73 lines
9.4 KiB
Markdown
73 lines
9.4 KiB
Markdown
# Decisiones técnicas
|
||
|
||
## ADR-001 — Base reproducible (2026-10-26)
|
||
|
||
Estado: verificada para T01 con compilación JDK 21 y smoke de salud contra server02; ver ADR-004 y evidencia E09 en PROGRESS. Pruebas de persistencia e integración completas corresponden a tareas posteriores.
|
||
|
||
| Componente | Selección | Motivo |
|
||
|---|---|---|
|
||
| Java | 21, `release=21`, Enforcer `[21,22)` | Versión requerida por la especificación |
|
||
| Spring Boot / BOM | 4.1.2 / spring-boot-dependencies 4.1.2 | Release estable verificada en documentación oficial y Maven Central; compatible con Java 21 |
|
||
| Maven | 3.9.12 | Wrapper oficial con distribución fija |
|
||
| Maven Wrapper | 3.3.4, only-script | Scripts oficiales, sin JAR de wrapper en el repositorio |
|
||
| PostgreSQL | 17.11-bookworm | Major 17 requerido y parche fijo; imagen pendiente de pull/verificación con Docker |
|
||
| JUnit | 5.13.4 | Mantener JUnit 5 requerido; sobrescribir junit-jupiter.version del BOM |
|
||
| Surefire / Failsafe | 3.5.4 | Separar pruebas unitarias de integración; verify ejecuta ambas |
|
||
| Maven Enforcer | 3.6.2 | Fallar explícitamente si el JDK no es 21 |
|
||
|
||
MVC, Security, Hibernate, Flyway, JDBC PostgreSQL y demás dependencias se resuelven desde el BOM fijado. No declarar versiones dinámicas ni snapshots de dependencias. `0.1.0-SNAPSHOT` es la versión de desarrollo de este proyecto, no una dependencia externa.
|
||
|
||
Spring Boot 4 usa starters modulares: `webmvc`, `security-oauth2-resource-server` y `flyway`. No se añade `springdoc` hasta validar compatibilidad en T02. OpenAPI será contractual. Testcontainers y servidor de mocks se fijarán y verificarán al incorporarse en T03/T11. No adoptar automáticamente dependencias de test de Boot que cambien JUnit 5; comprobar integración con Spring Test al introducirla.
|
||
|
||
Fuentes consultadas el 2026-10-26:
|
||
|
||
- [Requisitos oficiales de Spring Boot](https://docs.spring.io/spring-boot/system-requirements.html).
|
||
- [Dependencias gestionadas](https://docs.spring.io/spring-boot/appendix/dependency-versions/coordinates.html).
|
||
- [POM publicado de Boot 4.1.2](https://repo.maven.apache.org/maven2/org/springframework/boot/spring-boot-starter-parent/4.1.2/spring-boot-starter-parent-4.1.2.pom).
|
||
- [PostgreSQL: descargas y release 17.11](https://www.postgresql.org/download/).
|
||
|
||
Alternativa: Boot 3.5, compatible con Java 21, pero se prefiere la línea estable actual para un proyecto nuevo. No cambia la semántica del motor. La compatibilidad de bibliotecas futuras se verificará antes de incorporarlas.
|
||
|
||
## ADR-002 — Alcance de esta entrega
|
||
|
||
El pedido actual comprende arquetipo, plan y seguimiento. Se prepara T01 y se documenta T02–T17; no se implementan anticipadamente el dominio, contratos incompletos ni endpoints con respuestas simuladas. Las tareas se cierran con sus verificaciones, no por existencia de carpetas.
|
||
|
||
La configuración local conserva JWT y exige parámetros externos. No se incluye issuer falso ni contraseña predeterminada. El Compose actual es exclusivamente de desarrollo; no es un despliegue productivo.
|
||
|
||
## ADR-003 — Docker del servicio con PostgreSQL externo (2026-10-26)
|
||
|
||
Por instrucción expresa del usuario se adelanta el empaquetado del arquetipo: Compose contiene sólo orquestador y sustituye el anterior servicio PostgreSQL. No administra base ni volúmenes externos. T17 no se considera terminado: la demo integral sigue pendiente de sus dependencias.
|
||
|
||
Dockerfile multietapa con Temurin 21.0.12.1_1 (JDK para construir, JRE para ejecutar), tags verificados en el [catálogo oficial](https://github.com/docker-library/official-images/blob/master/library/eclipse-temurin). Runtime no root y healthcheck de readiness. Maven Wrapper construye con package y ejecuta pruebas unitarias; verify con integración permanece en CI. El contexto permite sólo fuentes, POM y Wrapper; excluye .env, target y archivos del IDE.
|
||
|
||
Compose exige DB_URL/usuario/contraseña y parámetros JWT, conserva el puerto interno 8080 y publica localhost:8080 por defecto. Se incluye host-gateway para PostgreSQL en el anfitrión. La construcción y conexión real están pendientes de un entorno Docker y valores externos. Referencias: [build multietapa](https://docs.docker.com/build/building/multi-stage/) e [interpolación de Compose](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/).
|
||
|
||
## ADR-004 — Cierre verificable de T01 con despliegue en la red local (2026-10-26)
|
||
|
||
El servicio ya está desplegado por el usuario en server02:8787 con PostgreSQL externo. Se interpreta el health local de T01 como comprobación del entorno de desarrollo en esa red, sin requerir duplicar el despliegue en el equipo del agente. La compilación se realiza localmente con Temurin JDK 21 oficial, descargado a .tools y validado por SHA256 del proveedor; no se modifica el Java del sistema.
|
||
|
||
El perfil explícito deployment-smoke ejecuta cinco pruebas Failsafe de sólo lectura contra una URL obligatoria: health, readiness, liveness, rechazo sin token y rechazo con token malformado. No se omiten errores de conectividad ni pruebas fallidas. Se preservan los patrones normales de integración *IT, IT* y *ITCase al activar el perfil.
|
||
|
||
El build de T01 y la salud del despliegue se verifican por separado: no se afirma que el JAR recién generado haya sido desplegado ni se acredita el runtime remoto por una respuesta health. No se redepliega el servidor ni se accede directamente a sus credenciales o base. Testcontainers, migraciones, JWT válido/roles y A01–A20 siguen pendientes; este smoke no los sustituye. CI no depende de server02: el perfil requiere activación explícita fuera del build normal.
|
||
|
||
## ADR-005 — Contratos T02: REST y DSL v1 (2026-10-26)
|
||
|
||
Estado: implementado como contrato y pruebas, no como endpoints. OpenAPI 3.1.0 y JSON Schema 2020-12 en archivos separados con referencias relativas locales. No se incorpora springdoc: la documentación contractual es independiente de Boot y no habilita rutas administrativas antes de T07.
|
||
|
||
Se concreta lo no detallado por la especificación sin cambiar idempotencia, aislamiento de versiones ni autorización:
|
||
|
||
- Rutas fijas usan to/outcome; rutas calculadas usan decision/destinations, con el output de decisión como resultado de negocio. EXISTS usa value.path; NOT usa arg; AND/OR usan args. Mappings admiten exactamente path o literal.
|
||
- dataSchema e initialDataSchema permiten describir datos finales/entrada inicial. Borradores y ejemplo mínimo original pueden omitirlos estructuralmente; publicación T06 exige dataSchema de objeto. InitialDataSchema ausente utiliza dataSchema. No se confunde validez estructural con publicación válida.
|
||
- Schemas embebidos limitan el vocabulario a validación declarativa y no admiten referencias externas. Se conservan boolean schemas y combinadores. Se rechazan propiedades desconocidas de DSL/DTOs; datos configurables requieren segunda validación contra su schema de evento/flujo. Rechazo de JSON con claves duplicadas precede validación.
|
||
- JSON Pointer de updates es relativo a request.data. Restricciones de identidad/ACL permanecen fuera de ese espacio. Publicación verifica destinos solapados y schemas resultantes; runtime verifica tipos/ambigüedad. Estas comprobaciones no se simulan en T02.
|
||
- Publicar y retirar exigen If-Match adicional al exigido por eventos/edición/activación. Esto concreta su concurrencia y evita operar sobre una revisión diferente a la revisada. Alta de request_type se provisionará por migración/configuración en T03/T06; activar uno inexistente devuelve 404.
|
||
- Conciliación acepta RESUME con evidencia y resultados verificados por acción, o CLOSE_WITHOUT_TRANSITION con ausencia/compensación comprobada. Prohíbe escoger destino. RESUME reencola PENDING; cierre marca FAILED sin cambiar negocio. Idempotencia durable, autorización por scope y evidencia verificada son requisitos para T12.
|
||
- Replays de creación devuelven 201 con la misma identidad; eventos devuelven 202 con executionId estable y status actual. Los errores tienen code/correlationId; fechas UTC Z, opcionales omitidos, cursor opaco máximo 100.
|
||
- Se fijan techos estructurales auxiliares: 500 eventos/decisiones/tareas, 100 roles por transición, 200 updates, reintentos máximo 3 y tamaño documental máximo 100 MiB en DSL. Los límites operativos podrán ser menores; los 1 MiB/256 KiB y límites AST de la especificación requieren control adicional antes/durante deserialización en T06/T09.
|
||
|
||
Herramientas fijadas, únicamente scope test: networknt json-schema-validator 1.5.9 (2020-12 con format assertions) y swagger-parser-v3 2.1.35 (OpenAPI 3.1). Jackson 2 de estas herramientas convive sólo en tests con Jackson 3 del runtime Boot 4.1.2. Se comprobó compatibilidad mediante clean verify con Java 21.
|
||
|
||
Se conserva una copia del schema oficial OpenAPI 3.1 (2022-10-07), SHA256 DA01BA28852CAC0DE53893797CB8D1942BC3B05084F526DCC216717DEC314ED0, para validar sin red. Swagger Parser con resolve=true intentó expandir indefinidamente las referencias recursivas del AST: se usa resolve=false y comprobación explícita de todos los $ref locales. Networknt valida los schemas y ejemplos reales. No se relajan límites ni se ignoran referencias rotas para resolver esa incompatibilidad.
|
||
|
||
Referencias: [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0), [schema oficial](https://spec.openapis.org/oas/3.1/schema/2022-10-07), [networknt](https://github.com/networknt/json-schema-validator), [Swagger Parser y soporte 3.1](https://github.com/swagger-api/swagger-parser). Detalles de uso en contracts/README.md y schemas/README.md.
|