erp-transportistas-v2/docs/02-definicion-modulos/MAE-016-carta-porte/historias-usuario/US-MAE016-008-registrar-figuras-transporte.md

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.