docs: Update DDL README with comprehensive schema documentation

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

ddl/README.md

@@ -1,8 +1,8 @@
 # Database DDL Files - erp-core
 
-**Version:** 1.0.0
-**Fecha:** 2026-01-24
-**Total Archivos:** 35
+**Version:** 1.1.0
+**Fecha:** 2026-02-03
+**Total Archivos:** 38
 **Total Schemas:** 20
 
 ---
@@ -17,7 +17,8 @@ Los archivos DDL siguen un esquema de numeracion por rangos segun dominio funcio
 | 10-15 | System | Audit, feature-flags, webhooks, storage, AI, WhatsApp |
 | 16-19 | Partners & Products | Partners, products, warehouses, attributes |
 | 20-24 | Catalogs & Operations | Core catalogs, inventory, sales, purchases, invoices |
-| 25-49 | Reserved | Expansiones futuras |
+| 25-29 | Fiscal & CFDI | Catalogos SAT, facturacion electronica CFDI |
+| 30-49 | Reserved | Expansiones futuras |
 | 50-59 | Financial | Contabilidad completa |
 | 60-69 | Projects | Proyectos y timesheets |
 
@@ -59,7 +60,7 @@ Los archivos DDL siguen un esquema de numeracion por rangos segun dominio funcio
 | 18 | `18-warehouses.sql` | inventory | Almacenes, zonas, ubicaciones |
 | 19 | `19-product-attributes.sql` | products | Atributos, variantes |
 
-### Catalogs & Operations (20-26)
+### Catalogs & Operations (20-24)
 
 | # | Archivo | Schema | Descripcion |
 |---|---------|--------|-------------|
@@ -68,7 +69,16 @@ Los archivos DDL siguen un esquema de numeracion por rangos segun dominio funcio
 | 22 | `22-sales.sql` | sales | Ordenes de venta, cotizaciones |
 | 23 | `23-purchases.sql` | purchases | Ordenes de compra |
 | 24 | `24-invoices.sql` | billing | Facturas operacionales, pagos |
-| 26 | `26-fiscal-catalogs.sql` | fiscal | Catalogos SAT (CFDI, regimenes) |
+
+### Fiscal & CFDI (25-29)
+
+| # | Archivo | Schema | Descripcion |
+|---|---------|--------|-------------|
+| 25 | `25-payment-terminals.sql` | billing | Terminales punto de venta |
+| 26 | `26-fiscal-catalogs.sql` | fiscal | Catalogos SAT (regimenes, usos CFDI, formas pago) |
+| 27 | `27-cfdi-core.sql` | fiscal | CFDI: certificados, facturas CFDI, conceptos |
+| 28 | `28-cfdi-operations.sql` | fiscal | CFDI: cancelaciones, logs, complementos pago |
+| 29 | `29-cfdi-rls-functions.sql` | fiscal | CFDI: RLS, funciones auxiliares, triggers, vistas |
 
 ### Financial (50-57)
 
@@ -107,7 +117,7 @@ Los archivos DDL siguen un esquema de numeracion por rangos segun dominio funcio
 | core | Catalogos compartidos | 03, 20 |
 | feature_flags | Feature toggles | 11 |
 | financial | Contabilidad | 50-57 |
-| fiscal | Catalogos SAT | 26 |
+| fiscal | Catalogos SAT y CFDI | 26, 27, 28, 29 |
 | inventory | Inventario y stock | 18, 21 |
 | mobile | App movil | 04 |
 | notifications | Notificaciones | 09 |
@@ -137,6 +147,8 @@ done
 1. `01-auth-profiles.sql` debe ejecutarse primero (define auth.users, auth.tenants)
 2. `50-financial-schema.sql` antes del resto de financial
 3. `20-core-catalogs.sql` antes de inventory/sales/purchases
+4. `24-invoices.sql` y `26-fiscal-catalogs.sql` antes de `27-cfdi-core.sql`
+5. `27-cfdi-core.sql` antes de `28-cfdi-operations.sql` y `29-cfdi-rls-functions.sql`
 
 ---
 
@@ -153,6 +165,58 @@ done
 
 ---
 
+## Notas de Sprint - Modulo CFDI (2026-02-03)
+
+### Archivos creados:
+1. **27-cfdi-core.sql**: Tablas core del modulo CFDI
+   - `cfdi_certificates`: Certificados CSD para timbrado
+   - `cfdi_pac_configurations`: Configuracion de PACs
+   - `cfdi_invoices`: Extension de facturas con datos CFDI 4.0
+   - `cfdi_invoice_items`: Conceptos con claves SAT
+   - `cfdi_invoice_item_taxes`: Impuestos por concepto
+   - `cfdi_related_documents`: CFDIs relacionados
+
+2. **28-cfdi-operations.sql**: Operaciones CFDI
+   - `cfdi_cancellation_requests`: Solicitudes de cancelacion
+   - `cfdi_operation_logs`: Audit trail de operaciones
+   - `cfdi_payment_complements`: Complementos de pago (REP)
+   - `cfdi_payment_complement_documents`: Documentos en complemento
+   - `cfdi_stamp_queue`: Cola de timbrado asincrono
+
+3. **29-cfdi-rls-functions.sql**: Seguridad y funciones
+   - RLS policies para multi-tenancy
+   - Funciones auxiliares (validate_rfc, generate_folio, etc.)
+   - Triggers de auditoria y validacion
+   - Vistas para reportes y monitoreo
+
+### ENUMs creados:
+- `cfdi_voucher_type`: Tipos de comprobante (I, E, T, N, P)
+- `csd_certificate_status`: Estados de certificado CSD
+- `cfdi_status`: Estados del CFDI
+- `cfdi_relation_type`: Tipos de relacion entre CFDIs
+- `cfdi_cancellation_reason`: Motivos de cancelacion SAT
+- `cancellation_request_status`: Estados de solicitud cancelacion
+- `cfdi_operation_type`: Tipos de operacion para logs
+- `payment_complement_status`: Estados del complemento de pago
+
+### Funciones creadas:
+- `fiscal.get_default_certificate()`: Obtener certificado activo
+- `fiscal.get_active_pac()`: Obtener PAC configurado
+- `fiscal.validate_rfc()`: Validar RFC mexicano
+- `fiscal.generate_cfdi_folio()`: Generar folios consecutivos
+- `fiscal.can_cancel_cfdi()`: Verificar si CFDI puede cancelarse
+- `fiscal.get_invoice_payment_balance()`: Saldo de factura PPD
+- `fiscal.get_cfdi_summary()`: Resumen de CFDIs por periodo
+
+### Vistas creadas:
+- `fiscal.v_cfdi_pending_stamp`: CFDIs pendientes de timbrar
+- `fiscal.v_cfdi_pending_cancellations`: Cancelaciones pendientes
+- `fiscal.v_certificates_expiring`: Certificados por vencer
+- `fiscal.v_pac_stamp_usage`: Uso de timbres por PAC
+- `fiscal.v_invoices_pending_payment`: Facturas PPD con saldo
+
+---
+
 ## Referencias
 
 - Entities: `docs/_definitions/ENTITIES-CATALOG.md`
@@ -161,4 +225,4 @@ done
 
 ---
 
-*Documentacion creada: 2026-01-24 - Sprint 3 Documentacion*
+*Documentacion actualizada: 2026-02-03 - Modulo CFDI*