orquestador/contracts/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.