# Migraciones idempotentes por driver con introspección centralizada

- **Código:** BUG-002
- **Tipo:** bugfix
- **Estado:** en curso

## Objetivo

Permitir que `init:principal` e `init:sucursal` se ejecuten repetidamente sobre una base MySQL ya inicializada sin errores por columnas, índices o claves foráneas duplicadas. Centralizar las consultas de introspección en el trait `IntrospeccionEsquema` y aplicarlo a las migraciones 066, 067, 094 y a ambas 095, manteniendo idéntico el esquema resultante en MySQL.

## Problema

Los comandos `init:*` aplican `up()` directamente en cada ejecución; no consultan la tabla `migrations`. Por eso, una segunda ejecución vuelve a intentar cambios que ya existen:

- `066_CreateSedocumentos` crea la tabla con `createTable(..., true)`, pero luego ejecuta sin condición `ALTER TABLE ... ADD CONSTRAINT se_documentos_ibfk_1` (`app/Database/Migrations/2026-08-26-000066_CreateSedocumentos.php:74`).
- `067_CreateSeserviciocomunitarioestudiante` tiene el mismo patrón con `se_servicio_comunitario_estudiante_ibfk_1` (`app/Database/Migrations/2026-08-26-000067_CreateSeserviciocomunitarioestudiante.php:69`).
- `094_AddGhlCodigoToAasucurs` ejecuta `forge->addColumn()` y `ALTER TABLE ... ADD INDEX` sin comprobar si la columna o el índice ya existen (`app/Database/Migrations/2026-10-18-000094_AddGhlCodigoToAasucurs.php:27` y `:32`).
- `095_AddGhlContactIdToNiInscripciones` repite el mismo patrón sobre `ni_inscripciones` (`app/Database/Migrations/2026-10-20-000095_AddGhlContactIdToNiInscripciones.php:27` y `:32`).
- `095_AddOrbisCodigoToCecarrera` ya es idempotente y concentra su propia introspección en `existeIndice()` (`app/Database/Migrations/2026-10-19-000095_AddOrbisCodigoToCecarrera.php:66-80`); se incluye para reutilizar el trait sin cambiar su comportamiento.

El repositorio ya declara que los comandos `init:*` deben ser idempotentes (`MEMORY.md`, sección 2.4), pero estas migraciones incumplen esa regla.

## Impacto

- **Operación:** `init:sucursal` falla en la segunda ejecución al llegar a 066; `init:principal` falla en la segunda ejecución al llegar a 094. Esto impide reinstalar, reprovisionar o recuperar una sede sobre una base existente.
- **Desarrollo y pruebas:** obliga a recrear la base o a limpiar columnas, índices y FK manualmente para volver a ejecutar los comandos.
- **Usuarios finales:** no hay evidencia de afectación directa en producción; el usuario confirmó que el fallo se observó solo en desarrollo/pruebas. Si se confirma que ya ocurrió en producción, el caso debe tratarse como **hotfix**.
- **Gravedad:** media. Es un defecto operativo, no un cambio de reglas de negocio ni de datos de usuario.
- **Alcance de datos:** el esquema de la primera ejecución no debe cambiar; no se corrige ni se migra ningún dato existente.

## Reproducción

> Ejecutar solo en una base MySQL de desarrollo o pruebas autorizada. No ejecutar sobre producción sin respaldo y autorización.

1. Partir de una base principal ya inicializada con `php spark init:principal`.
2. Ejecutar de nuevo `php spark init:principal`.
3. Resultado actual esperado: falla al aplicar 094 porque `aasucurs.ghl_codigo` ya existe (error de columna duplicada). Si 094 se saltara, 095 fallaría por `ni_inscripciones.ghl_contact_id` o por el índice duplicado. Confirmar el mensaje exacto en la base de pruebas.
4. Partir de una base de sucursal ya inicializada con `php spark init:sucursal <AASUCURSID>`.
5. Ejecutar de nuevo `php spark init:sucursal <AASUCURSID>`.
6. Resultado actual esperado: falla al aplicar 066 porque `se_documentos_ibfk_1` ya existe (restricción duplicada). Si 066 se saltara, 067 fallaría por `se_servicio_comunitario_estudiante_ibfk_1`. 095 Orbis no falla porque ya tiene guardas.
7. En una prueba aislada de 094 o 095 GHL, ejecutar `down()` dos veces: la segunda intenta eliminar una columna ya eliminada y falla porque no hay guarda.

## Comportamiento esperado

- `php spark init:principal` se puede ejecutar dos o más veces seguidas sin errores.
- `php spark init:sucursal <AASUCURSID>` se puede ejecutar dos o más veces seguidas sin errores.
- La segunda ejecución no agrega columnas, índices ni FK adicionales y no elimina nada.
- El esquema resultante es idéntico al actual: mismos nombres de columnas, tipos, orden, índices, FK, engine y charset.
- `down()` de 094 y 095 GHL se puede ejecutar dos veces: solo elimina el índice/columna si existe. 095 Orbis conserva su comportamiento actual. 066 y 067 ya usan `dropTable(..., true)` y no requieren cambio.
- No cambian los seeders, los datos de configuración ni el comportamiento de la aplicación fuera de los comandos de inicialización.

## Causa raíz (hipótesis)

**Confirmada en código; pendiente de reproducir en la base MySQL de pruebas.**

1. `InitPrincipalDb::runPrincipalMigrations()` y `LoadBranchConfig::runBranchMigrations()` hacen `require_once` del archivo y llaman `up()` en cada ejecución (`app/Commands/InitPrincipalDb.php:139-140`, `app/Commands/LoadBranchConfig.php:294-299`). No usan la tabla `migrations` para omitir migraciones ya aplicadas.
2. 066 y 067 crean la tabla de forma segura (`createTable(..., true)`), pero la FK se agrega con SQL directo sin consultar si ya existe.
3. 094 y 095 GHL agregan columna e índice con DDL directo, sin `fieldExists` ni una comprobación equivalente para índices.
4. Los `down()` de 094 y 095 GHL no comprueban la existencia del índice ni de la columna antes de eliminarlos.
5. 095 Orbis ya resolvió el problema con `existeIndice()`, pero esa lógica está duplicada y solo cubre índices; no hay un trait compartido para columnas y FK.

## Archivos afectados

| Acción | Archivo | Motivo |
| --- | --- | --- |
| Agregar | `app/Database/Migrations/Concerns/IntrospeccionEsquema.php` (propuesta) | Trait con `columnaExiste`, `indiceExiste` y `claveForaneaExiste`. Implementación MySQLi para producción y rama SQLite3 solo para pruebas. |
| Modificar | `app/Database/Migrations/2026-08-26-000066_CreateSedocumentos.php` | Usar el trait y agregar la FK solo si no existe, comparando nombre y columnas/referencia. No cambiar el DDL de creación ni el `down()`. |
| Modificar | `app/Database/Migrations/2026-08-26-000067_CreateSeserviciocomunitarioestudiante.php` | Igual que 066 para `se_servicio_comunitario_estudiante_ibfk_1`. No cambiar el DDL de creación ni el `down()`. |
| Modificar | `app/Database/Migrations/2026-10-18-000094_AddGhlCodigoToAasucurs.php` | Guardar `addColumn` con `columnaExiste` y `ADD INDEX` con `indiceExiste`. En `down()`, eliminar índice y columna solo si existen. |
| Modificar | `app/Database/Migrations/2026-10-19-000095_AddOrbisCodigoToCecarrera.php` | Reemplazar el método privado `existeIndice()` por `indiceExiste()` del trait. Cambio de consolidación sin cambio de comportamiento. |
| Modificar | `app/Database/Migrations/2026-10-20-000095_AddGhlContactIdToNiInscripciones.php` | Guardar `addColumn` e índice; proteger `down()` igual que 094. |
| Agregar | `tests/app/Database/Migrations/IntrospeccionEsquemaTest.php` (propuesta) | Prueba del trait contra SQLite en memoria: columna, índice y FK existentes/inexistentes, incluida la detección por mapeo cuando el nombre no está disponible. |
| Modificar | `MEMORY.md` | Registrar el trait y la regla de idempotencia por driver; dejar anotada la colisión de numeración 095 como deuda separada. |

No se modifican `app/Commands/InitPrincipalDb.php` ni `app/Commands/LoadBranchConfig.php`: las migraciones ya están registradas. Tampoco se renumera ninguna 095 en este bugfix; la colisión queda documentada como deuda separada.

## Plan de pasos

1. **Crear el trait `IntrospeccionEsquema`** en `app/Database/Migrations/Concerns/`.
   - `columnaExiste(string $tabla, string $columna): bool`.
   - `indiceExiste(string $tabla, string $indice): bool`.
   - `claveForaneaExiste(string $tabla, string $constraint, array $columnas, string $tablaReferenciada, array $columnasReferenciadas = []): bool`.
   - Detectar `$this->db->DBDriver`: `MySQLi` para producción y `SQLite3` solo para pruebas. Para un driver distinto, lanzar una excepción explícita en lugar de devolver un falso negativo.
   - MySQLi: `SHOW INDEX FROM ... WHERE Key_name = ?` para índices; `information_schema.KEY_COLUMN_USAGE` filtrado por `TABLE_SCHEMA = DATABASE()` para FK; `fieldExists` para columnas.
   - SQLite3: `PRAGMA index_list(...)`, `PRAGMA foreign_key_list(...)` y `PRAGMA table_info(...)`. SQLite no expone el nombre de la FK en `PRAGMA foreign_key_list`; en ese driver la comparación será por columnas/tabla referenciada.
   - Para FK, comparar el nombre y el mapeo de columnas. Si existe una FK con el mismo nombre pero mapeo distinto, lanzar una excepción clara para no dejar un esquema inconsistente en silencio. Si el mapeo coincide pero el nombre es distinto, devolver `true` para no duplicar.
2. **Aplicar el trait a 066 y 067.** Envolver el `ALTER TABLE ... ADD CONSTRAINT` en `if (! $this->claveForaneaExiste(...))`. Mantener el nombre exacto de la constraint y las mismas columnas/referencias. No tocar la creación de tablas, los defaults ni el `down()`.
3. **Aplicar el trait a 094 y 095 GHL.** Guardar la columna con `columnaExiste` y el índice con `indiceExiste`. En `down()`, eliminar el índice solo si existe y luego la columna solo si existe. Mantener el mismo orden y los mismos nombres.
4. **Aplicar el trait a 095 Orbis.** Eliminar el método privado `existeIndice()` y usar `indiceExiste('cecarrera', self::INDICE)`. Conservar el `down()` y el resto del DDL sin cambios.
5. **Agregar la prueba del trait** en `tests/app/Database/Migrations/IntrospeccionEsquemaTest.php`, usando `Database::connect('tests', false)` y SQLite en memoria. La prueba debe crear una tabla padre, una tabla hija con FK nombrada y un índice, y verificar los métodos a través de una clase anónima que use el trait y exponga wrappers públicos.
6. **Verificar el esquema en MySQL.** Repetir `init:principal` e `init:sucursal` dos veces en la base autorizada y comparar `SHOW CREATE TABLE` antes/después. Confirmar que no hay columnas, índices ni FK duplicados.
7. **Verificar `down()` en una base desechable.** Aplicar las migraciones una vez, ejecutar `down()` dos veces y comprobar que la segunda no lanza error. Para 066/067 basta confirmar que `dropTable(..., true)` sigue igual.
8. **Actualizar `MEMORY.md`** con la existencia del trait, el alcance MySQLi/SQLite de pruebas y la deuda de numeración 095. Ejecutar `graphify update .` al cerrar el cambio de código.

## Plan de verificación

### Prueba manual (flujo normal)

> Usar una base MySQL de desarrollo o pruebas autorizada. No usar producción. Respaldar antes de ejecutar.

1. Capturar el esquema actual de las tablas afectadas:

   ```sql
   SHOW CREATE TABLE se_documentos;
   SHOW CREATE TABLE se_servicio_comunitario_estudiante;
   SHOW CREATE TABLE aasucurs;
   SHOW CREATE TABLE ni_inscripciones;
   SHOW CREATE TABLE cecarrera;
   ```

2. Ejecutar `php spark init:principal` dos veces seguidas.
3. Resultado esperado: ambas ejecuciones terminan sin error; la segunda no agrega columnas, índices ni FK.
4. Ejecutar `php spark init:sucursal <AASUCURSID>` dos veces seguidas contra una sede de pruebas.
5. Resultado esperado: ambas ejecuciones terminan sin error; la segunda no agrega columnas, índices ni FK.
6. Comparar el `SHOW CREATE TABLE` de las cinco tablas con el capturado al inicio. Debe ser idéntico.
7. Verificar las FK:

   ```sql
   SELECT CONSTRAINT_NAME, COLUMN_NAME, REFERENCED_TABLE_NAME, REFERENCED_COLUMN_NAME
   FROM information_schema.KEY_COLUMN_USAGE
   WHERE TABLE_SCHEMA = DATABASE()
     AND TABLE_NAME IN ('se_documentos', 'se_servicio_comunitario_estudiante')
     AND CONSTRAINT_NAME IN ('se_documentos_ibfk_1', 'se_servicio_comunitario_estudiante_ibfk_1');
   ```

   Resultado esperado: una fila por constraint, sin duplicados.
8. Verificar los índices:

   ```sql
   SHOW INDEX FROM aasucurs WHERE Key_name = 'idx_aasucurs_ghl_codigo';
   SHOW INDEX FROM ni_inscripciones WHERE Key_name = 'idx_ni_inscripciones_ghl_contact_id';
   SHOW INDEX FROM cecarrera WHERE Key_name = 'idx_cecarrera_orbis_codigo';
   ```

   Resultado esperado: una fila por índice, sin duplicados.
9. Verificar `down()` en una base desechable: aplicar una vez las migraciones y ejecutar `down()` dos veces. Resultado esperado: la segunda ejecución no lanza error y el esquema queda sin la columna/índice correspondiente.

### Prueba automatizada / código de verificación

Agregar `tests/app/Database/Migrations/IntrospeccionEsquemaTest.php` con estos casos:

- `testColumnaExisteEnSQLite`.
- `testIndiceExisteEnSQLite`.
- `testClaveForaneaExistePorMapeoEnSQLite`.
- `testClaveForaneaNoExiste`.
- `testIndiceInexistenteDevuelveFalse`.
- `testConsultasRepetidasNoLanzanError`.

Comando en Windows/PowerShell:

```powershell
vendor\bin\phpunit.bat tests/app/Database/Migrations/IntrospeccionEsquemaTest.php
```

Alternativa si el proxy de Composer falla:

```powershell
php vendor\phpunit\phpunit\phpunit tests/app/Database/Migrations/IntrospeccionEsquemaTest.php
```

La prueba del trait usa SQLite en memoria porque la suite del proyecto ya está configurada así (`phpunit.xml.dist`). La verificación MySQLi real se hace con el smoke test manual anterior. Si se autoriza una prueba destructiva de `down()`, agregarla como prueba de integración marcada `@group DatabaseLive` y ejecutarla solo contra un esquema desechable; no debe formar parte de la suite por defecto ni usar credenciales versionadas.

## Riesgos y efectos secundarios

- **Permisos de `information_schema`:** la introspección de FK en MySQLi requiere acceso de lectura a `information_schema`. Es el comportamiento habitual, pero debe confirmarse con el usuario de la base.
- **FK con nombre repetido y mapeo distinto:** el trait lanzará una excepción explícita en vez de intentar corregir el esquema. Ese caso requiere intervención manual y no forma parte de la reejecución normal.
- **Índice con el mismo nombre pero otras columnas:** `indiceExiste` compara por nombre; si existe un índice homónimo con otras columnas, la migración lo considerará existente. Es un esquema anómalo; se documenta y no se corrige automáticamente.
- **SQLite no expone el nombre de la FK:** la rama SQLite de pruebas compara solo el mapeo. La comparación por nombre se valida en MySQLi con el smoke test.
- **`init:principal` ejecuta seeders:** la prueba manual debe hacerse en una base de pruebas; no se debe usar producción.
- **`init:sucursal` toca la base de una sede:** usar una sede de pruebas autorizada. No ejecutar sobre sedes con datos reales sin respaldo.
- **`down()` es destructivo:** elimina columnas y tablas. La verificación de `down()` debe hacerse en una base desechable, nunca en la base compartida de pruebas con datos útiles.
- **066/067 con tablas existentes pero FK ausente:** si la tabla existe y la FK falta, la corrección la agregará. Si los datos existentes violan la FK, el `ALTER` fallará; es un esquema parcial que requiere revisión manual.
- **Numeración 095 duplicada:** no se corrige en este bugfix. Queda como deuda separada y puede afectar el orden de ejecución de futuras migraciones.
- **Rama actual:** el repositorio está en `feature/desacoplar-contructor-pagos`; se recomienda crear una rama `fix/migraciones-idempotentes` antes de implementar. No se cambia de rama automáticamente.

## Criterios de finalización

- [x] Existe `IntrospeccionEsquema` con `columnaExiste`, `indiceExiste` y `claveForaneaExiste`, con rama MySQLi y rama SQLite solo para pruebas.
- [x] 066 y 067 agregan la FK solo si no existe, comparando nombre y mapeo.
- [x] 094 y 095 GHL agregan columna e índice solo si no existen.
- [x] `down()` de 094 y 095 GHL se puede ejecutar dos veces sin error; 095 Orbis conserva su comportamiento; 066/067 mantienen `dropTable(..., true)`.
- [ ] `init:principal` se ejecuta dos veces en MySQL de pruebas sin error y sin cambios de esquema. — Pendiente: no hay base MySQL de pruebas autorizada.
- [ ] `init:sucursal` se ejecuta dos veces en una sede de pruebas sin error y sin cambios de esquema. — Pendiente: no hay sede de pruebas autorizada.
- [ ] El `SHOW CREATE TABLE` de las tablas afectadas es idéntico antes y después de la segunda ejecución. — Pendiente: depende del smoke test MySQL.
- [x] La prueba `tests/app/Database/Migrations/IntrospeccionEsquemaTest.php` pasa.
- [x] `MEMORY.md` registra el trait, el alcance de drivers y la deuda de numeración 095.
- [x] No se modificaron seeders, datos de configuración, contratos de la aplicación ni código de producción fuera de las migraciones y el trait.
- [x] Se ejecutó `graphify update .` después de los cambios de código.

## Notas del programador

- No ejecutar `init:principal`, `init:sucursal` ni `down()` sobre producción sin respaldo y autorización.
- Mantener los nombres exactos de columnas, índices y constraints; el bugfix no debe renombrar nada.
- No cambiar `createTable(..., true)`, `$existeAntes`, `aplicarDefaultCurrentTimestamp()` ni los seeders; no forman parte de este defecto.
- La rama SQLite del trait es solo para pruebas; no se debe usar para afirmar compatibilidad de producción con SQLite.
- La colisión de numeración 095 debe quedar documentada; no renumerar en este cambio.
- Al implementar, ejecutar primero la prueba del trait y después el smoke test MySQL; si el smoke test falla, no cerrar el bugfix.
