rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ec43d9c6cd
erp-transportistas-v2/docs/02-definicion-modulos/MAE-016-carta-porte/historias-usuario/US-MAE016-006-consultar-expediente-fiscal.md
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.0 KiB
Raw Blame History

US-MAE016-006: Consultar expediente fiscal

Metadata

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

Historia de Usuario

Como contador, quiero consultar el expediente fiscal completo de un viaje que incluya todas las cartas porte asociadas con su UUID, XML, PDF y estado, para tener trazabilidad fiscal de cada operacion de transporte y facilitar auditorias internas o requerimientos de la autoridad fiscal.

Descripcion Detallada

Cada viaje de transporte genera uno o mas CFDI con complemento Carta Porte durante su ciclo de vida. Un viaje puede tener multiples cartas porte cuando se cancela un CFDI y se emite uno de sustitucion. El expediente fiscal concentra todos estos documentos en una sola vista, permitiendo al contador verificar el estado fiscal del viaje de forma rapida.

El expediente fiscal muestra para cada carta porte asociada al viaje: UUID del CFDI, tipo (Ingreso o Traslado), estado (BORRADOR, VALIDADA, TIMBRADA, CANCELADA), serie y folio, fecha de timbrado, subtotal y total, enlaces para descargar XML y PDF, y datos de cancelacion (fecha, motivo, UUID de sustitucion) cuando aplica. Si existe un CFDI cancelado con motivo 01, el expediente muestra la relacion con el CFDI de sustitucion.

Esta funcionalidad es critica para cumplir con las obligaciones de conservacion de documentos fiscales digitales y para responder a requerimientos del SAT durante auditorias.

Criterios de Aceptacion

Escenario 1: Expediente con un CFDI timbrado vigente

Dado un viaje que tiene una sola carta porte en estado TIMBRADA Cuando el contador consulta el expediente fiscal del viaje Entonces el sistema muestra una lista con un registro que incluye: UUID del CFDI, tipo_cfdi, estado "TIMBRADA", serie, folio, fecha_timbrado, subtotal, total, y enlaces para descargar PDF y XML.

Escenario 2: Expediente con CFDI cancelado y sustitucion

Dado un viaje que tiene una carta porte CANCELADA con motivo 01 y una carta porte TIMBRADA de sustitucion Cuando el contador consulta el expediente fiscal Entonces el sistema muestra ambos registros ordenados por fecha de creacion, el CFDI cancelado muestra el motivo de cancelacion y el UUID de sustitucion vinculado al CFDI vigente, y el CFDI vigente se resalta visualmente como el documento activo.

Escenario 3: Viaje sin carta porte

Dado un viaje que no tiene ninguna carta porte generada Cuando el contador consulta el expediente fiscal Entonces el sistema muestra un mensaje "No se han generado cartas porte para este viaje" con un boton para generar la primera carta porte.

Escenario 4: Filtro por estado en listado general

Dado el listado general de cartas porte del tenant Cuando el contador filtra por estado CANCELADA y rango de fechas del mes actual Entonces el sistema muestra solo las cartas porte canceladas en el periodo, con totales de documentos cancelados y montos acumulados.

Tareas Tecnicas

  • Database: Consultar compliance.cartas_porte filtrado por viaje_id; incluir joins con tablas relacionadas para mostrar detalle resumido de ubicaciones y mercancias
  • Backend: Crear endpoint GET /api/v1/carta-porte/expediente/:viajeId que retorna todas las cartas porte del viaje con datos completos; crear ExpedienteFiscalResponseDto con array de cartas porte y metadatos del viaje; soportar filtros en listado general GET /api/v1/carta-porte con query params: estado, tipo_cfdi, fecha_desde, fecha_hasta, rfc_receptor
  • Frontend: Crear componente ExpedienteFiscalPanel que se integra en la vista de detalle del viaje; mostrar timeline de documentos fiscales con estado visual (verde = timbrada, rojo = cancelada, amarillo = borrador); enlaces de descarga rapida de PDF y XML; badge de relacion cancelacion-sustitucion para motivo 01
  • Tests: Test de endpoint expediente con viaje sin cartas porte; test con viaje con una carta porte timbrada; test con viaje con cancelacion y sustitucion; test de filtros del listado general

Dependencias

  • Depende de: US-MAE016-003 (Timbrar CFDI - los datos del expediente incluyen CFDI timbrados)
  • Bloquea: MAE-018 (Reportes y KPIs - los reportes fiscales se basan en datos del expediente)

Notas Tecnicas

  • La consulta del expediente usa el indice idx_carta_porte_viaje sobre compliance.cartas_porte(viaje_id) para rendimiento optimo.
  • El listado general usa los indices idx_carta_porte_tenant y idx_carta_porte_estado para filtros eficientes.
  • RLS por tenant_id garantiza que cada tenant solo vea sus propios documentos fiscales.
  • La relacion entre CFDI cancelado (motivo 01) y CFDI de sustitucion se establece a traves del campo uuid_sustitucion que almacena el UUID del nuevo CFDI.
  • El expediente no muestra el contenido XML completo, solo metadatos y enlaces de descarga para mantener la respuesta liviana.
  • Se debe considerar paginacion para viajes con multiples cancelaciones/reemisiones (caso excepcional pero posible).