# Prototipo de ejecución — BUG-004 Aislamiento de pagos regulares frente a pagos de nuevo ingreso

- **Rama:** p-bugfix/aislamiento-pagos-regulares-nuevo-ingreso
- **Rama base:** feature/desacoplar-contructor-pagos
- **Plan:** docs/bugfix/004-aislamiento-pagos-regulares-nuevo-ingreso/plan.md
- **Fecha:** 2026-10-28
- **Estado:** parcial

## Resumen

Se implementó el aislamiento por origen en los flujos regulares: las consultas y autorizaciones ahora excluyen intenciones con `ni_inscripcion_id` no nulo. También se cerró el IDOR de `retirarDetalle`, se protegió `Reportes::Recibo`, se impidió la cancelación regular de intenciones NI y se parametrizó el cierre de vencidos para que el portal regular no toque pagos de nuevo ingreso. Las pruebas automatizadas del modelo, del servicio NI y de pagos quedaron en verde. La verificación manual en una base de desarrollo sigue pendiente porque este entorno no dispone de la base/sesión autorizada.

## Tareas realizadas

- [x] Filtrar `ni_inscripcion_id IS NULL` en `IntencionesPagoModel::getPagosPorCedulaConDetalle()`.
- [x] Rechazar en `IntencionesPagoModel::cancelarIntencion()` las intenciones NI cuando se llama sin `$niId`.
- [x] Parametrizar `IntencionesPagoModel::cierraPagosVencidos()` por origen regular o por postulación NI.
- [x] Pasar `$niInscripcionId` desde `NuevoIngresoPagoService::crearIntencion()` al cierre de vencidos.
- [x] Filtrar `pg_intenciones_pago.ni_inscripcion_id IS NULL` en `Pagos::index()`.
- [x] Rechazar intenciones NI en `Pagos::validarPropietario()`.
- [x] Validar detalle, existencia de la intención, origen regular y propietario en `Pagos::retirarDetalle()`.
- [x] Rechazar intenciones NI en `Reportes::Recibo()`.
- [x] Agregar seis pruebas de regresión en `IntencionesPagoModelNiTest`.
- [x] Agregar una prueba de integración en `NuevoIngresoPagoServiceTest`.
- [x] Ejecutar `php -l` sobre todos los archivos PHP modificados.
- [x] Ejecutar las tres suites indicadas por el plan.
- [x] Actualizar el grafo con `graphify update .`.
- [ ] Verificación manual en base de desarrollo — Motivo: no hay base ni sesión de desarrollo autorizada en este entorno.
- [ ] Auditoría de intenciones NI históricas con `ni_inscripcion_id` nulo — Motivo: requiere acceso a la base principal de desarrollo.

## Archivos creados

| Archivo | Motivo |
| --- | --- |
| `docs/bugfix/004-aislamiento-pagos-regulares-nuevo-ingreso/prototipo.md` | Registro de ejecución de este bugfix. |

## Archivos modificados

| Archivo | Cambio realizado |
| --- | --- |
| `app/Models/PagosOnline/IntencionesPagoModel.php` | Filtro por origen en la consulta por cédula; guarda de origen en `cancelarIntencion()`; parámetro de origen en `cierraPagosVencidos()`. |
| `app/Controllers/Pagos.php` | Filtro NI en `index()`; rechazo NI en `validarPropietario()`; validación de detalle, intención, origen y propietario en `retirarDetalle()`. |
| `app/Controllers/Reportes.php` | Rechazo de intenciones NI en `Recibo()` con el mensaje de permisos existente. |
| `app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoService.php` | El cierre de vencidos recibe el `$niInscripcionId` de la postulación. |
| `tests/app/Models/PagosOnline/IntencionesPagoModelNiTest.php` | Seis casos nuevos: filtro por origen, `detalleExiste()`, cancelación regular/NI y cierre de vencidos por origen; se sembró el tipo de pago 1 para simular deudas regulares. |
| `tests/app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoServiceTest.php` | Caso que verifica que `crearIntencion(20)` cierra solo la intención vencida de la postulación 20 y no la 21. |
| `docs/bugfix/004-aislamiento-pagos-regulares-nuevo-ingreso/plan.md` | Estado actualizado de `pendiente` a `en curso` por la verificación manual pendiente. |

## Comandos ejecutados

| Comando | Resultado |
| --- | --- |
| `php -l app\Models\PagosOnline\IntencionesPagoModel.php` | Sin errores de sintaxis. |
| `php -l app\Controllers\Pagos.php` | Sin errores de sintaxis. |
| `php -l app\Controllers\Reportes.php` | Sin errores de sintaxis. |
| `php -l app\Libraries\Inscripciones\NuevoIngreso\Pago\NuevoIngresoPagoService.php` | Sin errores de sintaxis. |
| `php -l tests\app\Models\PagosOnline\IntencionesPagoModelNiTest.php` | Sin errores de sintaxis. |
| `php -l tests\app\Libraries\Inscripciones\NuevoIngreso\Pago\NuevoIngresoPagoServiceTest.php` | Sin errores de sintaxis. |
| `vendor\bin\phpunit.bat tests\app\Models\PagosOnline\IntencionesPagoModelNiTest.php --no-coverage` | OK: 14 tests, 43 assertions. |
| `vendor\bin\phpunit.bat tests\app\Libraries\Inscripciones\NuevoIngreso\Pago --no-coverage` | OK: 16 tests, 57 assertions. |
| `vendor\bin\phpunit.bat tests\app\Libraries\Payments --no-coverage` | OK: 18 tests, 67 assertions. |
| `graphify update .` | Grafo actualizado: 13.403 nodos, 27.327 aristas y 865 comunidades. Advertencias preexistentes por `tree_sitter_sql` ausente y tres archivos no PHP; no afectan este bugfix. |

## Verificación

- **Prueba manual:** no ejecutada. Requiere una base de desarrollo con una intención NI y un estudiante regular con la misma cédula, además de una sesión válida. Los pasos están documentados en `plan.md` (portal regular, flujo NI, flujo regular completo y consulta de control posterior).
- **Pruebas automatizadas:** modelo en `tests/app/Models/PagosOnline/IntencionesPagoModelNiTest.php` (14/14), servicio NI en `tests/app/Libraries/Inscripciones/NuevoIngreso/Pago` (16/16) y pagos en `tests/app/Libraries/Payments` (18/18). Las tres suites quedaron en verde.
- **Criterios del plan:**
  - [x] `getPagosPorCedulaConDetalle()` excluye NI y `detalleExiste()` ya no ve sus detalles; cubierto por pruebas.
  - [x] `cancelarIntencion($id)` sin `$niId` rechaza NI; con `$niId` coincidente sigue funcionando; cubierto por pruebas.
  - [x] `cierraPagosVencidos()` sin parámetro no toca NI; con `$niInscripcionId` cierra solo esa postulación; cubierto por pruebas.
  - [x] `NuevoIngresoPagoService::crearIntencion()` pasa `$niInscripcionId`; cubierto por prueba de servicio.
  - [ ] `/Pagos` no lista intenciones NI — código implementado, verificación manual pendiente.
  - [ ] `validarPropietario()` rechaza NI y conserva el rechazo por cédula distinta — código implementado, verificación manual pendiente.
  - [ ] `CambiarPagar`, `prePago`, `postPago`, `CancelarPago` e `IntencionesPagos` no modifican intenciones NI — código implementado, verificación manual pendiente.
  - [ ] `Reportes::Recibo()` rechaza NI y no genera PDF — código implementado, verificación manual pendiente.
  - [ ] `retirarDetalle()` rechaza detalles NI, ajenos o inexistentes y permite los propios regulares — código implementado, verificación manual pendiente.
  - [ ] Flujo NI y flujo regular completos — pruebas automatizadas en verde; smoke manual pendiente.
  - [ ] Auditoría de intenciones NI históricas con `ni_inscripcion_id` nulo — pendiente por falta de acceso a la base.
  - [x] No se modificaron rutas, filtros, pasarelas, montos ni esquema.

## Desviaciones del plan

- Se agregó el tipo de pago `1` (`_de`) al fixture de `IntencionesPagoModelNiTest` para que el detalle regular con `AdMovID` participe en el `INNER JOIN` con `pg_tipos_pagos` que usa `getPagosPorCedulaConDetalle()`. Es un ajuste de prueba, no de producción.
- No se modificó `PaymentOrchestrator` ni `Pagos::CancelarPago()`: quedan cubiertos por el filtro del modelo y `validarPropietario()`, respectivamente, tal como preveía el plan.
- No se creó una prueba HTTP de controladores porque dependen de sesión CI4, `BaseController`, conexión por sucursal y vistas; el plan ya preveía verificación manual para esos puntos.

## Riesgos y pendientes

- **Verificación manual pendiente:** falta comprobar en desarrollo que `/Pagos`, `validarPropietario`, `retirarDetalle`, `Reportes::Recibo` y el cierre de vencidos se comportan como espera el plan con una sesión real.
- **Datos históricos:** la migración `099` no hizo backfill. Si existen intenciones NI previas con `ni_inscripcion_id` nulo, este cambio no las aislará. Hay que ejecutar la consulta de auditoría del plan y tratar los datos aparte.
- **Controladores legacy:** `Pagos_r`, `Pagos_old` y `Pagos_old2` no se modificaron. Si alguna ruta los expone, requieren análisis separado.
- **Cierre de vencidos:** sigue haciendo borrado físico de detalles; no se cambió a borrado lógico en este bugfix.
- **Rama local:** no se hizo `commit`, `push`, merge ni pull request. Los cambios quedan en el árbol de trabajo de la rama `p-bugfix/aislamiento-pagos-regulares-nuevo-ingreso`.

## Consolidación

- **Estado:** consolidado
- **Fecha:** 2026-10-28
- **Rama destino:** feature/desacoplar-contructor-pagos
- **Rama prototipo:** p-bugfix/aislamiento-pagos-regulares-nuevo-ingreso (eliminada)
- **Estrategia:** merge --no-ff
- **Commit de merge:** fbb344e
- **Verificación:** la rama prototipo quedó como ancestro de la rama destino, sin commits pendientes y sin diferencias de archivos.
- **Nota:** este registro conserva el historial de ejecución anterior. La verificación manual del plan continúa pendiente y no queda sustituida por la consolidación.
