Memoria · Decisions · The Professor

decisions.md — Registro de decisiones (ADRs)

Decisiones pedagógicas y técnicas del curso, con su porqué. Formato ligero de ADR. Se añaden solo decisiones con impacto; nunca se borran.

Fecha: 2026-09-28
Estado: aceptada
Contexto: El alumno quiere un curso documentado en MD que también sirva a otros desarrolladores, con memoria para que cualquier agente retome el hilo. Existen muchas formas de estructurarlo (una sola wiki, un repo por lección, chat puro…).
Decisión: Estructura README.md + CURRICULUM.md + memory/ + lessons/NN-nombre/{lesson.md,exercises.md,solutions.md}. Metodología por lección: objetivos → teoría → ejercicios → corrección → autoevaluación → aplicación al proyecto.
Consecuencias: El curso es autocontenido, navegable y continuable por cualquier agente. Coste: mantener la memoria actualizada en cada sesión (obligatorio según protocolo).

Fecha: 2026-09-28
Estado: aceptada
Contexto: El requisito dice explícitamente que el desarrollador (alumno) elige lenguaje y framework, y el profesor enseña a partir de eso. Antes de la elección no se puede impartir código concreto.
Decisión: Las lecciones 00 y 01 se redactan genéricas (teoría universal, código de ejemplo con nota de adaptación). Al confirmarse el stack, el profesor personaliza las instrucciones de instalación y los ejemplos, y lo registra en student-profile.md.
Consecuencias: Respetamos la autonomía del alumno; la lección 01 ya es útil aunque tarde en elegir. Coste: primera sesión de personalización tras la elección.

Fecha: 2026-09-28
Estado: aceptada (v1; se revisará en Lección 10 con transacciones reales)
Contexto: Al empezar el proyecto hilo conductor se decidió modelar antes de seguir teoría. Había varias opciones para garantizar la invariante I1 (un asiento no se vende dos veces): checks en vistas, contadores de aforo, constraints de BD.
Decisión: Invariantes estructurales en la base de datos mediante UniqueConstraint condicionales en ReservationItem (PostgreSQL las soporta; MySQL no, ver ADR-0003). Reservas de un solo evento para transacciones atómicas locales. Asiento como fila física (no contador) para poder expresar I1. Máquinas de estado como métodos del modelo con excepciones de dominio; cancel() idempotente. AUTH_USER_MODEL a app propia declarado antes de la primera migración.
Consecuencias: El modelo es correcto por construcción y auditable. Coste: PostgreSQL requerido (o adaptar constraints), y el job de expiración (L29) deberá consultarse status+expires_at eficientemente (índice ya creado).

Fecha: 2026-09-28
Estado: aceptada (sustituye parcialmente al ADR-0005)
Contexto: El ADR-0005 versionaba el HTML de las lecciones generado por el build. El alumno pidió explícitamente mantener todo en Markdown y tener un renderizador que lo muestre en la web — el Markdown como única fuente de verdad, sin artefactos derivados en el repo.
Decisión: El repo no versiona HTML de lecciones (site/lessons/ en .gitignore). El servidor site/tools/serve.py (Python puro, stdlib) renderiza en cada petición los .md con el parser del curso: portada (catálogo generado desde los .md presentes), lecciones, memoria, temario y docs. Sirve con Cache-Control: no-store para que editar un .md y recargar baste. build.py conserva las funciones puras de render y un modo build opcional para CI/despliegue estático.
Consecuencias: Editar = recargar; cero pasos de build para publicar; el agente (o el alumno) trabaja siempre en Markdown. Coste: el sitio requiere el renderizador corriendo (para estático puro queda el modo build); el render por petición es barato (ficheros locales, documentos pequeños).

Fecha: 2026-09-28
Estado: aceptada
Contexto: El alumno pidió las lecciones y ejercicios «1 x 1» visibles en la web sin abrir ficheros locales. Opciones: renderizar Markdown en el navegador con JS (dependencia + prohibición de innerHTML de las reglas dicresoft), usar un generador externo (Hugo/ Eleventy: dependencia nueva), o pre-renderizar en build.
Decisión: Generador propio en Python puro (site/tools/build.py, sin dependencias) que convierte lessons/<slug>/{lesson,exercises,solutions}.md a site/lessons/<slug>/<doc>/index.html con el sistema de diseño del sitio. El Markdown fuente conserva los emojis (convención del repo); el build los elimina o traduce — la UI publicada no lleva ninguno. El catálogo de la portada se regenera desde un catálogo declarativo único entre marcadores. Cobertura: 25 tests unitarios (site/tools/test_build.py).
Consecuencias: El sitio sigue siendo estático y funciona sin JS (gate de accesibilidad); el código de las lecciones se sirve escapado (sin riesgo de inyección); añadir una lección nueva = escribir el MD y ejecutar python3 site/tools/build.py. Coste: el parser cubre el subconjunto Markdown del curso (no Markdown arbitrario); los tests lo protegen contra regresiones.

Fecha: 2026-09-28
Estado: aceptada
Contexto: El temario exige SQL avanzado, EXPLAIN, transacciones y funciones de ventana; PostgreSQL es el motor que mejor las soporta y el más usado en la industria.
Decisión: Salvo preferencia contraria del alumno, todo el módulo de bases de datos se imparte sobre PostgreSQL. La Lección 01 usa SQL estándar portable para los ejemplos.
Consecuencias: Coherencia durante todo el módulo 2; si el alumno prefiere otro motor, se registra aquí la excepción.