﻿# Dominio del pago de nuevo ingreso (`NuevoIngresoPagoService`)

- **CÃ³digo:** FEAT-003
- **Tipo:** feature
- **Estado:** completado
- **Fecha:** 2026-10-28
- **Autor:** opencode (agente)

## Objetivo

Crear el dominio de pago de nuevo ingreso: resolver los planes configurados por sede para el periodo de nuevo ingreso, calcular el monto en el servidor, crear o reutilizar una intenciÃ³n de pago idempotente, controlar los estados permitidos y cancelar de forma lÃ³gica. La integraciÃ³n se completa con `ni_inscripcion_id` en `IntencionesPagoModel` y con `ProceNi`, que valida el detalle de nuevo ingreso al procesar el pago. No incluye interfaz, rutas, controladores ni pasarelas nuevas.

## Alcance

- Incluye:
  - `NuevoIngresoPagoService` en `App\Libraries\Inscripciones\NuevoIngreso\Pago`.
  - Contratos mÃ­nimos (interfaz del servicio, resolver de conexiÃ³n de sede y reloj) e inyecciÃ³n de modelos, conexiÃ³n y reloj.
  - `NuevoIngresoPagoException` con fÃ¡bricas estÃ¡ticas y mensajes en espaÃ±ol.
  - Lectura directa de `ni_plan_pago_id` y `periodo_ni` desde `gb_config` de la sede, sin pasar por `OfertaAcademicaService`.
  - CÃ¡lculo server-side del monto con la fÃ³rmula del respaldo: `round(ref_dolar * tasa + costo_seguro, 2)`.
  - Formas de pago activas del catÃ¡logo, soportadas por `PaymentService`, excluyendo `saldofavor`.
  - IntenciÃ³n idempotente: una activa por `ni_inscripcion_id`; si ya existe una aprobada, se devuelve.
  - Estados: `2 Pagando` al crear, `1 Creado` para intenciones heredadas, `3 Aprobado`, `5 Cancelado`, `7 Sin verificar` y `8 Verificado`.
  - CancelaciÃ³n lÃ³gica: estado `5` en la cabecera y `borrado_dt` en sus detalles.
  - `ni_inscripcion_id` en `IntencionesPagoModel::$allowedFields`.
  - `ProceNi` privado en `IntencionesPagoModel`, invocado desde `validarDetallesPago()`.
  - `cancelarIntencion()` en `IntencionesPagoModel` con borrado lÃ³gico de detalles.
  - Registro de `Services::nuevoIngresoPago()`.
  - Pruebas unitarias/de integraciÃ³n del servicio y del modelo.
- No incluye:
  - Vistas, JavaScript, controladores, rutas, filtros, CSRF o UI del Paso 4.
  - Pasarelas nuevas o cambios internos en las clases de pago existentes.
  - Migraciones, seeds, cambios de esquema, `gb_config`, `ni_inscripciones` o datos reales.
  - CreaciÃ³n de la inscripciÃ³n en Orbis, sincronizaciÃ³n acadÃ©mica, GHL o recibos.
  - Estado `4 Rechazado`; su gestiÃ³n queda fuera del servicio.
  - Uso de `saldofavor` como mÃ©todo de pago de nuevo ingreso.
  - Pagos parciales, abonos, cuotas o aplicaciÃ³n de `PoDetPlan`; el pago es por el plan completo.
  - CÃ¡lculo del descuento Zelle dentro del servicio; el porcentaje se expone para que la pasarela lo aplique.
  - Lectura de `ni_plan_pago_id` desde `OfertaAcademicaService` o desde el controlador `Paso2`.

## Contexto y supuestos

- Este plan se alinea con la implementaciÃ³n de referencia que ya funcionaba en el respaldo `PORTAL-ESTUDIANTIL-V2 - copia`: `app/Libraries/Payments/NuevoIngresoPagoService.php`, sus contratos y `IntencionesPagoModel`.
- La rama de trabajo es `p-feature/dominio-pago-nuevo-ingreso`, creada desde `feature/desacoplar-contructor-pagos`.
- `pg_intenciones_pago` ya tiene `ni_inscripcion_id` por la migraciÃ³n `2026-10-27-000099`; el modelo ya lo declara en `$allowedFields`.
- `pg_intenciones_pago.identificacion` ya es `VARCHAR(20)` por la migraciÃ³n `2026-10-27-000100`.
- `pg_tipos_pagos` tiene `id = 3`, `codigo = '_ni'`; `pg_formas_pago`, `pg_estados`, `ceplanpagoperio` y `ceplanpagoperiodet` estÃ¡n sembrados por los seeders existentes.
- `ni_plan_pago_id` es una configuraciÃ³n local de sede (`gb_config` de la conexiÃ³n de la sede) con formato de IDs numÃ©ricos separados por coma, por ejemplo `900002,900003`.
- `periodo_ni` es una configuraciÃ³n local de sede; los planes configurados deben pertenecer a ese `CePerioLectID`. Los IDs invÃ¡lidos, de otro periodo o con `ref_dolar <= 0` se ignoran con advertencia.
- `costo_seguro` se lee de `gb_config` de la base principal y se normaliza a `0` si falta, no es numÃ©rico o es negativo.
- `desc_pg_dolar_ni` es un porcentaje (`0` a `100`) y se expone mediante `descuentoDolarNuevoIngreso()`; no se resta del monto base del servicio. La pasarela Zelle lo aplica al convertir a dÃ³lares.
- El monto se calcula una sola vez al crear la intenciÃ³n y se persiste en bolÃ­vares (`monto_total` y `monto` del detalle).
- La Ãºltima tasa se toma de `pg_tasa_dia` de la sede por `fecha` descendente y luego `id` descendente. Si la Ãºltima tasa es `0` o no existe, es un error de configuraciÃ³n.
- El detalle de nuevo ingreso usa el JSON del respaldo: `NiInscripcionID`, `PlanPagoPerioID`, `PeriodoID`, `Tasa`, `RefDolar` y `Seguro`.
- La intenciÃ³n se crea en estado `2 Pagando`, con `formas_pago_id = 0`. La forma de pago se elige despuÃ©s, al preparar la pasarela.
- Las formas de pago se leen del catÃ¡logo activo (`pg_formas_pago`) agrupadas por `po` y `rp`; se excluye `saldofavor` y cualquier cÃ³digo no soportado por `PaymentService`.
- `ProceNi()` no exige un estado especÃ­fico de la intenciÃ³n: valida que el detalle tenga `NiInscripcionID`, que la postulaciÃ³n exista y que coincida con `pg_intenciones_pago.ni_inscripcion_id`. No escribe datos acadÃ©micos.
- La estructura de clases se alinea al respaldo: el servicio recibe modelos, conexiÃ³n, resolver de sede, reloj y `PaymentService`; no se usan DTOs ni repositorios intermedios. La semÃ¡ntica de planes, monto, estados, JSON y `ProceNi` se alinea al respaldo.
- `MEMORY.md` no existe en este checkout; no se crea en esta feature.
- El cÃ³digo `FEAT-003` no colisiona: `docs/features` solo contiene `001` y `002`.

## Flujo normal

1. Paso 1: El futuro consumidor obtiene `ni_inscripcion_id` desde la sesiÃ³n `nuevo_ingreso` o desde el registro de postulaciÃ³n; nunca desde un parÃ¡metro libre del cliente.
2. Paso 2: Llama a `Services::nuevoIngresoPago()->listarPlanes($niInscripcionId)` para conocer los planes y montos, o directamente a `crearIntencion($niInscripcionId, $planId)`.
3. Paso 3: El servicio carga la postulaciÃ³n en la base principal con `NiInscripcionModel`. Si no existe, lanza `NuevoIngresoPagoException::porInscripcionNoEncontrada()`.
4. Paso 4: Resuelve `sucursal_id` desde `es_sucursales_carreras` en la base principal usando `ni_inscripciones.sucursal_carrera_id`. Si la relaciÃ³n no existe, lanza `porSucursalNoResuelta()`.
5. Paso 5: Obtiene la conexiÃ³n de la sede mediante el resolver inyectado y lee `gb_config.ni_plan_pago_id` y `gb_config.periodo_ni` directamente en esa conexiÃ³n. Si faltan o no son vÃ¡lidos, lanza `porPlanNoConfigurado()` o `porConfiguracionInvalida()`.
6. Paso 6: Carga `ceplanpagoperio` y `ceplanpagoperiodet` de la sede para los IDs configurados y el `periodo_ni`, ordenando los detalles por `SeDetPlan ASC`.
7. Paso 7: Descarta los planes inexistentes, de otro periodo o con `ref_dolar <= 0`, registrando una advertencia. Si no queda ningÃºn plan vÃ¡lido, lanza `porPlanNoEncontrado()`.
8. Paso 8: Obtiene la Ãºltima tasa de `pg_tasa_dia` de la sede. Si no existe o es menor o igual a `0`, lanza `porTasaNoDisponible()`.
9. Paso 9: Lee `costo_seguro` de la configuraciÃ³n principal y lo normaliza a `0` si falta, no es numÃ©rico o es negativo.
10. Paso 10: Calcula el monto de cada plan como `round((ref_dolar * tasa) + costo_seguro, 2)`. No aplica `PoDetPlan` ni descuento de Zelle en este cÃ¡lculo.
11. Paso 11: Si el consumidor no indica `planId`, selecciona el primer plan vÃ¡lido. Si indica uno, lo valida contra la lista de planes vÃ¡lidos; si no pertenece, lanza `porPlanNoEncontrado()`.
12. Paso 12: Busca una intenciÃ³n aprobada (`3` u `8`) de la postulaciÃ³n. Si existe, la devuelve sin crear otra.
13. Paso 13: Busca una intenciÃ³n activa (`1`, `2` o `7`). Si existe:
    - En estado `1`, la actualiza a `2 Pagando` y la devuelve.
    - En estado `2` o `7`, la devuelve sin cambios.
14. Paso 14: Si no existe intenciÃ³n, abre una transacciÃ³n, inserta la cabecera en `pg_intenciones_pago` con estado `2`, `formas_pago_id = 0`, `ni_inscripcion_id`, identificaciÃ³n del aspirante, `AASUCURSID`, fecha y monto total; inserta el detalle `_ni` con el JSON del respaldo; confirma la transacciÃ³n.
15. Paso 15: Devuelve un arreglo con la intenciÃ³n, sus detalles, el estado, el plan, el periodo, el monto y el JSON de snapshot.
16. Paso 16: El consumidor consulta `formasPagoDisponibles()` para mostrar los mÃ©todos activos permitidos. `saldofavor` no aparece.
17. Paso 17: Al preparar la pasarela, el consumidor puede usar `descuentoDolarNuevoIngreso()` para que Zelle aplique el porcentaje al convertir a dÃ³lares. El servicio no modifica el monto persistido.
18. Paso 18: Para un pago no Zelle, el consumidor llama a `iniciarPago($intencionId, $niId)` (idempotente) y, al confirmar la pasarela, a `aprobarPago($intencionId, $niId)` para pasar de `2` a `3`.
19. Paso 19: Para Zelle, el consumidor llama a `reportarPagoZelle($intencionId, $niId)` para pasar de `2` a `7`; cuando el comprobante se verifica manualmente llama a `verificarPagoZelle($intencionId, $niId)` para pasar de `7` a `8`. El estado `8` es el estado final aprobado de Zelle y no cambia mÃ¡s.
20. Paso 20: El consumidor puede cancelar una intenciÃ³n en estado `1` o `2` con `cancelar($intencionId, $niId)`: pasa a estado `5` y hace borrado lÃ³gico de la cabecera y de sus detalles con el reloj inyectado.
21. Paso 21: Al procesar el pago, `IntencionesPagoModel::validarDetallesPago()` detecta el detalle por `NiInscripcionID` y llama a `ProceNi()`; si la postulaciÃ³n existe y coincide con la cabecera, devuelve `true` sin escribir datos acadÃ©micos.

## Flujos alternativos / variantes

### Varios planes vÃ¡lidos

1. Paso 1: `ni_plan_pago_id` contiene dos IDs y ambos existen en `periodo_ni` con `ref_dolar > 0`.
2. Paso 2: `listarPlanes()` devuelve los dos planes con su monto.
3. Paso 3: El consumidor muestra el selector; si no envÃ­a `planId`, el servicio usa el primero.
4. Paso 4: Si envÃ­a un `planId` que no estÃ¡ en la lista vÃ¡lida, se rechaza con `porPlanNoEncontrado()`.
5. Paso 5: El plan seleccionado se persiste en el JSON del detalle como `PlanPagoPerioID`.

### IntenciÃ³n aprobada existente

1. Paso 1: La postulaciÃ³n ya tiene una intenciÃ³n en estado `3` u `8`.
2. Paso 2: El consumidor vuelve a solicitar `crearIntencion()`.
3. Paso 3: El servicio devuelve la intenciÃ³n aprobada sin crear otra ni cambiar el plan.
4. Paso 4: `pg_intenciones_pago` conserva una sola intenciÃ³n aprobada para la postulaciÃ³n.

### IntenciÃ³n activa existente

1. Paso 1: La postulaciÃ³n tiene una intenciÃ³n en estado `1`, `2` o `7`.
2. Paso 2: El consumidor vuelve a solicitar `crearIntencion()`.
3. Paso 3: El servicio devuelve la misma intenciÃ³n. Si estaba en `1`, la pasa a `2`.
4. Paso 4: No se crea un segundo detalle ni se modifica el plan ya persistido.

### Reintento despuÃ©s de cancelar

1. Paso 1: La intenciÃ³n anterior estÃ¡ en estado `5` y sus detalles tienen `borrado_dt`.
2. Paso 2: El consumidor solicita una nueva intenciÃ³n.
3. Paso 3: La bÃºsqueda de activas y aprobadas no encuentra la cancelada.
4. Paso 4: El servicio crea una nueva intenciÃ³n con el plan seleccionado.

### Descuento Zelle

1. Paso 1: El consumidor consulta `descuentoDolarNuevoIngreso()`.
2. Paso 2: Obtiene el porcentaje de `desc_pg_dolar_ni`, normalizado a `0` si falta o no es vÃ¡lido.
3. Paso 3: La pasarela Zelle aplica el descuento al convertir el monto en bolÃ­vares a dÃ³lares.
4. Paso 4: El monto persistido en la intenciÃ³n no cambia.

## Flujos de control de errores

| Error / condiciÃ³n | DetecciÃ³n | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| La postulaciÃ³n no existe en la base principal | `NiInscripcionModel::find()` devuelve nulo | Lanza `NuevoIngresoPagoException::porInscripcionNoEncontrada()`; no escribe | Sin intenciÃ³n |
| La relaciÃ³n `es_sucursales_carreras` no existe | Consulta por `sucursal_carrera_id` sin fila | Lanza `porSucursalNoResuelta()`; no escribe | Sin intenciÃ³n |
| `gb_config.ni_plan_pago_id` falta, estÃ¡ vacÃ­o o no tiene IDs numÃ©ricos | Lectura y parseo en la sede | Lanza `porPlanNoConfigurado()`; no escribe | Sin intenciÃ³n |
| `gb_config.periodo_ni` falta o no es numÃ©rico | Lectura en la sede | Lanza `porConfiguracionInvalida()` | Sin intenciÃ³n |
| Un ID de plan no existe, es de otro periodo o tiene `ref_dolar <= 0` | Consulta y validaciÃ³n | Se omite con advertencia; si no queda ninguno vÃ¡lido, lanza `porPlanNoEncontrado()` | Sin intenciÃ³n |
| El `planId` solicitado no estÃ¡ entre los planes vÃ¡lidos | ComparaciÃ³n con la lista | Lanza `porPlanNoEncontrado()` | Sin intenciÃ³n |
| No hay tasa vÃ¡lida en `pg_tasa_dia` | Ãšltima tasa ausente o `<= 0` | Lanza `porTasaNoDisponible()`; no escribe | Sin intenciÃ³n |
| `costo_seguro` falta, no es numÃ©rico o es negativo | Lectura de configuraciÃ³n | Se normaliza a `0` sin bloquear | CÃ¡lculo continÃºa |
| `desc_pg_dolar_ni` falta o no es numÃ©rico | Lectura de configuraciÃ³n | Se normaliza a `0`; no bloquea la creaciÃ³n | CÃ¡lculo continÃºa |
| El monto calculado es menor o igual a `0` | CÃ¡lculo del monto | Lanza `porMontoInvalido()` | Sin intenciÃ³n |
| Existe una intenciÃ³n aprobada | BÃºsqueda por `ni_inscripcion_id` y estados `3, 8` | Devuelve la intenciÃ³n existente sin escribir | IntenciÃ³n aprobada conservada |
| Existe una intenciÃ³n activa | BÃºsqueda por `ni_inscripcion_id` y estados `1, 2, 7` | Devuelve la misma; si estÃ¡ en `1`, la pasa a `2` | Una sola intenciÃ³n activa |
| Se intenta una transiciÃ³n no permitida | ValidaciÃ³n de estado origen/destino | Lanza `porTransicionInvalida()`; no escribe | Estado anterior conservado |
| La intenciÃ³n no pertenece a la postulaciÃ³n | ComparaciÃ³n de `ni_inscripcion_id` | Lanza `porIntencionNoEncontrada()` | Sin cambios |
| Se intenta cancelar una intenciÃ³n en estado distinto de `1` o `2` | ValidaciÃ³n de estado | Devuelve `false`; no escribe | Estado anterior conservado |
| Fallo de base de datos al insertar cabecera o detalle | ExcepciÃ³n dentro de la transacciÃ³n | Rollback completo y `porErrorPersistencia()` | Sin intenciÃ³n parcial |
| `ProceNi` recibe un detalle sin `NiInscripcionID` | ValidaciÃ³n del JSON | Devuelve `false`; el detalle se reporta como error de nuevo ingreso | IntenciÃ³n sin cambios |
| `ProceNi` no encuentra la postulaciÃ³n | Consulta a `ni_inscripciones` | Devuelve `false`; no escribe | IntenciÃ³n sin cambios |
| `ProceNi` no encuentra la intenciÃ³n o el `ni_inscripcion_id` no coincide | Consulta y comparaciÃ³n | Devuelve `false`; no escribe | IntenciÃ³n sin cambios |
| `validarDetallesPago()` obtiene `false` de `ProceNi` | Resultado del mÃ©todo | Agrega un error de tipo `nuevo_ingreso` a `errores` y devuelve `ok = false` | IntenciÃ³n sin cambios acadÃ©micos |

## Reglas de negocio y validaciones

- La identidad de la postulaciÃ³n se recibe como `ni_inscripcion_id` desde el contexto de nuevo ingreso. El servicio no lee la sesiÃ³n ni acepta una sede enviada por el cliente.
- La sede se resuelve en la base principal: `ni_inscripciones.sucursal_carrera_id` â†’ `es_sucursales_carreras.sucursal_id`. La conexiÃ³n de la sede se obtiene con el resolver inyectado, no con `default`.
- Los planes se leen de `gb_config.ni_plan_pago_id` y el periodo de `gb_config.periodo_ni`, ambos en la conexiÃ³n de la sede. No se usa `OfertaAcademicaService` para `ni_plan_pago_id`.
- El formato de `ni_plan_pago_id` es una lista de IDs numÃ©ricos separados por coma; se ignoran entradas vacÃ­as, no numÃ©ricas, cero o negativas y se eliminan duplicados.
- Cada plan se valida contra `periodo_ni` y `ref_dolar > 0`. Los planes invÃ¡lidos se omiten con `log_message('warning', ...)` sin datos personales.
- Si hay un solo plan vÃ¡lido se usa automÃ¡ticamente. Si hay varios, el consumidor puede indicar `planId`; sin selecciÃ³n se usa el primero.
- La fÃ³rmula del monto es `round((ref_dolar * tasa) + costo_seguro, 2)`. No se usa `PoDetPlan`, `MnInscripcion` ni cuotas.
- `costo_seguro` se normaliza a `0` si falta, no es numÃ©rico o es negativo. `desc_pg_dolar_ni` se normaliza a `0` si falta o no es numÃ©rico y se expone con `descuentoDolarNuevoIngreso()`; no se resta del monto base.
- El monto se calcula una sola vez al crear la intenciÃ³n y se persiste. La pasarela recibe el monto persistido, nunca el del cliente.
- La intenciÃ³n se crea en estado `2 Pagando`, con `formas_pago_id = 0`, `monto_pagado = 0`, `referencia` y `data_respuesta` nulas, `fecha` del reloj inyectado y `AASUCURSID` de la sede resuelta.
- El detalle se crea con `tipo_pago_id = 3` (`_ni`), `descripcion` del plan y `datos` JSON con `NiInscripcionID`, `PlanPagoPerioID`, `PeriodoID`, `Tasa`, `RefDolar` y `Seguro`. No se usa `saldofavor` ni se crean detalles de deuda o inscripciÃ³n regular.
- Formas de pago disponibles: las activas de `pg_formas_pago` agrupadas por `po` y `rp`, filtradas por `PaymentService::soporta()` y excluyendo `saldofavor`.
- Transiciones permitidas:
  - `1 â†’ 2` con `iniciarPago()` para intenciones heredadas; si ya estÃ¡ en `2`, devuelve la misma.
  - `2 â†’ 3` con `aprobarPago()` para mÃ©todos distintos de Zelle.
  - `2 â†’ 7` con `reportarPagoZelle()`.
  - `7 â†’ 8` con `verificarPagoZelle()`; `8` es final y no cambia mÃ¡s.
  - `1` o `2` â†’ `5` con `cancelar()`, escribiendo `borrado_dt` en los detalles.
- El estado `4 Rechazado` no lo gestiona este servicio. Cualquier intento de usarlo como destino lanza `porTransicionInvalida()`.
- Idempotencia: se considera activa toda intenciÃ³n con `estados_id IN (1, 2, 7)` y `borrado_dt IS NULL`; se considera aprobada toda intenciÃ³n con `estados_id IN (3, 8)` y `borrado_dt IS NULL`. Solo puede existir una intenciÃ³n activa por `ni_inscripcion_id`.
- Si existe una intenciÃ³n aprobada, se devuelve y no se permite cambiar de plan. Si existe una activa, se devuelve la misma y no se modifica el plan persistido.
- La cancelaciÃ³n es lÃ³gica: la cabecera pasa a `estados_id = 5` y conserva su `borrado_dt` nulo para auditorÃ­a; los detalles reciben `borrado_dt` para dejar de participar en consultas.
- `ProceNi()` vive en `IntencionesPagoModel` como mÃ©todo privado, con el mismo patrÃ³n de `ProceDeuda()` y `ProceInscr()`.
- `ProceNi()` exige:
  - Detalle de `pg_intenciones_pago_det` con `datos.NiInscripcionID` numÃ©rico mayor a `0`.
  - Cabecera `pg_intenciones_pago` existente y con `ni_inscripcion_id` igual al `NiInscripcionID` del detalle.
  - PostulaciÃ³n existente en `ni_inscripciones` (solo lectura).
  - No exige un estado especÃ­fico de la intenciÃ³n.
- `ProceNi()` no actualiza `ni_inscripciones`, no crea inscripciÃ³n en Orbis, no cambia `paso_actual`, `orbis_sincronizado` ni `ghl_sincronizado`. Devuelve `true` si todo coincide y `false` en caso contrario.
- `validarDetallesPago()` filtra los detalles con `borrado_dt` nulo y evalÃºa `AdMovID`, `CeEstudiInscID` y `NiInscripcionID` en ese orden. Si `ProceNi()` devuelve `false`, agrega un error con `tipo = 'nuevo_ingreso'` y mensaje `No se pudo validar el pago de nuevo ingreso.`.
- El servicio no expone datos tÃ©cnicos al usuario final. Los mensajes de la excepciÃ³n son en espaÃ±ol y los detalles internos se registran en `writable/logs` sin identificaciÃ³n, nombre, correo ni telÃ©fono.
- El reloj se inyecta como `RelojInterface::ahora(): DateTimeImmutable` y se usa para `fecha`, `borrado_dt` y logs. No se usa `date()` directamente en el servicio.
- La conexiÃ³n principal se inyecta como `BaseConnection`; la conexiÃ³n de sede se obtiene con un `ConexionSedeResolverInterface` inyectado. Las pruebas pueden sustituir ambos sin abrir bases reales.

## Contratos y diseÃ±o propuesto

| Componente | Responsabilidad |
| --- | --- |
| `Contracts\NuevoIngresoPagoServiceInterface` | Contrato pÃºblico: `listarPlanes`, `formasPagoDisponibles`, `esFormaPagoPermitida`, `descuentoDolarNuevoIngreso`, `crearIntencion`, `iniciarPago`, `reportarPagoZelle`, `verificarPagoZelle`, `aprobarPago`, `cancelar` y `obtenerIntencion`. |
| `Contracts\ConexionSedeResolverInterface` | Devuelve la `BaseConnection` de la sede a partir de `sucursal_id`. |
| `Contracts\RelojInterface` | Devuelve `DateTimeImmutable` para fechas y snapshots. |
| `NuevoIngresoPagoException` | ExcepciÃ³n de dominio con fÃ¡bricas estÃ¡ticas y mensajes en espaÃ±ol. |
| `Repositories\ConexionSedeResolver` | ImplementaciÃ³n por defecto del resolver de conexiÃ³n de sede. |
| `Support\RelojSistema` | ImplementaciÃ³n por defecto del reloj. |

- El servicio concreto recibe en su constructor los modelos (`NiInscripcionModel`, `IntencionesPagoModel`, `FormasPagoModel`), la `BaseConnection` principal, el resolver de conexiÃ³n de sede, el reloj y `PaymentService`. No usa DTOs ni repositorios intermedios; devuelve arreglos.
- `Services::nuevoIngresoPago()` devuelve una instancia compartida, construida con los modelos y la conexiÃ³n principal, el resolver de sede y el reloj del sistema.
- El servicio no guarda estado mutable entre llamadas: la conexiÃ³n de sede, la tasa y el contexto se resuelven en cada invocaciÃ³n.

## Ãreas afectadas

| AcciÃ³n | Archivo / componente | Motivo |
| --- | --- | --- |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoService.php` | Servicio de dominio con planes, monto, intenciÃ³n, estados y cancelaciÃ³n |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoException.php` | ExcepciÃ³n de dominio y fÃ¡bricas estÃ¡ticas |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Pago/Contracts/NuevoIngresoPagoServiceInterface.php` | Interfaz del servicio |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Pago/Contracts/ConexionSedeResolverInterface.php` | Contrato del resolver de conexiÃ³n de sede |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Pago/Contracts/RelojInterface.php` | Contrato del reloj |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Pago/Repositories/ConexionSedeResolver.php` | ImplementaciÃ³n del resolver de sede |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Pago/Support/RelojSistema.php` | ImplementaciÃ³n del reloj |
| Modificar | `app/Config/Services.php` | Registrar `Services::nuevoIngresoPago()` como instancia compartida |
| Modificar | `app/Models/PagosOnline/IntencionesPagoModel.php` | `ni_inscripcion_id` en `$allowedFields`; `ProceNi()`, `cancelarIntencion()` y filtro de detalles borrados |
| Crear | `tests/app/Libraries/Inscripciones/NuevoIngreso/Pago/NuevoIngresoPagoServiceTest.php` | Cubrir planes, monto, idempotencia, estados, mÃ©todos y cancelaciÃ³n |
| Crear / modificar | `tests/app/Models/PagosOnline/IntencionesPagoModelNiTest.php` | Cubrir `ProceNi()`, `cancelarIntencion()` y `validarDetallesPago()` con `NiInscripcionID` |
| Documentar | `docs/features/003-dominio-pago-nuevo-ingreso/plan.md` | Este plan |

No se modifican `Routes.php`, `Filters.php`, controladores, vistas, JavaScript, `PaymentService`, `PaymentOrchestrator`, migraciones, seeds, `gb_config`, `ni_inscripciones` ni las pasarelas.

## Criterios de finalizaciÃ³n

- [x] Existe `NuevoIngresoPagoService` en `app/Libraries/Inscripciones/NuevoIngreso/Pago/` y cumple `NuevoIngresoPagoServiceInterface`.
- [x] Existe `NuevoIngresoPagoException` con fÃ¡bricas estÃ¡ticas para inscripciÃ³n, sucursal, planes, monto, tasa, configuraciÃ³n, mÃ©todo, intenciÃ³n, transiciÃ³n y persistencia; todos los mensajes estÃ¡n en espaÃ±ol.
- [x] El servicio recibe por constructor los modelos, la conexiÃ³n principal, el resolver de sede, el reloj y `PaymentService`, y devuelve arreglos en lugar de DTOs.
- [x] `Services::nuevoIngresoPago()` devuelve una instancia compartida y no conserva estado mutable entre llamadas.
- [x] `listarPlanes()` lee `ni_plan_pago_id` y `periodo_ni` directamente de `gb_config` de la sede, parsea IDs con coma, elimina duplicados, ignora entradas invÃ¡lidas y filtra planes por periodo y `ref_dolar > 0`.
- [x] `listarPlanes()` calcula el monto con `round((ref_dolar * tasa) + costo_seguro, 2)`, sin `PoDetPlan`, sin cuotas y sin descuento de Zelle.
- [x] `crearIntencion()` usa el primer plan vÃ¡lido cuando no se indica `planId` y rechaza un `planId` fuera de la lista configurada.
- [x] `crearIntencion()` devuelve la intenciÃ³n aprobada existente (`3`/`8`) sin crear otra.
- [x] `crearIntencion()` reutiliza la intenciÃ³n activa (`1`/`2`/`7`); si estÃ¡ en `1`, la pasa a `2`, y no modifica el plan ya persistido.
- [x] `crearIntencion()` inserta cabecera y detalle en una transacciÃ³n, con estado `2`, `formas_pago_id = 0`, `ni_inscripcion_id`, `monto_pagado = 0` y `AASUCURSID` de la sede.
- [x] El detalle usa `tipo_pago_id = 3` y el JSON `NiInscripcionID`, `PlanPagoPerioID`, `PeriodoID`, `Tasa`, `RefDolar` y `Seguro`.
- [x] Las transiciones `1 â†’ 2`, `2 â†’ 3`, `2 â†’ 7` y `7 â†’ 8` funcionan; `8` es final y las transiciones invÃ¡lidas lanzan excepciÃ³n.
- [x] `cancelar()` solo acepta intenciones en estado `1` o `2`, escribe `estados_id = 5` en la cabecera y `borrado_dt` en sus detalles, sin borrar fÃ­sicamente.
- [x] `formasPagoDisponibles()` lee las formas activas de `pg_formas_pago` por tipo `po`/`rp`, excluye `saldofavor` y descarta cÃ³digos no soportados por `PaymentService`.
- [x] `esFormaPagoPermitida()` devuelve `true` solo para las formas incluidas en `formasPagoDisponibles()`.
- [x] `descuentoDolarNuevoIngreso()` lee `desc_pg_dolar_ni`, normaliza a `0` si falta o no es vÃ¡lido y no altera el monto persistido.
- [x] `IntencionesPagoModel::$allowedFields` incluye `ni_inscripcion_id`.
- [x] `ProceNi()` es privado, se llama desde `validarDetallesPago()` para detalles con `NiInscripcionID` y devuelve `true` solo si el detalle, la cabecera, el `ni_inscripcion_id` y la postulaciÃ³n existen y coinciden.
- [x] `ProceNi()` no exige estado especÃ­fico, no escribe en `ni_inscripciones` ni en tablas acadÃ©micas y es idempotente en llamadas repetidas.
- [x] `cancelarIntencion()` verifica propiedad, solo cancela estados `1`/`2` y hace borrado lÃ³gico de los detalles.
- [x] `validarDetallesPago()` filtra detalles con `borrado_dt` nulo, evalÃºa `AdMovID`, `CeEstudiInscID` y `NiInscripcionID`, y agrega un error de tipo `nuevo_ingreso` cuando `ProceNi()` devuelve `false`.
- [x] Las pruebas del servicio cubren planes por periodo, monto, plan por defecto/seleccionado, idempotencia, estados, cancelaciÃ³n, formas de pago y errores de configuraciÃ³n.
- [x] Las pruebas del modelo cubren `ProceNi()` con `NiInscripcionID`, postulaciÃ³n inexistente, identificador que no coincide, idempotencia y cancelaciÃ³n lÃ³gica.
- [x] Las pruebas del Ã¡rea pasan con `vendor/bin/phpunit` sobre los archivos afectados; `Paso3NuevoIngresoTest` sigue pasando.
- [x] `php -l` no reporta errores en los archivos PHP nuevos o modificados.
- [x] No se modificaron rutas, filtros, controladores, vistas, JavaScript, migraciones, seeds, `gb_config`, `PaymentService`, `PaymentOrchestrator` ni pasarelas.
- [x] `graphify update .` se ejecutÃ³ despuÃ©s de los cambios de cÃ³digo.

## Preguntas abiertas

- `costo_seguro` y `desc_pg_dolar_ni` se leen de `gb_config` de la base principal, como en el respaldo. Â¿Se confirma que no se configurarÃ¡n por sede?
- La intenciÃ³n se crea con `formas_pago_id = 0` y la forma se elige al preparar la pasarela. Â¿Se confirma que no se requiere persistir el mÃ©todo al crear?
- `ProceNi()` no exige estado `3/8`; solo valida el vÃ­nculo con la postulaciÃ³n, igual que el respaldo. Â¿Se acepta ese comportamiento o debe endurecerse mÃ¡s adelante?
- Si existe una intenciÃ³n activa en `7` y el consumidor intenta cambiar de plan, el respaldo devuelve la intenciÃ³n existente sin cambios. Â¿Se confirma esa semÃ¡ntica?
- La cancelaciÃ³n se limita a estados `1` y `2`; una intenciÃ³n en `7` no puede cancelarse desde el servicio. Â¿Se confirma?
- La lista de planes no se persiste por carrera; se toma de la configuraciÃ³n de la sede. Â¿Se mantiene esa decisiÃ³n?

## BitÃ¡cora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-28 | CreaciÃ³n del plan FEAT-003 con alcance de servicio de dominio, contratos, excepciÃ³n, `ni_inscripcion_id` y `ProceNi`, sin UI ni rutas. | opencode (agente) |
| 2026-10-28 | Plan alineado con la implementaciÃ³n de referencia del respaldo: planes por `periodo_ni`, monto sin `PoDetPlan`, intenciÃ³n en estado `2`, JSON `NiInscripcionID`, `ProceNi` sin filtro de estado y cancelaciÃ³n lÃ³gica de detalles. | opencode (agente) |
| 2026-10-28 | Se retiraron DTOs y repositorios intermedios: el servicio recibe modelos, conexiÃ³n, resolver de sede, reloj y `PaymentService`, y devuelve arreglos como el respaldo. | opencode (agente) |
| 2026-10-28 | Implementación cerrada: servicio, excepción, contratos mínimos, resolver de sede, reloj, `ProceNi`, `cancelarIntencion`, registro en `Services` y pruebas. Automatizadas en verde; `php -l` sin errores y `graphify update` ejecutado. | opencode (agente) |

