# US-MAE016-008: Registrar figuras de transporte

## Metadata
| Campo | Valor |
|-------|-------|
| **ID** | US-MAE016-008 |
| **Epica** | EPIC-MAE-016 - Carta Porte CFDI |
| **Modulo** | carta-porte |
| **Prioridad** | P1 |
| **Story Points** | 5 |
| **Sprint** | Por asignar |
| **Estado** | Backlog |

## Historia de Usuario
**Como** coordinador de operaciones,
**quiero** registrar las figuras de transporte (operador, propietario, arrendador) en la carta porte con sus datos fiscales y licencia,
**para** cumplir con el nodo FiguraTransporte del complemento Carta Porte 3.1 que identifica a las personas involucradas en el traslado de mercancias.

## Descripcion Detallada
El nodo FiguraTransporte del complemento Carta Porte 3.1 es obligatorio e identifica a las personas fisicas o morales que participan en el transporte. El SAT define tres tipos de figura: Operador (tipo '01'), que es el conductor del vehiculo y requiere numero de licencia; Propietario (tipo '02'), que es el dueno del vehiculo o remolque; y Arrendador (tipo '03'), cuando la unidad esta arrendada.

Al generar la carta porte desde el viaje, el sistema carga automaticamente el operador asignado como figura tipo '01' con su RFC, nombre completo y numero de licencia de conducir. El coordinador puede agregar figuras adicionales (propietario del vehiculo, arrendador) cuando la operacion lo requiere, por ejemplo, cuando la unidad tractora es arrendada o pertenece a un tercero.

Para cada figura se registra: tipo_figura (01, 02 o 03), rfc_figura, nombre_figura, y para operadores el num_licencia. El domicilio fiscal (pais, estado, codigo_postal, calle) es opcional. Para propietarios y arrendadores se pueden registrar partes de transporte (JSONB) indicando los vehiculos o remolques de su propiedad utilizados en el viaje.

## Criterios de Aceptacion
### Escenario 1: Carga automatica del operador asignado al viaje
**Dado** una carta porte en estado BORRADOR generada desde un viaje con operador asignado que tiene RFC = 'GAMA800101ABC', nombre = 'Garcia Martinez Juan' y licencia = 'JGAM800101HDFRGT09'
**Cuando** se genera la carta porte
**Entonces** el sistema crea automaticamente un registro en `compliance.figuras_transporte` con tipo_figura = '01', rfc_figura = 'GAMA800101ABC', nombre_figura = 'Garcia Martinez Juan', num_licencia = 'JGAM800101HDFRGT09'.

### Escenario 2: Agregar propietario del vehiculo
**Dado** una carta porte en estado BORRADOR donde la unidad tractora pertenece a una persona moral diferente del emisor
**Cuando** el coordinador agrega una figura con tipo_figura = '02' (Propietario), rfc_figura = 'TME860101XYZ', nombre_figura = 'Transportes Mexico SA de CV'
**Entonces** el sistema crea el registro en `compliance.figuras_transporte` con los datos del propietario y partes_transporte indicando los vehiculos de su propiedad usados en el viaje.

### Escenario 3: Operador sin numero de licencia
**Dado** una carta porte en estado BORRADOR
**Cuando** el coordinador intenta agregar una figura tipo '01' (Operador) sin num_licencia
**Entonces** el sistema rechaza el registro con el mensaje "El numero de licencia es obligatorio para figuras de transporte tipo Operador (01)".

### Escenario 4: Eliminar figura de transporte
**Dado** una carta porte en estado BORRADOR con un propietario registrado como figura tipo '02'
**Cuando** el coordinador elimina la figura de propietario porque la unidad es propia del emisor
**Entonces** el sistema elimina el registro de `compliance.figuras_transporte` y actualiza la vista de figuras de transporte.

## Tareas Tecnicas
- **Database:** Insertar, actualizar y eliminar registros en `compliance.figuras_transporte`; usar indice `idx_figura_carta` para consultas por carta_porte_id; el campo partes_transporte (JSONB) almacena array de objetos con clave parte_transporte
- **Backend:** Crear endpoint POST `/api/v1/carta-porte/:id/figuras` para agregar figura; crear endpoint PUT `/api/v1/carta-porte/:id/figuras/:figuraId` para editar; crear endpoint DELETE `/api/v1/carta-porte/:id/figuras/:figuraId` para eliminar; crear `CreateFiguraTransporteDto` con validacion condicional (num_licencia obligatorio para tipo '01'); crear servicio `FiguraTransporteService` con logica de carga automatica desde viaje
- **Frontend:** Crear componente `FigurasTransportePanel` que muestra lista de figuras con tipo, RFC, nombre, licencia; boton "Agregar Figura" que abre dialogo con selector de tipo_figura (01 Operador, 02 Propietario, 03 Arrendador); campos condicionales segun tipo seleccionado; indicador visual del operador principal (auto-cargado); opcion de editar y eliminar figuras adicionales
- **Tests:** Test unitario de carga automatica del operador desde viaje; test de validacion de num_licencia para tipo '01'; test de creacion de propietario con partes_transporte; test de eliminacion de figura; test de integracion del endpoint

## Dependencias
- **Depende de:** US-MAE016-001 (Generar carta porte - debe existir un registro en BORRADOR), MAI-011 (Flota - datos del operador con RFC y licencia)
- **Bloquea:** US-MAE016-002 (Validar datos - al menos un operador es obligatorio para la validacion)

## Notas Tecnicas
- Los tipos de figura del catalogo SAT son: '01' (Operador), '02' (Propietario), '03' (Arrendador). Estos valores se validan contra el catalogo oficial c_FiguraTransporte.
- El campo num_licencia para operadores corresponde a la licencia federal de conducir emitida por la SCT. El formato varia segun el tipo de licencia.
- El campo rfc_figura acepta RFC de persona fisica (13 caracteres) o moral (12 caracteres).
- El campo partes_transporte (JSONB) para propietario/arrendador contiene un array con la estructura: `[{"parte_transporte": "PT01"}, {"parte_transporte": "PT02"}]`, donde cada parte identifica un vehiculo o remolque.
- El domicilio de la figura es opcional en el complemento Carta Porte 3.1 para autotransporte domestico, pero puede ser obligatorio para transporte internacional.
- En la mayoria de operaciones de autotransporte federal, solo se requiere la figura de operador (tipo '01'). Las figuras de propietario y arrendador se usan cuando la unidad no pertenece al emisor del CFDI.