# Database DDL Files - erp-core

**Version:** 1.1.0
**Fecha:** 2026-02-03
**Total Archivos:** 38
**Total Schemas:** 20

---

## Convenciones de Numeracion

Los archivos DDL siguen un esquema de numeracion por rangos segun dominio funcional:

| Rango | Dominio | Descripcion |
|-------|---------|-------------|
| 01-09 | Foundation | Auth, core, mobile, billing base |
| 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-29 | Fiscal & CFDI | Catalogos SAT, facturacion electronica CFDI |
| 30-49 | Reserved | Expansiones futuras |
| 50-59 | Financial | Contabilidad completa |
| 60-69 | Projects | Proyectos y timesheets |

---

## Archivos DDL por Dominio

### Foundation (01-09)

| # | Archivo | Schema | Descripcion |
|---|---------|--------|-------------|
| 01 | `01-auth-profiles.sql` | auth | Usuarios, sesiones, perfiles |
| 02 | `02-auth-devices.sql` | auth | Dispositivos, biometria |
| 03 | `03-core-branches.sql` | core | Sucursales, horarios |
| 04 | `04-mobile.sql` | mobile | Sesiones movil, push, sync |
| 05 | `05-billing-usage.sql` | billing | Suscripciones, planes, uso |
| 06 | `06-auth-extended.sql` | auth | OAuth, MFA extendido |
| 07 | `07-users-rbac.sql` | auth | Roles, permisos, grupos |
| 08 | `08-plans.sql` | billing | Planes detallados, features |
| 09 | `09-notifications.sql` | notifications | Notificaciones multicanal |

### System (10-15)

| # | Archivo | Schema | Descripcion |
|---|---------|--------|-------------|
| 10 | `10-audit.sql` | audit | Logs de auditoria completos |
| 11 | `11-feature-flags.sql` | feature_flags | Feature toggles por tenant |
| 12 | `12-webhooks.sql` | webhooks | Suscripciones y entregas |
| 13 | `13-storage.sql` | storage | Archivos, buckets, uploads |
| 14 | `14-ai.sql` | ai | Modelos, prompts, completions |
| 15 | `15-whatsapp.sql` | whatsapp | Conversaciones, mensajes |

### Partners & Products (16-19)

| # | Archivo | Schema | Descripcion |
|---|---------|--------|-------------|
| 16 | `16-partners.sql` | partners | Clientes/proveedores, tax_info, segments |
| 17 | `17-products.sql` | products | Productos comerciales |
| 18 | `18-warehouses.sql` | inventory | Almacenes, zonas, ubicaciones |
| 19 | `19-product-attributes.sql` | products | Atributos, variantes |

### Catalogs & Operations (20-24)

| # | Archivo | Schema | Descripcion |
|---|---------|--------|-------------|
| 20 | `20-core-catalogs.sql` | core | Paises, monedas, UoM, secuencias |
| 21 | `21-inventory.sql` | inventory | Stock, lots, pickings, transfers |
| 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 |

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

| # | Archivo | Schema | Descripcion |
|---|---------|--------|-------------|
| 50 | `50-financial-schema.sql` | financial | Schema y extensiones |
| 51 | `51-financial-accounts.sql` | financial | Plan de cuentas, tipos |
| 52 | `52-financial-journals.sql` | financial | Diarios contables |
| 53 | `53-financial-entries.sql` | financial | Asientos contables |
| 54 | `54-financial-invoices.sql` | financial | Facturas contables |
| 55 | `55-financial-payments.sql` | financial | Pagos contables |
| 56 | `56-financial-taxes.sql` | financial | Impuestos |
| 57 | `57-financial-bank-reconciliation.sql` | financial | Conciliacion bancaria |

### Projects (60+)

| # | Archivo | Schema | Descripcion |
|---|---------|--------|-------------|
| 60 | `60-projects-timesheets.sql` | projects | Hojas de tiempo |

### Matching (46)

| # | Archivo | Schema | Descripcion |
|---|---------|--------|-------------|
| 46 | `46-purchases-matching.sql` | purchases | 3-way matching PO/Receipt/Invoice |

---

## Schemas PostgreSQL

| Schema | Proposito | DDL Files |
|--------|-----------|-----------|
| auth | Autenticacion y usuarios | 01, 02, 06, 07 |
| audit | Logs de auditoria | 10 |
| billing | Facturacion SaaS | 05, 08, 24 |
| core | Catalogos compartidos | 03, 20 |
| feature_flags | Feature toggles | 11 |
| financial | Contabilidad | 50-57 |
| fiscal | Catalogos SAT y CFDI | 26, 27, 28, 29 |
| inventory | Inventario y stock | 18, 21 |
| mobile | App movil | 04 |
| notifications | Notificaciones | 09 |
| partners | Clientes/proveedores | 16 |
| products | Productos | 17, 19 |
| projects | Proyectos | 60 |
| purchases | Compras | 23, 46 |
| sales | Ventas | 22 |
| storage | Archivos | 13 |
| webhooks | Webhooks | 12 |
| whatsapp | WhatsApp | 15 |
| ai | Inteligencia artificial | 14 |

---

## Orden de Ejecucion

Para una instalacion limpia, ejecutar en orden numerico:

```bash
for f in $(ls *.sql | sort -n); do
  psql -d erp_db -f "$f"
done
```

**Dependencias importantes:**
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`

---

## Notas de Sprint 2 (2026-01-24)

### Cambios realizados:
1. **21-inventory.sql**: Agregadas tablas `lots` y `pickings` con ENUMs
2. **16-partners.sql**: Agregadas tablas `partner_tax_info` y `partner_segments`
3. **26-fiscal-catalogs.sql**: Renumerado de 21 a 26 para evitar conflicto

### Renumeracion historica:
- `21-fiscal-catalogs.sql` -> `26-fiscal-catalogs.sql` (Sprint 2, 2026-01-24)
- `25-fiscal-catalogs.sql` eliminado (duplicado)

---

## 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`
- Services: `docs/_definitions/SERVICES-CATALOG.md`
- Invoices/Payments: `docs/_definitions/INVOICES-PAYMENTS-REFERENCE.md`

---

*Documentacion actualizada: 2026-02-03 - Modulo CFDI*