# Prototipo de ejecución — FEAT-016 Detalle de postulación con recaudos digitales y disponibilidad

- **Rama:** p-feature/detalle-postulacion-recaudos-digitales
- **Rama base:** feature/panel-administrativo-documentos-ni
- **Plan:** docs/features/016-detalle-postulacion-recaudos-digitales/plan.md
- **Fecha:** 2026-10-30
- **Estado:** consolidado
- **Fecha de consolidación:** 2026-10-30
- **Rama destino:** feature/panel-administrativo-documentos-ni

## Resumen

Se agregó `PostulacionesAdminService::obtenerDetalle(int $id): ?array`, que devuelve los datos completos de una postulación de nuevo ingreso y la lista de sus recaudos activos con su disponibilidad, sin exponer rutas físicas ni leer archivos. Reutiliza la consulta base, el formateo y el resolvedor de pasos del listado administrativo existente. El resultado es la fuente de datos del detalle del panel administrativo (Slice 7).

## Tareas realizadas

- [x] Implementar `obtenerDetalle(int $id): ?array` en `PostulacionesAdminService` con retorno `null` para `id <= 0` y postulación inexistente.
- [x] Devolver identificación completa sin enmascarar, nombre, apellido, nombre completo, correo, teléfono, carrera, sede, paso, estado de pago y fecha de creación.
- [x] Obtener recaudos activos con `NiInscripcionRecaudoModel::obtenerRecaudosPorInscripcion()` y transformarlos al contrato público, descartando `archivo_path`, `archivo_hash` y `observacion`.
- [x] Calcular `recaudos_total` y `recaudos_disponibles` desde la lista transformada.
- [x] Reutilizar `crearBuilderBase()`, `formatearFila()` y `PasoActualResolver`; extraer las subconsultas de pago y recaudos a métodos privados compartidos con `listar()`.
- [x] Agregar dependencia opcional `?NiInscripcionRecaudoModel` al constructor, conservando los dos parámetros previos.
- [x] Añadir desempate `ir.id ASC` al orden de `obtenerRecaudosPorInscripcion()` para cumplir el orden estable.
- [x] Ampliar el esquema SQLite de pruebas con `ni_recaudos` y las columnas `recaudo_id`, `es_requerido`, `estado`, `archivo_hash` y `observacion`.
- [x] Agregar casos de detalle: existente, extranjero, múltiples intenciones, id inválido, inexistente, sin recaudos, oferta inexistente, ausencia de rutas/hashes, no verificación física y solo lectura.

## Criterios de aceptación

| Criterio | Cómo se verificó | Resultado |
| --- | --- | --- |
| `obtenerDetalle(int $id): ?array` existe y es público | Revisión de firma y prueba `testObtenerDetalleRetornaDatosCompletosYRecaudosOrdenados` | ok |
| Firma y constructor compatibles con `listar()`/`obtenerCatalogosFiltros()` | Tercer parámetro opcional; pruebas de listado y catálogos siguen pasando | ok |
| `id <= 0` retorna `null` sin consultar | `testObtenerDetalleIdInvalidoRetornaNullSinConsultar` compara la última consulta antes y después | ok |
| Postulación inexistente retorna `null` | `testObtenerDetalleInexistenteRetornaNull` | ok |
| Detalle con todos los campos requeridos | `testObtenerDetalleRetornaDatosCompletosYRecaudosOrdenados` | ok |
| Identificación completa `V-`/`E-` sin enmascarar | Casos id 1 (`V-11111111`) e id 3 (`E-33333333`) | ok |
| Sin intención de pago: `estado_pago_id = null` y `Pendiente` | Casos id 1 y id 4 | ok |
| Varias intenciones: usa la más reciente no borrada | `testObtenerDetalleConVariasIntencionesUsaLaMasReciente` (Rechazado 10 → Aprobado 11) | ok |
| Solo recaudos con `activo = 1` | El recaudo inactivo id 4 no aparece en la lista | ok |
| Cada recaudo incluye `id`, `recaudo_id`, `nombre`, `es_requerido`, `estado`, `disponible` | Aserciones por cada fila del detalle | ok |
| `es_requerido` y `disponible` booleanos | `assertTrue`/`assertFalse` en los tres recaudos del id 1 | ok |
| `disponible` según `archivo_path` | `''` → false, `NULL` → false, ruta con valor → true | ok |
| Orden por catálogo y desempate por fila | `[10, 30, 30]` con ids `[5, 6, 7]` en el id 2 | ok |
| Contadores coinciden con la lista | `3/2` en ids 1 y 2; `0/0` en id 4 | ok |
| Postulación sin recaudos devuelve lista vacía y ceros | `testObtenerDetalleSinRecaudosRetornaListaVacia` | ok |
| Sin `archivo_path`, `archivo_hash`, rutas ni contenido | `testObtenerDetalleNoExponeRutasNiHashes` recorre claves y valores recursivamente | ok |
| No se leen archivos | `testObtenerDetalleNoVerificaExistenciaFisicaDelArchivo` usa una ruta inexistente y sigue disponible | ok |
| Sin escrituras | `testSoloLecturaNoModificaLaBaseDeDatos` compara el conteo de 8 tablas antes y después | ok |
| Cobertura ampliada de casos | 24 pruebas del archivo, 354 aserciones | ok |
| `PostulacionesAdminServiceTest` pasa | `phpunit .../PostulacionesAdminServiceTest.php` | ok |
| `php -l` sin errores | Servicio, modelo y pruebas | ok |
| Sin cambios en rutas, controladores, vistas, migraciones, seeds, SPA ni API | Revisión de `git status` y `git diff --stat` | ok |

## Flujos cubiertos

- **Flujo normal:** el consumidor invoca `obtenerDetalle($id)` y recibe la postulación normalizada con `recaudos` ordenados y los contadores calculados.
- **Flujos alternativos:** postulación sin recaudos, recaudos activos con y sin archivo, postulación sin intención de pago, múltiples intenciones de pago, oferta académica no encontrada y paso actual desconocido o nulo.
- **Control de errores:** `id <= 0` y postulación inexistente retornan `null`; los errores de base de datos se registran con el `id` y se propagan; un recaudo inactivo queda excluido; un archivo ausente en disco no altera `disponible`.

## Archivos creados

| Archivo | Motivo |
| --- | --- |
| `docs/features/016-detalle-postulacion-recaudos-digitales/prototipo.md` | Documentación de la ejecución de la feature. |

## Archivos modificados

| Archivo | Cambio realizado |
| --- | --- |
| `app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminService.php` | Nuevo `obtenerDetalle()`, dependencia opcional del modelo de recaudos, transformación de recaudos y extracción de subconsultas compartidas. |
| `app/Models/Inscripciones/NiInscripcionRecaudoModel.php` | Desempate `ir.id ASC` en `obtenerRecaudosPorInscripcion()` para el orden estable del catálogo. |
| `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php` | Esquema SQLite ampliado, seeds de catálogo de recaudos y casos de detalle. |
| `docs/features/016-detalle-postulacion-recaudos-digitales/plan.md` | Estado actualizado a `completado` y criterios marcados. |

## Rutas, permisos y datos

- **Rutas/endpoints nuevos o modificados:** no aplica; el Slice 7 expondrá el servicio bajo `adminPanel:module=inscripciones_ni`.
- **Permisos y validaciones:** el método no autoriza por sí mismo. El ID se valida (`$id <= 0`) y se usa con Query Builder/bindings; los recaudos se obtienen con el método parametrizado del modelo.
- **Migraciones/seeds:** no aplica; sin cambios de esquema ni datos.
- **Compatibilidad:** el constructor conserva sus dos primeros parámetros y el nuevo es opcional; `Paso1` y el controlador administrativo siguen funcionando. El desempate agregado al modelo no altera consumidores existentes.

## Comandos ejecutados

| Comando | Resultado |
| --- | --- |
| `php vendor/phpunit/phpunit/phpunit tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php` (línea base) | Éxito: 15 pruebas, 110 aserciones. |
| `php -l app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminService.php` | Sin errores de sintaxis. |
| `php -l app/Models/Inscripciones/NiInscripcionRecaudoModel.php` | Sin errores de sintaxis. |
| `php -l tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php` | Sin errores de sintaxis. |
| `php vendor/phpunit/phpunit/phpunit tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php` (después) | Éxito: 24 pruebas, 354 aserciones. |
| `php vendor/phpunit/phpunit/phpunit tests/app/Libraries/Inscripciones/NuevoIngreso` (regresión) | 123 pruebas, 710 aserciones, 1 fallo preexistente en `NuevoIngresoPagoServiceTest::testPlanSeleccionadoYReutilizacionSinDuplicar` (línea 233). |

## Verificación

- **Línea base (antes):** `PostulacionesAdminServiceTest` en verde con 15 pruebas y 110 aserciones.
- **Prueba manual (flujo normal):** no hay interfaz en este slice; se ejercitó el servicio con la postulación 1 sembrada en SQLite y se verificaron datos personales, oferta, paso, estado de pago y recaudos.
- **Flujos alternativos y errores:** cubiertos por las pruebas de detalle (sin recaudos, inactivos, archivo vacío/NULL, múltiples intenciones, oferta inexistente, paso inválido, id inválido e inexistente).
- **Pruebas automatizadas:** `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php` (24/24 en verde).
- **Criterios del plan:** todos los criterios de finalización verificados. El fallo de la suite ampliada es preexistente y ajeno al cambio (registrado también en los prototipos de FEAT-009 y FEAT-013).

## Desviaciones del plan

- Se extrajeron las subconsultas de estado de pago y recaudos disponibles a métodos privados para que `listar()` y `obtenerDetalle()` compartan exactamente las mismas reglas; no cambia el contrato ni el comportamiento del listado.
- Se agregó el desempate `ir.id ASC` directamente en `obtenerRecaudosPorInscripcion()` en lugar de reordenar en el servicio, manteniendo una única fuente de orden para todos los consumidores.

## Riesgos y pendientes

- El detalle expone datos personales completos sin enmascarar; el Slice 7 debe mantenerlo bajo `adminPanel:module=inscripciones_ni` y no publicarlo por una ruta abierta.
- Persiste el fallo preexistente de `NuevoIngresoPagoServiceTest::testPlanSeleccionadoYReutilizacionSinDuplicar`; debe atenderse en un flujo de corrección independiente.
- Pendiente para el Slice 7: crear la ruta, el controlador y la vista que consumen este contrato, y las rutas de visualización/descarga del Slice 8.
