# Detalle de postulación con recaudos digitales y disponibilidad

- **Código:** FEAT-016
- **Tipo:** feature
- **Estado:** completado
- **Fecha:** 2026-10-30
- **Autor:** opencode (agente)

## Objetivo

Que el panel administrativo pueda obtener, desde la capa de servicio, la información mínima de una postulación de nuevo ingreso y la lista completa de sus recaudos digitales activos con su disponibilidad, sin exponer rutas físicas ni ejecutar lecturas de archivos. Es la base de datos que consumirá la pantalla de detalle del Slice 7.

## Alcance

- **Incluye:**
  - Implementar `obtenerDetalle(int $id): ?array` en `App\Libraries\Inscripciones\NuevoIngreso\Admin\PostulacionesAdminService`.
  - Devolver los datos de la postulación: identificación completa (tipo `V-`/`E-` y valor), nombre, apellido, nombre completo, correo, teléfono, carrera, sede, paso actual con etiqueta y descripción, estado de pago (`id` y nombre) y fecha de creación.
  - Devolver la lista de recaudos activos en la clave `recaudos`, ordenada por catálogo, con `id` (fila de `ni_inscripciones_recaudos`), `recaudo_id`, `nombre`, `es_requerido` (booleano), `estado` (valor crudo) y `disponible` (booleano).
  - Calcular `recaudos_total` (filas activas) y `recaudos_disponibles` (activas y con `archivo_path` no vacío) como resumen del detalle.
  - Reutilizar `crearBuilderBase()`, `formatearFila()` y el resolvedor de pasos existentes para no duplicar reglas del listado.
  - Reutilizar `NiInscripcionRecaudoModel::obtenerRecaudosPorInscripcion()` para obtener los recaudos activos ordenados por `ni_recaudos.id`, y transformar la salida en el contrato anterior.
  - Devolver `null` cuando el `id` sea menor o igual a `0` o cuando la postulación no exista.
  - Ampliar `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php` con los casos de detalle.

- **No incluye:**
  - Crear o modificar rutas, controladores o vistas del panel administrativo (Slice 7).
  - Servir, leer, validar existencia física o descargar archivos de recaudos (Slices 8 y 9).
  - Exponer `archivo_path`, `archivo_hash` ni rutas del sistema de archivos.
  - Aprobar, rechazar, marcar recibidos o modificar postulaciones, recaudos o pagos.
  - Incluir documentos presenciales de FEAT-010 o comprobantes Zelle.
  - Agregar montos, fechas de intención, identificadores de intención u otros datos de pago distintos de `estado_pago_id` y `estado_pago_nombre`.
  - Enmascarar la identificación en el detalle.
  - Modificar el esquema de base de datos, migraciones o datos de producción.

> **Evaluación de alcance:** el cambio cubre una sola capacidad de negocio y una sola capa: consultar el detalle de una postulación y sus recaudos desde el servicio existente. No mezcla presentación, autorización, archivos ni escrituras; el Slice 7 consume este contrato. No se detectó necesidad de dividirlo.

## Contexto y supuestos

- El cambio corresponde al **Slice 6** de `docs/slices/panel-administrativo-inscripciones-nuevo-ingreso/plan.md`.
- El servicio `App\Libraries\Inscripciones\NuevoIngreso\Admin\PostulacionesAdminService` (FEAT-014) ya existe y contiene la resolución de carrera, sede, paso y estado de pago más reciente. El detalle debe reutilizarla, no replicarla.
- Todas las tablas involucradas (`ni_inscripciones`, `ni_inscripciones_recaudos`, `ni_recaudos`, `es_sucursales_carreras`, `es_carreras`, `aasucurs`, `pg_intenciones_pago`, `pg_estados`) viven en la conexión principal `default`.
- La relación postulación/oferta es `ni_inscripciones.sucursal_carrera_id = es_sucursales_carreras.id`; la oferta se une con `es_carreras` y `aasucurs`, igual que en `listar()`.
- La relación postulación/recaudos es `ni_inscripciones_recaudos.inscripcion_id = ni_inscripciones.id` y `ni_inscripciones_recaudos.recaudo_id = ni_recaudos.id`.
- “Recaudo activo” significa `ni_inscripciones_recaudos.activo = 1`. No se exige `ni_recaudos.activo = 1`, por decisión funcional registrada en la entrevista.
- “Disponible” significa que `archivo_path` no es `NULL` y no es cadena vacía. No se consulta el disco, el `estado` del recaudo ni el `archivo_hash`.
- El `id` del recaudo que se expone es el de `ni_inscripciones_recaudos`, necesario para construir en el Slice 8 la URL del recaudo. El `recaudo_id` identifica la fila del catálogo.
- El orden “por catálogo” se interpreta como `ni_recaudos.id ASC`, que es el orden que ya aplica `NiInscripcionRecaudoModel::obtenerRecaudosPorInscripcion()`. Si dos filas comparten catálogo, el desempate será `ni_inscripciones_recaudos.id ASC`.
- Si una postulación no tiene filas de recaudos, `recaudos` será `[]`, `recaudos_total = 0` y `recaudos_disponibles = 0`.
- Si la postulación no tiene intención de pago, `estado_pago_id = null` y `estado_pago_nombre = 'Pendiente'`, igual que en el listado.
- `obtenerDetalle()` no aplica autorización por sí mismo; el acceso administrativo lo garantiza la ruta con `adminPanel:module=inscripciones_ni` en el Slice 7. El método es de solo lectura.
- El constructor del servicio podrá recibir opcionalmente una instancia de `NiInscripcionRecaudoModel` para pruebas y reutilizar la conexión inyectada; los dos parámetros actuales (`$db`, `$pasoResolver`) se conservan.
- El siguiente código documental libre es `FEAT-016`, verificado contra `docs/features/` (el último registrado es `015`).
- La suite completa tiene un fallo preexistente ajeno a este cambio; se ejecutan las pruebas del área afectada.

## Flujo normal

1. Paso 1: Un consumidor administrativo invoca `PostulacionesAdminService::obtenerDetalle($id)` con el identificador de la postulación.
2. Paso 2: El servicio valida que `$id` sea mayor que `0`; si no lo es, retorna `null` sin consultar la base.
3. Paso 3: El servicio construye la consulta de la postulación usando la misma base de `listar()` (postulación, oferta, carrera, sede y subconsultas de la última intención de pago no borrada).
4. Paso 4: Si la consulta no devuelve fila, el servicio retorna `null`.
5. Paso 5: Si existe, el servicio normaliza la fila con `formatearFila()`, incluyendo la identificación completa y los datos personales completos.
6. Paso 6: El servicio obtiene los recaudos activos de la postulación mediante `NiInscripcionRecaudoModel::obtenerRecaudosPorInscripcion($id)`.
7. Paso 7: El servicio transforma cada recaudo al contrato público: conserva `id`, `recaudo_id`, `nombre`, `es_requerido`, `estado`; calcula `disponible`; descarta `archivo_path` y `archivo_hash`.
8. Paso 8: El servicio calcula `recaudos_total` y `recaudos_disponibles` a partir de la lista transformada.
9. Paso 9: El servicio agrega la clave `recaudos` y los contadores a la fila normalizada y retorna el arreglo.
10. Paso 10: El consumidor (Slice 7) usa los datos para renderizar el resumen y la tabla de recaudos, mostrando acciones solo cuando `disponible = true`.

## Flujos alternativos / variantes

### Postulación sin recaudos

1. Paso 1: El consumidor solicita el detalle de una postulación sin filas en `ni_inscripciones_recaudos`.
2. Paso 2: El servicio obtiene un arreglo vacío del modelo.
3. Paso 3: El servicio retorna la postulación con `recaudos = []`, `recaudos_total = 0` y `recaudos_disponibles = 0`.
4. Paso 4: El consumidor puede mostrar el estado vacío de la tabla sin tratar el detalle como inexistente.

### Recaudos activos con y sin archivo

1. Paso 1: La postulación tiene tres recaudos activos: dos con `archivo_path` informado y uno con `archivo_path = ''`.
2. Paso 2: El modelo devuelve las tres filas activas y excluye las inactivas.
3. Paso 3: El servicio marca `disponible = true` en los dos primeros y `disponible = false` en el tercero.
4. Paso 4: `recaudos_total = 3` y `recaudos_disponibles = 2`; la lista conserva el orden del catálogo.

### Postulación sin intención de pago

1. Paso 1: La postulación está en Paso 0, 1 o 2 y no tiene filas en `pg_intenciones_pago`.
2. Paso 2: Las subconsultas de pago devuelven `NULL`.
3. Paso 3: El servicio normaliza `estado_pago_id = null` y `estado_pago_nombre = 'Pendiente'`.
4. Paso 4: El resto del detalle y la lista de recaudos se retornan normalmente.

### Postulación con intenciones de pago múltiples

1. Paso 1: La postulación tiene una intención rechazada anterior y una aprobada posterior.
2. Paso 2: Las subconsultas seleccionan la intención no borrada con el `id` más alto.
3. Paso 3: El detalle expone el estado de la intención más reciente.
4. Paso 4: No se exponen montos, fechas ni el identificador de la intención.

### Oferta académica no encontrada

1. Paso 1: La postulación referencia un `sucursal_carrera_id` que no existe en la oferta.
2. Paso 2: Los `LEFT JOIN` no producen coincidencia.
3. Paso 3: El detalle usa `'No disponible'` para carrera y sede, coherente con el listado.
4. Paso 4: La postulación se retorna igual; no se convierte en `null`.

### Paso actual desconocido o nulo

1. Paso 1: `ni_inscripciones.paso_actual` contiene un valor fuera de `0`–`4` o `NULL`.
2. Paso 2: `PasoActualResolver` devuelve la etiqueta y descripción de respaldo.
3. Paso 3: El detalle conserva `paso_actual` crudo y agrega los textos de respaldo.
4. Paso 4: No se lanza una excepción.

### Consumo del detalle desde el Slice 7

1. Paso 1: La ruta administrativa autorizada llama a `obtenerDetalle($id)`.
2. Paso 2: Si el resultado es `null`, el controlador redirige con un mensaje de “postulación no encontrada”.
3. Paso 3: Si existe, la vista muestra los datos completos y la tabla de recaudos.
4. Paso 4: Los botones “Ver” y “Descargar” se renderizan solo para recaudos con `disponible = true`; este cambio no implementa esas rutas.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| `$id` igual a `0` o negativo | Validación inicial con `$id <= 0` | Retorna `null` sin ejecutar consultas | Detalle no encontrado |
| `$id` no numérico enviado por un consumidor no tipado | Coerción a `int` en la firma `obtenerDetalle(int $id)` | Se comporta como el entero resultante; si es `<= 0`, retorna `null` | Detalle no encontrado o consulta válida |
| Postulación inexistente | La consulta principal no devuelve fila | Retorna `null` | Detalle no encontrado |
| Postulación sin recaudos | El modelo devuelve arreglo vacío | Retorna `recaudos = []` y contadores en `0` | Detalle válido con lista vacía |
| Recaudo activo sin archivo | `archivo_path` nulo o cadena vacía | `disponible = false`; el recaudo permanece en la lista | Detalle válido sin archivo |
| Recaudo inactivo | `ni_inscripciones_recaudos.activo <> 1` | El modelo lo excluye de la lista y de los contadores | Recaudo no visible |
| Oferta o carrera inexistente | `LEFT JOIN` sin coincidencia | Usa `'No disponible'` en sede y carrera | Detalle válido |
| Paso actual desconocido o nulo | `PasoActualResolver` sin coincidencia | Usa etiqueta y descripción de respaldo | Detalle válido |
| Sin intención de pago | Subconsulta de pago devuelve `NULL` | `estado_pago_id = null`, `estado_pago_nombre = 'Pendiente'` | Detalle válido |
| Fallo de base de datos | `DatabaseException` | Se registra en el log con el `id` consultado y se propaga al llamador | Error controlado; sin datos parciales |
| Intento de acceder al detalle sin autorización | Fuera de este método; lo aplica `adminPanel` en el Slice 7 | La ruta redirige al login antes de invocar el servicio | Acceso denegado |

## Reglas de negocio y validaciones

1. **Solo lectura:** `obtenerDetalle()` no ejecuta `INSERT`, `UPDATE`, `DELETE` ni DDL. Tampoco ejecuta `is_file`, `file_exists`, `readfile`, `file_get_contents` ni ninguna lectura de archivos.
2. **Contrato de inexistencia:** un `id <= 0`, no encontrado o sin postulación válida retorna `null`. No se lanza una excepción de negocio.
3. **Datos completos en el detalle:** la identificación se arma con el prefijo `V-` cuando `identificacion_tipo = '0'` y `E-` cuando es `'1'`, y se retorna sin enmascarar, junto con nombre, apellido, correo y teléfono.
4. **Reutilización del listado:** la resolución de carrera, sede, paso, estado de pago, identificación completa y nombre completo debe salir de `crearBuilderBase()` y `formatearFila()`. No se duplican etiquetas ni reglas de pago.
5. **Recaudos activos:** se incluyen solo filas con `ni_inscripciones_recaudos.activo = 1`. No se filtra por `ni_recaudos.activo`.
6. **Disponibilidad:** `disponible = true` si y solo si `archivo_path` no es `NULL` y no es `''`. No se recorta el valor ni se verifica el `estado` del recaudo.
7. **Orden estable:** los recaudos se ordenan por `ni_recaudos.id ASC` y, ante empate, por `ni_inscripciones_recaudos.id ASC`.
8. **Campos prohibidos:** la respuesta no debe contener `archivo_path`, `archivo_hash`, rutas absolutas, rutas relativas del disco ni contenido de archivos.
9. **Tipos normalizados:** `id`, `recaudo_id`, `sucursal_id`, `carrera_id`, `estado_pago_id`, `recaudos_total` y `recaudos_disponibles` se retornan como enteros o `null` cuando corresponda; `es_requerido` y `disponible` como booleanos; `estado` como cadena.
10. **Contadores:** `recaudos_total` cuenta las filas activas devueltas; `recaudos_disponibles` cuenta las que tienen `disponible = true`. Ambos deben coincidir con la lista.
11. **Compatibilidad:** la firma `obtenerDetalle(int $id): ?array` y la posible inyección opcional del modelo no deben romper las llamadas existentes a `listar()` ni a `obtenerCatalogosFiltros()`.
12. **Seguridad:** la consulta de la postulación usa el Query Builder y bindings para el `id`; los recaudos se obtienen con el método parametrizado del modelo. No se concatena entrada del cliente en SQL.
13. **Idioma:** docblocks y mensajes nuevos en español, según `AGENTS.md`.

## Áreas afectadas

- `app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminService.php`: nuevo método `obtenerDetalle()` y transformación de recaudos; posible dependencia opcional de `NiInscripcionRecaudoModel`.
- `app/Models/Inscripciones/NiInscripcionRecaudoModel.php`: reutilizado mediante `obtenerRecaudosPorInscripcion()`; no se requieren cambios si su salida cubre `inscripcion_recaudo_id`, `recaudo_id`, `archivo_path`, `es_requerido`, `estado` y `nombre`. Cualquier ajuste debe ser compatible con sus consumidores actuales.
- `tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php`: ampliación del esquema SQLite con `ni_recaudos` y `ni_inscripciones_recaudos.recaudo_id`, y nuevos casos de detalle.
- `docs/features/016-detalle-postulacion-recaudos-digitales/plan.md`: este documento.
- `MEMORY.md`: solo si al cerrar el cambio se altera el estado o una decisión documentada del proyecto.

No se modifican rutas, controladores, vistas, la SPA, la API JWT, migraciones, seeds, `vendor/`, `public/vendor/`, `system/` ni `app/ThirdParty/`.

## Criterios de finalización

- [x] `PostulacionesAdminService::obtenerDetalle(int $id): ?array` existe y es público.
- [x] La firma y el constructor siguen siendo compatibles con las llamadas actuales a `listar()` y `obtenerCatalogosFiltros()`.
- [x] Un `id` menor o igual a `0` retorna `null` sin ejecutar consultas.
- [x] Una postulación inexistente retorna `null`.
- [x] Una postulación existente retorna, al menos, `id`, `identificacion_tipo`, `identificacion_valor`, `identificacion_completa`, `nombre`, `apellido`, `nombre_completo`, `correo`, `telefono`, `sucursal_id`, `sucursal_nombre`, `carrera_id`, `carrera_nombre`, `paso_actual`, `paso_actual_etiqueta`, `paso_actual_descripcion`, `estado_pago_id`, `estado_pago_nombre`, `recaudos_total`, `recaudos_disponibles`, `created_at` y `recaudos`.
- [x] La identificación completa se retorna sin enmascarar con el prefijo `V-` o `E-` según el tipo.
- [x] El detalle de una postulación sin intención de pago devuelve `estado_pago_id = null` y `estado_pago_nombre = 'Pendiente'`.
- [x] El detalle de una postulación con varias intenciones devuelve el estado de la más reciente no borrada.
- [x] La lista `recaudos` incluye solo filas con `ni_inscripciones_recaudos.activo = 1`.
- [x] Cada recaudo incluye `id`, `recaudo_id`, `nombre`, `es_requerido`, `estado` y `disponible`.
- [x] `es_requerido` y `disponible` se retornan como booleanos.
- [x] `disponible` es `false` cuando `archivo_path` es `NULL` o `''`, y `true` cuando tiene un valor no vacío.
- [x] Los recaudos se ordenan por `ni_recaudos.id ASC` con desempate por `ni_inscripciones_recaudos.id ASC`.
- [x] `recaudos_total` y `recaudos_disponibles` coinciden exactamente con la lista devuelta.
- [x] Una postulación sin recaudos retorna `recaudos = []`, `recaudos_total = 0` y `recaudos_disponibles = 0`.
- [x] La respuesta no contiene `archivo_path`, `archivo_hash`, rutas del sistema de archivos ni contenido de archivos, verificable de forma recursiva en las pruebas.
- [x] No se ejecutan lecturas de archivos (`file_exists`, `is_file`, `readfile`, `file_get_contents`) en el flujo del detalle.
- [x] El detalle no realiza escrituras; el conteo de filas de las tablas involucradas es igual antes y después de la prueba.
- [x] Las pruebas ampliadas cubren: postulación existente, inexistente, `id` inválido, sin recaudos, con recaudos disponibles y no disponibles, exclusión de inactivos, orden por catálogo y ausencia de rutas físicas.
- [x] Las pruebas de `PostulacionesAdminServiceTest` pasan con `vendor/bin/phpunit tests/app/Libraries/Inscripciones/NuevoIngreso/Admin/PostulacionesAdminServiceTest.php`.
- [x] Se ejecuta `php -l` sobre `PostulacionesAdminService.php` y sobre el modelo reutilizado sin errores de sintaxis.
- [x] No se modificaron rutas, controladores, vistas, migraciones, seeds, la SPA ni la API.

## Riesgos

- **Medio:** el detalle expone datos personales completos y sin enmascarar. El método no autoriza por sí mismo; el Slice 7 debe mantener la ruta bajo `adminPanel:module=inscripciones_ni` y no exponer el servicio por una ruta pública.
- **Bajo:** agregar una dependencia opcional de `NiInscripcionRecaudoModel` al constructor puede afectar pruebas si no se conserva la compatibilidad de los dos parámetros actuales. Se mitiga con parámetros opcionales y pruebas de regresión del listado.
- **Bajo:** `obtenerRecaudosPorInscripcion()` devuelve `archivo_path`; la transformación debe descartarlo explícitamente. Una prueba debe verificar de forma recursiva que no se filtre.
- **Bajo:** el join con el catálogo es interno en el modelo; un recaudo activo sin fila de catálogo no aparecería. La llave foránea `recaudo_id` con `RESTRICT` hace que ese caso no sea esperado.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-30 | Especificación inicial del detalle de postulación con recaudos digitales para el Slice 6. Se cierra el contrato de retorno, la regla de disponibilidad, el orden y el manejo de `id` inválido. | opencode (agente) |
