# Prototipo de ejecución — BUG-001 Aislar el descuento Zelle de nuevo ingreso y evitar que `init:principal` reinicie configuraciones

- **Rama:** p-bugfix/desc-pg-dolar-ni
- **Rama base:** feature/desacoplar-contructor-pagos
- **Plan:** docs/bugfix/001-desc-pg-dolar-ni/plan.md
- **Fecha:** 2026-10-27
- **Estado:** parcial

## Resumen

`GbConfigSeeder` pasó a ser insert-only: ya no actualiza claves existentes, solo inserta las que faltan. Se agregó la clave global `desc_pg_dolar_ni` con valor inicial `0` mediante el seeder y una migración de datos idempotente registrada en `init:principal`. `desc_pg_dolar` queda aislado para estudiantes regulares. Las pruebas automatizadas del seeder pasan; la verificación manual de `init:principal` quedó bloqueada por una migración GHL no idempotente, fuera del alcance de este bugfix.

## Tareas realizadas

- [x] Crear migración idempotente `2026-10-27-000098_CreateDescPgDolarNiConfig.php` que inserta `desc_pg_dolar_ni = 0` solo si falta.
- [x] Cambiar el bucle de `GbConfigSeeder` a insert-only y agregar `desc_pg_dolar_ni = 0` al catálogo de claves.
- [x] Registrar la nueva migración en `InitPrincipalDb::runPrincipalMigrations()`.
- [x] Ampliar `GbConfigSeederTest` con los cinco casos solicitados.
- [x] Registrar la decisión en `MEMORY.md` (separación de claves y semántica insert-only).
- [ ] Verificación manual: dos ejecuciones consecutivas de `php spark init:principal` sobre una base autorizada. Motivo: la ejecución falla antes de llegar al seeder por una migración previa no idempotente, fuera del alcance de este bugfix (ver Riesgos y pendientes).

## Archivos creados

| Archivo | Motivo |
| --- | --- |
| `app/Database/Migrations/2026-10-27-000098_CreateDescPgDolarNiConfig.php` | Migración de datos idempotente para crear `desc_pg_dolar_ni = 0` en bases existentes sin tocar `desc_pg_dolar`. |

## Archivos modificados

| Archivo | Cambio realizado |
| --- | --- |
| `app/Database/Seeds/GbConfigSeeder.php` | El bucle ahora es insert-only (`continue` si la clave existe); se agregó `desc_pg_dolar_ni` con valor `0`. |
| `app/Commands/InitPrincipalDb.php` | Se registró la migración `2026-10-27-000098_CreateDescPgDolarNiConfig.php`. |
| `tests/app/Database/Seeds/GbConfigSeederTest.php` | Nuevas pruebas: no sobrescritura de `desc_pg_dolar`, alta de `desc_pg_dolar_ni`, conservación si existe, conservación de `costo_seguro` y conteo idempotente de la clave NI. |
| `MEMORY.md` | Se documentó la semántica insert-only de `gb_config` y la separación `desc_pg_dolar` / `desc_pg_dolar_ni`. El archivo está ignorado por Git, por lo que el cambio es local. |
| `docs/bugfix/001-desc-pg-dolar-ni/plan.md` | Estado actualizado a `en curso` y criterios de finalización marcados según lo verificado. |

## Comandos ejecutados

| Comando | Resultado |
| --- | --- |
| `php -l app\Database\Migrations\2026-10-27-000098_CreateDescPgDolarNiConfig.php` | Sin errores de sintaxis. |
| `php -l app\Database\Seeds\GbConfigSeeder.php` | Sin errores de sintaxis. |
| `php -l app\Commands\InitPrincipalDb.php` | Sin errores de sintaxis. |
| `php -l tests\app\Database\Seeds\GbConfigSeederTest.php` | Sin errores de sintaxis. |
| `vendor\bin\phpunit.bat tests/app/Database/Seeds/GbConfigSeederTest.php` | Éxito: `OK (9 tests, 14 assertions)`. Se emitieron deprecaciones preexistentes de `FILTER_SANITIZE_STRING` en `system/Router/RouteCollection.php`, ajenas a este cambio. |
| `php spark init:principal` (manual, entorno del usuario) | Fallo antes de los seeders: `mysqli_sql_exception: Duplicate column name 'ghl_codigo'` en `2026-10-18-000094_AddGhlCodigoToAasucurs.php:26`. Bloqueo externo al alcance de este bugfix. |

## Verificación

- **Prueba manual:** bloqueada. `php spark init:principal` falla antes de ejecutar `GbConfigSeeder` con `Duplicate column name 'ghl_codigo'` en `2026-10-18-000094_AddGhlCodigoToAasucurs.php:26`. Esa migración (y probablemente `2026-10-20-000095_AddGhlContactIdToNiInscripciones.php`, con el mismo patrón) no es idempotente. Por decisión del usuario, se corrige en un bugfix separado y no se modificó aquí.
- **Pruebas automatizadas:** `vendor\bin\phpunit.bat tests/app/Database/Seeds/GbConfigSeederTest.php` → `OK (9 tests, 14 assertions)`. Cubre no sobrescritura de `desc_pg_dolar`, alta y conservación de `desc_pg_dolar_ni`, conservación de `costo_seguro` e idempotencia.
- **Criterios del plan:** cumplidos la no sobrescritura, la creación/conservación de la clave NI, el seeder insert-only, la migración idempotente registrada, las pruebas del seeder y la actualización de `MEMORY.md`. Pendiente solo la verificación manual con `init:principal`.

## Desviaciones del plan

- El plan indicaba que el repositorio estaba en `feature/inscripciones-nuevo-ingreso`; la rama real era `feature/desacoplar-contructor-pagos`. La rama `p-bugfix/desc-pg-dolar-ni` se creó desde la rama actual, sin cambiar el historial.
- `desc_pg_dolar_ni` se agregó al arreglo `$records` existente en lugar de un bloque separado como `pensum_activo`, porque el bucle insert-only ya garantiza el comportamiento requerido.
- `down()` de la migración es intencionalmente un no-op: borrar la clave al revertir eliminaría configuración operativa real.

## Riesgos y pendientes

- **Bloqueo de verificación manual:** `2026-10-18-000094_AddGhlCodigoToAasucurs.php` llama `addColumn` sin `fieldExists` y falla con `Duplicate column name 'ghl_codigo'` al reejecutar `init:principal`. `2026-10-20-000095_AddGhlContactIdToNiInscripciones.php` repite el patrón y fallaría a continuación. El usuario decidió tratarlo en otro bugfix; aquí no se modificaron esas migraciones.
- Falta la verificación manual de dos ejecuciones consecutivas de `init:principal` en una base autorizada, una vez corregidas las migraciones GHL.
- `MEMORY.md` está en `.gitignore`; la decisión quedó documentada solo en el working tree local y no viajará con un commit.
- `GbConfigSucursalSeeder` mantiene el patrón de actualización anterior; el plan lo excluye explícitamente y queda como bugfix separado.
- `desc_pg_dolar_ni` aún no tiene consumidor en el flujo de pagos de nuevo ingreso; eso pertenece a la feature de pagos NI.
