# Prototipo de ejecución — FEAT-003 Dominio del pago de nuevo ingreso

- **Rama:** p-feature/dominio-pago-nuevo-ingreso
- **Rama base:** feature/desacoplar-contructor-pagos
- **Plan:** docs/features/003-dominio-pago-nuevo-ingreso/plan.md
- **Fecha:** 2026-10-28
- **Estado:** consolidado

## Resumen

Se implementó el dominio de pago de nuevo ingreso alineado a la solución de referencia del respaldo. El servicio resuelve los planes de la sede para `periodo_ni`, calcula el monto en el servidor, crea o reutiliza una intención vinculada a `ni_inscripciones`, controla los estados, cancela con borrado lógico de detalles y expone los métodos de pago permitidos sin `saldofavor`. `IntencionesPagoModel` incorpora `ni_inscripcion_id`, `ProceNi()` y `cancelarIntencion()`. No se agregaron UI, rutas ni controladores.

## Tareas realizadas

- [x] Crear `NuevoIngresoPagoService` con inyección de modelos, conexión, resolver de sede, reloj y `PaymentService`.
- [x] Crear `NuevoIngresoPagoException` con fábricas de error en español.
- [x] Crear los contratos mínimos del servicio, resolver de conexión de sede y reloj.
- [x] Implementar `listarPlanes()` con lectura directa de `ni_plan_pago_id` y `periodo_ni`, filtrado de planes inválidos y cálculo server-side.
- [x] Implementar `crearIntencion()` idempotente: devuelve aprobadas, reutiliza activas y crea en estado `2 Pagando`.
- [x] Implementar transiciones `1→2`, `2→3`, `2→7` y `7→8`.
- [x] Implementar `cancelar()` solo para estados `1`/`2`, con estado `5` y `borrado_dt` en detalles.
- [x] Implementar `formasPagoDisponibles()`, `esFormaPagoPermitida()` y `descuentoDolarNuevoIngreso()`.
- [x] Agregar `ni_inscripcion_id` a `IntencionesPagoModel::$allowedFields`.
- [x] Agregar `ProceNi()` y la detección `NiInscripcionID` en `validarDetallesPago()`.
- [x] Agregar `cancelarIntencion()` con borrado lógico de detalles.
- [x] Registrar `Services::nuevoIngresoPago()` como instancia compartida.
- [x] Crear pruebas del servicio y del modelo con SQLite.
- [x] Ejecutar pruebas, `php -l` y `graphify update .`.
- [x] Retirar DTOs y repositorios intermedios que no eran necesarios tras alinear la semántica con el respaldo.

## Criterios de aceptación

| Criterio | Cómo se verificó | Resultado |
| --- | --- | --- |
| Servicio con inyección de modelos, conexión, resolver de sede, reloj y `PaymentService` | Revisión de constructor y prueba `testServicioCompartidoEnServices` | ok |
| Planes filtrados por `periodo_ni`, ignorando IDs inválidos o con `ref_dolar <= 0` | `testListaPlanesDelPeriodoConMonto` | ok |
| Monto `round(ref_dolar * tasa + costo_seguro, 2)` sin `PoDetPlan` ni cuotas | `testListaPlanesDelPeriodoConMonto` y `testCalculaMontoYRedondea` | ok |
| Selección del primer plan por defecto y validación del `planId` | `testCreaIntencionConPrimerPlanPorDefecto`, `testPlanSeleccionadoYReutilizacionSinDuplicar` y `testRechazaPlanSeleccionadoNoValido` | ok |
| Intención creada en estado `2`, `formas_pago_id = 0` y JSON `NiInscripcionID` | `testCreaIntencionConPrimerPlanPorDefecto` | ok |
| Reutilización de intención activa sin duplicar | `testPlanSeleccionadoYReutilizacionSinDuplicar` | ok |
| Devolución de intención aprobada existente | `testDevuelveIntencionAprobadaSinCrearOtra` | ok |
| Transiciones de estado | `testIniciarPagoDesdeEstadoCreado`, `testTransicionesDeZelle` y `testApruebaPagoNoZelle` | ok |
| Cancelación lógica de detalles y bloqueo de recancelación | `testCancelaYHaceBorradoLogicoDeDetalles` y `IntencionesPagoModelNiTest` | ok |
| Formas activas sin `saldofavor` ni códigos no soportados | `testFormasDisponiblesExcluyenSaldoFavorYNoSoportadas` | ok |
| Descuento Zelle expuesto sin alterar el monto persistido | `testDescuentoDolarNuevoIngreso` | ok |
| `ProceNi()` valida `NiInscripcionID`, postulación y cabecera | `IntencionesPagoModelNiTest` | ok |
| `ProceNi()` no exige estado específico y es idempotente | `testAceptaDetalleVinculadoEnEstadoPagando`, `testAceptaDetalleVinculadoAprobadoYVerificado` y `testEsIdempotente` | ok |
| No se modificaron rutas, filtros, controladores, vistas, migraciones, seeds ni pasarelas | `git status` y revisión de alcance | ok |
| Pruebas del área y `php -l` | Comandos de la sección de verificación | ok |

## Flujos cubiertos

- **Flujo normal:** el servicio resuelve la postulación y la sede, lee `ni_plan_pago_id`/`periodo_ni`, valida la tasa y el seguro, calcula el monto, devuelve la intención aprobada o activa, o crea una nueva en estado `2` con detalle `_ni`.
- **Flujos alternativos:** varios planes válidos con selección explícita o primer plan por defecto; reutilización de intención activa; devolución de intención aprobada; reintento después de cancelar; descuento Zelle expuesto para la pasarela.
- **Control de errores:** postulación inexistente, relación carrera/sede inexistente, plan no configurado, periodo no configurado, plan inválido, tasa no disponible, monto inválido, intención ajena, transición inválida, cancelación no permitida y fallo de persistencia.

## Archivos creados

| Archivo | Motivo |
| --- | --- |
| `app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoService.php` | Dominio de planes, monto, intención, estados, métodos y cancelación |
| `app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoException.php` | Excepciones de dominio |
| `app/Libraries/Inscripciones/NuevoIngreso/Pago/Contracts/NuevoIngresoPagoServiceInterface.php` | Contrato público del servicio |
| `app/Libraries/Inscripciones/NuevoIngreso/Pago/Contracts/ConexionSedeResolverInterface.php` | Contrato del resolver de conexión de sede |
| `app/Libraries/Inscripciones/NuevoIngreso/Pago/Contracts/RelojInterface.php` | Contrato del reloj |
| `app/Libraries/Inscripciones/NuevoIngreso/Pago/Repositories/ConexionSedeResolver.php` | Resolución de la conexión de la sede |
| `app/Libraries/Inscripciones/NuevoIngreso/Pago/Support/RelojSistema.php` | Reloj por defecto |
| `tests/app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoServiceTest.php` | Pruebas del servicio con SQLite |
| `tests/app/Models/PagosOnline/IntencionesPagoModelNiTest.php` | Pruebas de `ProceNi()`, `cancelarIntencion()` y detalles `_ni` |

## Archivos modificados

| Archivo | Cambio realizado |
| --- | --- |
| `app/Config/Services.php` | Registro de `Services::nuevoIngresoPago()` con modelos, conexión, resolver de sede, reloj y `PaymentService` |
| `app/Models/PagosOnline/IntencionesPagoModel.php` | `ni_inscripcion_id` en `$allowedFields`; `ProceNi()`; `cancelarIntencion()`; filtro de detalles borrados y detección `NiInscripcionID` |
| `docs/features/003-dominio-pago-nuevo-ingreso/plan.md` | Plan alineado al respaldo y marcado como completado |
| `docs/features/003-dominio-pago-nuevo-ingreso/prototipo.md` | Este documento |

## Rutas, permisos y datos

- **Rutas/endpoints nuevos o modificados:** no aplica. La feature no agrega rutas ni controladores.
- **Permisos y validaciones:** el servicio recibe `ni_inscripcion_id` desde el contexto de nuevo ingreso y valida propiedad en `obtenerIntencion()`, transiciones y cancelación comparando `pg_intenciones_pago.ni_inscripcion_id`. No lee la sesión ni acepta una sede enviada por el cliente.
- **Migraciones/seeds:** no aplica. No se crearon ni ejecutaron migraciones o seeds.
- **Compatibilidad:** el detalle `_ni` usa el JSON del respaldo (`NiInscripcionID`, `PlanPagoPerioID`, `PeriodoID`, `Tasa`, `RefDolar`, `Seguro`). `ProceNi()` es compatible con ese formato y no exige estado específico. No se modificaron los flujos regulares de pago ni las pasarelas.

## Comandos ejecutados

| Comando | Resultado |
| --- | --- |
| `git rev-parse --is-inside-work-tree` | `true` |
| `git switch -c p-feature/dominio-pago-nuevo-ingreso` | Rama local creada y activa |
| `vendor\bin\phpunit.bat tests\app\Integration\Paso3NuevoIngresoTest.php` | OK, 37 tests, 96 assertions |
| `vendor\bin\phpunit.bat tests\app\Libraries\Payments` | OK, 18 tests, 67 assertions |
| `vendor\bin\phpunit.bat tests\app\Libraries\Inscripciones\NuevoIngreso\Pago\NuevoIngresoPagoServiceTest.php` | OK, 15 tests, 50 assertions |
| `vendor\bin\phpunit.bat tests\app\Models\PagosOnline\IntencionesPagoModelNiTest.php` | OK, 8 tests, 20 assertions |
| `php -l` sobre 11 archivos PHP nuevos/modificados | 0 errores |
| `graphify update .` | Grafo actualizado: 13.353 nodos y 27.160 aristas |

## Verificación

- **Línea base (antes):** `Paso3NuevoIngresoTest` en verde con 37 tests y 96 assertions. La suite de `tests/app/Libraries/Payments` se ejecutó al cierre y quedó en verde con 18 tests y 67 assertions.
- **Prueba manual (flujo normal):** no aplica smoke manual con base real porque la feature es de dominio, no agrega UI ni rutas y no se dispuso de una sede autorizada. El flujo se cubrió con SQLite en las pruebas del servicio.
- **Flujos alternativos y errores:** cubiertos por las pruebas del servicio y del modelo: selección de plan, reutilización de intención, intención aprobada, cancelación, transiciones, formas no permitidas, postulación inexistente, periodo inválido, tasa inválida y `ProceNi` con identificadores que no coinciden.
- **Pruebas automatizadas:** 15 tests/50 assertions del servicio y 8 tests/20 assertions del modelo; además, 37/96 de `Paso3NuevoIngresoTest` y 18/67 de `tests/app/Libraries/Payments`.
- **Criterios del plan:** todos los criterios de finalización quedaron marcados como cumplidos en `plan.md`.

## Desviaciones del plan

- Se retiraron los DTOs y los repositorios intermedios (`PlanPagoRepository`, `IntencionPagoRepository` y sus contratos) porque no eran necesarios tras alinear la semántica con el respaldo. El servicio recibe directamente modelos, conexión, resolver de sede, reloj y `PaymentService`, y devuelve arreglos.
- La cancelación mantiene la cabecera con `borrado_dt` nulo y estado `5`, y hace borrado lógico solo de los detalles, igual que el respaldo. El plan se actualizó para reflejarlo.

## Riesgos y pendientes

- No se ejecutó un smoke test contra una base MySQL real ni una pasarela en sandbox. Las pruebas usan SQLite y no cubren diferencias de driver, bloqueos ni datos reales.
- `ProceNi()` no exige estado `3`/`8`, en línea con el respaldo. Si se requiere mayor endurecimiento, debe evaluarse en una tarea separada.
- La intención se crea con `formas_pago_id = 0`; la forma se elige al preparar la pasarela. Si se necesita persistir el método al crear, habría que ampliar el contrato.
- Existe una posible condición de carrera al crear intenciones concurrentes para la misma postulación. No se agregó un índice único ni bloqueo específico; queda como deuda técnica.

## Consolidación

- **Fecha:** 2026-10-28
- **Rama destino:** `feature/desacoplar-contructor-pagos`
- **Estrategia:** `git merge --no-ff`
- **Commit de merge:** `b86d64f`
- **Rama prototipo eliminada:** sí, con `git branch -d` tras verificar el traslado.
- **Verificación:** sin commits pendientes ni diferencias de archivos entre ramas; 78 pruebas y 233 aserciones en verde; `php -l` sin errores.
