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