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

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

// 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

// 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

// 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

// 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

// 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

// 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