# 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).