# Aislar el descuento Zelle de nuevo ingreso y evitar que `init:principal` reinicie configuraciones

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

## Objetivo

Evitar que `init:principal` sobrescriba configuraciones reales de `gb_config`, en especial `desc_pg_dolar`, que pertenece a los estudiantes regulares. Crear una clave independiente `desc_pg_dolar_ni` para el descuento de nuevo ingreso, con valor inicial `0`, sin reiniciar valores ya existentes.

## Problema

`InitPrincipalDb` ejecuta `GbConfigSeeder` en cada invocación de `init:principal`. Ese seeder, además de insertar claves faltantes, actualiza las claves existentes con sus valores por defecto (`app/Database/Seeds/GbConfigSeeder.php:75-78`). Por eso una base con `desc_pg_dolar` configurado para estudiantes regulares vuelve a `0` (valor del seed en `app/Database/Seeds/GbConfigSeeder.php:40-42`).

Además, no existe una clave `desc_pg_dolar_ni`, por lo que nuevo ingreso no tiene un porcentaje de descuento aislado y, cuando se implemente su consumo, tendería a reutilizar la clave de estudiantes regulares.

## Impacto

- **Estudiantes regulares:** un descuento Zelle ya configurado puede quedar en `0` tras ejecutar `init:principal`, alterando el monto que pagan.
- **Nuevo ingreso:** no hay una configuración propia de descuento; queda acoplado al valor de estudiantes regulares.
- **Operación:** el comando se presenta como idempotente, pero en la práctica reinicia datos de configuración. Esto reduce la confianza en `init:*` y complica reinstalaciones o soporte.
- **Gravedad:** alta por tratarse de configuración financiera; el impacto real depende de si `init:principal` ya se ejecutó sobre una base con valores reales. No hay evidencia en el repositorio de que eso haya ocurrido en producción. Si se confirma que ya afectó a usuarios reales, este caso debe tratarse como **hotfix**, no como bugfix.

## Reproducción

1. En una base autorizada de desarrollo, verificar que `gb_config` tenga `desc_pg_dolar` con un valor distinto de `0` (por ejemplo `5`).
2. Ejecutar `php spark init:principal` o, para aislar el seed, `php spark db:seed GbConfigSeeder`.
3. Consultar `SELECT codigo, valor FROM gb_config WHERE codigo = 'desc_pg_dolar';`.
4. Resultado actual: `desc_pg_dolar` vuelve a `0`.
5. Consultar `SELECT codigo, valor FROM gb_config WHERE codigo = 'desc_pg_dolar_ni';`.
6. Resultado actual: la clave no existe.

## Comportamiento esperado

- `init:principal` inserta únicamente las claves de `gb_config` que faltan y nunca modifica el valor de una clave existente.
- `desc_pg_dolar` conserva el valor configurado para estudiantes regulares.
- `desc_pg_dolar_ni` se crea con valor `0` solo cuando no existe.
- Si `desc_pg_dolar_ni` ya existe, se conserva su valor.
- El comando puede ejecutarse varias veces sin cambiar configuraciones ni duplicar claves.

## Causa raíz (hipótesis)

**Confirmada en código, pendiente de confirmar impacto real en producción.**

1. `GbConfigSeeder::run()` actualiza cualquier clave que ya exista (`app/Database/Seeds/GbConfigSeeder.php:69-81`). No distingue entre una instalación nueva y una configuración real.
2. `InitPrincipalDb::run()` invoca ese seeder en cada ejecución (`app/Commands/InitPrincipalDb.php:70`), por lo que `init:principal` propaga la sobrescritura.
3. El seed declara `desc_pg_dolar = 0` (`app/Database/Seeds/GbConfigSeeder.php:40-42`), valor que reemplaza al configurado.
4. No existe `desc_pg_dolar_ni` en el esquema, seed ni migraciones. `tasaDolar_helper.php` solo expone `getDescuentoDolar()` para `desc_pg_dolar` (`app/Helpers/tasaDolar_helper.php:54-72`), y `PagosZelleServices` aplica ese descuento al convertir el monto a dólares (`app/Libraries/Payments/PagosZelleServices.php:41` y `:91`).

## Archivos afectados

| Acción | Archivo | Motivo |
| --- | --- | --- |
| Agregar | `app/Database/Migrations/2026-10-27-000098_CreateDescPgDolarNiConfig.php` (propuesta) | Migración de datos idempotente: inserta `desc_pg_dolar_ni = 0` solo si la clave no existe. No modifica `desc_pg_dolar`. El número `000098` es el siguiente libre; se verificaron colisiones hasta `000097`. |
| Modificar | `app/Database/Seeds/GbConfigSeeder.php` | Cambiar el bucle de inserción/actualización para que sea insert-only: si la clave existe, conservarla; si falta, insertarla. Agregar `desc_pg_dolar_ni` con valor `0`. |
| Modificar | `app/Commands/InitPrincipalDb.php` | Registrar la nueva migración en `runPrincipalMigrations()` para que `init:principal` la aplique. |
| Modificar | `tests/app/Database/Seeds/GbConfigSeederTest.php` | Cubrir que `desc_pg_dolar` no se sobrescribe, que `desc_pg_dolar_ni` se crea en `0` si falta, que se conserva si existe y que el seeder es idempotente para la nueva clave. |
| Modificar | `MEMORY.md` | Registrar la decisión: `gb_config` es insert-only en `init:principal` y nuevo ingreso usa `desc_pg_dolar_ni`, separado de estudiantes regulares. |

> No se modifica `app/Helpers/tasaDolar_helper.php` en este bugfix: en esta rama el Paso 4 de pago es un placeholder y no existe consumidor de descuentos de nuevo ingreso. Agregar el helper o el consumo real pertenece a la implementación de la feature de pagos de nuevo ingreso.

## Plan de verificación

### Prueba manual (flujo normal)

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

1. Confirmar el valor actual: `SELECT codigo, valor FROM gb_config WHERE codigo IN ('desc_pg_dolar', 'desc_pg_dolar_ni');`.
2. Si `desc_pg_dolar` no tiene un valor distinguible, asignar uno de prueba (`5`) y eliminar `desc_pg_dolar_ni` si existe.
3. Ejecutar `php spark init:principal`.
4. Verificar que `desc_pg_dolar` sigue en `5` y que `desc_pg_dolar_ni` existe con `0`.
5. Cambiar `desc_pg_dolar_ni` a `7` y ejecutar de nuevo `php spark init:principal`.
6. Verificar que `desc_pg_dolar` sigue en `5` y `desc_pg_dolar_ni` sigue en `7`.
7. Resultado esperado: ninguna configuración existente cambia; solo se insertan claves faltantes y no hay duplicados.

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

Ampliar `tests/app/Database/Seeds/GbConfigSeederTest.php` con estos casos:

- `testDescPgDolarNoSeSobrescribeSiYaExiste`: insertar `desc_pg_dolar = 5`, ejecutar el seeder y afirmar que sigue en `5`.
- `testDescPgDolarNiSeInsertaEnCeroSiFalta`: ejecutar el seeder y afirmar que `desc_pg_dolar_ni` existe con `0`.
- `testDescPgDolarNiNoSeSobrescribeSiYaExiste`: insertar `desc_pg_dolar_ni = 7`, ejecutar el seeder y afirmar que sigue en `7`.
- `testSeederNoReiniciaOtrasConfiguracionesExistentes`: insertar por ejemplo `costo_seguro = 3.5`, ejecutar el seeder y afirmar que se conserva.
- Extender `testSeederEsIdempotente` para afirmar que hay exactamente una fila de `desc_pg_dolar_ni` tras ejecutar el seeder dos veces.

Comando en Windows/PowerShell:

```powershell
vendor\bin\phpunit.bat tests/app/Database/Seeds/GbConfigSeederTest.php
```

Alternativa si el proxy de Composer falla:

```powershell
php vendor\phpunit\phpunit\phpunit tests/app/Database/Seeds/GbConfigSeederTest.php
```

La migración se valida en la prueba manual anterior, porque `init:principal` la ejecuta dos veces y debe conservar la clave NI existente. Si se desea cobertura automatizada adicional, agregar una prueba de integración de la migración en `tests/app/Database/Migrations/` usando SQLite en memoria; no se crea ahora porque la verificación manual ya demuestra el caso y la suite actual no tiene pruebas de migraciones.

## Riesgos y efectos secundarios

- **Cambio de semántica del seed:** al ser insert-only, los valores por defecto ya no corregirán configuraciones existentes. Cualquier ajuste intencional deberá hacerse por SQL o por la interfaz administrativa correspondiente.
- **Bases existentes:** la clave `desc_pg_dolar_ni` solo aparecerá si se aplica la migración. Si el despliegue no ejecuta migraciones, la clave seguirá ausente.
- **Producción:** aunque el fix evita la sobrescritura, `init:principal` sigue aplicando migraciones y otros seeders. Debe ejecutarse con respaldo y autorización.
- **Longitud de clave:** `desc_pg_dolar_ni` tiene 16 caracteres y cabe en `gb_config.codigo` (`VARCHAR(20)`).
- **Alcance relacionado no incluido:** `GbConfigSucursalSeeder` usa el mismo patrón de actualización para configuraciones locales de sede. No se corrige aquí para no ampliar el alcance; se recomienda evaluarlo en un bugfix separado.
- **Rama actual:** el repositorio está en `feature/inscripciones-nuevo-ingreso`, no en una rama de bugfix. No se cambia de rama automáticamente; se recomienda crear una rama `fix/desc-pg-dolar-ni` antes de implementar.

## Criterios de finalización

- [x] `desc_pg_dolar` conserva su valor tras ejecutar `init:principal` o `GbConfigSeeder` (cubierto por prueba automatizada; verificación manual de `init:principal` pendiente).
- [x] `desc_pg_dolar_ni` se crea con `0` solo cuando falta y conserva su valor si ya existe.
- [x] `GbConfigSeeder` no actualiza ninguna clave existente.
- [x] La migración nueva es idempotente y está registrada en `InitPrincipalDb`.
- [x] Las pruebas de `tests/app/Database/Seeds/GbConfigSeederTest.php` pasan.
- [ ] La verificación manual confirma que dos ejecuciones consecutivas no alteran configuraciones.
- [x] `MEMORY.md` refleja la separación de claves y la semántica insert-only.

## Notas del programador
