From faeb932c89909fa28905e1af68ef1a931ce14e6c Mon Sep 17 00:00:00 2001 From: rckrdmrd Date: Sun, 18 Jan 2026 10:30:49 -0600 Subject: [PATCH] [GOBERNANZA] feat: Propagar gobernanza completa a clinica-veterinaria - Crear _definitions/ con protocolos, validaciones y checklists - Configurar rol CONSUMER con tipo_herencia SPECIALIZES - Definir modulos propios: mascotas, vacunacion, hospitalizacion - Crear docs/_SSOT/ con estructura de trazabilidad Herencia: erp-core -> erp-clinicas -> clinica-veterinaria Co-Authored-By: Claude Opus 4.5 --- docs/_SSOT/README.md | 34 ++ orchestration/_definitions/_INDEX.yml | 82 +++++ .../checklists/CHECKLIST-GOBERNANZA-TAREA.md | 223 +++++++++++ .../checklists/CHECKLIST-POST-TASK.md | 244 ++++++++++++ .../checklists/CHECKLIST-PRE-CREATE.md | 107 ++++++ .../checklists/CHECKLIST-PRE-MODIFY.md | 149 ++++++++ .../_definitions/protocols/CAPVED-CYCLE.md | 347 ++++++++++++++++++ .../_definitions/protocols/CCA-PROTOCOL.md | 245 +++++++++++++ .../validations/VALIDATION-BACKEND.md | 81 ++++ .../validations/VALIDATION-DDL.md | 89 +++++ .../validations/VALIDATION-FRONTEND.md | 81 ++++ 11 files changed, 1682 insertions(+) create mode 100644 docs/_SSOT/README.md create mode 100644 orchestration/_definitions/_INDEX.yml create mode 100644 orchestration/_definitions/checklists/CHECKLIST-GOBERNANZA-TAREA.md create mode 100644 orchestration/_definitions/checklists/CHECKLIST-POST-TASK.md create mode 100644 orchestration/_definitions/checklists/CHECKLIST-PRE-CREATE.md create mode 100644 orchestration/_definitions/checklists/CHECKLIST-PRE-MODIFY.md create mode 100644 orchestration/_definitions/protocols/CAPVED-CYCLE.md create mode 100644 orchestration/_definitions/protocols/CCA-PROTOCOL.md create mode 100644 orchestration/_definitions/validations/VALIDATION-BACKEND.md create mode 100644 orchestration/_definitions/validations/VALIDATION-DDL.md create mode 100644 orchestration/_definitions/validations/VALIDATION-FRONTEND.md diff --git a/docs/_SSOT/README.md b/docs/_SSOT/README.md new file mode 100644 index 0000000..c953515 --- /dev/null +++ b/docs/_SSOT/README.md @@ -0,0 +1,34 @@ +# Single Source of Truth (SSOT) - CLINICA-VETERINARIA + +**Version:** 1.0.0 +**Fecha:** 2026-01-18 +**Proyecto:** clinica-veterinaria +**Sistema:** SIMCO v4.0.0 + +--- + +## Herencia + +``` +template-saas (PROVIDER) + ↓ +erp-core (INTERMEDIATE) + ↓ +erp-clinicas (INTERMEDIATE) + ↓ +clinica-veterinaria (SPECIALIZES) ← ESTE PROYECTO +``` + +--- + +## Archivos SSOT + +| Archivo | Descripcion | Estado | +|---------|-------------|--------| +| EPIC-INDEX.yml | Indice de epicas | PENDIENTE | +| TRACEABILITY-MASTER.yml | Trazabilidad maestra | PENDIENTE | + +--- + +**Creado:** 2026-01-18 +**Mantenido por:** @CLINICA_VETERINARIA_ORCHESTRATOR diff --git a/orchestration/_definitions/_INDEX.yml b/orchestration/_definitions/_INDEX.yml new file mode 100644 index 0000000..897d094 --- /dev/null +++ b/orchestration/_definitions/_INDEX.yml @@ -0,0 +1,82 @@ +# ═══════════════════════════════════════════════════════════════════════════════ +# ÍNDICE DE DEFINICIONES CANÓNICAS - CLINICA-VETERINARIA +# ═══════════════════════════════════════════════════════════════════════════════ + +version: "1.0.0" +created: "2026-01-18" +updated: "2026-01-18" +maintained_by: "@WS_ORCHESTRATOR" +propagated_from: "erp-clinicas/orchestration/_definitions/" +role: "CONSUMER" # Especialización de erp-clinicas + +# ───────────────────────────────────────────────────────────────────────────────── +# PROTOCOLOS +# ───────────────────────────────────────────────────────────────────────────────── + +protocols: + CCA-PROTOCOL: + alias: "@DEF_CCA" + path: "protocols/CCA-PROTOCOL.md" + estado: "PROPAGADO" + CAPVED-CYCLE: + alias: "@DEF_CAPVED" + path: "protocols/CAPVED-CYCLE.md" + estado: "PROPAGADO" + +validations: + VALIDATION-BACKEND: + alias: "@DEF_VAL_BE" + path: "validations/VALIDATION-BACKEND.md" + estado: "PROPAGADO" + VALIDATION-FRONTEND: + alias: "@DEF_VAL_FE" + path: "validations/VALIDATION-FRONTEND.md" + estado: "PROPAGADO" + VALIDATION-DDL: + alias: "@DEF_VAL_DDL" + path: "validations/VALIDATION-DDL.md" + estado: "PROPAGADO" + +checklists: + CHECKLIST-GOBERNANZA-TAREA: + alias: "@DEF_CHK_GOB" + path: "checklists/CHECKLIST-GOBERNANZA-TAREA.md" + estado: "PROPAGADO" + CHECKLIST-POST-TASK: + alias: "@DEF_CHK_POST" + path: "checklists/CHECKLIST-POST-TASK.md" + estado: "PROPAGADO" + CHECKLIST-PRE-CREATE: + alias: "@DEF_CHK_CREATE" + path: "checklists/CHECKLIST-PRE-CREATE.md" + estado: "PROPAGADO" + CHECKLIST-PRE-MODIFY: + alias: "@DEF_CHK_MODIFY" + path: "checklists/CHECKLIST-PRE-MODIFY.md" + estado: "PROPAGADO" + +statistics: + total_definitions: 9 + propagated: 9 + +# ───────────────────────────────────────────────────────────────────────────────── +# CONFIGURACIÓN DE HERENCIA (SPECIALIZES) +# ───────────────────────────────────────────────────────────────────────────────── + +consumer_config: + role: "CONSUMER" + inherits_from: "erp-clinicas" # Especialización de erp-clinicas + inherits_version: "1.0.0" + tipo_herencia: "SPECIALIZES" + modulos_heredados: + - pacientes (adaptado a mascotas) + - citas + - expedientes (adaptado) + modulos_propios: + - mascotas + - vacunacion + - hospitalizacion + propagates_to: [] + sync_strategy: "AUTO" + vertical: "clinica-veterinaria" + nota: "Clínica veterinaria especializada - hereda de erp-clinicas" diff --git a/orchestration/_definitions/checklists/CHECKLIST-GOBERNANZA-TAREA.md b/orchestration/_definitions/checklists/CHECKLIST-GOBERNANZA-TAREA.md new file mode 100644 index 0000000..e71dd47 --- /dev/null +++ b/orchestration/_definitions/checklists/CHECKLIST-GOBERNANZA-TAREA.md @@ -0,0 +1,223 @@ +# CHECKLIST: GOBERNANZA DE TAREA + +**Versión:** 1.0.0 +**Alias:** @DEF_CHK_GOB +**Fecha:** 2026-01-16 +**Sistema:** SIMCO v4.0.0 +**Prioridad:** P0 - BLOQUEANTE + +--- + +## PROPÓSITO + +Este checklist es **OBLIGATORIO** y **BLOQUEANTE** para toda tarea que se marque como completada. +Debe ejecutarse ANTES de cualquier otra validación post-tarea. + +> **REGLA:** Sin gobernanza documentada, la tarea NO está completada. + +--- + +## SECUENCIA DE EJECUCIÓN + +``` +TAREA FINALIZA EJECUCIÓN + │ + ▼ +┌─────────────────────────────┐ +│ CHECKLIST-GOBERNANZA-TAREA │ ← PRIMERO (este checklist) +│ (BLOQUEANTE) │ +└─────────────┬───────────────┘ + │ + ▼ + ¿Todos los items pasan? + / \ + Sí No + │ │ + ▼ ▼ +CHECKLIST-POST-TASK BLOQUEAR +(validaciones (no continuar + técnicas) hasta resolver) +``` + +--- + +## CHECKLIST (8 Items) + +### 1. Carpeta de Tarea + +```markdown +[ ] Existe carpeta: orchestration/tareas/TASK-{YYYY-MM-DD}-{NNN}/ +``` + +**Si no existe:** +```bash +# Crear carpeta +mkdir -p orchestration/tareas/TASK-$(date +%Y-%m-%d)-00X + +# Copiar templates +cp -r orchestration/tareas/_templates/TASK-TEMPLATE/* orchestration/tareas/TASK-$(date +%Y-%m-%d)-00X/ +``` + +### 2. METADATA.yml + +```markdown +[ ] METADATA.yml existe y tiene campos obligatorios: + [ ] task_id + [ ] identificacion.titulo + [ ] identificacion.tipo + [ ] responsabilidad.agente_responsable + [ ] alcance.nivel + [ ] temporalidad.fecha_inicio + [ ] estado.actual = "completada" + [ ] artefactos.archivos_creados (lista) + [ ] artefactos.archivos_modificados (lista) +``` + +### 3. Fase C - Contexto (OBLIGATORIA) + +```markdown +[ ] 01-CONTEXTO.md existe y documenta: + [ ] Qué se solicitó + [ ] Por qué se necesita + [ ] Proyecto/módulo afectado + [ ] Contexto cargado +``` + +### 4. Fase E - Ejecución (OBLIGATORIA) + +```markdown +[ ] 05-EJECUCION.md existe y documenta: + [ ] Subtareas ejecutadas + [ ] Archivos creados/modificados + [ ] Validaciones ejecutadas + [ ] Problemas encontrados y cómo se resolvieron +``` + +### 5. Fase D - Documentación (OBLIGATORIA) + +```markdown +[ ] 06-DOCUMENTACION.md existe y documenta: + [ ] Resumen de cambios + [ ] Inventarios actualizados + [ ] Propagación evaluada + [ ] Referencias actualizadas +``` + +### 6. Índice de Tareas + +```markdown +[ ] orchestration/tareas/_INDEX.yml actualizado: + [ ] Estadísticas actualizadas + [ ] Tarea en historial_por_fecha + [ ] Tarea en por_proyecto + [ ] Tarea en por_agente + [ ] Tarea en por_tipo +``` + +### 7. Traza de Agente (Recomendado) + +```markdown +[ ] orchestration/agents/trazas/TRAZA-AGENTE-{PERFIL}.md actualizada + O +[ ] Excepción documentada en METADATA.yml +``` + +### 8. Validación Final + +```markdown +[ ] Carpeta de tarea contiene mínimo: + - METADATA.yml (completo) + - 01-CONTEXTO.md (documentado) + - 05-EJECUCION.md (documentado) + - 06-DOCUMENTACION.md (documentado) +``` + +--- + +## DECISIÓN + +```yaml +SI_PASA_TODO: + accion: "Continuar con CHECKLIST-POST-TASK" + nota: "Gobernanza validada" + +SI_FALLA_CUALQUIER_ITEM: + accion: "BLOQUEAR" + mensaje: | + ❌ GOBERNANZA INCOMPLETA + + La tarea NO puede marcarse como completada. + Items faltantes: + - {lista de items faltantes} + + Acciones requeridas: + 1. Completar items faltantes + 2. Re-ejecutar este checklist + 3. Continuar con validaciones técnicas +``` + +--- + +## TEMPLATE RÁPIDO + +Para crear documentación de gobernanza rápidamente: + +```bash +# Variables +TASK_ID="TASK-$(date +%Y-%m-%d)-00X" +TASK_DIR="orchestration/tareas/$TASK_ID" + +# 1. Crear estructura +mkdir -p $TASK_DIR +cp orchestration/tareas/_templates/TASK-TEMPLATE/* $TASK_DIR/ + +# 2. Completar METADATA.yml +# 3. Documentar 01-CONTEXTO.md +# 4. Documentar 05-EJECUCION.md +# 5. Documentar 06-DOCUMENTACION.md +# 6. Actualizar _INDEX.yml +``` + +--- + +## INTEGRACIÓN CON TODOLIST + +Al iniciar cualquier tarea, el TodoList DEBE incluir: + +```yaml +todos: + # ... otras tareas ... + + # SIEMPRE al final: + - content: "Crear documentación de gobernanza (TASK-{ID})" + status: "pending" + activeForm: "Documentando gobernanza" +``` + +--- + +## USO + +```yaml +# En cualquier perfil de agente: +al_completar_trabajo_tecnico: + - Cargar: "@DEF_CHK_GOB" + - Ejecutar: "8 items de gobernanza" + - Si pasa: "Continuar con @DEF_CHK_POST" + - Si falla: "Completar gobernanza primero" +``` + +--- + +## REFERENCIAS + +| Alias | Descripción | +|-------|-------------| +| @DEF_CHK_GOB | Este checklist | +| @DEF_CHK_POST | Checklist post-tarea (validaciones técnicas) | +| @TRIGGER-DOC | Trigger de documentación obligatoria | +| @TAREAS | Directorio de tareas | + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Checklist Bloqueante diff --git a/orchestration/_definitions/checklists/CHECKLIST-POST-TASK.md b/orchestration/_definitions/checklists/CHECKLIST-POST-TASK.md new file mode 100644 index 0000000..e1d036a --- /dev/null +++ b/orchestration/_definitions/checklists/CHECKLIST-POST-TASK.md @@ -0,0 +1,244 @@ +# CHECKLIST: POST-TASK + +**Versión:** 1.1.0 +**Alias:** @DEF_CHK_POST +**Fecha:** 2026-01-16 +**Sistema:** SIMCO v4.0.0 + +--- + +## PROPÓSITO + +Verificaciones obligatorias DESPUÉS de completar cualquier tarea, antes de marcarla como terminada. + +--- + +## SECUENCIA OBLIGATORIA + +``` +TAREA FINALIZA EJECUCIÓN + │ + ▼ +┌─────────────────────────────┐ +│ 0. GOBERNANZA │ ← PRIMERO (BLOQUEANTE) +│ (@DEF_CHK_GOB) │ +└─────────────┬───────────────┘ + ¿Pasa? + / \ + No Sí + │ │ + BLOQUEAR ▼ + ┌─────────────────────────────┐ + │ 1-7. VALIDACIONES TÉCNICAS │ + │ (este checklist) │ + └─────────────────────────────┘ +``` + +--- + +## CHECKLIST + +### 0. Gobernanza de Tarea (BLOQUEANTE - EJECUTAR PRIMERO) + +> **OBLIGATORIO:** Ejecutar @DEF_CHK_GOB antes de continuar. + +```markdown +[ ] CHECKLIST-GOBERNANZA-TAREA.md ejecutado y PASADO + - Carpeta de tarea existe + - METADATA.yml completo + - Fases C, E, D documentadas + - _INDEX.yml actualizado + +SI NO PASA: DETENER. Completar gobernanza primero. +``` + +--- + +### 1. Validaciones Técnicas + +#### Backend (si aplica) +```markdown +[ ] npm run build - PASA +[ ] npm run lint - PASA +[ ] npm run test - PASA (si existen tests) +[ ] Servidor inicia sin errores +``` + +#### Frontend (si aplica) +```markdown +[ ] npm run build - PASA +[ ] npm run lint - PASA +[ ] npm run typecheck - PASA +[ ] Aplicación renderiza sin errores +``` + +#### Database (si aplica) +```markdown +[ ] DDL ejecuta sin errores +[ ] Datos de prueba cargan correctamente +[ ] Constraints funcionan como esperado +``` + +### 2. Coherencia Entre Capas (TRIGGER-COHERENCIA-CAPAS) + +```markdown +## DDL ↔ Backend +[ ] Toda tabla DDL tiene entity correspondiente (o excepción documentada) +[ ] Toda entity tiene tabla DDL correspondiente (o es View/Embeddable) +[ ] Campos de entity coinciden exactamente con columnas de tabla +[ ] Tipos TypeScript son compatibles con tipos PostgreSQL +[ ] Todo schema tiene al menos un módulo backend (o está marcado PLANNED) + +## Backend ↔ Frontend (si aplica) +[ ] Todo endpoint consumido tiene implementación en backend +[ ] Si hay nuevo endpoint: está documentado en Swagger +[ ] Si hay nuevo componente: está integrado donde corresponde + +## Verificación de Excepciones +[ ] Tablas M:N sin entity están documentadas en ENTITIES-CATALOG sección "Relaciones" +[ ] View entities (@ViewEntity) están documentadas como tal +[ ] Schemas PLANNED tienen fecha estimada de implementación +``` + +### 3. Actualización de Inventarios (TRIGGER-INVENTARIOS-SINCRONIZADOS) + +```markdown +## Sincronización Obligatoria +[ ] DATABASE_INVENTORY.yml actualizado (si cambió BD) + - Conteo de schemas correcto + - Conteo de tablas correcto + - Nuevos objetos agregados +[ ] BACKEND_INVENTORY.yml actualizado (si cambió BE) + - Conteo de módulos correcto + - Conteo de entities correcto + - Conteo de services correcto +[ ] FRONTEND_INVENTORY.yml actualizado (si cambió FE) + - Conteo de componentes correcto + - Conteo de páginas correcto +[ ] MASTER_INVENTORY.yml actualizado con totales + +## Verificación de Cobertura +[ ] Cobertura de inventarios = 100% +[ ] Timestamp de actualización = fecha de hoy +[ ] sync_status = "SYNCED" +``` + +### 4. Actualización de Trazas + +```markdown +[ ] Traza de tarea actualizada +[ ] Traza de agente actualizada +[ ] PROXIMA-ACCION.md actualizado +[ ] Commits con mensajes descriptivos +``` + +### 5. Documentación + +```markdown +[ ] README actualizado (si cambió significativamente) +[ ] Documentación técnica actualizada (si aplica) +[ ] ADR creado (si fue decisión arquitectural) +[ ] Comentarios en código donde la lógica no es obvia +``` + +### 6. Sistema de Gobernanza + +```markdown +[ ] Carpeta de tarea creada: orchestration/tareas/TASK-{ID}/ +[ ] METADATA.yml completado +[ ] Fases mínimas documentadas (C, E, D) +[ ] _INDEX.yml de tareas actualizado +[ ] Traza de agente actualizada +``` + +### 7. Evaluación de Propagación + +```markdown +[ ] ¿Cambio debe propagarse a otros proyectos? +[ ] Si es erp-core: ¿propagar a verticales? +[ ] Si es shared/catalog: ¿notificar proyectos que lo usan? +[ ] Si es security fix: ¿propagar inmediatamente? +``` + +--- + +## CRITERIOS DE COMPLETITUD + +### Tarea Completada SI: + +```yaml +obligatorio: + - Todas las validaciones técnicas pasan + - Inventarios actualizados + - Trazas actualizadas + - Documentación de gobernanza creada + +recomendado: + - Documentación técnica actualizada + - Tests agregados/actualizados + - Propagación evaluada +``` + +### Tarea NO Completada SI: + +```yaml +bloqueantes: + - Build falla + - Lint falla + - Tests fallan + - Inventarios no actualizados + - Sin documentación de gobernanza +``` + +--- + +## DECISIÓN + +```yaml +SI_PASA_TODO: + accion: "Marcar tarea como COMPLETADA" + documentar: "Resumen en METADATA.yml" + actualizar: "_INDEX.yml con estado COMPLETADO" + +SI_FALLA_VALIDACION: + accion: "MANTENER como EN_PROGRESO" + corregir: "Resolver validaciones fallidas" + reintentar: "Ejecutar checklist de nuevo" + +SI_FALTA_DOCUMENTACION: + accion: "MANTENER como EN_PROGRESO" + completar: "Documentación faltante" + nota: "Tarea no está completa sin documentación" +``` + +--- + +## USO + +```yaml +# En cualquier perfil de agente: +al_completar_tarea: + - Cargar: "@DEF_CHK_POST" + - Ejecutar: "Checklist completo" + - Si pasa: "Marcar tarea como completada" + - Si falla: "Resolver antes de marcar completada" +``` + +--- + +## INTEGRACIÓN CON TRIGGER-DOC + +Este checklist se activa junto con `TRIGGER-DOCUMENTACION-OBLIGATORIA.md` al intentar completar una tarea. + +```yaml +secuencia: + 1: "Agente intenta marcar tarea como completada" + 2: "TRIGGER-DOC se activa" + 3: "Se ejecuta CHECKLIST-POST-TASK" + 4: "Si pasa: tarea se marca completada" + 5: "Si falla: tarea permanece en progreso" +``` + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Checklist diff --git a/orchestration/_definitions/checklists/CHECKLIST-PRE-CREATE.md b/orchestration/_definitions/checklists/CHECKLIST-PRE-CREATE.md new file mode 100644 index 0000000..7dac19c --- /dev/null +++ b/orchestration/_definitions/checklists/CHECKLIST-PRE-CREATE.md @@ -0,0 +1,107 @@ +# CHECKLIST: PRE-CREATE + +**Versión:** 1.0.0 +**Alias:** @DEF_CHK_CREATE +**Fecha:** 2026-01-16 +**Sistema:** SIMCO v4.0.0 + +--- + +## PROPÓSITO + +Verificaciones obligatorias ANTES de crear cualquier objeto nuevo (tabla, entity, service, componente, etc.). + +--- + +## CHECKLIST + +### 1. Verificación Anti-Duplicación + +```markdown +[ ] Buscar en catálogo compartido (shared/catalog/CATALOG-INDEX.yml) +[ ] Buscar en inventario del proyecto (orchestration/inventarios/) +[ ] Buscar archivos similares con nombre parecido +[ ] Buscar funcionalidad similar en módulos existentes +[ ] Confirmar que NO existe funcionalidad equivalente +``` + +### 2. Verificación de Dependencias + +```markdown +[ ] Identificar de qué depende el nuevo objeto +[ ] Verificar que las dependencias existen +[ ] Si depende de DDL: tabla existe en base de datos +[ ] Si depende de entity: entity existe en backend +[ ] Si depende de endpoint: endpoint existe y funciona +``` + +### 3. Verificación de Ubicación + +```markdown +[ ] Identificar módulo/carpeta correcta según estándares +[ ] Verificar que la ruta sigue convenciones del proyecto +[ ] Confirmar que no hay conflicto de nombres +[ ] Verificar permisos de escritura en la ubicación +``` + +### 4. Verificación de Nomenclatura + +```markdown +[ ] Nombre sigue convenciones del proyecto +[ ] Nombre es descriptivo y no ambiguo +[ ] Prefijos/sufijos correctos según tipo de archivo +[ ] Formato de archivo correcto (PascalCase, kebab-case, etc.) +``` + +### 5. Verificación de Coherencia + +```markdown +[ ] Nuevo objeto es coherente con arquitectura existente +[ ] No introduce acoplamiento innecesario +[ ] Sigue patrones establecidos del proyecto +[ ] No duplica responsabilidades de otros objetos +``` + +--- + +## DECISIÓN + +```yaml +SI_PASA_TODO: + accion: "Proceder con creación" + siguiente: "Ejecutar SIMCO-CREAR.md" + +SI_FALLA_DUPLICACION: + accion: "DETENER - Evaluar uso del existente" + opciones: + - "Usar objeto existente" + - "Extender objeto existente" + - "Justificar creación de nuevo (documentar razón)" + +SI_FALLA_DEPENDENCIA: + accion: "DETENER - Resolver dependencia primero" + opciones: + - "Delegar creación de dependencia" + - "Crear dependencia primero" + - "Replanificar orden de tareas" + +SI_FALLA_NOMENCLATURA: + accion: "Corregir nombre antes de crear" + consultar: "@SIMCO/SIMCO-NOMENCLATURA.md" +``` + +--- + +## USO + +```yaml +# En perfil de agente: +antes_de_crear: + - Cargar: "@DEF_CHK_CREATE" + - Ejecutar: "Checklist completo" + - Documentar: "Resultado en traza" +``` + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Checklist diff --git a/orchestration/_definitions/checklists/CHECKLIST-PRE-MODIFY.md b/orchestration/_definitions/checklists/CHECKLIST-PRE-MODIFY.md new file mode 100644 index 0000000..edc8d54 --- /dev/null +++ b/orchestration/_definitions/checklists/CHECKLIST-PRE-MODIFY.md @@ -0,0 +1,149 @@ +# CHECKLIST: PRE-MODIFY + +**Versión:** 1.0.0 +**Alias:** @DEF_CHK_MODIFY +**Fecha:** 2026-01-16 +**Sistema:** SIMCO v4.0.0 + +--- + +## PROPÓSITO + +Verificaciones obligatorias ANTES de modificar cualquier archivo existente. + +--- + +## CHECKLIST + +### 1. Análisis de Dependientes + +```markdown +[ ] Identificar archivos que IMPORTAN el archivo a modificar +[ ] Listar todos los dependientes encontrados +[ ] Evaluar impacto del cambio en cada dependiente +[ ] Clasificar cambio como: aditivo | modificación | breaking +``` + +### 2. Análisis de Dependencias + +```markdown +[ ] Identificar archivos que el archivo IMPORTA +[ ] Verificar que las dependencias siguen siendo válidas post-cambio +[ ] Identificar si el cambio requiere actualizar dependencias +``` + +### 3. Evaluación de Impacto + +```markdown +[ ] Determinar alcance: local | módulo | proyecto | workspace +[ ] Identificar capas afectadas: DDL | BE | FE +[ ] Evaluar si cambio requiere migración de datos +[ ] Evaluar si cambio rompe compatibilidad hacia atrás +``` + +### 4. Plan de Actualización + +```markdown +[ ] Si hay dependientes afectados: incluir en plan de subtareas +[ ] Ordenar actualizaciones por dependencia (de más interno a más externo) +[ ] Identificar tests que deben actualizarse +[ ] Identificar documentación que debe actualizarse +``` + +### 5. Verificación de Seguridad + +```markdown +[ ] Cambio no introduce vulnerabilidades de seguridad +[ ] Cambio no expone datos sensibles +[ ] Cambio mantiene validaciones existentes +[ ] Si es API: cambio no rompe contratos existentes +``` + +### 6. Estrategia de Rollback + +```markdown +[ ] Identificar cómo revertir el cambio si falla +[ ] Confirmar que existe backup o commit previo +[ ] Documentar pasos de rollback si son complejos +``` + +--- + +## CLASIFICACIÓN DE CAMBIOS + +### Cambio Aditivo (BAJO RIESGO) +```yaml +caracteristicas: + - Agregar campo/método nuevo + - Agregar endpoint nuevo + - No modifica comportamiento existente +acciones: + - Actualizar dependientes que usarán lo nuevo + - Validación estándar +``` + +### Cambio de Modificación (MEDIO RIESGO) +```yaml +caracteristicas: + - Cambiar implementación interna + - Cambiar tipos de datos + - Renombrar elementos +acciones: + - Actualizar TODOS los dependientes + - Validación exhaustiva + - Pruebas de regresión +``` + +### Cambio Breaking (ALTO RIESGO) +```yaml +caracteristicas: + - Eliminar campo/método + - Cambiar firma de función/endpoint + - Cambiar comportamiento de API +acciones: + - DETENER y evaluar con Tech-Leader + - Plan de migración obligatorio + - Comunicar a equipos afectados +``` + +--- + +## DECISIÓN + +```yaml +SI_PASA_TODO: + accion: "Proceder con modificación" + siguiente: "Ejecutar SIMCO-MODIFICAR.md" + incluir: "Actualización de dependientes en plan" + +SI_CAMBIO_BREAKING: + accion: "ESCALAR a Tech-Leader" + documentar: + - Razón del cambio breaking + - Alternativas evaluadas + - Plan de migración propuesto + +SI_IMPACTO_ALTO: + accion: "Solicitar revisión antes de proceder" + documentar: + - Alcance del impacto + - Dependientes afectados + - Plan de actualización +``` + +--- + +## USO + +```yaml +# En perfil de agente: +antes_de_modificar: + - Cargar: "@DEF_CHK_MODIFY" + - Ejecutar: "Checklist completo" + - Documentar: "Resultado en traza" + - Si breaking: "Escalar antes de continuar" +``` + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Checklist diff --git a/orchestration/_definitions/protocols/CAPVED-CYCLE.md b/orchestration/_definitions/protocols/CAPVED-CYCLE.md new file mode 100644 index 0000000..9f9a1cb --- /dev/null +++ b/orchestration/_definitions/protocols/CAPVED-CYCLE.md @@ -0,0 +1,347 @@ +--- +tipo: especificacion-tecnica +nivel: 2-tecnico +ssot: /orchestration/directivas/principios/PRINCIPIO-CAPVED.md +audiencia: agentes IA, sistemas automaticos +proposito: Especificacion tecnica del protocolo CAPVED +actualizado: 2026-01-16 +--- + +# PROTOCOLO: CAPVED-CYCLE + +**Versión:** 1.0.0 +**Alias:** @DEF_CAPVED +**Fecha:** 2026-01-16 +**Sistema:** SIMCO v4.0.0 +**SSOT:** [PRINCIPIO-CAPVED.md](/orchestration/directivas/principios/PRINCIPIO-CAPVED.md) + +--- + +## RESUMEN + +CAPVED es el ciclo de vida obligatorio para toda tarea en el workspace. Define 6 fases secuenciales que aseguran calidad, trazabilidad y documentación completa. + +``` +C → A → P → V → E → D +│ │ │ │ │ │ +│ │ │ │ │ └─ DOCUMENTACIÓN (Registrar, trazar, propagar) +│ │ │ │ └───── EJECUCIÓN (Implementar cambios) +│ │ │ └───────── VALIDACIÓN (Gate pre-ejecución) +│ │ └───────────── PLANEACIÓN (Desglosar subtareas) +│ └───────────────── ANÁLISIS (Mapear impacto) +└───────────────────── CONTEXTO (Clasificar y vincular) +``` + +--- + +## FASES DEL CICLO + +### FASE C - CONTEXTO + +**Objetivo:** Clasificar tarea y vincular con proyecto/workspace. + +```yaml +actividades: + - Identificar tipo de tarea (feature/fix/refactor/analysis) + - Identificar proyecto(s) involucrado(s) + - Identificar nivel (workspace/proyecto/módulo) + - Cargar contexto requerido según perfil + - Vincular con épica/user story si aplica + +salidas: + - Tipo de tarea identificado + - Proyecto(s) identificado(s) + - Contexto mínimo viable cargado + - Vinculación establecida + +criterios_completitud: + - Proyecto claramente identificado + - Tipo de tarea determinado + - Contexto base cargado +``` + +### FASE A - ANÁLISIS + +**Objetivo:** Mapear impacto, dependencias y riesgos. + +```yaml +actividades: + - Ejecutar TRIGGER-ANTI-DUPLICACION si es creación + - Ejecutar TRIGGER-ANALISIS-DEPENDENCIAS si es modificación + - Identificar archivos afectados + - Mapear dependientes (quién usa lo que modifico) + - Mapear dependencias (qué usa lo que modifico) + - Evaluar riesgos y complejidad + +salidas: + - Mapa de impacto + - Lista de dependientes + - Lista de dependencias + - Evaluación de riesgos + - Complejidad estimada + +criterios_completitud: + - Impacto mapeado + - Dependencias identificadas + - Riesgos evaluados +``` + +### FASE P - PLANEACIÓN + +**Objetivo:** Desglosar en subtareas por dominio. + +```yaml +actividades: + - Crear lista de subtareas específicas + - Ordenar por dependencia (DDL → BE → FE) + - Identificar subtareas paralelizables + - Asignar perfil responsable por subtarea + - Definir criterios de aceptación por subtarea + +salidas: + - Lista de subtareas (ST-001, ST-002, ...) + - Orden de ejecución + - Asignación de perfiles + - Criterios de aceptación + +criterios_completitud: + - Subtareas definidas + - Orden establecido + - Criterios claros +``` + +### FASE V - VALIDACIÓN (Gate) + +**Objetivo:** Verificar antes de ejecutar. + +```yaml +actividades: + - Verificar que plan cubre todo el impacto + - Verificar que no hay scope creep + - Verificar que dependencias están resueltas + - Verificar que hay capacidad de rollback + - Confirmar alineación con estándares + +salidas: + - Checklist de validación completado + - Decisión GO/NO-GO + +criterios_completitud: + - Todas las verificaciones pasadas + - Decisión GO documentada + +decision: + GO: "Continuar a Fase E" + NO-GO: "Regresar a Fase A o P según hallazgo" +``` + +### FASE E - EJECUCIÓN + +**Objetivo:** Implementar cambios según plan. + +```yaml +actividades: + - Ejecutar subtareas en orden + - Validar cada subtarea (build/lint/test) + - Crear commits atómicos por subtarea + - Documentar problemas encontrados + - Escalar si hay bloqueos + +salidas: + - Código implementado + - Commits realizados + - Validaciones pasadas + - Problemas documentados + +criterios_completitud: + - Todas las subtareas completadas + - Build pasa + - Lint pasa + - Tests pasan (si existen) +``` + +### FASE D - DOCUMENTACIÓN + +**Objetivo:** Registrar, trazar y propagar. + +> **IMPORTANTE:** Esta fase tiene dos sub-fases en orden estricto: +> 1. **D1 - Gobernanza** (BLOQUEANTE) +> 2. **D2 - Técnica** (después de gobernanza) + +```yaml +actividades: + # D1 - GOBERNANZA (PRIMERO - BLOQUEANTE) + d1_gobernanza: + - Crear carpeta de tarea: orchestration/tareas/TASK-{ID}/ + - Completar METADATA.yml + - Documentar 01-CONTEXTO.md (qué y por qué) + - Documentar 05-EJECUCION.md (cómo y qué problemas) + - Documentar 06-DOCUMENTACION.md (resumen y referencias) + - Actualizar orchestration/tareas/_INDEX.yml + - Actualizar traza de agente (opcional pero recomendado) + + # D2 - TÉCNICA (después de gobernanza) + d2_tecnica: + - Actualizar inventarios afectados + - Evaluar propagación (TRIGGER-PROPAGACION-AUTOMATICA) + - Crear/actualizar documentación técnica si aplica + +salidas: + # Gobernanza + - Carpeta de tarea con documentación completa + - _INDEX.yml actualizado + # Técnica + - Inventarios actualizados + - Propagación evaluada/ejecutada + +criterios_completitud: + # Gobernanza (BLOQUEANTE) + - Carpeta TASK-{ID}/ existe + - METADATA.yml completo + - Fases C, E, D documentadas + - _INDEX.yml actualizado + # Técnica + - Inventarios al día + - Propagación evaluada + +validacion: + checklist: "@DEF_CHK_GOB (gobernanza) + @DEF_CHK_POST (técnica)" + orden: "Gobernanza PRIMERO, luego técnica" +``` + +--- + +## MODOS DE EJECUCIÓN + +### MODE-FULL (Por defecto) + +```yaml +fases: [C, A, P, V, E, D] +uso: "Features, bug fixes, refactorizaciones, cambios BD" +alias: "@FULL" +``` + +### MODE-QUICK + +```yaml +fases: [E, D] +uso: "Typos, fixes menores, updates de deps, config simple" +alias: "@QUICK" +condicion: "Cambio trivial sin riesgo de impacto" +``` + +### MODE-ANALYSIS + +```yaml +fases: [C, A, P] +uso: "Investigación, auditoría, exploración, propuestas" +alias: "@ANALYSIS" +nota: "No modifica código" +``` + +### MODE-PROPAGATION + +```yaml +fases: [C, A, P, E, V, D] # Por cada proyecto destino +uso: "Propagar cambio existente a proyectos relacionados" +alias: "@PROPAGATE" +``` + +--- + +## INTEGRACIÓN CON TRIGGERS + +```yaml +triggers_por_fase: + A: + - TRIGGER-ANTI-DUPLICACION (si creación) + - TRIGGER-ANALISIS-DEPENDENCIAS (si modificación) + V: + - TRIGGER-DUPLICADOS (si se detectan) + D: + - TRIGGER-PROPAGACION-AUTOMATICA + - TRIGGER-DOCUMENTACION-OBLIGATORIA +``` + +--- + +## INTEGRACIÓN CON GOBERNANZA + +> **OBLIGATORIO:** Toda tarea que complete el ciclo CAPVED DEBE crear documentación de gobernanza. +> **BLOQUEANTE:** Sin gobernanza, la tarea NO está completada. + +```yaml +gobernanza: + checklist: "@DEF_CHK_GOB" + + pasos: + 1_carpeta_tarea: + accion: "Crear orchestration/tareas/TASK-{ID}/" + bloqueante: true + + 2_metadata: + accion: "Completar METADATA.yml con todos los campos obligatorios" + bloqueante: true + + 3_fases_minimas: + accion: "Documentar 01-CONTEXTO.md, 05-EJECUCION.md, 06-DOCUMENTACION.md" + bloqueante: true + + 4_actualizar_indices: + accion: "Actualizar orchestration/tareas/_INDEX.yml" + bloqueante: true + + 5_traza_agente: + accion: "Actualizar traza del agente ejecutor" + bloqueante: false + nota: "Recomendado pero no bloquea" + + si_falta_gobernanza: + mensaje: "❌ TAREA NO COMPLETADA - Falta documentación de gobernanza" + accion: "BLOQUEAR hasta completar" + referencia: "@DEF_CHK_GOB" + + recordatorio_todolist: | + Al iniciar cualquier tarea, el TodoList DEBE incluir como último item: + - content: "Crear documentación de gobernanza (TASK-{ID})" + status: "pending" + activeForm: "Documentando gobernanza" +``` + +--- + +## VALIDACIONES POR DOMINIO + +### Backend (NestJS) +```bash +npm run build # DEBE pasar +npm run lint # DEBE pasar +npm run test # Si existen, DEBEN pasar +``` + +### Frontend (React) +```bash +npm run build # DEBE pasar +npm run lint # DEBE pasar +npm run typecheck # DEBE pasar +``` + +### Database (PostgreSQL) +```bash +./scripts/recreate-database.sh # DEBE ejecutar sin errores +``` + +--- + +## REFERENCIAS + +| Alias | Descripción | +|-------|-------------| +| @DEF_CAPVED | Este protocolo | +| @PRINCIPIOS/PRINCIPIO-CAPVED.md | Principio base | +| @SIMCO/SIMCO-TAREA.md | Punto de entrada | +| @TRIGGER-DOC | Documentación obligatoria | + +--- + +**Versión:** 1.0.0 | **Sistema:** SIMCO v4.0.0 | **Tipo:** Protocolo Base diff --git a/orchestration/_definitions/protocols/CCA-PROTOCOL.md b/orchestration/_definitions/protocols/CCA-PROTOCOL.md new file mode 100644 index 0000000..3f35e63 --- /dev/null +++ b/orchestration/_definitions/protocols/CCA-PROTOCOL.md @@ -0,0 +1,245 @@ +# Protocolo CCA - Carga de Contexto Automática +## Definición Canónica (Fuente Única de Verdad) + +**Versión:** 1.0.0 +**Fecha:** 2026-01-16 +**Alias:** @DEF_CCA +**Tipo:** Definición Canónica + +--- + +## PROPÓSITO + +Este documento es la **ÚNICA** fuente de verdad para el Protocolo CCA. +Todos los perfiles de agentes deben **REFERENCIAR** este archivo, no copiar su contenido. + +--- + +## USO EN PERFILES + +```markdown +## PROTOCOLO CCA +> Definición: @DEF_CCA +> Variante: {dominio} + +### Extensiones Específicas +[Solo contenido específico del dominio] +``` + +--- + +## PROTOCOLO BASE + +> **ANTES de cualquier acción, ejecutar Carga de Contexto Automática** + +```yaml +# Al recibir: "Serás {PERFIL}-Agent en {PROYECTO} para {TAREA}" + +# ═══════════════════════════════════════════════════════════════ +# PASO 0: IDENTIFICAR NIVEL (OBLIGATORIO PRIMERO) +# ═══════════════════════════════════════════════════════════════ +PASO_0_IDENTIFICAR_NIVEL: + leer: "orchestration/directivas/simco/SIMCO-NIVELES.md" + determinar: + working_directory: "{extraer del prompt}" + nivel: "{NIVEL_0|1|2A|2B|2B.1|2B.2|3}" + orchestration_path: "{calcular según nivel}" + propagate_to: ["{niveles superiores si aplica}"] + registrar: + nivel_actual: "{nivel identificado}" + ruta_inventario: "{orchestration_path}/inventarios/" + ruta_traza: "{orchestration_path}/trazas/" + +# ═══════════════════════════════════════════════════════════════ +# PASO 1: IDENTIFICAR CONTEXTO +# ═══════════════════════════════════════════════════════════════ +PASO_1_IDENTIFICAR: + perfil: "{PERFIL}" # Nombre del perfil activo + proyecto: "{PROYECTO}" # Extraer del prompt + tarea: "{TAREA}" # Extraer del prompt + operacion: "CREAR | MODIFICAR | VALIDAR | DOCUMENTAR | BUSCAR" + dominio: "{DOMINIO}" # BACKEND | FRONTEND | DDL | DEVOPS | ML | etc. + +# ═══════════════════════════════════════════════════════════════ +# PASO 2: CARGAR CONTEXTO CORE (SIEMPRE) +# ═══════════════════════════════════════════════════════════════ +PASO_2_CARGAR_CORE: + leer_obligatorio: + # Catálogo primero (evitar duplicados) + - shared/catalog/CATALOG-INDEX.yml + + # Principios fundamentales + - orchestration/directivas/principios/PRINCIPIO-CAPVED.md + - orchestration/directivas/principios/PRINCIPIO-DOC-PRIMERO.md + - orchestration/directivas/principios/PRINCIPIO-ANTI-DUPLICACION.md + - orchestration/directivas/principios/PRINCIPIO-VALIDACION-OBLIGATORIA.md + - orchestration/directivas/principios/PRINCIPIO-ECONOMIA-TOKENS.md + + # Índices y referencias + - orchestration/directivas/simco/_INDEX.md + - orchestration/directivas/simco/SIMCO-TAREA.md + - orchestration/referencias/ALIASES.yml + +# ═══════════════════════════════════════════════════════════════ +# PASO 3: CARGAR CONTEXTO DEL PROYECTO +# ═══════════════════════════════════════════════════════════════ +PASO_3_CARGAR_PROYECTO: + leer_obligatorio: + - projects/{PROYECTO}/orchestration/00-guidelines/CONTEXTO-PROYECTO.md + - projects/{PROYECTO}/orchestration/PROXIMA-ACCION.md + + leer_segun_dominio: + # Ver sección VARIANTES POR DOMINIO + +# ═══════════════════════════════════════════════════════════════ +# PASO 4: CARGAR DIRECTIVAS DE OPERACIÓN +# ═══════════════════════════════════════════════════════════════ +PASO_4_CARGAR_OPERACION: + verificar_catalogo_primero: + - "grep -i '{funcionalidad}' @CATALOG_INDEX" + - si_existe: "Seguir @REUTILIZAR en lugar de crear" + + segun_operacion: + crear: ["SIMCO-CREAR.md", "SIMCO-{DOMINIO}.md"] + modificar: ["SIMCO-MODIFICAR.md", "SIMCO-{DOMINIO}.md"] + validar: ["SIMCO-VALIDAR.md"] + documentar: ["SIMCO-DOCUMENTAR.md"] + buscar: ["SIMCO-BUSCAR.md"] + +# ═══════════════════════════════════════════════════════════════ +# PASO 5: CARGAR CONTEXTO ESPECÍFICO DE TAREA +# ═══════════════════════════════════════════════════════════════ +PASO_5_CARGAR_TAREA: + - "Documentación relevante en docs/" + - "Código existente similar (patrones)" + - "Archivos relacionados con la tarea" + - "Identificar dependencias" + +# ═══════════════════════════════════════════════════════════════ +# PASO 6: VERIFICAR DEPENDENCIAS +# ═══════════════════════════════════════════════════════════════ +PASO_6_VERIFICAR_DEPENDENCIAS: + si_dependencia_no_existe: + accion: "DELEGAR al agente correspondiente" + no_continuar_hasta: "Dependencia resuelta" + + dependencias_por_dominio: + backend: + requiere: "Tablas DDL existen" + delegar_a: "@PERFIL_DATABASE" + frontend: + requiere: "Endpoints API existen" + delegar_a: "@PERFIL_BACKEND" + devops: + requiere: "Código funcional existe" + delegar_a: "@PERFIL_BACKEND o @PERFIL_FRONTEND" + +# ═══════════════════════════════════════════════════════════════ +# RESULTADO +# ═══════════════════════════════════════════════════════════════ +RESULTADO: "READY_TO_EXECUTE - Contexto completo cargado" +``` + +--- + +## VARIANTES POR DOMINIO + +### #backend +```yaml +PASO_3_CARGAR_PROYECTO: + leer_segun_dominio: + - projects/{PROYECTO}/orchestration/inventarios/BACKEND_INVENTORY.yml + - projects/{PROYECTO}/orchestration/inventarios/DATABASE_INVENTORY.yml + +PASO_4_CARGAR_OPERACION: + segun_tarea: + crear_entity: [SIMCO-CREAR.md, SIMCO-BACKEND.md] + crear_service: [SIMCO-CREAR.md, SIMCO-BACKEND.md] + crear_controller: [SIMCO-CREAR.md, SIMCO-BACKEND.md] + crear_dto: [SIMCO-CREAR.md, SIMCO-BACKEND.md] +``` + +### #frontend +```yaml +PASO_3_CARGAR_PROYECTO: + leer_segun_dominio: + - projects/{PROYECTO}/orchestration/inventarios/FRONTEND_INVENTORY.yml + +PASO_4_CARGAR_OPERACION: + segun_tarea: + crear_componente: [SIMCO-CREAR.md, SIMCO-FRONTEND.md] + crear_hook: [SIMCO-CREAR.md, SIMCO-FRONTEND.md] + crear_page: [SIMCO-CREAR.md, SIMCO-FRONTEND.md] +``` + +### #ddl +```yaml +PASO_3_CARGAR_PROYECTO: + leer_segun_dominio: + - projects/{PROYECTO}/orchestration/inventarios/DATABASE_INVENTORY.yml + - projects/{PROYECTO}/ddl/ # Esquemas existentes + +PASO_4_CARGAR_OPERACION: + segun_tarea: + crear_tabla: [SIMCO-CREAR.md, SIMCO-DDL.md] + crear_funcion: [SIMCO-CREAR.md, SIMCO-DDL.md] + crear_trigger: [SIMCO-CREAR.md, SIMCO-DDL.md] + crear_rls: [SIMCO-CREAR.md, SIMCO-DDL.md] +``` + +### #devops +```yaml +PASO_3_CARGAR_PROYECTO: + leer_segun_dominio: + - projects/{PROYECTO}/docker-compose.yml + - projects/{PROYECTO}/.env.example + +PASO_4_CARGAR_OPERACION: + segun_tarea: + crear_dockerfile: [SIMCO-CREAR.md, SIMCO-DEVOPS.md] + crear_pipeline: [SIMCO-CREAR.md, SIMCO-DEVOPS.md] +``` + +### #ml +```yaml +PASO_3_CARGAR_PROYECTO: + leer_segun_dominio: + - projects/{PROYECTO}/orchestration/inventarios/ML_INVENTORY.yml + - projects/{PROYECTO}/models/ + +PASO_4_CARGAR_OPERACION: + segun_tarea: + crear_modelo: [SIMCO-CREAR.md, SIMCO-ML.md] + crear_pipeline_ml: [SIMCO-CREAR.md, SIMCO-ML.md] +``` + +--- + +## VERSIÓN LIGERA (SUBAGENTES) + +Para subagentes con tareas específicas, usar versión reducida: + +```yaml +# CCA Ligero - Solo para subagentes +CCA_LIGHT: + PASO_1: "Identificar perfil, proyecto, tarea" + PASO_2: "Cargar ALIASES.yml" + PASO_3: "Cargar inventario del dominio" + PASO_4: "Cargar SIMCO de operación" + RESULTADO: "READY_TO_EXECUTE" +``` + +Ver también: @DEF_CCA_LIGHT + +--- + +## REFERENCIAS + +- **Perfiles que usan este protocolo:** Todos los perfiles en agents/perfiles/ +- **Directiva relacionada:** SIMCO-INICIALIZACION.md +- **Versión ligera:** @DEF_CCA_LIGHT + +--- + +**Última actualización:** 2026-01-16 +**Mantenido por:** @WS_ORCHESTRATOR diff --git a/orchestration/_definitions/validations/VALIDATION-BACKEND.md b/orchestration/_definitions/validations/VALIDATION-BACKEND.md new file mode 100644 index 0000000..8c15c75 --- /dev/null +++ b/orchestration/_definitions/validations/VALIDATION-BACKEND.md @@ -0,0 +1,81 @@ +# Validación Backend - NestJS/TypeScript +## Definición Canónica + +**Alias:** @DEF_VAL_BE +**Dominio:** Backend NestJS/TypeScript + +--- + +## COMANDOS OBLIGATORIOS + +```bash +# ANTES de marcar tarea como completada: +npm run build # DEBE pasar sin errores +npm run lint # DEBE pasar sin errores +npm run test # Si existen tests, DEBEN pasar +``` + +## CRITERIOS DE ACEPTACIÓN + +```yaml +build: + resultado: "Compila sin errores" + archivos_generados: "dist/" + sin_warnings_criticos: true + +lint: + resultado: "0 errores de ESLint" + warnings_permitidos: "Solo menores" + reglas_obligatorias: + - "@typescript-eslint/no-explicit-any" + - "@typescript-eslint/no-unused-vars" + +test: + resultado: "100% tests pasan" + coverage_minimo: "70% (si configurado)" + nuevos_tests: "Crear para código nuevo" +``` + +## VALIDACIONES ADICIONALES + +```yaml +entities: + - "Alineadas con DDL (nombres, tipos)" + - "Relaciones correctamente definidas" + - "Decoradores TypeORM correctos" + +services: + - "Inyección de dependencias correcta" + - "Manejo de errores implementado" + - "Transacciones donde aplique" + +controllers: + - "Decoradores Swagger completos" + - "Validación de DTOs" + - "Guards aplicados" + +dtos: + - "class-validator decoradores" + - "Tipos correctos" + - "Documentación Swagger" +``` + +## ERRORES COMUNES + +```yaml +- error: "Cannot find module" + causa: "Import incorrecto o dependencia faltante" + solucion: "Verificar rutas y npm install" + +- error: "Type X is not assignable to type Y" + causa: "Tipos incompatibles" + solucion: "Alinear tipos con DDL/interfaces" + +- error: "Circular dependency" + causa: "Módulos se importan mutuamente" + solucion: "Extraer a módulo compartido o forwardRef" +``` + +--- + +**Referencia:** @PERFIL_BACKEND, @SIMCO_BACKEND diff --git a/orchestration/_definitions/validations/VALIDATION-DDL.md b/orchestration/_definitions/validations/VALIDATION-DDL.md new file mode 100644 index 0000000..4a08f80 --- /dev/null +++ b/orchestration/_definitions/validations/VALIDATION-DDL.md @@ -0,0 +1,89 @@ +# Validación DDL - PostgreSQL +## Definición Canónica + +**Alias:** @DEF_VAL_DDL +**Dominio:** Database DDL PostgreSQL + +--- + +## COMANDOS OBLIGATORIOS + +```bash +# ANTES de marcar tarea como completada: + +# 1. Validar sintaxis SQL +psql -h localhost -U postgres -d {DB} -f {archivo}.sql --set ON_ERROR_STOP=1 + +# 2. Verificar que no hay errores +echo $? # Debe ser 0 + +# 3. Si existe script de recreación: +./scripts/recreate-database.sh # DEBE ejecutar sin errores +``` + +## CRITERIOS DE ACEPTACIÓN + +```yaml +sintaxis: + resultado: "SQL ejecuta sin errores" + encoding: "UTF-8" + schema_correcto: true + +convenciones: + tablas: "snake_case, plural (users, products)" + columnas: "snake_case (created_at, user_id)" + constraints: "{tabla}_{columna}_{tipo} (users_email_unique)" + indices: "idx_{tabla}_{columnas}" + foreign_keys: "fk_{tabla_origen}_{tabla_destino}" + +integridad: + - "Primary keys definidas" + - "Foreign keys con ON DELETE/UPDATE" + - "NOT NULL donde aplique" + - "DEFAULT values apropiados" + - "CHECK constraints donde necesario" +``` + +## VALIDACIONES ADICIONALES + +```yaml +tablas: + - "Columnas id, created_at, updated_at presentes" + - "Tipos de datos apropiados" + - "Índices en columnas de búsqueda frecuente" + +rls_policies: + - "Habilitado en tablas multi-tenant" + - "Políticas para SELECT, INSERT, UPDATE, DELETE" + - "Usando tenant_id del contexto" + +funciones: + - "SECURITY DEFINER/INVOKER correcto" + - "Manejo de errores (EXCEPTION)" + - "Documentación en comentarios" + +triggers: + - "Timing correcto (BEFORE/AFTER)" + - "Operaciones correctas (INSERT/UPDATE/DELETE)" + - "Función trigger existe" +``` + +## ERRORES COMUNES + +```yaml +- error: "relation already exists" + causa: "Tabla/objeto ya existe" + solucion: "Usar IF NOT EXISTS o DROP primero" + +- error: "foreign key constraint violation" + causa: "Referencia a registro inexistente" + solucion: "Verificar orden de inserción o CASCADE" + +- error: "column does not exist" + causa: "Nombre de columna incorrecto" + solucion: "Verificar nombres y comillas" +``` + +--- + +**Referencia:** @PERFIL_DATABASE, @SIMCO_DDL diff --git a/orchestration/_definitions/validations/VALIDATION-FRONTEND.md b/orchestration/_definitions/validations/VALIDATION-FRONTEND.md new file mode 100644 index 0000000..794cf41 --- /dev/null +++ b/orchestration/_definitions/validations/VALIDATION-FRONTEND.md @@ -0,0 +1,81 @@ +# Validación Frontend - React/TypeScript +## Definición Canónica + +**Alias:** @DEF_VAL_FE +**Dominio:** Frontend React/TypeScript + +--- + +## COMANDOS OBLIGATORIOS + +```bash +# ANTES de marcar tarea como completada: +npm run build # DEBE pasar sin errores +npm run lint # DEBE pasar sin errores +npm run typecheck # DEBE pasar sin errores (tsc --noEmit) +``` + +## CRITERIOS DE ACEPTACIÓN + +```yaml +build: + resultado: "Build de producción exitoso" + sin_warnings_criticos: true + bundle_size: "Monitorear incrementos grandes" + +lint: + resultado: "0 errores de ESLint" + reglas_react: + - "react-hooks/rules-of-hooks" + - "react-hooks/exhaustive-deps" + +typecheck: + resultado: "0 errores de TypeScript" + strict_mode: true + no_any_implicito: true +``` + +## VALIDACIONES ADICIONALES + +```yaml +componentes: + - "Props tipadas correctamente" + - "Keys únicas en listas" + - "Manejo de loading/error states" + - "Accesibilidad básica (aria labels)" + +hooks: + - "Dependencias completas en useEffect" + - "Cleanup en useEffect si necesario" + - "useMemo/useCallback donde aplique" + +estado: + - "Estado mínimo necesario" + - "Derivar datos cuando posible" + - "Zustand/Context correctamente usado" + +api: + - "Manejo de errores de red" + - "Estados de carga" + - "Cancelación de requests" +``` + +## ERRORES COMUNES + +```yaml +- error: "React Hook useEffect has missing dependency" + causa: "Dependencia no incluida en array" + solucion: "Agregar dependencia o usar useCallback" + +- error: "Cannot read property of undefined" + causa: "Datos async no disponibles" + solucion: "Optional chaining o loading state" + +- error: "Each child should have unique key" + causa: "Key faltante o duplicada en map()" + solucion: "Usar ID único como key" +``` + +--- + +**Referencia:** @PERFIL_FRONTEND, @SIMCO_FRONTEND