diff --git a/database b/database index afa4f1a..6235880 160000 --- a/database +++ b/database @@ -1 +1 @@ -Subproject commit afa4f1a6fcb4a12c8e1eed7112972a5323cdad6e +Subproject commit 6235880380d02c25ddca9e4f10cc79090c1d72e1 diff --git a/orchestration/directivas/principios/PRINCIPIO-ANTI-DUPLICACION.md b/orchestration/directivas/principios/PRINCIPIO-ANTI-DUPLICACION.md new file mode 100644 index 0000000..6a10a93 --- /dev/null +++ b/orchestration/directivas/principios/PRINCIPIO-ANTI-DUPLICACION.md @@ -0,0 +1,287 @@ +# PRINCIPIO: ANTI-DUPLICACIÓN + +**Versión:** 1.0.0 +**Fecha:** 2025-12-08 +**Tipo:** Principio Fundamental - HERENCIA OBLIGATORIA +**Aplica a:** TODOS los agentes sin excepción + +--- + +## DECLARACIÓN DEL PRINCIPIO + +``` +╔══════════════════════════════════════════════════════════════════════╗ +║ ║ +║ ANTES DE CREAR, VERIFICAR QUE NO EXISTE ║ +║ ║ +║ "Un duplicado creado es tiempo perdido y confusión garantizada." ║ +║ "2 minutos de verificación ahorran horas de corrección." ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## REGLA DE ORO + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ │ +│ NUNCA crear un objeto (tabla, entity, componente, etc.) │ +│ sin antes verificar que NO existe algo igual o similar. │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## PROCESO DE VERIFICACIÓN + +### Paso 0: Consultar Catálogo de Funcionalidades (NUEVO - OBLIGATORIO) + +```bash +# 🆕 PRIMERO: Verificar si existe funcionalidad en catálogo global +grep -i "{funcionalidad}" @CATALOG_INDEX + +# Funcionalidades comunes ya catalogadas: +# - auth (login, registro, JWT) +# - session-management (sesiones, dispositivos) +# - rate-limiting (throttle, 429) +# - notifications (email, push) +# - multi-tenancy (tenant, RLS) +# - feature-flags (toggles) +# - websocket (realtime) +# - payments (stripe) +``` + +**Si encuentra en @CATALOG:** +``` +✅ USAR CÓDIGO DEL CATÁLOGO +1. Ir a @CATALOG/{funcionalidad}/ +2. Leer README.md (descripción y trade-offs) +3. Seguir IMPLEMENTATION.md (pasos) +4. Copiar _reference/ (código base) +5. Adaptar configuración al proyecto + +Ver: @REUTILIZAR (SIMCO-REUTILIZAR.md) +``` + +### Paso 1: Consultar Inventario del Proyecto +```bash +# Buscar en inventario maestro +grep -i "{nombre}" @INVENTORY + +# Buscar en inventario específico +grep -i "{nombre}" @INV_DB # Para database +grep -i "{nombre}" @INV_BE # Para backend +grep -i "{nombre}" @INV_FE # Para frontend +``` + +### Paso 2: Buscar en Código +```bash +# Buscar archivos con nombre similar +find apps/ -name "*{nombre}*" -type f + +# Buscar definiciones en código +grep -rn "CREATE TABLE.*{nombre}" apps/ +grep -rn "class {Nombre}" apps/ +grep -rn "export.*{Nombre}" apps/ +``` + +### Paso 3: Evaluar Resultado + +| Resultado | Acción | +|-----------|--------| +| Existe en @CATALOG | ✅ REUTILIZAR del catálogo (ver @REUTILIZAR) | +| No encontrado | ✅ Proceder a crear | +| Encontrado idéntico | 🛑 DETENER - No crear, usar existente | +| Encontrado similar | ⚠️ PREGUNTAR - ¿Modificar existente o crear diferente? | + +--- + +## QUÉ VERIFICAR POR TIPO + +### Database (DDL) +```bash +# Verificar tabla +grep -rn "CREATE TABLE.*{nombre}" @DDL_ROOT +grep -i "{nombre}" @INV_DB + +# Verificar schema +grep -rn "CREATE SCHEMA.*{nombre}" @DDL_ROOT + +# Verificar función +grep -rn "CREATE.*FUNCTION.*{nombre}" @DDL_ROOT +``` + +### Backend (NestJS) +```bash +# Verificar entity +find @BACKEND -name "*{nombre}*.entity.ts" +grep -rn "class {Nombre}Entity" @BACKEND + +# Verificar service +find @BACKEND -name "*{nombre}*.service.ts" +grep -rn "class {Nombre}Service" @BACKEND + +# Verificar controller +find @BACKEND -name "*{nombre}*.controller.ts" +``` + +### Frontend (React) +```bash +# Verificar componente +find @FRONTEND -name "*{Nombre}*.tsx" +grep -rn "export.*{Nombre}" @FRONTEND_ROOT + +# Verificar hook +find @FRONTEND -name "use{Nombre}*.ts" + +# Verificar type +grep -rn "interface {Nombre}\|type {Nombre}" @FRONTEND_ROOT +``` + +--- + +## SI ENCUENTRAS DUPLICADO + +### Duplicado Exacto +```markdown +🛑 DETENER INMEDIATAMENTE + +El objeto `{nombre}` YA EXISTE: +- **Ubicación:** {ruta} +- **Inventario:** {línea en inventario} +- **Estado:** {estado} + +**Acción:** Usar el existente, NO crear nuevo. + +**Si necesitas modificarlo:** +Ver @MODIFICAR (SIMCO-MODIFICAR.md) +``` + +### Objeto Similar +```markdown +⚠️ OBJETO SIMILAR ENCONTRADO + +Encontré `{nombre_similar}` que podría ser lo mismo: +- **Ubicación:** {ruta} +- **Propósito:** {descripción} + +**Preguntas a resolver:** +1. ¿Es el mismo objeto con diferente nombre? +2. ¿Debo modificar el existente? +3. ¿Son diferentes y debo crear con otro nombre? + +ESPERAR CLARIFICACIÓN antes de proceder. +``` + +--- + +## CONSECUENCIAS DE DUPLICAR + +``` +❌ Confusión sobre cuál usar + → Diferentes partes del código usan diferentes versiones + +❌ Mantenimiento duplicado + → Cambios deben hacerse en múltiples lugares + +❌ Bugs por inconsistencia + → Un objeto se actualiza, el duplicado no + +❌ Inventarios incorrectos + → Estado del proyecto confuso + +❌ Tiempo perdido + → Trabajo que hay que deshacer +``` + +--- + +## PREVENCIÓN PROACTIVA + +### Al Planificar +```markdown +ANTES de diseñar nuevo objeto: +1. [ ] Busqué en inventarios +2. [ ] Busqué en código +3. [ ] Confirmé que no existe +``` + +### Al Crear +```markdown +DURANTE creación de objeto: +1. [ ] Nombre no colisiona con existente +2. [ ] Ubicación es única +3. [ ] Propósito no está cubierto por otro objeto +``` + +### Al Completar +```markdown +DESPUÉS de crear: +1. [ ] Actualicé inventario +2. [ ] No hay advertencias de duplicados +``` + +--- + +## CASOS ESPECIALES + +### ¿Qué pasa si necesito algo PARECIDO pero diferente? + +```markdown +Ejemplo: Existe `UserEntity`, necesito `AdminUserEntity` + +Verificar: +1. ¿Es una extensión? → Heredar/extender existente +2. ¿Es un caso especial? → Agregar campo al existente +3. ¿Es realmente diferente? → Crear nuevo con nombre claro + +Nombrar claramente: +- ❌ `User2Entity` (confuso) +- ✅ `AdminUserEntity` (claro y diferenciado) +``` + +### ¿Qué pasa si el existente está mal? + +```markdown +Si el objeto existente tiene problemas: +1. Documentar los problemas +2. Decidir: ¿Corregir existente o reemplazar? +3. Si reemplazar: eliminar viejo completamente +4. NUNCA tener ambos coexistiendo +``` + +--- + +## CHECKLIST RÁPIDO + +``` +Antes de crear CUALQUIER objeto: +[ ] 🆕 Busqué funcionalidad en @CATALOG_INDEX (PRIMERO) +[ ] Busqué "{nombre}" en @INVENTORY +[ ] Busqué archivos con find +[ ] Busqué definiciones con grep +[ ] Confirmé que NO existe en catálogo NI en proyecto +[ ] Si existe en catálogo, seguí @REUTILIZAR +[ ] Si existe similar, pregunté qué hacer +``` + +--- + +## REFERENCIAS SIMCO + +- **@CATALOG** - Catálogo de funcionalidades reutilizables (CONSULTAR PRIMERO) +- **@REUTILIZAR** - Proceso para reutilizar del catálogo +- **@CREAR** - Proceso completo de creación (incluye verificación) +- **@BUSCAR** - Estrategias de búsqueda +- **@DOCUMENTAR** - Actualización de inventarios + +--- + +**Este principio es OBLIGATORIO y NO puede ser ignorado por ningún agente.** + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Principio Fundamental diff --git a/orchestration/directivas/principios/PRINCIPIO-CAPVED.md b/orchestration/directivas/principios/PRINCIPIO-CAPVED.md new file mode 100644 index 0000000..b0d1532 --- /dev/null +++ b/orchestration/directivas/principios/PRINCIPIO-CAPVED.md @@ -0,0 +1,384 @@ +--- +tipo: ssot-normativo +nivel: 3-completo +es_ssot: true +versiones_derivadas: + - docs/30-directivas/CICLO-CAPVED.md (nivel 1 - resumen usuario) + - orchestration/_definitions/protocols/CAPVED-CYCLE.md (nivel 2 - tecnico) +actualizado: 2026-01-16 +--- + +# PRINCIPIO: CAPVED - Ciclo de Vida de Tareas + +**Versión:** 1.0.0 +**Fecha:** 2025-12-08 +**Tipo:** Principio Fundamental - HERENCIA OBLIGATORIA - **SSOT** +**Aplica a:** TODOS los agentes sin excepción +**Alias:** @CAPVED + +--- + +## DECLARACIÓN DEL PRINCIPIO + +``` +╔══════════════════════════════════════════════════════════════════════════════╗ +║ ║ +║ CAPVED: Contexto → Análisis → Planeación → Validación → Ejecución → Doc ║ +║ ║ +║ "Toda tarea que modifica código o documentación DEBE pasar por ║ +║ el ciclo completo CAPVED antes de considerarse Done." ║ +║ ║ +║ "Si aparece trabajo fuera del alcance original, se genera HU nueva." ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## QUÉ ES CAPVED + +CAPVED es un **ciclo de vida obligatorio** para toda Historia de Usuario (HU) o tarea técnica que involucre modificación de código o documentación. Garantiza: + +1. **Trazabilidad completa**: Desde el origen hasta la implementación +2. **Análisis de impacto**: Antes de tocar código +3. **Validación de coherencia**: Plan vs Análisis +4. **Generación controlada**: HUs derivadas para descubrimientos +5. **Documentación actualizada**: Como criterio de Done + +--- + +## LAS 6 FASES DE CAPVED + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ C - CONTEXTO │ +│ • Vincular HU a proyecto/módulo/epic │ +│ • Clasificar tipo: feature | fix | refactor | spike | doc-only │ +│ • Registrar origen: plan-original | descubrimiento | incidencia │ +│ • Cargar documentos SIMCO relevantes │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ ↓ │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ A - ANÁLISIS │ +│ • Comportamiento deseado (perspectiva de negocio) │ +│ • Restricciones: seguridad, performance, UX │ +│ • Objetos impactados: BD, Backend, Frontend, otros proyectos │ +│ • Dependencias con otras HUs (bloquea/bloqueada por) │ +│ • Riesgos identificados │ +│ → SALIDA: Lista de objetos + dependencias + riesgos │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ ↓ │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ P - PLANEACIÓN │ +│ • Desglose en subtareas por dominio (BD, BE, FE, Docs) │ +│ • Orden de ejecución y dependencias │ +│ • Criterios de aceptación por subtarea │ +│ • Plan de pruebas: unitarias, integración, regresión │ +│ • Asignación de agentes/subagentes │ +│ → SALIDA: Plan de ejecución con subtareas asignadas │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ ↓ │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ V - VALIDACIÓN (⚠️ NO DELEGAR - EJECUTAR DIRECTAMENTE) │ +│ • ¿Todo lo detectado en A tiene acción concreta en P? │ +│ • ¿Hay dependencias ocultas sin atender? │ +│ • ¿Criterios de aceptación cubren los riesgos? │ +│ • ¿Hay scope creep? → Registrar y crear HU derivada │ +│ → GATE: Solo pasa a Ejecución si todo cuadra │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ ↓ │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ E - EJECUCIÓN │ +│ • Actualizar docs/ del proyecto PRIMERO │ +│ • Ejecutar subtareas en orden establecido │ +│ • Cada subtarea: código + notas + validación (build/lint) │ +│ • Registrar progreso y desviaciones │ +│ → USAR: SIMCO correspondientes (CREAR, MODIFICAR, DDL, etc.) │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ ↓ │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ D - DOCUMENTACIÓN CONTINUA │ +│ • Actualizar diagramas y modelos de dominio │ +│ • Actualizar especificaciones técnicas (BD, APIs, contratos) │ +│ • Crear/actualizar ADRs si hubo decisiones arquitectónicas │ +│ • Actualizar inventarios (DATABASE, BACKEND, FRONTEND) │ +│ • Actualizar trazas de tareas │ +│ • Registrar HUs derivadas (si se generaron) │ +│ • Registrar lecciones aprendidas │ +│ → GATE: HU NO está Done si documentación no está actualizada │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## CUÁNDO APLICA CAPVED + +### APLICA A (Obligatorio): + +```yaml +Tareas_que_DEBEN_seguir_CAPVED: + - Nuevas features (cualquier tamaño) + - Bug fixes que modifican código + - Refactorizaciones + - Cambios en estructura de BD + - Nuevos endpoints de API + - Nuevos componentes de UI + - Cambios en lógica de negocio + - Integraciones con sistemas externos + - Cualquier tarea que genere commit +``` + +### NO APLICA A (Excepciones): + +```yaml +Tareas_exentas_de_CAPVED_completo: + - Corrección de typos en código (solo E+D) + - Actualización de dependencias menores (solo E+D) + - Tareas puramente exploratorias (solo lectura) + - Consultas de información + - Spikes de investigación sin implementación + +NOTA: Incluso las excepciones DEBEN documentar en trazas +``` + +--- + +## INTEGRACIÓN CON SIMCO + +CAPVED es el **ciclo de vida**, SIMCO son las **operaciones**: + +``` +CAPVED SIMCO +─────── ───── +C - Contexto → SIMCO-INICIALIZACION.md (CCA) +A - Análisis → SIMCO-BUSCAR.md + docs/ +P - Planeación → TEMPLATE-PLAN.md +V - Validación → Checklist CAPVED (este documento) +E - Ejecución → SIMCO-CREAR/MODIFICAR/DDL/BACKEND/FRONTEND +D - Documentación → SIMCO-DOCUMENTAR.md + inventarios + trazas +``` + +### Orden de Lectura para Agentes: + +```yaml +1. SIMCO-INICIALIZACION.md # Bootstrap con CCA +2. PRINCIPIO-CAPVED.md # Este documento (ciclo obligatorio) +3. PRINCIPIO-DOC-PRIMERO.md # Documentación antes de código +4. PRINCIPIO-ANTI-DUPLICACION.md # Verificar antes de crear +5. PRINCIPIO-VALIDACION-OBLIGATORIA.md # Build/lint obligatorios +6. SIMCO-TAREA.md # Proceso detallado CAPVED +7. SIMCO específicos según operación +``` + +--- + +## GENERACIÓN DE HUs DERIVADAS + +### Cuándo Generar HU Nueva: + +```yaml +Generar_HU_derivada_cuando: + # Durante Análisis (A) + - Se detecta bug estructural no relacionado al objetivo + - Se identifica deuda técnica que bloquea + - Se descubre dependencia no documentada + + # Durante Validación (V) + - Hay trabajo detectado fuera del alcance original + - Se requiere refactor previo no planificado + - Se identifica mejora de UX no solicitada + + # Durante Ejecución (E) + - Se encuentra código legacy que debe corregirse + - Se descubre inconsistencia en otra parte del sistema + - Se identifica oportunidad de optimización +``` + +### Proceso de Generación: + +```markdown +1. DETECTAR: Identificar que algo está fuera del alcance +2. REGISTRAR: Documentar en la sección "HUs Derivadas" de la HU actual +3. CREAR: Generar archivo de HU con prefijo DERIVED-{HU-ORIGEN}-{N} +4. VINCULAR: Referenciar la HU origen en la nueva HU +5. PRIORIZAR: Marcar como pendiente para siguiente planificación +6. CONTINUAR: Seguir con la HU original sin desviarse +``` + +### Template de Registro: + +```yaml +HUs_Derivadas: + - id: "DERIVED-HU-001-001" + origen: "HU-001" + tipo: "bug | feature | refactor | deuda-tecnica" + descripcion: "Descripción breve de lo detectado" + detectado_en_fase: "A | V | E" + prioridad_sugerida: "P0 | P1 | P2 | P3" + notas: "Contexto adicional relevante" +``` + +--- + +## CHECKLIST RÁPIDO CAPVED + +### Antes de Iniciar (C): +``` +[ ] HU vinculada a proyecto/módulo/epic +[ ] Tipo clasificado (feature/fix/refactor/spike/doc-only) +[ ] Origen registrado (plan/descubrimiento/incidencia) +[ ] Documentos SIMCO relevantes identificados +``` + +### Antes de Planificar (A completado): +``` +[ ] Comportamiento de negocio entendido +[ ] Objetos impactados listados (todas las capas) +[ ] Dependencias identificadas +[ ] Riesgos documentados +``` + +### Antes de Ejecutar (P+V completados): +``` +[ ] Subtareas definidas por dominio +[ ] Orden de ejecución establecido +[ ] Criterios de aceptación definidos +[ ] Plan vs Análisis validado (todo cubierto) +[ ] Scope creep registrado (si existe) +[ ] HUs derivadas creadas (si aplica) +``` + +### Durante Ejecución (E): +``` +[ ] docs/ actualizado PRIMERO +[ ] Subtareas ejecutadas en orden +[ ] Build/lint pasa por subtarea +[ ] Progreso registrado +``` + +### Antes de Cerrar (D): +``` +[ ] Diagramas/modelos actualizados +[ ] Specs técnicas actualizadas +[ ] ADRs creados (si decisión arquitectónica) +[ ] Inventarios actualizados +[ ] Trazas actualizadas +[ ] HUs derivadas vinculadas +[ ] Lecciones aprendidas registradas +``` + +### GATE DE CIERRE (OBLIGATORIO - @DEF_CHK_POST) + +> **ANTES de declarar una HU/tarea como DONE, ejecutar @DEF_CHK_POST** + +```markdown +## Checklist de Cierre Obligatorio + +### Gobernanza (BLOQUEANTE) +[ ] Carpeta de tarea existe: orchestration/tareas/TASK-{ID}/ +[ ] METADATA.yml completo con fases C, E, D +[ ] _INDEX.yml de tareas actualizado + +### Validaciones Técnicas +[ ] Build pasa (backend y/o frontend) +[ ] Lint pasa +[ ] Tests pasan (si existen) + +### Coherencia Entre Capas +[ ] DDL ↔ Backend verificado +[ ] Backend ↔ Frontend verificado (si aplica) + +### Inventarios +[ ] DATABASE_INVENTORY.yml (si cambió BD) +[ ] BACKEND_INVENTORY.yml (si cambió BE) +[ ] FRONTEND_INVENTORY.yml (si cambió FE) +[ ] MASTER_INVENTORY.yml actualizado + +### Trazas +[ ] Traza de tarea correspondiente actualizada +[ ] PROXIMA-ACCION.md actualizado + +### Propagación +[ ] Evaluado si aplica a otros proyectos +``` + +**SI FALLA CUALQUIER ITEM BLOQUEANTE:** HU permanece EN PROGRESO. + +**REFERENCIA:** `@TRIGGER_CIERRE` - orchestration/directivas/triggers/TRIGGER-CIERRE-TAREA-OBLIGATORIO.md + +--- + +## CONSECUENCIAS DE IGNORAR CAPVED + +``` +❌ Saltar Contexto (C) + → HU sin trazabilidad, trabajo desconectado del plan + +❌ Saltar Análisis (A) + → Impacto no previsto, bugs en otras partes del sistema + +❌ Saltar Planeación (P) + → Ejecución caótica, trabajo rehecho, tiempo perdido + +❌ Saltar Validación (V) + → Scope creep no controlado, trabajo infinito + +❌ Saltar Documentación (D) + → Sistema diverge de docs/, confusión futura, onboarding difícil +``` + +--- + +## LECCIONES APRENDIDAS + +### Registro Obligatorio: + +Al cerrar cada HU, registrar: + +```yaml +Lecciones_Aprendidas: + que_funciono_bien: + - "Descripción de práctica exitosa" + + que_se_puede_mejorar: + - "Descripción de área de mejora" + + para_futuras_HUs_similares: + - "Recomendación específica para HUs del mismo tipo" +``` + +### Ubicación: + +- En el archivo de la HU (sección final) +- Consolidar mensualmente en `orchestration/retrospectivas/` + +--- + +## REFERENCIAS SIMCO + +| Fase CAPVED | SIMCO Relacionados | +|-------------|-------------------| +| C - Contexto | `SIMCO-INICIALIZACION.md`, `CONTEXTO-PROYECTO.md` | +| A - Análisis | `SIMCO-BUSCAR.md`, `TEMPLATE-ANALISIS.md` | +| P - Planeación | `TEMPLATE-PLAN.md`, `SIMCO-DELEGACION.md` | +| V - Validación | `TEMPLATE-VALIDACION.md` | +| E - Ejecución | `SIMCO-CREAR.md`, `SIMCO-MODIFICAR.md`, `SIMCO-DDL.md`, etc. | +| D - Documentación | `SIMCO-DOCUMENTAR.md`, inventarios, trazas | + +--- + +## ALIAS + +```yaml +@CAPVED: core/orchestration/directivas/principios/PRINCIPIO-CAPVED.md +@TAREA: core/orchestration/directivas/simco/SIMCO-TAREA.md +@TPL_CAPVED: core/orchestration/templates/TEMPLATE-TAREA-CAPVED.md +``` + +--- + +**Este principio es OBLIGATORIO y NO puede ser ignorado por ningún agente.** + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO + CAPVED | **Tipo:** Principio Fundamental diff --git a/orchestration/directivas/principios/PRINCIPIO-DOC-PRIMERO.md b/orchestration/directivas/principios/PRINCIPIO-DOC-PRIMERO.md new file mode 100644 index 0000000..769be33 --- /dev/null +++ b/orchestration/directivas/principios/PRINCIPIO-DOC-PRIMERO.md @@ -0,0 +1,190 @@ +# PRINCIPIO: DOCUMENTACIÓN PRIMERO + +**Versión:** 1.0.0 +**Fecha:** 2025-12-08 +**Tipo:** Principio Fundamental - HERENCIA OBLIGATORIA +**Aplica a:** TODOS los agentes sin excepción + +--- + +## DECLARACIÓN DEL PRINCIPIO + +``` +╔══════════════════════════════════════════════════════════════════════╗ +║ ║ +║ DOCUMENTACIÓN PRIMERO, IMPLEMENTACIÓN DESPUÉS ║ +║ ║ +║ "Si no está documentado, no existe." ║ +║ "Si contradice la documentación, está mal." ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## REGLA EN 3 PASOS + +``` +PASO 1: ANTES DE IMPLEMENTAR +───────────────────────────── +Consultar docs/ para entender: +- ¿Qué dice la documentación sobre esto? +- ¿Hay especificaciones o diseños? +- ¿Hay ADRs relacionados? + +PASO 2: SI HAY CAMBIO DE DISEÑO +───────────────────────────── +Actualizar docs/ PRIMERO: +- Documentar el nuevo diseño +- Crear ADR si es decisión arquitectónica +- Actualizar especificaciones + +PASO 3: IMPLEMENTAR +───────────────────────────── +Solo entonces escribir código: +- Seguir lo documentado +- Referenciar docs/ en comentarios si aplica +``` + +--- + +## FLUJO VISUAL + +``` +┌─────────────────────┐ +│ TAREA NUEVA │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ +│ ¿Consulté docs/? │──── NO ────► CONSULTAR DOCS/ PRIMERO +└──────────┬──────────┘ + │ SÍ + ▼ +┌─────────────────────┐ +│ ¿Hay contradicción? │──── SÍ ────► ACTUALIZAR DOCS/ PRIMERO +└──────────┬──────────┘ + │ NO + ▼ +┌─────────────────────┐ +│ ¿Falta documentar? │──── SÍ ────► DOCUMENTAR PRIMERO +└──────────┬──────────┘ + │ NO + ▼ +┌─────────────────────┐ +│ IMPLEMENTAR │ +└─────────────────────┘ +``` + +--- + +## DOCUMENTACIÓN A CONSULTAR + +### Antes de CUALQUIER tarea: +```yaml +Obligatorio: + - docs/00-vision-general/ # Visión y alcance + - docs/95-guias-desarrollo/ # Estándares y convenciones + - docs/97-adr/ # Decisiones arquitectónicas + +Si aplica: + - docs/01-fase-*/ # Especificaciones por fase + - docs/modulos/{modulo}/ # Especificaciones del módulo + - orchestration/inventarios/ # Estado actual del proyecto +``` + +### Para cada tipo de tarea: +```yaml +Database: + - @GUIAS/database/ (si existe) + - @ADR (decisiones de BD) + +Backend: + - @GUIAS_BE/DTO-CONVENTIONS.md + - @GUIAS_BE/API-CONVENTIONS.md + - @ADR + +Frontend: + - @GUIAS_FE/TYPES-CONVENTIONS.md + - @GUIAS_FE/COMPONENT-PATTERNS.md + - @ADR +``` + +--- + +## CUÁNDO ACTUALIZAR DOCS/ PRIMERO + +| Situación | Acción | +|-----------|--------| +| Nueva feature no documentada | Documentar diseño antes de implementar | +| Cambio de arquitectura | Crear ADR antes de implementar | +| Contradicción docs/ vs realidad | Actualizar docs/ (si realidad es correcta) | +| Nueva convención | Documentar en guías antes de usar | +| Nuevo módulo/schema | Documentar estructura antes de crear | + +--- + +## CUÁNDO NO APLICA + +```yaml +Excepciones (no requiere actualizar docs/ primero): + - Bug fixes menores (solo corrección, no cambio de diseño) + - Refactors internos (misma funcionalidad) + - Actualizaciones de dependencias + - Corrección de typos en código + +PERO siempre aplica: + - Consultar docs/ para entender el contexto + - Documentar en traza lo realizado + - Actualizar inventarios si hay cambios estructurales +``` + +--- + +## CONSECUENCIAS DE IGNORAR ESTE PRINCIPIO + +``` +❌ Código que contradice documentación + → Confusión, bugs, deuda técnica + +❌ Features no documentadas + → Nadie sabe qué hace ni por qué + +❌ Implementar sin consultar docs/ + → Duplicados, inconsistencias, trabajo rehecho + +❌ Cambiar arquitectura sin ADR + → Decisiones perdidas, errores repetidos +``` + +--- + +## CHECKLIST RÁPIDO + +``` +Antes de escribir código: +[ ] Consulté docs/ relevantes +[ ] No hay contradicción con lo documentado +[ ] Si hay cambio de diseño, actualicé docs/ primero + +Al terminar: +[ ] Código sigue lo documentado +[ ] Actualicé inventarios +[ ] Documenté en traza +``` + +--- + +## REFERENCIAS SIMCO + +- **@DOCUMENTAR** - Cómo documentar correctamente +- **@VALIDAR** - Validación de coherencia docs/código +- **@BUSCAR** - Cómo encontrar documentación + +--- + +**Este principio es OBLIGATORIO y NO puede ser ignorado por ningún agente.** + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Principio Fundamental diff --git a/orchestration/directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md b/orchestration/directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md new file mode 100644 index 0000000..250a4cc --- /dev/null +++ b/orchestration/directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md @@ -0,0 +1,292 @@ +# PRINCIPIO: ECONOMÍA DE TOKENS + +**Versión:** 1.0.0 +**Fecha:** 2025-12-08 +**Aplica a:** Todos los agentes +**Prioridad:** OBLIGATORIA para evitar errores de context overflow + +--- + +## RESUMEN EJECUTIVO + +> **Los agentes tienen límites de tokens. Excederlos = fallo de tarea.** +> Planificar con economía de tokens = tareas exitosas. +> Tareas grandes sin desglose = error garantizado. + +--- + +## LÍMITES CRÍTICOS + +```yaml +CONTEXTO_MAXIMO: + entrada: ~200,000 tokens # Lo que el agente puede "ver" + salida: ~8,000 tokens # Lo que puede generar por respuesta + recomendado_carga: <50,000 tokens # Para dejar espacio de trabajo + +ARCHIVO_INDIVIDUAL: + maximo_recomendado: 500 líneas (~2,000 tokens) + ideal: 200-300 líneas (~1,000 tokens) + alerta: >400 líneas → considerar división + +PROMPT_DELEGACION: + maximo: 3,000 tokens (~750 líneas de prompt) + recomendado: 1,500 tokens (~375 líneas) + minimo_efectivo: 500 tokens (~125 líneas) +``` + +--- + +## REGLAS DE ECONOMÍA + +### Regla 1: Cargar Solo Lo Necesario + +```yaml +MAL: + - Cargar TODOS los archivos del proyecto + - Leer archivos completos cuando solo necesitas una sección + - Incluir documentación extendida en prompts de delegación + +BIEN: + - Cargar SOLO archivos relevantes para la tarea actual + - Usar SIMCO-QUICK-REFERENCE.md en lugar de _INDEX.md completo + - Referencias a archivos en vez de copiar contenido +``` + +### Regla 2: Desglosar Tareas Grandes + +```yaml +TAREA_GRANDE (>2000 tokens de output esperado): + - Dividir en subtareas independientes + - Cada subtarea = máximo 1 archivo o 1 función + - Secuenciar: crear → validar → siguiente + +EJEMPLO_MALO: + "Crear el módulo completo de usuarios con entity, service, + controller, DTOs, tests, y documentación" + # Esto generará >8000 tokens de salida = ERROR + +EJEMPLO_BUENO: + ST-001: Crear UserEntity alineada con DDL + ST-002: Crear CreateUserDto y UpdateUserDto + ST-003: Crear UserService con CRUD básico + ST-004: Crear UserController con endpoints + ST-005: Ejecutar build + lint + # Cada una <2000 tokens = ÉXITO +``` + +### Regla 3: Prompts de Delegación Concisos + +```yaml +INCLUIR: + - Contexto mínimo necesario (nivel, variables críticas) + - Tarea específica (1 cosa) + - Criterios de aceptación (checklist corto) + - 1-2 archivos de referencia máximo + +NO INCLUIR: + - Historia completa del proyecto + - Documentación extendida + - Múltiples opciones/alternativas + - Código de ejemplo extenso (>50 líneas) +``` + +--- + +## ESTRATEGIAS DE DESGLOSE + +### Por Capa (Vertical) + +```yaml +# En lugar de: "Crear feature de notificaciones" +# Desglosar en: + +ST-001_DATABASE: + tarea: "Crear tabla notifications.notifications" + output_esperado: ~300 tokens (1 archivo DDL) + +ST-002_BACKEND_ENTITY: + tarea: "Crear NotificationEntity" + output_esperado: ~200 tokens (1 archivo) + +ST-003_BACKEND_DTO: + tarea: "Crear DTOs de Notification" + output_esperado: ~300 tokens (2 archivos pequeños) + +ST-004_BACKEND_SERVICE: + tarea: "Crear NotificationService con CRUD" + output_esperado: ~400 tokens (1 archivo) + +ST-005_BACKEND_CONTROLLER: + tarea: "Crear NotificationController con endpoints" + output_esperado: ~350 tokens (1 archivo) + +ST-006_VALIDACION: + tarea: "Ejecutar build + lint backend" + output_esperado: ~100 tokens (comandos) +``` + +### Por Funcionalidad (Horizontal) + +```yaml +# En lugar de: "Implementar autenticación" +# Desglosar en: + +ST-001: Verificar @CATALOG (¿existe auth?) +ST-002: Si existe → usar SIMCO-REUTILIZAR +ST-003: Si no existe → crear esquema auth (DDL) +ST-004: Crear AuthModule básico (register/login) +ST-005: Crear JWT strategy +ST-006: Crear guards +ST-007: Integrar en app.module +ST-008: Validar build + lint +``` + +--- + +## ESTIMACIÓN DE TOKENS + +### Fórmula Rápida + +``` +tokens ≈ caracteres / 4 +tokens ≈ palabras * 1.3 +tokens ≈ líneas * 10 (código promedio) +``` + +### Tabla de Referencia + +| Tipo de Archivo | Líneas Típicas | Tokens Estimados | +|-----------------|----------------|------------------| +| Entity simple | 30-50 | 300-500 | +| Entity con relaciones | 80-120 | 800-1200 | +| DTO | 20-40 | 200-400 | +| Service CRUD | 100-150 | 1000-1500 | +| Controller REST | 80-120 | 800-1200 | +| Tabla DDL | 30-60 | 300-600 | +| Componente React simple | 50-80 | 500-800 | +| Componente React complejo | 150-250 | 1500-2500 | +| Hook | 30-60 | 300-600 | + +--- + +## DETECCIÓN DE PROBLEMAS + +### Señales de Alerta + +```yaml +ANTES_DE_EJECUTAR: + - [ ] ¿La tarea pide crear >3 archivos? → Desglosar + - [ ] ¿El prompt de delegación >1500 tokens? → Reducir + - [ ] ¿Se pide "módulo completo"? → Desglosar por componente + - [ ] ¿Se incluye código de referencia >50 líneas? → Usar referencia a archivo + +DURANTE_EJECUCION: + - [ ] ¿Respuesta truncada? → Tarea muy grande + - [ ] ¿Error de context? → Demasiados archivos cargados + - [ ] ¿Alucinaciones? → Contexto insuficiente o confuso +``` + +### Acciones Correctivas + +```yaml +SI_RESPUESTA_TRUNCADA: + 1. Dividir tarea en 2-3 subtareas + 2. Re-ejecutar cada subtarea por separado + 3. Validar entre subtareas + +SI_ERROR_CONTEXT: + 1. Descargar archivos no esenciales + 2. Usar SIMCO-QUICK-REFERENCE en lugar de _INDEX completo + 3. Referencias en lugar de contenido inline + +SI_ALUCINACIONES: + 1. Verificar que archivos de referencia se cargaron + 2. Incluir más contexto específico (menos genérico) + 3. Ser más explícito en criterios de aceptación +``` + +--- + +## TEMPLATE DE DELEGACIÓN OPTIMIZADO + +```yaml +# PROMPT OPTIMIZADO (~800 tokens) + +## SUBAGENTE: {Tipo} +Nivel: {nivel} | Proyecto: {proyecto} | Ruta: {orchestration_path} + +## TAREA ÚNICA +{Descripción en 1-2 oraciones} + +## ESPECIFICACIÓN +{Solo lo necesario, máximo 10 líneas} + +## REFERENCIA +- Archivo: `{ruta exacta}` (copiar patrón de líneas X-Y) + +## CRITERIOS (máximo 5) +- [ ] {criterio 1} +- [ ] {criterio 2} +- [ ] {criterio 3} + +## VALIDACIÓN +```bash +{1-2 comandos} +``` + +## ENTREGABLES +1. {archivo a crear/modificar} +``` + +--- + +## INTEGRACIÓN CON CAPVED + +### Fase P (Planeación) - Verificar Tokens + +```yaml +ANTES_DE_APROBAR_PLAN: + - [ ] Cada subtarea genera <2000 tokens de output + - [ ] Cada prompt de delegación <1500 tokens + - [ ] No hay subtareas que pidan "módulo completo" + - [ ] Subtareas son independientes (pueden fallar sin afectar otras) +``` + +### Fase E (Ejecución) - Monitorear + +```yaml +DURANTE_EJECUCION: + - Si subtarea falla por tokens → subdividir más + - Si contexto insuficiente → cargar archivo específico + - Si respuesta truncada → dividir y reintentar +``` + +--- + +## MÉTRICAS DE ÉXITO + +```yaml +TAREA_BIEN_DESGLOSADA: + - 0 errores de token overflow + - 0 respuestas truncadas + - Cada subtarea completa en 1 iteración + - Build pasa después de cada subtarea + +DELEGACION_OPTIMA: + - Prompt <1500 tokens + - Respuesta completa sin truncar + - Criterios verificables cumplidos + - Sin re-trabajo por malentendidos +``` + +--- + +## REFERENCIAS + +- **Referencia rápida:** `SIMCO-QUICK-REFERENCE.md` +- **Delegación:** `SIMCO-DELEGACION.md` +- **Desglose de tareas:** `SIMCO-TAREA.md` + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Principio Fundamental diff --git a/orchestration/directivas/principios/PRINCIPIO-NO-ASUMIR.md b/orchestration/directivas/principios/PRINCIPIO-NO-ASUMIR.md new file mode 100644 index 0000000..7def8f3 --- /dev/null +++ b/orchestration/directivas/principios/PRINCIPIO-NO-ASUMIR.md @@ -0,0 +1,361 @@ +# PRINCIPIO: NO ASUMIR + +**Version:** 1.0.0 +**Fecha:** 2025-12-12 +**Tipo:** Principio Fundamental - HERENCIA OBLIGATORIA +**Aplica a:** TODOS los agentes sin excepcion + +--- + +## DECLARACION DEL PRINCIPIO + +``` +╔══════════════════════════════════════════════════════════════════════╗ +║ ║ +║ "Si no esta documentado, NO asumir. PREGUNTAR." ║ +║ ║ +║ Nunca implementar basado en suposiciones. ║ +║ Nunca inventar requisitos. ║ +║ Nunca tomar decisiones de negocio sin autorizacion. ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## REGLA INQUEBRANTABLE + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ │ +│ PROHIBIDO: │ +│ - Asumir valores/comportamientos no documentados │ +│ - Inventar requisitos o especificaciones │ +│ - Tomar decisiones de negocio sin consultar │ +│ - Implementar "lo que parece logico" sin confirmacion │ +│ - Interpretar ambiguedad a favor de una opcion │ +│ - Completar huecos de documentacion con suposiciones │ +│ │ +│ OBLIGATORIO: │ +│ - Detener trabajo cuando falta informacion critica │ +│ - Documentar la pregunta claramente │ +│ - Escalar al Product Owner │ +│ - Esperar respuesta antes de continuar │ +│ - Documentar la decision antes de implementar │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## POR QUE ESTE PRINCIPIO + +```yaml +problema: + - Implementaciones basadas en suposiciones causan retrabajo + - Asunciones incorrectas generan bugs de negocio + - Decisiones no autorizadas crean deuda tecnica + - Interpretaciones personales divergen del objetivo real + +consecuencias_de_asumir: + - Codigo que no cumple requisitos reales + - Retrabajo costoso cuando se descubre la asuncion incorrecta + - Perdida de confianza del cliente/PO + - Documentacion desalineada con implementacion + - Bugs dificiles de rastrear (parecen funcionar pero no son correctos) + +beneficios_de_preguntar: + - Implementacion correcta desde el inicio + - Documentacion completa y precisa + - Menos retrabajo + - Mayor confianza del equipo + - Decisiones respaldadas por autoridad correcta +``` + +--- + +## CUANDO APLICA ESTE PRINCIPIO + +### Casos que REQUIEREN Escalamiento + +```yaml +informacion_faltante: + - Tabla mencionada sin definicion de columnas + - Endpoint sin especificacion de payload + - Pagina sin definicion de componentes + - Regla de negocio incompleta + - Valores de enum no especificados + - Validaciones no documentadas + - Comportamiento de error no definido + - Limites/umbrales no especificados + +ambiguedad: + - Requisito interpretable de multiples formas + - Contradiccion entre documentos + - Alcance no claramente definido + - Criterios de aceptacion vagos + - Casos edge no cubiertos + +decisiones_de_negocio: + - Cambio que afecta UX + - Modificacion de flujos existentes + - Nuevas restricciones + - Priorizacion entre alternativas + - Trade-offs con impacto en usuario +``` + +### Casos que NO Requieren Escalamiento + +```yaml +decisiones_tecnicas_puras: + - Nombre de variable interna + - Estructura de codigo (si no afecta API) + - Optimizaciones de rendimiento + - Refactorizaciones internas + → Consultar Architecture-Analyst si hay duda + +implementacion_clara: + - Documentacion existe y es clara + - No hay ambiguedad + - Comportamiento esta especificado + → Proceder con implementacion + +estandares_definidos: + - Nomenclatura definida en directivas + - Patrones definidos en SIMCO + - Convenciones del proyecto + → Seguir lo establecido +``` + +--- + +## COMO APLICAR ESTE PRINCIPIO + +### Paso 1: Buscar Exhaustivamente + +```yaml +ANTES_de_escalar: + buscar_en: + - docs/01-requerimientos/ + - docs/02-especificaciones-tecnicas/ + - docs/97-adr/ + - orchestration/inventarios/ + - Codigo existente relacionado + - Historial de trazas + + tiempo_minimo: "10-15 minutos de busqueda activa" +``` + +### Paso 2: Si No se Encuentra, Documentar + +```markdown +## INFORMACION NO ENCONTRADA + +**Busqueda realizada:** +- [X] docs/01-requerimientos/ - No encontrado +- [X] docs/02-especificaciones-tecnicas/ - Mencionado pero incompleto +- [X] ADRs - No hay ADR relacionado +- [X] Inventarios - N/A + +**Conclusion:** Informacion no disponible, requiere escalamiento +``` + +### Paso 3: Escalar Correctamente + +```markdown +## CONSULTA AL PRODUCT OWNER + +**Fecha:** {fecha} +**Agente:** {agente} +**Tarea:** [{ID}] {titulo} + +### Contexto +{que estoy haciendo} + +### Lo que encontre +{informacion parcial disponible} + +### Lo que falta / es ambiguo +{descripcion clara del gap} + +### Pregunta especifica +{pregunta concreta} + +### Opciones (si las identifique) +1. {opcion A} +2. {opcion B} + +### Impacto +{que pasa si no se resuelve} +``` + +### Paso 4: Esperar y Documentar Respuesta + +```yaml +MIENTRAS_espero: + - NO implementar esa parte + - Continuar con otras tareas si es posible + - Marcar tarea como BLOQUEADA si es critico + +CUANDO_recibo_respuesta: + - Documentar la decision + - Actualizar documentacion correspondiente + - Crear ADR si es decision significativa + - Continuar implementacion +``` + +--- + +## FLUJO DE DECISION + +``` +┌─────────────────────────────────────┐ +│ Encontrar informacion faltante │ +│ o ambiguedad │ +└──────────────┬──────────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ Buscar exhaustivamente en docs │ +│ (10-15 minutos minimo) │ +└──────────────┬──────────────────────┘ + │ + ▼ + ┌──────┴──────┐ + │ Encontrado? │ + └──────┬──────┘ + │ + ┌────────┴────────┐ + │ SI │ NO + ▼ ▼ +┌───────────┐ ┌─────────────────────┐ +│ Proceder │ │ DETENER │ +│ con │ │ Documentar pregunta │ +│ implement │ │ Escalar al PO │ +└───────────┘ └──────────┬──────────┘ + │ + ▼ + ┌─────────────────────┐ + │ ESPERAR respuesta │ + │ (NO asumir) │ + └──────────┬──────────┘ + │ + ▼ + ┌─────────────────────┐ + │ Documentar decision │ + │ Continuar │ + └─────────────────────┘ +``` + +--- + +## EJEMPLOS + +### Ejemplo CORRECTO + +```yaml +situacion: "DDL menciona campo 'status' pero no especifica valores" + +proceso_correcto: + 1. Buscar en docs/: No encontrado + 2. Buscar en specs: Solo dice "tiene status" + 3. Buscar en ADRs: No hay ADR + 4. Conclusion: Escalar + 5. Documentar: "Cuales son los valores validos de status?" + 6. Esperar respuesta + 7. PO responde: "['draft', 'active', 'completed']" + 8. Documentar decision + 9. Implementar con valores correctos +``` + +### Ejemplo INCORRECTO + +```yaml +situacion: "DDL menciona campo 'status' pero no especifica valores" + +proceso_incorrecto: + 1. "Parece que deberian ser 'pending', 'done'" + 2. Implementar con esos valores + 3. PO revisa y dice: "No, son 'draft', 'active', 'completed'" + 4. Retrabajo: migration, seed update, tests, backend, frontend + 5. Tiempo perdido: 2-4 horas +``` + +--- + +## CONSECUENCIAS DE IGNORAR + +```yaml +ignorar_este_principio: + retrabajo: + - Implementacion incorrecta debe rehacerse + - Tests basados en asuncion incorrecta + - Documentacion desalineada + + bugs_de_negocio: + - Funcionalidad no cumple expectativas + - Comportamiento inesperado para usuarios + - Datos incorrectos en sistema + + deuda_tecnica: + - Codigo parche sobre asuncion incorrecta + - Inconsistencias acumuladas + - Complejidad innecesaria + + perdida_de_confianza: + - PO pierde confianza en implementaciones + - Mas revision necesaria + - Ciclos de feedback mas largos +``` + +--- + +## CHECKLIST RAPIDO + +``` +Antes de implementar algo no 100% claro: + +[ ] Busque en documentacion? (10-15 min minimo) +[ ] Revise specs, ADRs, inventarios? +[ ] Sigue sin estar claro? +[ ] Documente la pregunta? +[ ] Escale al PO? +[ ] Espere respuesta? +[ ] Documente la decision? +[ ] Actualice documentacion correspondiente? + +Solo entonces: Proceder con implementacion +``` + +--- + +## RELACION CON OTROS PRINCIPIOS + +```yaml +PRINCIPIO-DOC-PRIMERO: + - Leer docs antes de implementar + - Si docs estan incompletos -> NO-ASUMIR aplica + +PRINCIPIO-CAPVED: + - Fase A (Analisis): Identificar informacion faltante + - Fase V (Validacion): NO aprobar sin informacion completa + +PRINCIPIO-VALIDACION-OBLIGATORIA: + - Validar que implementacion coincide con decision documentada +``` + +--- + +## REFERENCIAS SIMCO + +- **@ESCALAMIENTO** - Proceso completo de escalamiento +- **@DOC_PRIMERO** - Consultar documentacion primero +- **@TAREA** - Ciclo de vida de tareas + +--- + +**Este principio es OBLIGATORIO y NO puede ser ignorado por ningun agente.** + +--- + +**Version:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Principio Fundamental diff --git a/orchestration/directivas/principios/PRINCIPIO-VALIDACION-OBLIGATORIA.md b/orchestration/directivas/principios/PRINCIPIO-VALIDACION-OBLIGATORIA.md new file mode 100644 index 0000000..55070dc --- /dev/null +++ b/orchestration/directivas/principios/PRINCIPIO-VALIDACION-OBLIGATORIA.md @@ -0,0 +1,248 @@ +# PRINCIPIO: VALIDACIÓN OBLIGATORIA + +**Versión:** 1.0.0 +**Fecha:** 2025-12-08 +**Tipo:** Principio Fundamental - HERENCIA OBLIGATORIA +**Aplica a:** TODOS los agentes sin excepción + +--- + +## DECLARACIÓN DEL PRINCIPIO + +``` +╔══════════════════════════════════════════════════════════════════════╗ +║ ║ +║ BUILD PASA + LINT PASA = REQUISITO MÍNIMO ║ +║ ║ +║ "Código que no compila NO está terminado." ║ +║ "Tarea con errores NO está completada." ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## REGLA INQUEBRANTABLE + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ │ +│ NINGUNA tarea se marca como COMPLETADA si: │ +│ │ +│ • Build falla │ +│ • Lint tiene errores críticos │ +│ • Carga limpia falla (para DDL) │ +│ • Tests fallan (si existen) │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## VALIDACIONES POR CAPA + +### Database (DDL) +```bash +# OBLIGATORIO +cd @DB_SCRIPTS +./{RECREATE_CMD} # Carga limpia DEBE pasar + +# Verificación +psql -d {DB_NAME} -c "\dt {schema}.*" # Tablas creadas +psql -d {DB_NAME} -c "\di {schema}.*" # Índices creados +``` + +### Backend (NestJS) +```bash +# OBLIGATORIO +cd @BACKEND_ROOT +npm run build # DEBE pasar +npm run lint # DEBE pasar + +# Adicional +npm run test # Si hay tests, DEBEN pasar +npm run start:dev # DEBE iniciar sin errores +``` + +### Frontend (React) +```bash +# OBLIGATORIO +cd @FRONTEND_ROOT +npm run build # DEBE pasar +npm run lint # DEBE pasar + +# Adicional +npm run typecheck # DEBE pasar +npm run dev # DEBE iniciar sin errores +``` + +--- + +## FLUJO DE VALIDACIÓN + +``` +TERMINAR IMPLEMENTACIÓN + │ + ▼ +┌─────────────────────┐ +│ EJECUTAR BUILD │ +└──────────┬──────────┘ + │ + ▼ +┌─────────────────────┐ ┌─────────────────────┐ +│ ¿BUILD PASA? │──NO──►│ CORREGIR ERRORES │ +└──────────┬──────────┘ └──────────┬──────────┘ + │ SÍ │ + │◄────────────────────────────┘ + ▼ +┌─────────────────────┐ ┌─────────────────────┐ +│ EJECUTAR LINT │──NO──►│ CORREGIR ERRORES │ +│ ¿LINT PASA? │ └──────────┬──────────┘ +└──────────┬──────────┘ │ + │ SÍ │ + │◄────────────────────────────┘ + ▼ +┌─────────────────────┐ ┌─────────────────────┐ +│ EJECUTAR TESTS │──NO──►│ CORREGIR TESTS │ +│ ¿TESTS PASAN? │ └──────────┬──────────┘ +└──────────┬──────────┘ │ + │ SÍ │ + │◄────────────────────────────┘ + ▼ +┌─────────────────────┐ +│ ✅ TAREA COMPLETA │ +└─────────────────────┘ +``` + +--- + +## QUÉ HACER CUANDO FALLA + +### Build Falla +```markdown +1. NO marcar tarea como completada +2. Leer el error completo +3. Identificar archivo y línea +4. Corregir el error +5. Volver a ejecutar build +6. Repetir hasta que pase +``` + +### Lint Falla (Errores) +```markdown +1. NO marcar tarea como completada +2. Distinguir errores de warnings + - Errores (error): DEBEN corregirse + - Warnings (warn): Pueden ignorarse (pero mejor corregir) +3. Corregir todos los errores +4. Volver a ejecutar lint +5. Repetir hasta que pase +``` + +### Carga Limpia Falla (DDL) +```markdown +1. NO marcar tarea como completada +2. NO ejecutar fix manual en BD +3. Leer el error de PostgreSQL +4. Corregir archivo DDL +5. Volver a ejecutar carga limpia completa +6. Repetir hasta que pase +``` + +### Tests Fallan +```markdown +1. NO marcar tarea como completada +2. Identificar test que falla +3. Determinar si: + a. El código tiene bug → Corregir código + b. El test está desactualizado → Actualizar test +4. Volver a ejecutar tests +5. Repetir hasta que pasen +``` + +--- + +## EXCEPCIONES (MUY LIMITADAS) + +```yaml +Puede marcarse completa SIN tests: + - Si no existen tests para el módulo (pero build y lint DEBEN pasar) + - Se documenta: "Tests pendientes de crear" + +Puede tener warnings de lint: + - Si son warnings menores (no errores) + - Se documenta: "N warnings de lint pendientes" + +NUNCA puede marcarse completa: + - Con build fallando + - Con errores de lint + - Con carga limpia fallando +``` + +--- + +## REPORTE DE VALIDACIÓN + +En toda entrega incluir: + +```markdown +## Validaciones + +| Validación | Comando | Resultado | +|------------|---------|-----------| +| Build | `npm run build` | ✅ Pasa / ❌ Falla | +| Lint | `npm run lint` | ✅ Pasa / ⚠️ Warnings / ❌ Errores | +| Tests | `npm run test` | ✅ Pasa / ❌ Falla / ⏭️ N/A | +| Carga Limpia | `./{RECREATE_CMD}` | ✅ Pasa / ❌ Falla / ⏭️ N/A | + +**Estado:** ✅ Validaciones completas / ❌ Pendiente corrección +``` + +--- + +## CONSECUENCIAS DE IGNORAR + +``` +❌ Código que no compila entregado + → Bloquea a otros agentes/desarrolladores + +❌ Errores de lint ignorados + → Código inconsistente, bugs potenciales + +❌ Tests fallando ignorados + → Regresiones, bugs en producción + +❌ DDL con errores + → BD inconsistente, datos corruptos +``` + +--- + +## CHECKLIST RÁPIDO + +``` +Antes de marcar CUALQUIER tarea como completada: + +[ ] Build pasa sin errores +[ ] Lint pasa sin errores (warnings OK) +[ ] Tests pasan (si existen) +[ ] Carga limpia pasa (si es DDL) +[ ] Aplicación inicia correctamente +``` + +--- + +## REFERENCIAS SIMCO + +- **@VALIDAR** - Proceso completo de validación +- **@OP_DDL** - Validación específica de database +- **@OP_BACKEND** - Validación específica de backend +- **@OP_FRONTEND** - Validación específica de frontend + +--- + +**Este principio es OBLIGATORIO y NO puede ser ignorado por ningún agente.** + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Principio Fundamental diff --git a/orchestration/directivas/principios/PROPAGACION-ARCHITECTURE.md b/orchestration/directivas/principios/PROPAGACION-ARCHITECTURE.md new file mode 100644 index 0000000..9d88826 --- /dev/null +++ b/orchestration/directivas/principios/PROPAGACION-ARCHITECTURE.md @@ -0,0 +1,316 @@ +# PROPAGACION-ARCHITECTURE: Arquitectura de Propagacion del Workspace + +**ID:** PROPAGACION-ARCHITECTURE +**Version:** 1.0.0 +**Fecha:** 2026-01-13 +**Autor:** CLAUDE-CAPVED + +--- + +## Proposito + +Este documento clarifica la arquitectura de propagacion del workspace, cuando usar cada mecanismo, y como se relacionan los diferentes componentes del sistema de propagacion. + +--- + +## Jerarquia de Propagacion + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ NIVELES DE PROPAGACION │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ NIVEL 0: PROVIDER │ +│ ┌──────────────────┐ │ +│ │ template-saas │ → Provee funcionalidades base a todos │ +│ │ (v1.2.1) │ │ +│ └────────┬─────────┘ │ +│ │ │ +│ ▼ │ +│ NIVEL 1: INTERMEDIATE │ +│ ┌──────────────────┐ │ +│ │ erp-core │ → Extiende y adapta para verticales ERP │ +│ │ (v1.3.0) │ │ +│ └────────┬─────────┘ │ +│ │ │ +│ ├─────────────────────────────────────────────────┐ │ +│ ▼ ▼ │ +│ NIVEL 2: CONSUMERS NIVEL 2: INTERMEDIATE │ +│ ┌──────────────────┐ ┌──────────────────┐ │ +│ │ erp-construccion │ │ erp-clinicas │ │ +│ │ erp-mecanicas │ │ (v1.0.0) │ │ +│ │ erp-retail │ └────────┬─────────┘ │ +│ │ erp-vidrio │ │ │ +│ └──────────────────┘ ▼ │ +│ NIVEL 3: SUB-CONSUMERS │ +│ ┌──────────────────┐ │ +│ │ clinica-dental │ │ +│ │ clinica-veterina │ │ +│ └──────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Componentes del Sistema de Propagacion + +### 1. Directivas + +| Componente | Ubicacion | Proposito | +|------------|-----------|-----------| +| **MODE-PROPAGATION** | `directivas/modos/` | Modo de ejecucion para propagar cambios entre proyectos | +| **TRIGGER-PROPAGACION-AUTOMATICA** | `directivas/triggers/` | Activa automaticamente en Fase D para evaluar propagacion | +| **SIMCO-PROPAGACION** | `directivas/simco/` | Propagacion de documentacion en verticales (interno) | + +### 2. Referencias + +| Componente | Ubicacion | Proposito | +|------------|-----------|-----------| +| **PROPAGATION-CRITERIA-MATRIX** | `referencias/` | Matriz de criterios para decidir propagacion | +| **DEPENDENCY-GRAPH** | `orchestration/` | Grafo de dependencias entre proyectos | +| **TRACEABILITY-MASTER** | `orchestration/` | Trazabilidad centralizada del workspace | + +### 3. Mirrors + +| Componente | Ubicacion | Proposito | +|------------|-----------|-----------| +| **MIRRORS-INDEX** | `shared/mirrors/` | Indice de todos los repositorios espejo | +| **PROPAGATION-STATUS** | `shared/mirrors/{proyecto}/` | Estado de propagacion por proyecto | + +--- + +## Cuando Usar Cada Mecanismo + +### MODE-PROPAGATION (@PROPAGATE) + +**Usar cuando:** +- Necesitas propagar un cambio especifico a multiples proyectos +- Cambio en erp-core que debe ir a verticales +- Fix de seguridad que afecta multiples proyectos +- Bug fix en modulo compartido +- Actualizacion de dependencias compartidas + +**Ejemplos:** +```bash +@PROPAGATE-ERP Distribuir fix de JWT a verticales +@PROPAGATE-SECURITY Fix de vulnerabilidad XSS +@PROPAGATE-CATALOG Actualizar modulo de notificaciones +``` + +**Flujo:** +``` +Cambio en origen → CAPVED completo → Aplicar en cada destino → Validar → Documentar +``` + +--- + +### TRIGGER-PROPAGACION-AUTOMATICA + +**Usar cuando:** +- Se activa automaticamente al completar Fase D +- No lo invocas directamente, el sistema lo evalua + +**Cuando se activa:** +1. Completas una tarea en proyecto con propagacion (erp-core, shared/catalog) +2. El trigger evalua tipo de cambio +3. Sugiere o inicia propagacion segun reglas + +**Flujo:** +``` +Tarea completada → Trigger evalua → Decide accion → Notifica o propaga +``` + +--- + +### SIMCO-PROPAGACION + +**Usar cuando:** +- Propagas documentacion DENTRO de un proyecto vertical +- No es para propagacion ENTRE proyectos +- Es para estructurar documentacion de modulos heredados + +**Cuando se usa:** +- Al documentar un modulo heredado en una vertical +- Para asegurar que la documentacion refleja la herencia + +**NO usar para:** +- Propagar codigo entre proyectos (usar MODE-PROPAGATION) +- Propagar cambios de core a verticales (usar MODE-PROPAGATION) + +--- + +## Flujo de Decision + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ PREGUNTA: Que necesitas propagar? │ +└────────────────────────────┬────────────────────────────────────┘ + │ + ┌──────────────┴──────────────┐ + ▼ ▼ + ┌────────────────┐ ┌─────────────────┐ + │ CODIGO/CAMBIO │ │ DOCUMENTACION │ + │ entre proyectos│ │ dentro de │ + └───────┬────────┘ │ proyecto │ + │ └────────┬────────┘ + ▼ │ + ┌────────────────────┐ ▼ + │ Es security fix? │ ┌─────────────────┐ + └─────────┬──────────┘ │ SIMCO-PROPAGACION│ + │ │ (interno) │ + ┌────────┴────────┐ └─────────────────┘ + ▼ ▼ +┌─────────┐ ┌─────────┐ +│ SI │ │ NO │ +└────┬────┘ └────┬────┘ + │ │ + ▼ ▼ +┌──────────────┐ ┌───────────────────────┐ +│ @PROPAGATE- │ │ Es bug fix? │ +│ SECURITY │ └───────────┬───────────┘ +│ (inmediato) │ ┌──────┴──────┐ +└──────────────┘ ▼ ▼ + ┌─────────┐ ┌─────────┐ + │ SI │ │ NO │ + └────┬────┘ └────┬────┘ + │ │ + ▼ ▼ + ┌──────────────┐ ┌───────────────┐ + │ @PROPAGATE- │ │ @PROPAGATE │ + │ ERP │ │ (evaluar) │ + │ (72h SLA) │ │ │ + └──────────────┘ └───────────────┘ +``` + +--- + +## SLAs Unificados + +| Tipo de Cambio | SLA | Prioridad | Accion | +|----------------|-----|-----------|--------| +| **Security Fix** | 24 horas | CRITICA | Propagar inmediatamente | +| **Bug Fix** | 72 horas | ALTA | Propagar con prioridad | +| **Feature** | 1 semana | MEDIA | Evaluar si aplica | +| **Refactor** | 2 semanas | BAJA | Opcional | +| **Documentacion** | Inmediato | N/A | Auto-sync via mirrors | +| **Definiciones** | Inmediato | N/A | Auto-sync via mirrors | + +--- + +## Sistema de Mirrors + +### Proposito +Los mirrors son repositorios espejo que facilitan la propagacion automatica de: +- Documentacion (README, CHANGELOG) +- Definiciones (YAML de modulos) +- Interfaces (TypeScript .d.ts) + +### Mirrors Activos + +| Mirror | Version | Consumidores | +|--------|---------|--------------| +| template-saas | 1.2.1 | erp-core | +| erp-core | 1.3.0 | 5 verticales + 2 sub-verticales | +| erp-clinicas | 1.0.0 | clinica-dental, clinica-veterinaria | + +### Auto-Propagacion via Mirrors + +```yaml +Tipo: Documentacion/Definiciones +Flujo: + 1. Cambio en proyecto origen + 2. Sync automatico a shared/mirrors/{proyecto}/ + 3. Consumidores leen del mirror + 4. Actualizacion inmediata disponible + +Tipo: Codigo +Flujo: + 1. Cambio en proyecto origen + 2. Validacion local (build+lint+tests) + 3. Propagar manualmente via MODE-PROPAGATION + 4. Actualizar PROPAGATION-STATUS.yml +``` + +--- + +## Trazabilidad + +### Donde se registra cada propagacion + +| Registro | Ubicacion | Contenido | +|----------|-----------|-----------| +| **TRACEABILITY-MASTER** | `orchestration/` | Registro centralizado de todas las propagaciones | +| **PROPAGATION-STATUS** | `shared/mirrors/{proyecto}/` | Estado por proyecto mirror | +| **MASTER_INVENTORY** | `{proyecto}/orchestration/inventarios/` | Referencia a ultima propagacion recibida | + +### Formato de Registro + +```yaml +propagacion: + id: "PROP-CORE-002" + fecha: "2026-01-13" + tipo: "bulk_propagation" + origen: "erp-core" + destinos: + - erp-construccion + - erp-clinicas + - erp-mecanicas-diesel + - erp-retail + - erp-vidrio-templado + sub_destinos: + - clinica-dental (via erp-clinicas) + - clinica-veterinaria (via erp-clinicas) + modulos: MGN-016 a MGN-022 + estado: "completed" +``` + +--- + +## Comandos Rapidos + +| Alias | Descripcion | Ejemplo | +|-------|-------------|---------| +| `@PROPAGATE-ERP` | Propagar de erp-core a verticales | `@PROPAGATE-ERP Fix de autenticacion` | +| `@PROPAGATE-CATALOG` | Propagar cambio de catalogo | `@PROPAGATE-CATALOG Actualizar notifications` | +| `@PROPAGATE-SECURITY` | Propagacion urgente de seguridad | `@PROPAGATE-SECURITY Vulnerabilidad XSS` | +| `@SYNC-MIRRORS` | Sincronizar todos los mirrors | `@SYNC-MIRRORS` | +| `@PROPAGATE-DOC` | Propagar documentacion | `@PROPAGATE-DOC {proyecto}` | +| `@PROPAGATE-DEF` | Propagar definiciones | `@PROPAGATE-DEF {proyecto}` | +| `@PROPAGATE-CODE` | Propagar codigo validado | `@PROPAGATE-CODE {proyecto}` | + +--- + +## Errores Comunes + +### 1. Confundir MODE-PROPAGATION con SIMCO-PROPAGACION +- **MODE-PROPAGATION:** Entre proyectos (erp-core → verticales) +- **SIMCO-PROPAGACION:** Dentro de un proyecto (documentacion interna) + +### 2. Propagar sin validar +- **Correcto:** Siempre ejecutar build+lint+tests antes de propagar +- **Incorrecto:** Propagar directamente sin validacion + +### 3. Olvidar actualizar trazabilidad +- **Correcto:** Registrar en TRACEABILITY-MASTER y PROPAGATION-STATUS +- **Incorrecto:** Propagar sin documentar + +### 4. Propagar codigo no validado +- **Documentacion/Definiciones:** OK propagar inmediatamente +- **Codigo:** SIEMPRE validar antes de propagar + +--- + +## Referencias + +- `orchestration/directivas/modos/MODE-PROPAGATION.md` +- `orchestration/directivas/triggers/TRIGGER-PROPAGACION-AUTOMATICA.md` +- `orchestration/directivas/simco/SIMCO-PROPAGACION.md` +- `orchestration/referencias/PROPAGATION-CRITERIA-MATRIX.yml` +- `orchestration/TRACEABILITY-MASTER.yml` +- `orchestration/DEPENDENCY-GRAPH.yml` +- `shared/mirrors/MIRRORS-INDEX.yml` + +--- + +*PROPAGACION-ARCHITECTURE v1.0.0 - Sistema SAAD* diff --git a/orchestration/directivas/simco/SIMCO-GIT.md b/orchestration/directivas/simco/SIMCO-GIT.md new file mode 100644 index 0000000..faec47b --- /dev/null +++ b/orchestration/directivas/simco/SIMCO-GIT.md @@ -0,0 +1,510 @@ +# SIMCO: GIT (Control de Versiones) + +**Version:** 1.2.0 +**Fecha:** 2026-01-16 +**Aplica a:** TODO agente que modifica codigo o documentacion +**Prioridad:** OBLIGATORIA + +--- + +## RESUMEN EJECUTIVO + +> **Todo cambio en codigo o documentacion DEBE versionarse correctamente.** +> **Commits frecuentes, atomicos y descriptivos.** +> **PUSH OBLIGATORIO al finalizar cada tarea.** +> **FETCH OBLIGATORIO antes de verificar estado.** +> **Nunca perder trabajo por falta de commits o push.** + +--- + +## REGLA CRITICA 1: FETCH ANTES DE OPERAR + +``` +╔══════════════════════════════════════════════════════════════════════════╗ +║ ║ +║ ANTES DE CUALQUIER VERIFICACION DE ESTADO GIT: ║ +║ ║ +║ 1. git fetch origin ║ +║ → Obtener estado actual del remoto ║ +║ ║ +║ 2. git log HEAD..origin/main --oneline ║ +║ → Si hay output = hay commits remotos que no tienes ║ +║ ║ +║ 3. Si hay commits remotos: ║ +║ git pull --no-recurse-submodules ║ +║ → Sincronizar antes de continuar ║ +║ ║ +║ 4. AHORA SI: git status ║ +║ → Verificar estado local ║ +║ ║ +║ SIN FETCH = ESTADO INCOMPLETO ║ +║ (Otro agente pudo hacer cambios en otra sesion) ║ +║ ║ +║ Referencia: INC-2026-01-16-001 ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════════╝ +``` + +### Secuencia Obligatoria de Verificacion + +```bash +# SIEMPRE ejecutar en este orden: +git fetch origin +git log HEAD..origin/main --oneline # Si hay output, hacer pull +git pull --no-recurse-submodules # Solo si paso anterior tiene output +git status # Ahora si verificar estado local +``` + +--- + +## REGLA CRITICA 2: COMMIT + PUSH OBLIGATORIO + +``` +╔══════════════════════════════════════════════════════════════════════════╗ +║ ║ +║ TODA TAREA QUE CREA O MODIFICA ARCHIVOS DEBE TERMINAR CON: ║ +║ ║ +║ 1. git add . ║ +║ 2. git commit -m "[ID] tipo: descripcion" ║ +║ 3. git push origin {rama} ║ +║ ║ +║ SIN PUSH = TAREA INCOMPLETA ║ +║ ║ +║ En workspace con SUBMODULES: ║ +║ - Commitear y push en CADA submodule afectado ║ +║ - Luego commitear y push en workspace principal ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════════╝ +``` + +### Checklist Fin de Tarea (OBLIGATORIO) + +```yaml +ANTES_de_reportar_tarea_completada: + - [ ] Todos los archivos creados/modificados estan guardados + - [ ] git status muestra archivos a commitear + - [ ] git add {archivos} + - [ ] git commit -m "[TAREA-ID] tipo: descripcion" + - [ ] git push origin {rama} + - [ ] Verificar: git status muestra "nothing to commit, working tree clean" + - [ ] Verificar: git log origin/main..HEAD muestra vacio (todo pusheado) + +SI_hay_SUBMODULES: + - [ ] Repetir proceso en CADA submodule modificado + - [ ] Luego actualizar referencias en workspace principal + - [ ] Push final del workspace principal +``` + +### Secuencia para Workspace con Submodules + +```bash +# 1. Commitear en cada submodule modificado +cd projects/{submodule} +git add . +git commit -m "[TAREA-ID] tipo: descripcion" +git push origin main + +# 2. Repetir para cada submodule afectado +# ... + +# 3. Actualizar workspace principal +cd /home/isem/workspace-v2 +git add projects/{submodule} # Actualiza referencia del submodule +git commit -m "[WORKSPACE] chore: Update submodule references" +git push origin main + +# 4. Verificar todo sincronizado +git status # Debe mostrar "clean" +``` + +--- + +## PRINCIPIOS FUNDAMENTALES + +``` +╔══════════════════════════════════════════════════════════════════════╗ +║ ║ +║ "Commitear temprano, commitear frecuentemente" ║ +║ ║ +║ Cada commit debe: ║ +║ - Representar un cambio logico completo ║ +║ - Ser funcional (no romper compilacion) ║ +║ - Ser reversible sin afectar otros cambios ║ +║ - Tener mensaje descriptivo con ID de tarea ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## FRECUENCIA DE COMMITS + +```yaml +OBLIGATORIO_commitear: + - Al finalizar cada fase (Analisis, Planeacion, Ejecucion) + - Al completar cada archivo significativo + - Cada 30-45 minutos de trabajo continuo + - Antes de lanzar subagentes + - Despues de validar trabajo de subagentes + - Antes de cambiar de tarea + - Cuando build + lint pasan + +RAZON: "Minimizar perdida de trabajo en caso de error" +``` + +--- + +## FORMATO DE MENSAJE DE COMMIT + +### Estructura Obligatoria + +``` +[{TAREA-ID}] {tipo}: {descripcion concisa} + +{cuerpo opcional - descripcion detallada} + +{footer opcional - referencias, breaking changes} +``` + +### Ejemplos Correctos + +```bash +# Feature nueva +[DB-042] feat: Crear tabla projects con soporte PostGIS + +# Bug fix +[BE-015] fix: Corregir validacion de codigo unico en ProjectService + +# Refactor +[FE-008] refactor: Extraer componente ProjectCard de ProjectList + +# Documentacion +[DB-042] docs: Actualizar DATABASE_INVENTORY con tabla projects + +# Tests +[BE-015] test: Agregar tests unitarios para ProjectService + +# Subtarea +[DB-042-SUB-001] feat: Implementar indices para tabla projects +``` + +### Ejemplos Incorrectos + +```bash +# Sin ID de tarea +fix: Corregir bug + +# Muy vago +[BE-015] update: Cambios varios + +# Demasiado largo en primera linea +[DB-042] feat: Crear tabla projects con todas las columnas necesarias incluyendo soporte para PostGIS y configuracion de indices compuestos para optimizar queries + +# Sin tipo +[FE-008] Mejorar componente +``` + +--- + +## TIPOS DE COMMITS + +| Tipo | Uso | Ejemplo | +|------|-----|---------| +| `feat` | Nueva funcionalidad | `[DB-042] feat: Agregar soporte PostGIS` | +| `fix` | Correccion de bug | `[BE-015] fix: Resolver error en constraint` | +| `refactor` | Refactorizacion sin cambio funcional | `[FE-008] refactor: Mejorar estructura componentes` | +| `docs` | Solo documentacion | `[DB-042] docs: Actualizar README con schema` | +| `test` | Agregar/modificar tests | `[BE-015] test: Agregar tests para ProjectService` | +| `chore` | Tareas de mantenimiento | `[DB-042] chore: Actualizar dependencias` | +| `style` | Formato/estilo (sin cambio logico) | `[FE-008] style: Aplicar prettier` | +| `perf` | Mejora de performance | `[DB-042] perf: Agregar indice compuesto` | +| `build` | Cambios en build/deps | `[BE-015] build: Actualizar TypeORM a v0.3` | +| `ci` | Cambios en CI/CD | `[INFRA-001] ci: Agregar workflow de tests` | + +--- + +## COMMITS ATOMICOS + +### Que es un Commit Atomico + +```yaml +atomico: + - Representa UN cambio logico completo + - Es funcional (build pasa) + - Es reversible individualmente + - No mezcla cambios no relacionados + +NO_atomico: + - Multiples cambios no relacionados + - Trabajo incompleto (excepto WIP explicito) + - Mezcla de fix y feat + - Cambios en multiples features +``` + +### Ejemplo de Atomicidad + +```bash +# CORRECTO - Commits atomicos separados +[DB-042] feat: Crear tabla projects +[DB-042] feat: Agregar indices a tabla projects +[DB-042] feat: Crear seeds para projects +[DB-042] docs: Actualizar inventario con tabla projects + +# INCORRECTO - Un commit masivo +[DB-042] feat: Crear tabla projects con indices, seeds y actualizacion de inventario +``` + +--- + +## FLUJO DE TRABAJO GIT + +### Antes de Empezar Tarea + +```bash +# 1. Asegurar rama actualizada +git fetch origin +git pull origin main + +# 2. Crear rama de trabajo (si aplica) +git checkout -b feature/{TAREA-ID}-descripcion-corta + +# 3. Verificar estado limpio +git status +``` + +### Durante la Tarea + +```bash +# 1. Hacer cambios +# ... editar archivos ... + +# 2. Verificar que build pasa +npm run build +npm run lint + +# 3. Agregar cambios +git add {archivos especificos} +# o para todos los cambios relacionados: +git add . + +# 4. Commit con mensaje descriptivo +git commit -m "[TAREA-ID] tipo: descripcion" + +# 5. Repetir para cada cambio logico +``` + +### Al Completar Tarea + +```bash +# 1. Verificar historial +git log --oneline -5 + +# 2. Push a remoto +git push origin {rama} + +# 3. Crear PR si aplica +gh pr create --title "[TAREA-ID] Descripcion" --body "..." +``` + +--- + +## CHECKLIST PRE-COMMIT + +```yaml +ANTES_de_cada_commit: + - [ ] Build pasa sin errores + - [ ] Lint pasa sin errores criticos + - [ ] Tests pasan (si existen) + - [ ] Cambios son logicamente completos + - [ ] No hay archivos no deseados (node_modules, .env, etc.) + - [ ] Mensaje sigue formato correcto + +VERIFICAR: + git status # Ver archivos modificados + git diff # Ver cambios en detalle + git diff --cached # Ver cambios staged +``` + +--- + +## ERRORES COMUNES + +| Error | Consecuencia | Solucion | +|-------|--------------|----------| +| No commitear frecuentemente | Perdida de trabajo | Commit cada 30-45 min | +| Commits masivos | Dificil revertir | Commits atomicos | +| Mensajes vagos | Historial incomprensible | Seguir formato | +| Commit con build roto | Bloquea CI/CD | Verificar antes de commit | +| Olvidar ID de tarea | Perdida de trazabilidad | Siempre incluir [TAREA-ID] | +| Commitear secretos | Brecha de seguridad | Verificar .gitignore | + +--- + +## ARCHIVOS A IGNORAR (.gitignore) + +```yaml +SIEMPRE_ignorar: + - node_modules/ + - .env + - .env.* + - dist/ + - build/ + - coverage/ + - *.log + - .DS_Store + - *.tmp + - *.cache + +NUNCA_commitear: + - Credenciales + - API keys + - Passwords + - Certificados privados + - Archivos de configuracion local +``` + +--- + +## RAMAS (BRANCHING) + +### Convencion de Nombres + +```yaml +ramas: + feature: feature/{TAREA-ID}-descripcion-corta + bugfix: bugfix/{TAREA-ID}-descripcion-corta + hotfix: hotfix/{TAREA-ID}-descripcion-corta + release: release/v{X.Y.Z} + +ejemplos: + - feature/DB-042-crear-tabla-projects + - bugfix/BE-015-fix-validacion + - hotfix/SEC-001-fix-xss + - release/v2.1.0 +``` + +### Flujo de Ramas + +``` +main (produccion) + │ + ├─── develop (desarrollo) + │ │ + │ ├─── feature/DB-042-* + │ │ └── merge a develop + │ │ + │ ├─── feature/BE-015-* + │ │ └── merge a develop + │ │ + │ └── release/v2.1.0 + │ └── merge a main + tag + │ + └─── hotfix/SEC-001-* + └── merge a main + develop +``` + +--- + +## REVERTIR CAMBIOS + +### Revertir Ultimo Commit (no pusheado) + +```bash +# Mantener cambios en working directory +git reset --soft HEAD~1 + +# Descartar cambios completamente +git reset --hard HEAD~1 +``` + +### Revertir Commit ya Pusheado + +```bash +# Crear commit de reversion (seguro) +git revert {commit-hash} +git push +``` + +### Deshacer Cambios en Archivo + +```bash +# Descartar cambios no staged +git checkout -- {archivo} + +# Descartar cambios staged +git reset HEAD {archivo} +git checkout -- {archivo} +``` + +--- + +## SITUACIONES ESPECIALES + +### Work in Progress (WIP) + +```bash +# Cuando necesitas commitear trabajo incompleto +git commit -m "[TAREA-ID] WIP: descripcion de estado actual" + +# Luego, completar y hacer commit final +# (opcional: squash commits WIP antes de PR) +``` + +### Antes de Lanzar Subagente + +```bash +# SIEMPRE commitear antes de delegar +git add . +git commit -m "[TAREA-ID] chore: Estado antes de delegacion a {SubAgente}" +``` + +### Despues de Validar Subagente + +```bash +# Commitear resultado de subagente +git add . +git commit -m "[TAREA-ID-SUB-XXX] tipo: Resultado de {SubAgente}" +``` + +--- + +## VALIDACION DE COMMITS + +### Verificar Historial + +```bash +# Ver ultimos commits +git log --oneline -10 + +# Ver commits de tarea especifica +git log --oneline --grep="DB-042" + +# Ver cambios de un commit +git show {commit-hash} +``` + +### Verificar Formato de Mensaje + +```yaml +formato_valido: + - Tiene [TAREA-ID] al inicio + - Tiene tipo valido (feat, fix, etc.) + - Descripcion concisa (<72 caracteres primera linea) + - No tiene errores de ortografia graves + +verificar_manualmente: + git log --oneline -1 + # Debe mostrar: {hash} [TAREA-ID] tipo: descripcion +``` + +--- + +## REFERENCIAS + +- **Principio de Validacion:** @PRINCIPIOS/PRINCIPIO-VALIDACION-OBLIGATORIA.md +- **Documentar:** @SIMCO/SIMCO-DOCUMENTAR.md +- **Crear:** @SIMCO/SIMCO-CREAR.md + +--- + +**Version:** 1.0.0 | **Sistema:** SIMCO | **Mantenido por:** Tech Lead diff --git a/orchestration/directivas/simco/SIMCO-TAREA.md b/orchestration/directivas/simco/SIMCO-TAREA.md new file mode 100644 index 0000000..30ae4dc --- /dev/null +++ b/orchestration/directivas/simco/SIMCO-TAREA.md @@ -0,0 +1,829 @@ +# SIMCO: CICLO DE VIDA DE TAREAS (CAPVED) + +**Versión:** 1.1.0 +**Sistema:** SIMCO - Gestión de Tareas con CAPVED +**Propósito:** Definir el proceso completo para toda HU/Tarea que modifica código o documentación +**Actualizado:** 2025-12-08 + +--- + +## PRINCIPIO FUNDAMENTAL + +> **Toda tarea que genera commit DEBE pasar por el ciclo CAPVED completo.** +> **Si algo aparece fuera del alcance, se registra y genera HU nueva.** +> **NUEVO: Antes de CAPVED, ejecutar FASE 0 para identificar nivel y contexto.** + +--- + +## FASE 0: IDENTIFICACIÓN DE NIVEL (NUEVA - CRÍTICA) + +**OBLIGATORIO antes de iniciar CAPVED** + +### 0.1 Determinar Nivel Jerárquico + +```yaml +Paso_1: Identificar en qué nivel del workspace estás trabajando + +NIVEL_0_WORKSPACE: + ruta: "/workspace/orchestration/" + identificador: "Es directiva global o índice de workspace" + +NIVEL_1_CORE: + ruta: "/workspace/core/" + identificador: "Es funcionalidad de catálogo o directiva" + +NIVEL_2A_STANDALONE: + ruta: "/workspace/projects/{proyecto}/" + identificador: "NO tiene subcarpeta verticales/" + ejemplos: "gamilit, trading-platform, betting-analytics" + +NIVEL_2B_SUITE: + ruta: "/workspace/projects/{suite}/" + identificador: "TIENE subcarpeta apps/verticales/" + ejemplo: "erp-suite" + +NIVEL_2B1_SUITE_CORE: + ruta: "/workspace/projects/{suite}/apps/erp-core/" + identificador: "Es el núcleo de la suite" + +NIVEL_2B2_VERTICAL: + ruta: "/workspace/projects/{suite}/apps/verticales/{vertical}/" + identificador: "Es vertical especializada" + ejemplos: "construccion, vidrio-templado, clinicas, retail" + +NIVEL_3_CATALOGO: + ruta: "/workspace/shared/catalog/{funcionalidad}/" + identificador: "Es funcionalidad reutilizable" +``` + +### 0.2 Cargar Contexto del Nivel + +```yaml +Archivos_a_leer_según_nivel: + + STANDALONE: + - orchestration/templates/TEMPLATE-CONTEXTO-PROYECTO.md + - orchestration/templates/HERENCIA-SIMCO.md + - orchestration/inventarios/MASTER_INVENTORY.yml + + VERTICAL: + - orchestration/templates/TEMPLATE-CONTEXTO-PROYECTO.md + - orchestration/templates/HERENCIA-SIMCO.md + - orchestration/templates/HERENCIA-ERP-CORE-TEMPLATE.md + - orchestration/inventarios/MASTER_INVENTORY.yml + + SUITE_CORE: + - orchestration/templates/TEMPLATE-CONTEXTO-PROYECTO.md + - orchestration/inventarios/MASTER_INVENTORY.yml + - orchestration/inventarios/DEVENV-MASTER-INVENTORY.yml +``` + +### 0.3 Identificar Ruta de Propagación + +```yaml +Según_tu_nivel_actual: + + STANDALONE → propagar a: + - WORKSPACE (orchestration/WORKSPACE-STATUS.md) + + VERTICAL → propagar a: + - SUITE (../../../orchestration/inventarios/) + - WORKSPACE (orchestration/WORKSPACE-STATUS.md) + + SUITE_CORE → propagar a: + - SUITE (../../orchestration/inventarios/) + - WORKSPACE (orchestration/WORKSPACE-STATUS.md) + - VERTICALES (si afecta herencia) + + CATALOGO → propagar a: + - CORE (inventarios/CORE_INVENTORY.yml) + - CONSUMIDORES (CATALOG-USAGE-TRACKING.yml) +``` + +### 0.4 Registrar Identificación + +```yaml +# Resultado de Fase 0 (incluir en reporte) +fase_0_identificacion: + nivel: "{NIVEL_IDENTIFICADO}" + proyecto: "{NOMBRE}" + path: "{RUTA_COMPLETA}" + propagacion_a: + - "{nivel_superior_1}" + - "{nivel_superior_2}" + contexto_cargado: + - TEMPLATE-CONTEXTO-PROYECTO.md ✓ + - HERENCIA-SIMCO.md ✓ + - MASTER_INVENTORY.yml ✓ + herencia_especifica: "{Si aplica: HERENCIA-ERP-CORE-TEMPLATE.md}" +``` + +### 0.5 Verificar Catálogo + +```yaml +ANTES_de_proceder_a_CAPVED: + verificar: "¿Lo que voy a crear existe en @CATALOG?" + comando: "Buscar en shared/catalog/CATALOG-INDEX.yml" + + SI_EXISTE: + - Leer SIMCO-REUTILIZAR.md + - Adaptar en lugar de crear + - Documentar adaptación + + SI_NO_EXISTE: + - Proceder con CAPVED normal + - Considerar contribuir al catálogo al finalizar +``` + +--- + +## CUÁNDO USAR ESTE SIMCO + +```yaml +USAR_SIMCO_TAREA_cuando: + - Recibes una HU o tarea técnica + - La tarea involucra modificar código + - La tarea involucra modificar documentación + - La tarea generará uno o más commits + - Cualquier trabajo que no sea puramente exploratorio + +NO_USAR_cuando: + - Solo estás investigando/explorando (usa SIMCO-BUSCAR) + - Solo estás consultando información + - Es un spike sin implementación +``` + +--- + +## FLUJO COMPLETO CAPVED + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ │ +│ ENTRADA: HU o Tarea Técnica │ +│ │ +│ ┌──────────────────────────────────────────────────────────────────────┐ │ +│ │ FASE C: CONTEXTO (~5 min) │ │ +│ │ ──────────────────────────── │ │ +│ │ 1. Identificar proyecto/módulo/epic │ │ +│ │ 2. Clasificar tipo de tarea │ │ +│ │ 3. Registrar origen │ │ +│ │ 4. Cargar contexto SIMCO (CCA) │ │ +│ │ 5. Vincular documentos relevantes │ │ +│ └──────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────────────────────────────┐ │ +│ │ FASE A: ANÁLISIS (~15 min) │ │ +│ │ ────────────────────────── │ │ +│ │ 1. Entender comportamiento deseado (negocio) │ │ +│ │ 2. Identificar restricciones (seguridad/perf/UX) │ │ +│ │ 3. Mapear objetos impactados (BD, BE, FE, otros) │ │ +│ │ 4. Identificar dependencias (HUs bloqueantes/bloqueadas) │ │ +│ │ 5. Detectar riesgos │ │ +│ │ → SALIDA: Reporte de análisis │ │ +│ └──────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────────────────────────────┐ │ +│ │ FASE P: PLANEACIÓN (~10 min) │ │ +│ │ ───────────────────────────── │ │ +│ │ 1. Desglosar en subtareas por dominio │ │ +│ │ 2. Establecer orden de ejecución │ │ +│ │ 3. Definir criterios de aceptación │ │ +│ │ 4. Planificar pruebas │ │ +│ │ 5. Asignar agentes/subagentes (si aplica) │ │ +│ │ → SALIDA: Plan de ejecución │ │ +│ └──────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────────────────────────────┐ │ +│ │ FASE V: VALIDACIÓN (~5 min) ⚠️ NO DELEGAR │ │ +│ │ ──────────────────────────────────────────── │ │ +│ │ 1. ¿Todo lo de A tiene acción en P? │ │ +│ │ 2. ¿Dependencias resueltas o planificadas? │ │ +│ │ 3. ¿Criterios cubren riesgos? │ │ +│ │ 4. ¿Hay scope creep? → Registrar + crear HU derivada │ │ +│ │ → GATE: Solo pasa si TODO cuadra │ │ +│ └──────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌─────────┴─────────┐ │ +│ │ ¿VALIDACIÓN OK? │ │ +│ └─────────┬─────────┘ │ +│ NO │ │ SÍ │ +│ ▼ ▼ │ +│ ┌────────────┐ ┌──────────────────────────────────────────┐ │ +│ │ AJUSTAR │ │ FASE E: EJECUCIÓN (variable) │ │ +│ │ A o P │ │ ───────────────────────────── │ │ +│ │ y volver │ │ 1. Actualizar docs/ PRIMERO │ │ +│ │ a V │ │ 2. Ejecutar subtareas en orden │ │ +│ └────────────┘ │ 3. Validar build/lint por subtarea │ │ +│ │ 4. Registrar progreso │ │ +│ │ 5. Usar SIMCO correspondientes │ │ +│ │ → SALIDA: Código implementado │ │ +│ └──────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────────────────────────────────────────────────────────────┐ │ +│ │ FASE D: DOCUMENTACIÓN (~10 min) │ │ +│ │ ─────────────────────────────── │ │ +│ │ 1. Actualizar diagramas/modelos │ │ +│ │ 2. Actualizar specs técnicas │ │ +│ │ 3. Crear ADR (si decisión arquitectónica) │ │ +│ │ 4. Actualizar inventarios │ │ +│ │ 5. Actualizar trazas │ │ +│ │ 6. Vincular HUs derivadas │ │ +│ │ 7. Registrar lecciones aprendidas │ │ +│ │ → GATE: HU NO está Done sin esto │ │ +│ └──────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ │ +│ SALIDA: HU Completada, Documentada, Trazable │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## FASE C: CONTEXTO (Detalle) + +### C.1 Identificar Proyecto/Módulo/Epic + +```yaml +Contexto_Obligatorio: + proyecto: "{nombre del proyecto}" + ruta_proyecto: "projects/{proyecto}/" + modulo: "{nombre del módulo afectado}" + epic_padre: "{EPIC-ID} - {nombre}" + feature_padre: "{FEATURE-ID} - {nombre}" # si aplica +``` + +### C.2 Clasificar Tipo de Tarea + +```yaml +Tipos_de_Tarea: + feature: "Nueva funcionalidad" + enhancement: "Mejora a funcionalidad existente" + fix: "Corrección de bug" + refactor: "Reestructuración sin cambio funcional" + spike: "Investigación técnica" + doc-only: "Solo documentación" + tech-debt: "Pago de deuda técnica" + security: "Corrección de seguridad" + performance: "Optimización de rendimiento" +``` + +### C.3 Registrar Origen + +```yaml +Origenes_de_Tarea: + plan-original: "Parte del plan de proyecto/sprint" + descubrimiento: "Detectada durante otra tarea" + incidencia: "Reportada por usuario/QA" + mejora-continua: "Identificada en retrospectiva" + dependencia: "Requerida por otra HU" +``` + +### C.4 Cargar Contexto SIMCO (CCA) + +``` +Seguir protocolo de SIMCO-INICIALIZACION.md: +1. Leer principios fundamentales (4 ahora con CAPVED) +2. Leer perfil del agente +3. Leer CONTEXTO-PROYECTO.md +4. Leer inventarios relevantes +5. Cargar SIMCO de operación según tipo de tarea +``` + +### C.5 Vincular Documentos Relevantes + +```yaml +Documentos_a_Vincular: + docs_proyecto: + - "docs/{fase}/{epic}/README.md" + - "docs/{fase}/{epic}/requerimientos/{archivo}.md" + - "docs/{fase}/{epic}/especificaciones/{archivo}.md" + + docs_tecnicos: + - "docs/95-guias-desarrollo/{relevantes}.md" + - "docs/97-adr/{relacionados}.md" + + orchestration: + - "orchestration/inventarios/{relevantes}.yml" + - "orchestration/trazas/TRAZA-{tipo}.md" +``` + +--- + +## FASE A: ANÁLISIS (Detalle) + +### A.1 Comportamiento Deseado (Negocio) + +```yaml +Preguntas_de_Negocio: + - "¿Qué debe poder hacer el usuario al completar esta HU?" + - "¿Qué problema de negocio resuelve?" + - "¿Cuál es el criterio de éxito desde perspectiva de usuario?" + - "¿Hay casos de uso específicos documentados?" + +Formato_Respuesta: + como: "{rol de usuario}" + quiero: "{acción deseada}" + para: "{beneficio/valor}" +``` + +### A.2 Restricciones + +```yaml +Restricciones_a_Identificar: + seguridad: + - "¿Requiere autenticación?" + - "¿Requiere autorización por rol?" + - "¿Maneja datos sensibles?" + - "¿Aplica RLS?" + + performance: + - "¿Volumen esperado de datos?" + - "¿Tiempo de respuesta esperado?" + - "¿Requiere paginación?" + - "¿Requiere caché?" + + ux: + - "¿Hay wireframes/mockups?" + - "¿Estados de carga definidos?" + - "¿Manejo de errores definido?" + - "¿Responsive requerido?" +``` + +### A.3 Mapear Objetos Impactados + +```yaml +Objetos_por_Capa: + database: + schemas: [] # Schemas afectados + tablas: [] # Tablas a crear/modificar + vistas: [] # Vistas afectadas + funciones: [] # Funciones a crear/modificar + indices: [] # Índices necesarios + triggers: [] # Triggers afectados + rls_policies: [] # Políticas RLS + + backend: + modulos: [] # Módulos NestJS + entities: [] # Entities TypeORM + services: [] # Services + controllers: [] # Controllers + dtos: [] # DTOs (Request/Response) + guards: [] # Guards de autorización + pipes: [] # Pipes de validación + + frontend: + paginas: [] # Páginas/rutas + componentes: [] # Componentes React + hooks: [] # Custom hooks + stores: [] # Stores Zustand + types: [] # TypeScript types/interfaces + services: [] # Services de API + + otros: + proyectos: [] # Otros proyectos afectados + integraciones: [] # Integraciones externas + jobs: [] # Jobs/colas + caches: [] # Caché a invalidar +``` + +### A.4 Identificar Dependencias + +```yaml +Dependencias: + bloquea_a: # Esta HU bloquea a otras + - hu_id: "HU-XXX" + razon: "Necesita la tabla que creo" + + bloqueada_por: # Esta HU depende de otras + - hu_id: "HU-YYY" + razon: "Necesito el endpoint de auth" + estado: "completada | en-progreso | pendiente" + + relacionadas: # HUs relacionadas (no bloqueo directo) + - hu_id: "HU-ZZZ" + relacion: "Mismo módulo" +``` + +### A.5 Detectar Riesgos + +```yaml +Riesgos_Identificados: + - id: "R1" + descripcion: "Cambio en tabla users afecta auth de todos los tenants" + probabilidad: "alta | media | baja" + impacto: "alto | medio | bajo" + mitigacion: "Ejecutar en horario de bajo tráfico, tener rollback listo" +``` + +--- + +## FASE P: PLANEACIÓN (Detalle) + +### P.1 Desglosar en Subtareas + +```yaml +Subtareas: + documentacion: # SIEMPRE PRIMERO + - id: "ST-001" + descripcion: "Actualizar spec de API en docs/" + artefactos: ["docs/.../.md"] + + database: + - id: "ST-002" + descripcion: "Crear tabla users en schema auth" + artefactos: ["ddl/schemas/auth/tables/users.sql"] + agente: "Database-Agent" + + backend: + - id: "ST-003" + descripcion: "Crear UserEntity alineada con DDL" + artefactos: ["src/modules/users/entities/user.entity.ts"] + agente: "Backend-Agent" + depende_de: ["ST-002"] + + - id: "ST-004" + descripcion: "Crear UsersService con CRUD" + artefactos: ["src/modules/users/users.service.ts"] + agente: "Backend-Agent" + depende_de: ["ST-003"] + + frontend: + - id: "ST-005" + descripcion: "Crear UserList component" + artefactos: ["src/components/users/UserList.tsx"] + agente: "Frontend-Agent" + depende_de: ["ST-004"] + + validacion: # SIEMPRE AL FINAL + - id: "ST-006" + descripcion: "Validación final build/lint/tests" + agente: "Ejecutar directamente" +``` + +### P.2 Orden de Ejecución + +``` +1. Documentación (docs/ actualizados) + ↓ +2. Database (DDL, migraciones) + ↓ +3. Backend (Entities → Services → Controllers) + ↓ +4. Frontend (Types → Hooks → Components → Pages) + ↓ +5. Validación (build, lint, tests) + ↓ +6. Documentación final (inventarios, trazas) +``` + +### P.3 Criterios de Aceptación + +```yaml +Criterios_de_Aceptacion: + funcionales: + - "Usuario puede crear registro" + - "Usuario puede listar registros con paginación" + - "Usuario puede editar registro existente" + - "Usuario puede eliminar registro (soft delete)" + + tecnicos: + - "Build pasa sin errores" + - "Lint pasa sin errores" + - "Tests unitarios cubren >80%" + - "API documentada en Swagger" + + documentacion: + - "Inventarios actualizados" + - "Trazas registradas" + - "ADR creado (si aplica)" +``` + +### P.4 Plan de Pruebas + +```yaml +Plan_de_Pruebas: + unitarias: + - "Service: CRUD operations" + - "Guards: permission checks" + + integracion: + - "API: endpoints responden correctamente" + - "DB: datos persisten correctamente" + + e2e: + - "Flujo completo crear-editar-eliminar" + + regresion: + - "Auth sigue funcionando" + - "Otros módulos no afectados" +``` + +--- + +## FASE V: VALIDACIÓN (Detalle) + +### V.1 Verificar Cobertura Análisis → Plan + +```yaml +Verificacion_Cobertura: + objetos_database: + - objeto: "tabla users" + en_analisis: true + en_plan: "ST-002" + ✓ CUBIERTO + + objetos_backend: + - objeto: "UserEntity" + en_analisis: true + en_plan: "ST-003" + ✓ CUBIERTO + + # Si algo en Análisis NO tiene subtarea en Plan: + gap_detectado: + - objeto: "índice en email" + en_analisis: true + en_plan: false + accion: "Agregar subtarea ST-002b" +``` + +### V.2 Verificar Dependencias + +```yaml +Verificacion_Dependencias: + - hu_dependencia: "HU-YYY" + estado: "completada" + ✓ LISTA + + - hu_dependencia: "HU-ZZZ" + estado: "pendiente" + ⚠️ BLOQUEADOR + accion: "Esperar o crear subtarea previa" +``` + +### V.3 Detectar Scope Creep + +```yaml +Scope_Creep_Detectado: + - item: "Se necesita también endpoint de búsqueda" + parte_de_hu_original: false + accion: "CREAR HU DERIVADA" + hu_derivada: + id: "DERIVED-HU-001-001" + descripcion: "Endpoint de búsqueda de usuarios" + prioridad: "P2" +``` + +### V.4 Gate de Validación + +``` +CHECKLIST GATE: +[ ] Todo objeto de Análisis tiene subtarea en Plan +[ ] Todas las dependencias están resueltas o planificadas +[ ] Criterios de aceptación cubren todos los riesgos +[ ] Scope creep registrado y HUs derivadas creadas +[ ] No hay gaps sin resolver + +→ Si TODO marcado: PROCEDER A EJECUCIÓN +→ Si algo falta: VOLVER A AJUSTAR A o P +``` + +--- + +## FASE E: EJECUCIÓN (Detalle) + +### E.1 Actualizar docs/ PRIMERO + +```yaml +Antes_de_Codigo: + - Actualizar specs de API + - Actualizar diagramas de entidades + - Actualizar documentación de módulo + - Verificar que docs/ refleja lo que se va a implementar +``` + +### E.2 Ejecutar Subtareas en Orden + +Para cada subtarea: + +```yaml +Por_Subtarea: + 1_iniciar: + - Marcar subtarea "en progreso" + - Cargar SIMCO correspondiente (CREAR/MODIFICAR/DDL/etc) + + 2_implementar: + - Seguir checklist del SIMCO + - Aplicar principios (doc-primero, anti-dup, validación) + - Generar código/cambios + + 3_validar: + - Ejecutar build + - Ejecutar lint + - Verificar que compila + + 4_registrar: + - Marcar subtarea "completada" + - Notas de lo implementado + - Desviaciónes (si las hubo) + + 5_siguiente: + - Pasar a siguiente subtarea +``` + +### E.3 Usar SIMCO Correspondientes + +```yaml +SIMCO_por_Subtarea: + crear_tabla: "@SIMCO-CREAR + @SIMCO-DDL" + crear_entity: "@SIMCO-CREAR + @SIMCO-BACKEND" + crear_componente: "@SIMCO-CREAR + @SIMCO-FRONTEND" + modificar_algo: "@SIMCO-MODIFICAR + @SIMCO-{dominio}" + validar: "@SIMCO-VALIDAR" +``` + +--- + +## FASE D: DOCUMENTACIÓN (Detalle) + +### D.1 Actualizar Diagramas/Modelos + +```yaml +Diagramas_a_Actualizar: + - tipo: "ERD" + ubicacion: "docs/{epic}/diseño/erd.md" + cambio: "Agregar tabla users" + + - tipo: "Arquitectura" + ubicacion: "docs/00-vision-general/arquitectura.md" + cambio: "Agregar módulo users" # si aplica +``` + +### D.2 Actualizar Specs Técnicas + +```yaml +Specs_a_Actualizar: + - tipo: "API" + ubicacion: "docs/{epic}/especificaciones/api-users.md" + cambio: "Documentar endpoints CRUD" + + - tipo: "BD" + ubicacion: "docs/{epic}/especificaciones/modelo-datos.md" + cambio: "Agregar tabla users" +``` + +### D.3 Crear ADR (si aplica) + +```yaml +ADR_Requerido_Si: + - "Se tomó decisión arquitectónica importante" + - "Se eligió tecnología/librería nueva" + - "Se cambió patrón establecido" + - "Se hizo trade-off significativo" + +Ubicacion: "docs/97-adr/ADR-{NNN}-{titulo}.md" +``` + +### D.4 Actualizar Inventarios + +```yaml +Inventarios_a_Actualizar: + - archivo: "orchestration/inventarios/DATABASE_INVENTORY.yml" + agregar: "Nueva tabla users en schema auth" + + - archivo: "orchestration/inventarios/BACKEND_INVENTORY.yml" + agregar: "Nuevo módulo users" + + - archivo: "orchestration/inventarios/FRONTEND_INVENTORY.yml" + agregar: "Nuevo componente UserList" +``` + +### D.5 Actualizar Trazas + +```yaml +Traza_a_Registrar: + archivo: "orchestration/trazas/TRAZA-TAREAS-{tipo}.md" + entrada: + fecha: "2025-12-08" + hu_id: "HU-001" + descripcion: "CRUD de usuarios" + archivos_creados: [lista] + archivos_modificados: [lista] + agente: "Backend-Agent" + duracion: "2h" + notas: "Sin incidencias" +``` + +### D.6 Vincular HUs Derivadas + +```yaml +HUs_Derivadas: + - id: "DERIVED-HU-001-001" + descripcion: "Endpoint de búsqueda de usuarios" + origen: "HU-001" + detectado_en: "Fase V - Validación" + estado: "pendiente" + prioridad: "P2" +``` + +### D.7 Registrar Lecciones Aprendidas + +```yaml +Lecciones_Aprendidas: + que_funciono_bien: + - "Seguir orden DB → BE → FE evitó retrabajos" + - "Validar contra Swagger antes de FE ahorró tiempo" + + que_se_puede_mejorar: + - "Definir tipos compartidos desde el inicio" + + para_futuras_HUs: + - "En módulos CRUD, siempre incluir paginación desde V1" +``` + +### D.8 Gate Final + +``` +CHECKLIST DOCUMENTACIÓN: +[ ] Diagramas actualizados +[ ] Specs técnicas actualizadas +[ ] ADR creado (si aplica) +[ ] Inventarios actualizados +[ ] Trazas registradas +[ ] HUs derivadas vinculadas +[ ] Lecciones aprendidas registradas + +→ Si TODO marcado: HU COMPLETADA +→ Si algo falta: COMPLETAR ANTES DE CERRAR +``` + +--- + +## TEMPLATE DE REGISTRO RÁPIDO + +```yaml +# Registro CAPVED para HU-{ID} +# ──────────────────────────── + +hu_id: "HU-XXX" +titulo: "Título de la HU" +fecha_inicio: "YYYY-MM-DD" +fecha_fin: "YYYY-MM-DD" + +contexto: + proyecto: "" + modulo: "" + epic: "" + tipo: "feature | fix | refactor | etc" + origen: "plan | descubrimiento | incidencia" + +analisis: + objetos_impactados: N + dependencias: N + riesgos: N + +planeacion: + subtareas: N + agentes_asignados: [] + +validacion: + gaps_detectados: N + scope_creep: "sí | no" + hus_derivadas: N + +ejecucion: + subtareas_completadas: "N/N" + build_status: "✓ | ✗" + lint_status: "✓ | ✗" + +documentacion: + inventarios: "✓ | ✗" + trazas: "✓ | ✗" + adr: "✓ | N/A" + lecciones: "✓ | ✗" + +estado_final: "COMPLETADA | EN_PROGRESO | BLOQUEADA" +``` + +--- + +## REFERENCIAS + +| Documento | Propósito | +|-----------|-----------| +| `PRINCIPIO-CAPVED.md` | Declaración del principio | +| `SIMCO-INICIALIZACION.md` | Protocolo CCA | +| `TEMPLATE-TAREA-CAPVED.md` | Template completo para tracking | +| `TEMPLATE-ANALISIS.md` | Template de análisis | +| `TEMPLATE-PLAN.md` | Template de planeación | +| `TEMPLATE-VALIDACION.md` | Template de validación | + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO + CAPVED | **Tipo:** Directiva de Proceso diff --git a/orchestration/directivas/simco/SIMCO-VALIDAR.md b/orchestration/directivas/simco/SIMCO-VALIDAR.md new file mode 100644 index 0000000..40fc98d --- /dev/null +++ b/orchestration/directivas/simco/SIMCO-VALIDAR.md @@ -0,0 +1,394 @@ +# SIMCO: VALIDAR + +**Versión:** 1.0.0 +**Fecha:** 2025-12-08 +**Aplica a:** TODO agente antes de marcar una tarea como completada +**Prioridad:** OBLIGATORIA - NO SE PUEDE OMITIR + +--- + +## RESUMEN EJECUTIVO + +> **NINGUNA tarea se marca como completada sin pasar TODAS las validaciones.** +> **Si una validación falla, la tarea NO está completa.** + +--- + +## PRINCIPIO FUNDAMENTAL + +``` +╔══════════════════════════════════════════════════════════════════════╗ +║ BUILD PASA + LINT PASA + TESTS PASAN = TAREA PUEDE COMPLETARSE ║ +║ CUALQUIER FALLO = TAREA NO COMPLETADA ║ +╚══════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## CHECKLIST UNIVERSAL DE VALIDACIÓN + +``` +VALIDACIONES TÉCNICAS (OBLIGATORIAS) +├── [ ] 1. Build compila sin errores +├── [ ] 2. Lint pasa sin errores críticos +├── [ ] 3. Tests pasan (si existen) +└── [ ] 4. Aplicación inicia correctamente + +VALIDACIONES DE COHERENCIA +├── [ ] 5. Código alineado con documentación +├── [ ] 6. Sin duplicados creados +├── [ ] 7. Convenciones seguidas +└── [ ] 8. Inventarios actualizados + +VALIDACIONES DE INTEGRACIÓN +├── [ ] 9. Coherencia entre capas (DB↔BE↔FE) +└── [ ] 10. APIs funcionan correctamente +``` + +--- + +## VALIDACIONES POR CAPA + +> **Definiciones canónicas disponibles:** +> - @DEF_VAL_BE → `_definitions/validations/VALIDATION-BACKEND.md` +> - @DEF_VAL_FE → `_definitions/validations/VALIDATION-FRONTEND.md` +> - @DEF_VAL_DDL → `_definitions/validations/VALIDATION-DDL.md` +> - @DEF_VAL_DEVOPS → `_definitions/validations/VALIDATION-DEVOPS.md` + +### Database (DDL) + +> **Definición canónica:** @DEF_VAL_DDL + +**Comando obligatorio:** +```bash +# Carga limpia COMPLETA +cd @DB_SCRIPTS +./{RECREATE_CMD} +``` + +**Criterios de éxito:** +``` +✅ Script ejecuta sin errores +✅ Todas las tablas se crean +✅ Todos los índices se crean +✅ Constraints se aplican +✅ Seeds se cargan (si existen) +✅ Integridad referencial OK +``` + +**Verificación post-creación:** +```bash +# Verificar tablas +psql -d {DB_NAME} -c "\dt {schema}.*" + +# Verificar índices +psql -d {DB_NAME} -c "\di {schema}.*" + +# Verificar estructura +psql -d {DB_NAME} -c "\d {schema}.{tabla}" + +# Test de insert +psql -d {DB_NAME} -c "INSERT INTO {schema}.{tabla} (...) VALUES (...);" +``` + +**Si falla:** +``` +🛑 NO marcar como completada +1. Identificar error en DDL +2. Corregir archivo DDL (NO fix manual en BD) +3. Re-ejecutar carga limpia +4. Solo entonces continuar +``` + +--- + +### Backend (NestJS/TypeScript) + +> **Definición canónica:** @DEF_VAL_BE + +**Comandos obligatorios:** +```bash +cd @BACKEND_ROOT + +# 1. Build (OBLIGATORIO) +npm run build +# ✅ Debe completar sin errores + +# 2. Lint (OBLIGATORIO) +npm run lint +# ✅ Debe pasar o corregir errores + +# 3. Tests (si existen) +npm run test +# ✅ Deben pasar + +# 4. Iniciar aplicación +npm run start:dev +# ✅ Debe iniciar sin errores de runtime +``` + +**Criterios de éxito:** +``` +✅ TypeScript compila sin errores +✅ ESLint sin errores (warnings aceptables) +✅ Tests unitarios pasan +✅ Aplicación inicia +✅ Endpoints responden +``` + +**Verificación de endpoints:** +```bash +# Verificar health +curl http://localhost:3000/api/health + +# Verificar endpoint creado +curl http://localhost:3000/api/{recurso} + +# Verificar Swagger +curl http://localhost:3000/api/docs +``` + +**Si falla:** +``` +🛑 NO marcar como completada +1. Revisar errores de TypeScript +2. Corregir código +3. Re-ejecutar build + lint +4. Solo entonces continuar +``` + +--- + +### Frontend (React/TypeScript) + +> **Definición canónica:** @DEF_VAL_FE + +**Comandos obligatorios:** +```bash +cd @FRONTEND_ROOT + +# 1. Build (OBLIGATORIO) +npm run build +# ✅ Debe completar sin errores + +# 2. Lint (OBLIGATORIO) +npm run lint +# ✅ Debe pasar o corregir errores + +# 3. Type check +npm run typecheck # o tsc --noEmit +# ✅ Debe pasar + +# 4. Iniciar aplicación +npm run dev +# ✅ Debe iniciar sin errores +``` + +**Criterios de éxito:** +``` +✅ TypeScript compila sin errores +✅ ESLint sin errores críticos +✅ Aplicación renderiza correctamente +✅ Sin errores en consola del navegador +✅ Componentes funcionan según diseño +``` + +**Si falla:** +``` +🛑 NO marcar como completada +1. Revisar errores de TypeScript/React +2. Corregir código +3. Re-ejecutar build + lint +4. Solo entonces continuar +``` + +--- + +## VALIDACIÓN DE COHERENCIA + +### Coherencia Documentación ↔ Código + +**Verificar:** +```markdown +- [ ] Lo implementado coincide con docs/ +- [ ] No hay features documentadas sin implementar +- [ ] No hay código sin documentación correspondiente +- [ ] ADRs actualizados si hay decisiones nuevas +``` + +### Coherencia Entre Capas (3-Tier) + +**Database ↔ Backend:** +```markdown +- [ ] Entity mapea correctamente a tabla +- [ ] Tipos de columnas coinciden +- [ ] Relaciones (FK) correctas +- [ ] Nombres de campos alineados +``` + +**Backend ↔ Frontend:** +```markdown +- [ ] DTOs coinciden con types del frontend +- [ ] Endpoints documentados en Swagger +- [ ] Respuestas API coinciden con interfaces FE +- [ ] Errores manejados consistentemente +``` + +### Anti-Duplicación + +**Verificar después de crear:** +```bash +# Buscar objetos con nombre similar +grep -rn "{nombre}" @INVENTORY + +# No debe haber entradas duplicadas +# Si hay duplicados → ERROR → Corregir +``` + +--- + +## MATRIZ DE VALIDACIONES POR TIPO DE TAREA + +| Tipo de Tarea | Build | Lint | Tests | Carga Limpia | Coherencia 3-Tier | +|---------------|-------|------|-------|--------------|-------------------| +| Nueva tabla | - | - | - | ✅ OBLIGATORIO | ✅ | +| Nueva entity | ✅ BE | ✅ BE | ✅ BE | - | ✅ | +| Nuevo service | ✅ BE | ✅ BE | ✅ BE | - | - | +| Nuevo controller | ✅ BE | ✅ BE | ✅ BE | - | ✅ | +| Nuevo componente | ✅ FE | ✅ FE | ✅ FE | - | ✅ | +| Nueva página | ✅ FE | ✅ FE | ✅ FE | - | ✅ | +| Bug fix | ✅ Afectado | ✅ Afectado | ✅ Afectado | Si DDL | - | +| Refactor | ✅ TODO | ✅ TODO | ✅ TODO | Si DDL | ✅ | + +--- + +## PROTOCOLO DE FALLA + +### Si Build Falla + +```markdown +## ❌ Build Fallido + +**Error:** +{copiar error completo} + +**Archivo(s) afectado(s):** +- {lista de archivos} + +**Análisis:** +{descripción del problema} + +**Acción:** +1. Corregir {archivo} línea {N} +2. Re-ejecutar build +3. Continuar solo si pasa +``` + +### Si Lint Falla (Errores Críticos) + +```markdown +## ❌ Lint Fallido + +**Errores críticos:** +{lista de errores} + +**Acción:** +1. Corregir cada error +2. Re-ejecutar lint +3. Warnings son aceptables +4. Errores NO son aceptables +``` + +### Si Tests Fallan + +```markdown +## ❌ Tests Fallidos + +**Tests que fallan:** +- {test 1}: {razón} +- {test 2}: {razón} + +**Acción:** +1. Analizar si es error de código o de test +2. Si error de código → Corregir código +3. Si test desactualizado → Actualizar test +4. Re-ejecutar tests +``` + +### Si Carga Limpia Falla + +```markdown +## ❌ Carga Limpia Fallida + +**Error:** +{error de PostgreSQL} + +**Archivo DDL problemático:** +{archivo.sql} + +**Acción:** +1. NO ejecutar fix manual en BD +2. Corregir archivo DDL +3. Re-ejecutar carga limpia completa +4. Repetir hasta éxito +``` + +--- + +## REPORTE DE VALIDACIÓN + +**Incluir en cada entrega:** + +```markdown +## Validaciones Ejecutadas + +### Build +- Backend: ✅ Pasa | ❌ Falla +- Frontend: ✅ Pasa | ❌ Falla | ⏭️ N/A + +### Lint +- Backend: ✅ Pasa | ❌ Falla +- Frontend: ✅ Pasa | ❌ Falla | ⏭️ N/A + +### Tests +- Backend: ✅ Pasa | ❌ Falla | ⏭️ N/A +- Frontend: ✅ Pasa | ❌ Falla | ⏭️ N/A + +### Carga Limpia (DDL) +- Database: ✅ Pasa | ❌ Falla | ⏭️ N/A + +### Coherencia +- Docs ↔ Código: ✅ OK | ❌ Discrepancia +- DB ↔ BE: ✅ OK | ❌ Discrepancia | ⏭️ N/A +- BE ↔ FE: ✅ OK | ❌ Discrepancia | ⏭️ N/A + +### Estado Final +✅ TODAS LAS VALIDACIONES PASAN → Tarea completable +❌ ALGUNA VALIDACIÓN FALLA → Tarea NO completable +``` + +--- + +## ERRORES COMUNES + +| Error | Causa | Solución | +|-------|-------|----------| +| Reportar sin validar | Prisa por entregar | SIEMPRE ejecutar validaciones | +| Fix manual en BD | Carga limpia falla | Corregir DDL, no BD directamente | +| Ignorar warnings de lint | Parecer inofensivos | Revisar si son errores disfrazados | +| Saltar tests | "No hay tiempo" | Tests son OBLIGATORIOS | +| No verificar coherencia | Asumir que está bien | Verificar SIEMPRE entre capas | + +--- + +## REFERENCIAS + +- **Ciclo de vida de tareas:** @CAPVED (PRINCIPIO-CAPVED.md) - Fase V y E +- **Punto de entrada HU:** @TAREA (SIMCO-TAREA.md) +- **Crear archivos:** @CREAR (SIMCO-CREAR.md) +- **Documentar:** @DOCUMENTAR (SIMCO-DOCUMENTAR.md) +- **Directiva completa de validación:** @DIRECTIVAS/PROCESO-VALIDACION.md + +--- + +**Versión:** 1.1.0 | **Sistema:** SIMCO + CAPVED | **Mantenido por:** Tech Lead diff --git a/orchestration/directivas/triggers/TRIGGER-ANALISIS-DEPENDENCIAS.md b/orchestration/directivas/triggers/TRIGGER-ANALISIS-DEPENDENCIAS.md new file mode 100644 index 0000000..bfd52f0 --- /dev/null +++ b/orchestration/directivas/triggers/TRIGGER-ANALISIS-DEPENDENCIAS.md @@ -0,0 +1,345 @@ +# TRIGGER-ANALISIS-DEPENDENCIAS + +**ID:** TRIGGER-ANALISIS-DEPENDENCIAS +**Version:** 1.0.0 +**Tipo:** Automatico +**Fase CAPVED:** Se activa en Fase A (Analisis) + +--- + +## Proposito + +Analizar automaticamente las dependencias de un archivo antes de modificarlo, +identificando tanto los archivos de los que depende (imports) como los archivos +que dependen de el (dependientes), para evaluar el impacto del cambio y +asegurar que todos los archivos afectados sean considerados en el plan. + +--- + +## Cuando Se Activa + +```yaml +activadores: + palabras_clave: + - "modificar" + - "cambiar" + - "actualizar" + - "refactorizar" + - "eliminar" + - "renombrar" + - "mover" + + tipos_operacion: + - Modificacion de archivo existente + - Eliminacion de archivo + - Renombrado de archivo/clase/funcion + - Cambio de firma de funcion/metodo + - Cambio de estructura de tabla/entity + + ejemplos: + - "Modificar UserEntity para agregar campo email_verified" + - "Cambiar estructura de tabla payments" + - "Refactorizar AuthService" + - "Renombrar componente Dashboard a AdminDashboard" + - "Eliminar funcion deprecada calculateTotal" +``` + +--- + +## Acciones del Trigger + +### Paso 1: Identificar Dependencias (Imports) +```yaml +accion: "Identificar archivos que el archivo modificado importa" +descripcion: "Estos son los archivos de los que DEPENDE el archivo a modificar" + +comandos: + typescript: + - grep -E "^import .* from" {archivo} + - grep -E "require\(" {archivo} + + python: + - grep -E "^from .* import|^import " {archivo} + + sql: + - grep -E "REFERENCES|FOREIGN KEY" {archivo} + +output: + formato: | + ## Dependencias (de los que depende) + | Archivo | Tipo de Dependencia | + |---------|---------------------| + | {ruta} | {import/extends/uses} | +``` + +### Paso 2: Identificar Dependientes +```yaml +accion: "Identificar archivos que importan o usan el archivo a modificar" +descripcion: "Estos son los archivos que DEPENDEN del archivo a modificar" + +comandos: + buscar_imports: + - grep -rn "from.*{nombre_modulo}" apps/ libs/ src/ + - grep -rn "import.*{NombreClase}" apps/ libs/ src/ + - grep -rn "require.*{nombre}" apps/ libs/ src/ + + buscar_uso: + - grep -rn "{NombreClase}" apps/ libs/ src/ --include="*.ts" + - grep -rn "{nombre_funcion}\(" apps/ libs/ src/ + + buscar_referencias_bd: + - grep -rn "REFERENCES.*{tabla}" database/ + - grep -rn "{tabla}\." apps/ libs/ src/ + +output: + formato: | + ## Dependientes (los que dependen de este) + | Archivo | Linea | Tipo de Uso | + |---------|-------|-------------| + | {ruta} | {linea} | {import/call/extends} | +``` + +### Paso 3: Evaluar Impacto +```yaml +accion: "Clasificar el nivel de impacto del cambio" + +clasificacion: + ALTO: + condiciones: + - Mas de 5 dependientes + - Cambio es breaking (firma, estructura, nombre) + - Afecta multiples capas (DB + BE + FE) + - Afecta modulo compartido + acciones: + - Listar TODOS los archivos afectados + - Incluir actualizacion de dependientes en plan + - Considerar migracion gradual + - Verificar tests existentes + + MEDIO: + condiciones: + - 2-5 dependientes + - Cambio es aditivo (nuevo campo, nueva funcion) + - Afecta una capa principalmente + acciones: + - Listar archivos afectados + - Evaluar si dependientes necesitan cambios + - Actualizar tests si existen + + BAJO: + condiciones: + - 0-1 dependientes + - Cambio interno (no afecta API publica) + - Refactoring sin cambio de comportamiento + acciones: + - Proceder con precaucion normal + - Verificar build y lint +``` + +### Paso 4: Generar Plan de Modificacion +```yaml +accion: "Proponer orden de modificacion basado en dependencias" + +reglas_orden: + 1. Modificar dependencias primero (lo que importa) + 2. Modificar archivo principal + 3. Modificar dependientes (los que importan) + 4. Actualizar tests + 5. Validar build completo + +ejemplo: + si_modifica: "UserEntity" + orden_sugerido: + 1. user.entity.ts (archivo principal) + 2. user.service.ts (usa UserEntity) + 3. user.controller.ts (usa UserService) + 4. user.dto.ts (si hay cambios de estructura) + 5. user.spec.ts (tests) + 6. components usando user (frontend) +``` + +--- + +## Formato de Reporte + +```markdown +## Analisis de Dependencias + +### Archivo a Modificar +- Ruta: {ruta_completa} +- Tipo: {entity|service|component|table|...} +- Proyecto: {proyecto} + +### Tipo de Cambio +- Descripcion: {que se va a cambiar} +- Breaking: {SI | NO} +- Afecta API Publica: {SI | NO} + +### Dependencias (de los que depende) +| # | Archivo | Tipo | +|---|---------|------| +| 1 | {ruta} | {import/extends} | + +### Dependientes (los que dependen de este) +| # | Archivo | Linea | Tipo de Uso | Requiere Cambio | +|---|---------|-------|-------------|-----------------| +| 1 | {ruta} | {n} | {import} | {SI/NO/EVALUAR} | + +### Clasificacion de Impacto +**Nivel: {ALTO | MEDIO | BAJO}** + +Razon: {explicacion} + +### Plan de Modificacion Sugerido +1. {paso_1} +2. {paso_2} +... + +### Archivos a Incluir en el Plan +- [ ] {archivo_1} +- [ ] {archivo_2} +... + +### Advertencias +{lista_de_advertencias_si_aplica} +``` + +--- + +## Casos Especiales + +### Cambio en Entity de Base de Datos +```yaml +si_modifica: "*.entity.ts" +buscar_adicional: + - Archivo de migracion relacionado + - DTOs que exponen la entity + - Services que usan la entity + - Controllers que exponen endpoints + - Componentes frontend que muestran datos + +verificar: + - Coherencia con esquema DDL + - Migracion necesaria si es produccion + - Validaciones en DTOs +``` + +### Cambio en Tabla DDL +```yaml +si_modifica: "*.sql (CREATE TABLE, ALTER TABLE)" +buscar_adicional: + - Entity correspondiente en backend + - Otras tablas con FOREIGN KEY + - Vistas que usan la tabla + - Funciones/triggers que referencian + +verificar: + - Script recreate-database.sh actualizado + - Migracion para produccion + - Seed data si aplica +``` + +### Cambio en Servicio Compartido +```yaml +si_modifica: "shared/modules/*.ts" +buscar_adicional: + - Todos los proyectos que importan el modulo + - Proyectos en projects/ que usan shared/ + +alerta: | + ATENCION: Cambio en modulo compartido. + Este cambio puede afectar multiples proyectos. + + Considerar: + 1. Versionado del modulo + 2. Cambio backward-compatible si es posible + 3. Propagacion coordinada a proyectos +``` + +--- + +## Ejemplos de Ejecucion + +### Ejemplo 1: Modificar Entity +``` +Usuario: Modificar UserEntity para agregar campo email_verified + +Sistema: +== TRIGGER-ANALISIS-DEPENDENCIAS ACTIVADO == + +### Archivo a Modificar +- Ruta: apps/api/src/modules/users/entities/user.entity.ts +- Tipo: Entity + +### Dependencias +| Archivo | Tipo | +|---------|------| +| typeorm | import | +| base.entity.ts | extends | + +### Dependientes (12 encontrados) +| Archivo | Linea | Tipo | Requiere Cambio | +|---------|-------|------|-----------------| +| user.service.ts | 5 | import | EVALUAR | +| user.controller.ts | 8 | import | NO | +| auth.service.ts | 12 | import | NO | +| create-user.dto.ts | 3 | reference | SI | +| update-user.dto.ts | 3 | reference | SI | +| user.spec.ts | 10 | import | SI | +... (6 mas) + +### Impacto: ALTO (>5 dependientes, cambio de estructura) + +### Plan Sugerido +1. Actualizar user.entity.ts (agregar campo) +2. Actualizar create-user.dto.ts (agregar campo opcional) +3. Actualizar update-user.dto.ts (agregar campo) +4. Actualizar user.spec.ts (agregar tests) +5. Verificar migracion de BD necesaria +6. Build + lint + test +``` + +### Ejemplo 2: Cambio Bajo Impacto +``` +Usuario: Refactorizar metodo interno en PaymentService + +Sistema: +== TRIGGER-ANALISIS-DEPENDENCIAS ACTIVADO == + +### Archivo a Modificar +- Ruta: apps/api/src/modules/payments/payment.service.ts +- Tipo: Service + +### Dependientes (2 encontrados) +| Archivo | Tipo | Requiere Cambio | +|---------|------|-----------------| +| payment.controller.ts | import | NO (metodo interno) | +| payment.spec.ts | import | EVALUAR (tests) | + +### Impacto: BAJO (metodo interno, no afecta API publica) + +### Plan Sugerido +1. Refactorizar metodo en payment.service.ts +2. Actualizar tests si cambia comportamiento +3. Build + lint +``` + +--- + +## Integracion con Modos + +### En MODE-FULL +- Se ejecuta siempre en Fase A +- Resultado incluido en plan de Fase P + +### En MODE-QUICK +- NO se ejecuta (cambios menores no requieren) +- Si build falla, escalar a MODE-FULL + +### En MODE-ANALYSIS +- Se ejecuta para generar reporte de impacto +- No se incluye plan de ejecucion + +--- + +*TRIGGER-ANALISIS-DEPENDENCIAS v1.0.0 - Sistema SAAD* diff --git a/orchestration/directivas/triggers/TRIGGER-ANTI-DUPLICACION.md b/orchestration/directivas/triggers/TRIGGER-ANTI-DUPLICACION.md new file mode 100644 index 0000000..b04b942 --- /dev/null +++ b/orchestration/directivas/triggers/TRIGGER-ANTI-DUPLICACION.md @@ -0,0 +1,282 @@ +# TRIGGER-ANTI-DUPLICACION + +**ID:** TRIGGER-ANTI-DUPLICACION +**Version:** 1.0.0 +**Tipo:** Automatico +**Fase CAPVED:** Se activa en Fase A (Analisis) + +--- + +## Proposito + +Prevenir la creacion de objetos duplicados verificando automaticamente el +catalogo global y los inventarios del proyecto antes de crear cualquier +archivo, componente, servicio, entidad o tabla nueva. + +--- + +## Cuando Se Activa + +```yaml +activadores: + palabras_clave: + - "crear" + - "nuevo" + - "agregar" + - "implementar" + - "anadir" + - "generar" + + tipos_objeto: + - tabla (DDL) + - entity + - service + - controller + - componente + - hook + - modulo + - funcionalidad + + ejemplos: + - "Crear nueva tabla de usuarios" + - "Agregar entidad PaymentMethod" + - "Implementar servicio de notificaciones" + - "Nuevo componente de dashboard" +``` + +--- + +## Acciones del Trigger + +### Paso 1: Verificar Catalogo Global +```yaml +accion: "Buscar en catalogo de funcionalidades reutilizables" +comando: | + grep -i "{funcionalidad}" shared/catalog/CATALOG-INDEX.yml + +catalogo_contiene: + - auth (autenticacion y autorizacion) + - session-management (gestion de sesiones) + - rate-limiting (limitacion de tasa) + - notifications (notificaciones email/push) + - multi-tenancy (soporte multi-tenant) + - feature-flags (flags dinamicos) + - websocket (comunicacion tiempo real) + - payments (integracion pagos) + - audit-logs (auditoria) + - portales (templates de portales) + - template-saas (template SaaS completo) + +si_existe_en_catalogo: + accion: "DETENER creacion" + mensaje: | + ATENCION: Esta funcionalidad ya existe en el catalogo global. + + Ubicacion: shared/catalog/{funcionalidad}/ + Documentacion: shared/catalog/{funcionalidad}/README.md + + Recomendacion: Usar SIMCO-REUTILIZAR.md para integrar + el modulo existente en lugar de crear uno nuevo. + + Si necesita modificaciones, considerar: + 1. Extender el modulo existente + 2. Contribuir mejoras al catalogo + + Para continuar de todos modos, confirmar explicitamente. +``` + +### Paso 2: Verificar Inventario del Proyecto +```yaml +accion: "Buscar en inventarios del proyecto actual" +comandos: + - grep -i "{nombre}" orchestration/inventarios/MASTER_INVENTORY.yml + - grep -i "{nombre}" orchestration/inventarios/DATABASE_INVENTORY.yml + - grep -i "{nombre}" orchestration/inventarios/BACKEND_INVENTORY.yml + - grep -i "{nombre}" orchestration/inventarios/FRONTEND_INVENTORY.yml + +si_existe_en_inventario: + accion: "DETENER creacion" + mensaje: | + ATENCION: Ya existe un objeto similar en este proyecto. + + Nombre: {nombre_existente} + Tipo: {tipo} + Ubicacion: {ruta} + + Opciones: + 1. Reutilizar el existente + 2. Extender el existente + 3. Renombrar el nuevo si es diferente + + Para continuar, clarificar la diferencia. +``` + +### Paso 3: Buscar Archivos Similares +```yaml +accion: "Buscar archivos con nombre similar en el codigo" +comandos: + - find apps/ libs/ -name "*{nombre}*" -type f + - find src/ -name "*{nombre}*" -type f + - grep -rn "class {Nombre}" apps/ libs/ src/ + - grep -rn "interface {Nombre}" apps/ libs/ src/ + - grep -rn "CREATE TABLE.*{nombre}" database/ + +si_encuentra_similar: + accion: "ALERTAR y preguntar" + mensaje: | + ATENCION: Se encontraron archivos similares: + + {lista_archivos} + + Por favor confirmar: + 1. Es el mismo objeto? -> Usar el existente + 2. Es diferente? -> Explicar la diferencia + 3. Es un duplicado a consolidar? -> Usar @DELETE-SAFE primero +``` + +### Paso 4: Evaluar Resultado +```yaml +matriz_decision: + existe_en_catalogo: + accion: "REUTILIZAR del catalogo" + simco: "SIMCO-REUTILIZAR.md" + + no_encontrado: + accion: "PROCEDER a crear" + simco: "SIMCO-CREAR.md" + + existe_identico: + accion: "DETENER" + mensaje: "Ya existe, no crear duplicado" + + existe_similar: + accion: "PREGUNTAR" + mensaje: "Clarificar diferencia antes de continuar" +``` + +--- + +## Checklist Rapido Anti-Duplicacion + +Antes de crear cualquier objeto nuevo, verificar: + +```markdown +[ ] Busque funcionalidad en shared/catalog/CATALOG-INDEX.yml +[ ] Busque "{nombre}" en orchestration/inventarios/ +[ ] Busque archivos con find en apps/ y src/ +[ ] Busque definiciones con grep (class, interface, CREATE TABLE) +[ ] Confirme que NO existe en catalogo NI en proyecto +[ ] Si existe en catalogo, use SIMCO-REUTILIZAR.md +[ ] Si existe similar, pregunte que hacer antes de continuar +``` + +--- + +## Formato de Reporte + +Cuando se activa este trigger, generar reporte: + +```markdown +## Verificacion Anti-Duplicacion + +### Objeto a Crear +- Nombre: {nombre} +- Tipo: {tabla|entity|service|component|...} +- Proyecto: {proyecto} + +### Resultado Catalogo Global +- Estado: {ENCONTRADO | NO_ENCONTRADO} +- Detalles: {ubicacion si encontrado} + +### Resultado Inventario Proyecto +- Estado: {ENCONTRADO | NO_ENCONTRADO} +- Detalles: {nombre y ubicacion si encontrado} + +### Resultado Busqueda Codigo +- Estado: {ENCONTRADO | NO_ENCONTRADO} +- Archivos similares: {lista si encontrados} + +### Decision +- [ ] PROCEDER: No se encontraron duplicados +- [ ] REUTILIZAR: Usar modulo del catalogo +- [ ] DETENER: Ya existe en proyecto +- [ ] CONSULTAR: Existe similar, clarificar +``` + +--- + +## Excepciones + +### Cuando NO aplicar este trigger +```yaml +excepciones: + - Archivos de configuracion (no son objetos reutilizables) + - Tests (cada modulo tiene sus propios tests) + - Documentacion (puede haber docs similares) + - Migraciones de BD (tienen timestamp unico) +``` + +--- + +## Integracion con SIMCO + +### Si se encuentra en catalogo +```yaml +siguiente_paso: "Leer SIMCO-REUTILIZAR.md" +acciones: + 1. Leer documentacion del modulo en catalogo + 2. Verificar compatibilidad con proyecto + 3. Seguir instrucciones de integracion + 4. Registrar uso en inventario +``` + +### Si no se encuentra +```yaml +siguiente_paso: "Leer SIMCO-CREAR.md" +acciones: + 1. Proceder con creacion normal + 2. Seguir principio Doc-Primero + 3. Registrar en inventario al crear + 4. Evaluar si debe agregarse al catalogo +``` + +--- + +## Ejemplo de Ejecucion + +``` +Usuario: Crear servicio de autenticacion para erp-construccion + +Sistema: +== TRIGGER-ANTI-DUPLICACION ACTIVADO == + +Paso 1: Verificando catalogo global... + Buscando: "auth" en shared/catalog/CATALOG-INDEX.yml + ENCONTRADO: shared/catalog/auth/ + +Paso 2: Verificando inventario... + (No aplica - se encontro en catalogo) + +Paso 3: Busqueda codigo... + (No aplica - se encontro en catalogo) + +== RESULTADO == +DETENIDO: Funcionalidad existe en catalogo global. + +Ubicacion: shared/catalog/auth/ +Contenido: + - NestJS + JWT + Passport + - Guards, strategies, decorators + - Documentacion completa + +Recomendacion: + Usar SIMCO-REUTILIZAR.md para integrar el modulo + de autenticacion del catalogo. + + Comando sugerido: + @CREATE-SAFE Integrar modulo auth del catalogo en erp-construccion +``` + +--- + +*TRIGGER-ANTI-DUPLICACION v1.0.0 - Sistema SAAD* diff --git a/orchestration/directivas/triggers/TRIGGER-CIERRE-TAREA-OBLIGATORIO.md b/orchestration/directivas/triggers/TRIGGER-CIERRE-TAREA-OBLIGATORIO.md new file mode 100644 index 0000000..8fad979 --- /dev/null +++ b/orchestration/directivas/triggers/TRIGGER-CIERRE-TAREA-OBLIGATORIO.md @@ -0,0 +1,267 @@ +# TRIGGER: CIERRE DE TAREA OBLIGATORIO + +**Versión:** 1.0.0 +**Fecha:** 2026-01-16 +**Sistema:** SIMCO v4.0.0 +**Alias:** @TRIGGER_CIERRE + +--- + +## RESUMEN EJECUTIVO + +Este trigger OBLIGA la ejecución del checklist post-tarea (@DEF_CHK_POST) antes de que cualquier tarea pueda ser marcada como completada. + +**PRINCIPIO:** "Una tarea no está completada hasta que su checklist de cierre esté 100% verificado." + +--- + +## CONDICIONES DE ACTIVACIÓN + +```yaml +activar_cuando: + - Agente intenta marcar tarea como "completada" + - Agente dice "tarea finalizada" o variantes + - Agente termina la última subtarea del plan + - Agente declara "Done" o "DONE" + - Agente reporta que terminó el trabajo + +palabras_clave_trigger: + - "completada" + - "finalizada" + - "terminada" + - "Done" + - "DONE" + - "tarea cerrada" + - "trabajo terminado" + - "implementación completa" +``` + +--- + +## ACCIÓN REQUERIDA + +### Secuencia Obligatoria + +``` +AGENTE DECLARA TAREA TERMINADA + │ + ▼ +┌─────────────────────────────────────┐ +│ 1. DETENER │ +│ No marcar como completada aún │ +└─────────────────┬───────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ 2. CARGAR @DEF_CHK_POST │ +│ CHECKLIST-POST-TASK.md │ +└─────────────────┬───────────────────┘ + │ + ▼ +┌─────────────────────────────────────┐ +│ 3. EJECUTAR CHECKLIST │ +│ - Gobernanza (BLOQUEANTE) │ +│ - Validaciones técnicas │ +│ - Coherencia entre capas │ +│ - Inventarios │ +│ - Trazas │ +│ - Propagación │ +└─────────────────┬───────────────────┘ + │ + ▼ + ┌───────────────┐ + │ ¿TODOS PASAN? │ + └───────┬───────┘ + / \ + Sí No + │ │ + ▼ ▼ +┌──────────────┐ ┌──────────────────────┐ +│ 4. MARCAR │ │ 4. MANTENER EN │ +│ COMPLETADA │ │ PROGRESO │ +└──────────────┘ │ │ + │ - Documentar items │ + │ faltantes │ + │ - Completar antes │ + │ de cerrar │ + └──────────────────────┘ +``` + +--- + +## CHECKLIST RÁPIDO DE CIERRE + +```markdown +## Verificación Pre-Cierre (@DEF_CHK_POST) + +### 0. Gobernanza (BLOQUEANTE - SI FALLA, NO CONTINUAR) +[ ] Carpeta de tarea existe: orchestration/tareas/TASK-{ID}/ +[ ] METADATA.yml completo con fases C, E, D +[ ] _INDEX.yml de tareas actualizado + +### 1. Validaciones Técnicas +[ ] Build pasa (backend y/o frontend según aplique) +[ ] Lint pasa +[ ] Tests pasan (si existen) + +### 2. Coherencia Entre Capas +[ ] DDL ↔ Backend coherente (o excepciones documentadas) +[ ] Backend ↔ Frontend coherente (si aplica) + +### 3. Inventarios Actualizados +[ ] DATABASE_INVENTORY.yml (si cambió BD) +[ ] BACKEND_INVENTORY.yml (si cambió BE) +[ ] FRONTEND_INVENTORY.yml (si cambió FE) +[ ] MASTER_INVENTORY.yml (siempre) + +### 4. Trazas Actualizadas +[ ] Traza de tarea correspondiente actualizada +[ ] PROXIMA-ACCION.md actualizado + +### 5. Propagación Evaluada +[ ] ¿Cambio debe propagarse a otros proyectos? (evaluar) +[ ] Si aplica: propagación ejecutada o documentada como pendiente +``` + +--- + +## BLOQUEO + +### SI el checklist NO pasa: + +```yaml +accion: "BLOQUEAR cierre de tarea" +estado: "EN PROGRESO" +mensaje: | + Tarea NO puede ser marcada como completada. + Items faltantes del checklist: + - [listar items que fallaron] + + Acción requerida: + - Completar items faltantes + - Re-ejecutar checklist + - Solo entonces marcar como completada + +reintentar: "Después de completar items faltantes" +``` + +### Items BLOQUEANTES (no negociables): + +```yaml +bloqueantes_absolutos: + - Gobernanza (carpeta + METADATA + _INDEX) + - Build que falla + - Tests que fallan + +advertencias_serias: + - Inventarios desactualizados + - Trazas desactualizadas + - Coherencia no verificada + +advertencias_menores: + - Propagación no evaluada (si proyecto aislado) +``` + +--- + +## INTEGRACIÓN CON OTROS TRIGGERS + +```yaml +secuencia_de_triggers: + 1: "Agente ejecuta trabajo" + 2: "Agente intenta cerrar tarea" + 3: "→ TRIGGER-CIERRE-TAREA-OBLIGATORIO se activa" + 4: "→ Carga @DEF_CHK_POST" + 5: "→ TRIGGER-INVENTARIOS-SINCRONIZADOS verifica inventarios" + 6: "→ TRIGGER-COHERENCIA-CAPAS verifica coherencia" + 7: "→ TRIGGER-DOCUMENTACION-OBLIGATORIA verifica gobernanza" + 8: "Si todo pasa: tarea = COMPLETADA" + 9: "Si algo falla: tarea = EN PROGRESO" + +dependencias: + - "@TRIGGER_INVENTARIOS" + - "@TRIGGER_COHERENCIA" + - "@TRIGGER_DOC" +``` + +--- + +## MENSAJES ESTÁNDAR + +### Al detectar intento de cierre: + +``` +⚠️ TRIGGER-CIERRE-TAREA-OBLIGATORIO activado + +Antes de marcar la tarea como completada, debo ejecutar el checklist post-tarea. + +Ejecutando @DEF_CHK_POST... +``` + +### Si todo pasa: + +``` +✅ Checklist post-tarea completado exitosamente + +Verificaciones: +- [✓] Gobernanza +- [✓] Validaciones técnicas +- [✓] Coherencia entre capas +- [✓] Inventarios sincronizados +- [✓] Trazas actualizadas +- [✓] Propagación evaluada + +TAREA MARCADA COMO COMPLETADA +``` + +### Si algo falla: + +``` +❌ Checklist post-tarea NO completado + +Items faltantes: +- [ ] {item que falló} +- [ ] {otro item que falló} + +Acción: Completar items faltantes antes de cerrar. +Estado: EN PROGRESO (no completada) +``` + +--- + +## EXCEPCIONES + +```yaml +excepciones_permitidas: + tareas_triviales: + - Corrección de typos + - Actualización de comentarios + - Cambios cosméticos + checklist_reducido: + - Solo Gobernanza + - Solo Validación build + + investigación_pura: + - Análisis sin cambios de código + - Spikes exploratorios + checklist_reducido: + - Solo documentación de hallazgos + +nota: "Incluso excepciones DEBEN documentar en trazas" +``` + +--- + +## REFERENCIAS + +| Alias | Archivo | +|-------|---------| +| @DEF_CHK_POST | orchestration/_definitions/checklists/CHECKLIST-POST-TASK.md | +| @TRIGGER_INVENTARIOS | orchestration/directivas/triggers/TRIGGER-INVENTARIOS-SINCRONIZADOS.md | +| @TRIGGER_COHERENCIA | orchestration/directivas/triggers/TRIGGER-COHERENCIA-CAPAS.md | +| @TRIGGER_DOC | orchestration/directivas/triggers/TRIGGER-DOCUMENTACION-OBLIGATORIA.md | +| @CAPVED | orchestration/directivas/principios/PRINCIPIO-CAPVED.md | + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Trigger de Cierre Obligatorio diff --git a/orchestration/directivas/triggers/TRIGGER-COHERENCIA-CAPAS.md b/orchestration/directivas/triggers/TRIGGER-COHERENCIA-CAPAS.md new file mode 100644 index 0000000..39b14fa --- /dev/null +++ b/orchestration/directivas/triggers/TRIGGER-COHERENCIA-CAPAS.md @@ -0,0 +1,311 @@ +# TRIGGER: COHERENCIA ENTRE CAPAS + +**Versión:** 1.0.0 +**Fecha:** 2026-01-16 +**Sistema:** SIMCO v4.0.0 +**Alias:** @TRIGGER_COHERENCIA + +--- + +## RESUMEN EJECUTIVO + +Este trigger OBLIGA a mantener coherencia entre las capas DDL, Backend y Frontend. Se activa automáticamente cuando se crea o modifica cualquier objeto en cualquier capa. + +**PRINCIPIO:** "Ninguna capa puede tener objetos huérfanos. Todo DDL debe tener entity, todo entity que requiera persistencia debe tener DDL." + +--- + +## CONDICIONES DE ACTIVACIÓN + +```yaml +activar_cuando: + DDL: + - Se crea nueva tabla (CREATE TABLE) + - Se modifica estructura de tabla (ALTER TABLE) + - Se crea nuevo schema + - Se elimina tabla o schema + + Backend: + - Se crea nueva entity + - Se modifica entity existente + - Se crea nuevo módulo + - Se elimina entity o módulo + + Frontend: + - Se crea componente que consume endpoint nuevo + - Se crea store/hook que requiere datos de API +``` + +--- + +## VERIFICACIONES OBLIGATORIAS + +### 1. Al Crear Tabla DDL + +```yaml +ANTES_de_completar_tarea: + verificar: + - "¿Existe entity correspondiente en backend?" + - "¿Entity tiene mismos campos que tabla?" + - "¿Tipos de datos son compatibles (PostgreSQL ↔ TypeScript)?" + - "¿Está documentada en DATABASE_INVENTORY.yml?" + - "¿Está documentada en ENTITIES-CATALOG.md?" + + si_no_existe_entity: + accion: "BLOQUEAR hasta crear entity" + excepcion: "Tablas de relación M:N pueden no tener entity si están documentadas como tal" + + si_no_documentada: + accion: "BLOQUEAR hasta documentar en inventarios" +``` + +### 2. Al Crear Entity + +```yaml +ANTES_de_completar_tarea: + verificar: + - "¿Existe tabla DDL correspondiente?" + - "¿Campos coinciden con DDL?" + - "¿Decoradores TypeORM son correctos?" + - "¿Está documentada en BACKEND_INVENTORY.yml?" + - "¿Está documentada en ENTITIES-CATALOG.md?" + + si_no_existe_tabla: + accion: "BLOQUEAR hasta crear tabla DDL" + excepcion: "Entities de solo lectura (views) deben estar documentadas" + + si_no_documentada: + accion: "BLOQUEAR hasta documentar en inventarios" +``` + +### 3. Al Crear Módulo Backend + +```yaml +ANTES_de_completar_tarea: + verificar: + - "¿Todas las entities del módulo tienen tabla DDL?" + - "¿Módulo está documentado en MODULES-CATALOG.md?" + - "¿Servicios están documentados en SERVICES-CATALOG.md?" + - "¿Endpoints están documentados en QUICK-API.yml?" + + si_incompleto: + accion: "BLOQUEAR hasta completar documentación" +``` + +### 4. Al Crear Schema DDL + +```yaml +ANTES_de_completar_tarea: + verificar: + - "¿Schema tiene al menos un módulo backend correspondiente?" + - "¿Schema está documentado en DATABASE-SCHEMA.md?" + - "¿Schema está en DATABASE_INVENTORY.yml?" + + si_schema_vacio: + accion: "ADVERTIR - Schema sin tablas debe tener plan de uso" + + si_no_documentado: + accion: "BLOQUEAR hasta documentar" +``` + +--- + +## MATRIZ DE COHERENCIA + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ MATRIZ DE COHERENCIA │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ DDL (Schema/Tabla) │ +│ │ │ +│ ▼ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ Tabla │────▶│ Entity │────▶│ Service │ │ +│ │ DDL │ │ TypeORM │ │ NestJS │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ │ │ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ DATABASE_ │ │ BACKEND_ │ │ QUICK- │ │ +│ │ INVENTORY │ │ INVENTORY │ │ API.yml │ │ +│ └─────────────┘ └─────────────┘ └─────────────┘ │ +│ │ │ │ │ +│ └───────────────────┼───────────────────┘ │ +│ ▼ │ +│ ┌─────────────────┐ │ +│ │ ENTITIES-CATALOG│ │ +│ │ MODULES-CATALOG │ │ +│ │ SERVICES-CATALOG│ │ +│ └─────────────────┘ │ +│ │ +│ REGLA: Cada flecha representa una DEPENDENCIA OBLIGATORIA │ +│ No puede existir ningún nodo sin sus dependencias │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## EXCEPCIONES PERMITIDAS + +```yaml +excepciones: + tablas_sin_entity: + - tipo: "Tablas de relación M:N gestionadas por TypeORM" + requisito: "Documentar en ENTITIES-CATALOG.md sección 'Relaciones'" + ejemplo: "user_roles, permission_roles" + + - tipo: "Tablas de auditoría automática" + requisito: "Documentar en DATABASE-SCHEMA.md sección 'Audit'" + ejemplo: "audit_logs, activity_logs" + + - tipo: "Tablas de sistema/migración" + requisito: "Documentar en DATABASE-SCHEMA.md sección 'System'" + ejemplo: "migrations, typeorm_metadata" + + entities_sin_tabla: + - tipo: "View entities (solo lectura)" + requisito: "Documentar como @ViewEntity con query" + ejemplo: "UserStatsView, DashboardSummaryView" + + - tipo: "Entities embebidas" + requisito: "Documentar como @Embeddable" + ejemplo: "AddressEmbed, MetadataEmbed" + + schemas_sin_modulo: + - tipo: "Schemas planificados (FUTURE)" + requisito: "Documentar en DATABASE_INVENTORY con estado='PLANNED'" + requisito_2: "Crear issue/ticket de implementación" +``` + +--- + +## FLUJO DE VALIDACIÓN + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ FLUJO DE VALIDACIÓN │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ 1. Agente completa tarea │ +│ │ │ +│ ▼ │ +│ 2. TRIGGER-COHERENCIA-CAPAS se activa │ +│ │ │ +│ ▼ │ +│ 3. Detectar tipo de cambio (DDL/BE/FE) │ +│ │ │ +│ ▼ │ +│ 4. Ejecutar verificaciones según tipo │ +│ │ │ +│ ├──── SI PASA ────▶ 5a. Permitir completar tarea │ +│ │ │ +│ └──── SI FALLA ───▶ 5b. BLOQUEAR y reportar gaps │ +│ │ │ +│ ▼ │ +│ 6. Agente debe: │ +│ - Crear objetos faltantes │ +│ - Documentar en inventarios │ +│ - Re-ejecutar validación │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## CHECKLIST DE COHERENCIA + +### Para Cambios DDL + +```markdown +[ ] Tabla tiene entity correspondiente en backend +[ ] Campos de entity coinciden con columnas de tabla +[ ] Tipos de datos son compatibles +[ ] Tabla documentada en DATABASE_INVENTORY.yml +[ ] Schema documentado en DATABASE-SCHEMA.md +[ ] Entity documentada en ENTITIES-CATALOG.md +``` + +### Para Cambios Backend + +```markdown +[ ] Entity tiene tabla DDL correspondiente +[ ] Campos coinciden con DDL +[ ] Módulo documentado en MODULES-CATALOG.md +[ ] Servicios documentados en SERVICES-CATALOG.md +[ ] Entity documentada en BACKEND_INVENTORY.yml +[ ] Endpoints documentados en QUICK-API.yml +``` + +### Para Nuevo Schema + +```markdown +[ ] Schema tiene módulo backend planificado o existente +[ ] Schema documentado en DATABASE-SCHEMA.md +[ ] Schema en DATABASE_INVENTORY.yml +[ ] Si no tiene módulo: documentar como PLANNED con fecha estimada +``` + +--- + +## INTEGRACIÓN CON OTROS TRIGGERS + +```yaml +secuencia_triggers: + 1: "TRIGGER-ANTI-DUPLICACION" # Verificar no existe + 2: "TRIGGER-ANALISIS-DEPENDENCIAS" # Mapear impacto + 3: "TRIGGER-COHERENCIA-CAPAS" # ← ESTE TRIGGER + 4: "TRIGGER-DOCUMENTACION-OBLIGATORIA" # Documentar + +orden: "TRIGGER-COHERENCIA-CAPAS se ejecuta ANTES de TRIGGER-DOC" +razon: "No se puede documentar algo que no está coherente" +``` + +--- + +## MENSAJES DE ERROR + +```yaml +errores: + E-COH-001: + mensaje: "Tabla DDL sin entity correspondiente" + accion: "Crear entity antes de completar tarea" + bloqueante: true + + E-COH-002: + mensaje: "Entity sin tabla DDL" + accion: "Crear tabla DDL o documentar como excepción" + bloqueante: true + + E-COH-003: + mensaje: "Schema sin módulo backend" + accion: "Crear módulo o documentar como PLANNED" + bloqueante: true + + E-COH-004: + mensaje: "Objeto no documentado en inventario" + accion: "Actualizar inventario correspondiente" + bloqueante: true + + E-COH-005: + mensaje: "Discrepancia de campos DDL ↔ Entity" + accion: "Sincronizar campos entre DDL y Entity" + bloqueante: true +``` + +--- + +## REFERENCIAS + +| Alias | Descripción | +|-------|-------------| +| @TRIGGER_COHERENCIA | Este trigger | +| @DEF_CHK_POST | Checklist post-tarea | +| @TRIGGER-DOC | Documentación obligatoria | +| @SIMCO-VALIDAR | Directiva de validación | + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Trigger Preventivo diff --git a/orchestration/directivas/triggers/TRIGGER-COMMIT-PUSH-OBLIGATORIO.md b/orchestration/directivas/triggers/TRIGGER-COMMIT-PUSH-OBLIGATORIO.md new file mode 100644 index 0000000..f8e54b7 --- /dev/null +++ b/orchestration/directivas/triggers/TRIGGER-COMMIT-PUSH-OBLIGATORIO.md @@ -0,0 +1,151 @@ +# TRIGGER: Commit y Push Obligatorio + +**Version:** 1.0.0 +**Fecha:** 2026-01-16 +**Tipo:** AUTOMATICO +**Prioridad:** CRITICA + +--- + +## ACTIVACION + +Este trigger se activa AUTOMATICAMENTE cuando: + +1. Se completa una tarea que creo o modifico archivos +2. Se marca un todo como "completed" +3. Se reporta al usuario que una tarea esta finalizada +4. Se cambia de contexto a otra tarea +5. Antes de finalizar una sesion de trabajo + +--- + +## ACCION OBLIGATORIA + +``` +╔══════════════════════════════════════════════════════════════════════════╗ +║ ║ +║ ANTES DE REPORTAR TAREA COMPLETADA: ║ +║ ║ +║ 1. Ejecutar: git status ║ +║ - Si hay cambios pendientes -> continuar ║ +║ - Si esta limpio -> verificar que push se hizo ║ +║ ║ +║ 2. Si hay cambios: ║ +║ git add . ║ +║ git commit -m "[TAREA-ID] tipo: descripcion" ║ +║ git push origin main ║ +║ ║ +║ 3. Si hay SUBMODULES modificados: ║ +║ - Commitear y push en CADA submodule primero ║ +║ - Luego actualizar workspace principal ║ +║ ║ +║ 4. Verificar sincronizacion: ║ +║ git log origin/main..HEAD --oneline ║ +║ - Debe estar VACIO (sin commits pendientes de push) ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## SECUENCIA WORKSPACE-V2 + +El workspace-v2 usa submodules. Secuencia obligatoria: + +```bash +# PASO 1: Identificar submodules modificados +cd /home/isem/workspace-v2 +git status + +# PASO 2: Para CADA submodule con cambios +cd projects/{submodule} +git add . +git commit -m "[{submodule}] tipo: descripcion" +git push origin main +cd ../.. + +# PASO 3: Actualizar workspace principal +git add . +git commit -m "[WORKSPACE] chore: descripcion de cambios" +git push origin main + +# PASO 4: Verificar TODO sincronizado +git status # Debe mostrar "clean" +git submodule foreach 'git status' # Todos deben estar "clean" +``` + +--- + +## ERRORES A EVITAR + +| Error | Consecuencia | Prevencion | +|-------|--------------|------------| +| No hacer push | Archivos solo en local | Siempre push despues de commit | +| Olvidar submodules | Referencias desincronizadas | Commitear submodules primero | +| Reportar sin verificar | Usuario cree que esta hecho | Verificar git status antes | +| Commitear sin push | Cambios no en remoto | Push inmediato tras commit | + +--- + +## VERIFICACION RAPIDA + +```bash +# Comando unico para verificar todo sincronizado +git status && git log origin/main..HEAD --oneline + +# Salida esperada: +# On branch main +# Your branch is up to date with 'origin/main'. +# nothing to commit, working tree clean +# (sin output del log = todo pusheado) +``` + +--- + +## INTEGRACION CON CAPVED + +Este trigger se ejecuta en: + +- **Fase E (Ejecucion):** Commit atomico por cada cambio logico +- **Fase D (Documentacion):** Commit final con documentacion +- **Post-Tarea:** Push OBLIGATORIO antes de reportar completado + +```yaml +fase_D_documentacion: + ultimo_paso: "Commit + Push de todos los cambios" + verificacion: "git status clean + git log empty" + reportar_solo_si: "Todo sincronizado con remoto" +``` + +--- + +## MENSAJE AL AGENTE + +``` +╔══════════════════════════════════════════════════════════════════════════╗ +║ ║ +║ RECUERDA: Una tarea NO esta completa hasta que: ║ +║ ║ +║ 1. Todos los archivos estan GUARDADOS en disco ║ +║ 2. Todos los cambios estan COMMITEADOS ║ +║ 3. Todos los commits estan PUSHEADOS al remoto ║ +║ 4. git status muestra "working tree clean" ║ +║ 5. git log origin/main..HEAD esta VACIO ║ +║ ║ +║ SIN PUSH = TRABAJO PERDIDO POTENCIAL ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## REFERENCIAS + +- SIMCO-GIT.md - Directiva principal de control de versiones +- PRINCIPIO-CAPVED.md - Ciclo de vida de tareas +- SIMCO-TAREA.md - Punto de entrada de tareas + +--- + +**Sistema:** SIMCO v4.0.0 +**Mantenido por:** Workspace Admin diff --git a/orchestration/directivas/triggers/TRIGGER-FETCH-OBLIGATORIO.md b/orchestration/directivas/triggers/TRIGGER-FETCH-OBLIGATORIO.md new file mode 100644 index 0000000..d960cd9 --- /dev/null +++ b/orchestration/directivas/triggers/TRIGGER-FETCH-OBLIGATORIO.md @@ -0,0 +1,178 @@ +# TRIGGER: Fetch Obligatorio Antes de Operar + +**Version:** 1.0.0 +**Fecha:** 2026-01-16 +**Tipo:** AUTOMATICO +**Prioridad:** CRITICA +**Incidente de Origen:** INC-2026-01-16-001 + +--- + +## ACTIVACION + +Este trigger se activa AUTOMATICAMENTE cuando: + +1. Se inicia una sesion de trabajo en el workspace +2. Se va a verificar el estado de git (git status) +3. Se va a realizar cualquier operacion git (commit, push, pull) +4. Se retoma trabajo despues de una pausa +5. Se cambia de contexto entre proyectos/submodulos + +--- + +## ACCION OBLIGATORIA + +``` +╔══════════════════════════════════════════════════════════════════════════╗ +║ ║ +║ ANTES DE VERIFICAR ESTADO O REALIZAR OPERACIONES GIT: ║ +║ ║ +║ 1. Ejecutar: git fetch origin ║ +║ → Obtiene el estado actual del repositorio remoto ║ +║ ║ +║ 2. Verificar: git log HEAD..origin/main --oneline ║ +║ → Si hay output = HAY COMMITS REMOTOS QUE NO TIENES ║ +║ → Si esta vacio = Estas sincronizado ║ +║ ║ +║ 3. Si hay commits remotos: ║ +║ git pull --no-recurse-submodules ║ +║ → Sincroniza tu local con el remoto ║ +║ ║ +║ 4. AHORA SI verificar estado: ║ +║ git status ║ +║ ║ +║ MOTIVO: Otro agente pudo haber hecho cambios en otra sesion. ║ +║ Sin FETCH, reportaras estado incompleto. ║ +║ ║ +╚══════════════════════════════════════════════════════════════════════════╝ +``` + +--- + +## SECUENCIA COMPLETA + +```bash +# PASO 1: Fetch del remoto +git fetch origin + +# PASO 2: Verificar si hay commits remotos no sincronizados +REMOTE_COMMITS=$(git log HEAD..origin/main --oneline) + +# PASO 3: Si hay commits remotos, sincronizar +if [ -n "$REMOTE_COMMITS" ]; then + echo "Commits remotos detectados:" + echo "$REMOTE_COMMITS" + git pull --no-recurse-submodules +fi + +# PASO 4: Ahora verificar estado local +git status +``` + +--- + +## PARA WORKSPACE CON SUBMODULOS + +En workspace-v2 con multiples niveles de submodulos: + +```bash +# NIVEL 0: Workspace principal +cd /home/isem/workspace-v2 +git fetch origin +git log HEAD..origin/main --oneline +# Si hay output: git pull --no-recurse-submodules +git status + +# NIVEL 1: Proyectos (si vas a trabajar en uno) +cd projects/{proyecto} +git fetch origin +git log HEAD..origin/main --oneline +# Si hay output: git pull --no-recurse-submodules +git status + +# NIVEL 2: Subrepositorios (si vas a trabajar en uno) +cd {componente} # backend, database, frontend +git fetch origin +git log HEAD..origin/main --oneline +# Si hay output: git pull --no-recurse-submodules +git status +``` + +--- + +## ERRORES A EVITAR + +| Error | Consecuencia | Prevencion | +|-------|--------------|------------| +| Solo hacer git status | No detectar commits remotos | SIEMPRE fetch primero | +| Reportar "clean" sin fetch | Usuario confundido | Seguir secuencia completa | +| Asumir que no hay cambios | Desincronizacion | Verificar con log HEAD..origin | +| Olvidar en submodulos | Referencias inconsistentes | Fetch en cada nivel | + +--- + +## INCIDENTE DE ORIGEN + +### INC-2026-01-16-001 + +**Descripcion:** Un agente reporto "working tree clean" cuando habia un commit +remoto (c027da53) que no habia sido detectado. + +**Causa Raiz:** No se ejecuto `git fetch` antes de verificar estado con `git status`. + +**Impacto:** Usuario confundido sobre el estado real del repositorio. + +**Resolucion:** +- Creado este trigger obligatorio +- Actualizado SIMCO-GIT.md v1.2.0 con regla critica +- Actualizado SIMCO-SUBMODULOS.md v1.1.0 con secuencia obligatoria +- Documentado en TRAZA-GIT-OPERATIONS.md + +--- + +## VERIFICACION RAPIDA + +```bash +# Comando unico para verificar sincronizacion completa +git fetch origin && git log HEAD..origin/main --oneline && git status + +# Salida esperada si todo sincronizado: +# (sin output del log) +# On branch main +# Your branch is up to date with 'origin/main'. +# nothing to commit, working tree clean +``` + +--- + +## INTEGRACION CON CAPVED + +Este trigger se ejecuta en: + +- **Pre-Tarea:** SIEMPRE antes de iniciar cualquier tarea +- **Pre-Commit:** Antes de hacer commit (verificar no hay conflictos) +- **Pre-Push:** Antes de push (verificar no hay rechazos pendientes) +- **Post-Pausa:** Al retomar trabajo despues de interrupcion + +```yaml +pre_tarea: + primer_paso: "git fetch origin" + verificar: "git log HEAD..origin/main" + sincronizar_si_necesario: "git pull --no-recurse-submodules" + luego: "Continuar con la tarea" +``` + +--- + +## REFERENCIAS + +- `orchestration/directivas/simco/SIMCO-GIT.md` - Directiva principal git (v1.2.0) +- `orchestration/directivas/simco/SIMCO-SUBMODULOS.md` - Protocolo submodulos (v1.1.0) +- `orchestration/SUBMODULES-POLICY.yml` - Politicas de sincronizacion (v1.1.0) +- `orchestration/trazas/TRAZA-GIT-OPERATIONS.md` - Registro de operaciones +- `orchestration/directivas/triggers/TRIGGER-COMMIT-PUSH-OBLIGATORIO.md` - Trigger complementario + +--- + +**Sistema:** SIMCO v4.0.0 +**Mantenido por:** Workspace Admin diff --git a/orchestration/directivas/triggers/TRIGGER-INICIO-TAREA.md b/orchestration/directivas/triggers/TRIGGER-INICIO-TAREA.md new file mode 100644 index 0000000..d8a44c1 --- /dev/null +++ b/orchestration/directivas/triggers/TRIGGER-INICIO-TAREA.md @@ -0,0 +1,160 @@ +# ═══════════════════════════════════════════════════════════════════════════════ +# TRIGGER-INICIO-TAREA +# ═══════════════════════════════════════════════════════════════════════════════ +# +# Version: 1.0.0 +# Creado: 2026-01-16 +# Origen: Auditoría post-tarea TASK-2026-01-16-004 +# Proposito: Garantizar creación de carpeta de tarea ANTES de ejecutar código +# +# ═══════════════════════════════════════════════════════════════════════════════ + +## CONDICION DE ACTIVACION + +Este trigger se activa **AUTOMATICAMENTE** cuando: + +1. Se recibe una solicitud que implica **modificar código** +2. Se recibe una solicitud que implica **crear archivos nuevos** +3. Se usa `@FULL` o `@CREATE-SAFE` o `@MODIFY-SAFE` +4. El primer item de TodoWrite incluye una tarea de implementación + +**EXCEPCION:** No aplica para: +- Modo `@QUICK` en fixes menores (typos, config simple) +- Modo `@ANALYSIS` (solo investigación) +- Tareas puramente de lectura/exploración + +--- + +## ACCION OBLIGATORIA + +### Paso 1: Generar ID de Tarea + +``` +TASK-{YYYY-MM-DD}-{NNN} +``` + +Donde: +- `YYYY-MM-DD`: Fecha actual +- `NNN`: Siguiente secuencial del día (consultar `_INDEX.yml`) + +### Paso 2: Crear Estructura de Carpeta + +```bash +# Ruta base +orchestration/tareas/TASK-{ID}/ + +# Archivos mínimos obligatorios +├── METADATA.yml # Copiar de _templates/TASK-TEMPLATE/ +├── 01-CONTEXTO.md # Llenar con clasificación inicial +└── (otros según avance) +``` + +### Paso 3: Registrar en Inventario + +Agregar entrada en `tareas_activas` de `_INDEX.yml`: + +```yaml +tareas_activas: + - task_id: "TASK-2026-01-XX-NNN" + titulo: "Título descriptivo" + agente: "PERFIL-AGENTE" + estado: "en_progreso" + fase: "C" # Inicia en Contexto + proyecto: "nombre-proyecto" +``` + +### Paso 4: Incluir en TodoWrite + +El **PRIMER item** de TodoWrite debe ser: + +``` +- Crear carpeta de tarea TASK-{ID} en orchestration/tareas/ +``` + +O si ya existe: + +``` +- Documentar contexto en TASK-{ID}/01-CONTEXTO.md +``` + +--- + +## CHECKPOINT DE VALIDACION + +**ANTES de ejecutar cualquier código (fase E):** + +``` +[ ] ¿Existe carpeta orchestration/tareas/TASK-{ID}/? +[ ] ¿Existe METADATA.yml con información básica? +[ ] ¿Se registró en _INDEX.yml como tarea activa? +[ ] ¿TodoWrite incluye la tarea de documentación? +``` + +**SI algún checkbox falla:** BLOQUEAR ejecución hasta completar. + +--- + +## INTEGRACION CON TODOWRITE + +Cuando se use TodoWrite para planificar una tarea de código, incluir SIEMPRE: + +```typescript +// Ejemplo de TodoWrite correcto +[ + { content: "Crear carpeta TASK-2026-01-16-004", status: "pending" }, + { content: "Documentar contexto y clasificación", status: "pending" }, + { content: "Analizar dependencias", status: "pending" }, + // ... tareas técnicas ... + { content: "Actualizar _INDEX.yml al completar", status: "pending" } +] +``` + +--- + +## REFERENCIAS + +- `@TAREAS` - orchestration/tareas/ +- `@NUEVA-TAREA` - orchestration/tareas/_templates/TASK-TEMPLATE/ +- `@TRIGGER-DOC` - TRIGGER-DOCUMENTACION-OBLIGATORIA.md +- `@MAPA-DOC` - orchestration/MAPA-DOCUMENTACION.yml + +--- + +## CASO DE ESTUDIO: TASK-2026-01-16-004 + +Esta directiva nace del análisis post-mortem de la tarea: + +**"Integración de Servicios de API en Trading Platform Frontend"** + +### Problema Detectado +- La tarea se ejecutó correctamente (build pasa, código funcional) +- PERO no se creó carpeta de tarea antes de ejecutar +- No se documentaron fases C, A, P, V formalmente +- No se actualizó _INDEX.yml hasta auditoría posterior + +### Causa Raíz +1. No existía trigger bloqueante para creación de carpeta +2. TodoWrite no recordaba incluir checkpoint de gobernanza +3. Las reglas estaban en CLAUDE.md pero sin enforcement automático + +### Solución Implementada +1. Crear este trigger (TRIGGER-INICIO-TAREA) +2. Documentación retroactiva de la tarea +3. Actualización de _INDEX.yml +4. Propuesta de mejora a flujo de TodoWrite + +--- + +## METRICAS DE CUMPLIMIENTO + +| Métrica | Objetivo | Medición | +|---------|----------|----------| +| Tareas con carpeta antes de E | 100% | `tareas_con_carpeta / total_tareas` | +| Fases documentadas por tarea | >= 3 | `promedio(fases_doc)` | +| _INDEX.yml actualizado | 100% | `tareas_en_index / total_tareas` | + +--- + +# ═══════════════════════════════════════════════════════════════════════════════ +# FIN DEL TRIGGER +# ═══════════════════════════════════════════════════════════════════════════════ diff --git a/orchestration/directivas/triggers/TRIGGER-INVENTARIOS-SINCRONIZADOS.md b/orchestration/directivas/triggers/TRIGGER-INVENTARIOS-SINCRONIZADOS.md new file mode 100644 index 0000000..7735a9b --- /dev/null +++ b/orchestration/directivas/triggers/TRIGGER-INVENTARIOS-SINCRONIZADOS.md @@ -0,0 +1,281 @@ +# TRIGGER: INVENTARIOS SINCRONIZADOS + +**Versión:** 1.0.0 +**Fecha:** 2026-01-16 +**Sistema:** SIMCO v4.0.0 +**Alias:** @TRIGGER_INVENTARIOS + +--- + +## RESUMEN EJECUTIVO + +Este trigger OBLIGA a mantener los inventarios sincronizados con el código real. Se activa al completar cualquier tarea que modifique código o estructura. + +**PRINCIPIO:** "Los inventarios son la fuente de verdad. Si no está en el inventario, no existe oficialmente." + +--- + +## CONDICIONES DE ACTIVACIÓN + +```yaml +activar_cuando: + - Se completa cualquier tarea con cambios de código + - Se crea/modifica/elimina: tabla, entity, service, módulo, componente + - Se ejecuta auditoría de proyecto + - Han pasado más de 7 días desde última sincronización +``` + +--- + +## INVENTARIOS REQUERIDOS POR PROYECTO + +```yaml +inventarios_obligatorios: + DATABASE_INVENTORY.yml: + contenido: + - Lista completa de schemas + - Lista completa de tablas por schema + - Conteo de funciones, triggers, policies + - Estado de cada objeto (active/deprecated/planned) + actualizar_cuando: + - Crear/modificar/eliminar tabla + - Crear/modificar/eliminar schema + - Agregar/modificar funciones o triggers + + BACKEND_INVENTORY.yml: + contenido: + - Lista completa de módulos + - Lista completa de entities por módulo + - Lista completa de services por módulo + - Conteo de endpoints por módulo + - Estado de cada objeto + actualizar_cuando: + - Crear/modificar/eliminar entity + - Crear/modificar/eliminar service + - Crear/modificar/eliminar módulo + - Agregar/modificar endpoints + + FRONTEND_INVENTORY.yml: + contenido: + - Lista completa de componentes + - Lista completa de páginas + - Lista completa de hooks/stores + - Estado de cada objeto + actualizar_cuando: + - Crear/modificar/eliminar componente + - Crear/modificar/eliminar página + - Crear/modificar/eliminar hook/store + + MASTER_INVENTORY.yml: + contenido: + - Resumen de todos los inventarios + - Totales consolidados + - Última fecha de sincronización + - Score de coherencia + actualizar_cuando: + - Se actualiza cualquier otro inventario +``` + +--- + +## VERIFICACIONES DE SINCRONIZACIÓN + +### 1. Verificar Cobertura de Inventarios + +```yaml +cobertura_minima: + DATABASE_INVENTORY: + schemas: "100% de schemas en DDL" + tablas: "100% de tablas en DDL" + funciones: "100% de funciones en DDL" + + BACKEND_INVENTORY: + modulos: "100% de carpetas en modules/" + entities: "100% de archivos .entity.ts" + services: "100% de archivos .service.ts" + + FRONTEND_INVENTORY: + componentes: "100% de archivos .tsx en components/" + paginas: "100% de archivos en pages/" + stores: "100% de stores/hooks" +``` + +### 2. Verificar Consistencia de Conteos + +```yaml +validacion_conteos: + comparar: + - "Conteo en inventario vs archivos reales" + - "Conteo reportado en _INDEX.yml vs inventario" + - "Conteo entre inventarios relacionados" + + tolerancia: "0% - Debe ser exacto" + + si_discrepancia: + accion: "BLOQUEAR hasta sincronizar" +``` + +### 3. Verificar Actualización Reciente + +```yaml +frescura: + maxima_antiguedad: "7 días" + + verificar: + - "Fecha de última actualización en inventario" + - "Comparar con fecha de último commit en código" + + si_desactualizado: + accion: "ADVERTIR y solicitar sincronización" +``` + +--- + +## PROCESO DE SINCRONIZACIÓN + +### Sincronización Manual + +```bash +# El agente debe ejecutar para cada inventario: + +# 1. Contar objetos reales +find apps/database/ddl -name "*.sql" -exec grep -l "CREATE TABLE" {} \; | wc -l +find apps/backend/src/modules -name "*.entity.ts" | wc -l +find apps/backend/src/modules -name "*.service.ts" | wc -l + +# 2. Comparar con inventario +# 3. Actualizar inventario si hay discrepancia +# 4. Actualizar timestamp de sincronización +``` + +### Campos Obligatorios en Inventarios + +```yaml +metadata_obligatoria: + version: "Semver del inventario" + updated: "Fecha ISO de última actualización" + updated_by: "Agente que actualizó" + sync_status: "SYNCED | OUT_OF_SYNC | PARTIAL" + coverage: + total_expected: "N objetos esperados" + total_documented: "N objetos documentados" + percentage: "100%" +``` + +--- + +## CHECKLIST DE SINCRONIZACIÓN + +### Al Completar Tarea + +```markdown +## Verificación de Inventarios + +### DATABASE_INVENTORY.yml +[ ] Conteo de schemas correcto +[ ] Conteo de tablas correcto +[ ] Nuevos objetos agregados +[ ] Objetos eliminados removidos +[ ] Timestamp actualizado + +### BACKEND_INVENTORY.yml +[ ] Conteo de módulos correcto +[ ] Conteo de entities correcto +[ ] Conteo de services correcto +[ ] Conteo de endpoints correcto +[ ] Nuevos objetos agregados +[ ] Timestamp actualizado + +### FRONTEND_INVENTORY.yml +[ ] Conteo de componentes correcto +[ ] Conteo de páginas correcto +[ ] Nuevos objetos agregados +[ ] Timestamp actualizado + +### MASTER_INVENTORY.yml +[ ] Totales consolidados correctos +[ ] Score de coherencia actualizado +[ ] Timestamp actualizado +``` + +--- + +## INTEGRACIÓN CON TRIGGER-COHERENCIA-CAPAS + +```yaml +secuencia: + 1: "TRIGGER-COHERENCIA-CAPAS verifica estructura" + 2: "TRIGGER-INVENTARIOS-SINCRONIZADOS verifica documentación" + 3: "TRIGGER-DOCUMENTACION-OBLIGATORIA verifica gobernanza" + +dependencia: + - "Coherencia debe pasar ANTES de sincronizar inventarios" + - "Inventarios deben estar sincronizados ANTES de documentar" +``` + +--- + +## MENSAJES DE ERROR + +```yaml +errores: + E-INV-001: + mensaje: "Inventario desactualizado (más de 7 días)" + accion: "Ejecutar sincronización de inventario" + bloqueante: false (advertencia) + + E-INV-002: + mensaje: "Discrepancia de conteo en inventario" + accion: "Sincronizar inventario con código real" + bloqueante: true + + E-INV-003: + mensaje: "Objeto en código no documentado en inventario" + accion: "Agregar objeto al inventario" + bloqueante: true + + E-INV-004: + mensaje: "Objeto en inventario no existe en código" + accion: "Remover objeto del inventario o restaurar código" + bloqueante: true + + E-INV-005: + mensaje: "Inventario faltante" + accion: "Crear inventario siguiendo template" + bloqueante: true +``` + +--- + +## AUTOMATIZACIÓN FUTURA + +```yaml +scripts_recomendados: + sync-database-inventory: + descripcion: "Sincronizar DATABASE_INVENTORY.yml automáticamente" + implementar_en: "scripts/sync-inventories.sh" + + sync-backend-inventory: + descripcion: "Sincronizar BACKEND_INVENTORY.yml automáticamente" + implementar_en: "scripts/sync-inventories.sh" + + validate-inventories: + descripcion: "Validar que todos los inventarios estén sincronizados" + implementar_en: "scripts/validate-inventories.sh" + + estado: "DOCUMENTADO - Por implementar" +``` + +--- + +## REFERENCIAS + +| Alias | Descripción | +|-------|-------------| +| @TRIGGER_INVENTARIOS | Este trigger | +| @TRIGGER_COHERENCIA | Coherencia entre capas | +| @DEF_CHK_POST | Checklist post-tarea | + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Trigger de Sincronización diff --git a/orchestration/inventarios/BACKEND_INVENTORY.yml b/orchestration/inventarios/BACKEND_INVENTORY.yml new file mode 100644 index 0000000..26247b0 --- /dev/null +++ b/orchestration/inventarios/BACKEND_INVENTORY.yml @@ -0,0 +1,22 @@ +# BACKEND_INVENTORY.yml - clinica-veterinaria +# Generado: 2026-01-18T13:01:47-06:00 + +project: "clinica-veterinaria" +layer: "backend" + +modules: [] + +entities: [] + +services: [] + +controllers: [] + +total: + modules: 0 + entities: 0 + services: 0 + controllers: 0 + tests: 0 + +last_updated: "2026-01-18T13:01:47-06:00" diff --git a/orchestration/inventarios/DATABASE_INVENTORY.yml b/orchestration/inventarios/DATABASE_INVENTORY.yml index 9029fbf..537d919 100644 --- a/orchestration/inventarios/DATABASE_INVENTORY.yml +++ b/orchestration/inventarios/DATABASE_INVENTORY.yml @@ -1,443 +1,21 @@ ---- -# DATABASE INVENTORY - Clinica Veterinaria -# Version: 1.0.0 -# Ultima actualizacion: 2026-01-07 +# DATABASE_INVENTORY.yml - clinica-veterinaria +# Generado: 2026-01-18T13:01:47-06:00 -proyecto: "clinica-veterinaria" -schema_principal: "veterinaria" -version_ddl: "1.0" -estado: "completado" +project: "clinica-veterinaria" +layer: "database" -herencia: - vertical_padre: "erp-clinicas" - suite_core: "erp-core" - schemas_heredados: - - name: "auth" - desde: "erp-core" - - name: "tenants" - desde: "erp-core" - - name: "users" - desde: "erp-core" - - name: "clinica" - desde: "erp-clinicas" - tablas: ["doctors", "appointments", "consultations"] +schemas: [] -enums: - - name: "sexo_animal" - values: - - "macho" - - "hembra" - - "desconocido" +tables: [] - - name: "estado_hospitalizacion" - values: - - "ingresado" - - "en_tratamiento" - - "estable" - - "critico" - - "alta" - - "fallecido" +functions: [] -catalogos: - - name: "especies" - descripcion: "Catalogo de especies animales" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "nombre: VARCHAR(50)" - - "nombre_cientifico: VARCHAR(100)" - - "descripcion: TEXT" - - "active: BOOLEAN" +triggers: [] - - name: "razas" - descripcion: "Catalogo de razas por especie" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "especie_id: UUID FK" - - "nombre: VARCHAR(100)" - - "descripcion: TEXT" - - "tamanio_promedio: VARCHAR(20)" - - "peso_promedio_kg: NUMERIC(5,2)" - - "active: BOOLEAN" +total: + schemas: 0 + tables: 0 + functions: 0 + triggers: 0 - - name: "vacunas" - descripcion: "Catalogo de vacunas veterinarias" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "nombre: VARCHAR(100)" - - "descripcion: TEXT" - - "especie_id: UUID FK" - - "laboratorio: VARCHAR(100)" - - "dosis_ml: NUMERIC(5,2)" - - "intervalo_refuerzo_dias: INTEGER" - - "es_obligatoria: BOOLEAN" - - "active: BOOLEAN" - -tablas: - - name: "propietarios" - descripcion: "Propietarios/duenos de mascotas" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "partner_id: UUID FK (opcional)" - - "nombre: VARCHAR(100)" - - "apellidos: VARCHAR(100)" - - "telefono: VARCHAR(20)" - - "telefono_emergencia: VARCHAR(20)" - - "email: VARCHAR(100)" - - "direccion: TEXT" - - "rfc: VARCHAR(13)" - - "active: BOOLEAN" - indices: - - "idx_propietarios_tenant" - - "idx_propietarios_telefono" - - - name: "mascotas" - descripcion: "Mascotas/pacientes de la clinica" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "propietario_id: UUID FK" - - "especie_id: UUID FK" - - "raza_id: UUID FK" - - "nombre: VARCHAR(100)" - - "sexo: veterinaria.sexo_animal" - - "fecha_nacimiento: DATE" - - "edad_aproximada: VARCHAR(50)" - - "color: VARCHAR(50)" - - "peso_kg: NUMERIC(6,2)" - - "numero_chip: VARCHAR(50)" - - "tiene_chip: BOOLEAN" - - "esterilizado: BOOLEAN" - - "fecha_esterilizacion: DATE" - - "alergias: TEXT" - - "condiciones_especiales: TEXT" - - "notas: TEXT" - - "foto_url: VARCHAR(255)" - - "active: BOOLEAN" - indices: - - "idx_mascotas_tenant" - - "idx_mascotas_propietario" - - "idx_mascotas_especie" - - "idx_mascotas_chip" - - - name: "cartilla_vacunacion" - descripcion: "Historial de vacunacion de mascotas" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "mascota_id: UUID FK" - - "vacuna_id: UUID FK" - - "veterinario_id: UUID FK" - - "fecha_aplicacion: DATE" - - "fecha_proximo_refuerzo: DATE" - - "lote: VARCHAR(50)" - - "laboratorio: VARCHAR(100)" - - "observaciones: TEXT" - indices: - - "idx_cartilla_tenant" - - "idx_cartilla_mascota" - - "idx_cartilla_fecha" - - - name: "desparasitaciones" - descripcion: "Historial de desparasitaciones" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "mascota_id: UUID FK" - - "veterinario_id: UUID FK" - - "tipo: VARCHAR(50)" - - "producto: VARCHAR(100)" - - "dosis: VARCHAR(50)" - - "via_administracion: VARCHAR(50)" - - "fecha_aplicacion: DATE" - - "fecha_proxima: DATE" - - "observaciones: TEXT" - indices: - - "idx_desparasitaciones_tenant" - - "idx_desparasitaciones_mascota" - - - name: "hospitalizacion" - descripcion: "Registro de hospitalizaciones" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "mascota_id: UUID FK" - - "veterinario_id: UUID FK" - - "consultation_id: UUID FK" - - "fecha_ingreso: TIMESTAMPTZ" - - "motivo_ingreso: TEXT" - - "diagnostico_ingreso: TEXT" - - "area: VARCHAR(50)" - - "numero_jaula: VARCHAR(20)" - - "estado: veterinaria.estado_hospitalizacion" - - "fecha_alta: TIMESTAMPTZ" - - "diagnostico_alta: TEXT" - - "instrucciones_alta: TEXT" - indices: - - "idx_hospitalizacion_tenant" - - "idx_hospitalizacion_mascota" - - "idx_hospitalizacion_estado" - - - name: "hospitalizacion_monitoreo" - descripcion: "Monitoreo durante hospitalizacion" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "hospitalizacion_id: UUID FK" - - "fecha_hora: TIMESTAMPTZ" - - "peso_kg: NUMERIC(6,2)" - - "temperatura: NUMERIC(4,1)" - - "frecuencia_cardiaca: INTEGER" - - "frecuencia_respiratoria: INTEGER" - - "comio: BOOLEAN" - - "bebio_agua: BOOLEAN" - - "orino: BOOLEAN" - - "defeco: BOOLEAN" - - "consistencia_heces: VARCHAR(50)" - - "estado_animo: VARCHAR(50)" - - "nivel_dolor: INTEGER (0-10)" - - "observaciones: TEXT" - - "registrado_por: UUID FK" - indices: - - "idx_hospitalizacion_monitoreo_hosp" - - - name: "estetica" - descripcion: "Servicios de estetica/grooming" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "mascota_id: UUID FK" - - "estilista_id: UUID FK" - - "fecha_servicio: TIMESTAMPTZ" - - "servicios: TEXT[]" - - "tipo_corte: VARCHAR(50)" - - "shampoo_usado: VARCHAR(100)" - - "estado: VARCHAR(20)" - - "hora_inicio: TIME" - - "hora_fin: TIME" - - "observaciones: TEXT" - - "observaciones_piel: TEXT" - - "precio: NUMERIC(10,2)" - indices: - - "idx_estetica_tenant" - - "idx_estetica_mascota" - - "idx_estetica_fecha" - -extensiones_clinica: - tabla: "clinica.consultations" - columnas_agregadas: - - "mascota_id: UUID FK" - - "peso_actual: NUMERIC(6,2)" - - "temperatura: NUMERIC(4,1)" - -# ============================================================================ -# FARMACIA (VET-006) - Agregado 2026-01-07 -# ============================================================================ - -enums_farmacia: - - name: "categoria_medicamento" - values: - - "antibiotico" - - "antiparasitario" - - "analgesico" - - "antiinflamatorio" - - "vacuna" - - "vitamina" - - "dermatologico" - - "oftalmico" - - "cardiaco" - - "digestivo" - - "otro" - - - name: "tipo_movimiento_farmacia" - values: - - "entrada" - - "salida" - - "ajuste_positivo" - - "ajuste_negativo" - - "devolucion" - - "merma" - - - name: "fraccion_controlada" - values: - - "no_controlado" - - "fraccion_i" - - "fraccion_ii" - - "fraccion_iii" - - "fraccion_iv" - -tablas_farmacia: - - name: "medicamentos" - descripcion: "Catalogo de medicamentos veterinarios" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "codigo: VARCHAR(50)" - - "nombre: VARCHAR(150)" - - "nombre_comercial: VARCHAR(150)" - - "principio_activo: VARCHAR(200)" - - "categoria: veterinaria.categoria_medicamento" - - "presentacion: VARCHAR(100)" - - "concentracion: VARCHAR(50)" - - "contenido: VARCHAR(50)" - - "laboratorio: VARCHAR(100)" - - "requiere_receta: BOOLEAN" - - "controlado: BOOLEAN" - - "fraccion_controlada: veterinaria.fraccion_controlada" - - "stock_minimo: INTEGER" - - "stock_actual: INTEGER" - - "precio_compra: NUMERIC(10,2)" - - "precio_venta: NUMERIC(10,2)" - - "especies_aplicables: UUID[]" - - "active: BOOLEAN" - indices: - - "idx_medicamentos_tenant" - - "idx_medicamentos_codigo" - - "idx_medicamentos_nombre" - - "idx_medicamentos_categoria" - - "idx_medicamentos_controlado" - - "idx_medicamentos_stock_bajo" - - - name: "medicamentos_lotes" - descripcion: "Lotes de medicamentos con control de caducidad" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "medicamento_id: UUID FK" - - "numero_lote: VARCHAR(50)" - - "fecha_caducidad: DATE" - - "cantidad_inicial: INTEGER" - - "cantidad_actual: INTEGER" - - "precio_compra: NUMERIC(10,2)" - - "factura_compra: VARCHAR(50)" - - "proveedor: VARCHAR(100)" - - "fecha_recepcion: DATE" - - "bloqueado: BOOLEAN" - - "motivo_bloqueo: TEXT" - indices: - - "idx_lotes_tenant" - - "idx_lotes_medicamento" - - "idx_lotes_caducidad" - - "idx_lotes_numero" - - "idx_lotes_proximos_caducar" - - - name: "dispensaciones" - descripcion: "Registro de dispensacion de medicamentos" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "medicamento_id: UUID FK" - - "lote_id: UUID FK" - - "mascota_id: UUID FK" - - "veterinario_id: UUID FK" - - "receta_id: UUID FK" - - "consultation_id: UUID FK" - - "cantidad: INTEGER" - - "fecha_dispensacion: TIMESTAMPTZ" - - "dosis: VARCHAR(100)" - - "duracion_tratamiento: VARCHAR(50)" - - "instrucciones: TEXT" - - "dispensado_por: UUID FK" - - "notas: TEXT" - indices: - - "idx_dispensaciones_tenant" - - "idx_dispensaciones_medicamento" - - "idx_dispensaciones_mascota" - - "idx_dispensaciones_fecha" - - "idx_dispensaciones_veterinario" - - - name: "movimientos_farmacia" - descripcion: "Kardex de movimientos de inventario de farmacia" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "medicamento_id: UUID FK" - - "lote_id: UUID FK" - - "tipo: veterinaria.tipo_movimiento_farmacia" - - "cantidad: INTEGER" - - "stock_anterior: INTEGER" - - "stock_posterior: INTEGER" - - "referencia_tipo: VARCHAR(50)" - - "referencia_id: UUID" - - "motivo: TEXT" - - "documento: VARCHAR(100)" - - "usuario_id: UUID FK" - indices: - - "idx_movimientos_tenant" - - "idx_movimientos_medicamento" - - "idx_movimientos_fecha" - - - name: "bitacora_controlados" - descripcion: "Bitacora de medicamentos controlados (COFEPRIS)" - rls: true - columnas: - - "id: UUID PK" - - "tenant_id: UUID FK" - - "medicamento_id: UUID FK" - - "lote_id: UUID FK" - - "dispensacion_id: UUID FK" - - "tipo_movimiento: veterinaria.tipo_movimiento_farmacia" - - "cantidad: INTEGER" - - "mascota_id: UUID FK" - - "propietario_nombre: VARCHAR(200)" - - "receta_id: UUID FK" - - "veterinario_id: UUID FK" - - "veterinario_cedula: VARCHAR(50)" - - "justificacion: TEXT" - - "diagnostico: TEXT" - - "fecha_registro: TIMESTAMPTZ" - - "registrado_por: UUID FK" - - "ip_address: VARCHAR(45)" - indices: - - "idx_bitacora_tenant" - - "idx_bitacora_medicamento" - - "idx_bitacora_fecha" - -funciones_farmacia: - - name: "get_lotes_proximos_caducar(tenant_id, dias)" - descripcion: "Obtiene lotes que caducaran en los proximos N dias" - - name: "get_medicamentos_stock_bajo(tenant_id)" - descripcion: "Obtiene medicamentos con stock igual o menor al minimo" - - name: "seleccionar_lote_fefo(medicamento_id, cantidad)" - descripcion: "Selecciona el lote con fecha de caducidad mas proxima (FEFO)" - -triggers_farmacia: - - name: "trg_actualizar_stock" - tabla: "medicamentos_lotes" - descripcion: "Actualiza stock_actual en medicamentos cuando cambian los lotes" - - name: "trg_registrar_dispensacion" - tabla: "dispensaciones" - descripcion: "Registra movimiento y bitacora al dispensar medicamentos" - -resumen: - total_enums: 5 - total_catalogos: 3 - total_tablas: 12 - total_con_rls: 15 - total_funciones: 3 - total_triggers: 2 - archivos_ddl: - - "database/schemas/01-veterinaria-schema-ddl.sql" - - "database/schemas/02-veterinaria-farmacia-ddl.sql" - archivos_seeds: - - "database/seeds/fase8/01-veterinaria-catalogos.sql" - -ultima_actualizacion: "2026-01-07" -actualizado_por: "Orquestador Workspace (Sprint 9)" +last_updated: "2026-01-18T13:01:47-06:00" diff --git a/orchestration/inventarios/FRONTEND_INVENTORY.yml b/orchestration/inventarios/FRONTEND_INVENTORY.yml new file mode 100644 index 0000000..7f0cea8 --- /dev/null +++ b/orchestration/inventarios/FRONTEND_INVENTORY.yml @@ -0,0 +1,24 @@ +# FRONTEND_INVENTORY.yml - clinica-veterinaria +# Generado: 2026-01-18T13:01:47-06:00 + +project: "clinica-veterinaria" +layer: "frontend" + +features: [] + +components: [] + +pages: [] + +stores: [] + +hooks: [] + +total: + features: 0 + components: 0 + pages: 0 + stores: 0 + hooks: 0 + +last_updated: "2026-01-18T13:01:47-06:00" diff --git a/orchestration/inventarios/MASTER_INVENTORY.yml b/orchestration/inventarios/MASTER_INVENTORY.yml index 07c5a72..7e6bb5b 100644 --- a/orchestration/inventarios/MASTER_INVENTORY.yml +++ b/orchestration/inventarios/MASTER_INVENTORY.yml @@ -1,163 +1,25 @@ ---- -# MASTER INVENTORY - Clinica Veterinaria -# Version: 1.1.0 -# Ultima actualizacion: 2026-01-13 +# MASTER_INVENTORY.yml - clinica-veterinaria +# Generado: 2026-01-18T13:01:47-06:00 +# Version: 1.0.0 -proyecto: "clinica-veterinaria" -descripcion: "ERP especializado para clinicas veterinarias" -version: "1.0.0" -estado: "desarrollo" -tipo: "sub-vertical" -base: "erp-clinicas" +project: + name: "clinica-veterinaria" + type: "erp-vertical" + parent: "erp-core" + version: "0.1.0" -progreso: - fase_actual: "Database" - porcentaje: 25 - database_completado: true - backend_completado: false - frontend_completado: false +summary: + total_modules: 0 + backend_entities: 0 + frontend_components: 0 + database_tables: 0 + test_files: 0 + coverage_percentage: 0 -# Cadena de herencia completa -herencia: - cadena: "template-saas -> erp-core -> erp-clinicas -> clinica-veterinaria" - vertical_padre: "erp-clinicas" - suite_core: "erp-core" - provider: "template-saas" +inventories: + backend: "BACKEND_INVENTORY.yml" + frontend: "FRONTEND_INVENTORY.yml" + database: "DATABASE_INVENTORY.yml" - # Módulos heredados por fase - modulos_heredados: - fase_01_02_core: - - MGN-001 (auth) - - MGN-002 (users) - - MGN-003 (roles) - - MGN-004 (tenants) - - MGN-005 (catalogs) - - MGN-007 (audit) - - MGN-008 (notifications) - - MGN-009 (reports) - fase_04_saas: - - MGN-016 (billing) - - MGN-017 (plans) - - MGN-018 (webhooks) - - MGN-019 (feature-flags) - fase_05_ia: - - MGN-020 (ai-integration) - - MGN-021 (whatsapp-business) - - MGN-022 (mcp-server) - erp_clinicas: - - CL-001 (fundamentos) - - CL-002 (pacientes) - - CL-003 (citas) - - CL-004 (consultas) - - CL-005 (recetas) - - CL-006 (laboratorio) - - CL-007 (farmacia) - - CL-008 (facturacion) - - CL-009 (reportes) - - CL-010 (telemedicina) - - CL-011 (expediente) - - CL-012 (imagenologia) - - total_modulos_heredados: 28 # 16 erp-core (sin biometrics) + 12 erp-clinicas - - # Propagación recibida - ultima_propagacion: - id: "PROP-CORE-002" - fecha: "2026-01-13" - tipo: "bulk_propagation" - modulos_recibidos: - - MGN-016 a MGN-022 (Fases 04-05) - -modulos_especificos: - - id: "VET-001" - nombre: "mascotas" - descripcion: "Registro de animales/pacientes" - estado: "ddl_completado" - - - id: "VET-002" - nombre: "propietarios" - descripcion: "Duenos de mascotas" - estado: "ddl_completado" - - - id: "VET-003" - nombre: "vacunacion" - descripcion: "Cartilla y control de vacunas" - estado: "ddl_completado" - - - id: "VET-004" - nombre: "hospitalizacion" - descripcion: "Control de internamiento" - estado: "ddl_completado" - - - id: "VET-005" - nombre: "estetica" - descripcion: "Servicios de estetica canina" - estado: "documentado" - - - id: "VET-006" - nombre: "farmacia" - descripcion: "Inventario veterinario" - estado: "pendiente" - -database: - schema: "veterinaria" - archivo_ddl: "database/schemas/01-veterinaria-schema-ddl.sql" - archivo_seeds: "database/seeds/fase8/01-veterinaria-catalogos.sql" - tablas_especificas: - - "pets" - - "pet_owners" - - "vaccinations" - - "vaccination_records" - - "hospitalizations" - - "vet_consultations" - schemas_heredados: - - billing (Fase 04) - - webhooks (Fase 04) - - feature_flags (Fase 04) - - ai_agents (Fase 05) - - messaging (Fase 05) - -catalogos: - - "especies" - - "razas_por_especie" - - "vacunas_por_especie" - - "especialidades_veterinarias" - -# Adaptaciones IA para veterinaria -ia_adaptations: - mcp_tools: - - crear_cita_vet - - cartilla_vacunacion - - calcular_dosis - - historial_mascota - - alerta_vacunas - whatsapp_templates: - - recordatorio_vacuna - - confirmacion_cita_vet - - seguimiento_hospitalizacion - - recordatorio_desparasitacion - - promocion_estetica - -normativa: - - NOM-064-ZOO-2000 - - NOM-051-ZOO-1995 - - NOM-046-ZOO-1995 - - SENASICA - - SAGARPA - -proximas_tareas: - - "Implementar backend modulo mascotas" - - "Crear frontend para cartilla de vacunacion" - - "Configurar feature flags para veterinaria" - - "Crear templates WhatsApp para vacunas" - - "Integrar MCP tools veterinarios" - - "Implementar modulo VET-006 farmacia" - -documentos_referencia: - - "orchestration/00-guidelines/HERENCIA-ERP-CORE.md" - - "orchestration/00-guidelines/HERENCIA-ERP-CLINICAS.md" - - "orchestration/referencias/DEPENDENCIAS-ERP-CORE.yml" - -ultima_actualizacion: "2026-01-13" -actualizado_por: "CLAUDE-CAPVED" -propagacion_ref: "PROP-CORE-002" +last_updated: "2026-01-18T13:01:47-06:00" +updated_by: "propagate-governance.sh"