orquestador/README.md

# 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

Para configurar respuestas de proveedores manualmente desde Postman, consultar
[Proveedores mock](demo/providers-mock/README.md). 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](specs/POC_AUTH.md) 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.

```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).