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:

```bash
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:

```bash
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.