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

Herencia SIMCO - ERP Core

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 Core - Núcleo del Sistema ERP
Nivel	SUITE_CORE (Nivel 2)
Padre	erp-suite
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/       ← PADRE DIRECTO
            │
            └── Nivel 2: erp-core/orchestration/ ← ESTE PROYECTO
                    │
                    └── Nivel 3: verticales/*/orchestration/
                        ├── construccion     (hereda de aquí)
                        ├── vidrio-templado  (hereda de aquí)
                        ├── mecanicas-diesel (hereda de aquí)
                        ├── retail           (hereda de aquí)
                        └── clinicas         (hereda de aquí)

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

Responsabilidad: ERP Core provee el 60-70% del código base que las verticales extienden.

---

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 implementadas en ERP Core:

Funcionalidad	Estado	Notas
auth	Implementada	JWT + bcryptjs
multi-tenancy	Implementada	RLS por constructora_id
session-management	Implementada	Tokens de sesión
rate-limiting	Implementada	express-rate-limit

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 Core
@OP_DDL	SIMCO-DDL.md	PostgreSQL, SQL	SÍ - Schemas base
@OP_BACKEND	SIMCO-BACKEND.md	Express, TypeORM	SÍ - API principal
@OP_FRONTEND	SIMCO-FRONTEND.md	React, TypeScript	SÍ - UI base
@OP_MOBILE	SIMCO-MOBILE.md	React Native	SÍ - App móvil
@OP_ML	SIMCO-ML.md	Python, FastAPI	NO

---

Directivas de Documentación (SIMCO v3.7)

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

Nuevas directivas agregadas en v3.7 para 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 (MGN-, RF-, ET-)	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 (Odoo)	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 (Odoo connector)
@TPL_MODULO_ESTANDAR	TEMPLATE-MODULO-ESTANDAR.md	Documentar módulos base

IMPORTANTE para ERP Core: Estas directivas aplican también a todas las verticales.

---

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

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

Nuevas directivas agregadas en v3.8 para mantenimiento, purga y sincronización de documentació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 ERP Core: Cambios DDL en core DEBEN ejecutar @SYNC_BD y propagar a verticales.

---

Patrones Heredados (OBLIGATORIOS para ERP Core)

Ubicación: core/orchestration/patrones/

Patrón	Uso Obligatorio	Notas
MAPEO-TIPOS-DDL-TYPESCRIPT.md	SÍ	Mapeo consistente BD↔TypeScript
PATRON-VALIDACION.md	SÍ	Zod + class-validator en DTOs
PATRON-EXCEPTION-HANDLING.md	SÍ	HttpException estandarizado
PATRON-TESTING.md	SÍ	Jest + cobertura mínima 80%
PATRON-LOGGING.md	SÍ	Winston con correlation IDs
PATRON-CONFIGURACION.md	SÍ	Validación de env vars
PATRON-SEGURIDAD.md	SÍ	OWASP Top 10
PATRON-PERFORMANCE.md	Recomendado	Optimización de queries
PATRON-TRANSACCIONES.md	SÍ	TypeORM QueryRunner
ANTIPATRONES.md	SÍ	Evitar siempre
NOMENCLATURA-UNIFICADA.md	SÍ	Consistencia obligatoria

---

Impactos y Dependencias

Documento	Consultar Cuando
IMPACTO-CAMBIOS-DDL.md	Modificar schema base
IMPACTO-CAMBIOS-BACKEND.md	Modificar servicios core
IMPACTO-CAMBIOS-ENTITY.md	Modificar entities base
IMPACTO-CAMBIOS-API.md	Modificar endpoints compartidos
MATRIZ-DEPENDENCIAS.md	Ver impacto en verticales

IMPORTANTE: Cambios en ERP Core impactan a TODAS las verticales.

---

Directivas Heredadas de ERP Suite (Nivel 1)

Ubicación: projects/erp-suite/orchestration/

Directiva Suite	Propósito	Aplicación
HERENCIA-SIMCO.md	Configuración SIMCO para suite	Heredar configuración
Directivas multi-tenant	RLS por constructora_id	Toda query

---

Directivas Específicas de ERP Core

Ubicación: ./directivas/

Directivas ACTIVAS

Directiva Local	Extiende	Propósito
DIRECTIVA-MULTI-TENANT.md	@PATRON-SEGURIDAD	RLS obligatorio por tenant
DIRECTIVA-EXTENSION-VERTICALES.md	@NIVELES	Cómo verticales extienden core
DIRECTIVA-DOCUMENTACION-PRE-DESARROLLO.md	@DOC_PRIMERO	Docs ANTES de código
DIRECTIVA-PATRONES-ODOO.md	@PATRONES	Patrones de diseño ERP

Directivas PENDIENTES (por crear con SIMCO)

Directiva	Extiende	Propósito
DIRECTIVA-HERENCIA-MODULOS.md	@CREAR	Herencia de módulos base
ESTANDARES-API-REST-GENERICO.md	@OP_BACKEND	APIs RESTful estándar

---

Variables de Contexto CCA

# Variables para resolver en ALIASES y templates
PROJECT_NAME: "erp-core"
PROJECT_LEVEL: "SUITE_CORE"
PROJECT_ROOT: "./"
PARENT_PROJECT: "erp-suite"

# Rutas específicas
DB_DDL_PATH: "database/ddl"
BACKEND_ROOT: "backend/src"
FRONTEND_ROOT: "frontend/src"
DOCS_ROOT: "./docs/"

# Stack
BACKEND_FRAMEWORK: "Express.js"
ORM: "TypeORM"
FRONTEND_FRAMEWORK: "React"
BUILD_TOOL: "Vite"

# Inventarios
MASTER_INVENTORY: "orchestration/inventarios/MASTER_INVENTORY.yml"
DATABASE_INVENTORY: "orchestration/inventarios/DATABASE_INVENTORY.yml"
BACKEND_INVENTORY: "orchestration/inventarios/BACKEND_INVENTORY.yml"
FRONTEND_INVENTORY: "orchestration/inventarios/FRONTEND_INVENTORY.yml"

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

---

Perfiles de Agentes más usados en ERP Core

Perfil	Especialización	Frecuencia
PERFIL-DATABASE.md	Schemas base, RLS	Alta
PERFIL-BACKEND.md	Servicios, Controllers	Alta
PERFIL-FRONTEND.md	Componentes React	Alta
PERFIL-ARCHITECTURE-ANALYST.md	Decisiones de arquitectura	Media
PERFIL-CODE-REVIEWER.md	Revisión de código	Media

---

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

---

Módulos Base de ERP Core

Módulo	Descripción	Extensible
auth	Autenticación JWT	Sí
users	Gestión de usuarios	Sí
roles	RBAC	Sí
companies	Multi-empresa	Sí
branches	Sucursales	Sí
catalogs	Catálogos base	Sí
audit	Auditoría	No (core only)

Las verticales EXTIENDEN estos módulos, NUNCA los modifican directamente.

---

Flujo de Trabajo para Desarrollo en ERP Core

# PASO 1: Cargar contexto (CCA)
CARGAR:
  - @TAREA
  - @CAPVED
  - @INICIALIZACION
  - ../erp-suite/HERENCIA-SIMCO.md  # Contexto padre

# PASO 2: Verificar catálogo
VERIFICAR:
  - @CATALOG_INDEX  # ¿Existe funcionalidad similar?
  - @REUTILIZAR     # Si existe, reutilizar

# PASO 3: Seleccionar operación
OPERACION:
  - @OP_DDL         # Si es base de datos
  - @OP_BACKEND     # Si es API
  - @OP_FRONTEND    # Si es UI

# PASO 4: Aplicar patrones
PATRONES:
  - @PATRON-VALIDACION
  - @PATRON-EXCEPTION-HANDLING
  - @PATRON-SEGURIDAD  # Multi-tenant obligatorio

# PASO 5: Validar impactos
IMPACTOS:
  - @MATRIZ-DEPENDENCIAS  # Impacto en verticales

# PASO 6: Documentar y propagar
CIERRE:
  - @DOCUMENTAR
  - @PROPAGACION  # Notificar a verticales si aplica

---

Responsabilidades como SUITE_CORE

1. Proveer módulos base que las verticales extienden
2. Definir interfaces que las verticales implementan
3. NO contener lógica de negocio específica de verticales
4. Mantener compatibilidad con todas las verticales
5. Documentar puntos de extensión claramente

---

Propagacion de Mejoras

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

Modulos Base Usados

Modulo	Version	Estado
auth-jwt-nestjs	2.1.0	Al dia
auth-multi-tenant	2.0.0	Al dia
users-roles-permissions	2.0.0	Al dia
users-multi-tenant	2.0.0	Al dia
ui-admin-dashboard	2.0.0	Al dia
ui-data-tables	2.0.0	Al dia
api-filtering-sorting	1.2.0	Al dia
db-audit-trail	1.5.0	Al dia
db-multi-tenant-schema	2.0.0	Al dia
integration-odoo-connector	1.5.0	Al dia

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

Recibir Propagaciones

1. Se crea una tarea de propagacion
2. Evaluar si la mejora aplica a este proyecto
3. IMPORTANTE: Evaluar impacto en verticales dependientes
4. Implementar cambios siguiendo guia de migracion
5. Propagar a verticales si aplica
6. Actualizar esta tabla con nueva version

Ver directiva completa: @PROPAGACION

Propagar Mejoras desde Este Proyecto

./devtools/scripts/propagation/propagate-module-update.sh <modulo> <version> erp-core

Nota: Como SUITE_CORE, las mejoras aqui pueden requerir propagacion a verticales.

---

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