MyNMP
/
orquestador
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
orquestador/specs/IMPLEMENTATION_PLAN.md

17 KiB
Raw Blame History

Plan de implementación

Fecha: 2026-10-26. Fuente normativa: especificación, secciones 13–16.

El alcance actual es crear el arquetipo y dejar preparada la ejecución del plan. La implementación funcional continúa por tareas autorizadas. Una sola tarea principal IN_PROGRESS; elegir la primera pendiente con dependencias DONE. Un bloqueo externo se documenta y no equivale a una prueba aprobada.

Secuencia y criterios

ID Tarea Dependencias Criterio de cierre
T01 Bootstrap y ADR de versiones — Wrapper reproducible, compilación y health local comprobados
T02 Contratos OpenAPI y JSON Schema del DSL T01 OpenAPI 3.1 y schemas completos; ejemplos validados
T03 Modelo PostgreSQL y Flyway T02 Restricciones e inmutabilidad verificadas en PostgreSQL real
T04 Modelo de dominio y puertos T02,T03 Dominio sin HTTP/JPA y contratos tipados
T05 Evaluador de decisiones T04 A04–A06 y errores de evaluación comprobados
T06 Validador, publicación y activación T03,T04,T05 A16–A17; catálogo resoluble y publicación consistente
T07 Seguridad y autorización por recurso T04 A15; rutas protegidas antes de exposición
T08 Crear y consultar solicitudes T06,T07 Creación atómica e idempotente, versión fijada
T09 Aceptar eventos idempotentes T08 A07–A09; aceptación durable sin HTTP
T10 Worker PostgreSQL y leases T09 Cola durable multiinstancia; worker obsoleto no confirma
T11 Handlers e integraciones HTTP T10 A01–A03; fallos técnicos separados del resultado de negocio
T12 Reintentos y conciliación T11 A12–A14,A19; efectos inciertos no liberan solicitud
T13 Documentos y tareas para front T11,T12 A11,A20; INVALID conserva tarea, error técnico no equivale a INVALID
T14 Flujos demostrativos v1/v2 T05,T06,T13 A10,A18; dos tipos de solicitud publicables
T15 Auditoría y observabilidad T09,T10,T11,T12,T13,T14 Auditoría atómica desde T06 y operación observable
T16 Verificación integral T15 Todos los casos obligatorios pasan en entorno reproducible
T17 Empaquetado y documentación T16 Checkout limpio reproduce definición final de terminado

T01 — Bootstrap y ADR de versiones

Dependencias: —. Entregables: pom.xml, mvnw*, .mvn, configuración, ADR-001.

  • Fijar versiones y BOM.
  • Generar Wrapper oficial.
  • Preparar paquetes y configuración.
  • Ejecutar compilación y smoke test de salud con JDK 21/PostgreSQL.

Verificación: JDK 21; ./mvnw clean verify; arranque local y HTTP health. Cierre: Wrapper reproducible, compilación y health local comprobados.

Cerrado el 2026-10-26: clean verify -Pdeployment-smoke -Dsmoke.baseUrl=http://server02:8787 con JDK 21.0.12.1 y Maven 3.9.12, 5 pruebas aprobadas, 0 omitidas. Compilación en el equipo de desarrollo y smoke sobre el despliegue de la red local con PostgreSQL externo, conforme a ADR-004. Evidencia detallada en PROGRESS.

T02 — Contratos OpenAPI y JSON Schema del DSL

Dependencias: T01. Entregables: contracts/openapi.yaml, schemas/, ejemplos contractuales.

  • Definir rutas, DTOs y errores.
  • Definir schema del flujo/AST/tareas.
  • Validar ejemplos y casos inválidos automáticamente.

Verificación: Validador OpenAPI/JSON Schema dentro de verify. Cierre: OpenAPI 3.1 y schemas completos; ejemplos validados.

Cerrado el 2026-10-26: clean verify con Java 21, 92 comprobaciones, 0 fallos/errores/omisiones. Contrato de 14 operaciones, DSL 2020-12, DTOs y resultados normalizados de ejemplo. Las pruebas verifican estructura/ejemplos/referencias, no comportamiento del motor; ver ADR-005 y evidencia E10.

T03 — Modelo PostgreSQL y Flyway

Dependencias: T02. Entregables: db/migration/, pruebas *IT.

Entorno objetivo actualizado por el usuario: PostgreSQL 9.6.2 disponible en server02; ver ADR-006. Usar DDL compatible con 9.6 y un entorno aislado para pruebas de escritura. La comprobación de conexión/arranque E11 no cierra esta tarea.

  • Crear tablas, FKs e índices.
  • Añadir idempotencia de creación/admin_audit/reconciliation_resolution.
  • Proteger inmutabilidad e historial con roles y triggers.
  • Probar migraciones desde cero.

Verificación: Testcontainers PostgreSQL, rollback y migraciones. Cierre: Restricciones e inmutabilidad verificadas en PostgreSQL real.

Cerrado el 2026-10-26: 92 contratos y 40 pruebas de integración aprobadas mediante clean verify -Pmigration-tests-external sobre PostgreSQL 9.6.2 real en orquestador_test. Migraciones, rollback, permisos y concurrencia verificados; aislamiento y alternativa a Docker local documentados en ADR-007/E12.

T04 — Modelo de dominio y puertos

Dependencias: T02,T03. Entregables: flow/, request/, execution/, decision/, action/.

  • Definir records y errores estables.
  • Separar DTOs y entidades.
  • Implementar puertos DecisionEvaluator, ActionHandler y FlowDefinitionValidator.

Verificación: Pruebas de dominio y dependencias entre capas. Cierre: Dominio sin HTTP/JPA y contratos tipados.

Cerrado el 2026-10-26: mvnw test con Java 21; 134 pruebas aprobadas, incluidas 42 de dominio/arquitectura/frontera. Dominio y puertos recompilados sin infraestructura y DTO validado contra el contrato existente. No hay entidades JPA ni endpoints nuevos; implementaciones de puertos pendientes de T05/T06/T11. Evidencia E13 y ADR-008.

T05 — Evaluador de decisiones

Dependencias: T04. Entregables: decision/, pruebas de AST.

  • Implementar operadores/JSON Pointer/BigDecimal.
  • Distinguir null y ausente.
  • Aplicar límites y cortocircuito.
  • Resolver UNIQUE/FIRST y ambigüedad.

Verificación: JUnit parametrizado: 71/70/61/60, tipos y solapamientos. Cierre: A04–A06 y errores de evaluación comprobados.

Cerrado el 2026-10-26: mvnw test con Java 21; 216 pruebas aprobadas, incluidas 82 nuevas de decisiones/pointers/intervalos. A04–A06 verificados al nivel de evaluador puro y contrato de salida; no como flujo REST completo. Límites, cortocircuito y arquitectura comprobados. Ver E14, ADR-009 y DECISION_EVALUATOR.md.

T06 — Validador, publicación y activación

Dependencias: T03,T04,T05. Entregables: flow/, admin_audit, pruebas *IT.

  • Validar grafo, mappings, roles y capacidades.
  • Editar borradores con revision.
  • Publicar checksum canónico e inmutabilidad.
  • Activar/retirar con bloqueos y auditoría.

Verificación: Pruebas PostgreSQL de carreras publicación/activación/retiro. Cierre: A16–A17; catálogo resoluble y publicación consistente.

Cerrado el 2026-10-26 para servicios internos: clean verify -Pmigration-tests-external, 258 pruebas unitarias + 51 IT PostgreSQL aprobadas (309 total). A16 verificado en servicio/DB y A17 con asignación transaccional real; exposición REST/JWT queda en T07 conforme a ADR-010. No se anuncia A16 HTTP completo ni integración de proveedor real. Evidencia E15 y FLOW_PUBLICATION.md.

T07 — Seguridad y autorización por recurso

Dependencias: T04. Entregables: shared/infrastructure/security/, autorización por capacidad.

  • Validar JWT real (firma/issuer/audience/exp).
  • Mapear permisos técnicos y roles.
  • Conectar catálogo confiable/servicios T06 y exponer administración REST con pruebas JWT; completar A16 HTTP (ADR-010).
  • Comprobar propiedad/scope en cada recurso.
  • Separar rol DB de ejecución.

Verificación: Tokens firmados válidos/expirados, otro issuer/audience, scope/rol ajenos. Cierre: A15; rutas protegidas antes de exposición.

Cerrado el 2026-10-27: 265 unitarias + 57 IT (322 total), sin fallos/errores/omisiones. Evidencia E16, SECURITY.md y ADR-011. A15 verificado mediante puerta real de recursos y controlador exclusivo de test; endpoints de negocio futuros deben integrarla. Keycloak real y despliegue pendientes. Simulación HTTP pendiente; seguimiento explícito en T16 (ADR-018).

T08 — Crear y consultar solicitudes

Dependencias: T06,T07. Entregables: request/, repositorios y API.

  • Resolver y fijar flujo activo.
  • Validar datos iniciales.
  • Idempotencia durable de creación.
  • Exponer consulta y ETag con acceso por recurso.

Verificación: IT creación repetida/conflictiva y activación concurrente. Cierre: Creación atómica e idempotente, versión fijada.

Cerrado el 2026-10-27: clean verify -Pmigration-tests-external, 268 unitarias + 66 IT (334 total), cero fallos/errores/omisiones. Creación/replay/consulta HTTP, activación y retiro con barreras, rollback SQL. Evidencia E17, REQUESTS.md y ADR-012. Sin despliegue.

T09 — Aceptar eventos idempotentes

Dependencias: T08. Entregables: execution/api, aceptación, auditoría.

  • Bloquear solicitud.
  • Verificar hash antes de revisión.
  • Validar If-Match/rol/guardia.
  • Insertar PENDING, revision y auditoría atómicamente.
  • Responder 202/Location.

Verificación: IT duplicados, conflictos, concurrencia y rollback. Cierre: A07–A09; aceptación durable sin HTTP.

Cerrado el 2026-10-27: clean verify -Pmigration-tests-external, 268 unitarias + 76 IT (344 total), cero fallos/errores/omisiones. A07–A09 cubiertos en aceptación, sin acciones externas. Evidencia E18, EVENTS.md y ADR-013. Worker y GET ejecución pendientes T10; sin despliegue.

T10 — Worker PostgreSQL y leases

Dependencias: T09. Entregables: execution/infrastructure, worker y repositorios.

  • Reclamar con SKIP LOCKED.
  • Renovar lease con tiempo DB.
  • Exigir owner/token en escrituras.
  • Checkpoints por acción y recuperación inicial.
  • Exponer GET /executions/{id} con autorización y estado técnico (seguimiento del Location T09; ADR-013).

Verificación: IT dos workers, lease vencido y checkpoint; no @Async en memoria. Cierre: Cola durable multiinstancia; worker obsoleto no confirma.

Cerrado el 2026-10-27. Suite completa: 268 unitarias + 91 IT; tras dos controles adicionales, verificación final: 268 unitarias + 17 WorkerIT. Evidencia vigente de 361 casos distintos (268 + 93), todos aprobados. Ver E19, WORKER.md y ADR-014. Sin despliegue ni proveedores reales; adapters T11 y política completa de retry T12 pendientes.

T11 — Handlers e integraciones HTTP

Dependencias: T10. Entregables: action/, integration/, mocks, compose.yaml.

  • Implementar catálogo confiable y REGISTER_DOCUMENT/INVOKE_INTEGRATION/NO_OP sólo simulación.
  • Fijar contratos/perfiles.
  • Mapear entradas/salidas y timeouts.
  • Añadir mocks.

Verificación: Mocks HTTP de cliente encontrado/no encontrado, timeout y salida inválida; worker con PostgreSQL real, contratos fijados y rollback documental. Cierre T11: A01/A02 y separación técnica de A03. La programación completa de reintentos de A03 corresponde a T12; ver ADR-015. Proveedores reales requieren contratos/credenciales confirmados y no son sustituidos por evidencia de mocks.

Cerrado el 2026-10-27: 301 unitarias + 99 IT = 400 aprobadas en la suite completa, sin fallos/errores/omisiones. Evidencia E20, INTEGRATIONS.md y ADR-015. Mocks HTTP locales y PostgreSQL real; integración real pendiente de contratos/credenciales. Siguiente T12.

T12 — Reintentos y conciliación

Dependencias: T11. Entregables: execution/, endpoint resolve, pruebas *IT.

  • Limitar intentos/backoff/jitter.
  • Recuperar leases según clasificación de efecto.
  • Tratar UNKNOWN.
  • Conciliar con evidencia y autorización/idempotencia.

Verificación: Fault injection antes/después de envío, checkpoint y commit. Cierre: A12–A14,A19; efectos inciertos no liberan solicitud.

Cerrado el 2026-10-27: 303 unitarias + 116 IT = 419 aprobadas; 17 casos T12 incluyen cinco caídas reales de JVM, retries, conciliación concurrente y rollback. Ver E21, RECONCILIATION.md y ADR-016. Sin despliegue ni proveedor real. Siguiente T13.

T13 — Documentos y tareas para front

Dependencias: T11,T12. Entregables: document/, request/available-events.

  • Verificar pertenencia/tipo/MIME/tamaño/checksum/antimalware.
  • Guardar referencias.
  • Exponer schemas/UI y bloqueos.
  • Impedir escritura de resultados del proveedor.

Verificación: Documento ajeno/inválido, ejecución activa y payload con score. Cierre: A11,A20; INVALID conserva tarea, error técnico no equivale a INVALID.

Cerrado el 2026-10-27: 308 unitarias + 137 IT = 445 aprobadas; incluye 8 casos de disponibilidad y 13 documentales con PostgreSQL real y mocks HTTP. Ver E22, AVAILABLE_EVENTS.md y ADR-017. Backend únicamente; sin interfaz gráfica, despliegue ni documentos reales. Siguiente T14.

T14 — Flujos demostrativos v1/v2

Dependencias: T05,T06,T13. Entregables: examples/flows/, examples/http/.

  • Crear crédito v1, crédito v2 con licencia y compra v1 completos.
  • Publicar/activar y recorrer.
  • Demostrar coexistencia de versiones sin cambios Java/columnas.

Verificación: Recorridos completos de v1/v2, licencia válida/inválida y fronteras. Cierre: A10,A18; dos tipos de solicitud publicables.

Cerrado el 2026-10-28: 311 unitarias + 29 IT = 340 aprobadas; demo 10, documentos 13 y HTTP 6. Ver E23 y ADR-018. Tres flujos publicados/activados y recorridos con mocks; src/main y JAR idénticos a T13. Siguiente T15.

T15 — Auditoría y observabilidad

Dependencias: T09,T10,T11,T12,T13,T14. Entregables: audit/, métricas, logs, health.

  • Completar consultas paginadas/filtradas.
  • Métricas sin cardinalidad por solicitud.
  • Logs sin PII.
  • Readiness/liveness y apagado ordenado.

Verificación: Rollback/auditoría, acceso a historial, métricas y apagado. Cierre: Auditoría atómica desde T06 y operación observable.

Cerrado el 2026-10-28: 314 unitarias + 163 IT = 477 aprobadas, más 4 unitarias + 1 IT para el ajuste final de cursor. Ver E24, OBSERVABILITY.md y ADR-019. Historial/ACL, métricas, logs, DB-health, apagado y rollback verificados localmente; siguiente T16.

T16 — Verificación integral

Dependencias: T15. Entregables: src/test/, CI, matriz A01–A20.

  • Automatizar A01–A20.

  • Reinicios y concurrencia deterministas.

  • Verificar fronteras de rollback y seguridad.

  • Conservar reportes.

  • Cerrar pendiente del endpoint puro /admin/flows/{id}/simulate, registrado desde T07 (ADR-018); implementado/verificado por SimulationIT y FlowSimulationTest (ADR-020).

  • Ejecutar suite completa y gate A01–A20 con Docker/Testcontainers operativo.

Verificación: ./mvnw clean verify con Docker, sin skips de integración. Cierre: Todos los casos obligatorios pasan en entorno reproducible.

Estado 2026-10-28: BLOCKED solo por entorno Docker. Implementación/simulación, CI y matriz completos; 493 pruebas Java y 2 del checker aprobadas con PostgreSQL externo. Testcontainers confirmó ausencia de motor válido. Ver E25, ACCEPTANCE.md y ADR-020; no equivale a cierre Docker.

T17 — Empaquetado y documentación

Dependencias: T16. Entregables: Dockerfile, compose.yaml, README, RUNBOOK, examples/http, CI.

  • Construir imagen y Compose completos.
  • Incluir mocks e issuer local documentado.
  • Ejecutar demo desde checkout limpio.
  • Documentar límites, recuperación y contratos reales pendientes.

Verificación: Build de imagen, compose, verify y demo completa de sección 16. Cierre: Checkout limpio reproduce definición final de terminado.

Reglas de ejecución

Antes de codificar, revisar criterios y prueba pertinente. Al cerrar, registrar fecha, archivos, comando exacto y resultado en PROGRESS. Mantener actualizados contrato, migraciones y pruebas cuando cambie el comportamiento. Auditoría mínima acompaña cada escritura desde T06; T15 completa consultas y operación. T06 puede implementar servicios internos, pero sus endpoints no se exponen antes de T07. No modificar semántica de seguridad/idempotencia/versionado sin ADR.

Matriz de aceptación

Casos Tarea responsable Evidencia final
A01–A03 T11 Cliente encontrado/no encontrado/fallo técnico
A04–A06 T05 Fronteras, contratos inválidos y UNIQUE ambiguo
A07–A09 T09 Idempotencia y concurrencia de eventos
A10,A18 T14 Coexistencia v1/v2 y licencia configurable
A11,A20 T13 Documentos y protección de resultados
A12–A14,A19 T12 Recuperación, efectos inciertos y rollback
A15 T07 Autorización por rol/scope/propiedad
A16–A17 T06 Inmutabilidad y activación/retiro concurrentes

T16 vuelve a ejecutar la matriz completa; pruebas unitarias no sustituyen PostgreSQL real. La integración real con proveedores permanece pendiente si faltan contrato/credenciales, aunque los mocks pasen.

Seguimiento T16 (2026-10-28, E26): corregidas las entradas del build Docker para incluir ejemplos de flujos/integraciones y los dos archivos de configuración requeridos. Package aislado: 326 pruebas aprobadas. Pendientes build Docker real y suite Testcontainers para el cierre.