From 6b02d8ab08269bf6f139de16fc12bcc322da8439 Mon Sep 17 00:00:00 2001 From: Adrian Flores Cortes Date: Tue, 3 Feb 2026 07:19:45 -0600 Subject: [PATCH] [ST-P0-003] docs: Add DDL execution order and update README - Create DDL-EXECUTION-ORDER.md with schema dependencies - Document execution order for erp-core + erp-construccion - Add WSL commands for database recreation - Update README.md with current schema counts (10 schemas, 143 tables, 115 ENUMs) Co-Authored-By: Claude Opus 4.5 --- DDL-EXECUTION-ORDER.md | 278 +++++++++++++++++++++++++++++++++++++++++ README.md | 258 ++++++++++++++++++++++---------------- 2 files changed, 425 insertions(+), 111 deletions(-) create mode 100644 DDL-EXECUTION-ORDER.md diff --git a/DDL-EXECUTION-ORDER.md b/DDL-EXECUTION-ORDER.md new file mode 100644 index 0000000..9d441ed --- /dev/null +++ b/DDL-EXECUTION-ORDER.md @@ -0,0 +1,278 @@ +# DDL Execution Order - ERP Construccion + +**Version:** 1.0.0 +**Fecha:** 2026-02-03 +**Proyecto:** erp-construccion + +--- + +## Descripcion + +Este documento define el orden correcto de ejecucion de archivos DDL para crear una base de datos limpia de ERP Construccion. Es fundamental seguir este orden debido a las dependencias entre schemas y tablas. + +--- + +## Dependencias de Schema + +### Diagrama de Dependencias + +``` +erp-core (auth, core, etc.) + | + +-- auth.tenants (REQUERIDO) + +-- auth.users (REQUERIDO) + | + v +erp-construccion + | + +-- init-scripts/01-init-database.sql + | | + | +-- core_shared (funciones) + | +-- core.tenants (fallback si erp-core no instalado) + | +-- core.users (fallback si erp-core no instalado) + | +-- Schemas: construction, estimates, infonavit, hse, hr, inventory, purchase + | + +-- schemas/01-construction-schema-ddl.sql + | | + | +-- VERIFICA: auth.tenants, auth.users + | +-- CREA: Schema construction (24 tablas) + | + +-- schemas/02-hr-schema-ddl.sql + +-- schemas/03-hse-schema-ddl.sql + +-- schemas/04-estimates-schema-ddl.sql + +-- schemas/05-infonavit-schema-ddl.sql + +-- schemas/06-inventory-ext-schema-ddl.sql + +-- schemas/07-purchase-ext-schema-ddl.sql + +-- schemas/08-finance-schema-ddl.sql + +-- schemas/09-assets-schema-ddl.sql + +-- schemas/10-documents-schema-ddl.sql + +-- schemas/99-rls-policies.sql +``` + +--- + +## Orden de Ejecucion + +### Escenario A: Base de Datos Nueva (sin erp-core) + +Cuando se crea una BD limpia SIN erp-core instalado previamente: + +| Paso | Archivo | Descripcion | +|------|---------|-------------| +| 1 | `init-scripts/01-init-database.sql` | Extensiones, core_shared, schemas base, tablas fallback | +| 2 | `schemas/01-construction-schema-ddl.sql` | Schema construction (24 tablas, 7 ENUMs) | +| 3 | `schemas/02-hr-schema-ddl.sql` | Schema hr extension | +| 4 | `schemas/03-hse-schema-ddl.sql` | Schema hse (58 tablas, 67 ENUMs) | +| 5 | `schemas/04-estimates-schema-ddl.sql` | Schema estimates (8 tablas, 4 ENUMs) | +| 6 | `schemas/05-infonavit-schema-ddl.sql` | Schema infonavit (8 tablas) | +| 7 | `schemas/06-inventory-ext-schema-ddl.sql` | Extension inventory | +| 8 | `schemas/07-purchase-ext-schema-ddl.sql` | Extension purchase | +| 9 | `schemas/08-finance-schema-ddl.sql` | Schema finance (11 tablas, 20 ENUMs) | +| 10 | `schemas/09-assets-schema-ddl.sql` | Schema assets (11 tablas, 9 ENUMs) | +| 11 | `schemas/10-documents-schema-ddl.sql` | Schema documents (11 tablas, 8 ENUMs) | +| 12 | `schemas/99-rls-policies.sql` | Politicas RLS para todos los schemas | +| 13 | `init-scripts/02-payment-terminals.sql` | Terminales de pago (opcional) | + +### Escenario B: Base de Datos con erp-core (Recomendado) + +Cuando erp-core YA esta instalado: + +| Paso | Ubicacion | Archivo | Descripcion | +|------|-----------|---------|-------------| +| 1-N | erp-core | `01-auth-profiles.sql` ... `99-rls-erp-modules.sql` | Todos los DDL de erp-core | +| N+1 | erp-construccion | `init-scripts/01-init-database.sql` | Extensiones PostGIS, funciones | +| N+2 | erp-construccion | `schemas/01-construction-schema-ddl.sql` | Schema construction | +| ... | ... | ... | Resto de schemas construccion | + +--- + +## Verificaciones Pre-Ejecucion + +El archivo `01-construction-schema-ddl.sql` incluye verificaciones automaticas: + +```sql +-- Verificar que ERP-Core esta instalado +DO $$ +BEGIN + IF NOT EXISTS (SELECT 1 FROM pg_namespace WHERE nspname = 'auth') THEN + RAISE EXCEPTION 'Schema auth no existe. Ejecutar primero ERP-Core DDL'; + END IF; + IF NOT EXISTS (SELECT 1 FROM pg_tables WHERE schemaname = 'auth' AND tablename = 'tenants') THEN + RAISE EXCEPTION 'Tabla auth.tenants no existe. ERP-Core debe estar instalado'; + END IF; + IF NOT EXISTS (SELECT 1 FROM pg_tables WHERE schemaname = 'auth' AND tablename = 'users') THEN + RAISE EXCEPTION 'Tabla auth.users no existe. ERP-Core debe estar instalado'; + END IF; +END $$; +``` + +--- + +## Naming de Schemas + +### erp-core usa + +| Schema | Descripcion | +|--------|-------------| +| `auth` | Autenticacion, tenants, users, roles | +| `core` | Sucursales, catalogos compartidos | +| `billing` | Facturacion SaaS | +| `inventory` | Inventario base | +| `partners` | Clientes/proveedores | +| `products` | Productos | +| `purchases` | Compras | +| `sales` | Ventas | +| `financial` | Contabilidad | + +### erp-construccion usa + +| Schema | Tipo | Descripcion | +|--------|------|-------------| +| `construction` | Propio | Proyectos, frentes, avances (24 tablas) | +| `estimates` | Propio | Estimaciones, generadores (8 tablas) | +| `infonavit` | Propio | Procesos INFONAVIT (8 tablas) | +| `hse` | Propio | Seguridad, salud, ambiente (58 tablas) | +| `hr` | Extension | RRHH extendido para construccion | +| `inventory` | Extension | Almacen de obra | +| `purchase` | Extension | Compras por proyecto | +| `finance` | Propio | Contabilidad construccion (11 tablas) | +| `assets` | Propio | Equipos, maquinaria (11 tablas) | +| `documents` | Propio | Gestion documental (11 tablas) | + +### Schemas Legacy (Deprecados) + +Los siguientes schemas se crean en `01-init-database.sql` para compatibilidad pero estan DEPRECADOS: + +- `auth_management` -> Usar `auth` +- `project_management` -> Usar `construction` +- `financial_management` -> Usar `estimates` +- `purchasing_management` -> Usar `purchase` +- `inventory_management` -> Usar `inventory` +- `construction_management` -> Usar `construction` +- `quality_management` -> Usar `hse` o `construction` +- `safety_management` -> Usar `hse` +- `infonavit_management` -> Usar `infonavit` + +--- + +## Comandos de Ejecucion WSL + +### Recrear BD Completa (Recomendado) + +```bash +# Desde Windows PowerShell +wsl -d Ubuntu-24.04 -u developer -- bash '/mnt/c/Empresas/ISEM/workspace-v2/projects/erp-construccion/database/drop-and-recreate-database.sh' +``` + +### Ejecutar Archivos Individuales + +```bash +# Variables de conexion +export PGHOST=localhost +export PGPORT=5432 +export PGDATABASE=erp_construccion_db +export PGUSER=erp_admin +export PGPASSWORD=erp_dev_2026 + +# Ruta base Windows desde WSL +BASE_PATH="/mnt/c/Empresas/ISEM/workspace-v2/projects/erp-construccion/database" + +# 1. Inicializacion +psql -f "$BASE_PATH/init-scripts/01-init-database.sql" + +# 2. Schemas en orden +for i in $(seq -w 1 10); do + f="$BASE_PATH/schemas/${i}-*.sql" + if ls $f 1>/dev/null 2>&1; then + psql -f $f + fi +done + +# 3. RLS +psql -f "$BASE_PATH/schemas/99-rls-policies.sql" +``` + +### Ejecutar Solo ERP-Core (si separado) + +```bash +# Ruta erp-core +CORE_PATH="/mnt/c/Empresas/ISEM/workspace-v2/projects/erp-core/database/ddl" + +# Ejecutar todos los DDL de core en orden +for f in $(ls "$CORE_PATH"/*.sql | sort -V); do + psql -f "$f" +done +``` + +### Verificar Instalacion + +```sql +-- Verificar schemas creados +SELECT schema_name +FROM information_schema.schemata +WHERE schema_name IN ( + 'auth', 'core', 'construction', 'estimates', + 'infonavit', 'hse', 'hr', 'inventory', + 'purchase', 'finance', 'assets', 'documents' +) +ORDER BY schema_name; + +-- Contar tablas por schema +SELECT table_schema, COUNT(*) as table_count +FROM information_schema.tables +WHERE table_schema IN ( + 'auth', 'core', 'construction', 'estimates', + 'infonavit', 'hse', 'hr', 'inventory', + 'purchase', 'finance', 'assets', 'documents' +) +GROUP BY table_schema +ORDER BY table_schema; +``` + +--- + +## Troubleshooting + +### Error: "Schema auth no existe" + +**Causa:** Se ejecuto `01-construction-schema-ddl.sql` sin ejecutar `01-init-database.sql` primero, o sin instalar erp-core. + +**Solucion:** +```bash +# Opcion A: Ejecutar init primero +psql -f init-scripts/01-init-database.sql + +# Opcion B: Instalar erp-core completo primero +``` + +### Error: "Tabla auth.tenants no existe" + +**Causa:** El init-database.sql usa fallback a `core.tenants` pero el construction DDL espera `auth.tenants`. + +**Solucion:** El `01-init-database.sql` crea tablas en `core.*` como fallback. Para produccion, se recomienda instalar erp-core completo. + +### Error: Extension postgis no disponible + +**Causa:** PostGIS no esta instalado en el servidor PostgreSQL. + +**Solucion:** +```bash +# En Ubuntu/Debian +sudo apt install postgresql-15-postgis-3 + +# Luego en psql +CREATE EXTENSION postgis; +``` + +--- + +## Referencias + +- `HERENCIA-ERP-CORE.md` - Relacion con erp-core +- `_MAP.md` - Mapa completo de la BD +- `VALIDACION-DDL-INVENTARIOS.md` - Validaciones de inventario +- `../CLAUDE.md` - Instrucciones del proyecto + +--- + +*Documentacion creada: 2026-02-03 - ST-P0-003* diff --git a/README.md b/README.md index c63e6e1..7e0ce6a 100644 --- a/README.md +++ b/README.md @@ -1,185 +1,221 @@ -# Database - MVP Sistema Administración de Obra +# Database - ERP Construccion **Stack:** PostgreSQL 15+ con PostGIS -**Versión:** 1.0.0 -**Fecha:** 2025-11-20 +**Version:** 2.0.0 +**Fecha:** 2026-02-03 +**Dependencia:** erp-core (auth, core schemas) --- -## 📋 DESCRIPCIÓN +## Descripcion -Base de datos del sistema de administración de obra e INFONAVIT. +Base de datos del ERP de construccion. Extiende erp-core con schemas especializados para gestion de obras, estimaciones, INFONAVIT, HSE y mas. -**Schemas principales:** -- `auth_management` - Autenticación y usuarios -- `project_management` - Proyectos y estructura de obra -- `financial_management` - Presupuestos y control financiero -- `purchasing_management` - Compras e inventarios -- `construction_management` - Control de obra y avances -- `quality_management` - Calidad y postventa -- `infonavit_management` - Integración INFONAVIT +**Schemas principales (actuales):** +- `construction` - Proyectos, fraccionamientos, avances (24 tablas) +- `estimates` - Presupuestos, estimaciones, generadores (8 tablas) +- `infonavit` - Integracion INFONAVIT (8 tablas) +- `hse` - Seguridad, salud y ambiente (58 tablas) +- `hr` - Extension RRHH para construccion +- `inventory` - Extension almacen de obra +- `purchase` - Extension compras por proyecto +- `finance` - Contabilidad construccion (11 tablas) +- `assets` - Equipos y maquinaria (11 tablas) +- `documents` - Gestion documental (11 tablas) + +**Total:** 10 schemas, 143 tablas, 115 ENUMs --- -## 🏗️ ESTRUCTURA +## Estructura ``` -ddl/ -├── 00-init.sql # Inicialización + extensiones -└── schemas/ # Schemas por contexto - ├── auth_management/ - │ ├── tables/ # Tablas (01-users.sql, 02-roles.sql, ...) - │ ├── functions/ # Funciones SQL - │ ├── triggers/ # Triggers - │ └── views/ # Vistas - ├── project_management/ - │ └── ... - └── [otros schemas]/ - -seeds/ -├── dev/ # Datos de desarrollo -└── prod/ # Datos de producción inicial - -migrations/ # Migraciones versionadas -scripts/ # Scripts de utilidad +database/ +├── DDL-EXECUTION-ORDER.md # Orden de ejecucion (LEER PRIMERO) +├── README.md # Este archivo +├── HERENCIA-ERP-CORE.md # Relacion con erp-core +├── _MAP.md # Mapa completo de la BD +├── VALIDACION-DDL-INVENTARIOS.md # Validaciones +├── drop-and-recreate-database.sh # Script recrear BD +├── validate-clean-load-policy.sh # Validar politica carga limpia +├── init-scripts/ +│ ├── 01-init-database.sql # Extensiones, funciones, schemas base +│ └── 02-payment-terminals.sql # Terminales de pago +└── schemas/ + ├── 01-construction-schema-ddl.sql # construction (24 tablas) + ├── 02-hr-schema-ddl.sql # hr extension + ├── 03-hse-schema-ddl.sql # hse (58 tablas, 67 ENUMs) + ├── 04-estimates-schema-ddl.sql # estimates (8 tablas) + ├── 05-infonavit-schema-ddl.sql # infonavit (8 tablas) + ├── 06-inventory-ext-schema-ddl.sql # inventory extension + ├── 07-purchase-ext-schema-ddl.sql # purchase extension + ├── 08-finance-schema-ddl.sql # finance (11 tablas) + ├── 09-assets-schema-ddl.sql # assets (11 tablas) + ├── 10-documents-schema-ddl.sql # documents (11 tablas) + └── 99-rls-policies.sql # Politicas RLS ``` --- -## 🚀 SETUP INICIAL +## Dependencias -### 1. Crear Base de Datos +**IMPORTANTE:** Este proyecto depende de erp-core. Antes de ejecutar los DDL de construccion: + +1. El schema `auth` debe existir con las tablas `tenants` y `users` +2. Ver `DDL-EXECUTION-ORDER.md` para orden de ejecucion completo + +--- + +## Setup Inicial + +### Opcion A: Recrear BD Completa (Recomendado) ```bash -# Ejecutar script de creación -cd scripts -./create-database.sh +# Desde Windows PowerShell - ejecuta en WSL +wsl -d Ubuntu-24.04 -u developer -- bash '/mnt/c/Empresas/ISEM/workspace-v2/projects/erp-construccion/database/drop-and-recreate-database.sh' ``` -### 2. Ejecutar DDL +### Opcion B: Ejecutar DDL Manualmente ```bash -# Ejecutar inicialización -psql $DATABASE_URL -f ddl/00-init.sql +# Variables de conexion +export PGHOST=localhost +export PGPORT=5432 +export PGDATABASE=erp_construccion_db +export PGUSER=erp_admin +export PGPASSWORD=erp_dev_2026 -# Ejecutar schemas (en orden) -psql $DATABASE_URL -f ddl/schemas/auth_management/tables/01-users.sql -# ... etc -``` +# Ruta base desde WSL +BASE="/mnt/c/Empresas/ISEM/workspace-v2/projects/erp-construccion/database" -### 3. Cargar Seeds (desarrollo) +# 1. Inicializacion +psql -f "$BASE/init-scripts/01-init-database.sql" -```bash -psql $DATABASE_URL -f seeds/dev/01-users.sql -psql $DATABASE_URL -f seeds/dev/02-projects.sql +# 2. Schemas en orden +psql -f "$BASE/schemas/01-construction-schema-ddl.sql" +psql -f "$BASE/schemas/02-hr-schema-ddl.sql" +psql -f "$BASE/schemas/03-hse-schema-ddl.sql" +psql -f "$BASE/schemas/04-estimates-schema-ddl.sql" +psql -f "$BASE/schemas/05-infonavit-schema-ddl.sql" +psql -f "$BASE/schemas/06-inventory-ext-schema-ddl.sql" +psql -f "$BASE/schemas/07-purchase-ext-schema-ddl.sql" +psql -f "$BASE/schemas/08-finance-schema-ddl.sql" +psql -f "$BASE/schemas/09-assets-schema-ddl.sql" +psql -f "$BASE/schemas/10-documents-schema-ddl.sql" +psql -f "$BASE/schemas/99-rls-policies.sql" ``` --- -## 🔧 SCRIPTS DISPONIBLES +## Scripts Disponibles -| Script | Descripción | +| Script | Descripcion | |--------|-------------| -| `create-database.sh` | Crea la base de datos desde cero | -| `reset-database.sh` | Elimina y recrea la base de datos | -| `run-migrations.sh` | Ejecuta migraciones pendientes | -| `backup-database.sh` | Crea backup de la base de datos | +| `drop-and-recreate-database.sh` | Elimina y recrea la BD completa | +| `validate-clean-load-policy.sh` | Valida politica de carga limpia | --- -## 📊 CONVENCIONES +## Convenciones -### Nomenclatura +### Nomenclatura Actual -Seguir **ESTANDARES-NOMENCLATURA.md**: -- Schemas: `snake_case` + sufijo `_management` +- Schemas: `snake_case` (sin sufijo `_management`) - Tablas: `snake_case` plural - Columnas: `snake_case` singular -- Índices: `idx_{tabla}_{columnas}` -- Foreign Keys: `fk_{origen}_to_{destino}` -- Constraints: `chk_{tabla}_{columna}` +- Indices: `idx_{tabla}_{columnas}` +- Constraints: `chk_{tabla}_{condicion}`, `uq_{tabla}_{columnas}` -### Estructura de Archivo DDL +### Schemas Legacy (Deprecados) -```sql --- ============================================================================ --- Tabla: nombre_tabla --- Schema: nombre_schema --- Descripción: [descripción] --- Autor: Database-Agent --- Fecha: YYYY-MM-DD --- ============================================================================ - -DROP TABLE IF EXISTS schema.tabla CASCADE; - -CREATE TABLE schema.tabla ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - -- columnas... - created_at TIMESTAMPTZ NOT NULL DEFAULT now(), - updated_at TIMESTAMPTZ NOT NULL DEFAULT now() -); - -COMMENT ON TABLE schema.tabla IS '[descripción]'; -COMMENT ON COLUMN schema.tabla.columna IS '[descripción]'; - -CREATE INDEX idx_tabla_columna ON schema.tabla(columna); -``` +Los siguientes schemas existen para compatibilidad pero NO deben usarse: +- `auth_management` -> Usar `auth` +- `project_management` -> Usar `construction` +- `financial_management` -> Usar `estimates` +- Ver `DDL-EXECUTION-ORDER.md` para lista completa --- -## 🔍 VALIDACIÓN +## Validacion ### Verificar Schemas ```sql SELECT schema_name FROM information_schema.schemata -WHERE schema_name LIKE '%_management'; +WHERE schema_name IN ( + 'auth', 'core', 'construction', 'estimates', + 'infonavit', 'hse', 'hr', 'inventory', + 'purchase', 'finance', 'assets', 'documents' +) +ORDER BY schema_name; ``` -### Verificar Tablas +### Contar Tablas por Schema ```sql -SELECT table_schema, table_name, - (SELECT COUNT(*) FROM information_schema.columns - WHERE table_schema = t.table_schema - AND table_name = t.table_name) as column_count -FROM information_schema.tables t -WHERE table_schema LIKE '%_management' -ORDER BY table_schema, table_name; +SELECT table_schema, COUNT(*) as table_count +FROM information_schema.tables +WHERE table_schema IN ( + 'construction', 'estimates', 'infonavit', 'hse', + 'hr', 'inventory', 'purchase', 'finance', 'assets', 'documents' +) +GROUP BY table_schema +ORDER BY table_count DESC; ``` -### Verificar Índices +### Verificar Tablas Core Requeridas ```sql -SELECT tablename, indexname -FROM pg_indexes -WHERE schemaname LIKE '%_management' -ORDER BY tablename; +-- Estas tablas deben existir antes de ejecutar DDL de construccion +SELECT EXISTS ( + SELECT 1 FROM pg_tables + WHERE schemaname = 'auth' AND tablename = 'tenants' +) AS tenants_exists, +EXISTS ( + SELECT 1 FROM pg_tables + WHERE schemaname = 'auth' AND tablename = 'users' +) AS users_exists; ``` --- -## 📚 REFERENCIAS +## Referencias -- [DIRECTIVA-DISENO-BASE-DATOS.md](../../orchestration/directivas/DIRECTIVA-DISENO-BASE-DATOS.md) -- [ESTANDARES-NOMENCLATURA.md](../../orchestration/directivas/ESTANDARES-NOMENCLATURA.md) -- [MVP-APP.md](../../docs/00-overview/MVP-APP.md) +- `DDL-EXECUTION-ORDER.md` - Orden de ejecucion y dependencias +- `HERENCIA-ERP-CORE.md` - Relacion con erp-core +- `_MAP.md` - Mapa completo de la BD +- `VALIDACION-DDL-INVENTARIOS.md` - Validaciones de inventario +- `../../CLAUDE.md` - Instrucciones del proyecto --- -## 📝 VARIABLES DE ENTORNO +## Variables de Entorno ```bash -DATABASE_URL=postgresql://usuario:password@localhost:5432/nombre_db +# Desarrollo local (WSL) DB_HOST=localhost DB_PORT=5432 -DB_NAME=erp_construccion -DB_USER=postgres -DB_PASSWORD=password +DB_NAME=erp_construccion_db +DB_USER=erp_admin +DB_PASSWORD=erp_dev_2026 + +# Connection string +DATABASE_URL=postgresql://erp_admin:erp_dev_2026@localhost:5432/erp_construccion_db ``` --- -**Mantenido por:** Database-Agent -**Última actualización:** 2025-11-20 +## Credenciales de Desarrollo + +| Variable | Valor | +|----------|-------| +| Database | erp_construccion_db | +| User | erp_admin | +| Password | erp_dev_2026 | +| Host | localhost | +| Port | 5432 | + +--- + +*Documentacion actualizada: 2026-02-03*