238 lines
12 KiB
Markdown
238 lines
12 KiB
Markdown
# Plan de implementación
|
||
|
||
Fecha: 2026-10-26. Fuente normativa: [especificación](../Specs_Orquestador_SpringBoot_PostgreSQL.md), 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.
|
||
|
||
- [x] Fijar versiones y BOM.
|
||
- [x] Generar Wrapper oficial.
|
||
- [x] Preparar paquetes y configuración.
|
||
- [x] 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.
|
||
|
||
- [x] Definir rutas, DTOs y errores.
|
||
- [x] Definir schema del flujo/AST/tareas.
|
||
- [x] 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.
|
||
|
||
## 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.
|
||
|
||
## 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.
|
||
|
||
## 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.
|
||
|
||
## 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.
|
||
- [ ] 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.
|
||
|
||
## 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.
|
||
|
||
## 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.
|
||
|
||
## 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.
|
||
|
||
Verificación: IT dos workers, lease vencido y checkpoint; no @Async en memoria. Cierre: Cola durable multiinstancia; worker obsoleto no confirma.
|
||
|
||
## 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 de cliente encontrado/no encontrado, timeout y salida inválida. Cierre: A01–A03; fallos técnicos separados del resultado de negocio.
|
||
|
||
## 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.
|
||
|
||
## 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.
|
||
|
||
## 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.
|
||
|
||
## 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.
|
||
|
||
## 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.
|
||
|
||
Verificación: ./mvnw clean verify con Docker, sin skips de integración. Cierre: Todos los casos obligatorios pasan en entorno reproducible.
|
||
|
||
## 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.
|