erp-transportistas-v2/docs/02-definicion-modulos/MAE-016-carta-porte/historias-usuario/US-MAE016-007-agregar-mercancias-transportadas.md

US-MAE016-007: Agregar mercancias transportadas

Metadata

Campo	Valor
ID	US-MAE016-007
Epica	EPIC-MAE-016 - Carta Porte CFDI
Modulo	carta-porte
Prioridad	P0
Story Points	5
Sprint	Por asignar
Estado	Backlog

Historia de Usuario

Como facturador, quiero agregar y editar las mercancias transportadas en la carta porte con sus claves SAT, pesos, cantidades y datos de material peligroso, para cumplir con el nodo Mercancias del complemento Carta Porte 3.1 que exige el SAT para documentar los bienes que se transportan.

Descripcion Detallada

El nodo Mercancias del complemento Carta Porte 3.1 es uno de los elementos mas criticos del documento. Cada mercancia debe identificarse con la clave del catalogo de bienes transportados del SAT (campo BienesTransp), la clave de unidad de medida (ClaveUnidad), descripcion, cantidad y peso en kilogramos. Errores en estos campos son la causa mas frecuente de rechazo de timbrado.

Al generar la carta porte desde el viaje (US-MAE016-001), el sistema precarga las mercancias desde las OTs asociadas. Sin embargo, el facturador puede necesitar ajustar los datos para cumplir con los catalogos SAT: asignar la clave BienesTransp correcta, ajustar la ClaveUnidad, especificar si es material peligroso y, en ese caso, completar la clave de material peligroso (CveMaterialPeligroso), tipo de embalaje y descripcion del embalaje.

Para transporte internacional, las mercancias pueden incluir fraccion arancelaria, UUID de comercio exterior y numeros de pedimento. Para servicios de paqueteria, se soportan numeros de guia. El sistema calcula automaticamente el peso_bruto_total y num_total_mercancias a partir de los registros individuales.

Criterios de Aceptacion

Escenario 1: Agregar mercancia con campos obligatorios

Dado una carta porte en estado BORRADOR Cuando el facturador agrega una mercancia con bienes_transp = '31181701' (fertilizantes), descripcion = 'Fertilizante liquido NPK', cantidad = 25000, clave_unidad = 'KGM', peso_en_kg = 25000 y secuencia = 1 Entonces el sistema crea un registro en compliance.mercancias_carta_porte con los datos proporcionados y actualiza peso_bruto_total = 25000 y num_total_mercancias = 1 en la carta porte.

Escenario 2: Agregar mercancia con material peligroso

Dado una carta porte en estado BORRADOR Cuando el facturador agrega una mercancia con material_peligroso = true, cve_material_peligroso = '1005' (amoniaco anhidro), tipo_embalaje = '4G' (caja de carton) y descripcion_embalaje = 'Contenedor presurizado' Entonces el sistema crea el registro con los campos de material peligroso completos y marca la carta porte para que la validacion (US-MAE016-002) exija seguro de medio ambiente.

Escenario 3: Editar mercancia precargada desde OT

Dado una carta porte en estado BORRADOR con mercancias precargadas automaticamente desde las OTs del viaje, donde una mercancia no tiene la clave bienes_transp Cuando el facturador edita la mercancia y asigna bienes_transp = '50201700' (productos quimicos) Entonces el sistema actualiza el registro en compliance.mercancias_carta_porte con la clave SAT asignada.

Escenario 4: Calculo automatico de totales

Dado una carta porte con 3 mercancias con peso_en_kg de 5000, 3000 y 2000 respectivamente Cuando el facturador guarda las mercancias Entonces el sistema calcula y actualiza peso_bruto_total = 10000 (KGM) y num_total_mercancias = 3 en la tabla compliance.cartas_porte.

Tareas Tecnicas

• Database: Insertar, actualizar y eliminar registros en compliance.mercancias_carta_porte; actualizar campos peso_bruto_total y num_total_mercancias en compliance.cartas_porte; usar indice idx_mercancia_carta para consultas por carta_porte_id
• Backend: Crear endpoint POST /api/v1/carta-porte/:id/mercancias para agregar mercancia; crear endpoint PUT /api/v1/carta-porte/:id/mercancias/:mercanciaId para editar; crear endpoint DELETE /api/v1/carta-porte/:id/mercancias/:mercanciaId para eliminar; crear CreateMercanciaDto y UpdateMercanciaDto con validaciones de campos obligatorios; crear servicio MercanciaCartaPorteService con logica de calculo de totales; implementar busqueda en catalogo SAT de BienesTransp y ClaveUnidad
• Frontend: Crear componente MercanciasCartaPorteTable con tabla editable que muestre bienes_transp, descripcion, cantidad, clave_unidad, peso_en_kg, material_peligroso; crear dialogo AgregarMercanciaDialog con buscador de claves SAT (autocomplete con catalogo BienesTransp); seccion colapsable para datos de material peligroso (visible solo si material_peligroso = true); seccion colapsable para datos de comercio exterior; indicador visual de peso_bruto_total y num_total_mercancias
• Tests: Test unitario del calculo de peso_bruto_total y num_total_mercancias; test de creacion de mercancia con campos obligatorios; test de creacion con material peligroso; test de edicion de mercancia; test de eliminacion con recalculo de totales; test de validacion de clave bienes_transp contra catalogo SAT

Dependencias

• Depende de: US-MAE016-001 (Generar carta porte - debe existir un registro en BORRADOR)
• Bloquea: US-MAE016-002 (Validar datos - las mercancias son parte de la validacion obligatoria)

Notas Tecnicas

• El catalogo BienesTransp del SAT contiene mas de 50,000 claves. Se recomienda implementar busqueda con autocomplete y carga paginada del catalogo.
• El catalogo ClaveUnidad del SAT contiene claves como KGM (kilogramo), LTR (litro), H87 (pieza), TNE (tonelada), MTR (metro).
• El campo bienes_transp (VARCHAR(10)) almacena la clave de 8 digitos del catalogo SAT.
• El campo cve_material_peligroso (VARCHAR(10)) referencia al catalogo de materiales peligrosos de la ONU.
• El campo tipo_embalaje (VARCHAR(10)) referencia al catalogo de tipos de embalaje de la ONU.
• El campo pedimentos (TEXT[]) almacena numeros de pedimento para comercio exterior en formato: "AA AANNNNNN NNNNNNN N" (21 posiciones).
• El campo guias (TEXT[]) almacena numeros de guia para servicios de paqueteria.
• El campo secuencia (INT NOT NULL) establece el orden de las mercancias en el XML del complemento.
• La suma de peso_en_kg debe coincidir con peso_bruto_total; la unidad de peso por defecto es 'KGM'.