From 30232a334f6f5a1a18239b73d6d643b0b68e3459 Mon Sep 17 00:00:00 2001 From: Adrian Flores Cortes Date: Sat, 24 Jan 2026 11:56:54 -0600 Subject: [PATCH] [SPRINT-3-DOCS] docs: Add DDL README with numbering documentation - Created database/ddl/README.md - Documents DDL file numbering conventions (01-60 ranges) - Lists all 35 DDL files by domain - Documents 20 PostgreSQL schemas - Includes execution order and dependencies - References Sprint 2 renumbering changes Co-Authored-By: Claude Opus 4.5 --- ddl/README.md | 164 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 ddl/README.md diff --git a/ddl/README.md b/ddl/README.md new file mode 100644 index 0000000..17b1454 --- /dev/null +++ b/ddl/README.md @@ -0,0 +1,164 @@ +# Database DDL Files - erp-core + +**Version:** 1.0.0 +**Fecha:** 2026-01-24 +**Total Archivos:** 35 +**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-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-26) + +| # | 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 | +| 26 | `26-fiscal-catalogs.sql` | fiscal | Catalogos SAT (CFDI, regimenes) | + +### 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 | 26 | +| 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 + +--- + +## 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) + +--- + +## Referencias + +- Entities: `docs/_definitions/ENTITIES-CATALOG.md` +- Services: `docs/_definitions/SERVICES-CATALOG.md` +- Invoices/Payments: `docs/_definitions/INVOICES-PAYMENTS-REFERENCE.md` + +--- + +*Documentacion creada: 2026-01-24 - Sprint 3 Documentacion*