FactuGES_ERP/docs/validacion-docker-y-migraciones-bd.md

Validación de Docker y migraciones de BD

Fecha: 17 de octubre de 2026.

Resultado funcional

• MariaDB de desarrollo preparada en 127.0.0.1:3308, con volumen persistente. El puerto por defecto 3307 estaba ocupado por otro proyecto y no se modificó.
• Configuración local nueva en infrastructure/database/.env, con credenciales generadas, permisos 0600 y exclusión de Git. No se reescribieron los .env existentes del servidor, worker, frontend o tests.
• Las 30 tablas del baseline y su historial están aplicados y verificados.
• El backend arrancó con el usuario de aplicación y respondió 200 en readiness. Se detuvo el proceso temporal de validación; la base local permanece disponible.
• Se verificó persistencia tras down/up con una fila de prueba, eliminada después.
• Se comprobó que el usuario de aplicación no puede ejecutar DDL ni modificar el historial de migraciones.
• La cancelación durante el aprovisionamiento eliminó el proyecto temporal.
• Las instancias temporales de migraciones, HTTP, E2E y generación del baseline se limpiaron. No se ejecutó SQL sobre producción ni sobre bases anteriores.

Comprobaciones correctas

Comando o comprobación	Resultado
pnpm typecheck:db	Correcto: motor, catálogo, contrato, snapshot y tests de historial
pnpm test:db	10 pruebas correctas, incluida CLI compilada, DDL parcial, recuperación y permisos
pnpm --filter @erp/factuges-server build	Correcto; incluye database-cli.js y catálogo
pnpm --filter @erp/factuges-worker build	Correcto
pnpm db:dev:up	Correcto en el puerto local 3308
pnpm db:migrate	Correcto; baseline aplicado y permisos locales configurados
pnpm db:verify	Correcto, sin diferencias ni migraciones pendientes
pnpm db:dev:down y pnpm db:dev:up	Correcto; datos de prueba persistidos
PORT=43002 pnpm --filter @erp/factuges-server dev	Backend listo, readiness 200; proceso detenido después
node --env-file=apps/server/.env.e2e --import tsx tests/e2e/support/smoke-e2e-bootstrap.ts	Correcto: esquema, cuenta, compañía, membership, rol y onboarding E2E
bash -n infrastructure/database/initialize-development.sh scripts/ci/check-database.sh	Correcto
git diff --check	Correcto

Tests dirigidos ejecutados:

node --import tsx --test \
  modules/core/src/api/infrastructure/database/migration-history.test.ts \
  modules/core/src/api/modules/module-runtime.test.ts \
  apps/server/src/testing/e2e/prepare-e2e-schema.test.ts \
  tests/e2e/support/e2e-contract.test.ts \
  tests/e2e/support/e2e-lifecycle.test.ts

Resultado: los cinco archivos pasan. Biome también se comprobó sobre los archivos TypeScript y JSON modificados con el siguiente comando:

pnpm exec biome check \
  modules/core/src/api/infrastructure/database/migration* \
  modules/core/src/api/infrastructure/database/schema-contract.ts \
  modules/core/src/api/infrastructure/database/index.ts \
  modules/core/src/api/modules/module-runtime* \
  modules/core/tsconfig.database.json \
  apps/server/src/infrastructure/database \
  apps/server/src/testing/database \
  apps/server/src/testing/e2e/prepare-e2e-schema* \
  apps/server/src/testing/http/http-test-runtime.ts \
  apps/server/src/testing/http/run-http-tests.ts \
  apps/server/src/config/database.ts \
  apps/server/src/config/env-schema.ts \
  apps/server/tsup.config.ts \
  apps/worker/src/index.ts \
  scripts/dev/database.ts scripts/dev/run-local-server.ts \
  scripts/testing/run-unit-tests.ts \
  package.json apps/server/package.json modules/core/package.json \
  tests/e2e/support/e2e-database-environment.ts \
  tests/e2e/support/run-e2e.ts

Comprobaciones con fallos preexistentes o limitaciones

Comando	Resultado observado
pnpm typecheck	Falla por errores de sintaxis en el mapper de supplier-invoices, sin cambios en ese archivo
pnpm --filter @erp/factuges-server typecheck	Falla por problemas existentes de rootDir, tipos y código de otros módulos; no se afirma compilación global correcta
pnpm lint	84 errores, 132 avisos y 953 informaciones en el repositorio; la comprobación dirigida del cambio pasa
pnpm test:unit	246 archivos correctos y 38 fallidos, de 284 seleccionados
pnpm test:http	37 pruebas correctas y 10 fallidas, de 47
pnpm test:e2e	Esquema y bootstrap preparados; Playwright no pudo continuar porque el puerto 5173 ya estaba ocupado

Para separar regresiones de deuda anterior se reconstruyó HEAD en un directorio temporal a partir de archivos versionados, sin copiar .env locales. Con las dependencias instaladas se reprodujeron exactamente los mismos conjuntos de 38 fallos unitarios y 10 fallos HTTP: no aparecieron fallos nuevos en estos conjuntos. Los tests HTTP fallidos afectan a fixtures/permisos de Companies, Customers y Suppliers.

La prueba manual del worker llegó a la verificación correcta del esquema, pero falló después al construir Identity: su composición neutral sigue accediendo a config.auth.jwt, ausente en WorkerConfig. Es un problema preexistente ajeno al versionado; no se han añadido credenciales ficticias ni se afirma que el worker arranque correctamente. Se detuvo el proceso de prueba. Su comando de desarrollo existente se conserva.

pnpm test:database:ci no se ejecutó como bloque porque repite las comprobaciones anteriores y quedaría detenido por los fallos HTTP conocidos. Cada fase relevante se ejecutó por separado. No se ejecutó un build global de frontend ni se desplegó ningún artefacto.

Pendientes operativos

• Liberar el puerto 5173 y completar la suite E2E de navegador.
• Corregir la deuda previa de TypeScript, Biome y tests antes de declarar verdes las validaciones globales.
• Corregir la composición/configuración neutral de Identity utilizada por el worker.
• Obtener inventario y configuración efectivos de producción; ensayar reconciliación y adopción en una copia con backup verificado. Las bases existentes deben adoptarse antes de arrancar esta versión, que rechaza esquemas sin historial compatible.
• Conectar test:database:ci al proveedor de CI utilizado por el proyecto.