# Agregar NbTurnoA al catálogo ceturno por sede

- **Código:** FEAT-020
- **Tipo:** feature
- **Estado:** en curso
- **Fecha:** 2026-11-03
- **Autor:** opencode (agente)

## Objetivo

Agregar la columna `NbTurnoA` al catálogo `ceturno` de cada base de sede mediante una migración idempotente, rellenar las filas existentes con el texto fijo `Sin descripción` y exponer el valor como `descripcion` en `OfertaAcademicaService::listarTurnosActivos`, con respaldo al código `CoTurno` cuando falte. Esta entrega deja el dato disponible para que una feature posterior lo muestre en el Paso 3 (materias, turno y modalidad) y en otros puntos del flujo.

## Alcance

- **Incluye:**
  - Nueva migración de sede `2026-11-03-000110_AddNbTurnoAToCeturno.php`.
  - Registro de la migración en `app/Commands/LoadBranchConfig.php` (`getBranchMigrationFiles()`), después de `2026-10-19-000096_AddActivoToCeturno.php`.
  - Columna `NbTurnoA VARCHAR(100) NULL DEFAULT NULL` en `ceturno` de cada base de sede.
  - Backfill idempotente de las filas existentes con `NbTurnoA IS NULL` al texto fijo `Sin descripción`.
  - Lectura de `NbTurnoA` en `OfertaAcademicaService::listarTurnosActivos()` y nueva clave `descripcion` en cada turno.
  - Respaldo `descripcion = CoTurno` cuando `NbTurnoA` sea `NULL` o cadena vacía.
  - Actualización del turno demo en `SucursalAcademicaSeeder` con un valor `NbTurnoA`.
  - Pruebas de migración, servicio, integración del Paso 3 y seeder demo.

- **No incluye:**
  - Vistas, JavaScript, controladores o rutas del Paso 3, Paso 4, planilla/PDF o panel administrativo.
  - Cambios en `Paso2`, `Paso4`, `NuevoIngresoPlanillaService`, `PostulacionesAdminService` ni en ninguna presentación.
  - Interfaz administrativa para editar `NbTurnoA`.
  - Modificación de la migración original `CreateCeturno`.
  - Migración en la base principal; `ceturno` es un catálogo por sede.
  - Cambios en `AddActivoToCeturno` ni en migraciones ya aplicadas.
  - Ejecución de `down()` sobre bases con datos reales.

> **Evaluación de alcance:** es una sola capacidad: incorporar un campo descriptivo al catálogo de turnos de sede y dejarlo disponible para su lectura. No mezcla actores ni comportamientos independientes; las visualizaciones en Paso 3, Paso 4, planilla y panel administrativo quedan para features posteriores. No requiere una nueva división.

## Contexto y supuestos

- `ceturno` existe en cada base de sede y hoy contiene al menos `CeTurnoID`, `CoTurno` y `activo`.
- `ceturno` se crea en la migración `2026-08-26-000056_CreateCeturno.php`; `activo` se agrega en `2026-10-19-000096_AddActivoToCeturno.php`. La nueva migración debe registrarse después de ambas para que `init:sucursal` la aplique en orden.
- El proyecto usa MySQLi en producción y SQLite3 solo en pruebas; la migración reutiliza el trait `App\Database\Migrations\Concerns\IntrospeccionEsquema` para verificar la columna en ambos drivers.
- `NbTurnoA` puede existir ya en bases de producción provenientes de Orbis. La migración no debe fallar ni duplicar la columna si ya existe.
- `respaldo` se interpreta como **texto fijo para las filas existentes**, no como copia de seguridad operativa de la tabla.
- El texto fijo acordado es `Sin descripción`. La tabla `ceturno` usa `latin1_swedish_ci`; el texto cabe en ese charset y en `VARCHAR(100)`.
- La columna es nullable y sin valor por defecto (`DEFAULT NULL`) para que las filas nuevas puedan quedar sin descripción hasta que se configuren.
- El servicio debe exponer la clave `descripcion`. Si `NbTurnoA` es `NULL` o cadena vacía, se usa `CoTurno`. Si ambos están vacíos, `descripcion` queda como cadena vacía; el consumidor decide cómo presentarlo.
- Se actualiza el turno demo existente (`SucursalAcademicaSeeder`, `CoTurno = 'PRB'`) con `NbTurnoA = 'Turno de prueba'`. El valor exacto del demo es un supuesto de esta especificación y puede ajustarse sin cambiar el alcance.
- No se agrega guardia de existencia de tabla porque la decisión fue validar solo la columna. El orden de `init:sucursal` garantiza que `ceturno` exista antes.
- El último documento de feature es `FEAT-019`; este cambio es `FEAT-020`. La última migración registrada es `2026-10-30-000109`; la nueva usa el número `000110` y la fecha `2026-11-03`.
- No se agrega una pantalla de edición: el valor se administra por base de datos o por el sistema de origen.

## Flujo normal

1. Paso 1: El operador ejecuta `php spark init:sucursal <id>` sobre una sede autorizada.
2. Paso 2: `LoadBranchConfig` aplica las migraciones en orden; `CreateCeturno` y `AddActivoToCeturno` ya se ejecutaron, por lo que `ceturno` existe.
3. Paso 3: La migración `000110` verifica con introspección si `ceturno.NbTurnoA` existe.
4. Paso 4: Si no existe, agrega la columna `NbTurnoA VARCHAR(100) NULL DEFAULT NULL`.
5. Paso 5: La misma migración ejecuta un `UPDATE ceturno SET NbTurnoA = 'Sin descripción' WHERE NbTurnoA IS NULL`, de modo que las filas existentes quedan con el texto fijo y los valores no nulos se preservan.
6. Paso 6: `OfertaAcademicaService::listarTurnosActivos()` consulta `CeTurnoID`, `CoTurno` y `NbTurnoA`, y devuelve cada turno con `id`, `codigo` y `descripcion`.
7. Paso 7: Para cada turno, `descripcion` toma `NbTurnoA`; si está vacío o es `NULL`, toma `CoTurno`.
8. Paso 8: `SucursalAcademicaSeeder` deja el turno demo con `NbTurnoA = 'Turno de prueba'`; una ejecución posterior de `demo:seed` actualiza ese valor por clave `CeTurnoID`.
9. Paso 9: Las pruebas automatizadas validan la migración, el servicio y los escenarios del Paso 3 que construyen `ceturno` en memoria.
10. Paso 10: Se actualiza `MEMORY.md` con el estado del catálogo y se ejecuta `graphify update .`.

## Flujos alternativos / variantes

### Sede nueva

1. Paso 1: Se crea la base de la sede con `init:sucursal`.
2. Paso 2: Se ejecutan `CreateCeturno`, `AddActivoToCeturno` y `AddNbTurnoAToCeturno` en ese orden.
3. Paso 3: La tabla nace con `NbTurnoA` y sin filas de turno; no hay backfill que aplicar.
4. Paso 4: Los turnos que se inserten después sin `NbTurnoA` quedan en `NULL` y el servicio respalda con `CoTurno`.

### Sede existente con la columna ya creada

1. Paso 1: La migración detecta que `NbTurnoA` existe y omite el `addColumn`.
2. Paso 2: El `UPDATE` solo afecta filas con `NbTurnoA IS NULL`; los valores ya configurados no se sobrescriben.
3. Paso 3: El servicio comienza a exponer `descripcion` sin cambios de esquema adicionales.

### Segunda ejecución de `init:sucursal`

1. Paso 1: La migración vuelve a ejecutarse porque `LoadBranchConfig` no usa la tabla `migrations`.
2. Paso 2: La introspección detecta la columna y no la duplica.
3. Paso 3: El backfill no encuentra filas nulas nuevas y no modifica datos existentes.
4. Paso 4: El resultado es el mismo que en la primera ejecución.

### Turno sin descripción

1. Paso 1: Existe un turno con `NbTurnoA = NULL` o `NbTurnoA = ''`.
2. Paso 2: `listarTurnosActivos()` devuelve `descripcion` igual a `CoTurno`.
3. Paso 3: El consumidor recibe un texto no vacío siempre que `CoTurno` tenga valor.

### Rollback controlado

1. Paso 1: Se ejecuta `down()` solo en un entorno autorizado y con respaldo previo.
2. Paso 2: Si la columna existe, se elimina; si no existe, no se hace nada.
3. Paso 3: El `down()` no restaura los valores de `NbTurnoA` ni revierte el backfill; esa pérdida es esperada y debe documentarse antes de ejecutarlo.

## Flujos de control de errores

| Error / condición | Detección | Respuesta del sistema | Estado final |
| --- | --- | --- | --- |
| `ceturno` no existe en la base de sede | `addColumn` falla al no encontrar la tabla | `init:sucursal` informa el error y detiene la ejecución de esa sede | La sede queda sin la columna; se debe completar primero la creación de `ceturno` |
| `NbTurnoA` ya existe | Introspección de columna | Se omite `addColumn` y se ejecuta solo el backfill de nulos | Columna única, valores no nulos preservados |
| `NbTurnoA` tiene valor no nulo | Backfill con `WHERE NbTurnoA IS NULL` | No se modifica la fila | Valor original preservado |
| `NbTurnoA` es `NULL` o vacío al consultar | Servicio `listarTurnosActivos()` | Devuelve `descripcion = CoTurno` | El consumidor recibe el código como respaldo |
| `CoTurno` también está vacío | Servicio `listarTurnosActivos()` | Devuelve `descripcion = ''` | El consumidor debe manejar el texto vacío |
| Migración ejecutada dos veces | Introspección de columna | No se duplica la columna; el backfill es idempotente | Esquema y datos estables |
| Driver no soportado por la introspección | `IntrospeccionEsquema::driverIntrospeccion()` | Lanza excepción y detiene la migración | No se modifica el esquema |
| Fallo de conexión o permisos durante `init:sucursal` | Excepción del comando | `init:sucursal` informa el error y no continúa con los seeders | La sede queda en el estado previo a la migración fallida |
| Seeder demo ejecutado sobre un esquema de pruebas sin `NbTurnoA` | Error de columna desconocida en SQLite | La prueba falla | Se debe actualizar el esquema de prueba antes de ejecutar el seeder |

## Reglas de negocio y validaciones

- `NbTurnoA` vive únicamente en la base de cada sede; no se crea en la base principal.
- La columna es `VARCHAR(100)`, nullable y con `DEFAULT NULL`.
- El texto fijo para filas existentes es exactamente `Sin descripción`.
- El backfill solo actualiza filas con `NbTurnoA IS NULL`; nunca sobrescribe un valor existente.
- La migración es idempotente: se puede ejecutar varias veces sin duplicar columnas ni reescribir datos.
- La migración no modifica `CreateCeturno` ni `AddActivoToCeturno`.
- `listarTurnosActivos()` mantiene las claves actuales `id` y `codigo`, y agrega `descripcion`.
- `descripcion` usa `NbTurnoA` cuando tiene valor; en caso contrario usa `CoTurno`.
- No se agrega lógica de presentación ni de edición en esta feature.
- No se elimina ni se renombra `CoTurno`; sigue siendo el código del turno.
- El valor demo `Turno de prueba` es solo para el seeder de demostración y no se aplica en `init:sucursal`.

## Áreas afectadas

| Acción | Archivo / ubicación | Motivo |
| --- | --- | --- |
| Agregar | `app/Database/Migrations/2026-11-03-000110_AddNbTurnoAToCeturno.php` | Crear la columna `NbTurnoA` y aplicar el backfill idempotente |
| Modificar | `app/Commands/LoadBranchConfig.php` (`getBranchMigrationFiles()`) | Registrar la migración para `init:sucursal` |
| Modificar | `app/Libraries/Academica/OfertaAcademicaService.php` (`listarTurnosActivos()`) | Seleccionar `NbTurnoA` y exponer `descripcion` con respaldo `CoTurno` |
| Modificar | `app/Database/Seeds/Demo/SucursalAcademicaSeeder.php` | Agregar `NbTurnoA` al turno demo |
| Agregar | `tests/app/Database/Migrations/AddNbTurnoAToCeturnoMigrationTest.php` | Probar creación, idempotencia, backfill y `down()` |
| Modificar | `tests/app/Libraries/OfertaAcademicaServiceTest.php` | Incluir `NbTurnoA` en el esquema de prueba y validar `descripcion` |
| Modificar | `tests/app/Integration/OfertaAcademicaServiceIntegrationTest.php` | Incluir `NbTurnoA` y validar el arreglo devuelto |
| Modificar | `tests/app/Integration/Paso3NuevoIngresoTest.php` | Incluir `NbTurnoA` en el esquema SQLite que consume el servicio |
| Modificar | `tests/app/Database/Seeds/SucursalAcademicaSeederTest.php` | Incluir `NbTurnoA` en el esquema de prueba del seeder |

## Criterios de finalización

- [x] Existe la migración `2026-11-03-000110_AddNbTurnoAToCeturno.php` con `up()` y `down()` idempotentes.
- [x] La migración usa `IntrospeccionEsquema` y verifica la columna `NbTurnoA` antes de crearla.
- [x] La migración agrega `NbTurnoA VARCHAR(100) NULL DEFAULT NULL` en `ceturno`.
- [x] La migración actualiza solo las filas con `NbTurnoA IS NULL` a `Sin descripción`.
- [x] La migración está registrada en `app/Commands/LoadBranchConfig.php` después de `AddActivoToCeturno`.
- [x] Una ejecución de `php spark init:sucursal <id>` en una sede limpia crea la columna y deja las filas existentes con `Sin descripción`.
- [x] Una segunda ejecución no duplica la columna ni sobrescribe valores no nulos.
- [x] `OfertaAcademicaService::listarTurnosActivos()` devuelve `id`, `codigo` y `descripcion`.
- [x] Si `NbTurnoA` está vacío o es `NULL`, `descripcion` devuelve `CoTurno`.
- [x] El turno demo de `SucursalAcademicaSeeder` incluye `NbTurnoA = 'Turno de prueba'`.
- [x] Las pruebas de migración, servicio, integración del Paso 3 y seeder demo pasan.
- [x] No se modificaron vistas, controladores, rutas, JavaScript ni el flujo del Paso 3/Paso 4.
- [x] No se creó ninguna migración en la base principal ni se tocó `CreateCeturno`.
- [ ] `MEMORY.md` refleja el nuevo campo y `graphify update .` se ejecutó.

### Verificación manual

1. Paso 1: En un entorno de desarrollo o pruebas autorizado, ejecutar `php spark init:sucursal <id>` para una sede que ya tenga `ceturno`.
2. Paso 2: Consultar la estructura con una sentencia de solo lectura, por ejemplo `SHOW COLUMNS FROM ceturno LIKE 'NbTurnoA'`, y confirmar `VARCHAR(100)`, `NULL` y `DEFAULT NULL`.
3. Paso 3: Consultar las filas existentes y confirmar que las que estaban nulas ahora tienen `Sin descripción`.
4. Paso 4: Ejecutar nuevamente `php spark init:sucursal <id>` y confirmar que no aparece una segunda columna ni cambian los valores no nulos.
5. Paso 5: Insertar o actualizar un turno de prueba con `NbTurnoA = NULL` y ejecutar una consulta equivalente a `listarTurnosActivos()`; confirmar que `descripcion` es igual a `CoTurno`.
6. Paso 6: Ejecutar `php spark demo:seed` en un entorno de pruebas autorizado y confirmar que el turno `PRB` tiene `NbTurnoA = 'Turno de prueba'`.

### Pruebas automatizadas

- `vendor/bin/phpunit tests/app/Database/Migrations/AddNbTurnoAToCeturnoMigrationTest.php`
- `vendor/bin/phpunit tests/app/Libraries/OfertaAcademicaServiceTest.php`
- `vendor/bin/phpunit tests/app/Integration/OfertaAcademicaServiceIntegrationTest.php`
- `vendor/bin/phpunit tests/app/Integration/Paso3NuevoIngresoTest.php`
- `vendor/bin/phpunit tests/app/Database/Seeds/SucursalAcademicaSeederTest.php`

En Windows/PowerShell, si `vendor/bin/phpunit` no está disponible, usar `vendor\bin\phpunit.bat` o `php vendor/phpunit/phpunit/phpunit` con las mismas rutas. No se ejecuta la suite completa porque `tests/app/Models/BotChatSystemTest.php` tiene un fallo preexistente por `DatabaseTestTrait`.

## Riesgos y efectos secundarios

- El texto `Sin descripción` puede aparecer en el futuro Paso 3 si un turno no se configura después de la migración; la feature de presentación debe decidir si lo oculta o lo muestra.
- Si una sede no ejecuta `init:sucursal`, `listarTurnosActivos()` fallará al seleccionar `NbTurnoA`; el despliegue debe aplicar la migración en todas las sedes antes de consumir la nueva clave.
- El valor demo `Turno de prueba` solo existe en `demo:seed`; no debe confundirse con datos reales.
- El `down()` elimina la columna y pierde los valores; no debe ejecutarse en producción sin respaldo y autorización.
- La tabla `ceturno` usa `latin1`; si en el futuro se requieren textos con caracteres fuera de ese charset, será necesario un cambio de esquema adicional.
- Cambiar el arreglo de `listarTurnosActivos()` es aditivo; no rompe consumidores que lean solo `id` y `codigo`, pero los tests que comparan el arreglo completo deben actualizarse.

## Bitácora

| Fecha | Cambio | Autor |
| --- | --- | --- |
| 2026-11-03 | Creación del plan FEAT-020 | opencode (agente) |
| 2026-11-04 | Ejecución de la feature en la rama `p-feature/agregar-nbturnoa-ceturno-por-sede`; estado `en curso` por `MEMORY.md` pendiente | opencode (agente) |
| 2026-11-04 | Migración aplicada con `init:sucursal` en las sedes 1, 2, 3 y 100; columna y backfill verificados por consulta de solo lectura | opencode (agente) |
| 2026-11-04 | Ajuste posterior fuera del alcance original: mostrar `NbTurnoA` como etiqueta del selector de Turno en `Paso2::index` (ruta `materias`) | opencode (agente) |
| 2026-11-04 | Ajuste posterior en la pantalla final: `Paso4::index` usa `NbTurnoA` en lugar del mapa fijo de `CoTurno` | opencode (agente) |
