146 lines
9.2 KiB
Markdown
146 lines
9.2 KiB
Markdown
# Orquestador NMP
|
||
|
||
Arquetipo de un microservicio Spring Boot para ejecutar flujos configurables y versionados sobre PostgreSQL. La fuente funcional es [la especificación](Specs_Orquestador_SpringBoot_PostgreSQL.md).
|
||
|
||
## Estado
|
||
|
||
Incluye la estructura Maven, configuración JWT/PostgreSQL, Docker y salud verificada (T01), además del [contrato OpenAPI](contracts/openapi.yaml), [JSON Schema del DSL](schemas/flow-definition.schema.json) y ejemplos con validación automática (T02). El motor, endpoints de negocio, migraciones y flujos completos todavía están pendientes. Consultar [PROGRESS](specs/PROGRESS.md) para evidencia y bloqueos.
|
||
|
||
## Requisitos y ejecución
|
||
|
||
- 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.
|
||
|
||
```powershell
|
||
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](specs/RUNBOOK.md).
|
||
|
||
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](specs/ARCHITECTURE.md): paquetes y fronteras.
|
||
- [Decisiones](specs/DECISIONS.md): versiones y motivos.
|
||
- [Administración interna T06](specs/FLOW_PUBLICATION.md): validación, publicación, catálogo y transacciones; REST seguro pendiente de T07.
|
||
- [Plan T01–T17](specs/IMPLEMENTATION_PLAN.md): dependencias, subtareas y criterios de cierre.
|
||
- [Seguimiento](specs/PROGRESS.md): 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:
|
||
|
||
```powershell
|
||
.\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](contracts/README.md), [semántica del DSL](schemas/README.md) y [fixtures T02](examples/contracts/README.md). 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](specs/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](specs/REQUESTS.md); [ejemplo HTTP](examples/http/requests.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](specs/EVENTS.md) y [ejemplo](examples/http/events.http).
|
||
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](specs/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](specs/INTEGRATIONS.md);
|
||
[ejemplos de contratos](examples/integrations/publication-catalog.json) y
|
||
[rutas](examples/integrations/integration-routes.example.json).
|
||
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](specs/RECONCILIATION.md);
|
||
[ejemplos HTTP](examples/http/reconciliation.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](specs/AVAILABLE_EVENTS.md);
|
||
[ejemplo HTTP](examples/http/available-events.http).
|
||
|
||
## Flujos de demostración (T14)
|
||
|
||
[Crédito v1/v2 y compra](examples/flows/README.md) 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](specs/OBSERVABILITY.md);
|
||
[ejemplos HTTP](examples/http/history-operations.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](specs/ACCEPTANCE.md). 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](specs/SIMULATION.md) y
|
||
[ejemplo HTTP](examples/http/simulate.http).
|