# Documentos presenciales pendientes en el pago aprobado

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

## Objetivo

Mostrar en el Paso 4 de nuevo ingreso, dentro del bloque de pago aprobado y junto a las descargas, la lista de documentos que el aspirante debe entregar de forma presencial en la sede, con la fecha límite calculada en 15 días hábiles desde la aprobación del pago. La lista es informativa, se calcula por carrera y no registra entregas.

## Alcance

- **Incluye:**
  - Crear un catálogo global de documentos presenciales en dos tablas nuevas: `ni_documentos_presenciales` y `ni_documentos_presenciales_carreras`.
  - Permitir documentos globales (sin carreras asociadas) y documentos exclusivos de una o varias carreras mediante una relación N:M.
  - Crear el seeder idempotente con los siete documentos solicitados y la asociación del certificado de salud mental a Enfermería, Psicopedagogía y Preescolar.
  - Registrar la migración y el seeder en el flujo `init:principal` y en los datos de demostración.
  - Crear un modelo de consulta que resuelva los documentos aplicables a la carrera de la postulación y una calculadora pura que calcule la fecha límite.
  - Inyectar el listado y el plazo en `Paso3::index()` solo cuando el estado sea `aprobado` (estados 3 y 8).
  - Mostrar en `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php`, dentro del bloque de pago aprobado y arriba del enlace "Ver intentos de pago", una sección con título, lista de documentos y fecha límite.
  - Ocultar la sección cuando no haya documentos aplicables.
  - Marcar visualmente el plazo como vencido cuando la fecha límite ya pasó.
  - Cubrir el modelo, la calculadora, las migraciones, el seeder y la vista con pruebas.

- **No incluye:**
  - Registrar qué documentos entregó el estudiante, marcar recibidos, cambiar estados de entrega ni crear una tabla pivote por postulación.
  - Crear una pantalla de administración para el catálogo; los cambios se hacen por migración, seeder o base de datos.
  - Definir documentos por sede; el catálogo es global para todas las sedes.
  - Descontar feriados nacionales o regionales; solo se excluyen sábados y domingos.
  - Hacer configurable el plazo de 15 días hábiles; queda como constante de negocio.
  - Mostrar la lista en el PDF de la planilla, en el recibo, en correos, en GHL o en la API.
  - Modificar los recaudos digitales de `ni_recaudos`, `ni_inscripciones_recaudos`, el Paso 1 o su flujo no bloqueante.
  - Mostrar el nombre o la dirección de la sede, instrucciones adicionales o enlaces de contacto.
  - Mostrar la sección en estados distintos de `aprobado` (creado, pagando, pendiente, reintento, cancelado o sin intención).
  - Agregar CSRF a una pantalla de solo lectura, cambiar rutas, filtros o sesión.
  - Modificar `vendor/`, `public/vendor/`, `system/` o `app/ThirdParty/`.

> **Evaluación de alcance:** la feature es una sola capacidad de negocio: informar documentos presenciales pendientes en el pago aprobado. Las tablas y el seeder existen únicamente para soportar esa visualización y no aportan valor por separado; por eso se mantiene un único documento con tres fases internas (datos, consulta/regla y vista). No se recomienda dividirla.

## Contexto y supuestos

- La rama de trabajo es `feature/desacoplar-contructor-pagos`, con FEAT-001 a FEAT-009 implementadas o especificadas para el flujo de pago de nuevo ingreso.
- El bloque final ya existe en `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` y muestra el mensaje "Pago aprobado con éxito", el monto, la referencia, el enlace "Ver intentos de pago" y los botones "Descargar recibo" y "Descargar planilla de inscripción".
- Los recaudos digitales (`ni_recaudos`, `ni_inscripciones_recaudos`) son un concepto distinto de esta feature. No se reutilizan ni se modifican; la nueva lista es de documentos físicos.
- Hoy no existe ningún campo ni tabla que distinga documentos presenciales. Por eso se crean dos tablas nuevas en la base principal (`default`).
- La consulta vive en `NiDocumentoPresencialModel`, siguiendo el precedente de `NiInscripcionRecaudoModel` (`obtenerRecaudosPorInscripcion()`). El cálculo de días hábiles vive en una clase pura, `CalculadoraPlazoEntrega`, sin base de datos. No se crea un servicio ni se registra nada nuevo en `Services`.
- La carrera de la postulación se obtiene de `Services::nuevoIngresoContext()->resolver()['carrera_id']`, que a su vez sale de `ni_inscripciones.sucursal_carrera_id` y `es_sucursales_carreras`. No se acepta una carrera enviada por el cliente.
- La fecha base del plazo es `pg_intenciones_pago.actualizado_dt` de la intención aprobada. Si está vacía, se usa `pg_intenciones_pago.fecha` como respaldo. Ambos campos ya existen.
- `actualizado_dt` se actualiza cuando el pago pasa a estado 3 (aprobado) u 8 (verificado), según `NuevoIngresoPagoService::cambiarEstado()`. Se asume que no se sobrescribe después con una operación posterior que cambie el plazo.
- Los 15 días hábiles se cuentan de lunes a viernes, sin feriados. El día siguiente hábil a la aprobación es el día 1; si la aprobación es viernes, el conteo inicia el lunes siguiente.
- La fecha límite se calcula y se compara con el día actual en la zona `America/Caracas`. El valor almacenado se toma por su componente de fecha (`Y-m-d`), sin convertir la hora desde `America/Chicago`; se asume que la fecha guardada representa el día calendario de la aprobación.
- El catálogo es global, no por sede, y se ordena por la columna `orden` y luego por `id`.
- Un documento sin filas en `ni_documentos_presenciales_carreras` es global y aplica a todas las carreras. Un documento con una o más filas es exclusivo de esas carreras.
- La lista es de solo lectura y se muestra completa cada vez que se abre el Paso 4 en estado aprobado. No hay seguimiento de entregas, por lo que todos los documentos aplicables se consideran pendientes.
- El título propuesto es "Documentos pendientes para entrega presencial"; se marca como supuesto sujeto a validación de negocio.
- Los textos de los documentos se transcriben de la petición del usuario. "Fondo negro certificado debe tener timbre fiscal electrónico" se normaliza como "Fondo negro del certificado con timbre fiscal electrónico"; se marca como supuesto.
- El certificado de salud mental se asocia por `es_carreras.orbis_codigo`: `F` (Enfermería), `S` (Psicopedagogía) y `P` (Preescolar). La asociación usa IDs resueltos en el seeder, no nombres.
- `docs/features` contiene FEAT-001 a FEAT-009; FEAT-010 no colisiona. Se respeta el esquema del repositorio (`FEAT-NNN`) y el nombre de carpeta `NNN-slug`.
- Las pruebas de integración del Paso 4 pueden ejecutarse sin las tablas nuevas. El controlador debe degradar a lista vacía y registrar una advertencia, sin romper la página.

## Fases internas de implementación

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

1. **Fase A - Datos:** crear las migraciones de las dos tablas, el seeder idempotente, el registro en `init:principal` y la ejecución del seeder en los datos de demostración. Al finalizar, las tablas y los siete documentos existen en una base inicializada.
2. **Fase B - Consulta y regla:** crear `NiDocumentoPresencialModel` con `obtenerParaCarrera()` y `CalculadoraPlazoEntrega` con `calcular()`. No se registra nada en `Services`. Cubrir con pruebas la resolución por carrera y el cálculo de días hábiles. Esta fase no toca vistas.
3. **Fase C - Interfaz:** inyectar el listado y el plazo en `Paso3::index()`, pasarlos por `paso3/index.php` a `paso3/estado.php` y renderizar la sección. Cubrir con pruebas de integración.

## Flujo normal

1. Paso 1: El aspirante completa el pago y el sistema deja la intención en estado 3 (aprobado) u 8 (verificado).
2. Paso 2: El aspirante abre `GET /inscripciones/nuevo-ingreso/paso-4`. El filtro `nuevoIngresoAuth:4` valida la sesión `nuevo_ingreso` y `paso_actual >= 4`.
3. Paso 3: `Paso3::index()` resuelve el contexto de nuevo ingreso con `Services::nuevoIngresoContext()->resolver()` y obtiene `ni_inscripcion_id`, `carrera_id` y la conexión de la sede.
4. Paso 4: `Paso3::index()` resuelve la intención visible y deriva el estado con `NuevoIngresoPagoService::estadoDeIntencion()`. El estado es `aprobado` para las intenciones 3 y 8.
5. Paso 5: Si el estado no es `aprobado`, no se consultan documentos presenciales y se conserva el comportamiento actual.
6. Paso 6: Si el estado es `aprobado`, `Paso3::index()` instancia `NiDocumentoPresencialModel` y llama a `obtenerParaCarrera($carreraId)`.
7. Paso 7: El modelo consulta `ni_documentos_presenciales` con `activo = 1` y devuelve los documentos globales (sin filas en la tabla de carreras) más los asociados a la carrera de la postulación, ordenados por `orden` y `id`.
8. Paso 8: `Paso3::index()` instancia `CalculadoraPlazoEntrega` y llama a `calcular($intencion)`.
9. Paso 9: La calculadora toma `pg_intenciones_pago.actualizado_dt`; si está vacío, usa `pg_intenciones_pago.fecha`.
10. Paso 10: La calculadora suma 15 días hábiles de lunes a viernes, comenzando por el día hábil siguiente a la fecha base. Devuelve la fecha en formato `Y-m-d`, su texto `d/m/Y`, los días hábiles y si el plazo está vencido según el día actual en `America/Caracas`.
11. Paso 11: `Paso3::index()` pasa `documentos_presenciales` y `plazo_entrega` a `paso3/index.php`.
12. Paso 12: `paso3/index.php` incluye `paso3/estado.php` y le reenvía ambos arreglos.
13. Paso 13: En estado `aprobado`, `estado.php` muestra primero el bloque de éxito con monto y referencia; inmediatamente después, y antes del enlace "Ver intentos de pago", muestra la sección de documentos.
14. Paso 14: La sección muestra el título "Documentos pendientes para entrega presencial", una lista con un icono de casilla vacía y el nombre de cada documento, y la fecha límite en formato `dd/mm/aaaa`.
15. Paso 15: Si el plazo está vencido, la sección muestra además una insignia "Plazo vencido" junto a la fecha. La lista sigue visible.
16. Paso 16: Si `documentos_presenciales` está vacío, la sección completa no se renderiza; tampoco se muestra la fecha límite.
17. Paso 17: Si no se pudo resolver la fecha base, se muestran los documentos sin la línea de fecha límite y se registra una advertencia en el log.
18. Paso 18: La operación es de solo lectura: no escribe en base de datos, no modifica la intención, no marca documentos y no altera `paso_actual`.
19. Paso 19: Si el aspirante recarga el Paso 4, la lista y el plazo se recalculan con los mismos datos persistidos y se muestran de nuevo mientras el pago siga aprobado.

## Flujos alternativos / variantes

### Documento exclusivo de la carrera del aspirante

1. Paso 1: El documento tiene al menos una fila en `ni_documentos_presenciales_carreras`.
2. Paso 2: Una de esas filas coincide con el `carrera_id` de la postulación.
3. Paso 3: `obtenerParaCarrera()` incluye el documento en la lista.
4. Paso 4: El aspirante de Enfermería, Psicopedagogía o Preescolar ve el certificado de salud mental; el resto de las carreras no lo ve.

### Documento exclusivo de otra carrera

1. Paso 1: El documento tiene filas de asociación, pero ninguna coincide con el `carrera_id` de la postulación.
2. Paso 2: La condición `EXISTS` de la carrera no se cumple y la condición de global tampoco.
3. Paso 3: El documento no se devuelve ni se muestra.
4. Paso 4: No se revela su existencia ni su nombre.

### Documento global

1. Paso 1: El documento no tiene filas en `ni_documentos_presenciales_carreras`.
2. Paso 2: La condición `NOT EXISTS` se cumple para cualquier carrera.
3. Paso 3: El documento aparece para todas las carreras, incluidas las que no tienen documentos exclusivos.
4. Paso 4: Se ordena según `orden` y luego `id`.

### Pago verificado por Zelle (estado 8)

1. Paso 1: La intención está en estado 8 y `estaAprobada()` devuelve verdadero.
2. Paso 2: `Paso3::index()` deriva el estado `aprobado` y consulta los documentos.
3. Paso 3: El plazo se calcula con el `actualizado_dt` de la verificación.
4. Paso 4: La sección se muestra igual que para el estado 3.

### Plazo vencido

1. Paso 1: La fecha límite calculada es anterior al día actual en `America/Caracas`.
2. Paso 2: `calcular()` devuelve `vencida = true`.
3. Paso 3: La sección mantiene la lista y la fecha límite, y agrega la insignia "Plazo vencido".
4. Paso 4: No se oculta la sección ni se bloquea ninguna descarga.

### Fecha base ausente

1. Paso 1: `actualizado_dt` está vacío y `fecha` también.
2. Paso 2: `calcular()` devuelve `null` y registra una advertencia.
3. Paso 3: La sección muestra los documentos aplicables sin la línea de fecha límite.
4. Paso 4: La página no falla y las descargas siguen disponibles.

### Respaldo con `fecha`

1. Paso 1: `actualizado_dt` está vacío, pero `fecha` tiene un valor válido.
2. Paso 2: La calculadora usa `fecha` como fecha base y calcula el plazo.
3. Paso 3: La sección muestra la fecha límite calculada.
4. Paso 4: Se registra una advertencia indicando que se usó el respaldo.

### Sin documentos aplicables

1. Paso 1: No hay documentos activos, o todos los activos son exclusivos de otras carreras.
2. Paso 2: `obtenerParaCarrera()` devuelve un arreglo vacío.
3. Paso 3: `estado.php` no renderiza la sección ni la fecha límite.
4. Paso 4: El resto del bloque de éxito y las descargas no cambian.

### Carrera no resuelta o igual a cero

1. Paso 1: El contexto no devuelve un `carrera_id` positivo.
2. Paso 2: `NiDocumentoPresencialModel::obtenerParaCarrera()` usa un identificador imposible y devuelve solo los documentos globales; registra una advertencia.
3. Paso 3: La sección se muestra con los documentos globales, sin los exclusivos.
4. Paso 4: No se consulta ni se muestra un documento de una carrera desconocida.

### Fallo de base de datos o tablas no migradas

1. Paso 1: La consulta de documentos falla porque las tablas no existen o la base no responde.
2. Paso 2: `Paso3::index()` captura `\Throwable`, registra una advertencia sin datos personales y deja la lista vacía.
3. Paso 3: `estado.php` oculta la sección.
4. Paso 4: El Paso 4 sigue cargando y las descargas de recibo y planilla no se ven afectadas.

### Recarga del Paso 4

1. Paso 1: El aspirante recarga la página en estado aprobado.
2. Paso 2: El controlador vuelve a consultar el catálogo y a calcular el plazo.
3. Paso 3: La lista y la fecha se muestran con los mismos valores persistidos.
4. Paso 4: No se crea historial, caché ni registro de visualización.

## 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 sección; sin escritura |
| `paso_actual` menor a 4 | Filtro; `sesionValida()` | Redirección a `/inscripciones/nuevo-ingreso/materias`; en AJAX 403 | Sin sección |
| Estado distinto de `aprobado` | `estadoDeIntencion()` | No se consultan documentos; se conserva el bloque actual | Sin sección |
| Intención ausente | `$intencion === null` | No se consultan documentos ni plazo | Sin sección |
| `carrera_id` no resuelto o igual a cero | Validación del modelo | Solo documentos globales; advertencia en log | Sección parcial, sin exclusivos |
| Tabla `ni_documentos_presenciales` inexistente | Excepción de base de datos | `Paso3::index()` captura, registra advertencia y deja la lista vacía | Sección oculta; página operativa |
| Tabla `ni_documentos_presenciales_carreras` inexistente | Excepción de base de datos | Igual que el caso anterior | Sección oculta; página operativa |
| Catálogo vacío | Consulta sin filas | Arreglo vacío | Sección oculta |
| Documento inactivo | Filtro `activo = 1` | No se devuelve | No se muestra |
| Documento exclusivo de otra carrera | `EXISTS` sobre la carrera de la postulación | No se devuelve | No se muestra ni se revela |
| `actualizado_dt` vacío y `fecha` válida | Respaldo de la calculadora | Se calcula con `fecha`; advertencia en log | Lista con fecha límite |
| `actualizado_dt` y `fecha` vacíos o inválidos | Validación de la calculadora | `plazo = null`; advertencia en log | Lista sin fecha límite |
| Fecha límite anterior al día actual | Comparación en `America/Caracas` | `vencida = true`; insignia "Plazo vencido" | Lista y fecha visibles |
| Cambio manual del catálogo | No aplica | Se refleja en la siguiente carga del Paso 4; no hay caché | Sin escritura |
| Seeder ejecutado dos veces | Upsert por nombre y por par documento-carrera | No duplica filas ni asociaciones | Idempotente |
| Carrera del seeder inexistente | Búsqueda por `orbis_codigo` sin fila | Se omite la asociación y se registra advertencia; el documento queda global | Seed no falla |
| Error inesperado al renderizar la vista | Revisión de la vista y pruebas | La vista no debe lanzar excepciones; los datos se escapan con `esc()` | Página operativa |
| Regresión del bloque de éxito | Pruebas de integración existentes | El mensaje, monto, referencia y descargas siguen presentes | Sin cambio funcional |

## Reglas de negocio y validaciones

- La sección solo se evalúa y muestra cuando el estado derivado es `aprobado`, es decir, cuando `estados_id` es `3` u `8`.
- La lista se calcula con la carrera de la postulación (`carrera_id` del contexto) y nunca con un parámetro enviado por el cliente.
- Un documento sin asociaciones es global. Un documento con al menos una asociación es exclusivo de las carreras asociadas.
- Solo se consideran documentos con `activo = 1`.
- El orden visible es `orden ASC, id ASC`.
- El catálogo es global para todas las sedes; no se filtra por `AASUCURSID`.
- La lista muestra todos los documentos aplicables cada vez. No hay seguimiento de entregas ni descuento de documentos ya recibidos.
- La lista es de solo lectura: no tiene checkboxes funcionales, botones, formularios, endpoints de escritura ni JavaScript nuevo.
- El título de la sección es "Documentos pendientes para entrega presencial".
- Cada elemento muestra un icono de casilla vacía y el nombre del documento. No se muestra la descripción en esta feature.
- La fecha límite se muestra como "Fecha límite de entrega: dd/mm/aaaa".
- Si la fecha límite ya pasó, se agrega la insignia "Plazo vencido" y la lista permanece visible.
- Si no hay documentos aplicables, no se renderiza la sección ni la fecha límite.
- Si no hay fecha base válida, se muestran los documentos sin la línea de fecha límite.
- El plazo es de 15 días hábiles, de lunes a viernes, sin feriados.
- El día siguiente hábil a la aprobación es el día 1. Si la aprobación es viernes, el conteo inicia el lunes siguiente.
- La fecha base es `actualizado_dt` de la intención aprobada. Si está vacía, se usa `fecha`. Si ambas faltan o son inválidas, no hay plazo.
- La fecha límite y la condición de vencida se calculan con la zona `America/Caracas`.
- El valor almacenado se interpreta por su componente de fecha (`Y-m-d`); no se convierte la hora desde la zona de la aplicación.
- El modelo y la calculadora no escriben en base de datos, no actualizan la intención, no modifican `paso_actual`, no crean reportes, no marcan GHL y no sincronizan Orbis.
- El controlador degrada a lista vacía ante cualquier error del modelo o de la calculadora, para no romper el Paso 4 ni las descargas.
- La vista escapa toda salida con `esc()`. Los nombres provienen de la base, no del cliente.
- No se modifica el bloque de éxito existente más allá de insertar la nueva sección antes del enlace "Ver intentos de pago".
- No se agregan dependencias, rutas, filtros, CSRF, migraciones de sucursal ni cambios de sesión.
- La feature depende de que las migraciones se hayan aplicado. Si no se aplicaron, la sección se oculta y se registra una advertencia.

## Contratos y diseño propuesto

### Tabla `ni_documentos_presenciales`

| Columna | Tipo | Nulo | Valor por defecto | Regla |
| --- | --- | --- | --- | --- |
| `id` | INT(11) AUTO_INCREMENT | No | — | Clave primaria. |
| `nombre` | VARCHAR(150) | No | — | Único; texto visible del documento. |
| `descripcion` | VARCHAR(255) | Sí | NULL | Reservado para futuras features; no se muestra. |
| `orden` | INT(11) | No | 0 | Orden ascendente de la lista. |
| `activo` | TINYINT(1) | No | 1 | Solo los activos se muestran. |
| `created_at` | DATETIME | Sí | CURRENT_TIMESTAMP | Auditoría básica. |
| `updated_at` | DATETIME | Sí | NULL | Auditoría básica. |

- Motor InnoDB, `utf8mb4`, `utf8mb4_general_ci`.
- Clave única en `nombre`.
- Migración idempotente con `createTable($tabla, true, $opciones)`.

### Tabla `ni_documentos_presenciales_carreras`

| Columna | Tipo | Nulo | Valor por defecto | Regla |
| --- | --- | --- | --- | --- |
| `id` | INT(11) AUTO_INCREMENT | No | — | Clave primaria. |
| `documento_id` | INT(11) | No | — | FK a `ni_documentos_presenciales.id`, `ON DELETE CASCADE`. |
| `carrera_id` | INT(11) | No | — | FK a `es_carreras.id`, `ON DELETE CASCADE`. |
| `created_at` | DATETIME | Sí | CURRENT_TIMESTAMP | Auditoría básica. |
| `updated_at` | DATETIME | Sí | NULL | Auditoría básica. |

- Clave única compuesta (`documento_id`, `carrera_id`).
- Índices individuales en `documento_id` y `carrera_id`.
- Motor InnoDB, `utf8mb4`, `utf8mb4_general_ci`.
- Migración idempotente con `createTable($tabla, true, $opciones)`.

### Catálogo inicial del seeder

| Orden | Nombre | Carreras asociadas |
| --- | --- | --- |
| 1 | Fondo negro del certificado con timbre fiscal electrónico | Global |
| 2 | Notas certificadas con timbre fiscal electrónico | Global |
| 3 | Registro OPSU | Global |
| 4 | Partida de nacimiento original | Global |
| 5 | 2 copias de la cédula de identidad centrada, ampliada y vigente | Global |
| 6 | 1 foto tipo carnet | Global |
| 7 | Certificado de salud mental emitido por ente público | Enfermería (`F`), Psicopedagogía (`S`), Preescolar (`P`) |

- El seeder hace upsert por `nombre` para los documentos y por (`documento_id`, `carrera_id`) para las asociaciones.
- No elimina asociaciones manuales existentes.
- Resuelve las carreras por `es_carreras.orbis_codigo`; si no existen, omite la asociación y registra una advertencia.
- El nombre del seeder es `NiDocumentosPresencialesSeeder`.
- Se registra en `InitPrincipalDb::run()` y se ejecuta desde `PrincipalDemoSeeder::seedBase()` para que `init:principal` y `demo:seed` garanticen el catálogo.

### `NiDocumentoPresencialModel`

Ubicación: `app/Models/Inscripciones/NiDocumentoPresencialModel.php`.

- Extiende `CodeIgniter\Model`.
- `protected $table = 'ni_documentos_presenciales'`, `$primaryKey = 'id'`, `$returnType = 'array'`, `$useSoftDeletes = false` y `$useTimestamps = true`.
- `$allowedFields` incluye `nombre`, `descripcion`, `orden`, `activo`, `created_at` y `updated_at`.
- Método `obtenerParaCarrera(int $carreraId): array`:
  - Devuelve las columnas `id`, `nombre`, `descripcion` y `orden`.
  - Filtra `activo = 1`.
  - Aplica la regla global/exclusivo con subconsultas:
    ```sql
    activo = 1 AND (
      id NOT IN (SELECT documento_id FROM ni_documentos_presenciales_carreras)
      OR id IN (SELECT documento_id FROM ni_documentos_presenciales_carreras WHERE carrera_id = ?)
    )
    ORDER BY orden ASC, id ASC
    ```
  - Si `$carreraId <= 0`, usa un identificador imposible para devolver solo los documentos globales.
  - Usa query builder y bindings, o un cast `(int)`, para el identificador; no concatena valores del cliente.
- No conoce sesión, ruta, vista, controlador, PDF ni cálculo de fechas.

### `CalculadoraPlazoEntrega`

Ubicación: `app/Libraries/Inscripciones/NuevoIngreso/Documentos/CalculadoraPlazoEntrega.php`.

| Método | Responsabilidad | Efectos |
| --- | --- | --- |
| `calcular(array $intencion, ?DateTimeImmutable $hoy = null): ?array` | Calcular la fecha límite de 15 días hábiles y si está vencida. | Solo lectura; puede registrar advertencias. |

- Clase pura, sin base de datos, sin sesión, sin ruta y sin vista.
- Constante `DIAS_HABILES = 15`.
- Toma `actualizado_dt` de la intención; si está vacío, usa `fecha`.
- Devuelve:
  ```php
  [
      'fecha_limite'       => '2026-11-20',
      'fecha_limite_texto' => '20/11/2026',
      'vencida'            => false,
      'dias_habiles'       => 15,
  ]
  ```
  o `null` si no hay fecha base válida.
- Crea un `DateTimeImmutable` con la fecha base en `America/Caracas`, avanza día por día y descuenta solo de lunes a viernes hasta completar 15. El primer día contado es el siguiente hábil.
- `$hoy` es inyectable para pruebas; por defecto se calcula con `new DateTimeImmutable('today', new DateTimeZone('America/Caracas'))`.
- Registra advertencias cuando falta la fecha base o cuando usa el respaldo `fecha`.

### Controlador y vistas

| Componente | Cambio |
| --- | --- |
| `Paso3::index()` | Si `estado === 'aprobado'` e `intencion !== null`, instanciar `NiDocumentoPresencialModel` y `CalculadoraPlazoEntrega`, consultar dentro de un `try/catch` y pasar `documentos_presenciales` y `plazo_entrega` a la vista. |
| `app/Views/inscripciones/nuevo_ingreso/paso3/index.php` | Reenviar `documentos_presenciales` y `plazo_entrega` a `paso3/estado.php`. |
| `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` | Insertar la sección de documentos entre el bloque de éxito y el enlace "Ver intentos de pago". |

- Variables de vista: `$documentos_presenciales` (arreglo) y `$plazo_entrega` (`array|null`).
- La sección usa Tailwind existente, `esc()` y el icono `check_box_outline_blank` o `description`.
- No se agrega JavaScript, formulario ni endpoint.
- Si `$documentos_presenciales` está vacío, no se renderiza nada.
- Si `$plazo_entrega` es nulo o no tiene `fecha_limite_texto`, se omite la línea de fecha.
- Si `$plazo_entrega['vencida']` es verdadero, se muestra la insignia "Plazo vencido".

## Áreas afectadas

| Acción | Archivo / componente | Motivo |
| --- | --- | --- |
| Crear | `app/Database/Migrations/2026-10-29-000102_CreateNiDocumentosPresenciales.php` | Catálogo global de documentos presenciales. |
| Crear | `app/Database/Migrations/2026-10-29-000103_CreateNiDocumentosPresencialesCarreras.php` | Relación N:M documento-carrera. |
| Crear | `app/Database/Seeds/NiDocumentosPresencialesSeeder.php` | Catálogo inicial idempotente. |
| Modificar | `app/Commands/InitPrincipalDb.php` | Registrar las migraciones y el seeder en `init:principal`. |
| Modificar | `app/Database/Seeds/Demo/PrincipalDemoSeeder.php` | Ejecutar el seeder en `demo:seed`. |
| Crear | `app/Models/Inscripciones/NiDocumentoPresencialModel.php` | Consulta de documentos globales y por carrera. |
| Crear | `app/Libraries/Inscripciones/NuevoIngreso/Documentos/CalculadoraPlazoEntrega.php` | Cálculo puro de los 15 días hábiles. |
| Modificar | `app/Controllers/Inscripciones/NuevoIngreso/Paso3.php` | Instanciar modelo y calculadora e inyectar documentos y plazo en estado aprobado. |
| Modificar | `app/Views/inscripciones/nuevo_ingreso/paso3/index.php` | Reenviar los datos a `estado.php`. |
| Modificar | `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` | Renderizar la sección antes de "Ver intentos de pago". |
| Crear | `tests/app/Database/Migrations/DocumentosPresencialesMigrationTest.php` | Tablas, índices, claves e idempotencia. |
| Crear | `tests/app/Database/Seeds/NiDocumentosPresencialesSeederTest.php` | Siete documentos, tres asociaciones e idempotencia. |
| Crear | `tests/app/Models/Inscripciones/NiDocumentoPresencialModelTest.php` | Filtrado por carrera, globales, activos y orden. |
| Crear | `tests/app/Libraries/Inscripciones/NuevoIngreso/Documentos/CalculadoraPlazoEntregaTest.php` | Días hábiles, respaldo, fecha ausente y vencimiento. |
| Crear | `tests/app/Integration/Paso4DocumentosPresencialesTest.php` | Visibilidad, ocultamiento, estado no aprobado y fecha límite. |
| Documentar | `docs/features/010-documentos-presenciales-pendientes-pago-aprobado/plan.md` | Este plan. |

No se modifican `ni_recaudos`, `ni_inscripciones_recaudos`, `Paso1`, `NuevoIngresoPagoService`, `NuevoIngresoReciboService`, `NuevoIngresoPlanillaService`, `Reportes::Recibo`, `Imprimir::planilla()`, rutas, filtros, la SPA ni la API. No se agregan dependencias.

## Criterios de finalización

- [ ] La migración `000102` crea `ni_documentos_presenciales` con `id`, `nombre`, `descripcion`, `orden`, `activo`, `created_at` y `updated_at`, clave única en `nombre` e idempotencia.
- [ ] La migración `000103` crea `ni_documentos_presenciales_carreras` con clave única (`documento_id`, `carrera_id`), índices y claves foráneas a `ni_documentos_presenciales` y `es_carreras`.
- [ ] Ambas migraciones se pueden ejecutar dos veces sin error y se registran en `InitPrincipalDb::runPrincipalMigrations()`.
- [ ] `NiDocumentosPresencialesSeeder` inserta los siete documentos con el orden indicado y tres asociaciones para el certificado de salud mental (`F`, `S`, `P`).
- [ ] Ejecutar el seeder dos veces no duplica documentos ni asociaciones.
- [ ] El seeder se registra en `InitPrincipalDb::run()` y se ejecuta desde `PrincipalDemoSeeder::seedBase()`.
- [ ] `NiDocumentoPresencialModel::obtenerParaCarrera()` devuelve los documentos globales y los de la carrera indicada.
- [ ] Un documento exclusivo de otra carrera no se devuelve ni se muestra.
- [ ] Los documentos inactivos no se devuelven.
- [ ] El orden devuelto respeta `orden ASC, id ASC`.
- [ ] `CalculadoraPlazoEntrega::calcular()` calcula 15 días hábiles de lunes a viernes; una aprobación el viernes 2026-10-30 produce como fecha límite el viernes 2026-11-20.
- [ ] `CalculadoraPlazoEntrega::calcular()` usa `fecha` cuando `actualizado_dt` está vacío y devuelve `null` cuando ambas faltan o son inválidas.
- [ ] `CalculadoraPlazoEntrega::calcular()` marca `vencida = true` cuando la fecha límite es anterior al día actual en `America/Caracas` y `false` el mismo día de la fecha límite.
- [ ] `Paso3::index()` instancia el modelo y la calculadora directamente; no se agregó un servicio ni un registro en `Services`.
- [ ] `Paso3::index()` solo consulta documentos y plazo cuando el estado es `aprobado`; en otros estados no ejecuta la consulta.
- [ ] Un fallo de base de datos o una tabla no migrada deja la lista vacía, registra una advertencia y no rompe el Paso 4.
- [ ] La sección se renderiza dentro del bloque de pago aprobado y antes del enlace "Ver intentos de pago".
- [ ] La sección muestra el título, la lista de documentos y la fecha límite en formato `dd/mm/aaaa`.
- [ ] La sección no se muestra cuando no hay documentos aplicables.
- [ ] La sección se muestra sin línea de fecha cuando no hay fecha base válida.
- [ ] La insignia "Plazo vencido" aparece solo cuando el plazo venció y la lista permanece visible.
- [ ] La lista es de solo lectura: no hay checkboxes funcionales, formularios, JavaScript ni endpoints nuevos.
- [ ] La vista escapa los nombres de los documentos con `esc()`.
- [ ] La operación no escribe en base de datos, no modifica la intención ni `paso_actual` y es idempotente ante recargas.
- [ ] El bloque de éxito conserva el mensaje, el monto, la referencia, el enlace "Ver intentos de pago" y los botones de recibo y planilla.
- [ ] Las pruebas de `Paso4NuevoIngresoTest`, `Paso4ReciboTest`, `Paso4PagoTest`, `Paso4PlanillaTest` y `ZelleNuevoIngresoTest` siguen pasando.
- [ ] Las pruebas nuevas del modelo, la calculadora, las migraciones, el seeder y la integración cubren los casos indicados.
- [ ] `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, rutas, filtros, CSRF, migraciones de sucursal ni cambios en `vendor/`, `system/` o `public/vendor/`.

## Decisiones de la entrevista

| Tema | Decisión |
| --- | --- |
| Origen de la lista | Tabla nueva con los siete documentos físicos indicados por el usuario. |
| Relación con carreras | N:M; sin asociaciones = global; con asociaciones = exclusivo de esas carreras. |
| Documento condicional | Certificado de salud mental solo para Enfermería, Psicopedagogía y Preescolar. |
| Interactividad | Solo lectura; sin marcación persistente. |
| Ubicación | Dentro del bloque de pago aprobado, arriba del enlace "Ver intentos de pago". |
| Estados | Solo pago aprobado o verificado (3 y 8). |
| Sin documentos | Ocultar la sección completa. |
| Administración | Migración, seeder y demo; sin pantalla de administración. |
| Capa de datos | `NiDocumentoPresencialModel` para la consulta y `CalculadoraPlazoEntrega` pura para el plazo; sin servicio ni registro en `Services`. |
| Alcance por sede | Global para todas las sedes. |
| Días hábiles | Lunes a viernes, sin feriados. |
| Inicio del conteo | El día siguiente hábil es el día 1. |
| Fecha base | `actualizado_dt` de la intención aprobada; respaldo `fecha`. |
| Zona horaria | `America/Caracas` para la fecha límite y el vencimiento. |
| Cantidades | Incluidas en el nombre del documento. |
| Texto de la sección | Solo título, lista y fecha límite. |
| Plazo vencido | Mantener la lista y marcar el plazo como vencido. |
| División del alcance | No se recomienda dividir; es una sola capacidad con tres fases internas. |

## Riesgos y deuda técnica

- **Sin seguimiento de entregas:** como no se registra qué documentos recibió la sede, todos los aplicables se muestran siempre. Un documento ya entregado seguirá apareciendo como pendiente. La solución requiere una tabla pivote por postulación y un flujo de marcado, que es una feature aparte.
- **Catálogo sin administración:** cambiar, desactivar o reordenar documentos exige una migración, un seeder o una edición manual de base de datos. Una pantalla CRUD es una funcionalidad independiente.
- **Asociación N:M y borrado de carreras:** si se eliminan todas las carreras asociadas a un documento, la fila del documento queda sin asociaciones y pasa a ser global. Se recomienda desactivar carreras con `es_carreras.activo` antes que borrarlas, o agregar en el futuro una columna `es_global` explícita.
- **Sin feriados:** el cálculo solo excluye fines de semana. Si negocio exige feriados venezolanos, se necesita un calendario y su mantenimiento.
- **Plazo fijo:** los 15 días hábiles están en una constante. Si el plazo cambia por periodo o sede, habrá que moverlo a configuración.
- **Zona horaria y fecha almacenada:** la fecha base se toma por su componente `Y-m-d` y no se convierte desde `America/Chicago`. Cerca de la medianoche, la fecha de aprobación percibida podría diferir en un día. Debe validarse en el smoke test.
- **`actualizado_dt` mutable:** es la única marca disponible de la aprobación. Si una operación posterior actualiza la intención, el plazo se recalcularía. Si eso ocurre, se debe agregar una columna específica de fecha de aprobación.
- **Nombre del primer documento:** "Fondo negro del certificado con timbre fiscal electrónico" es una normalización del texto original. Debe confirmarse con negocio.
- **Degradación silenciosa:** si las tablas no están migradas, la sección se oculta. Esto evita romper el Paso 4, pero puede pasar inadvertido en producción; el log es la única señal.
- **Dependencia de la carrera del contexto:** si el contexto cambia o la relación carrera/sede se desactiva, el listado puede quedar solo con los documentos globales. El flujo actual ya bloquea el Paso 4 en esos casos, pero debe revisarse.
- **Sin caché:** cada carga del Paso 4 ejecuta dos consultas. Es aceptable por el bajo volumen y evita datos obsoletos.

## Preguntas abiertas y supuestos a validar

- Se asume que el título "Documentos pendientes para entrega presencial" es el texto deseado.
- Se asume que "Fondo negro certificado debe tener timbre fiscal electrónico" se muestra como "Fondo negro del certificado con timbre fiscal electrónico".
- Se asume que las siete filas se muestran en el orden transcrito.
- Se asume que el certificado de salud mental no necesita mostrar la aclaratoria de carreras porque la lista ya se filtra por carrera.
- Se asume que la fecha límite se muestra como `dd/mm/aaaa` y que la insignia "Plazo vencido" es suficiente, sin cambiar el color de toda la sección.
- Se asume que el día de aprobación no cuenta y que el primer día hábil siguiente es el día 1.
- Se asume que no se descuentan feriados.
- Se asume que `actualizado_dt` representa la fecha de aprobación y que no se sobrescribe después.
- Se asume que la lista debe ocultarse por completo si no hay documentos, incluida la fecha límite.
- Se asume que no se requiere mostrar la sede ni instrucciones de entrega en esta iteración.
- Se asume que el catálogo es global y que no se necesita configuración por sucursal.
- Se asume que no se requiere auditoría de visualización ni de descargas.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-29 | Creación del plan FEAT-010 tras revisar `Paso3`, `paso3/estado.php`, `paso3/index.php`, `NuevoIngresoContextService`, `NuevoIngresoPagoService`, las migraciones de `ni_recaudos`/`ni_inscripciones_recaudos`, `NiRecaudosSeeder`, `EsCarrerasSeeder`, `InitPrincipalDb` y `PrincipalDemoSeeder`. La entrevista definió: catálogo nuevo en dos tablas, relación N:M con regla global/exclusivo, solo lectura, visible solo en pago aprobado, arriba de "Ver intentos de pago", ocultar sin documentos, 15 días hábiles de lunes a viernes, conteo desde el día siguiente hábil, fecha base `actualizado_dt` con respaldo `fecha`, zona `America/Caracas` y mostrar "Plazo vencido". | opencode (agente) |
| 2026-10-29 | Ajuste de diseño: se elimina `DocumentosPresencialesService` y su registro en `Services`. La consulta pasa a `NiDocumentoPresencialModel::obtenerParaCarrera()` y el cálculo de días hábiles a la clase pura `CalculadoraPlazoEntrega::calcular()`. Se actualizan flujos, contratos, áreas afectadas, criterios y pruebas. | opencode (agente) |
