TodoFactu

Nueva implementación de TodoFactu guiada por la especificación de .aicontext. El prototipo de .aicontext/prototype/TodofactuV2 está congelado y se usa únicamente como referencia funcional y corpus de contraste; no es la base técnica de este monorepo.

Estado

La Fase 0 conserva gates externos abiertos y la Fase 1 está implementada de forma parcial; la Fase 2 ya tiene varios cortes backend. Ya existen:

• monorepo Gradle Kotlin DSL con Java 21, Kotlin Multiplatform, Compose, Android, escritorio y web Kotlin/JS con DOM semántico;
• server-api Spring Boot con frontera OAuth 2.0/OIDC estricta, tokens de acceso RFC 9068, scopes por operación, errores RFC 9457 y correlación;
• migraciones PostgreSQL/Flyway V001–V027 con tenancy, sesiones, permisos, series y clientes —incluidos perfiles estructurados, búsqueda exacta, delegación e importación atómica acotada—, licencia/readiness e historial acotado, borradores versionados, RLS forzada, auditoría append-only y feed minimizado; V001–V026 tienen evidencia histórica sobre PostgreSQL 17.6-alpine con roles efectivos separados y V027 permanece pendiente de ese gate;
• GET/PUT/POST /v1/session/context, operaciones de sesiones, administración de acceso por obligado, consultas de licencia/readiness y auditoría minimizada condicionados a todofactu.database.enabled=true, con dos pools Hikari separados; la integración está deshabilitada por defecto;
• motor de huella VERI*FACTU contrastado con vectores oficiales adquiridos y verificados por checksum;
• contrato OpenAPI 3.1, trazabilidad automatizada, fixture multi-tenant sintético y CI de ocho jobs declarada para Linux, Windows y macOS;
• shell web con manifiesto y service worker preparados como activos PWA, que excluyen API y Actuator de la caché; web y Compose incluyen el resolutor sin autoselección, y core-network aporta un adaptador HTTP autenticado JVM/JS inyectable con retry idempotente explícito. El arranque sigue sintético hasta integrar BFF/IdP y contexto seguro, y los gates nuevos están pendientes por una limitación de red del sandbox.

El contrato PostgreSQL V001–V026 con roles reales está superado históricamente mediante Testcontainers: 41 tests sin fallos, errores u omisiones. Incluye los adaptadores JDBC/Hikari reales, bootstrap, guardas fail-closed, GUC transaccionales, RLS multi-cuenta, sesiones, concurrencia CAS, auditoría y licencia/readiness, series, clientes, borradores y auditoría minimizada. La evidencia unitaria anterior de server-api registró 27 suites/128 tests sin fallos, errores ni omisiones; no incluye LIC-002. El último baselineCheck (2026-08-09) pasó con 43 suites/182 casos; el gate KMP común pasó en JVM y JavaScript con 14 suites/49 casos por plataforma, y el flujo web de clientes pasó en Chrome Headless.

La regresión Gradle consolidada pasó el 2026-07-31 en Windows/JDK 21 en 2 min 2 s: 157 tareas ejecutadas y 53 suites/195 casos sin fallos, errores ni omisiones. Incluye JVM/Spring, PostgreSQL, Kotlin/JS Node/browser, Compose Desktop y Android; no equivale a ejecución en GitHub, macOS, Linux ni lectores de pantalla reales.

Esto no equivale a login ni acredita un IdP, MFA, operación completa de sesiones, administración/enforcement de licencia, readiness completo, bootstrap productivo, rate limiting de edge/IdP, worker de limpieza, autovacuum, métricas completas, política APM completa o restore. Tampoco se consideran cerrados CI ejecutada en GitHub, iOS/macOS/Linux, lectores de pantalla, PWA instalada/offline en navegador real, homelab ni almacenamiento de objetos. El estado y las evidencias exactas se mantienen en STATUS.md y HANDOFF.md.

Verificación local

Requisitos principales: JDK 21, Node.js 22.12 o posterior y, para Android, SDK API 36. Este equipo usa Linux, por lo que los ejemplos siguientes se ejecutan con Bash y ./gradlew.

npm ci --ignore-scripts --no-audit --no-fund
npm run check
npm run verify:regulatory

export JAVA_HOME='/home/carlos/.local/share/jdks/temurin-21'
export PATH="${JAVA_HOME}/bin:${PATH}"
export ANDROID_SDK_ROOT='/home/carlos/Android/Sdk'
export CHROME_BIN='/home/carlos/.cache/ms-playwright/chromium-1223/chrome-linux64/chrome'
export NODE_ENV='development'
./gradlew baselineCompile baselineCheck phase0UiCompile phase0UiCheck phase0AndroidCompile phase0AndroidCheck :app:core-model:jsNodeTest :app:core-domain:jsNodeTest :app:webApp:jsBrowserDistribution --no-daemon --no-parallel --max-workers=1 '-Pkotlin.compiler.execution.strategy=in-process'

export TODOFACTU_REQUIRE_POSTGRES_TESTS='true'
./gradlew :backend:server-api:postgresIntegrationTest --rerun-tasks --no-daemon --no-parallel --max-workers=1 '-Pkotlin.compiler.execution.strategy=in-process'

Las rutas corresponden a Temurin 21, Android SDK API 36 y Chrome for Testing instalados localmente en este equipo. NODE_ENV=development evita que el valor global production omita las dependencias de prueba de Kotlin/JS.

npm run check incluye verify:feature-flags, con un contrato positivo y tres negativas que exigen que borradores siga apagado por defecto y que sus handlers dependan a la vez de base de datos y flag explícitamente activos. También incluye verify:migration-authority, que rechaza archivos SQL con nombres no canónicos, huecos o versiones duplicadas, y exige que cada migración Flyway desde V020 hasta la última declare el par fijo todofactu_migrator -> SET ROLE todofactu_owner. Sus nueve tests cubren el catálogo, la compatibilidad histórica y las negativas de autoridad, incluida deriva en una migración protegida no final. Son comprobaciones estáticas tempranas y no reemplazan los gates reales de Gradle/Flyway/PostgreSQL.

El comando PostgreSQL requiere Docker y fuerza un fallo si Testcontainers no puede iniciar PostgreSQL. La ejecución local focal histórica usó postgres:17.6-alpine, aplicó y validó Flyway V001–V026 y terminó en 35s con 41 tests y cero fallos, errores u omisiones. V027 no tiene todavía evidencia PostgreSQL: el intento estricto del 2026-08-09 descubrió 40 tests pero no inició ninguno porque el sandbox denegó el socket Unix de Docker. El job CI postgres-contract aplica la misma condición estricta en Ubuntu, aunque el workflow todavía no se ha ejecutado en GitHub.

La integración de base de datos está apagada por defecto. Al habilitarla se exigen credenciales distintas para identidad y runtime, roles NOINHERIT sin membresías y, para cualquier host remoto, sslmode=verify-full; el loopback inseguro necesita un opt-in explícito. La aplicación no registra el secreto opaco, pero el guard de arranque también exige que PostgreSQL no registre parámetros enlazados. La configuración de PostgreSQL y cualquier agente APM deben mantener esa protección: el bootstrap SQL es reproducible y se prueba localmente, pero todavía no se ha ensayado con custodia, TLS, restore y observabilidad de producción.

El APK de depuración queda en app/androidApp/build/outputs/apk/debug/androidApp-debug.apk y la distribución web en app/webApp/build/dist/js/productionExecutable.

Para servir la web ya construida:

npm run preview:web

El servidor local escucha en http://127.0.0.1:4173 y aplica cabeceras defensivas apropiadas para el smoke test. No es un despliegue de producción.

Mapa del repositorio

• app/: modelo/dominio/transporte HTTP compartidos y shells Android, escritorio y web.
• backend/: API Spring Boot y módulos fiscales.
• contracts/: OpenAPI, fixtures sintéticos y artefactos regulatorios con manifiestos.
• docs/: ADR, seguridad, base de datos, cumplimiento y evidencias por fase.
• scripts/: comprobaciones reproducibles de contrato, trazabilidad, fixtures, PWA y fuentes regulatorias.
• .aicontext/: especificación autoritativa, plan, registros de ejecución y prototipo congelado.

No se deben copiar secretos, certificados, datos reales ni ficheros .env al repositorio. Tampoco se debe modificar el prototipo congelado.