erp-transportistas-v2/docs/02-definicion-modulos/MAE-016-carta-porte/historias-usuario/US-MAE016-001-generar-carta-porte-desde-viaje.md

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.