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