# Prototipo de ejecución — FEAT-002 Informar cuando la carrera no está ofertada en la sede

- **Rama:** p-feature/carrera-no-ofertada-en-la-sede
- **Rama base:** feature/desacoplar-contructor-pagos
- **Plan:** docs/features/002-carrera-no-ofertada-en-la-sede/plan.md
- **Fecha:** 2026-10-28
- **Estado:** completado
- **Consolidación:** consolidado el 2026-10-28 en `feature/desacoplar-contructor-pagos`

## Resumen

Se implementó la detección de carreras sin pensum activo en la sede para el Paso 2 de nuevo ingreso. En modo estricto la consulta de oferta responde `422` con un mensaje de usuario específico; en modo permisivo responde `200` con el mismo mensaje informativo y permite continuar. También se alineó el escenario demo para que la carrera de prueba use `orbis_codigo = 'X'` y se agregaron pruebas del servicio, presenter, controlador y seeder. El título del bloque de mensaje ahora muestra `Advertencia` en lugar de `Lapso N`.

## Tareas realizadas

- [x] Crear `CarreraNoOfertadaException` heredera de `OfertaAcademicaException`, con fábrica `porCarreraNoOfertada()` que devuelve `self`.
- [x] Agregar `OfertaAcademicaService::tieneOfertaActiva()` con normalización de códigos y consulta a `cecarrera` + `cecarrerapens` activo.
- [x] Agregar `MENSAJE_CARRERA_NO_OFERTADA` y `mensajeCarreraNoOfertada()` en `OfertaAcademicaPresenter`.
- [x] Detectar la carrera no ofertada en `Paso2::resolverContextoOferta()` antes de `resolverCarreraPens()`.
- [x] Manejar la excepción específica en `Paso2::consultar()` (estricto) y `Paso2::consultarModoPermisivo()`.
- [x] Cambiar el mapeo demo de `cecarrera.orbis_codigo` a `'X'` conservando `CoCarrera = 'PRB'`.
- [x] Agregar pruebas de `tieneOfertaActiva()`, del presenter, del contrato HTTP de `Paso2` y del seeder demo.
- [x] Cambiar el título del bloque de mensaje de `_resultado` de `Lapso N` a `Advertencia`.
- [x] Ejecutar pruebas del área, `php -l` y `graphify update .`.
- [ ] Smoke test manual con una base de datos autorizada — Motivo: no se dispone de una base de desarrollo/pruebas autorizada en este entorno. La cobertura se realizó con pruebas de integración SQLite.

## Criterios de aceptación

| Criterio | Cómo se verificó | Resultado |
| --- | --- | --- |
| `CarreraNoOfertadaException` existe, hereda de `OfertaAcademicaException` y su fábrica devuelve `self` | Revisión de `app/Libraries/Academica/CarreraNoOfertadaException.php` y ejecución de las pruebas de `Paso2` | ok |
| `tieneOfertaActiva()` devuelve `true` con carrera y pensum activo | `testTieneOfertaActivaConCarreraYPensumActivo` | ok |
| `tieneOfertaActiva()` devuelve `false` sin carrera, pensum distinto, pensum inactivo o códigos vacíos | `testTieneOfertaActivaDevuelveFalseSinCarreraOPensum`, `testTieneOfertaActivaDevuelveFalseConPensumInactivo`, `testTieneOfertaActivaDevuelveFalseConCodigosVacios` | ok |
| `tieneOfertaActiva()` no exige secciones | `testTieneOfertaActivaNoRequiereSecciones` elimina secciones y horarios antes de consultar | ok |
| El presenter expone el texto exacto acordado | `testMensajeCarreraNoOfertadaEsExacto` | ok |
| El bloque de mensaje muestra `Advertencia` y no `Lapso N` | `testConsultarModoPermisivoConCarreraAusenteEnSedeDevuelveMensaje` verifica el HTML | ok |
| `Paso2` detecta la carrera no ofertada antes de resolver el pensum | Revisión de `Paso2::resolverContextoOferta()` y pruebas HTTP | ok |
| Modo estricto responde `422`, `status: false` y el mensaje del presenter | `testConsultarEstrictoConCarreraAusenteEnSedeDevuelveMensaje`, `testConsultarEstrictoConPensumInactivoDevuelveMensajeDeCarreraNoOfertada` | ok |
| Modo permisivo responde `200`, `status: true`, `modo: mensaje`, mensaje específico y HTML | `testConsultarModoPermisivoConCarreraAusenteEnSedeDevuelveMensaje`, `testConsultarModoPermisivoConPensumInactivoDevuelveMensajeDeCarreraNoOfertada` | ok |
| En permisivo, `guardar()` sigue avanzando al Paso 4 | `testGuardarConModoPermisivoSinOfertaAvanza` | ok |
| `index()` y el resto de flujos de `guardar()` no cambian | Pruebas existentes de `Paso3NuevoIngresoTest` | ok |
| El seeder demo deja `orbis_codigo = 'X'`, `CoCarrera = 'PRB'` y conserva el nombre | `testMapeaLaCarreraDemoAlCodigoOrbisX` | ok |
| Los fixtures que usan `PRB` no se modificaron | Revisión de `Paso3NuevoIngresoTest` y `OfertaAcademicaServiceIntegrationTest` | ok |
| Las pruebas del área pasan | Comandos de la sección "Comandos ejecutados" | ok |
| `php -l` no reporta errores | Ejecución sobre los 10 archivos PHP tocados | ok |
| No se modificaron rutas, filtros, JavaScript, esquema, migraciones, `gb_config`, `Services.php` ni pagos; solo se ajustó el título de `_resultado` | Revisión de `git status` y `git diff` | ok |
| No se implementó el Paso 4 | Revisión de alcance y archivos tocados | ok |
| `graphify update .` ejecutado | Salida del comando sin errores de actualización del grafo | ok |

## Flujos cubiertos

- **Flujo normal:** una carrera con `cecarrera.orbis_codigo` y `cecarrerapens` activo continúa por `resolverCarreraPens()` y la consulta de oferta existente. Cubierto por las pruebas de `Paso3NuevoIngresoTest` y `OfertaAcademicaServiceIntegrationTest`.
- **Flujos alternativos:** modo permisivo con carrera ausente o pensum inactivo; carrera ofertada sin secciones; y mapeo demo a `'X'`. Cubiertos por pruebas específicas.
- **Control de errores:** modo estricto con carrera ausente o pensum inactivo devuelve `422`; errores de configuración (`pensum_activo` vacío, `periodo_ni` ausente) conservan el mensaje y el `422` existentes; errores inesperados siguen en el `catch (\Throwable)` con `500`.

## Archivos creados

| Archivo | Motivo |
| --- | --- |
| `app/Libraries/Academica/CarreraNoOfertadaException.php` | Excepción de dominio para distinguir la carrera no ofertada de otros errores de oferta |
| `tests/app/Database/Seeds/SucursalAcademicaSeederTest.php` | Verificar el mapeo demo a `orbis_codigo = 'X'` sin ejecutar todo el seeder |
| `docs/features/002-carrera-no-ofertada-en-la-sede/plan.md` | Plan de la feature y registro de criterios |
| `docs/features/002-carrera-no-ofertada-en-la-sede/prototipo.md` | Este registro de ejecución |

## Archivos modificados

| Archivo | Cambio realizado |
| --- | --- |
| `app/Libraries/Academica/OfertaAcademicaService.php` | Se agregó `tieneOfertaActiva()` con normalización de códigos y consulta de carrera/pensum activo |
| `app/Libraries/Academica/OfertaAcademicaPresenter.php` | Se agregaron `MENSAJE_CARRERA_NO_OFERTADA` y `mensajeCarreraNoOfertada()` |
| `app/Controllers/Inscripciones/NuevoIngreso/Paso2.php` | Se agregó la detección en `resolverContextoOferta()` y los catch específicos en `consultar()` y `consultarModoPermisivo()` |
| `app/Views/inscripciones/nuevo_ingreso/paso2/_resultado.php` | El título del bloque de mensaje pasó de `Lapso N` a `Advertencia` |
| `app/Database/Seeds/Demo/SucursalAcademicaSeeder.php` | Se cambió `orbis_codigo` de `'PRB'` a `'X'` conservando `CoCarrera` y el nombre |
| `tests/app/Libraries/OfertaAcademicaServiceTest.php` | Pruebas de `tieneOfertaActiva()` para códigos válidos, ausentes, inactivos y vacíos |
| `tests/app/Integration/OfertaAcademicaServiceIntegrationTest.php` | Prueba de que `tieneOfertaActiva()` no requiere secciones |
| `tests/app/Libraries/OfertaAcademicaPresenterTest.php` | Prueba del texto exacto del mensaje |
| `tests/app/Integration/Paso3NuevoIngresoTest.php` | Pruebas de carrera ausente/pensum inactivo en estricto y permisivo; actualización del test permisivo existente |

## Rutas, permisos y datos

- **Rutas/endpoints nuevos o modificados:** no aplica. Se conservan las rutas existentes de `Paso2` (`index`, `consultar`, `guardar`) y sus filtros de nuevo ingreso.
- **Permisos y validaciones:** se conservan `nuevoIngresoAuth`, la validación de sesión, paso, turno y modalidad. La nueva validación es de dominio y no relaja ningún control de acceso.
- **Migraciones/seeds:** no hay migraciones nuevas. El seeder demo `SucursalAcademicaSeeder` usa `upsert` por `CeCarreraID`, por lo que una segunda ejecución actualiza la misma fila y no duplica datos. La prueba del seeder verifica solo la etapa de catálogos.
- **Compatibilidad:** el contrato exitoso de `consultar()` no cambia. En modo estricto, una carrera no ofertada ahora devuelve un mensaje de usuario específico en lugar del mensaje genérico de configuración; en modo permisivo, el mensaje informativo cambia al texto acordado. Los clientes que dependan del texto anterior deben actualizar sus expectativas.

## Comandos ejecutados

| Comando | Resultado |
| --- | --- |
| `vendor\bin\phpunit.bat tests/app/Libraries/OfertaAcademicaServiceTest.php` (línea base) | OK, 23 tests, 50 assertions |
| `vendor\bin\phpunit.bat tests/app/Libraries/OfertaAcademicaPresenterTest.php` (línea base) | OK, 14 tests, 15 assertions |
| `vendor\bin\phpunit.bat tests/app/Integration/OfertaAcademicaServiceIntegrationTest.php` (línea base) | OK, 19 tests, 47 assertions |
| `vendor\bin\phpunit.bat tests/app/Integration/Paso3NuevoIngresoTest.php` (línea base) | OK, 34 tests, 84 assertions |
| `vendor\bin\phpunit.bat tests/app/Libraries/OfertaAcademicaServiceTest.php` (después) | OK, 27 tests, 56 assertions |
| `vendor\bin\phpunit.bat tests/app/Libraries/OfertaAcademicaPresenterTest.php` (después) | OK, 15 tests, 17 assertions |
| `vendor\bin\phpunit.bat tests/app/Integration/OfertaAcademicaServiceIntegrationTest.php` (después) | OK, 20 tests, 48 assertions |
| `vendor\bin\phpunit.bat tests/app/Database/Seeds/SucursalAcademicaSeederTest.php` | OK, 1 test, 4 assertions |
| `vendor\bin\phpunit.bat tests/app/Integration/Paso3NuevoIngresoTest.php` (después) | OK, 37 tests, 96 assertions |
| `php -l` sobre los 11 archivos PHP creados/modificados | Sin errores de sintaxis |
| `graphify update .` | Grafo actualizado; advertencias preexistentes por SQL y archivos de vista de errores |

## Verificación

- **Línea base (antes):** 90 tests y 196 assertions OK en los cuatro archivos del área (`OfertaAcademicaServiceTest`, `OfertaAcademicaPresenterTest`, `OfertaAcademicaServiceIntegrationTest`, `Paso3NuevoIngresoTest`).
- **Prueba manual (flujo normal):** no ejecutada por falta de una base de datos de desarrollo/pruebas autorizada. El flujo normal quedó cubierto por las pruebas de integración SQLite existentes y nuevas.
- **Flujos alternativos y errores:** cubiertos con pruebas de integración de `Paso2` para carrera ausente, pensum inactivo, modo estricto y modo permisivo; pruebas unitarias para códigos vacíos y pensum inactivo en el servicio.
- **Pruebas automatizadas:** 100 tests y 221 assertions OK en los cinco archivos del área después de la implementación.
- **Criterios del plan:** todos los criterios de `plan.md` quedaron verificados y marcados como cumplidos. El smoke test manual queda como pendiente de entorno, no como criterio bloqueante del plan.

## Desviaciones del plan

- La prueba del seeder demo se implementó con `ReflectionMethod` para ejecutar solo `seedCatalogo()`, en lugar de ejecutar `SucursalAcademicaSeeder::run()` completo. Motivo: evitar replicar todo el esquema de una sede; la prueba verifica directamente el mapeo acordado.
- En la prueba de integración se usó `DELETE FROM` mediante consulta directa porque el query builder de CI 4.0.3 rechaza `delete()` sin cláusula `where`.
- No se modificó `Paso2::index()` ni `Paso2::guardar()`, conforme al plan y a la entrevista de alcance.
- Ajuste posterior solicitado por el usuario: se cambió el título del bloque de mensaje de `_resultado` de `Lapso N` a `Advertencia`. Se actualizó el alcance y los criterios del plan para reflejarlo.

## Consolidación

- **Estado:** consolidado
- **Fecha:** 2026-10-28
- **Rama destino:** `feature/desacoplar-contructor-pagos`
- **Estrategia:** `git merge --no-ff`
- **Commit de merge:** `3f03f2e`
- **Commits integrados:** 4 commits de la rama prototipo, más el commit de merge
- **Rama prototipo:** `p-feature/carrera-no-ofertada-en-la-sede`, eliminada con `git branch -d`
- **Verificación:** ancestro confirmado, sin commits pendientes, sin diferencias de archivos, 100 tests y 221 assertions OK, `php -l` sin errores
- **Smoke manual:** sigue pendiente por falta de una base de datos autorizada

## Riesgos y pendientes

- **Smoke test manual:** pendiente en una base autorizada. Se recomienda validar con una postulación real de prueba: carrera ausente en la sede en modo estricto (422 y mensaje), en modo permisivo (200 y mensaje), y carrera ofertada (flujo normal).
- **Consulta duplicada:** `tieneOfertaActiva()` y `resolverCarreraPens()` consultan la misma relación carrera-pensum. Se aceptó una lectura adicional para no alterar `resolverCarreraPens()`; si el rendimiento importa, puede unificarse en una tarea posterior.
- **Mapeo demo:** el cambio a `'X'` depende de que `init:principal` haya sembrado la carrera `X` y su relación `es_sucursales_carreras`. En un entorno demo sin `init:principal`, el flujo seguirá sin encontrar oferta.
- **Commits y consolidación:** los cuatro commits del prototipo y el merge `3f03f2e` ya están en `feature/desacoplar-contructor-pagos`; la rama prototipo fue eliminada. La actualización de este documento queda sin commit salvo petición expresa.
