# Informar cuando la carrera no está ofertada en la sede

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

## Objetivo

Evitar que un aspirante de nuevo ingreso consulte la oferta del Paso 2 (materias, turno y modalidad) cuando la carrera que eligió no está ofertada en su sede. El sistema debe distinguir este caso de otros errores de configuración y de la simple ausencia de secciones u horarios, mostrando un mensaje específico y auditable. En modo estricto la consulta se rechaza; en modo permisivo se informa y el aspirante puede continuar.

## Alcance

- Incluye:
  - `App\Libraries\Academica\CarreraNoOfertadaException`, heredera de `OfertaAcademicaException`.
  - `OfertaAcademicaService::tieneOfertaActiva()` con contrato `(BaseConnection $dbSede, string $orbisCodigo, string $pensumCodigo): bool`.
  - Constante y método de mensaje en `OfertaAcademicaPresenter`.
  - Detección y manejo específico en `Paso2::resolverContextoOferta()`, `Paso2::consultar()` y `Paso2::consultarModoPermisivo()`.
  - Mapeo del seeder demo a `cecarrera.orbis_codigo = 'X'`.
  - Cambio del título visible del bloque de mensaje de `_resultado` de `Lapso N` a `Advertencia`.
  - Pruebas del servicio, del presenter, del contrato HTTP de `Paso2` y del seeder demo.
- No incluye:
  - Cambios en `Paso2::index()` ni en `Paso2::guardar()`.
  - Cambios de estructura, campos o estilos en vistas, JavaScript, rutas, filtros, CSRF o códigos HTTP existentes; solo se ajusta el título visible del bloque de mensaje.
  - Cambios en la lógica de secciones, lapso, periodo, turno o modalidad.
  - Cambios en `resolverCarreraPens()`, en sus mensajes o en la detección de mapeos ambiguos.
  - Migraciones, cambios de esquema, nuevos valores de `gb_config` o datos reales.
  - Paso 4, pagos, intenciones de pago o pasarelas.
  - Cambios en los fixtures de pruebas que hoy usan `orbis_codigo = 'PRB'`.

## Contexto y supuestos

- La rama de trabajo actual es `feature/desacoplar-contructor-pagos`. No se cambia de rama ni se reescribe historial.
- `cecarrera.orbis_codigo` existe por la migración `2026-10-19-000095_AddOrbisCodigoToCecarrera.php`; `cecarrerapens.EsActivo` existe por la migración `2026-08-26-000035_CreateCecarrerapens.php`.
- `pensum_activo` es una configuración global de `gb_config` en la base principal. Un valor vacío o ausente sigue siendo un error de configuración, no un caso de carrera no ofertada.
- Una carrera se considera ofertada en la sede cuando existe `cecarrera` con el `orbis_codigo` resuelto y al menos un `cecarrerapens` activo para el `pensum_activo` configurado. No se exige que existan secciones (`ceseccmaterperio`) ni horarios.
- `ni_oferta_permisiva` conserva su semántica: solo `'1'` habilita el modo permisivo; ausente, vacío o inválido se interpreta como estricto.
- El mensaje de usuario acordado es exactamente: `La carrera seleccionada no está ofertada en la sede seleccionada. La sede seleccionada está sujeta a cambios, Su horario de clases será enviado por correo electrónico una vez se confirmen los datos proporcionados.`
- El mapeo demo cambia solo `cecarrera.orbis_codigo` a `'X'` en `SucursalAcademicaSeeder`. `CoCarrera` sigue siendo `'PRB'` y el nombre de la carrera demo no cambia.
- El catálogo principal ya contiene la carrera con `orbis_codigo = 'X'` (`TSU en Comercio Exterior`) y `init:principal` siembra la relación `es_sucursales_carreras` para las sedes demo.
- `CecarreraOrbisCodigoSeeder` solo completa códigos vacíos; no sobrescribe el `'X'` del seeder demo.
- Los fixtures de `tests/app/Integration/Paso3NuevoIngresoTest.php` y de las pruebas del servicio conservan `orbis_codigo = 'PRB'` para no alterar su intención.
- `MEMORY.md` no existe en este checkout aunque `AGENTS.md` lo referencia. Este cambio no lo crea.
- El código `FEAT-002` no colisiona con `FEAT-001`; no existe otro documento `002` en `docs/features/`.
- `graphify-out/graph.json` existe y se consultó para ubicar `Paso2`, `OfertaAcademicaService`, `OfertaAcademicaPresenter` y sus pruebas.

## Flujo normal

1. Paso 1: El aspirante con sesión `nuevo_ingreso` válida y `paso_actual >= 2` envía `turno_id` y `modalidad` a `Paso2::consultar()`.
2. Paso 2: `consultar()` valida que la petición sea AJAX/JSON, que la sesión exista, que el paso sea suficiente, que el turno sea válido y que la modalidad sea `0` o `1`.
3. Paso 3: `consultar()` determina el modo con `modoPermisivo()` a partir de `ni_oferta_permisiva`.
4. Paso 4: `resolverContexto()` resuelve la inscripción, la relación carrera/sede, la carrera activa, el nombre de la sede y la conexión de la sede; devuelve `orbis_codigo`.
5. Paso 5: `consultar()` valida que el turno esté activo en la sede.
6. Paso 6: En ambos modos, `resolverContextoOferta()` lee `periodo_ni` y `pensum_activo`. Si faltan o son inválidos, lanza el error de configuración existente.
7. Paso 7: `resolverContextoOferta()` normaliza `orbis_codigo` y `pensum_activo` y llama a `OfertaAcademicaService::tieneOfertaActiva()`.
8. Paso 8: Si `tieneOfertaActiva()` devuelve `true`, se ejecuta `resolverCarreraPens()` y el resto de la consulta de oferta sigue sin cambios.
9. Paso 9: Si `tieneOfertaActiva()` devuelve `false`, `resolverContextoOferta()` lanza `CarreraNoOfertadaException::porCarreraNoOfertada()`.
10. Paso 10: En modo estricto, `consultar()` captura la excepción específica y responde HTTP `422` con `status: false` y el mensaje de `OfertaAcademicaPresenter`.
11. Paso 11: En modo permisivo, `consultarModoPermisivo()` captura la excepción específica, registra una advertencia y responde HTTP `200` con `status: true`, `modo: mensaje`, el mensaje del presenter y el HTML de `_resultado`.
12. Paso 12: El aspirante en modo permisivo puede ejecutar `guardar()` y avanzar al Paso 4; `guardar()` no cambia su comportamiento actual.

## Flujos alternativos / variantes

### Modo permisivo con carrera no ofertada

1. Paso 1: `ni_oferta_permisiva` vale `'1'` y el aspirante consulta la oferta.
2. Paso 2: `consultarModoPermisivo()` lee `primer_lapso_ni`; si es válido, continúa.
3. Paso 3: `resolverContextoOferta()` llama a `tieneOfertaActiva()` y obtiene `false`.
4. Paso 4: Se lanza `CarreraNoOfertadaException`.
5. Paso 5: El catch específico registra `log_message('warning', ...)` sin datos personales.
6. Paso 6: Se responde `200` con `status: true`, `modo: mensaje`, `lapso` actual, el mensaje específico y el HTML generado por `inscripciones/nuevo_ingreso/paso2/_resultado`.
7. Paso 7: El aspirante ve el aviso y puede guardar turno/modalidad para continuar.

### Carrera ofertada pero sin secciones u horarios

1. Paso 1: `tieneOfertaActiva()` devuelve `true` porque existe la carrera y el pensum activo.
2. Paso 2: `resolverCarreraPens()` devuelve el `CeCarreraPensID`.
3. Paso 3: `consultarPorLapso()` devuelve materias sin secciones, secciones sin bloques o una lista vacía según los datos.
4. Paso 4: `OfertaAcademicaPresenter::determinarModo()` decide `mensaje`, `materias` u `horario` como hoy.
5. Paso 5: El comportamiento y los mensajes existentes no cambian.

### Carrera mapeada en la sede pero pensum inactivo o distinto

1. Paso 1: Existe `cecarrera.orbis_codigo`, pero no hay `cecarrerapens` con `CoPensum = pensum_activo` y `EsActivo = 1`.
2. Paso 2: `tieneOfertaActiva()` devuelve `false`.
3. Paso 3: Se trata como carrera no ofertada y se aplica el flujo del modo correspondiente.
4. Paso 4: No se confunde con un error de configuración del `pensum_activo`.

### Error de configuración de la sede

1. Paso 1: Falta `periodo_ni` o `pensum_activo` está vacío.
2. Paso 2: `resolverContextoOferta()` lanza `OfertaAcademicaException::porConfiguracion()` como hoy.
3. Paso 3: El catch genérico conserva el mensaje y el código HTTP actuales.
4. Paso 4: No se muestra el mensaje de carrera no ofertada.

### Base demo con mapeo Orbis

1. Paso 1: Se ejecuta `php spark demo:seed` en un entorno autorizado.
2. Paso 2: `SucursalAcademicaSeeder` deja `cecarrera.orbis_codigo = 'X'`, `CoCarrera = 'PRB'` y el mismo nombre de carrera demo.
3. Paso 3: El aspirante demo elige la carrera `X` (`TSU en Comercio Exterior`) ofertada por `init:principal` para su sede.
4. Paso 4: `tieneOfertaActiva()` encuentra la carrera y el pensum demo `PEN900`; la consulta sigue el flujo normal.
5. Paso 5: Una segunda ejecución de `demo:seed` no duplica ni revierte el mapeo.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| La carrera no existe en `cecarrera` de la sede | `tieneOfertaActiva()` devuelve `false` | Estricto: `422`, `status: false`, mensaje del presenter. Permisivo: `200`, `status: true`, `modo: mensaje`, mismo mensaje | El aspirante permanece en el Paso 3; en permisivo puede continuar |
| La carrera existe pero no tiene `cecarrerapens` activo para el pensum configurado | `tieneOfertaActiva()` devuelve `false` | Igual que la fila anterior | Igual que la fila anterior |
| `orbis_codigo` del contexto está vacío | `tieneOfertaActiva()` normaliza y devuelve `false` | Igual que la fila anterior | Igual que la fila anterior |
| `pensum_activo` está vacío | Validación existente en `resolverContextoOferta()`, antes de `tieneOfertaActiva()` | `OfertaAcademicaException::porConfiguracion()`; estricto `422`, permisivo informativo genérico | No se evalúa carrera no ofertada |
| Falta `periodo_ni` | Validación existente en `resolverContextoOferta()` | `OfertaAcademicaException::porConfiguracion()` | No se evalúa carrera no ofertada |
| `tieneOfertaActiva()` devuelve `true` pero `resolverCarreraPens()` devuelve `null` por una carrera o pensum que cambió entre consultas | `resolverCarreraPens()` devuelve `null` | Se conserva `OfertaAcademicaException::porConfiguracion()` existente | Error de configuración, no carrera no ofertada |
| El mapeo de carrera/pensum es ambiguo | `resolverCarreraPens()` encuentra más de una fila | `OfertaAcademicaException::porValidacion()` existente | Error de validación; no se muestra el mensaje de carrera no ofertada |
| El turno no está activo en la sede | Validación existente en `consultar()` antes de resolver la oferta | `422` con el mensaje de turno existente | No se evalúa carrera no ofertada |
| La sesión expiró o el paso es insuficiente | Validaciones existentes al inicio de `consultar()` | `401` o `422` con los mensajes existentes | No se evalúa carrera no ofertada |
| Error inesperado de base de datos o de código | `catch (\Throwable)` existente | `500` con el mensaje genérico existente; detalle en `writable/logs` | El aspirante puede reintentar |
| `cecarrera` o `cecarrerapens` no existen en la sede | Excepción de base de datos en `tieneOfertaActiva()` | `catch (\Throwable)` existente; `500` genérico | Revisar esquema de la sede |
| El seeder demo se ejecuta sin el esquema de sede | Excepción del seeder al hacer `upsert` | El comando `demo:seed` falla y detiene esa sede | Ejecutar `init:sucursal` antes; no se aplica el mapeo |
| El seeder demo se ejecuta en producción sin autorización | Validación existente de `demo:seed` | El comando se cancela | Sin cambios en datos |

## Reglas de negocio y validaciones

- `CarreraNoOfertadaException` vive en `App\Libraries\Academica`, hereda de `OfertaAcademicaException` y declara su propia fábrica `porCarreraNoOfertada(string $orbisCodigo, string $pensumCodigo): self`. La fábrica debe usar `new self` para conservar el subtipo, igual que `NuevoIngresoContextException`.
- El mensaje técnico de la excepción debe incluir `orbis_codigo` y `pensum_codigo` para diagnóstico, pero nunca se muestra al usuario final.
- `OfertaAcademicaService::tieneOfertaActiva()` normaliza ambos códigos con la misma regla de `normalizarCodigo()` (`strtoupper(trim())`).
- `tieneOfertaActiva()` devuelve `false` si cualquiera de los dos códigos normalizados queda vacío.
- `tieneOfertaActiva()` consulta únicamente la existencia de `cecarrera` unida a `cecarrerapens` con `EsActivo = 1` y el `CoPensum` indicado. No valida secciones, periodo, turno, modalidad, cupos ni estado de la relación carrera/sede.
- Si existe más de una fila activa para la misma carrera y pensum, `tieneOfertaActiva()` devuelve `true`; la ambigüedad la sigue resolviendo `resolverCarreraPens()`.
- `Paso2::resolverContextoOferta()` llama a `tieneOfertaActiva()` después de validar `periodo_ni` y `pensum_activo`, y antes de `resolverCarreraPens()`.
- La validación se aplica solo en la ruta de consulta de oferta. `index()` sigue mostrando la pantalla con el contexto liviano y `guardar()` sigue guardando turno/modalidad sin resolver la oferta.
- En modo estricto, la respuesta es HTTP `422` con `status: false` y `message` igual a la constante del presenter. No se incluyen detalles técnicos ni HTML.
- En modo permisivo, la respuesta es HTTP `200` con `status: true`, `modo: mensaje`, el mismo mensaje y el HTML de `_resultado`. El modo permisivo no bloquea `guardar()`.
- El presenter expone la constante `MENSAJE_CARRERA_NO_OFERTADA` y el método `mensajeCarreraNoOfertada(): string`. El texto es único para ambos modos y no depende de lapso, modalidad ni turno.
- El mensaje debe escaparse en la vista como cualquier otro mensaje; no se inserta HTML.
- Los logs de la excepción usan `log_message('warning', ...)` y no incluyen identificación, nombre, correo ni teléfono del aspirante.
- El seeder demo cambia solo `orbis_codigo` a `'X'` en la carrera demo. No cambia `CoCarrera`, `NbCarrera`, `NbTituloOtorgado`, IDs, pensum, materias, secciones ni configuración.
- `init:sucursal` y `CecarreraOrbisCodigoSeeder` no se modifican. El mapeo demo se aplica solo en `demo:seed`.
- No se modifica el valor por defecto de `ni_oferta_permisiva` (sigue siendo `'0'`) ni se agregan claves nuevas a `gb_config`.
- No se modifican los fixtures de pruebas que usan `PRB`; las pruebas nuevas del flujo demo deben sembrar o usar explícitamente `X`.

## Áreas afectadas

| Acción | Archivo / componente | Motivo |
| --- | --- | --- |
| Crear | `app/Libraries/Academica/CarreraNoOfertadaException.php` | Excepción de dominio para la carrera no ofertada, heredera de `OfertaAcademicaException` |
| Modificar | `app/Libraries/Academica/OfertaAcademicaService.php` | Agregar `tieneOfertaActiva()` sin cambiar `resolverCarreraPens()` ni `consultarPorLapso()` |
| Modificar | `app/Libraries/Academica/OfertaAcademicaPresenter.php` | Agregar `MENSAJE_CARRERA_NO_OFERTADA` y `mensajeCarreraNoOfertada()` |
| Modificar | `app/Controllers/Inscripciones/NuevoIngreso/Paso2.php` | Detectar la carrera no ofertada en `resolverContextoOferta()` y manejarla en `consultar()` y `consultarModoPermisivo()` |
| Modificar | `app/Views/inscripciones/nuevo_ingreso/paso2/_resultado.php` | Cambiar el título del bloque de mensaje de `Lapso N` a `Advertencia` |
| Modificar | `app/Database/Seeds/Demo/SucursalAcademicaSeeder.php` | Cambiar `cecarrera.orbis_codigo` demo de `'PRB'` a `'X'` |
| Modificar | `tests/app/Libraries/OfertaAcademicaServiceTest.php` | Cubrir `tieneOfertaActiva()` con SQLite: códigos válidos, carrera ausente, pensum inactivo, pensum distinto y códigos vacíos |
| Modificar | `tests/app/Integration/OfertaAcademicaServiceIntegrationTest.php` | Cubrir `tieneOfertaActiva()` contra el esquema de sede y verificar que no exige secciones |
| Modificar | `tests/app/Libraries/OfertaAcademicaPresenterTest.php` | Verificar el texto exacto y que el mensaje no varía por modo |
| Modificar | `tests/app/Integration/Paso3NuevoIngresoTest.php` | Cubrir estricto `422` y permisivo `200` con el mensaje específico en `consultar()`; verificar que `guardar()` permisivo sigue avanzando |
| Crear | `tests/app/Database/Seeds/SucursalAcademicaSeederTest.php` | Verificar que `SucursalAcademicaSeeder` deja `orbis_codigo = 'X'` y conserva los demás campos |
| Documentar | `docs/features/002-carrera-no-ofertada-en-la-sede/plan.md` | Este plan |

No se modifican `Routes.php`, `Filters.php`, JavaScript, `app/Config/Services.php`, migraciones, `gb_config`, `Paso0`, `Paso1`, `Paso3`, `PaymentService`, `PaymentOrchestrator` ni la lógica de pagos. La única modificación de vista es el título del bloque de mensaje de `_resultado`.

## Criterios de finalización

- [x] Existe `CarreraNoOfertadaException` en `app/Libraries/Academica/`, hereda de `OfertaAcademicaException`, su fábrica `porCarreraNoOfertada()` devuelve `self` y su mensaje técnico incluye `orbis_codigo` y `pensum_codigo`.
- [x] `OfertaAcademicaService::tieneOfertaActiva()` normaliza los códigos y devuelve `true` solo cuando existe `cecarrera` con el `orbis_codigo` y un `cecarrerapens` activo con el `CoPensum` indicado.
- [x] `tieneOfertaActiva()` devuelve `false` si falta la carrera, si el pensum está inactivo, si el pensum no coincide o si cualquiera de los códigos está vacío.
- [x] `tieneOfertaActiva()` no consulta ni exige secciones, periodo, turno, modalidad, cupos ni relación `es_sucursales_carreras`.
- [x] `OfertaAcademicaPresenter` expone `MENSAJE_CARRERA_NO_OFERTADA` y `mensajeCarreraNoOfertada()` con el texto exacto acordado.
- [x] El bloque de mensaje de `_resultado` muestra `Advertencia` como título en lugar de `Lapso N`.
- [x] `Paso2::resolverContextoOferta()` llama a `tieneOfertaActiva()` después de validar `periodo_ni` y `pensum_activo`, y lanza `CarreraNoOfertadaException` cuando devuelve `false`.
- [x] `Paso2::consultar()` en modo estricto responde HTTP `422`, `status: false` y el mensaje del presenter; no expone el mensaje técnico de la excepción.
- [x] `Paso2::consultarModoPermisivo()` responde HTTP `200`, `status: true`, `modo: mensaje`, el mensaje del presenter y el HTML de `_resultado`; registra una advertencia sin datos personales.
- [x] En modo permisivo, `Paso2::guardar()` sigue permitiendo avanzar al Paso 4 sin validar la oferta.
- [x] `Paso2::index()` y el resto de flujos de `guardar()` no cambian su comportamiento.
- [x] `SucursalAcademicaSeeder` deja `cecarrera.orbis_codigo = 'X'` y conserva `CoCarrera = 'PRB'`, el nombre, los IDs, el pensum y las materias demo.
- [x] Los fixtures de pruebas que usan `PRB` no se modifican; las pruebas nuevas del flujo demo usan `X` explícitamente.
- [x] Las pruebas de `tieneOfertaActiva()`, del presenter, de `Paso2` en estricto y permisivo, y de `tests/app/Database/Seeds/SucursalAcademicaSeederTest.php` pasan con `vendor/bin/phpunit` sobre los archivos afectados.
- [x] `tests/app/Integration/Paso3NuevoIngresoTest.php` sigue pasando completo.
- [x] `php -l` no reporta errores en los archivos PHP nuevos o modificados.
- [x] No se modificaron rutas, filtros, JavaScript, esquema, migraciones, `gb_config`, `Services.php` ni código de pagos; la única vista tocada es `_resultado.php` para el título del mensaje.
- [x] No se implementó ni documentó el Paso 4 como parte de este cambio.
- [x] Se ejecutó `graphify update .` después de los cambios de código.

## Preguntas abiertas

- ¿El equipo prefiere que `tieneOfertaActiva()` se reutilice dentro de `resolverCarreraPens()` para evitar la consulta duplicada, o se mantiene como verificación independiente? Este plan asume la verificación independiente para no alterar `resolverCarreraPens()`.
- ¿La prueba del seeder demo debe ejecutar `SucursalAcademicaSeeder::run()` completo sobre un esquema mínimo o basta con verificar el archivo y un smoke test de `demo:seed`? Este plan deja la decisión al implementador, con la condición de que el mapeo `'X'` quede cubierto.
- ¿El seeder demo debe conservar `CoCarrera = 'PRB'` o también debe alinearlo a `'X'`? Este plan asume que se conserva, porque el cambio acordado es solo `orbis_codigo`.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-10-28 | Creación del plan FEAT-002 tras clasificar el cambio como feature única y cerrar la entrevista de alcance. Se descarta dividirlo: excepción, servicio, presenter, manejo en `Paso2` y mapeo demo forman un solo comportamiento verificable. | opencode (agente) |
| 2026-10-28 | Implementación en la rama local `p-feature/carrera-no-ofertada-en-la-sede`. Se agregaron excepción, método de servicio, mensaje del presenter, manejo estricto/permisivo, mapeo demo y pruebas. Todas las pruebas del área pasan; no se hizo commit. | opencode (agente) |
| 2026-10-28 | Ajuste solicitado por el usuario: el título del mensaje de `_resultado` pasa de `Lapso N` a `Advertencia`. Se agrega la aserción correspondiente en `Paso3NuevoIngresoTest`. | opencode (agente) |
