# Recibo PDF de nuevo ingreso

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

## Objetivo

Permitir que el aspirante con una intención de pago propia en estado 3 u 8 descargue su recibo PDF desde el Paso 4. La generación se extrae a `NuevoIngresoReciboService` y reutiliza la misma construcción de PDF del recibo regular, sin duplicar la plantilla. El recibo muestra los datos del pago, la tasa y el descuento solo para Zelle, y el monto verificado con su desglose. En este corte no se muestra el plan.

## Alcance

- Incluye:
  - Extraer de `Reportes::Recibo` la construcción visual del PDF a `App\Libraries\Recibos\ReciboPdfBuilder`, conservando título, logo, márgenes, tabla, descripción, pie y nombre de archivo del recibo regular.
  - Refactorizar `Reportes::Recibo` para usar el builder compartido sin cambiar su contrato, sus validaciones, sus filas ni su PDF.
  - Mantener que `Reportes::Recibo` rechace intenciones de nuevo ingreso cuando se accede por la ruta regular.
  - Crear `NuevoIngresoReciboService` en `App\Libraries\Inscripciones\NuevoIngreso\Recibo`, con su excepción de dominio.
  - Exponer `Paso3::recibo($id)` solo por GET, con sesión `nuevo_ingreso`, `paso_actual >= 4`, intención propia y estado 3 u 8.
  - Agregar la ruta `GET inscripciones/nuevo-ingreso/paso-4/recibo/(:num)` con el filtro `nuevoIngresoAuth:4`.
  - Mostrar el botón "Descargar recibo" únicamente en el bloque de estado aprobado del Paso 4.
  - Registrar `Services::nuevoIngresoRecibo()` y permitir inyectar el builder en pruebas.
  - Cubrir con pruebas unitarias el builder y el servicio, y con pruebas de integración el controlador y la regresión del recibo regular.
- No incluye:
  - Mostrar el plan en el recibo. El detalle `_ni` ya guarda `PlanPagoPerioID`, pero su presentación queda como funcionalidad futura.
  - Recibo para intenciones en estados 1, 2, 4, 5 o 7.
  - Reutilizar `Reportes::Recibo` como punto de entrada para nuevo ingreso; su ruta sigue aislada.
  - Cambiar el diseño visual, el logo, los márgenes o el contenido del recibo regular.
  - Correo con recibo adjunto, GHL, Orbis, sincronización académica o cambios de `paso_actual`.
  - Descarga desde la página de intentos, el portal regular o la SPA administrativa.
  - Almacenar el PDF, generar un historial de descargas o reenviar recibos.
  - Migraciones, seeds, cambios de esquema, `gb_config`, `ni_inscripciones`, pasarelas o máquina de estados.
  - CSRF. El recibo es una ruta GET de solo lectura y no modifica datos.
  - Cambios en `vendor/`, `public/vendor/`, `system/` o `app/ThirdParty/`.

> **Decisión de alcance y cambio respecto de la petición inicial:** la petición original pedía "no reutilizar `Reportes::Recibo`". En la entrevista el usuario corrigió esa decisión: se reutiliza su generación extrayéndola a un builder compartido, sin duplicar el PDF. Para no romper el aislamiento, `Reportes::Recibo` sigue rechazando intenciones NI y el recibo NI solo se obtiene desde el Paso 4 con sesión `nuevo_ingreso`. Este cambio se registra en la tabla de decisiones.

## Contexto y supuestos

- La rama de trabajo es `feature/desacoplar-contructor-pagos`. El Paso 4 ya tiene estado, plan e intención (FEAT-004), métodos y pago en línea (FEAT-005), y verificación de Zelle con estado 8 (FEAT-006).
- `Reportes::Recibo` (`app/Controllers/Reportes.php:705`) es el recibo regular. Valida la sesión del estudiante, consulta `pg_intenciones_pago`, exige que la intención no tenga `ni_inscripcion_id` (`:735`), solo permite estados 3/8 (`:749`), arma las filas del recibo y genera el PDF con `App\Libraries\fpdf\Recibo` (`:847-894`). Su ruta es auto-ruteada y responde en línea con `Content-Type: application/pdf`.
- `pg_intenciones_pago` guarda `id`, `descripcion`, `identificacion`, `estados_id`, `formas_pago_id`, `monto_total`, `monto_pagado`, `data_respuesta`, `referencia`, `AASUCURSID`, `ni_inscripcion_id`, `fecha` y `borrado_dt`.
- `pg_zelle_reportes` guarda el reporte Zelle con `intencio_pago_id`, `monto` (total final en USD), `monto_bs` (equivalente en Bs), `monto_pagado` (monto verificado en USD), `excedente`, `tasa`, `descuento` (porcentaje), `total_sin_descuento`, `monto_descuento`, `nro_confirmacion`, `remitente`, `fecha_pago`, `comprobante` y `borrado_dt`. Las columnas de desglose existen desde FEAT-006.
- Al verificar un reporte Zelle, `ZelleReportManager` deja en `pg_intenciones_pago.data_respuesta` un JSON con `monto`, `monto_pagado`, `excedente`, `tasa`, `descuento`, `total_sin_descuento`, `monto_descuento`, `monto_bs`, `origen` y `ni_inscripcion_id`. Se usa como respaldo de reportes históricos.
- `ni_inscripciones` guarda `nombre`, `apellido`, `identificacion_tipo` (`0` = V, `1` = E), `identificacion_valor` y `correo`. La identidad del recibo sale de ahí, no de la sesión del portal regular ni de un parámetro del cliente.
- `NuevoIngresoPagoService::obtenerIntencion($id, $niId)` filtra por `ni_inscripcion_id` y `borrado_dt IS NULL`; una intención ajena se comporta como inexistente. `estaAprobada()` reconoce los estados 3 y 8.
- El descuento y la tasa del recibo Zelle salen de los datos persistidos al verificar. No se recalculan con `desc_pg_dolar_ni` ni con la tasa vigente, para no alterar el documento de un pago ya cerrado.
- El recibo regular no muestra el plan; el recibo NI tampoco lo mostrará en este corte.
- El logo se mantiene en `base_url('/assets/reportes/logo1.png')`, igual que el recibo regular.
- `Reportes::Recibo` usa `utf8_decode()` para el texto del PDF. El proyecto declara PHP 8.0; se conserva el mismo comportamiento para no introducir diferencias visuales.
- El método público `Paso3::recibo()` queda expuesto por auto-routing además de la ruta explícita. Por eso valida siempre sesión, paso, propiedad y estado dentro del método.
- Las pruebas de integración usan SQLite en archivo y dobles, como `Paso4PagoTest` y `ZelleNuevoIngresoTest`, porque el controlador resuelve la conexión de la sede.
- `MEMORY.md` y `docs/constitution.md` no existen en este checkout; no se crean en esta feature.
- El código `FEAT-007` no colisiona: `docs/features` contiene `FEAT-001` a `FEAT-006`. Se respeta el esquema del repositorio en lugar de `feature-000`.

## Fases internas de implementación

La feature se implementa en dos fases secuenciales. Cada fase cierra con `php -l`, pruebas del área y revisión antes de continuar.

1. **Fase A - Builder compartido y regresión del recibo regular:** crear `ReciboPdfBuilder`, mover el bloque de renderizado de `Reportes::Recibo`, adaptar el controlador regular para usarlo y verificar que el PDF regular no cambia. Esta fase es un refactor habilitante; si el equipo prefiere aislar el riesgo, puede ejecutarse como un cambio `refactor` previo sin alterar el resto de este plan.
2. **Fase B - Recibo de nuevo ingreso:** crear `NuevoIngresoReciboService` y su excepción, registrar el servicio, agregar `Paso3::recibo`, la ruta, el botón del estado aprobado y las pruebas de integración.

## Flujo normal

1. Paso 1: El aspirante con sesión `nuevo_ingreso`, `paso_actual >= 4` y una intención en estado 3 u 8 abre `GET /inscripciones/nuevo-ingreso/paso-4`. El filtro `nuevoIngresoAuth:4` valida la sesión y el paso.
2. Paso 2: `Paso3::index()` deriva el estado `aprobado` para 3 u 8 y renderiza el bloque de pago aprobado con monto y referencia.
3. Paso 3: El bloque aprobado muestra el botón "Descargar recibo" solo si `estado === 'aprobado'` y `intencionId > 0`. El enlace apunta a `GET /inscripciones/nuevo-ingreso/paso-4/recibo/{id}` y se abre en una pestaña nueva.
4. Paso 4: La petición entra por la ruta explícita `paso-4/recibo/(:num)` con `nuevoIngresoAuth:4`.
5. Paso 5: `Paso3::recibo()` comprueba que el método sea GET. Si no lo es, responde 405 con la página de mensaje y un enlace de retorno al Paso 4.
6. Paso 6: `Paso3::recibo()` ejecuta `sesionValida()` como defensa adicional al filtro y al auto-routing.
7. Paso 7: Valida que `$id` sea un entero positivo. Si no, responde 422 con el mensaje "La intención de pago es obligatoria." y enlace al Paso 4.
8. Paso 8: Resuelve el contexto con `Services::nuevoIngresoContext()->resolver()` y obtiene `ni_inscripcion_id` de la postulación. La identidad y la sede no se leen de la petición.
9. Paso 9: Llama a `Services::nuevoIngresoRecibo()->generar($id, $niId)`.
10. Paso 10: `NuevoIngresoReciboService` obtiene la intención con `NuevoIngresoPagoService::obtenerIntencion($id, $niId)`. Si es nula, ajena o está borrada, lanza `NuevoIngresoReciboException::porIntencionNoEncontrada()`.
11. Paso 11: El servicio comprueba `estaAprobada($intencion)`. Si el estado no es 3 u 8, lanza `porPagoNoAprobado()`.
12. Paso 12: Carga la postulación con `NiInscripcionModel` y construye nombre completo e identificación (`V-` o `E-` según `identificacion_tipo`). Si la postulación no existe, lanza `porPostulacionNoEncontrada()`.
13. Paso 13: Consulta `pg_formas_pago` y `pg_monedas` por `formas_pago_id` en la base principal y determina si la forma es `zelle`. Si no hay fila, trata el pago como no Zelle y registra una advertencia.
14. Paso 14: Arma las filas base igual que el recibo regular: `Referencia`, `Nombre`, `Identificación` y `Numero transacción`.
15. Paso 15: Si el pago no es Zelle, agrega `Total a pagar (Bs)` con `monto_total` de la intención. No agrega descuento, tasa ni total en divisa.
16. Paso 16: Si el pago es Zelle, busca el último `pg_zelle_reportes` no borrado de la intención y arma el desglose:
    - `Subtotal` con `monto_total` de la intención en Bs.
    - `Descuento aplicado` solo si el porcentaje persistido es mayor que cero.
    - `Total a pagar (Bs)` con `monto_bs` del reporte.
    - `Tasa aplicada` solo si la tasa persistida es mayor que cero.
    - `Total $` con el monto verificado, o `Monto a pagar (USD)`, `Monto recibido` y `Monto a favor` cuando hay excedente.
17. Paso 17: Usa `descripcion` de la intención como bloque de descripción del recibo.
18. Paso 18: Llama a `ReciboPdfBuilder::generar($filas, $descripcion)` y devuelve `['pdf' => $binario, 'nombre_archivo' => 'ReciboNI' . $id . '.pdf']`.
19. Paso 19: `Paso3::recibo()` responde con `Content-Type: application/pdf`, `Content-Disposition: inline; filename="ReciboNI{id}.pdf"`, `Cache-Control: private, no-store` y el cuerpo binario. No envuelve el PDF en el layout.
20. Paso 20: El navegador muestra el PDF en línea o lo descarga según su preferencia. La operación es idempotente y no escribe en base de datos.

## Flujos alternativos / variantes

### Zelle verificado con excedente

1. Paso 1: La intención está en estado 8 y el reporte Zelle tiene `excedente > 0` y `monto_pagado > monto`.
2. Paso 2: El servicio agrega `Monto a pagar (USD)` con `monto` del reporte, `Monto recibido` con `monto_pagado` y `Monto a favor` con `excedente`.
3. Paso 3: No agrega la fila `Total $` para no duplicar el total.
4. Paso 4: El resto del desglose (subtotal, descuento, total Bs y tasa) se mantiene.

### Zelle verificado sin descuento

1. Paso 1: El reporte tiene `descuento` nulo, vacío o `0`, o el porcentaje derivado de `monto_bs`/`monto_total` es menor o igual a cero.
2. Paso 2: El servicio omite la fila `Descuento aplicado`.
3. Paso 3: Conserva `Subtotal`, `Total a pagar (Bs)`, `Tasa aplicada` y `Total $`.
4. Paso 4: No se bloquea el recibo por ausencia de descuento.

### Zelle sin columnas de desglose (reporte histórico)

1. Paso 1: El reporte existe pero `descuento`, `monto_bs` o `monto_pagado` son nulos.
2. Paso 2: El servicio completa los valores con `data_respuesta` de la intención.
3. Paso 3: Si `data_respuesta` tampoco tiene el dato, usa `monto` como monto verificado y `monto_total` como total en Bs.
4. Paso 4: Omite solo las filas cuyo dato no se pueda resolver; no recalcula con la tasa o el descuento vigentes.

### Zelle sin reporte asociado

1. Paso 1: La intención está en estado 8 pero no existe un `pg_zelle_reportes` no borrado.
2. Paso 2: El servicio registra una advertencia y usa `data_respuesta` como respaldo.
3. Paso 3: Si tampoco hay `data_respuesta`, muestra `Total a pagar (Bs)` con `monto_total` y omite descuento, tasa y total en divisa.
4. Paso 4: El recibo se genera igualmente; no se inventan montos.

### Pago no Zelle aprobado (estado 3)

1. Paso 1: La forma de pago es `pagomovilb` u otra pasarela `po`/`rp` distinta de Zelle.
2. Paso 2: El servicio no agrega descuento, tasa ni total en divisa.
3. Paso 3: Muestra `Total a pagar (Bs)` con `monto_total` y la referencia de la intención.
4. Paso 4: El recibo conserva el diseño y la descripción del recibo regular.

### Intención aprobada sin `monto_pagado`

1. Paso 1: La intención está en estado 3 y `monto_pagado` es `0` o nulo.
2. Paso 2: Para un pago no Zelle, el total sigue saliendo de `monto_total`; no se usa `monto_pagado`.
3. Paso 3: Para un pago Zelle, el monto verificado sale del reporte o de `data_respuesta`; si no existe, se usa `monto`.
4. Paso 4: No se muestra un total en cero si hay un monto persistido disponible.

### Descarga repetida

1. Paso 1: El aspirante vuelve a solicitar el mismo recibo.
2. Paso 2: El servicio vuelve a leer la intención y el reporte, sin escribir ni consumir nada.
3. Paso 3: El PDF se regenera con los mismos datos persistidos.
4. Paso 4: El resultado es equivalente; no se crea auditoría ni historial de descargas.

### Acceso por auto-routing

1. Paso 1: Un cliente invoca `Paso3::recibo` por una URI no prevista en `Routes.php`.
2. Paso 2: El método ejecuta la comprobación de GET, `sesionValida()`, la validación del id y la resolución del contexto antes de generar.
3. Paso 3: Sin sesión o sin paso 4, redirige; con sesión válida, aplica las mismas reglas de propiedad y estado.
4. Paso 4: No se expone ningún recibo ajeno.

### Recibo regular (regresión)

1. Paso 1: Un estudiante del portal regular abre `GET /Reportes/Recibo/{id}`.
2. Paso 2: `Reportes::Recibo` conserva su validación de sesión, propiedad, estado 3/8 y rechazo de intenciones NI.
3. Paso 3: Construye las mismas filas y llama al builder compartido.
4. Paso 4: El PDF, el nombre `Recibo{id}.pdf` y el comportamiento en línea no cambian.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| Sesión de nuevo ingreso ausente o inválida | Filtro `nuevoIngresoAuth:4`; `sesionValida()` | Redirección a `/inscripciones/nuevo-ingreso`; en AJAX 401 | Sin PDF; no se escribe |
| `paso_actual` menor a 4 | Filtro; `sesionValida()` | Redirección a `/inscripciones/nuevo-ingreso/materias`; en AJAX 403 | Sin PDF |
| Método distinto de GET en `recibo` | `$this->request->getMethod()` | Página de mensaje 405 con enlace al Paso 4 | Sin PDF |
| `$id` ausente, cero, negativo o no numérico | Validación del controlador | Página de mensaje 422 "La intención de pago es obligatoria." | Sin PDF |
| Contexto de postulación inválido | `NuevoIngresoContextException` | Página de mensaje 422 con enlace al Paso 4 | Sin PDF |
| `ni_inscripcion_id` no resuelto | Validación del controlador | Página de mensaje 422 o 500 según el origen; log técnico | Sin PDF |
| Intención inexistente, ajena o con `borrado_dt` | `obtenerIntencion()` devuelve `null` | Página de mensaje 422 "No tienes permisos para ver este recibo."; no se revela si el id existe | Sin PDF; sin datos ajenos |
| Intención en estado distinto de 3 u 8 | `estaAprobada()` devuelve `false` | Página de mensaje 422 "El recibo no está disponible. El pago aún no ha sido aprobado o verificado." con enlace al Paso 4 | Estado intacto |
| Postulación no encontrada | `NiInscripcionModel` devuelve `null` | Página de mensaje 422 "No fue posible generar el recibo."; log técnico | Sin PDF |
| Forma de pago inexistente o `formas_pago_id = 0` | Consulta a `pg_formas_pago` sin fila | Se trata como no Zelle; se muestra el total en Bs; log warning | Sin PDF en divisa |
| Banco o moneda sin datos | Join `pg_monedas` devuelve nulos | Se usa la abreviatura/descripción disponibles; si no hay, se omite la moneda del total en divisa | PDF generado con texto de respaldo |
| Reporte Zelle inexistente en estado 8 | Consulta sin fila | Se usa `data_respuesta`; si tampoco existe, se muestran solo los datos de la intención; log warning | PDF generado sin inventar montos |
| `data_respuesta` vacío o JSON inválido | `json_decode` no devuelve arreglo | Se ignora y se usan las columnas del reporte o la intención | PDF generado |
| Tasa Zelle nula o menor o igual a cero | Validación numérica | Se omite la fila `Tasa aplicada` | PDF generado sin tasa |
| Descuento Zelle nulo o cero | Validación numérica | Se omite la fila `Descuento aplicado` | PDF generado sin descuento |
| Excedente nulo o menor o igual a cero | Validación numérica | Se muestra `Total $` en lugar de las filas de excedente | PDF generado con total |
| Error del builder o de FPDF | `catch (\Throwable)` en el controlador | Página de mensaje 500 "No fue posible generar el recibo. Intenta nuevamente."; log técnico | Sin PDF; sin escritura |
| Auto-routing sin filtro | `sesionValida()` y validaciones internas | Misma respuesta que la ruta explícita | Sin PDF |
| Error inesperado de base de datos | Excepción del modelo o del servicio | Página de mensaje 500; log técnico sin datos personales | Sin PDF; sin escritura |
| Recibo regular con intención NI | Guarda existente en `Reportes::Recibo` | Página de mensaje "No tienes permisos para ver este recibo." | Sin PDF |
| Regresión del recibo regular | Prueba/smoke test | El PDF regular conserva filas, diseño y nombre | Sin cambio funcional |

## Reglas de negocio y validaciones

- El recibo solo se genera para intenciones propias de la postulación: `obtenerIntencion($id, $niId)` con `ni_inscripcion_id` y `borrado_dt IS NULL`. La identidad y la sede salen de la sesión `nuevo_ingreso` y del contexto, nunca de un `AASUCURSID` o de una cédula enviados por el cliente.
- Solo se permite el estado 3 (aprobado) u 8 (verificado). Cualquier otro estado, incluido 7 (en verificación), responde 422 y no genera PDF.
- `Paso3::recibo` es una operación de solo lectura: no actualiza la intención, no crea reportes, no marca GHL, no sincroniza Orbis y no modifica `paso_actual`.
- El recibo no muestra el plan. La resolución de `PlanPagoPerioID` y su nombre queda como funcionalidad futura.
- El descuento solo se muestra para pagos Zelle y solo si el porcentaje persistido es mayor que cero. No se recalcula con `desc_pg_dolar_ni` ni con el descuento global.
- La tasa solo se muestra para pagos Zelle y solo si el valor persistido es mayor que cero. Se presenta en `Bs/USD`.
- El subtotal en Bs es `monto_total` de la intención. El total en Bs para Zelle es `monto_bs` del reporte; si falta, se usa `monto_total`.
- El monto verificado en USD es `pg_zelle_reportes.monto_pagado`; si falta, `data_respuesta.monto_pagado`; si falta, `pg_zelle_reportes.monto`; si falta, `data_respuesta.monto`. No se acepta un monto del cliente ni se recalcula con la tasa vigente.
- El excedente es `pg_zelle_reportes.excedente` o `data_respuesta.excedente`. Solo se muestran las filas de excedente cuando es mayor que cero.
- El porcentaje de descuento es `pg_zelle_reportes.descuento` o `data_respuesta.descuento`. Si no existe, se deriva de `1 - (monto_bs / monto_total)` como hace el recibo regular. Si el resultado es menor o igual a cero, se omite.
- Para pagos no Zelle, el total es `monto_total` en Bs y no se muestran descuento, tasa ni total en divisa.
- La descripción del recibo es `pg_intenciones_pago.descripcion`, con el mismo tratamiento de caracteres que el recibo regular.
- Las filas, etiquetas, orden, formato numérico y resaltado del total replican el recibo regular: `Referencia`, `Nombre`, `Identificación`, `Numero transacción`, totales y `Descripción`.
- El nombre del archivo es `ReciboNI{id}.pdf`. El recibo regular conserva `Recibo{id}.pdf`.
- `Reportes::Recibo` sigue rechazando intenciones con `ni_inscripcion_id` no nulo. El recibo NI solo se obtiene por la ruta de nuevo ingreso con sesión `nuevo_ingreso`.
- `Reportes::Recibo` conserva sus validaciones y su respuesta ante errores. El refactor solo extrae el renderizado; no cambia filas, diseño, logo, márgenes ni contenido.
- `ReciboPdfBuilder` no consulta base de datos ni conoce sesión: recibe filas y descripción ya normalizadas. Esto permite probarlo de forma aislada y reutilizarlo en ambos flujos.
- `NuevoIngresoReciboService` no conoce la sesión, la ruta ni la vista. Recibe `niInscripcionId` y `intencionId` ya validados por el controlador y vuelve a validar propiedad y estado.
- Todos los métodos públicos nuevos validan sesión, paso, id, propiedad y estado, aunque exista una ruta con filtro, para cubrir el auto-routing.
- No se agregan dependencias, migraciones, seeds, CSRF ni cambios de esquema.
- Las vistas y los mensajes escapan la salida con `esc()`; los atributos usan `esc(..., 'attr')`. El PDF usa el mismo `utf8_decode()` del recibo regular.
- El botón "Descargar recibo" solo aparece en el estado `aprobado` del Paso 4 y no se agrega a la vista compartida de intentos.

## Contratos y diseño propuesto

### `ReciboPdfBuilder`

| Método | Responsabilidad | Efectos |
| --- | --- | --- |
| `generar(array $filas, string $descripcion, ?string $logoUrl = null): string` | Crear el PDF con el diseño del recibo regular y devolver el binario. | Sin escritura; sin base de datos. |

- Extrae el bloque de `Reportes::Recibo` que crea `new Recibo('P', 'mm', 'Letter')`, fija márgenes, auto page break, logo, título "RECIBO DE PAGO", tabla etiqueta/valor, resaltado de totales y bloque de descripción.
- Devuelve `$pdf->Output('S')` para que el controlador fije las cabeceras y el cuerpo. El PDF resultante conserva el mismo contenido visual que el recibo regular.
- Si `$logoUrl` es nulo, usa `base_url('/assets/reportes/logo1.png')`.
- No conoce origen regular ni nuevo ingreso; solo recibe filas y descripción.

### `Reportes::Recibo`

- Conserva `validarSesion()`, la consulta de la intención, la validación de propiedad, el rechazo de `ni_inscripcion_id` no nulo, la validación de estado 3/8, la consulta de forma/moneda, la consulta del reporte Zelle y la construcción de `$filas_recibo`.
- Reemplaza el bloque de renderizado por `Services::reciboPdfBuilder()->generar($filas_recibo, (string) $intencion_pago_r->descripcion)`.
- Responde con `Content-Type: application/pdf`, `Content-Disposition: inline; filename="Recibo{id}.pdf"` y el cuerpo binario.
- No cambia sus mensajes de error ni su comportamiento para intenciones NI.

### `NuevoIngresoReciboService`

| Método | Responsabilidad | Efectos |
| --- | --- | --- |
| `generar(int $intencionId, int $niInscripcionId): array` | Validar propiedad y estado, construir las filas del recibo NI y generar el PDF. | Solo lectura; no escribe. Lanza `NuevoIngresoReciboException`. |

- Construye las filas base y las filas Zelle descritas en las reglas de negocio.
- Devuelve:
  ```php
  [
      'pdf'            => $binario,
      'nombre_archivo' => 'ReciboNI' . $intencionId . '.pdf',
  ]
  ```
- Dependencias inyectables: `NiInscripcionModel`, `NuevoIngresoPagoService`, `ReciboPdfBuilder` y `BaseConnection` de la base principal.
- Reutiliza `obtenerIntencion()` y `estaAprobada()` del servicio de pago. No duplica la validación de propiedad.
- No conoce sesión, ruta, vista ni la sesión del portal regular.

### `NuevoIngresoReciboException`

- Extiende `\RuntimeException`.
- Fábricas: `porIntencionNoEncontrada()`, `porPagoNoAprobado()`, `porPostulacionNoEncontrada()` y `porErrorGeneracion(?\Throwable $previo = null)`.
- Mensajes en español, sin detalles técnicos ni datos personales.
- El controlador la traduce a una página de mensaje con código 422; los errores inesperados se traducen a 500.

### `Paso3::recibo`

| Aspecto | Regla |
| --- | --- |
| Firma | `public function recibo($id = 0)` |
| Método HTTP | Solo GET; otro método responde 405. |
| Sesión | `sesionValida()` exige `nuevo_ingreso` y `paso_actual >= 4`. |
| Id | Entero positivo; otro valor responde 422. |
| Contexto | `Services::nuevoIngresoContext()->resolver()`; `niId` sale de `inscripcion.id`. |
| Servicio | `Services::nuevoIngresoRecibo()->generar($id, $niId)`. |
| Respuesta | `application/pdf`, `Content-Disposition: inline`, `Cache-Control: private, no-store`, cuerpo binario. |
| Errores | Página de mensaje del layout de nuevo ingreso con enlace al Paso 4; 422 de dominio, 500 inesperado. |
| Escritura | Ninguna. |

### `Services`

- Agregar `use App\Libraries\Inscripciones\NuevoIngreso\Recibo\NuevoIngresoReciboService;`, `use App\Libraries\Recibos\ReciboPdfBuilder;` y el `use` de la excepción si aplica.
- Agregar `public static $nuevoIngresoReciboInstance = null;` y `public static $reciboPdfBuilderInstance = null;`.
- `reciboPdfBuilder($getShared = true)` devuelve una instancia compartida de `ReciboPdfBuilder`.
- `nuevoIngresoRecibo($getShared = true)` construye `NuevoIngresoReciboService` con `Database::connect()`, `NiInscripcionModel`, `Services::nuevoIngresoPago()` y `Services::reciboPdfBuilder()`.
- Las pruebas deben reiniciar ambas instancias en `setUp`/`tearDown`.

### Rutas y vistas

| Método | URI | Acción | Filtro |
| --- | --- | --- | --- |
| GET | `inscripciones/nuevo-ingreso/paso-4/recibo/(:num)` | `Paso3::recibo/$1` | `nuevoIngresoAuth:4` |

- `Paso3::urls()` agrega `'recibo' => $base . '/paso-4/recibo/'`.
- `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` agrega `$puedeVerRecibo` y el enlace "Descargar recibo" dentro del bloque `aprobado`, con `target="_blank"` y `rel="noopener"`.
- No se modifica `app/Views/pagos/intenciones_pagos.php` ni la vista del portal regular.
- No se modifica `public/css/tailwind-v4.css`; se usan clases Tailwind existentes.

## Áreas afectadas

| Acción | Archivo / componente | Motivo |
| --- | --- | --- |
| Crear | `app/Libraries/Recibos/ReciboPdfBuilder.php` | Builder compartido extraído del recibo regular. |
| Modificar | `app/Controllers/Reportes.php` | Usar el builder sin cambiar el contrato del recibo regular. |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Recibo/NuevoIngresoReciboService.php` | Dominio y generación del recibo NI. |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Recibo/NuevoIngresoReciboException.php` | Errores de dominio del recibo NI. |
| Modificar | `app/Config/Services.php` | Registrar `reciboPdfBuilder` y `nuevoIngresoRecibo`. |
| Modificar | `app/Controllers/Inscripciones/NuevoIngreso/Paso3.php` | `recibo()`, `urls()` y manejo de errores. |
| Modificar | `app/Config/Routes.php` | Ruta GET del recibo con `nuevoIngresoAuth:4`. |
| Modificar | `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` | Botón "Descargar recibo" en estado aprobado. |
| Crear | `tests/app/Libraries/Recibos/ReciboPdfBuilderTest.php` | PDF válido y filas con acentos. |
| Crear | `tests/app/Libraries/Inscripciones/NuevoIngreso/Recibo/NuevoIngresoReciboServiceTest.php` | Filas NI, Zelle, descuento, tasa, excedente, estados y propiedad. |
| Crear | `tests/app/Integration/Paso4ReciboTest.php` | Ruta, filtro, PDF, 405, 422 y aislamiento. |
| Modificar | `tests/app/Integration/Paso4NuevoIngresoTest.php` | Verificar el botón en estado aprobado. |
| Documentar | `docs/features/007-recibo-pdf-nuevo-ingreso/plan.md` | Este plan. |

No se modifican migraciones, seeds, `gb_config`, `ni_inscripciones`, `NuevoIngresoPagoService`, `PaymentService`, `PaymentOrchestrator`, las pasarelas, la SPA ni la API. Las vistas compartidas del portal regular no se tocan; solo se refactoriza el renderizado del recibo regular.

## Criterios de finalización

- [ ] `ReciboPdfBuilder::generar()` devuelve un binario que comienza con `%PDF-` y no lanza errores con acentos ni con filas vacías.
- [ ] `Reportes::Recibo` usa `ReciboPdfBuilder` y conserva sus validaciones, filas, título, logo, márgenes, descripción, nombre `Recibo{id}.pdf` y respuesta en línea.
- [ ] `Reportes::Recibo` sigue rechazando intenciones con `ni_inscripcion_id` no nulo.
- [ ] `NuevoIngresoReciboService::generar()` solo acepta intenciones propias en estado 3 u 8; una intención ajena, inexistente o en otro estado lanza la excepción de dominio.
- [ ] El recibo no muestra el plan.
- [ ] El recibo base muestra `Referencia`, `Nombre`, `Identificación`, `Numero transacción`, `Total a pagar (Bs)` y `Descripción`.
- [ ] El nombre completo y la identificación salen de `ni_inscripciones`; la identificación se presenta con prefijo `V-` o `E-` según `identificacion_tipo`.
- [ ] Para pagos no Zelle no se muestran descuento, tasa ni total en divisa.
- [ ] Para Zelle se muestra `Subtotal`, `Total a pagar (Bs)` y `Total $`; el descuento y la tasa se muestran solo si son mayores que cero.
- [ ] El descuento Zelle usa el porcentaje persistido o el derivado de `monto_bs`/`monto_total`; no usa `desc_pg_dolar_ni` ni el descuento global.
- [ ] La tasa Zelle usa el valor persistido en el reporte o en `data_respuesta`; no usa la tasa vigente.
- [ ] El monto verificado Zelle usa `monto_pagado`, luego `data_respuesta.monto_pagado`, luego `monto`; no acepta montos del cliente.
- [ ] Si el excedente es mayor que cero, se muestran `Monto a pagar (USD)`, `Monto recibido` y `Monto a favor`; si no, se muestra `Total $`.
- [ ] Un reporte histórico sin columnas de desglose se completa con `data_respuesta` y, si falta, con los datos de la intención, sin recalcular.
- [ ] `Paso3::recibo` solo acepta GET y responde 405 con página de mensaje para otros métodos.
- [ ] `Paso3::recibo` valida sesión, paso, id positivo, propiedad y estado; una intención ajena o inexistente responde 422 sin revelar su existencia.
- [ ] La ruta `GET /inscripciones/nuevo-ingreso/paso-4/recibo/(:num)` existe con el filtro `nuevoIngresoAuth:4`.
- [ ] El botón "Descargar recibo" aparece solo en el estado aprobado del Paso 4 y apunta a la ruta correcta.
- [ ] El controlador responde con `Content-Type: application/pdf`, `Content-Disposition: inline; filename="ReciboNI{id}.pdf"`, `Cache-Control: private, no-store` y el cuerpo binario.
- [ ] El recibo se genera sin escribir en base de datos y es idempotente ante descargas repetidas.
- [ ] Las pruebas unitarias del builder y del servicio cubren estados 3 y 8, no Zelle, Zelle con descuento, Zelle con excedente, Zelle sin desglose, intención ajena y estado no aprobado.
- [ ] Las pruebas de integración cubren PDF 200, 405, 422 por id inválido, 422 por estado 7, 422 por intención ajena y redirección sin sesión.
- [ ] Las pruebas existentes de `Paso4NuevoIngresoTest`, `Paso4PagoTest`, `ZelleNuevoIngresoTest` y el área de pagos siguen pasando.
- [ ] Se ejecuta un smoke test manual del recibo regular y del recibo NI en un entorno con sesión válida.
- [ ] `php -l` no reporta errores en los archivos PHP nuevos o modificados.
- [ ] `graphify update .` se ejecuta después de los cambios de código.
- [ ] No se agregaron dependencias, migraciones, seeds, CSRF ni cambios en `vendor/`, `system/` o `public/vendor/`.

## Decisiones de la entrevista

| Tema | Decisión |
| --- | --- |
| Reutilización | La petición inicial pedía no reutilizar `Reportes::Recibo`; el usuario corrigió y se reutiliza su generación mediante un builder compartido. |
| Arquitectura | Servicio compartido: `ReciboPdfBuilder` renderiza; `NuevoIngresoReciboService` orquesta el recibo NI; `Reportes::Recibo` usa el mismo builder. |
| Entrada HTTP | Ruta nueva `paso-4/recibo/(:num)` con `nuevoIngresoAuth:4`; no se reutiliza `/Reportes/Recibo`. |
| Aislamiento | `/Reportes/Recibo` sigue rechazando intenciones NI. |
| Acceso visible | Solo botón en el estado aprobado del Paso 4; no se toca la vista de intentos. |
| Contenido | El mismo recibo regular adaptado para nuevo ingreso. |
| Plan | Omitido; se documenta como funcionalidad futura. |
| Descuento | Solo para pagos Zelle y solo si el valor persistido es mayor que cero. |
| Tasa | Solo para pagos Zelle y solo si el valor persistido es mayor que cero. |
| Monto Zelle | Mismo desglose que el recibo regular: subtotal, descuento, total Bs, total USD y excedente si aplica. |
| Errores | Página de mensaje con código HTTP: 405 método, 422 dominio/ajena/no aprobada, 500 inesperado. |
| Identidad | Nombre y cédula de `ni_inscripciones`; sesión y contexto de nuevo ingreso; nunca datos del cliente. |
| Escritura | El recibo es de solo lectura y no genera historial ni auditoría de descargas. |

## Riesgos y deuda técnica

- **Refactor del recibo regular:** `Reportes::Recibo` es una ruta de producción compartida. El builder debe mover el renderizado sin cambiar filas, diseño ni mensajes. Se exige prueba de regresión y smoke test manual.
- **Cambio de decisión:** la petición original prohibía reutilizar `Reportes::Recibo`; la entrevista la revirtió. Queda registrado para que la revisión de código no lo interprete como una desviación.
- **Reportes Zelle históricos:** las columnas de desglose se agregaron en FEAT-006 y no hubo backfill. Los recibos de pagos anteriores pueden requerir `data_respuesta` o mostrar solo los datos disponibles.
- **`monto_pagado` en estado 3:** algunas pasarelas pueden no registrar `monto_pagado` en la intención. El recibo no Zelle no depende de ese campo; el Zelle usa el reporte.
- **FPDF y `utf8_decode()`:** el proyecto usa PHP 8.0 y conserva el comportamiento del recibo regular. Una futura migración a PHP 8.2+ debe revisar la deprecación.
- **Logo por URL:** el logo se toma de `base_url()`, igual que el recibo regular. Si la configuración del servidor no permite acceder a la URL desde FPDF, el comportamiento será el mismo que el recibo regular y debe probarse en el entorno de despliegue.
- **Auto-routing:** `Paso3::recibo` es público y podría invocarse por una URI no prevista. Se mitiga con las validaciones internas y el filtro de la ruta explícita.
- **Sin plan en el recibo:** el detalle `_ni` ya guarda `PlanPagoPerioID`, pero este corte no lo muestra. Si el negocio lo exige, debe especificarse una feature posterior.
- **PDF no almacenado:** cada descarga regenera el documento. No hay auditoría de descargas ni cache; es intencional para no agregar almacenamiento ni datos personales.
- **Sin CSRF:** la ruta es GET y de solo lectura; no se agrega CSRF. Cualquier cambio futuro que convierta el recibo en una acción con escritura debe revisar esta decisión.

## Preguntas abiertas y supuestos a validar

- Se asume que `identificacion_tipo = 0` es `V` y `1` es `E`, según el formulario de `Paso0`. Confirmar con negocio antes del despliegue.
- Se asume que un pago Zelle en estado 8 siempre tiene un reporte no borrado; si no, el recibo se degrada con `data_respuesta` y no se bloquea.
- Se asume que el nombre del archivo `ReciboNI{id}.pdf` es aceptable; el recibo regular conserva `Recibo{id}.pdf`.
- Se asume que el refactor de `Reportes::Recibo` puede ejecutarse dentro de esta feature. Si el equipo prefiere aislarlo, la Fase A debe convertirse en un cambio `refactor` previo con su propio plan.
- Se asume que el porcentaje de descuento persistido en `pg_zelle_reportes.descuento` está expresado como porcentaje (por ejemplo, `5.00` para 5%), según FEAT-006.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-28 | Creación del plan FEAT-007 tras revisar `Reportes::Recibo`, `Paso3`, `NuevoIngresoPagoService`, `NuevoIngresoContextService`, `ZelleReportManager`, las migraciones de `pg_intenciones_pago` y `pg_zelle_reportes`, y las features FEAT-004 a FEAT-006. La entrevista definió: reutilizar el recibo regular mediante un builder compartido, ruta nueva de nuevo ingreso, aislamiento de `/Reportes/Recibo`, botón solo en estado aprobado, sin plan, descuento y tasa solo para Zelle, y mismo desglose Zelle del recibo regular. | opencode (agente) |
