# Prototipo de ejecución — FEAT-010 Documentos presenciales pendientes en el pago aprobado

- **Rama:** p-feature/documentos-presenciales-pendientes-pago-aprobado
- **Rama base:** feature/desacoplar-contructor-pagos
- **Plan:** docs/features/010-documentos-presenciales-pendientes-pago-aprobado/plan.md
- **Fecha:** 2026-10-29
- **Estado:** consolidado
- **Fecha de consolidación:** 2026-10-29
- **Rama destino:** feature/desacoplar-contructor-pagos

## Resumen
Se implementó la lista informativa de documentos que el aspirante debe entregar de forma presencial después de que su pago sea aprobado o verificado. La lista se resuelve por carrera desde un catálogo global con asociaciones N:M y se muestra en el Paso 4, dentro del bloque de éxito y antes del enlace "Ver intentos de pago", con la fecha límite calculada en 15 días hábiles. La operación es de solo lectura y no registra entregas.

## Tareas realizadas
- [x] Fase A: migraciones `000102` y `000103`, seeder idempotente, registro en `init:principal` y ejecución en `demo:seed`.
- [x] Fase B: `NiDocumentoPresencialModel::obtenerParaCarrera()` y `CalculadoraPlazoEntrega::calcular()` con pruebas unitarias.
- [x] Fase C: inyección en `Paso3::index()`, reenvío por `paso3/index.php` y renderizado en `paso3/estado.php`.
- [x] Pruebas de migraciones, seeder, modelo, calculadora e integración del Paso 4.
- [x] Verificación con `php -l`, pruebas del área y `graphify update .`.
- [x] Plan actualizado a estado `completado`.

## Criterios de aceptación
| Criterio | Cómo se verificó | Resultado |
| --- | --- | --- |
| La migración `000102` crea `ni_documentos_presenciales` con columnas, clave única en `nombre` e idempotencia. | `DocumentosPresencialesMigrationTest` (columnas, índice único y doble ejecución). | ok |
| La migración `000103` crea `ni_documentos_presenciales_carreras` con clave única compuesta, índices y FKs. | `DocumentosPresencialesMigrationTest` (índices y `PRAGMA foreign_key_list`). | ok |
| Ambas migraciones se ejecutan dos veces sin error y se registran en `InitPrincipalDb::runPrincipalMigrations()`. | Pruebas de idempotencia y revisión de `InitPrincipalDb`. | ok |
| El seeder inserta los siete documentos en orden y las tres asociaciones `F`, `S`, `P`. | `NiDocumentosPresencialesSeederTest`. | ok |
| Ejecutar el seeder dos veces no duplica documentos ni asociaciones. | `NiDocumentosPresencialesSeederTest::testEsIdempotente`. | ok |
| El seeder se registra en `InitPrincipalDb::run()` y en `PrincipalDemoSeeder::seedBase()`. | Revisión de ambos archivos. | ok |
| El modelo devuelve globales y exclusivos de la carrera indicada. | `NiDocumentoPresencialModelTest`. | ok |
| Un documento exclusivo de otra carrera no se devuelve ni se muestra. | Pruebas del modelo e integración. | ok |
| Los documentos inactivos no se devuelven. | `NiDocumentoPresencialModelTest::testExcluyeDocumentosInactivos`. | ok |
| El orden respeta `orden ASC, id ASC`. | Pruebas del modelo e integración. | ok |
| La calculadora suma 15 días hábiles; viernes 2026-10-30 produce 2026-11-20. | `CalculadoraPlazoEntregaTest`. | ok |
| La calculadora usa `fecha` como respaldo y devuelve `null` si ambas faltan o son inválidas. | `CalculadoraPlazoEntregaTest`. | ok |
| La calculadora marca `vencida` solo después de la fecha límite, no el mismo día. | `CalculadoraPlazoEntregaTest::testMarcaVencidaSoloDespuesDeLaFechaLimite`. | ok |
| `Paso3::index()` instancia el modelo y la calculadora directamente, sin servicio ni `Services`. | Revisión del controlador. | ok |
| Solo se consultan documentos y plazo cuando el estado es `aprobado`. | Prueba de integración con estados 2 y 7. | ok |
| Un fallo de base o tablas no migradas deja la lista vacía, registra advertencia y no rompe el Paso 4. | Prueba de integración que elimina las tablas y valida el bloque de éxito y las descargas. | ok |
| La sección se renderiza dentro del bloque aprobado y antes de "Ver intentos de pago". | Prueba de integración con comparación de posiciones. | ok |
| La sección muestra título, lista y fecha límite en `dd/mm/aaaa`. | Prueba de integración con `18/11/2026`. | ok |
| La sección no se muestra cuando no hay documentos aplicables. | Prueba de integración con catálogo vacío. | ok |
| La sección se muestra sin línea de fecha si no hay fecha base válida. | Prueba de integración con `actualizado_dt` y `fecha` nulos. | ok |
| La insignia "Plazo vencido" aparece solo al vencer y la lista permanece visible. | Prueba de integración con fecha base de 2020. | ok |
| La lista es de solo lectura: sin checkboxes funcionales, formularios, JavaScript ni endpoints nuevos. | Revisión de la vista y del controlador; no se agregaron rutas. | ok |
| La vista escapa los nombres con `esc()`. | Prueba de integración con un nombre que contiene `<script>`. | ok |
| La operación no escribe en base, no modifica la intención ni `paso_actual` y es idempotente ante recargas. | Prueba de integración con dos cargas y comparación de filas. | ok |
| El bloque de éxito conserva mensaje, monto, referencia, enlace y botones. | Pruebas existentes del Paso 4 y prueba de integración. | ok |
| Las pruebas de `Paso4NuevoIngresoTest`, `Paso4ReciboTest`, `Paso4PagoTest`, `Paso4PlanillaTest` y `ZelleNuevoIngresoTest` siguen pasando. | Ejecución individual de las cinco suites. | ok (sin regresiones; persiste un fallo preexistente de línea base en `Paso4NuevoIngresoTest`) |
| Las pruebas nuevas cubren modelo, calculadora, migraciones, seeder e integración. | 34 pruebas nuevas ejecutadas. | ok |
| `php -l` no reporta errores en archivos nuevos o modificados. | Ejecución sobre los diez archivos PHP tocados. | ok |
| `graphify update .` se ejecuta después de los cambios. | Ejecutado; grafo actualizado. | ok |
| No se agregaron dependencias, rutas, filtros, CSRF, migraciones de sucursal ni cambios en `vendor/`, `system/` o `public/vendor/`. | Revisión de `git status` y del diff. | ok |

## Flujos cubiertos
- **Flujo normal:** pago en estado 3 u 8, carrera resuelta desde el contexto, catálogo global y exclusivo, lista y fecha límite visibles antes de "Ver intentos de pago".
- **Flujos alternativos:** documento exclusivo de la carrera, documento exclusivo de otra carrera, documento global, pago verificado (8), plazo vencido, fecha base ausente, respaldo con `fecha`, catálogo vacío, carrera no resuelta y recarga idempotente.
- **Control de errores:** tablas no migradas o fallo de base capturado en el controlador; la sección se oculta y el Paso 4 conserva el bloque de éxito y las descargas.

## Archivos creados
| Archivo | Motivo |
| --- | --- |
| `app/Database/Migrations/2026-10-29-000102_CreateNiDocumentosPresenciales.php` | Catálogo global de documentos presenciales. |
| `app/Database/Migrations/2026-10-29-000103_CreateNiDocumentosPresencialesCarreras.php` | Relación N:M documento-carrera con FKs e índices. |
| `app/Database/Seeds/NiDocumentosPresencialesSeeder.php` | Catálogo inicial idempotente de siete documentos. |
| `app/Models/Inscripciones/NiDocumentoPresencialModel.php` | Consulta de documentos globales y por carrera. |
| `app/Libraries/Inscripciones/NuevoIngreso/Documentos/CalculadoraPlazoEntrega.php` | Cálculo puro de los 15 días hábiles y del vencimiento. |
| `tests/app/Database/Migrations/DocumentosPresencialesMigrationTest.php` | Pruebas de esquema e idempotencia. |
| `tests/app/Database/Seeds/NiDocumentosPresencialesSeederTest.php` | Pruebas de catálogo y asociaciones. |
| `tests/app/Models/Inscripciones/NiDocumentoPresencialModelTest.php` | Pruebas de filtrado por carrera y orden. |
| `tests/app/Libraries/Inscripciones/NuevoIngreso/Documentos/CalculadoraPlazoEntregaTest.php` | Pruebas de días hábiles, respaldo y vencimiento. |
| `tests/app/Integration/Paso4DocumentosPresencialesTest.php` | Pruebas de visibilidad, ocultamiento, plazo y no escritura. |
| `docs/features/010-documentos-presenciales-pendientes-pago-aprobado/prototipo.md` | Registro de esta ejecución. |

## Archivos modificados
| Archivo | Cambio realizado |
| --- | --- |
| `app/Commands/InitPrincipalDb.php` | Registro de las migraciones `000102` y `000103` y del seeder. |
| `app/Database/Seeds/Demo/PrincipalDemoSeeder.php` | Ejecución de `EsCarrerasSeeder` y `NiDocumentosPresencialesSeeder` en `seedBase()`. |
| `app/Controllers/Inscripciones/NuevoIngreso/Paso3.php` | Instanciación del modelo y la calculadora solo en estado aprobado, con degradación segura. |
| `app/Views/inscripciones/nuevo_ingreso/paso3/index.php` | Reenvío de `documentos_presenciales` y `plazo_entrega`. |
| `app/Views/inscripciones/nuevo_ingreso/paso3/estado.php` | Renderizado de la sección de documentos antes de "Ver intentos de pago". |
| `docs/features/010-documentos-presenciales-pendientes-pago-aprobado/plan.md` | Estado actualizado a `completado`. |

## Rutas, permisos y datos
- **Rutas/endpoints nuevos o modificados:** no aplica. Se reutiliza `GET /inscripciones/nuevo-ingreso/paso-4` con el filtro existente `nuevoIngresoAuth:4`.
- **Permisos y validaciones:** la sesión `nuevo_ingreso` y `paso_actual >= 4` siguen validándose en el filtro y en `Paso3::index()`. La carrera sale del contexto de la postulación, nunca de la petición.
- **Migraciones/seeds:** `000102`, `000103` y `NiDocumentosPresencialesSeeder`; las migraciones son idempotentes con guarda `tableExists` y el seeder hace upsert por nombre y por par documento-carrera.
- **Compatibilidad:** solo lectura; no cambia contratos HTTP, filtros, CSRF, sesión, pagos, recibo, planilla ni la API. Las tablas nuevas son globales (base principal) y no afectan las bases de sede.

## Comandos ejecutados
| Comando | Resultado |
| --- | --- |
| `git rev-parse --is-inside-work-tree` | Éxito: repositorio Git. |
| `git status --porcelain` | Solo el plan sin seguimiento antes de crear la rama. |
| `git switch -c p-feature/documentos-presenciales-pendientes-pago-aprobado` | Rama local creada y activa. |
| `php vendor/phpunit/phpunit/phpunit tests/app/Integration/Paso4NuevoIngresoTest.php ...` (línea base) | 27 pruebas, 133 aserciones, 1 fallo preexistente. |
| `php vendor/phpunit/phpunit/phpunit` sobre las cinco pruebas nuevas | 34 pruebas, 100 aserciones, todas en verde. |
| `php vendor/phpunit/phpunit/phpunit` sobre `Paso4ReciboTest`, `Paso4PagoTest`, `Paso4PlanillaTest`, `ZelleNuevoIngresoTest` | 43 pruebas, todas en verde. |
| `php vendor/phpunit/phpunit/phpunit tests/app/Integration/Paso4NuevoIngresoTest.php` (después) | 27 pruebas, 133 aserciones, el mismo fallo preexistente. |
| `php -l` sobre los diez archivos PHP tocados | Sin errores de sintaxis. |
| `graphify update .` | Grafo actualizado (14.326 nodos, 29.783 aristas). |

## Verificación
- **Línea base (antes):** `Paso4NuevoIngresoTest`, `Paso4ReciboTest`, `Paso4PagoTest`, `Paso4PlanillaTest` y `ZelleNuevoIngresoTest`: 27 pruebas y 133 aserciones en el primer archivo, con 1 fallo preexistente en `testIniciarConIntencionCreadaIgnoraPlanDelFormulario` (la tabla `pg_intenciones_pago` contiene 2 filas en lugar de 1). Los otros cuatro archivos pasaron completos.
- **Prueba manual (flujo normal):** no se ejecutó un smoke test con navegador ni base MySQL real. El flujo normal se cubrió con `Paso4DocumentosPresencialesTest`, que simula la petición, renderiza la vista y valida el HTML.
- **Flujos alternativos y errores:** cubiertos por `Paso4DocumentosPresencialesTest` (estados 2 y 7, catálogo vacío, plazo vencido, sin fecha base, tablas ausentes y escape de nombres).
- **Pruebas automatizadas:** 34 pruebas nuevas en cinco archivos, todas en verde; suites existentes del área sin regresiones.
- **Criterios del plan:** todos verificados; el único resultado no ideal es el fallo preexistente de la línea base, ajeno a esta feature.

## Desviaciones del plan
- Se agregó `EsCarrerasSeeder` a `PrincipalDemoSeeder::seedBase()` para que `demo:seed` garantice las carreras necesarias para las asociaciones del certificado de salud mental. Es idempotente y ya existía.
- Las migraciones usan una guarda `tableExists` antes de `createTable`, porque el Forge de CI 4.0.3 intenta recrear los índices aunque se pase `IF NOT EXISTS`. Sin la guarda, la segunda ejecución fallaba.
- Las opciones de motor/collation y el `DEFAULT CURRENT_TIMESTAMP` se aplican solo en MySQLi; en SQLite (pruebas) se omiten para no romper el esquema de pruebas.

## Riesgos y pendientes
- Persiste el fallo preexistente `Paso4NuevoIngresoTest::testIniciarConIntencionCreadaIgnoraPlanDelFormulario`; no fue causado ni corregido por esta feature.
- No se ejecutó un smoke test contra MySQL real ni con el servidor de desarrollo; las migraciones y el seeder se validaron en SQLite. Se recomienda ejecutar `php spark init:principal` en un entorno de pruebas y revisar el Paso 4 con un pago aprobado.
- La fecha base es `actualizado_dt`; si una operación posterior la modifica, el plazo se recalcula. Queda documentado como deuda.
- No hay seguimiento de entregas ni administración del catálogo; los cambios se hacen por migración, seeder o base de datos.
- El cálculo no descuenta feriados y el plazo de 15 días es una constante.
- `graphify update` reportó advertencias ajenas: falta `tree_sitter_sql` y tres archivos de vistas/errores con sintaxis no extraíble. No afectan esta feature.
