[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 <noreply@anthropic.com>
This commit is contained in:
Adrian Flores Cortes 2026-02-03 07:19:45 -06:00
parent f76afed513
commit 6b02d8ab08
2 changed files with 425 additions and 111 deletions

278
DDL-EXECUTION-ORDER.md Normal file
View File

@ -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*

258
README.md
View File

@ -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*