erp-suite/orchestration/00-guidelines/HERENCIA-SIMCO.md

# Herencia SIMCO - ERP Suite

**Sistema:** SIMCO v3.8.0 + CAPVED + CCA Protocol + Estándares Documentación + Mantenimiento Docs
**Fecha:** 2026-01-10

---

## Configuración del Proyecto

| Propiedad | Valor |
|-----------|-------|
| **Proyecto** | ERP Suite - Sistema ERP Multi-Vertical |
| **Nivel** | SUITE (Nivel 1) |
| **Padre** | core/orchestration |
| **SIMCO Version** | 3.8.0 |
| **CAPVED** | Habilitado |
| **CCA Protocol** | Habilitado |

## Jerarquía de Herencia

```
Nivel 0: core/orchestration/                    ← FUENTE PRINCIPAL (76 docs)
    │
    └── Nivel 1: erp-suite/orchestration/       ← ESTE PROYECTO
            │
            ├── Nivel 2: erp-core/orchestration/
            │       │
            │       └── Nivel 3: verticales/*/orchestration/
            │           ├── construccion
            │           ├── vidrio-templado
            │           ├── mecanicas-diesel
            │           ├── retail
            │           └── clinicas
            │
            └── Nivel 2: products/*/orchestration/
                    ├── erp-basico
                    └── pos-micro
```

**Regla:** Las directivas de nivel inferior pueden EXTENDER las superiores, nunca REDUCIRLAS.

---

## Directivas Heredadas de CORE (OBLIGATORIAS)

Ubicación: `core/orchestration/`

### 1. Ciclo de Vida - USAR SIEMPRE

| Alias | Archivo | Propósito | Cuándo Usar |
|-------|---------|-----------|-------------|
| `@TAREA` | `directivas/simco/SIMCO-TAREA.md` | Punto de entrada | **Toda HU/tarea que genera commit** |
| `@CAPVED` | `directivas/principios/PRINCIPIO-CAPVED.md` | Ciclo de 6 fases | Contexto→Análisis→Plan→Validación→Ejecución→Doc |
| `@INICIALIZACION` | `directivas/simco/SIMCO-INICIALIZACION.md` | Bootstrap de agentes | Al iniciar cualquier agente |

### 2. Operaciones Universales

| Alias | Archivo | Propósito |
|-------|---------|-----------|
| `@CREAR` | `directivas/simco/SIMCO-CREAR.md` | Crear cualquier archivo nuevo |
| `@MODIFICAR` | `directivas/simco/SIMCO-MODIFICAR.md` | Modificar archivos existentes |
| `@VALIDAR` | `directivas/simco/SIMCO-VALIDAR.md` | Validar código (build, lint, tests) |
| `@DOCUMENTAR` | `directivas/simco/SIMCO-DOCUMENTAR.md` | Documentar trabajo realizado |
| `@BUSCAR` | `directivas/simco/SIMCO-BUSCAR.md` | Buscar archivos e información |
| `@DELEGAR` | `directivas/simco/SIMCO-DELEGACION.md` | Delegar trabajo a subagentes |

### 3. Catálogo de Funcionalidades

| Alias | Archivo | Propósito |
|-------|---------|-----------|
| `@CATALOG` | `catalog/` | Directorio de funcionalidades reutilizables |
| `@CATALOG_INDEX` | `catalog/CATALOG-INDEX.yml` | Índice machine-readable |
| `@REUTILIZAR` | `directivas/simco/SIMCO-REUTILIZAR.md` | ANTES de implementar algo común |
| `@CONTRIBUIR` | `directivas/simco/SIMCO-CONTRIBUIR-CATALOGO.md` | DESPUÉS de crear algo reutilizable |

**Funcionalidades del catálogo usadas por ERP Suite:**

| Funcionalidad | Uso en la Suite |
|---------------|-----------------|
| `auth` | Autenticación JWT centralizada |
| `multi-tenancy` | Separación por empresa/sucursal (RLS) |
| `session-management` | Gestión de sesiones de usuario |
| `rate-limiting` | Protección de APIs |

### 4. Principios Fundamentales (5)

| Alias | Archivo | Resumen |
|-------|---------|---------|
| `@CAPVED` | `PRINCIPIO-CAPVED.md` | Toda tarea pasa por 6 fases |
| `@DOC_PRIMERO` | `PRINCIPIO-DOC-PRIMERO.md` | Consultar docs/ antes de implementar |
| `@ANTI_DUP` | `PRINCIPIO-ANTI-DUPLICACION.md` | Verificar que no existe antes de crear |
| `@VALIDACION` | `PRINCIPIO-VALIDACION-OBLIGATORIA.md` | Build y lint DEBEN pasar |
| `@TOKENS` | `PRINCIPIO-ECONOMIA-TOKENS.md` | Desglosar tareas grandes |

---

## Directivas por Dominio Técnico

| Alias | Archivo | Tecnologías | Aplica a ERP Suite |
|-------|---------|-------------|-------------------|
| `@OP_DDL` | `SIMCO-DDL.md` | PostgreSQL, SQL | **SÍ** - 7 schemas |
| `@OP_BACKEND` | `SIMCO-BACKEND.md` | Express, TypeORM | **SÍ** - erp-core/backend |
| `@OP_FRONTEND` | `SIMCO-FRONTEND.md` | React, TypeScript, Vite | **SÍ** - erp-core/frontend |
| `@OP_MOBILE` | `SIMCO-MOBILE.md` | React Native | **SÍ** - mobile app |
| `@OP_ML` | `SIMCO-ML.md` | Python, FastAPI, ML/AI | NO |

---

## Directivas de Niveles y Propagación

| Alias | Archivo | Propósito |
|-------|---------|-----------|
| `@NIVELES` | `SIMCO-NIVELES.md` | Identificar nivel jerárquico |
| `@PROPAGACION` | `SIMCO-PROPAGACION.md` | Propagar cambios a niveles superiores |
| `@ALINEACION` | `SIMCO-ALINEACION.md` | Validar alineación DDL↔Entity↔DTO |
| `@DECISION_MATRIZ` | `SIMCO-DECISION-MATRIZ.md` | Decidir qué directiva usar |

---

## Patrones Heredados (RECOMENDADOS)

Ubicación: `core/orchestration/patrones/`

| Patrón | Uso en ERP Suite |
|--------|------------------|
| `MAPEO-TIPOS-DDL-TYPESCRIPT.md` | PostgreSQL ↔ TypeORM entities |
| `PATRON-VALIDACION.md` | Zod + class-validator |
| `PATRON-EXCEPTION-HANDLING.md` | HttpException + filtros globales |
| `PATRON-TESTING.md` | Jest + Supertest |
| `PATRON-LOGGING.md` | Winston estructurado |
| `PATRON-CONFIGURACION.md` | dotenv + validación |
| `PATRON-SEGURIDAD.md` | JWT, RBAC, RLS, Helmet |
| `PATRON-PERFORMANCE.md` | Query optimization, caching |
| `PATRON-TRANSACCIONES.md` | TypeORM QueryRunner |
| `ANTIPATRONES.md` | Lo que NUNCA hacer |
| `NOMENCLATURA-UNIFICADA.md` | snake_case BD, camelCase TS |

---

## Directivas de Documentación (SIMCO v3.7)

Ubicación: `workspace/orchestration/directivas/simco/`

**Directivas de estandarización de documentación:**

| Alias | Directiva | Propósito | Aplica |
|-------|-----------|-----------|--------|
| `@DOC_PROYECTO` | `SIMCO-DOCUMENTACION-PROYECTO.md` | Estructura base de documentación | **SÍ** |
| `@NOMENCLATURA` | `SIMCO-NOMENCLATURA.md` | Convenciones de nomenclatura | **SÍ** |
| `@ESTRUCTURA_DOCS` | `SIMCO-ESTRUCTURA-DOCS.md` | Estructura interna de documentos | **SÍ** |
| `@INVENTARIOS` | `SIMCO-INVENTARIOS.md` | Estándares de inventarios YAML | **SÍ** |
| `@TESTING` | `SIMCO-TESTING.md` | Cobertura y estándares de testing | **SÍ** |
| `@MIGRACIONES` | `SIMCO-MIGRACIONES-BD.md` | Migraciones y DDL | **SÍ** |
| `@INTEGRACIONES` | `SIMCO-INTEGRACIONES-EXTERNAS.md` | Documentación de integraciones | **SÍ** |

### Checklists Asociados

| Alias | Checklist | Items |
|-------|-----------|-------|
| `@CHK_DOCUMENTACION` | `CHECKLIST-DOCUMENTACION-PROYECTO.md` | 44 |
| `@CHK_INVENTARIOS` | `CHECKLIST-INVENTARIOS.md` | 63 |
| `@CHK_NOMENCLATURA` | `CHECKLIST-NOMENCLATURA.md` | 40 |

### Templates Disponibles

| Alias | Template | Uso |
|-------|----------|-----|
| `@TPL_INVENTARIO` | `TEMPLATE-INVENTARIO-PROYECTO.md` | Crear inventarios YAML |
| `@TPL_INTEGRACION` | `TEMPLATE-INTEGRACION-EXTERNA.md` | Documentar integraciones |
| `@TPL_MODULO_ESTANDAR` | `TEMPLATE-MODULO-ESTANDAR.md` | Documentar módulos |

---

## Directivas de Mantenimiento de Documentación (SIMCO v3.8)

Ubicación: `workspace/orchestration/directivas/simco/`

**Directivas de mantenimiento, purga y sincronización:**

| Alias | Directiva | Propósito | Aplica |
|-------|-----------|-----------|--------|
| `@MANTENIMIENTO_DOCS` | `SIMCO-MANTENIMIENTO-DOCUMENTACION.md` | Ciclo de mantenimiento, purga y deprecación | **SÍ** |
| `@SYNC_BD` | `SIMCO-SINCRONIZACION-BD.md` | Sincronización BD ↔ Código ↔ Docs | **SÍ** |

### Checklists de Mantenimiento

| Alias | Checklist | Items |
|-------|-----------|-------|
| `@CHK_MANTENIMIENTO` | `CHECKLIST-MANTENIMIENTO-DOCS.md` | 80 |
| `@CHK_SYNC_BD` | `CHECKLIST-SINCRONIZACION-BD.md` | 70 |

### Templates y Perfiles

| Alias | Archivo | Uso |
|-------|---------|-----|
| `@TPL_DEPRECACION` | `TEMPLATE-DEPRECACION.md` | Marcar documentos como deprecados |
| `@PERFIL_DOC_MAINT` | `PERFIL-DOCUMENTATION-MAINTAINER.md` | Perfil especializado en mantenimiento |

### Cuándo Usar

| Evento | Acción |
|--------|--------|
| Tarea completada (código) | `@MANTENIMIENTO_DOCS` nivel básico |
| Cambio en DDL | `@SYNC_BD` + `@CHK_SYNC_BD` |
| Fin de sprint/fase | `@CHK_MANTENIMIENTO` completo |
| Deprecar documentos | `@TPL_DEPRECACION` |

**IMPORTANTE para Suite:** Estos estándares aplican a todos los productos y verticales.

---

## Impactos y Dependencias

| Documento | Consultar Cuando |
|-----------|------------------|
| `IMPACTO-CAMBIOS-DDL.md` | Modificar schema de BD |
| `IMPACTO-CAMBIOS-BACKEND.md` | Modificar servicios/controllers |
| `IMPACTO-CAMBIOS-ENTITY.md` | Modificar entities TypeORM |
| `IMPACTO-CAMBIOS-API.md` | Modificar endpoints REST |
| `MATRIZ-DEPENDENCIAS.md` | Ver cascada completa |

---

## Perfiles de Agentes para ERP Suite

### Técnicos (más usados)
| Perfil | Especialización | Frecuencia |
|--------|-----------------|------------|
| `PERFIL-DATABASE.md` | PostgreSQL, DDL, RLS | Alta |
| `PERFIL-BACKEND.md` | Express, TypeORM | Alta |
| `PERFIL-FRONTEND.md` | React, TypeScript | Alta |
| `PERFIL-MOBILE-AGENT.md` | React Native | Media |

### Coordinación
| Perfil | Especialización |
|--------|-----------------|
| `PERFIL-ORQUESTADOR.md` | Coordinación multi-vertical |
| `PERFIL-ARCHITECTURE-ANALYST.md` | Decisiones de arquitectura |

### Calidad
| Perfil | Especialización |
|--------|-----------------|
| `PERFIL-CODE-REVIEWER.md` | Revisión de código |
| `PERFIL-BUG-FIXER.md` | Corrección de bugs |

---

## Directivas Específicas de ERP Suite

Ubicación: `./directivas/` (este proyecto)

| Directiva Local | Extiende | Propósito Específico |
|-----------------|----------|---------------------|
| `DIRECTIVA-MULTI-TENANT.md` | `@OP_DDL`, `@PATRON-SEGURIDAD` | RLS por constructora_id |
| `DIRECTIVA-HERENCIA-VERTICALES.md` | `@NIVELES` | Cómo verticales extienden core |
| `DIRECTIVA-EXTENSION-MODULOS.md` | `@CREAR` | Patrones para extender módulos |

---

## Variables de Contexto CCA

```yaml
# Variables para resolver en ALIASES y templates
PROJECT_NAME: "erp-suite"
PROJECT_LEVEL: "SUITE"
PROJECT_ROOT: "./"

# Rutas específicas
DB_DDL_PATH: "apps/erp-core/database/ddl"
BACKEND_ROOT: "apps/erp-core/backend"
FRONTEND_ROOT: "apps/erp-core/frontend"
DOCS_ROOT: "docs"

# Inventarios
MASTER_INVENTORY: "orchestration/inventarios/MASTER_INVENTORY.yml"

# Multi-tenant
TENANT_COLUMN: "constructora_id"
RLS_CONTEXT: "app.current_constructora_id"
```

---

## Mapeo: Directivas Antiguas → SIMCO

| Directiva Antigua | Reemplazada Por | Alias |
|-------------------|-----------------|-------|
| `DIRECTIVA-FLUJO-5-FASES.md` | `SIMCO-TAREA.md` + `PRINCIPIO-CAPVED.md` | @TAREA, @CAPVED |
| `DIRECTIVA-VALIDACION-SUBAGENTES.md` | `SIMCO-VALIDAR.md` | @VALIDAR |
| `POLITICAS-USO-AGENTES.md` | `SIMCO-DELEGACION.md` | @DELEGAR |
| `DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md` | `SIMCO-DOCUMENTAR.md` | @DOCUMENTAR |
| `DIRECTIVA-CALIDAD-CODIGO.md` | `patrones/ANTIPATRONES.md` | @PATRONES |
| `DIRECTIVA-DISENO-BASE-DATOS.md` | `SIMCO-DDL.md` | @OP_DDL |
| `ESTANDARES-API-REST-GENERICO.md` | `SIMCO-BACKEND.md` | @OP_BACKEND |

---

## Flujo de Trabajo para Subagentes

Al invocar un subagente para trabajar en ERP Suite:

```yaml
CONTEXTO_CCA:
  nivel: SUITE
  proyecto: erp-suite

DIRECTIVAS_A_CARGAR:
  core:
    - @TAREA           # Punto de entrada
    - @CAPVED          # Ciclo de vida
    - @INICIALIZACION  # Bootstrap
  operacion:
    - @OP_DDL          # Si trabaja con BD
    - @OP_BACKEND      # Si trabaja con API
    - @OP_FRONTEND     # Si trabaja con UI
  patrones:
    - @PATRON-SEGURIDAD    # Multi-tenant obligatorio
    - @PATRON-VALIDACION   # Zod + class-validator
  suite:
    - ./directivas/DIRECTIVA-MULTI-TENANT.md

INVENTARIO:
  - orchestration/inventarios/MASTER_INVENTORY.yml

DOCS_VALIDACION:
  - docs/verticales/{vertical}/
```

---

## Schemas de Base de Datos (7)

| Schema | Descripción | Directiva Aplicable |
|--------|-------------|---------------------|
| `auth_management` | Autenticación, usuarios, roles | @OP_DDL + @CATALOG(auth) |
| `project_management` | Proyectos, desarrollos, fases | @OP_DDL |
| `financial_management` | Presupuestos, estimaciones | @OP_DDL |
| `purchasing_management` | Compras, proveedores | @OP_DDL |
| `construction_management` | Avances, recursos | @OP_DDL |
| `quality_management` | Inspecciones, calidad | @OP_DDL |
| `infonavit_management` | Integración INFONAVIT | @OP_DDL |

---

## Verticales y Herencia

| Vertical | Nivel | Hereda De | Estado |
|----------|-------|-----------|--------|
| **erp-core** | 2 | erp-suite | 60% |
| **construccion** | 3 | erp-core | 35% |
| **vidrio-templado** | 3 | erp-core | 0% |
| **mecanicas-diesel** | 3 | erp-core | 0% |
| **retail** | 3 | erp-core | 0% |
| **clinicas** | 3 | erp-core | 0% |

Cada vertical DEBE tener su propio `HERENCIA-SIMCO.md` que extienda este.

---

## Propagacion de Mejoras

Este proyecto participa en el sistema de propagacion de mejoras de NEXUS.

### Modulos Base Usados

| Modulo | Version | Estado |
|--------|---------|--------|
| auth-session-based | 1.0.0 | Al dia |

Ver estado completo: `shared/knowledge-base/TRAZABILIDAD-PROYECTOS.yml`

### Recibir Propagaciones

Como SUITE, las propagaciones se manejan a traves de:
1. erp-core (modulos compartidos)
2. Verticales individuales

Ver directiva completa: @PROPAGACION

---

**Sistema:** SIMCO v3.8.0 + CAPVED + CCA Protocol + Estándares Documentación + Mantenimiento Docs
**Nivel:** SUITE (1)
**Última actualización:** 2026-01-10