workspace/projects/erp-suite/apps/verticales/GUIA-ALINEACION-ERP-CORE.md

Guía de Alineación de Verticales con ERP-Core

Versión: 1.0.0 Fecha: 2025-12-09 Propósito: Estándar para mantener verticales alineadas con erp-core

---

1. Arquitectura Base

ERP-Core como Fundación

Todas las verticales heredan de erp-core que provee:

Schema	Tablas	Propósito
auth	26	Autenticación, MFA, OAuth, API Keys, roles, permisos
core	12	Partners, catálogos, UoM, monedas, secuencias
financial	15	Contabilidad, facturas, pagos, asientos
inventory	20	Productos, stock, valoración FIFO/AVCO, lotes
purchase	8	Órdenes de compra, proveedores
sales	10	Ventas, cotizaciones, equipos de venta
projects	10	Proyectos, tareas, dependencias
analytics	7	Contabilidad analítica, centros de costo
system	13	Mensajes, notificaciones, logs, auditoría
billing	11	SaaS/Suscripciones (opcional)
crm	6	Leads, oportunidades (opcional)
hr	6	Empleados, contratos, ausencias
TOTAL	144

Variable RLS Estándar

current_setting('app.current_tenant_id', true)::UUID

IMPORTANTE: Todas las verticales DEBEN usar esta variable exacta para RLS.

---

2. Estructura de Archivos Requerida

Estructura Mínima por Vertical

apps/verticales/{vertical}/
├── backend/                    # Código backend (NestJS/Express)
├── frontend/                   # Código frontend (React/Vue)
├── database/
│   ├── HERENCIA-ERP-CORE.md   # REQUERIDO: Documento de herencia
│   ├── README.md              # Descripción de BD
│   ├── init/                  # DDL files (si implementado)
│   │   ├── 00-extensions.sql
│   │   ├── 01-create-schemas.sql
│   │   ├── 02-rls-functions.sql
│   │   └── XX-{schema}-tables.sql
│   └── seeds/                 # Datos iniciales
├── docs/                      # Documentación del proyecto
└── orchestration/
    └── inventarios/           # REQUERIDO: Inventarios YAML
        ├── MASTER_INVENTORY.yml
        ├── DATABASE_INVENTORY.yml
        ├── BACKEND_INVENTORY.yml
        ├── FRONTEND_INVENTORY.yml
        ├── DEPENDENCY_GRAPH.yml
        └── TRACEABILITY_MATRIX.yml

---

3. Formato Estándar de DATABASE_INVENTORY.yml

Sección herencia_core (OBLIGATORIA)

herencia_core:
  base_de_datos: erp-core
  version_core: "1.2.0"
  tablas_heredadas: 144  # NO MODIFICAR - valor fijo
  schemas_heredados:
    - nombre: auth
      tablas: 26
      uso: "Descripción contextualizada a la vertical"
    - nombre: core
      tablas: 12
      uso: "..."
    # ... todos los 12 schemas
  referencia_ddl: "apps/erp-core/database/ddl/"
  documento_herencia: "../database/HERENCIA-ERP-CORE.md"
  variable_rls: "app.current_tenant_id"

Sección schemas_especificos

schemas_especificos:
  - nombre: {schema_vertical}
    descripcion: "Propósito del schema"
    estado: PLANIFICADO | EN_DESARROLLO | IMPLEMENTADO
    tablas_estimadas: N
    modulos_relacionados: [MOD-001, MOD-002]
    tablas:
      - nombre_tabla_1
      - nombre_tabla_2

---

4. Reglas de Nomenclatura DDL

Archivos SQL

00-extensions.sql          # Extensiones PostgreSQL
01-create-schemas.sql      # CREATE SCHEMA IF NOT EXISTS
02-rls-functions.sql       # Funciones de contexto RLS
03-{dominio}-tables.sql    # Tablas por dominio
04-{dominio}-tables.sql
...
99-seed-data.sql           # Datos iniciales

Tablas

• Usar snake_case: service_orders, order_items
• Prefijo de schema obligatorio en FK: auth.users, core.partners
• Columnas de auditoría estándar:

  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  created_by UUID REFERENCES auth.users(id),
  updated_at TIMESTAMPTZ,
  updated_by UUID REFERENCES auth.users(id),
  deleted_at TIMESTAMPTZ,
  deleted_by UUID REFERENCES auth.users(id)
  

RLS Policy

CREATE POLICY tenant_isolation_{tabla} ON {schema}.{tabla}
  FOR ALL USING (tenant_id = current_setting('app.current_tenant_id', true)::UUID);

---

5. Estado de Verticales Actuales

Vertical	Estado	DDL	Backend	Frontend	Próximo Paso
Construcción	35%	✅ 7 archivos	Parcial	Estructura	Completar backend
Mecánicas Diesel	95%	✅ 6 archivos	Estructura	Estructura	Iniciar Sprint 1
Clínicas	25%	❌ Pendiente	No iniciado	No iniciado	Crear DDL
Retail	25%	❌ Pendiente	No iniciado	No iniciado	Crear DDL
Vidrio Templado	25%	❌ Pendiente	No iniciado	No iniciado	Crear DDL

---

6. Checklist de Alineación

Antes de iniciar desarrollo:

• herencia_core.tablas_heredadas = 144
• herencia_core.version_core = "1.2.0"
• herencia_core.variable_rls = "app.current_tenant_id"
• Los 12 schemas heredados están documentados
• HERENCIA-ERP-CORE.md existe en database/
• DDL usa current_setting('app.current_tenant_id', true)::UUID
• FK a auth.tenants y auth.users (NO core.*)

Validación de DDL:

# Verificar variable RLS correcta
grep -r "current_tenant_id" database/init/*.sql

# Verificar NO usar variable incorrecta
grep -r "current_tenant'" database/init/*.sql  # Debe retornar vacío

# Verificar FK correctas
grep -r "auth.tenants" database/init/*.sql
grep -r "auth.users" database/init/*.sql

---

7. Proceso de Actualización

Cuando erp-core se actualice:

1. Verificar cambios en INVENTARIO-OBJETOS-BD.yml
2. Actualizar tablas_heredadas si cambió
3. Actualizar version_core
4. Revisar si hay nuevos schemas
5. Actualizar DATABASE_INVENTORY.yml de cada vertical
6. Verificar compatibilidad de DDL existente

---

8. Contacto y Soporte

• Documentación Core: /apps/erp-core/docs/
• Inventario Core: /apps/erp-core/docs/04-modelado/trazabilidad/INVENTARIO-OBJETOS-BD.yml
• DDL Core: /apps/erp-core/database/ddl/

---

Última actualización: 2025-12-09 Mantenido por: Architecture Analyst Agent