erp-transportistas-v2/docs/02-definicion-modulos/MAE-016-carta-porte/historias-usuario/US-MAE016-009-configurar-datos-autotransporte.md

US-MAE016-009: Configurar datos autotransporte federal

Metadata

Campo	Valor
ID	US-MAE016-009
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 configurar los datos del autotransporte federal en la carta porte incluyendo permiso SCT, configuracion vehicular, placa del vehiculo, remolques y seguros, para cumplir con el nodo Autotransporte del complemento Carta Porte 3.1 que documenta el medio de transporte utilizado.

Descripcion Detallada

El nodo Autotransporte del complemento Carta Porte 3.1 es obligatorio para el transporte terrestre federal y contiene la informacion del vehiculo y sus permisos. Los datos principales son el tipo de permiso SCT (catalogo c_TipoPermiso del SAT), el numero de permiso, la configuracion vehicular (C2, C3, T3S2, T3S3, etc. del catalogo c_ConfigAutotransporte) y la placa del vehiculo motor. Cuando la unidad lleva remolques, se registran hasta 2 con su subtipo (catalogo c_SubTipoRem) y placa.

Al generar la carta porte desde el viaje, el sistema precarga automaticamente los datos de la unidad tractora y remolques asignados desde el modulo de gestion de flota (MAI-011): permiso SCT de la empresa, configuracion vehicular de la unidad, placa, anio modelo y datos de los remolques. El coordinador puede ajustar estos datos si es necesario.

Adicionalmente, esta historia cubre el registro de los seguros obligatorios: seguro de responsabilidad civil (obligatorio para todo autotransporte), seguro de medio ambiente (obligatorio si se transportan materiales peligrosos) y seguro de carga (opcional). Los datos del seguro incluyen nombre de la aseguradora, numero de poliza y prima.

Criterios de Aceptacion

Escenario 1: Carga automatica de datos del vehiculo desde flota

Dado una carta porte en estado BORRADOR generada desde un viaje con unidad tractora asignada (placa = 'ABC-123-A', config_vehicular = 'T3S2', permiso SCT tipo 'TPAF01', num_permiso = '123456') y un remolque (subtipo = 'CTR004', placa = 'REM-456-B') Cuando se genera la carta porte Entonces el sistema crea un registro en compliance.autotransporte_carta_porte con perm_sct = 'TPAF01', num_permiso_sct = '123456', config_vehicular = 'T3S2', placa_vm = 'ABC-123-A' y remolques = '[{"sub_tipo_rem": "CTR004", "placa": "REM-456-B"}]'.

Escenario 2: Registrar doble remolque

Dado una carta porte en estado BORRADOR para un full trailer (configuracion T3S2R4) Cuando el coordinador configura la unidad con 2 remolques: remolque 1 (sub_tipo_rem = 'CTR003', placa = 'REM-001-A') y remolque 2 (sub_tipo_rem = 'CTR004', placa = 'REM-002-B') Entonces el sistema almacena remolques = '[{"sub_tipo_rem": "CTR003", "placa": "REM-001-A"}, {"sub_tipo_rem": "CTR004", "placa": "REM-002-B"}]' en el campo JSONB.

Escenario 3: Registrar seguros obligatorios

Dado una carta porte en estado BORRADOR Cuando el coordinador registra asegura_resp_civil = 'Seguros Atlas SA de CV', poliza_resp_civil = 'POL-RC-2026-001', asegura_carga = 'GNP Seguros', poliza_carga = 'POL-CG-2026-456' y prima_seguro = 45000.00 Entonces el sistema actualiza los campos de seguros en compliance.cartas_porte con los datos proporcionados.

Escenario 4: Falta de datos obligatorios de autotransporte

Dado una carta porte en estado BORRADOR sin registro en compliance.autotransporte_carta_porte Cuando el facturador intenta validar la carta porte (US-MAE016-002) Entonces la validacion retorna errores indicando que perm_sct, num_permiso_sct, config_vehicular y placa_vm son campos obligatorios del nodo Autotransporte.

Tareas Tecnicas

• Database: Insertar y actualizar registros en compliance.autotransporte_carta_porte; actualizar campos de seguros (asegura_resp_civil, poliza_resp_civil, asegura_med_ambiente, poliza_med_ambiente, asegura_carga, poliza_carga, prima_seguro) en compliance.cartas_porte; usar indice idx_autotransporte_carta para consultas por carta_porte_id
• Backend: Crear endpoint POST /api/v1/carta-porte/:id/autotransporte para registrar datos del vehiculo; crear endpoint PUT /api/v1/carta-porte/:id/autotransporte/:autoId para editar; crear CreateAutotransporteDto con validaciones (perm_sct, num_permiso_sct, config_vehicular, placa_vm obligatorios); crear UpdateSegurosDto para actualizar datos de seguros; crear servicio AutotransporteCartaPorteService con logica de carga automatica desde flota; implementar busqueda en catalogos SAT de c_TipoPermiso, c_ConfigAutotransporte, c_SubTipoRem
• Frontend: Crear componente AutotransportePanel con formulario de datos del vehiculo: selector de tipo permiso SCT (autocomplete con catalogo SAT), campo num_permiso_sct, selector de config_vehicular (autocomplete), campo placa_vm, campo anio_modelo_vm; crear seccion de remolques con tabla editable (hasta 2 filas) con selector de sub_tipo_rem y campo placa; crear seccion de seguros con campos para responsabilidad civil (obligatorio), medio ambiente (condicional a material peligroso) y carga (opcional)
• Tests: Test unitario de carga automatica desde datos de flota; test de registro de autotransporte con 0, 1 y 2 remolques; test de validacion de campos obligatorios; test de registro de seguros; test de actualizacion de datos existentes; test de catalogo de configuraciones vehiculares

Dependencias

• Depende de: US-MAE016-001 (Generar carta porte - debe existir un registro en BORRADOR), MAI-011 (Flota - datos de unidad, remolques, permisos SCT)
• Bloquea: US-MAE016-002 (Validar datos - autotransporte es obligatorio para la validacion)

Notas Tecnicas

• El catalogo c_TipoPermiso del SAT incluye: TPAF01 (Autotransporte Federal de carga general), TPAF02 (Transporte privado de carga), TPAF03 (Autotransporte Federal de Carga Especializada), entre otros.
• El catalogo c_ConfigAutotransporte incluye configuraciones como: C2 (camion unitario 2 ejes), C3 (camion unitario 3 ejes), T3S2 (tractocamion 3 ejes - semiremolque 2 ejes), T3S3 (tractocamion 3 ejes - semiremolque 3 ejes), T3S2R4 (tractocamion con semiremolque y remolque).
• El catalogo c_SubTipoRem incluye subtipos como: CTR001 (semiremolque), CTR002 (semiremolque con eje de arrastre), CTR003 (remolque), CTR004 (semiremolque chasis portacontenedor).
• El campo remolques (JSONB) almacena hasta 2 remolques. La estructura es: [{"sub_tipo_rem": "string", "placa": "string"}].
• La placa del vehiculo motor (placa_vm) se valida con formato alfanumerico (hasta 15 caracteres, no se valida formato especifico por entidad federativa).
• Los datos del seguro de responsabilidad civil son obligatorios para autotransporte federal. Los datos del seguro de medio ambiente son obligatorios solo cuando alguna mercancia tiene material_peligroso = true.
• El anio_modelo_vm es opcional en el complemento pero util para validaciones internas del sistema (vehiculos con mas de cierta antiguedad pueden requerir revision adicional).