# Esquema y configuración del pago de nuevo ingreso

- **Código:** FEAT-001
- **Tipo:** feature
- **Estado:** en curso
- **Fecha:** 2026-10-27
- **Autor:** opencode (agente)

## Objetivo

Preparar el sustrato de base de datos y configuración que necesitará el futuro Paso 4 de pago de nuevo ingreso: vincular una intención de pago con la postulación (`ni_inscripciones`), ampliar la identificación almacenada, registrar el tipo de pago `_ni`, dejar la configuración local `ni_plan_pago_id` vacía por sede y disponer de dos planes demo para pruebas. No se implementa todavía interfaz, rutas, servicio de dominio ni procesamiento de pagos.

## Alcance

- Incluye:
  - Migración `2026-10-27-000099_AddNiInscripcionIdToPgIntencionesPago.php`: columna `ni_inscripcion_id` nullable e índice simple en `pg_intenciones_pago` de la base principal.
  - Migración `2026-10-27-000100_AlterIdentificacionPgIntencionesPago.php`: ampliar `pg_intenciones_pago.identificacion` de `VARCHAR(16)` a `VARCHAR(20)`.
  - Registro de ambas migraciones en `app/Commands/InitPrincipalDb.php`, después de la migración `098` existente.
  - Nueva fila idempotente `id = 3`, `codigo = '_ni'`, `descripcion = 'Nuevo Ingreso'` en `pg_tipos_pagos`.
  - Configuración local `gb_config.ni_plan_pago_id` con valor vacío por sede, insert-only, mediante `GbConfigSucursalSeeder`.
  - Dos planes demo por sede, solo para `demo:seed`: `PLAN NI CONTADO` (id 900002) y `PLAN NI CUOTAS` (id 900003), con sus detalles.
  - En `demo:seed`, valor demo `900002,900003` en `gb_config.ni_plan_pago_id`.
  - Pruebas automatizadas de migraciones/seeders afectados y actualización de la documentación de estado.
- No incluye:
  - UI, vistas, controladores, rutas o formularios del Paso 4.
  - `PaymentService`, `PaymentOrchestrator`, pasarelas, intenciones de pago, recibos, GHL o CSRF.
  - Consumo o validación de `ni_plan_pago_id` en código de dominio.
  - Backfill de `ni_inscripcion_id` en intenciones existentes.
  - Cambios en la migración `098` ya existente.
  - Migraciones de sucursal para `ni_inscripcion_id` o `identificacion`; ambos cambios viven en la base principal.
  - Ejecución en producción, `down()` sobre datos reales o `demo:seed` sin autorización.

## Contexto y supuestos

- La migración `2026-10-27-000098_CreateDescPgDolarNiConfig.php` ya existe y crea `gb_config.desc_pg_dolar_ni`; por eso las migraciones nuevas se numeran `099` y `100` para no colisionar ni reescribir una migración potencialmente aplicada.
- `pg_intenciones_pago` existe en la base principal y hoy tiene `identificacion VARCHAR(16) NOT NULL`, sin valor por defecto.
- `ni_inscripciones.id` es `INT(11)` autoincremental en la base principal; la relación es lógica y no requiere foreign key en esta etapa.
- `gb_config` existe en la base principal y en cada sucursal. `codigo` es `VARCHAR(20)` y `valor` es `TEXT`, suficiente para `ni_plan_pago_id` y para una lista separada por comas.
- `init:principal` aplica las migraciones de la base principal y luego ejecuta `PgTiposPagosSeeder`.
- `init:sucursal` aplica las migraciones de la sucursal y luego ejecuta `GbConfigSucursalSeeder`; es el punto donde debe quedar `ni_plan_pago_id` vacío.
- `demo:seed` ejecuta `SucursalAcademicaSeeder` y `SucursalPagosSeeder` por sede; los planes demo y el valor de configuración demo deben vivir en este flujo, no en `init:sucursal`.
- Los identificadores demo viven en el rango `900000+`; el plan existente `PLAN PRUEBA` (900001) se conserva sin cambios.
- Se reutilizan los valores del `PLAN PRUEBA`: `MnInscripcion = 0`, `ref_dolar = 50`, `PeriosClasesID = 1` y `CePerioLectID = 900001` (periodo demo). Las fechas se definen en las reglas de negocio.
- Para el `PLAN NI CONTADO` se asume `NuCuotas = 1` por tener una sola cuota; queda como pregunta abierta porque la respuesta de negocio solo confirmó los detalles.
- No existe consumidor de `ni_plan_pago_id` todavía; su formato se documenta ahora para que el futuro servicio lo lea sin ambigüedad.

## Flujo normal

1. Paso 1: Crear la migración `099` con el trait `IntrospeccionEsquema`. Verificar que `pg_intenciones_pago` exista; si no existe, registrar advertencia y no hacer cambios.
2. Paso 2: En la migración `099`, si `ni_inscripcion_id` no existe, agregarla como `INT(11) NULL` después de `id`. Si el índice `idx_pg_intenciones_pago_ni_inscripcion_id` no existe, crearlo sobre esa columna. No agregar foreign key ni backfill.
3. Paso 3: Crear la migración `100`. Verificar que `pg_intenciones_pago.identificacion` exista y que su longitud declarada sea menor a 20; si aplica, modificarla a `VARCHAR(20) NOT NULL` conservando los datos existentes. Si ya es 20 o mayor, no hacer cambios.
4. Paso 4: Registrar `099` y `100` en `app/Commands/InitPrincipalDb.php`, después de `2026-10-27-000098_CreateDescPgDolarNiConfig.php`, para que `init:principal` las aplique de forma idempotente.
5. Paso 5: Extender `PgTiposPagosSeeder` para sembrar `id = 3`, `codigo = '_ni'`, `descripcion = 'Nuevo Ingreso'`. No modificar las filas 1 (`_de`) y 2 (`_inc`). Si el `id = 3` ya está ocupado por otro código, no sobrescribir y registrar una advertencia.
6. Paso 6: Extender `GbConfigSucursalSeeder` para insertar `codigo = 'ni_plan_pago_id'`, `valor = ''` solo si la clave no existe. No sobrescribir un valor real ya configurado.
7. Paso 7: Agregar en `DemoData` las constantes de los dos planes demo y sus detalles; extender `SucursalPagosSeeder` para crearlos por sede con `upsert` por id.
8. Paso 8: En el mismo seeder demo, escribir `gb_config.ni_plan_pago_id = '900002,900003'` por sede demo. Este valor solo se aplica en `demo:seed`; `init:sucursal` deja la clave vacía.
9. Paso 9: Ejecutar las pruebas del área y los comandos de verificación en una base de desarrollo o pruebas autorizada; comprobar estructura, filas y valores con consultas de solo lectura.
10. Paso 10: Actualizar `MEMORY.md` con el estado del esquema y de la configuración, y registrar cualquier pendiente que surja de la implementación.

## Flujos alternativos / variantes

### Base nueva

1. Paso 1: Ejecutar `php spark init:principal`. Se crean las tablas de la base principal, se aplican `099` y `100`, y `PgTiposPagosSeeder` deja `_ni` con id 3.
2. Paso 2: Ejecutar `php spark init:sucursal <id>` por cada sede autorizada. `GbConfigSucursalSeeder` deja `ni_plan_pago_id` vacío.
3. Paso 3: Ejecutar `php spark demo:seed --solo sucursales --sucursales <id>` en un entorno de pruebas. Se crean los dos planes demo y se escribe `900002,900003` en la configuración local.
4. Paso 4: Verificar que una segunda ejecución de los tres comandos no duplique columnas, índices, filas de catálogo ni planes.

### Base existente con datos

1. Paso 1: Ejecutar `php spark init:principal`. Las migraciones detectan columnas e índices existentes y no los recrean; el seeder de tipos de pago no altera `_de` ni `_inc`.
2. Paso 2: Ejecutar `php spark init:sucursal <id>`. Si `ni_plan_pago_id` ya existe con un valor real, se conserva.
3. Paso 3: No ejecutar `demo:seed` sobre sedes reales. Los planes demo solo se aplican en entornos de prueba y con autorización.

### Intención de pago ya vinculada o identificación ya ampliada

1. Paso 1: Si `ni_inscripcion_id` ya existe con datos, la migración `099` no la modifica ni la vuelve a crear.
2. Paso 2: Si `identificacion` ya es `VARCHAR(20)` o mayor, la migración `100` no la modifica.
3. Paso 3: Los registros existentes conservan su valor; no se ejecuta backfill ni se valida el contenido de la identificación en esta etapa.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| `pg_intenciones_pago` no existe en la base principal | `tableExists` en la migración `099`/`100` | Registrar advertencia y omitir el cambio | Migración aplicada sin cambios; revisar esquema antes de continuar |
| `ni_inscripcion_id` ya existe | `columnaExiste` | No agregar la columna | Conserva la columna y sus datos |
| El índice ya existe con el nombre esperado | `indiceExiste` | No recrear el índice | Índice existente intacto |
| El nombre del índice existe sobre otra columna | `indiceExiste` devuelve verdadero por nombre | No recrear; registrar advertencia para revisión manual | Esquema sin cambios automáticos |
| `identificacion` no existe | `fieldExists` en la migración `100` | Registrar advertencia y omitir | Sin cambio; revisar esquema |
| `identificacion` ya mide 20 o más | `getFieldData` sobre la tabla | No modificar la columna | Datos y longitud actuales intactos |
| La modificación de columna falla por permisos o bloqueo | Excepción de la base de datos | La migración falla y `init:principal` se detiene | Cambio parcial posible por DDL no transaccional; revisar y reintentar |
| `id = 3` de `pg_tipos_pagos` está ocupado por otro código | Consulta previa por id y código | No sobrescribir; registrar advertencia | Filas 1 y 2 intactas; `_ni` no se crea hasta revisión manual |
| `gb_config` no existe en la sede | `tableExists` en el seeder | Registrar advertencia y omitir la clave | Sede sin `ni_plan_pago_id`; ejecutar `init:sucursal` primero |
| `ceplanpagoperio` o `ceplanpagoperiodet` no existen en la sede demo | `tableExists` antes de sembrar planes | Registrar error y omitir esa sede; continuar con las demás | Sede sin planes demo; requiere esquema de sucursal completo |
| `ni_plan_pago_id` ya tiene un valor real | Consulta por `codigo` en `GbConfigSucursalSeeder` | No sobrescribir | Valor real conservado |
| `demo:seed` se ejecuta en producción sin `--force` | Validación existente del comando | Cancelar la ejecución | Sin cambios en datos |

## Reglas de negocio y validaciones

- La migración `099` agrega `ni_inscripcion_id` como `INT(11) NULL`, sin foreign key y con índice simple `idx_pg_intenciones_pago_ni_inscripcion_id`. No se rellena hacia atrás.
- La migración `100` deja `identificacion` como `VARCHAR(20) NOT NULL`, sin cambiar su nulabilidad ni agregar valor por defecto. `down()` no revierte la longitud para evitar truncar identificaciones ya guardadas.
- `down()` de `099` elimina el índice y la columna solo si existen; es idempotente. `down()` de `100` es no-op.
- La migración `098` no se modifica.
- `pg_tipos_pagos` debe contener `id = 3`, `codigo = '_ni'`, `descripcion = 'Nuevo Ingreso'`. Las filas 1 y 2 no se alteran.
- `gb_config.ni_plan_pago_id` es una configuración local de sede. En `init:sucursal` se inserta vacía y nunca se sobrescribe un valor existente.
- El formato documentado de `ni_plan_pago_id` es una lista de `CePlanPagoPerioID` numéricos separados por coma, sin espacios. Valor vacío permitido. En demo se usa `900002,900003`.
- `PLAN NI CONTADO`: `CePlanPagoPerioID = 900002`, `NbPlan = 'PLAN NI CONTADO'`, `CoPlan = 'CONTADO'`, `PeriosClasesID = 1`, `MnInscripcion = 0`, `NuCuotas = 1` (supuesto), `CePerioLectID = 900001`, `ref_dolar = 50`.
- Detalle de `PLAN NI CONTADO`: `CePlanPagoPerioDetID = 900021`, `SeDetPlan = 0`, `TpDetPlan = 1`, `PoDetPlan = 100`, `FeTopePago = '2026-05-18'`.
- `PLAN NI CUOTAS`: `CePlanPagoPerioID = 900003`, `NbPlan = 'PLAN NI CUOTAS'`, `CoPlan = 'CUOTAS'`, `PeriosClasesID = 1`, `MnInscripcion = 0`, `NuCuotas = 5`, `CePerioLectID = 900001`, `ref_dolar = 50`.
- Detalles de `PLAN NI CUOTAS`: total cinco filas, con suma de `PoDetPlan` igual a 100:
  - `CePlanPagoPerioDetID = 900031`, `SeDetPlan = 0`, `TpDetPlan = 1`, `PoDetPlan = 0`, `FeTopePago = '2026-05-18'`.
  - `CePlanPagoPerioDetID = 900032` a `900035`, `SeDetPlan = 1` a `4`, `TpDetPlan = 2`, `PoDetPlan = 25`, `FeTopePago = '2026-06-30'`.
- Los planes demo solo se siembran desde `demo:seed`; no deben ejecutarse desde `init:sucursal` ni en producción.
- El `PLAN PRUEBA` existente (900001) y sus detalles no se modifican.
- No se crean rutas, controladores, vistas, servicios ni validaciones de identificación en esta feature.

## Áreas afectadas

| Acción | Archivo / componente | Motivo |
| --- | --- | --- |
| Crear | `app/Database/Migrations/2026-10-27-000099_AddNiInscripcionIdToPgIntencionesPago.php` | Columna `ni_inscripcion_id` e índice en la base principal |
| Crear | `app/Database/Migrations/2026-10-27-000100_AlterIdentificacionPgIntencionesPago.php` | Ampliar `identificacion` a `VARCHAR(20)` |
| Modificar | `app/Commands/InitPrincipalDb.php` | Registrar las migraciones `099` y `100` |
| Modificar | `app/Database/Seeds/PgTiposPagosSeeder.php` | Sembrar `_ni` con id 3 |
| Modificar | `app/Database/Seeds/GbConfigSucursalSeeder.php` | Insertar `ni_plan_pago_id` vacío por sede |
| Modificar | `app/Database/Seeds/Demo/DemoData.php` | Constantes de planes y detalles demo |
| Modificar | `app/Database/Seeds/Demo/SucursalPagosSeeder.php` | Crear los dos planes demo y el valor demo de la configuración |
| Crear / modificar | `tests/app/Database/Seeds/PgTiposPagosSeederTest.php` | Verificar `_ni`, idempotencia y no alteración de filas 1 y 2 |
| Modificar | `tests/app/Database/Seeds/GbConfigSucursalSeederTest.php` | Verificar `ni_plan_pago_id` vacío, insert-only y nuevo total de filas |
| Crear | `tests/app/Database/Seeds/SucursalPagosSeederTest.php` | Verificar los dos planes, sus detalles y el valor `900002,900003` |
| Crear | `tests/app/Database/Migrations/MigracionesNiPagoTest.php` | Verificar idempotencia y estructura de `099`/`100` según el driver disponible |
| Modificar | `MEMORY.md` | Registrar el estado del esquema y la configuración de pago de nuevo ingreso |

No se modifican `Routes.php`, controladores, vistas, `PaymentService`, `PaymentOrchestrator`, `NiInscripciones` ni la migración `098`.

## Criterios de finalización

- [x] Existe la migración `099`, es idempotente, agrega `ni_inscripcion_id INT(11) NULL` y el índice `idx_pg_intenciones_pago_ni_inscripcion_id`, sin foreign key ni backfill.
- [x] El `down()` de `099` elimina índice y columna solo si existen y puede ejecutarse dos veces sin error.
- [x] Existe la migración `100`, es idempotente, amplía `identificacion` a `VARCHAR(20) NOT NULL` y su `down()` es no-op.
- [x] `InitPrincipalDb` incluye ambas migraciones después de la `098` y `php spark init:principal` las aplica sin duplicar estructura al reejecutarse.
- [x] `PgTiposPagosSeeder` deja `id = 3`, `codigo = '_ni'`, `descripcion = 'Nuevo Ingreso'`; las filas 1 y 2 permanecen intactas y una segunda ejecución no duplica.
- [x] `GbConfigSucursalSeeder` inserta `ni_plan_pago_id = ''` por sede solo si falta; no sobrescribe un valor real y una segunda ejecución no duplica.
- [x] `demo:seed` crea `PLAN NI CONTADO` (900002) con su detalle 900021 y `PLAN NI CUOTAS` (900003) con los detalles 900031 a 900035, con los montos, porcentajes y fechas especificados.
- [x] `demo:seed` deja `ni_plan_pago_id = '900002,900003'` por sede demo; `init:sucursal` lo deja vacío.
- [x] Una segunda ejecución de `demo:seed` no duplica planes, detalles ni claves de configuración.
- [x] Las pruebas nuevas y actualizadas del área pasan con `vendor/bin/phpunit tests/app/Database/Migrations/MigracionesNiPagoTest.php tests/app/Database/Seeds/PgTiposPagosSeederTest.php tests/app/Database/Seeds/GbConfigSucursalSeederTest.php tests/app/Database/Seeds/SucursalPagosSeederTest.php`.
- [ ] Se ejecutó un smoke test en una base de desarrollo o pruebas autorizada y se documentaron las consultas de verificación.
- [x] No se modificaron UI, rutas, controladores, servicios de dominio ni la migración `098`.
- [x] `MEMORY.md` refleja el nuevo esquema y la configuración, y los supuestos/pendientes que sigan abiertos.

## Preguntas abiertas

- ¿`NuCuotas` del `PLAN NI CONTADO` debe ser `1` (una sola cuota) o `0` para replicar literalmente el `PLAN PRUEBA`? En este plan se asume `1`.
- ¿Los IDs de detalle propuestos (`900021` y `900031` a `900035`) están libres en todas las sedes demo, o el equipo prefiere otro rango?
- ¿La descripción exacta debe ser `Nuevo Ingreso` con mayúscula inicial en ambas palabras, o el negocio usa otro texto?
- ¿Se confirma que `identificacion` sigue siendo obligatoria (`NOT NULL`) después de ampliarla a `VARCHAR(20)`?
- ¿El futuro consumidor de `ni_plan_pago_id` espera IDs numéricos separados por coma, o códigos de plan (`CONTADO,CUOTAS`)? En este plan se usa `900002,900003`.
- ¿La siembra de los planes demo debe permanecer dentro de `SucursalPagosSeeder` o extraerse a un seeder específico de nuevo ingreso? En este plan se extiende `SucursalPagosSeeder`.
- ¿La interpretación de `TpDetPlan = 1` para el inicial y `TpDetPlan = 2` para las cuotas es la correcta según el negocio?

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-27 | Creación del plan FEAT-001 con alcance de esquema y configuración, sin UI, rutas ni servicio de dominio. | opencode (agente) |
| 2026-10-27 | Implementación de migraciones `099`/`100`, seeders y pruebas del área. Smoke test en base autorizada pendiente. | opencode (agente) |
