# 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

```sql
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)

```yaml
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

```yaml
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:
  ```sql
  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

```sql
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:

```bash
# 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