Adrian Flores Cortes ec43d9c6cd docs: Add Phase 3 secondary modules specifications (P1/P2/P3)

Modules documented:
- MAI-003 (OT): README, REQUERIMIENTOS, RESUMEN-EPICA, 10 US
- MAI-006 (Tracking): README, REQUERIMIENTOS, RESUMEN-EPICA
- MAI-008 (Incidencias): 3 US (18 SP)
- MAI-011 (Flota): README, REQUERIMIENTOS, RESUMEN-EPICA
- MAI-012 (Combustible): 3 US (18 SP)
- MAI-013 (Mantenimiento): 3 US (18 SP)
- MAI-014 (Carriers): 3 US (18 SP)
- MAI-015 (Portal): 3 US (18 SP)
- MAE-016 (Carta Porte): 10 US
- MAE-017 (HOS): 3 US (16 SP)
- MAE-018 (Reportes): 3 US (18 SP)

Phase 2+3 complete: 13 modules, 50+ User Stories

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-27 02:24:35 -06:00

5.1 KiB

Raw Blame History

US-MAE016-004: Descargar PDF de carta porte

Metadata

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

Historia de Usuario

Como operador de transporte, quiero descargar el PDF y XML de la carta porte timbrada para portarlo en mi dispositivo movil, para cumplir con la obligacion de presentar el documento durante el traslado ante cualquier inspeccion de la autoridad fiscal en carretera.

Descripcion Detallada

La normativa del SAT establece que durante el traslado de mercancias en territorio nacional, el transportista debe portar el CFDI con complemento Carta Porte. La autoridad fiscal puede solicitar la exhibicion de este documento en cualquier punto de la ruta (casetas, retenes, puntos de verificacion). La falta del documento puede resultar en multas y decomiso de la mercancia.

El sistema debe generar la representacion impresa (PDF) del CFDI timbrado conforme a las especificaciones del Anexo 20 del SAT. El PDF incluye los datos fiscales del emisor y receptor, detalle de mercancias transportadas (descripcion, cantidad, peso, clave SAT), ubicaciones de origen y destino con codigos postales, figuras de transporte (operador, propietario), datos del autotransporte federal (permiso SCT, vehiculo, remolques), datos de seguros y el codigo QR de verificacion del SAT.

Adicionalmente, el operador debe poder descargar tanto el PDF como el XML desde la app movil para consulta en modo offline. Los archivos se almacenan localmente en el dispositivo y permanecen accesibles sin conexion a internet durante todo el viaje.

Criterios de Aceptacion

Escenario 1: Descarga de PDF desde la aplicacion web

Dado una carta porte en estado TIMBRADA con uuid_cfdi y xml_cfdi almacenados Cuando el facturador solicita la descarga del PDF Entonces el sistema genera un PDF con todos los datos del CFDI y complemento Carta Porte (emisor, receptor, mercancias, ubicaciones, figuras, autotransporte, seguros, QR), lo almacena en el campo pdf_url y lo descarga al navegador del usuario.

Escenario 2: Descarga de XML desde la aplicacion web

Dado una carta porte en estado TIMBRADA con xml_cfdi almacenado Cuando el facturador solicita la descarga del XML Entonces el sistema retorna el contenido del campo xml_cfdi como archivo .xml descargable con nombre formato "{serie}-{folio}-{uuid_cfdi}.xml".

Escenario 3: Descarga offline desde app movil

Dado un operador con la app movil que tiene un viaje activo con carta porte timbrada Cuando el operador descarga el PDF y XML mientras tiene conexion a internet Entonces los archivos se almacenan localmente en el dispositivo y permanecen accesibles en la seccion "Documentos del Viaje" incluso sin conexion a internet.

Escenario 4: Carta porte no timbrada

Dado una carta porte en estado BORRADOR o VALIDADA (no timbrada) Cuando un usuario intenta descargar el PDF o XML Entonces el sistema muestra el mensaje "El PDF y XML solo estan disponibles para cartas porte timbradas" y no permite la descarga.

Tareas Tecnicas

Database: Leer campos xml_cfdi, pdf_url y qr_url de compliance.cartas_porte; actualizar pdf_url y qr_url despues de generar el PDF
Backend: Crear CartaPortePdfService para generar PDF con libreria de generacion (PDFKit o Puppeteer); crear endpoint GET /api/v1/carta-porte/:id/pdf que retorna el PDF como stream; crear endpoint GET /api/v1/carta-porte/:id/xml que retorna el XML como archivo; generar codigo QR con URL de verificacion del SAT
Frontend: Agregar botones "Descargar PDF" y "Descargar XML" en la vista de detalle de carta porte timbrada; en app movil: implementar descarga y almacenamiento local con acceso offline; mostrar visor de PDF integrado con opcion de compartir
Tests: Test unitario de generacion de PDF con datos de prueba; test de descarga de XML con contenido correcto; test de endpoint PDF con respuesta tipo application/pdf; test de QR con URL valida de verificacion SAT

Dependencias

Depende de: US-MAE016-003 (Timbrar CFDI - requiere estado TIMBRADA con xml_cfdi)
Bloquea: MAI-015 (Portal Cliente - descarga de carta porte por el cliente)

Notas Tecnicas

El PDF sigue el formato de representacion impresa del Anexo 20 del SAT.
El codigo QR contiene la URL de verificacion del SAT: https://verificacfdi.facturaelectronica.sat.gob.mx/default.aspx?id={uuid}&re={rfc_emisor}&rr={rfc_receptor}&tt={total}&fe={ultimos8SelloDigital}.
El nombre del archivo PDF sigue el formato: CP-{serie}{folio}-{uuid_cfdi}.pdf.
El nombre del archivo XML sigue el formato: {serie}-{folio}-{uuid_cfdi}.xml.
Para la app movil, los archivos descargados se almacenan en el almacenamiento local del dispositivo con un indice por viaje_id.
Se debe considerar el tamano del PDF (estimado 200-500 KB) para la descarga movil en condiciones de conectividad limitada.
El qr_url almacena la URL de la imagen QR generada, que se incluye en el PDF y puede mostrarse independientemente.

5.1 KiB Raw Blame History