Plan maestro de desarrollo del LIS

Estado: documento vivo · Versión: 1 · Fecha: 2026-09-24

Este plan traduce la documentación funcional del LIS en una secuencia de construcción verificable. No repite el dominio: lo ordena. Se apoya en MARCO.md como método de trabajo, en el marco conceptual como lenguaje ubicuo, en procesos y casos de uso como fuente de requisitos y en el modelo de datos con su DDL como esquema de partida.

1. Cómo se usa este documento

Lo que no está aquí: el detalle de la interfaz de usuario (vive en DESIGN_claude.md y queda fuera del alcance por decisión D-03), los requisitos por capacidad (se escriben por hito) y las decisiones estructurales (van a ADRs numerados).

2. Decisiones fundacionales

Consecuencia de D-04: spring-boot-starter-data-jpa sale del pom.xml. Una regla de dependencias es verificable cuando lo prohibido no está en el classpath.

Estructura de módulos

com.sineltek.lis
├── compartido/          identificadores tipados, errores de dominio, reloj, actor, consecutivos
├── catalogo/            prueba, perfil, analito, requisito de muestra, intervalos, tarifas   (P01)
├── admision/            paciente, orden, prueba solicitada, datos clínicos, consentimiento   (P02)
├── muestras/            muestra, custodia, no conformidad, alícuota, lista de trabajo    (P04, P05)
├── analitica/           ejecución, resultado, versión de resultado                            (P07)
├── validacion/          referencia, criticidad, reglas, validación, notificación crítica (P08, P09)
├── informes/            informe, detalle, entrega, corrección                                 (P10)
├── calidad/             control interno y externo, bloqueos, mantenimiento, calibración       (P06)
├── finanzas/            cobertura, factura, pago, cartera                                     (P03)
├── microbiologia/       cultivo, aislamiento, antibiograma                                    (P12)
├── derivacion/          laboratorio de referencia, envío, retorno                             (P13)
├── inventario/          reactivo, lote, movimiento, consumo                                   (P14)
└── seguridad/           cuentas, roles, auditoría, restricción de resultados sensibles        (P15)

Cada módulo se organiza en dominio, aplicacion, infraestructura y api.

Regla de dependencias: api → aplicacion → dominio. dominio no conoce Spring, ni jOOQ, ni HTTP, ni PostgreSQL. Las clases generadas por jOOQ solo existen en infraestructura.

Regla entre módulos: la escritura nunca cruza el límite de un módulo; se invoca el caso de uso del módulo dueño. La lectura sí puede cruzarlo a través de las vistas del esquema (v_lista_trabajo, v_resultados_para_informe, v_ordenes_completas), que pertenecen al módulo que las consume.

3. Mapa de hitos

flowchart LR
    M0[M0 · Cimientos] --> M1[M1 · Camino clínico nominal]
    M1 --> M2[M2 · Configuración clínica]
    M2 --> M3[M3 · Calidad y reglas]
    M1 --> M4[M4 · Cobertura y cobro]
    M1 --> M5[M5 · Microbiología y derivación]
    M3 --> M6[M6 · Inventario y consumo]
    M3 --> M7[M7 · Interfaces y POCT]
    M1 --> M8[M8 · Confidencialidad y auditoría]

    classDef hecho fill:#D3F9D8,stroke:#2B8A3E,stroke-width:2px,color:#1B4332
    classDef curso fill:#D0EBFF,stroke:#1971C2,stroke-width:2px,color:#0B2E4F
    classDef futuro fill:#F1F3F5,stroke:#868E96,stroke-width:1px,color:#343A40
    class M0,M1 curso
    class M2,M3,M4,M5,M6,M7,M8 futuro

El calendario depende de la dedicación. Con la regla del marco —un slice cabe en 1 a 3 días— M0 son dos días y M1 está entre seis y ocho semanas a tiempo parcial.

4. M0 — Cimientos

Estado actual del repositorio: Spring Boot 4.1 sobre Java 25, dependencias de jOOQ, Thymeleaf, Security con WebAuthn y OpenTelemetry, docker-compose con PostgreSQL 18 y Grafana LGTM, un TestController y una SecurityConfig mínima. No hay migraciones, ni generación de código, ni tests de integración, ni puertas de calidad.

Verificaciones que T0.1 y T0.4 deben resolver antes de avanzar: que Flyway 12.4 y jOOQ 3.21 —las versiones que gestiona Boot 4.1— traten correctamente uuidv7(), btree_gist, las restricciones de exclusión, la tabla particionada evento_auditoria y el esquema lis. Son incompatibilidades plausibles y baratas de descubrir el primer día, caras en la semana ocho.

Regla derivada de T0.4: ninguna migración se da por terminada hasta que el código jOOQ regenerado que la acompaña está en el mismo commit. Un esquema y un código generado desincronizados rompen el build de cualquiera que clone el repositorio.

ADRs de M0, escritos en docs/adr/: ADR-0001 monolito modular por capacidad · ADR-0002 generación jOOQ en perfil manual con fuentes versionadas · ADR-0003 el DDL como migración base · ADR-0004 solo jOOQ, sin JPA.

5. M1 — Camino clínico nominal

Objetivo: que una orden real recorra el ciclo completo con la evidencia que exige el dominio. Lo que M1 deja deliberadamente fuera: gestión del catálogo, cobertura y facturación, control de calidad, reglas reflejas y de autovalidación, microbiología, derivación, inventario, interfaces de equipo y POCT.

Precondición de datos (D-06): el catálogo clínico se carga con los datos de referencia y M1 solo lo lee. La primera pantalla de administración de catálogo es M2.

Slices

Orden de construcción dentro de cada slice

Tipos de dominio → puertos → caso de uso con tests → adaptador jOOQ → API → observabilidad. Un slice deja el sistema compilando y en verde, y cabe en un commit.

Escenarios de aceptación del hito

De los quince escenarios mínimos del documento de procesos, M1 debe superar el 1, el 2, el 8, el 10 y el 14 completos, y el 6 salvo su parte de alertas operativas. Los restantes pertenecen a hitos posteriores y no se dan por cubiertos antes.

6. Trazabilidad

La documentación existente ya provee la cadena de identificadores; el plan no inventa una nueva taxonomía.

RN-xx (marco conceptual §16)  →  PO-xx / CU-xx (procesos y casos de uso)  →  S1.xx (slice)  →  test

Cada test de aceptación cita en su nombre el identificador que verifica. Con eso, la pregunta ¿qué regla de negocio no tiene test? se responde con una búsqueda, no con una opinión. Al cerrar cada hito se ejecuta esa búsqueda y su resultado se anota en el PLAN.md del hito.

Las reglas que el hito en curso no cubre se declaran explícitamente como no cubiertas. Una regla sin test y sin declaración es un defecto de proceso.

7. Qué debe garantizar la aplicación

El DDL resuelve inmutabilidad de versiones y libros, tipo de valor y unidad, prohibición de autovalidar un crítico, matriz de transiciones, coherencia de orden y paciente, unicidad de código de barras, bloqueo de lotes vencidos y consecutivos. Todo lo demás es responsabilidad del código, y este plan lo asigna:

8. Puertas de calidad

Desde M0, el build falla si alguna no pasa:

build:        sin warnings nuevos sin justificación
formato:      formateador en modo verificación
tests:        unitarios + integración con Testcontainers sobre PostgreSQL 18
cobertura:    dominio y aplicación ≥ 90 %
arch-test:    ArchUnit — dominio sin Spring, sin jOOQ, sin HTTP; sin escritura entre módulos
migraciones:  esquema reconstruible desde cero; ninguna migración aplicada se edita
codegen:      el código jOOQ generado corresponde a las migraciones vigentes
secretos:     escaneo sobre el diff
dependencias: CVEs y licencias

9. Definición de terminado por slice

[ ] Cada criterio del slice verificado por un test que cita su identificador (RN, CU o PO).
[ ] Vi los tests fallar antes de pasar, por la razón correcta.
[ ] Casos de error, borde y concurrencia cubiertos.
[ ] `make verify` en verde, incluidas arch-test y migraciones desde cero.
[ ] Migración nueva si el esquema cambió; ninguna migración previa editada.
[ ] Trazas y métricas en los puntos de decisión. Sin PII, sin identificadores de paciente en logs.
[ ] Revisión adversarial en sesión limpia, con hallazgos concretos.
[ ] ADR escrito si hubo decisión estructural.
[ ] La documentación que describe esta configuración se actualizó en el mismo commit.
[ ] Un slice, un commit. Revisé el diff completo.

10. Ritmo de trabajo

Por slice, con los roles y prompts de MARCO.md parte VII, cada uno en sesión nueva:

1. Especificación — criterios de aceptación en Gherkin citando la regla de negocio que operacionalizan. Toda ambigüedad se marca como ASSUMPTION, OPEN QUESTION o DECISION REQUIRED; no se resuelve en silencio.
2. Rojo — tests derivados de esos criterios. Se ejecutan y se ven fallar.
3. Verde — implementación mínima.
4. Refactor — sin cambiar comportamiento.
5. Revisión adversarial — sesión limpia, rol de revisor escéptico, con foco en concurrencia, fallos a mitad de operación, autorización por recurso y consultas sin índice.
6. Merge — un commit, marcado en el PLAN.md del hito.

Por hito, antes del primer slice: requisitos de la capacidad (docs/02-requirements/), diseño de dominio y datos si hace falta, y el PLAN.md de la rama.

11. Riesgos

12. Bitácora de revisiones del plan