# Guia minima de preparacion para piloto 2026-2

Esta guia resume el recorrido operativo para validar el planificador con datos reales antes del piloto academico 2026-2. Para operacion diaria, usar tambien el checklist corto: `/guias/checklist-operativo-2026-2.md`.

## Preparacion tecnica del entorno piloto

Para un piloto institucional, usar `docker-compose.prod.yml` con un archivo `.env.prod` basado en `.env.prod.example`. Antes de operar con datos reales:

1. Confirmar `APP_DEBUG=false`.
2. Reemplazar `POSTGRES_PASSWORD` y `DATABASE_URL` con credenciales reales, no las de desarrollo.
3. Mantener PostgreSQL sin publicar al host; `docker-compose.prod.yml` no define `ports` para `db`.
4. Definir `APP_BIND=127.0.0.1` si la app se expone mediante proxy local. Usar `APP_BIND=0.0.0.0` solo con control de acceso externo.
5. Ejecutar migraciones con `docker compose --env-file .env.prod -f docker-compose.prod.yml run --rm app alembic upgrade head`.
6. Levantar la aplicacion con `docker compose --env-file .env.prod -f docker-compose.prod.yml up -d`.

Mientras no exista autenticacion propia, el piloto no debe exponerse directamente a internet ni a una red institucional abierta. Debe operar detras de VPN, proxy autenticado, allowlist de red o control de acceso externo equivalente.

## Flujo operativo recomendado

1. Cargar catalogo academico desde `/catalogo/importar`.
2. Revisar el catalogo validado en `/catalogo/validado`.
3. Revisar programas creados desde importacion en `/programas` y completar SNIES si aplica.
4. Revisar aulas activas en `/aulas`, incluyendo capacidad, sede, tipo y recursos.
5. Crear o verificar el periodo academico 2026-2 en `/periodos`.
6. Importar el reporte 85 desde `/programacion-academica/importar`.
7. Revisar programaciones con aula pendiente en `/programacion-academica`. Usar el filtro `Grupo` para distinguir asignaturas o programas con varias programaciones, grupos fusionados o asignaciones por grupo.
8. Revisar clases compartidas candidatas y grupos fusionados con el filtro `Agrupacion fisica`.
9. Asignar aula individual o conjunta segun corresponda.
10. Recalcular conflictos manualmente desde `/conflictos`.
11. Revisar vista semanal en `/vista-semanal` o `/`.
12. Revisar disponibilidad en `/disponibilidad`.
13. Revisar diferencias entre aula reportada por plataforma y aula efectiva operativa.
14. Volver al resumen operativo `/gt` y corregir o aceptar alertas de calidad.

## Checklist corto

El archivo `/guias/checklist-operativo-2026-2.md` separa los controles diarios en estos momentos:

- antes de importar;
- despues de importar reporte 85;
- antes de asignar aulas;
- clases compartidas;
- despues de recalcular conflictos;
- antes de usar vista semanal o disponibilidad como evidencia.

## Orden recomendado de carga

1. Catalogo academico.
2. Programas y datos visibles, incluido SNIES cuando aplique.
3. Aulas.
4. Periodo academico 2026-2.
5. Reporte 85 de programacion academica oficial.
6. Reservas existentes exportadas desde fuente operativa, si aplican.
7. Planeaciones manuales de prueba, si aplican.
8. Recalculo de conflictos.
9. Vista semanal y disponibilidad.

## Reporte 85 de programacion academica

El reporte 85, `Horarios de asignaturas por Programa Academico y por Semestre`, es la fuente oficial inicial para programacion academica importada. Cada carga se trata como un snapshot oficial actualizado. Se carga desde `/programacion-academica/importar` y se conserva en entidades separadas de la planeacion manual y de las reservas importadas.

Flujo recomendado:

1. Exportar el reporte 85 como CSV, XLS, XLSX o XLSM.
2. Ir a `/programacion-academica/importar` y cargar el archivo.
3. Revisar el resumen: filas leidas, validas, rechazadas, omitidas, programaciones agrupadas, slots generados, aulas pendientes y advertencias de capacidad.
4. Revisar `/programacion-academica` con el filtro `Aula = Pendiente`.
   El filtro `Programas` permite seleccionar varios programas al tiempo para revisar clases compartidas, grupos fusionados y asignaciones relacionadas.
5. Antes de asignar aula, revisar fechas, dias, franjas y primeras fechas mostradas en el listado.
6. Previsualizar el aula candidata para revisar capacidad y cruces potenciales.
7. Asignar aula a las programaciones pendientes cuando el aula exista en el catalogo maestro.
8. Si la asignacion fue incorrecta, desasignar el aula para devolver la programacion a `PENDIENTE_AULA`.
9. Ir a `/conflictos` y ejecutar el recalculo manual.
10. Validar que los slots importados con aula asignada aparezcan en `/vista-semanal` y ocupen aulas en `/disponibilidad`.

Notas operativas:

- Cada fila del reporte representa una clase en una fecha exacta. Los slots se generan desde esa fecha y la franja horaria de la fila.
- No se generan recurrencias por rango ni por dia de semana, porque eso podria crear clases inexistentes.
- Al reimportar el reporte 85, el sistema concilia cambios contra la programacion activa del mismo periodo.
- En jornadas de articulacion, el operador diligencia manualmente el convenio, colegio o institucion asociada a cada programacion. El dato no viene del reporte 85, se conserva al reimportar y ayuda a identificar estas jornadas, filtrar programaciones y reconocer ocupaciones en la vista semanal y en disponibilidad.
- Despues de cada reimportacion, el sistema puede advertir si una programacion entro o salio de una clase compartida candidata. Estas alertas son de revision operativa, no cambian automaticamente aulas ni asignaciones; los conflictos deben recalcularse para confirmar cruces reales.
- Si cambian fecha u hora, se conservan las aulas ya asignadas cuando corresponde, se regeneran los slots vigentes y se deben validar conflictos.
- Si cambian docente o estudiantes, se actualiza la programacion y se recalculan advertencias de capacidad.
- Las programaciones que ya no aparecen en el nuevo snapshot quedan como no vigentes y dejan de ocupar aulas.
- Si el aula no existe, esta vacia o parece placeholder, la programacion queda como `PENDIENTE_AULA`; no se crean aulas automaticamente.
- Asignar aula actualiza los slots de esa programacion y activa su ocupacion en vista semanal y disponibilidad.
- Cuando una programacion solo cabe parcialmente, `Ver disponibilidad parcial` permite asignar un aula a las fechas completamente libres y volver a consultar el panel para continuar con las fechas restantes.
- Las fechas parcialmente cruzadas no se asignan automaticamente: la sesion completa de esa fecha debe resolverse manualmente, sin repartirla por slots sueltos.
- Una programacion puede quedar distribuida por fecha en varias aulas. La fila resume las aulas y fechas pendientes, y la vista semanal ubica cada slot en su aula efectiva.
- Para desasignar solo una parte, abrir `Cambio por fecha`, seleccionar fechas que tengan aula efectiva y usar `Desasignar fechas seleccionadas`. La accion libera todos los slots de cada fecha elegida y conserva las demas asignaciones.
- La previsualizacion advierte cruces potenciales contra planeacion academica, reservas operativas, reservas importadas y otras programaciones academicas oficiales.
- La seleccion multiple del listado permite asignar una misma aula a varias programaciones visibles cuando el operador necesita resolver bloques relacionados. Antes de confirmar, la previsualizacion valida cruces internos entre las programaciones seleccionadas y cruces externos contra planeacion, reservas importadas, reservas operativas y programaciones importadas no seleccionadas.
- Los cruces internos no se reportan cuando las programaciones solapadas pertenecen a una clase compartida entre programas o a un grupo fusionado valido del mismo programa. Si hay cruces internos o externos, la asignacion masiva exige confirmacion explicita del operador.
- Por defecto, la grilla oculta del selector principal las aulas que generarian cruces. El operador puede activar `Mostrar aulas con cruces en asignacion` para verlas y previsualizar los conflictos; esta ayuda no reemplaza el recalculo manual posterior.
- Desasignar aula deja la programacion y sus slots como pendientes, por lo que dejan de ocupar disponibilidad.
- Despues de importar, reimportar, asignar o desasignar aulas, los conflictos quedan pendientes y deben recalcularse manualmente desde `/conflictos`.
- La importacion no borra cargas anteriores por defecto y reimportar la misma informacion no duplica slots.
- La capacidad insuficiente genera advertencia, pero no bloquea la importacion.

## Clases compartidas

El listado de programacion academica detecta posibles clases compartidas entre programas cuando coinciden periodo, docente valido y conjunto exacto de fechas y horas vigentes.

Reglas operativas:

- Los docentes vacios o marcados como `NO DEFINIDO`, `SIN DOCENTE`, `POR DEFINIR` o `PENDIENTE` se excluyen para reducir falsos positivos.
- El filtro `Compartidas candidatas` permite revisar solo candidatas o excluirlas de la grilla.
- La previsualizacion de una clase compartida permite confirmar una asignacion conjunta de aula para todos sus miembros; nunca se aplica automaticamente.
- La asignacion individual sigue disponible como opcion secundaria para casos excepcionales.
- En una asignacion conjunta, la capacidad se evalua sumando estudiantes matriculados y ofertados de todos los programas miembro.
- En vista semanal y agenda compacta, los miembros de una clase compartida se muestran como una sola ocupacion fisica con programas, asignaturas y totales de estudiantes.
- Cada programacion miembro conserva su trazabilidad individual y enlaces hacia la programacion academica importada.
- La disponibilidad del aula se calcula por ocupacion fisica, no por la cantidad de programas asociados a la clase compartida.
- Los cruces potenciales conjuntos ignoran a los miembros del mismo grupo y comparan contra ocupaciones externas vigentes.
- El recalculo global de conflictos tambien reconoce el grupo compartido: sus miembros no generan conflicto interno entre si.
- Las clases compartidas si generan conflictos contra planeaciones, reservas y otras programaciones externas que se solapen.
- Despues de asignar o desasignar aulas de clases compartidas, ejecutar `/conflictos/recalcular` desde la UI; los conflictos internos antiguos pasan a `RESUELTO` durante el recalculo.

## Grupos fusionados del mismo programa

La programacion academica reconoce de forma conservadora grupos del mismo programa que representan una sola ocupacion fisica. Deben coincidir el periodo, el programa normalizado, un docente valido, el semestre cuando esta informado y la firma exacta de fechas y horas vigentes. La materia debe coincidir por nombre normalizado o por codigo base. Cuando grupo o grupo_externo vienen informados, se usa la diferencia entre grupos como evidencia conservadora; si ambos estan ausentes, prevalecen las demas coincidencias exactas. El aula no participa en la deteccion.

Reglas operativas:

- La grilla los identifica con el badge Grupos fusionados, separado de Clase compartida candidata.
- El filtro Agrupacion fisica permite revisar exclusivamente los grupos fusionados.
- La previsualizacion permite asignar o cambiar aula conjuntamente, suma estudiantes para las advertencias de capacidad y conserva la opcion individual.
- Los miembros de una fusion no generan conflictos internos, pero siguen generando conflictos contra planeaciones, reservas y otras programaciones externas.
- Vista semanal y disponibilidad muestran la fusion como una sola ocupacion fisica y mantienen la trazabilidad de cada programacion miembro.
- Las alertas de transicion Ahora compartida y Dejo de ser compartida continuan aplicando solo a clases compartidas entre programas. Alertas equivalentes para entrada o salida de grupos fusionados quedan pendientes para una iteracion posterior.

## Diferencia entre fuentes de ocupacion

- Planeacion manual: creada desde `/planeacion`, editable por usuarios y ligada al catalogo academico validado.
- Programacion academica importada: cargada desde el reporte 85 como programacion oficial por fechas exactas.
- Reservas operativas: ocupaciones manuales creadas desde `/reservas-operativas`, opcionalmente asociadas a un programa academico activo.
- Reservas importadas: ocupaciones externas cargadas desde archivo, por ejemplo reservas existentes en Google Sheets.

La vista semanal, disponibilidad y conflictos consideran las cuatro fuentes cuando tienen slots `ACTIVO` y aula asignada.

## Reservas operativas manuales

1. Ir a `/reservas-operativas/nueva`.
2. Seleccionar una o varias aulas activas con el buscador de aulas, responsable/solicitante, actividad, fechas, dias y franja horaria entre 07:00 y 22:00.
3. Asociar programa academico activo cuando aplique. Si `tipo_solicitante` es `PROGRAMA_ACADEMICO`, el programa es obligatorio.
4. Guardar solo si la previsualizacion no reporta cruces contra planeacion manual, programacion importada, reservas importadas u otras reservas operativas.
5. Validar que los slots aparezcan en `/vista-semanal` y bloqueen disponibilidad.
6. Recalcular conflictos manualmente desde `/conflictos` antes de usar la informacion como evidencia.

Notas operativas:

- Editar aula, fechas, dias u horario deja los slots activos anteriores como `REGENERADO` y crea nuevos slots `ACTIVO`.
- Cancelar una reserva conserva el registro y marca sus slots activos como `CANCELADO`.
- La creacion multi-aula genera una reserva por aula con `grupo_reserva_uid` comun; si una de las aulas cruza, no se guarda ninguna.
- La clonacion abre un formulario precargado, pero sin aula seleccionada ni estado cancelado.
- No hay recurrencia avanzada en este alcance; se mantiene pendiente para iteraciones futuras.
- Las reservas operativas no reemplazan las reservas importadas; cada modulo conserva su origen.
## Reservas existentes desde Google Sheets

1. Exportar la hoja de Google Sheets como CSV o XLSX. Para reservas por rango, usar la hoja `Reservas`; si ya se cuenta con ocupaciones por fecha, hora y aula, se puede usar `SLOTS_HISTORICO`.
2. Ir a `/reservas-importadas/importar` y cargar el archivo exportado.
3. Revisar el resumen de registros leidos, importados, omitidos y rechazados. Corregir en la hoja fuente los errores de aula, fecha u hora y reexportar.
4. Ir a `/conflictos` y ejecutar el recalculo manual.
5. Validar que las reservas importadas aparezcan como ocupacion en `/vista-semanal` y bloqueen aulas en `/disponibilidad`.

Notas operativas:

- La importacion no borra reservas anteriores por defecto.
- Reimportar el mismo archivo no duplica reservas si conserva la misma informacion base.
- Las reservas canceladas se conservan como inactivas y sus slots no ocupan disponibilidad.
- No hay edicion de reservas desde la matriz; las correcciones deben hacerse en Google Sheets y luego reimportarse.

## Aulas: campos minimos recomendados

El MVP no tiene carga masiva de aulas por archivo. Para preparar una carga manual consistente, usar esta estructura como referencia:

| Campo | Requerido | Ejemplo |
| --- | --- | --- |
| `codigo_aula` | Si | A-101 |
| `nombre` | Si | Aula 101 |
| `capacidad` | Si | 35 |
| `tipo_aula` | Recomendado | Aula tradicional |
| `sede` | Recomendado | Principal |
| `bloque` | Opcional | Bloque A |
| `piso` | Opcional | 2 |
| `recursos` | Recomendado | Video beam, tablero, sonido |
| `estado` | Si | ACTIVA |

Antes de planear, revisar en `/aulas` las aulas activas marcadas como `Completar datos`. Para piloto, priorizar capacidad mayor que cero, tipo de aula, sede y recursos.

## Periodo academico 2026-2

Desde `/periodos`, usar `Crear 2026-2` para abrir el formulario prellenado. Confirmar las fechas institucionales antes de guardar:

- Codigo: `2026-2`.
- Nombre: `Periodo academico 2026-2`.
- Fecha inicio sugerida: `2026-07-01`.
- Fecha fin sugerida: `2026-11-30`.
- Estado: `ACTIVO`.

Solo debe existir un periodo activo. Si ya hay otro periodo activo, dejar 2026-2 en `BORRADOR` hasta cerrar o archivar el anterior.

## Criterios minimos antes del piloto

- No deben quedar programas pendientes de revision sin decision operativa.
- Las aulas usadas deben tener capacidad, tipo, sede y recursos revisados.
- El periodo 2026-2 debe estar activo y con fechas correctas.
- La programacion academica importada debe tener aulas efectivas asignadas cuando corresponda.
- Las reservas operativas manuales deben generar slots activos cuando apliquen.
- Las planeaciones manuales de prueba deben generar slots activos.
- Los conflictos deben estar recalculados antes de revisar vista semanal o disponibilidad.
- Las alertas del resumen operativo `/gt` deben revisarse y resolverse o aceptarse explicitamente.

## Conciliacion de aulas con el reporte 85

- El planificador es la fuente de verdad operativa para el aula efectiva. La vista semanal, disponibilidad y conflictos usan exclusivamente el aula efectiva del slot.
- El aula recibida en el reporte 85 se conserva por slot como evidencia de lo registrado en la plataforma academica. No reemplaza automaticamente una asignacion efectiva ya decidida en el planificador.
- Si un slot no tiene aula efectiva y el reporte trae un aula valida, esa aula puede adoptarse como asignacion inicial. Si el reporte no trae aula, nunca se borra la asignacion efectiva existente.
- La grilla identifica aulas sincronizadas, diferencias con plataforma, aulas distintas por fecha y cambios puntuales manuales.
- Un cambio puntual se gestiona por fecha: al seleccionar una fecha, el sistema aplica el aula nueva a todos los slots vigentes de esa fecha (`ACTIVO` o `PENDIENTE_AULA`), conserva el aula anterior y el motivo, y deja los conflictos pendientes de recalculo. No se aplica a slots `REGENERADO` ni `CANCELADO`.
- En clases compartidas candidatas se recomienda aplicar el cambio puntual al grupo completo para las mismas fechas; los miembros del grupo siguen sin generar cruces internos.
- Restablecer un aula general para toda la programacion o para todo el grupo limpia los cambios puntuales vigentes en los slots activos; los campos de cambio puntual representan el estado vigente, no un historico completo.
- El aula reportada por plataforma sigue separada del aula efectiva aunque se hagan cambios por fecha o se restablezca el aula general.
- Despues de cada reimportacion se deben revisar las diferencias con plataforma y corregirlas en la fuente o confirmar la decision operativa local segun corresponda.

## Asignacion parcial de aulas

- Si una programacion no cabe completa en una sola aula, usar `Ver disponibilidad parcial` en `/programacion-academica`.
- La herramienta muestra, por aula, cuantos slots y fechas estan libres, parcialmente libres o bloqueados, junto con el origen y responsable de cada cruce.
- La asignacion asistida solo aplica automaticamente fechas completamente libres. Tambien permite seleccionar un subconjunto de esas fechas; los slots parciales dentro de una fecha se mantienen sin cambios en esta iteracion.
- Las asignaciones por fecha pueden distribuir una programacion entre varias aulas sin perder la trazabilidad del aula efectiva, el aula anterior y el motivo del cambio.
- Para clases compartidas o grupos fusionados se evalua una sola vez cada slot fisico y la asignacion se aplica al grupo completo.
- Despues de realizar asignaciones parciales, recalcular conflictos antes de revisar la operacion final.

## Normalizacion horaria del reporte 85

- El sistema trabaja operativamente con bloques horarios completos de una hora.
- Si el reporte 85 trae minutos intermedios, la franja se normaliza por cobertura: el inicio baja a la hora anterior en punto y el fin sube a la hora siguiente en punto.
- Por ejemplo, `13:30-17:30` se bloquea operativamente como `13:00-18:00`; una franja exacta como `14:00-18:00` se conserva.
- La hora original y la franja operativa quedan registradas en observaciones con la marca `HORA_NORMALIZADA`.
- Esta cobertura protege la disponibilidad y la deteccion de conflictos aunque el tiempo real reportado sea menor que los bloques ocupados.
- Los reportes futuros de usabilidad deberan diferenciar la duracion real reportada de los bloques horarios ocupados.

## Resumen operativo

El resumen operativo esta en `/gt`. Muestra conteos y alertas generales de programas, aulas, periodos, slots de planeacion, conflictos activos, estado de recalculo y calidad de datos. La revision detallada de programacion importada, pendientes de aula, reservas, conciliacion y disponibilidad se hace en sus modulos especificos.