# EPICA: EPIC-RT-010 - Facturación CFDI

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-RT-010 |
| **Nombre** | Facturación CFDI |
| **Modulo** | facturacion |
| **Fase** | Fase 1 - MVP |
| **Prioridad** | P0 (Critico) |
| **Estado** | Backlog |
| **Story Points** | 35 |
| **Sprint(s)** | Sprint 6-7 |

---

## Descripcion

Generación de comprobantes fiscales digitales (CFDI 4.0) para ventas en tienda y online. Incluye facturación a público en general, facturación a cliente con RFC, notas de crédito, cancelaciones y portal de autofactura para clientes.

---

## Objetivo de Negocio

- Cumplimiento fiscal obligatorio
- Facturación inmediata en POS
- Autofactura para clientes
- Control de notas de crédito
- Reportes fiscales

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-RT010-001 | Como cajero, quiero generar factura inmediata al cerrar venta si el cliente la solicita | P0 | 5 | Backlog |
| US-RT010-002 | Como cajero, quiero generar factura a público en general para ventas sin RFC | P0 | 3 | Backlog |
| US-RT010-003 | Como cliente, quiero autofacturar desde portal web usando mi ticket | P0 | 8 | Backlog |
| US-RT010-004 | Como contador, quiero generar nota de crédito por devolución | P0 | 5 | Backlog |
| US-RT010-005 | Como contador, quiero cancelar CFDI con motivo de cancelación | P0 | 3 | Backlog |
| US-RT010-006 | Como cliente, quiero recibir mi factura PDF y XML por email | P0 | 3 | Backlog |
| US-RT010-007 | Como contador, quiero ver reporte de CFDIs emitidos por período | P0 | 3 | Backlog |
| US-RT010-008 | Como admin, quiero configurar datos fiscales de la empresa | P0 | 2 | Backlog |
| US-RT010-009 | Como contador, quiero regenerar PDF de factura existente | P1 | 2 | Backlog |
| US-RT010-010 | Como admin, quiero validar RFC del cliente contra SAT (opcional) | P2 | 1 | Backlog |

**Total Story Points:** 35 SP

---

## CFDI 4.0 - Elementos Clave

```
┌─────────────────────────────────────────────────────────┐
│              ESTRUCTURA CFDI 4.0                        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  EMISOR                                                 │
│  ├── RFC de la empresa                                  │
│  ├── Nombre o razón social                              │
│  ├── Régimen fiscal                                     │
│  └── Código postal del domicilio fiscal                 │
│                                                         │
│  RECEPTOR                                               │
│  ├── RFC del cliente (o XAXX010101000 para público)     │
│  ├── Nombre o razón social                              │
│  ├── Régimen fiscal                                     │
│  ├── Código postal del domicilio fiscal                 │
│  └── Uso del CFDI (G03 - Gastos en general)             │
│                                                         │
│  CONCEPTOS                                              │
│  ├── Clave de producto/servicio SAT                     │
│  ├── Descripción                                        │
│  ├── Cantidad y unidad                                  │
│  ├── Valor unitario                                     │
│  ├── Importe                                            │
│  └── Impuestos (IVA, IEPS si aplica)                    │
│                                                         │
│  COMPLEMENTOS                                           │
│  └── Pago (si es PPD - Pago en Parcialidades)           │
│                                                         │
│  TIMBRE FISCAL DIGITAL (TFD)                            │
│  ├── UUID (folio fiscal)                                │
│  ├── Fecha de timbrado                                  │
│  ├── Sello del SAT                                      │
│  └── Sello del emisor                                   │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## Flujo de Facturación

```
FACTURACIÓN INMEDIATA (POS)

┌─────────────┐
│   VENTA     │  ← Cajero cierra venta
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ ¿FACTURA?   │ ─── No ──► Ticket simple
└──────┬──────┘
       │ Si
       ▼
┌─────────────┐
│ DATOS RFC   │  ← Captura RFC y datos fiscales
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  TIMBRADO   │  ← PAC genera UUID
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ PDF + XML   │  ← Envío por email
└─────────────┘


AUTOFACTURA (Portal)

┌─────────────┐
│   PORTAL    │  ← Cliente ingresa
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   TICKET    │  ← Ingresa folio del ticket
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ DATOS RFC   │  ← Ingresa sus datos fiscales
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  TIMBRADO   │  ← PAC genera UUID
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  DESCARGA   │  ← PDF + XML disponibles
└─────────────┘
```

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] Facturación inmediata en POS
- [ ] Factura a público en general
- [ ] Portal de autofactura
- [ ] Notas de crédito por devolución
- [ ] Cancelación de CFDIs
- [ ] Envío por email
- [ ] Reportes de CFDIs
- [ ] Configuración de datos fiscales

**No Funcionales:**
- [ ] Timbrado < 5 segundos
- [ ] Alta disponibilidad del PAC
- [ ] Almacenamiento de XMLs por 5 años

**Tecnicos:**
- [ ] Integración con PAC (Finkok, Facturama, etc.)
- [ ] Generación de XML CFDI 4.0
- [ ] Generación de PDF personalizado
- [ ] Validación de RFC vs lista negra SAT

---

## Dependencias

**Esta epica depende de:**
| Epica/Modulo | Estado | Bloqueante |
|--------------|--------|------------|
| EPIC-RT-001 Fundamentos | Backlog | Si |
| EPIC-RT-002 POS | Backlog | Si |

**Esta epica bloquea:**
| Epica/Modulo | Razon |
|--------------|-------|
| Reportes fiscales | Requiere CFDIs emitidos |

---

## Desglose Tecnico

**Database:**
- [ ] Schema: `invoicing`
- [ ] Tablas: 6 (invoices, invoice_items, cancellations, fiscal_data, xml_storage, pac_logs)
- [ ] Funciones: 2 (generate_xml, validate_rfc)
- [ ] Indices: Por UUID, fecha, RFC

**Backend:**
- [ ] Modulo: `invoicing`
- [ ] Entities: 4 (Invoice, InvoiceItem, Cancellation, FiscalData)
- [ ] Services: PACService, XMLGenerator, PDFGenerator
- [ ] Endpoints: 12
- [ ] Tests: 28

**Frontend:**
- [ ] Paginas: 4 (InvoiceList, InvoiceDetail, SelfService, Config)
- [ ] Componentes: 10 (InvoiceForm, RFCInput, PDFViewer, etc.)
- [ ] Portal público de autofactura
- [ ] Stores: 1 (invoicingStore)

---

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /api/invoices | Crear y timbrar factura |
| GET | /api/invoices/:id | Detalle de factura |
| GET | /api/invoices/:id/pdf | Descargar PDF |
| GET | /api/invoices/:id/xml | Descargar XML |
| POST | /api/invoices/:id/send | Enviar por email |
| POST | /api/invoices/:id/cancel | Cancelar factura |
| POST | /api/invoices/credit-note | Crear nota de crédito |
| GET | /api/invoices/report | Reporte de CFDIs |
| POST | /api/invoices/self-service | Autofactura (público) |
| POST | /api/invoices/validate-rfc | Validar RFC |

---

## PAC (Proveedor Autorizado de Certificación)

| PAC | Notas |
|-----|-------|
| Finkok | Popular, buena documentación |
| Facturama | API REST moderna |
| SW Sapien | Económico para alto volumen |
| Facturify | Fácil integración |

---

## Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Caída del PAC | Baja | Alto | PAC de respaldo |
| Cambios normativos | Media | Alto | Monitoreo de actualizaciones |
| XMLs corruptos | Baja | Alto | Validación antes de timbrar |

---

## Nota Técnica

La facturación electrónica en México (CFDI) es obligatoria y debe cumplir con los lineamientos del SAT. El sistema debe estar preparado para actualizaciones normativas frecuentes.

---

## Definition of Ready (DoR)

- [x] Historias de usuario definidas
- [x] Criterios de aceptacion claros
- [x] Dependencias identificadas
- [x] Estimacion completada
- [ ] PAC seleccionado y contratado
- [ ] Certificados de sello digital (CSD) disponibles
- [ ] Catálogo de productos con claves SAT

## Definition of Done (DoD)

- [ ] Facturación inmediata funcionando
- [ ] Portal de autofactura operativo
- [ ] Notas de crédito y cancelaciones
- [ ] Integración con PAC estable
- [ ] Tests de integración pasando
- [ ] Documentación de API

---

## Historial

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-08 | Creacion de epica | Claude-Agent |

---

**Creada por:** Claude-Agent
**Fecha:** 2025-12-08
**Ultima actualizacion:** 2025-12-08