Orquestador NMP

Arquetipo de un microservicio Spring Boot para ejecutar flujos configurables y versionados sobre PostgreSQL. La fuente funcional es la especificación.

Estado

Incluye la estructura Maven, configuración JWT/PostgreSQL, Docker y salud verificada (T01), además del contrato OpenAPI, JSON Schema del DSL y ejemplos con validación automática (T02). El motor, endpoints de negocio, migraciones y flujos completos todavía están pendientes. Consultar PROGRESS para evidencia y bloqueos.

Requisitos y ejecución

Para configurar respuestas de proveedores manualmente desde Postman, consultar Proveedores mock. El archivo opcional compose.mock.yaml añade el servicio HTTP de demo en microsipNet; el Compose base conserva el servicio conectado a PostgreSQL externo. La POC puede usar token fijo sin Keycloak mediante el perfil demo-token.

• Docker con contenedores Linux y Compose v2. La imagen compila con JDK 21 y Maven Wrapper; no requiere Java/Maven en el anfitrión.
• PostgreSQL externo con base y usuario existentes, accesible desde Docker. El entorno actual usa PostgreSQL 9.6.2 en server02:30432 mediante el perfil postgres96; ver ADR-006.
• Un issuer JWT con JWKS y audiencia; se conserva la autenticación.

Copy-Item .env.example .env
# Completar DB_URL, DB_USERNAME, DB_PASSWORD y parámetros JWT.
docker compose config --quiet
docker compose up --build -d
docker compose ps
docker compose logs -f orquestador

Compose levanta únicamente orquestador. Para PostgreSQL en otra máquina usar jdbc:postgresql://HOST:5432/BASE; si está en el anfitrión de Docker, usar host.docker.internal en lugar de localhost. Ver RUNBOOK.

Compose selecciona postgres96 por defecto para el servidor disponible. .env.example contiene su URL/usuario y los endpoints Keycloak; completar DB_PASSWORD externamente y confirmar JWT_AUDIENCE con los tokens. Para una base moderna se puede seleccionar otro perfil, como SPRING_PROFILES_ACTIVE=local, conservando su DB_URL explícita. No se desactivan Flyway ni la validación del esquema en el servicio.

Salud: http://localhost:8080/actuator/health/readiness. El puerto publicado se configura con APP_PORT. El healthcheck incluye PostgreSQL; liveness no depende de proveedores. Las demás rutas requieren JWT. No hay endpoints de negocio implementados todavía.

Organización y seguimiento

• Arquitectura: paquetes y fronteras.
• Decisiones: versiones y motivos.
• Administración interna T06: validación, publicación, catálogo y transacciones; REST seguro pendiente de T07.
• Plan T01–T17: dependencias, subtareas y criterios de cierre.
• Seguimiento: estado real, verificaciones y siguiente paso.

Surefire ejecuta *Test en test; Failsafe ejecuta *IT en verify. T01 incorpora un smoke de despliegue con cinco comprobaciones; T03 incorpora Testcontainers PostgreSQL 9.6.24 y requiere Docker para verify. CI ejecuta clean verify sin acceder a servidores privados. Para verificar explícitamente un servicio iniciado, usar JDK 21 y ejecutar:

.\mvnw.cmd clean verify -Pdeployment-smoke '-Dsmoke.baseUrl=http://server02:8787'

Este perfil comprueba salud, readiness, liveness y rechazo de solicitudes sin token/con token malformado. No contiene todavía pruebas de negocio ni de JWT válido.

test valida los contratos y sus ejemplos sin servicios externos; clean verify agrega migraciones e integración PostgreSQL. Sin Docker local, usar el perfil migration-tests-external descrito en RUNBOOK. Consultar convenciones REST, semántica del DSL y fixtures T02. Los ejemplos de examples/http/contracts.http son contratos objetivo, no endpoints implementados. Los flujos de crédito completos corresponden a T14.

El Dockerfile incluye contratos/schemas/fixtures en la etapa de construcción para ejecutar las mismas pruebas y ejecuta con JRE 21 como usuario no root. Compose no administra PostgreSQL ni sus volúmenes. T03 incluye migraciones y permisos PostgreSQL; mocks y autorización funcional siguen pendientes de T11/T07.

Límites funcionales previstos

Nuevos umbrales, destinos y pasos con capacidades existentes se publicarán como configuración. Una nueva capacidad de validación puede requerir un adapter; un nuevo tipo de tarea puede requerir soporte del front. No incluye UI administrativa, Kafka, Drools ni migración automática de instancias.

Seguridad y administración (T07)

La administración REST requiere habilitación explícita y credenciales PostgreSQL separadas de migración/ejecución. Ver SECURITY.md y las variables nuevas de .env.example. Compose conserva únicamente el servicio y monta config/ como solo lectura; PostgreSQL sigue externo. No se ha desplegado esta versión.

Solicitudes (T08)

Implementados POST y GET de solicitudes, con versión fijada, idempotencia durable, validación de datos y autorización. Habilitar REQUEST_API_ENABLED=true únicamente con runtime DB restringido; administración puede permanecer apagada. Configuración y semántica; ejemplo HTTP. No se ha desplegado esta versión. Eventos y worker continúan pendientes.

Eventos (T09)

POST /requests/{id}/events acepta comandos idempotentes y retorna 202/Location. Ejecución PENDING, revisión y auditoría se confirman juntas. Ver EVENTS.md y ejemplo. El worker y GET de ejecución continúan pendientes en T10: 202 no indica que se haya procesado la acción. No se desplegó esta versión.

Worker y consulta de ejecución (T10)

GET /api/v1/executions/{id} ya permite seguimiento autorizado. WORKER_ENABLED=true activa procesamiento durable con leases y checkpoints; defaults y límites en WORKER.md. V3 conserva clasificación de efectos de acciones. Los adapters T11 requieren contratos y rutas configurados; los registros por defecto están vacíos. Flujos sin acciones pueden concluir. No se ha desplegado esta versión ni se han invocado proveedores reales.

Integraciones (T11)

INVOKE_INTEGRATION ejecuta POST JSON con contratos/perfiles fijados y límites de tiempo y tamaño. REGISTER_DOCUMENT verifica metadatos y registra referencias de forma atómica. NO_OP se limita a simulación. Configuración y límites; ejemplos de contratos y rutas. Los ejemplos usan dominios .invalid y datos sintéticos; requieren adaptación al proveedor real. Compose sigue levantando únicamente el servicio con PostgreSQL externo.

Reintentos y conciliación (T12)

El worker programa reintentos durables para fallos transitorios seguros, con backoff, jitter y Retry-After acotados. Los efectos inciertos mantienen bloqueada la solicitud hasta una resolución con evidencia por EXECUTION_OPERATOR. Operación y límites; ejemplos HTTP. La resolución requiere administración habilitada y ámbito autorizado; no permite elegir manualmente el estado de negocio. La evidencia es verificada por el operador, sin consulta automática a un proveedor real.

Eventos disponibles y documentos (T13)

GET /api/v1/requests/{id}/available-events devuelve eventos, schemas y metadatos FORM/DOCUMENT_UPLOAD de la versión fijada; oculta tareas con ejecución activa. No incluye desarrollar una interfaz gráfica. El worker verifica también los límites documentales de la tarea publicada. Semántica y pruebas; ejemplo HTTP.

Flujos de demostración (T14)

Crédito v1/v2 y compra incluyen definiciones completas, catálogo y ejemplos HTTP. DemoFlowsIT publica y recorre los archivos exactos usando API, worker, PostgreSQL de pruebas y proveedores HTTP simulados. La v2 incorpora licencia por configuración; las solicitudes existentes conservan v1. No hay front ni cobro real. La integración de proveedores reales requiere validación separada.

Auditoría y observabilidad (T15)

GET /api/v1/requests/{id}/history consulta el historial del propietario y ámbito con filtros y cursor. Actuator metrics requiere EXECUTION_OPERATOR y un ámbito incluido en ADMIN_BUSINESS_SCOPES. Incluye estados de cola, edad del pendiente, leases vencidos, resultados HTTP y latencia de integraciones sin etiquetas por UUID. Operación y límites; ejemplos HTTP. WORKER_SHUTDOWN_SECONDS controla el drenaje (1–20 s, predeterminado 20).

Verificación integral y simulación (T16)

Guía y matriz ejecutable A01–A20. Después de clean verify, python scripts/verify_acceptance.py --require-testcontainers exige evidencia de cada caso y ningún test omitido. El perfil externo identifica explícitamente su entorno y no pasa esa puerta Docker. CI archiva reportes y matriz.

POST /api/v1/admin/flows/{id}/simulate evalúa fixtures con FLOW_EDITOR y ámbito administrativo autorizado. Usa la proyección compartida con el worker, sin proveedores ni escrituras de negocio. Semántica y ejemplo HTTP.