orquestador/demo/providers-mock/README.md

Proveedores de prueba configurables

Servicio Java 21 independiente, sin dependencias Maven ni base de datos. Responde por HTTP y permite cambiar desde Postman cuerpo, código HTTP y demora sin reiniciar. Solo datos sintéticos. No consulta ningún proveedor real.

Levantar en server02

Desde la raíz del repositorio, agregar a .env:

MOCK_ADMIN_TOKEN=elige-un-token-para-administrar-el-mock
MOCK_BIND_ADDRESS=0.0.0.0
MOCK_PORT=8788

El token es exclusivo del mock, no es un JWT de Keycloak. La publicación del puerto en 0.0.0.0 permite acceso desde Postman en tu red de demo.

docker compose -f compose.yaml -f compose.mock.yaml up -d --build providers-mock
docker compose -f compose.yaml -f compose.mock.yaml ps

Esperar estado healthy. Esta POC usa HTTP: no requiere certificados ni cambios en la validación SSL de Postman.

Importar Providers-Mock.postman_collection.json. Configurar mockAdminToken con el mismo valor de .env. La variable mockUrl ya apunta a http://server02:8788. Ejecutar las peticiones individualmente: cada configuración reemplaza a la anterior, no son escenarios en secuencia.

Configurar manualmente

Ejemplo: cliente inexistente.

PUT http://server02:8788/__admin/clientes_consulta
Authorization: Bearer TU_TOKEN_DEL_MOCK
X-Mock-Status: 200
X-Mock-Delay-Ms: 0
Content-Type: application/json

{"found": false}

Después, POST /clientes_consulta devolverá ese JSON. Los valores iniciales son:

Proveedor	Ruta	Respuesta inicial
CLIENTES_CONSULTA	/clientes_consulta	200, found=true, customerId sintético
BURO_CONSULTA	/buro_consulta	200, score=71, consultationId sintético
DOCUMENTO_VALIDA	/documento_valida	200, status=VALID, reasonCodes=[]
DOCUMENTS_METADATA	/documents_metadata	404 hasta configurar los metadatos

Para cada ruta, PUT /__admin/<nombre> configura y GET /__admin/<nombre> consulta. GET administrativo devuelve 200 y el cuerpo configurado; sus cabeceras X-Mock-Status, X-Mock-Delay-Ms y X-Mock-Calls muestran el código del proveedor, la demora y el contador de llamadas. Las consultas administrativas no incrementan el contador ni sufren la demora. Los endpoints de proveedor son POST sin JWT.

• Para fallo técnico: X-Mock-Status=503 y un cuerpo de error sintético.
• Para timeout: X-Mock-Delay-Ms=7000; las rutas de demo tienen timeout de 5000 ms.
• Para restaurar: volver a enviar PUT con status=200 y delay=0.
• Para scoring: editar el número score (71, 70, 61 o 60).
• Para documento inválido: {"status":"INVALID","reasonCodes":["EXPIRED"]}.
• También acepta texto/JSON incorrecto deliberadamente para comprobar el rechazo por contrato del orquestador. No aplica validación de negocio al cuerpo ficticio.

Los PUT devuelven {"saved":true} con HTTP 200, aunque el proveedor se haya configurado con 503. Status admite 200..599 excepto 204/205/304; demora 0..60000 ms; cuerpos de hasta 256 KiB. Omisión de cabeceras restablece status=200 y delay=0.

Conectar el orquestador

El archivo base compose.yaml conserva un solo servicio. La combinación con compose.mock.yaml añade el mock a microsipNet y selecciona catálogo/rutas sin sobrescribir config/. Activa el perfil demo-mock junto al perfil configurado (por defecto postgres96). Ese perfil permite HTTP únicamente hacia el nombre providers-mock y puerto 8788. Sin ese perfil se mantiene el requisito HTTPS normal; local/test conserva su excepción previa para loopback.

Antes de habilitar la demo, configurar en .env REQUEST_API_ENABLED=true, WORKER_ENABLED=true y, para administrar flujos, FLOW_ADMIN_ENABLED=true y ADMIN_BUSINESS_SCOPES. Se requieren el usuario DB de runtime restringido y las credenciales separadas de migración descritos en SECURITY.md. Los JWT siguen procediendo de tu Keycloak. Este servicio no genera tokens JWT ni crea tipos, flujos, solicitudes o documentos automáticamente.

Aplicar en el entorno de demo:

docker compose -f compose.yaml -f compose.mock.yaml up -d --build

El orquestador espera a que el mock esté healthy. No se cambian JAVA_TOOL_OPTIONS ni truststores. Si ya habías levantado la versión HTTPS, reconstruir y recrear ambos servicios con el comando anterior y reimportar la colección Postman. Los antiguos volúmenes de certificados quedan sin uso; mock-data conserva las respuestas. No se borran volúmenes automáticamente.

Para COMPRA: configurar cliente encontrado, crear/activar el flujo de compra, crear solicitud, enviar ASIGNAR_CLIENTE, consultar ejecución hasta SUCCEEDED, refrescar revisión y enviar CONFIRMAR_COMPRA. Para probar cliente no encontrado, usar otra solicitud o la que sigue CREADA, con una clave de evento nueva. Repetir la misma clave reproduce la aceptación anterior, no fuerza otra consulta.

Metadatos documentales y límites

La colección incluye un PUT de metadatos: completar documentId, requestId, businessScope y documentType con los de la solicitud. Los campos de propiedad, MIME, tamaño, checksum y scanStatus=CLEAN son respuestas sintéticas, no un análisis real de archivos. No hay carga ni almacenamiento de documentos personales.

La respuesta es global por endpoint: no se selecciona por cliente, documento, perfil ni clave idempotente. Todos los perfiles DOCUMENTO_VALIDA comparten la respuesta. Para probar varios documentos, configurar el correspondiente antes de cada evento y esperar a que termine antes de cambiarlo. Una llamada en curso conserva la respuesta que leyó al comenzar; las siguientes usan la configuración nueva. Esto incluye reintentos automáticos del worker.

Las respuestas sobreviven a reinicios en el volumen mock-data; los contadores se reinician. El token administrativo se conserva, pero esta POC usa HTTP sin cifrado dentro de la red de pruebas. No se registran cuerpos ni tokens. No se simulan efectos externos de escritura ni deduplicación de un proveedor: las integraciones de esta demo son READ_ONLY.

Validación local sin Docker

Con Python 3 y JAVA_HOME apuntando a JDK 21:

python demo/providers-mock/test_mock.py

Compila el servidor y prueba HTTP real, autorización administrativa, cliente encontrado/no encontrado, status/demora, persistencia tras reinicio, scoring, documentos y respuestas malformadas. No usa PostgreSQL ni proveedores externos. No equivale a ejecutar el Compose ni cerrar T16.