# US-MAE016-001: Generar carta porte desde viaje

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

## Historia de Usuario
**Como** facturador,
**quiero** generar una carta porte a partir de un viaje despachado,
**para** cumplir con la obligacion fiscal del SAT de documentar el transporte de mercancias con el complemento Carta Porte 3.1.

## Descripcion Detallada
El complemento Carta Porte version 3.1 es obligatorio para toda empresa que transporte bienes y mercancias en territorio nacional por autotransporte federal. La generacion manual de este documento es propensa a errores y consume tiempo significativo, ya que requiere capturar datos de emisor, receptor, ubicaciones (origen/destino), mercancias, operador, unidad vehicular y remolques.

Esta historia cubre la automatizacion de la generacion del complemento. Al seleccionar un viaje despachado, el sistema extrae automaticamente todos los datos necesarios: datos fiscales del emisor (del tenant), datos del receptor/cliente, ubicaciones de la ruta del viaje, mercancias de las OTs asociadas, operador asignado y datos del vehiculo (permiso SCT, configuracion vehicular, placas). El facturador selecciona si es un CFDI de Ingreso (servicio de transporte) o CFDI de Traslado (mercancias propias).

El registro se crea en la tabla `compliance.cartas_porte` con estado BORRADOR, version_carta_porte '3.1' y todos los datos precargados. Automaticamente se generan los registros relacionados en `compliance.ubicaciones_carta_porte`, `compliance.mercancias_carta_porte`, `compliance.figuras_transporte` y `compliance.autotransporte_carta_porte`. El facturador puede revisar y ajustar los datos antes de proceder a la validacion.

## Criterios de Aceptacion
### Escenario 1: Generacion exitosa de carta porte tipo Ingreso
**Dado** un viaje con estado DESPACHADO o EN_TRANSITO que tiene datos completos (ubicaciones, mercancias, operador, unidad)
**Cuando** el facturador selecciona el viaje y elige tipo CFDI "Ingreso"
**Entonces** el sistema crea un registro en `compliance.cartas_porte` con tipo_cfdi = 'INGRESO', version_carta_porte = '3.1', estado = 'BORRADOR', datos del emisor (RFC, nombre, regimen fiscal del tenant), datos del receptor (RFC, nombre, uso CFDI, domicilio fiscal CP del cliente), y crea registros relacionados de ubicaciones, mercancias, figuras y autotransporte.

### Escenario 2: Generacion exitosa de carta porte tipo Traslado
**Dado** un viaje con estado DESPACHADO que transporta mercancias propias del contribuyente
**Cuando** el facturador selecciona el viaje y elige tipo CFDI "Traslado"
**Entonces** el sistema crea un registro con tipo_cfdi = 'TRASLADO', subtotal = 0, total = 0, receptor_rfc igual al emisor_rfc y estado = 'BORRADOR'.

### Escenario 3: Viaje sin datos suficientes
**Dado** un viaje con estado DESPACHADO pero sin mercancias registradas en sus OTs
**Cuando** el facturador intenta generar la carta porte
**Entonces** el sistema crea el registro en BORRADOR con los datos disponibles y muestra una advertencia indicando que faltan mercancias por registrar antes de proceder a la validacion.

### Escenario 4: Viaje en estado invalido
**Dado** un viaje con estado BORRADOR o PLANEADO (no despachado)
**Cuando** el facturador intenta generar una carta porte
**Entonces** el sistema rechaza la operacion con el mensaje "Solo se puede generar carta porte para viajes despachados o posteriores".

## Tareas Tecnicas
- **Database:** Utilizar tablas existentes del DDL `08-compliance-schema-ddl.sql`: `compliance.cartas_porte`, `compliance.ubicaciones_carta_porte`, `compliance.mercancias_carta_porte`, `compliance.figuras_transporte`, `compliance.autotransporte_carta_porte`
- **Backend:** Crear `CartaPorteService.generarDesdeViaje(viajeId, tipoCfdi)` que extraiga datos del viaje y sus relaciones; crear `CartaPorteController` con endpoint POST `/api/v1/carta-porte`; crear DTOs `CreateCartaPorteDto` y `CartaPorteResponseDto`
- **Frontend:** Crear componente `GenerarCartaPorteDialog` con selector de viaje y tipo CFDI; crear vista `CartaPorteListPage` con listado y filtros por estado/fecha/tipo; boton "Generar Carta Porte" en la vista de detalle del viaje
- **Tests:** Test unitario del servicio de extraccion de datos del viaje; test de integracion del endpoint POST; test de validacion de estado del viaje; test E2E del flujo completo de generacion

## Dependencias
- **Depende de:** MAI-005 (Despacho - viaje despachado), MAI-003 (OT - datos de mercancias y ubicaciones), MAI-011 (Flota - datos de unidad, remolques, operador)
- **Bloquea:** US-MAE016-002 (Validar datos), US-MAE016-007 (Agregar mercancias), US-MAE016-008 (Registrar figuras), US-MAE016-009 (Configurar autotransporte)

## Notas Tecnicas
- El campo `viaje_id` en `compliance.cartas_porte` es NOT NULL y referencia al viaje fuente.
- Los datos del emisor se obtienen de la configuracion fiscal del tenant (tabla de configuracion).
- Los datos del receptor se obtienen del cliente asociado a la OT del viaje.
- La version_carta_porte se establece como '3.1' por defecto (vigente desde 17-jul-2024).
- Las ubicaciones se mapean desde las paradas de la ruta del viaje, asignando secuencia numerica ordenada.
- El campo peso_bruto_total se calcula como la suma de peso_en_kg de todas las mercancias.
- El campo num_total_mercancias se calcula como el conteo de registros de mercancias.
- RLS por tenant_id garantiza aislamiento multi-tenant en todas las tablas del schema compliance.