History

JOSE ANASTACIO ESQUIVEL SALAS 21f5861e1b actualizacion		2026-10-28 08:37:46 -06:00
..
validation	first commit	2026-10-26 12:18:03 -06:00
README.md	actualizacion	2026-10-28 08:37:46 -06:00
openapi.yaml	actualizacion	2026-10-28 08:37:46 -06:00

README.md

Contrato REST del orquestador

openapi.yaml define OpenAPI 3.1.0 para las 14 operaciones de la sección 10 de la especificación. Base /api/v1, JWT Bearer obligatorio y autorización por recurso. Es un contrato objetivo: T02 no implementa controladores ni conecta proveedores.

Los DTOs se referencian desde ../schemas/api.schema.json; las definiciones de flujo desde ../schemas/flow-definition.schema.json. Conservar esta estructura al abrir el contrato en un visor compatible con OpenAPI 3.1. No instalar springdoc ni habilitar Swagger UI en runtime todavía. Para usar un servidor estático, publicar juntos contracts/ y schemas/; abrir sólo un archivo sin sus referencias no basta.

Convenciones

UUID como string; fechas UTC con sufijo Z; campos opcionales ausentes se omiten, sin null salvo dentro de datos configurables.
data es extensible, pero se valida también con el schema del flujo/evento. El DTO genérico no permite saltarse esa segunda validación.
Identidad, scope, permisos, estado, revision y resultados externos no se toman de campos enviados por el cliente. Los wrappers de comandos rechazan propiedades adicionales.
If-Match es un único ETag fuerte entre comillas, como "7"; falta: 428; desajuste: 412. Se exige en eventos, edición de borrador, publicación, retiro y activación. El ETag de activación pertenece al tipo.
Idempotency-Key es obligatorio en creación, eventos y conciliación. Creación: unicidad actor/scope; eventos y conciliación: por recurso. Comando canónico distinto con misma clave: 409. En eventos se comprueba replay antes de revisión; se conserva executionId y se devuelve estado actual de la ejecución.
Aceptación de evento devuelve 202 y Location. No supone éxito de negocio. SUCCEEDED puede contener CLIENTE_NO_ENCONTRADO, manteniendo el estado.
available-events es orientativo. Durante una ejecución activa: events vacío y blockedByExecutionId presente.
Historial ordenado por (createdAt,id), cursor opaco, máximo 100. Filtros kind, executionId, from inclusivo y to exclusivo; nextCursor se omite al terminar.
Errores application/problem+json con status, code y correlationId; detalles filtrados. 404 oculta recursos de otro scope; 403 representa permiso insuficiente cuando revelar el recurso está permitido.
x-required-roles enumera roles técnicos alternativos (OR); no reemplaza autorización por recurso. ANALISTA y otros roles de negocio se definen en las transiciones y se revalidan al aceptar.

Administración

Creación/edición reciben la definición completa. flowKey y version forman identidad inmutable, incluso al editar el borrador. Validación semántica retorna 200 con valid=false y errores JSON Pointer; publicación rechaza una definición inválida con 422. La publicación fija contractVersion/profileVersion desde catálogo confiable antes del checksum.

La simulación recibe actor/requestData/results de prueba, evalúa guardia/decisión/updates y no realiza HTTP ni efectos persistentes. Los fixtures de simulación nunca son datos confiables para el endpoint de eventos.

Tipos de solicitud se provisionarán en T03/T06 mediante migraciones/configuración administrativa; este MVP no agrega un endpoint de alta de tipos. Activar un tipo inexistente retorna 404. Retiro conserva las solicitudes existentes y bloquea nuevas asignaciones concurrentes.

Conciliación sólo permite RESUME con resultados verificados por acción o CLOSE_WITHOUT_TRANSITION con ausencia/compensación de efectos verificada. La evidencia es una referencia y motivo, no documentos personales ni secretos. El operador autorizado verifica la evidencia; el cliente no puede escoger estado destino. La resolución es idempotente y auditada.

Validación automática

Con JDK 21: ./mvnw clean verify (Windows: .\mvnw.cmd clean verify). ContractValidationTest comprueba el schema oficial OpenAPI 3.1, parseo Swagger, resolución local de referencias, meta-schema 2020-12, fixtures positivos/negativos, ejemplos embebidos y cabeceras/rutas obligatorias. Los validadores tienen scope test; no agregan dependencias Jackson 2 al runtime.

Swagger Parser 2.1.35 se usa sin expansión recursiva (resolve=false): expandir el AST produjo un error de profundidad. Las referencias se verifican explícitamente y networknt valida los ejemplos con los schemas reales; no se ignoran referencias rotas. Las pruebas normales no contactan server02, PostgreSQL, Keycloak ni proveedores. No sustituyen T05/T06/T07/T16.

Estado de implementación T07

Crear, editar, validar, publicar, activar y retirar flujos tienen controlador REST protegido. Simulación continúa pendiente (T14), conciliación en T12 y rutas de negocio en T08–T15. Configuración, permisos DB y política por recurso: SECURITY.md. SecurityHttpIT verifica JWT RSA mediante JWKS local, HTTP real y PostgreSQL aislado; no valida aún la configuración real de controlms.

Desde T06 networknt y Jackson 2 se usan también en infraestructura de runtime para validar DSL; Swagger Parser permanece solo en test. Esto sustituye la descripción histórica de todos los validadores como dependencias exclusivamente de test.

T08 implementa POST /requests y GET /requests/{id}, con JWT, propiedad/ámbito y ETag. Creación repetida retorna snapshot original; consulta retorna estado actual. Tipo inexistente 404; no asignable/cambio concurrente 409. Ver REQUESTS.md para habilitación y protocolo transaccional.

T09 implementa POST /requests/{id}/events con 202/Location, bloqueo de solicitud, replay antes de revisión y persistencia atómica. Ver EVENTS.md en specs. GET /executions/{id} sigue como contrato objetivo y se implementará en T10; no se debe interpretar el 202 como procesamiento completado.