erp-core/orchestration/directivas/DIRECTIVA-EXTENSION-VERTICALES.md

# Directiva: Extensión de Verticales

## Propósito

Define las reglas para que las verticales (construcción, vidrio-templado, etc.) extiendan correctamente el ERP Core sin modificarlo.

## Principio Fundamental

```
Las verticales EXTIENDEN el core, NUNCA lo modifican.
```

---

## Arquitectura de Extensión

```
erp-core (60-70% código base)
    │
    ├── core_auth.*           → Heredado por todas las verticales
    ├── core_users.*          → Heredado por todas las verticales
    ├── core_tenants.*        → Heredado por todas las verticales
    └── core_catalogs.*       → Heredado por todas las verticales
        │
        ▼
verticales/{nombre}/ (+30-40% código específico)
    │
    ├── {nombre}_*.schemas    → Schemas propios de la vertical
    ├── /backend/src/modules/ → Módulos específicos
    └── /frontend/src/        → Componentes específicos
```

---

## Reglas de Extensión

### 1. Schemas de Base de Datos

```sql
-- CORRECTO: Crear schema propio
CREATE SCHEMA construccion_management;

-- CORRECTO: Referenciar tablas del core
CREATE TABLE construccion_management.projects (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL REFERENCES core_tenants.tenants(id),
    created_by UUID REFERENCES core_auth.users(id),
    -- ... columnas específicas de construcción
);

-- INCORRECTO: Modificar tablas del core
ALTER TABLE core_auth.users ADD COLUMN campo_construccion TEXT; -- ❌ PROHIBIDO
```

### 2. Backend - Servicios

```typescript
// CORRECTO: Importar y extender servicios del core
import { AuthService } from '@erp-core/auth';
import { BaseService } from '@erp-core/shared';

@Injectable()
export class ProjectService extends BaseService<Project> {
    constructor(
        private authService: AuthService, // Usar del core
    ) {
        super();
    }
}

// INCORRECTO: Duplicar lógica del core
export class MyAuthService { } // ❌ PROHIBIDO - usar el del core
```

### 3. Backend - Entidades

```typescript
// CORRECTO: Extender entidad base
import { BaseEntity } from '@erp-core/shared';

@Entity('construccion_management.projects')
export class Project extends BaseEntity {
    // BaseEntity ya tiene: id, tenantId, createdAt, updatedAt

    @Column()
    nombre: string;

    // Referencia a usuario del core
    @ManyToOne(() => User)
    @JoinColumn({ name: 'project_manager_id' })
    projectManager: User;
}
```

### 4. Frontend - Componentes

```typescript
// CORRECTO: Usar componentes del core
import { Button, Input, DataTable } from '@erp-core/ui';
import { useAuth, useTenant } from '@erp-core/hooks';

export const ProjectList = () => {
    const { user } = useAuth(); // Hook del core

    return (
        <DataTable columns={columns} /> // Componente del core
    );
};

// INCORRECTO: Reimplementar componentes base
export const MyButton = () => { }; // ❌ PROHIBIDO - usar el del core
```

---

## Estructura de Directorio para Verticales

```
verticales/{nombre}/
├── backend/
│   └── src/
│       ├── modules/           # Módulos específicos
│       │   ├── projects/      # Ejemplo: proyectos de construcción
│       │   └── estimates/     # Ejemplo: estimaciones
│       └── index.ts           # Exporta módulos de la vertical
│
├── frontend/
│   └── src/
│       ├── components/        # Componentes específicos
│       ├── pages/             # Páginas específicas
│       └── index.ts           # Exporta componentes de la vertical
│
├── database/
│   ├── ddl/                   # Schemas específicos
│   ├── migrations/            # Migraciones específicas
│   └── seeds/                 # Seeds específicos
│
├── docs/                      # Documentación específica
└── orchestration/             # Orquestación específica
```

---

## Cómo Extender Funcionalidad

### Caso 1: Agregar campos a una entidad del core

```typescript
// NO modificar core_auth.users

// Crear tabla de extensión en la vertical
CREATE TABLE construccion_management.user_extensions (
    id UUID PRIMARY KEY,
    user_id UUID NOT NULL REFERENCES core_auth.users(id),
    cargo_obra VARCHAR(100),
    numero_imss VARCHAR(50),
    UNIQUE(user_id)
);

// Crear vista que combina ambas
CREATE VIEW construccion_management.users_complete AS
SELECT u.*, ue.cargo_obra, ue.numero_imss
FROM core_auth.users u
LEFT JOIN construccion_management.user_extensions ue ON u.id = ue.user_id;
```

### Caso 2: Agregar validación específica

```typescript
// En la vertical, crear decorator que usa el del core
import { ValidateTenant } from '@erp-core/validators';

// Agregar validación específica
export const ValidateProject = () => {
    return applyDecorators(
        ValidateTenant(), // Del core
        ValidateProjectBudget(), // Específico de construcción
    );
};
```

### Caso 3: Agregar endpoint específico

```typescript
// En la vertical
@Controller('construction/projects')
export class ProjectController {
    @Get()
    @UseGuards(AuthGuard) // Guard del core
    async findAll() {
        // Lógica específica de construcción
    }
}
```

---

## Validaciones Obligatorias

### Antes de crear código en vertical:
- [ ] ¿El core ya tiene esta funcionalidad? → Usar del core
- [ ] ¿Se puede extender algo del core? → Extender, no duplicar
- [ ] ¿Es realmente específico de la vertical? → Ok crear nuevo

### Antes de modificar el core:
- [ ] ¿Beneficia a TODAS las verticales? → Ok modificar core
- [ ] ¿Es específico de una vertical? → Crear en la vertical
- [ ] ¿Rompe compatibilidad? → Crear versión nueva, deprecar antigua

---

## Verticales Registradas

| Vertical | Código | Módulos | SP | Estado | SPECS Aplicables |
|----------|--------|---------|----:|--------|------------------|
| **Construcción** | CONS | 18 (MAI/MAE/MAA) | 450+ | EN_DESARROLLO | 27 |
| **Mecánicas Diesel** | MMD | 5 (MMD) | 150+ | DDL_IMPLEMENTADO | 25 |
| **Vidrio Templado** | VT | 8 (VT) | 212 | PLANIFICACION_COMPLETA | 25 |
| **Retail/POS** | RT | 10 (RT) | 322 | PLANIFICACION_COMPLETA | 26 |
| **Clínicas** | CL | 12 (CL) | 395 | PLANIFICACION_COMPLETA | 22 |

**Total:** 53 módulos | 1529+ Story Points | 30 SPECS transversales disponibles

---

## SPECS Obligatorias por Vertical

### Todas las Verticales (Obligatorias)
- `SPEC-SISTEMA-SECUENCIAS` - Secuencias automáticas
- `SPEC-SEGURIDAD-API-KEYS-PERMISOS` - API Keys y ACL
- `SPEC-MAIL-THREAD-TRACKING` - Comunicación

### Por Tipo de Vertical

| SPEC | CONS | MMD | VT | RT | CL |
|------|:----:|:---:|:--:|:--:|:--:|
| SPEC-VALORACION-INVENTARIO | ✓ | ✓ | ✓ | ✓ | ○ |
| SPEC-TRAZABILIDAD-LOTES-SERIES | ✓ | ✓ | ✓ | ✓ | ✓ |
| SPEC-PRICING-RULES | ✗ | ✓ | ✓ | ✓ | ✗ |
| SPEC-PROYECTOS-DEPENDENCIAS | ✓ | ✗ | ✓ | ✗ | ✗ |
| SPEC-INTEGRACION-CALENDAR | ✗ | ✗ | ✗ | ✗ | ✓ |
| SPEC-FACTURACION-CFDI | ✓ | ✓ | ○ | ✓ | ✓ |
| SPEC-INVENTARIOS-CICLICOS | ✗ | ✓ | ✗ | ✓ | ○ |
| SPEC-RRHH-EVALUACIONES | ✓ | ○ | ○ | ○ | ✓ |

**Leyenda:** ✓ Obligatoria | ○ Opcional | ✗ No aplica

---

## Documentación de Herencia por Vertical

Cada vertical debe tener:

1. **`orchestration/00-guidelines/HERENCIA-SPECS-CORE.md`**
   - Lista de SPECS aplicables con estado
   - Adaptaciones específicas por SPEC
   - Módulos afectados

2. **`database/HERENCIA-ERP-CORE.md`**
   - Tablas del core heredadas
   - Schemas específicos
   - Extensiones planeadas

3. **`orchestration/inventarios/MASTER_INVENTORY.yml`**
   - Métricas de herencia
   - specs_aplicables / specs_implementadas
   - Referencias a core

---

## Mapeo Completo

Ver matriz detallada de aplicabilidad:
```
apps/erp-core/docs/04-modelado/MAPEO-SPECS-VERTICALES.md
```

---

## Referencias

- ERP-Core: `../../../erp-core/`
- Directiva Multi-Tenant: `DIRECTIVA-MULTI-TENANT.md`
- Mapeo SPECS-Verticales: `../../../erp-core/docs/04-modelado/MAPEO-SPECS-VERTICALES.md`
- Suite Master Inventory: `../../../orchestration/inventarios/SUITE_MASTER_INVENTORY.yml`

---

*Directiva específica de ERP-Core*
*Última actualización: 2025-12-08*