# US-MAE016-002: Validar datos obligatorios SAT

## Metadata
| Campo | Valor |
|-------|-------|
| **ID** | US-MAE016-002 |
| **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** validar que todos los campos obligatorios del complemento Carta Porte 3.1 esten completos y correctos antes de enviar al PAC,
**para** evitar rechazos de timbrado y garantizar el cumplimiento con la estructura XML requerida por el SAT.

## Descripcion Detallada
El complemento Carta Porte 3.1 tiene reglas estrictas sobre campos obligatorios que varian segun el tipo de CFDI (Ingreso vs Traslado), el tipo de transporte y la naturaleza de las mercancias. Un error en cualquier campo obligatorio resulta en rechazo del timbrado por parte del PAC, lo que genera retrasos operativos y posibles multas si el viaje se realiza sin el documento.

La validacion debe ejecutarse de forma exhaustiva antes de permitir el timbrado. Cada regla de validacion verifica un campo o grupo de campos especifico contra los catalogos del SAT (BienesTransp, ClaveUnidad, ConfigVehicular, TipoPermiso SCT, TipoFigura). Cuando la validacion detecta errores, retorna una lista detallada indicando el campo, la tabla afectada y la descripcion del error para que el facturador pueda corregirlos.

Si todos los campos obligatorios son validos, la carta porte cambia de estado BORRADOR a VALIDADA, habilitando el boton de timbrado. Esto asegura que solo se envien al PAC documentos con alta probabilidad de timbrado exitoso, reduciendo cancelaciones y retrabajos.

## Criterios de Aceptacion
### Escenario 1: Validacion exitosa con todos los campos completos
**Dado** una carta porte en estado BORRADOR con datos de emisor, receptor, al menos una ubicacion de origen y una de destino, al menos una mercancia con bienes_transp y peso_en_kg, una figura de transporte tipo operador con num_licencia, datos de autotransporte con perm_sct y placa_vm, y seguro de responsabilidad civil
**Cuando** el facturador ejecuta la validacion
**Entonces** el sistema confirma que todos los campos son validos, actualiza el estado a VALIDADA y habilita la opcion de timbrado.

### Escenario 2: Validacion fallida por mercancias incompletas
**Dado** una carta porte en estado BORRADOR donde una mercancia no tiene el campo bienes_transp (clave SAT)
**Cuando** el facturador ejecuta la validacion
**Entonces** el sistema retorna un error con campo = "bienes_transp", tabla = "compliance.mercancias_carta_porte", descripcion = "Clave de bienes transportados (catalogo SAT) es obligatoria para cada mercancia" y no cambia el estado.

### Escenario 3: Validacion fallida por ausencia de ubicaciones
**Dado** una carta porte en estado BORRADOR sin registros en `compliance.ubicaciones_carta_porte`
**Cuando** el facturador ejecuta la validacion
**Entonces** el sistema retorna errores indicando que se requiere al menos una ubicacion de tipo 'Origen' y al menos una de tipo 'Destino', ambas con codigo_postal valido de 5 digitos.

### Escenario 4: Validacion fallida por material peligroso sin seguro ambiental
**Dado** una carta porte donde alguna mercancia tiene material_peligroso = true pero no se han registrado asegura_med_ambiente ni poliza_med_ambiente
**Cuando** el facturador ejecuta la validacion
**Entonces** el sistema retorna un error indicando que el seguro de medio ambiente es obligatorio cuando se transportan materiales peligrosos.

## Tareas Tecnicas
- **Database:** Consultar tablas `compliance.cartas_porte`, `compliance.ubicaciones_carta_porte`, `compliance.mercancias_carta_porte`, `compliance.figuras_transporte`, `compliance.autotransporte_carta_porte` para obtener datos completos; actualizar campo `estado` a 'VALIDADA'
- **Backend:** Crear `CartaPorteValidationService` con metodo `validar(cartaPorteId)` que ejecuta todas las reglas y retorna array de errores; crear endpoint POST `/api/v1/carta-porte/:id/validar`; crear `ValidationErrorDto` con campos: campo, tabla, descripcion, severidad
- **Frontend:** Crear componente `ValidacionCartaPortePanel` que muestra lista de errores agrupados por seccion (emisor, receptor, ubicaciones, mercancias, figuras, autotransporte, seguros); boton "Validar" con indicador visual (verde = valida, rojo = errores); enlace directo al campo con error para edicion rapida
- **Tests:** Test unitario para cada regla de validacion individual; test de validacion completa con datos correctos; test de validacion con cada tipo de error; test de transicion de estado BORRADOR a VALIDADA

## Dependencias
- **Depende de:** US-MAE016-001 (Generar carta porte - debe existir un registro en BORRADOR)
- **Bloquea:** US-MAE016-003 (Timbrar CFDI - requiere estado VALIDADA)

## Notas Tecnicas
- Las claves de catalogo SAT (bienes_transp, clave_unidad, config_vehicular, perm_sct, tipo_figura) se validan contra tablas o archivos de catalogo locales para evitar llamadas externas.
- El codigo_postal de ubicaciones debe existir en el catalogo de codigos postales del SAT (5 digitos).
- Para CFDI de Ingreso se valida que receptor_rfc sea diferente del emisor_rfc.
- Para CFDI de Traslado se valida que subtotal y total sean 0 o nulos.
- El peso_bruto_total debe ser igual a la suma de peso_en_kg de las mercancias (tolerancia de 0.001 kg por redondeo).
- El num_total_mercancias debe coincidir con el conteo de registros en mercancias_carta_porte.
- La validacion es idempotente: puede ejecutarse multiples veces sin efectos secundarios hasta que sea exitosa.