erp-transportistas-v2/docs/02-definicion-modulos/MAE-016-carta-porte/historias-usuario/US-MAE016-002-validar-datos-obligatorios-sat.md

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.