platform-STALD
Plataforma escolar: portal, Inglés en línea (actividades, exámenes y grupos; alumnos y alumnas en el registro de la
plataforma, sin Notion), Juegos y Secundaria (tablero de clases estilo RPG con XP, insignias y mundos; sin Notion desde octubre de 2026).
Flujo de trabajo: Spec-Driven Development con OpenSpec (/opsx:new → /opsx:ff → /opsx:apply →
/opsx:verify → /opsx:archive). Todo cambio empieza como un cambio en openspec/changes/.
Documentación
| Documento | Contenido |
|---|
| openspec/project.md | Qué es, arquitectura, URLs, comandos |
| openspec/config.yaml | Contexto y reglas para los artefactos OpenSpec |
| docs/base-standards.md | Principios base e idioma |
| docs/documentation-standards.md | Mantenimiento de la documentación |
| docs/frontend-standards.md | Páginas HTML / GitHub Pages; estructura de juegos.html en juegos/app/ |
| docs/backend-standards.md | Backend Deno Deploy, contrato HTTP, seguridad |
| docs/data-model.md | Base de Notion de Secundaria, registro de Inglés, exámenes y actividades semanales (formatos JSON) y tablas stald_* |
| docs/deno-deploy-setup.md | Configurar el backend en Deno Deploy y el repo privado de datos |
| docs/pruebas.md | Pruebas unitarias (CI) y E2E en local (tests/e2e/correr.sh), sesión de prueba, stald_test_* y análisis de calidad (tests/calidad, ) |
Herramientas del agente (Claude Code)
- Hook
proteger-git (.claude/hooks/proteger-git.mjs, registrado en
.claude/settings.json): antes de cada comando de Bash o PowerShell bloquea git add/commit
que incluirían un .env o algo de la carpeta privada IA/ (también por git add -A o lo ya preparado), y el
git push a main (incluye HEAD y refs/heads/main). El repo de datos sí publica en main. Revísalo con
/hooks; se activa al abrir una sesión nueva.
- Subagentes (ai-specs/agents/, visibles con
/agents): revisor-solo-lectura (segunda
lectura del diff contra su cambio OpenSpec) y verificador-pruebas (corre pruebas y devuelve solo el resumen), más
backend-developer, frontend-developer y product-strategy-analyst.
- Espejos:
.claude/ y .gemini/ son copias de ai-specs/; tras editar un agente o skill corre
node ai-specs/scripts/sincronizar-espejos.mjs (ver docs/base-standards.md §6).
Inicio de sesión (Supabase Auth)
Las clases entran con correo y contraseña, sin enlaces por correo. La contraseña inicial la da el profe y se pide
cambiarla al entrar; si alguien la olvida, el profe la restablece desde el portal («🔑 Restablecer contraseña»).
En Juegos, quien no es de las clases entra o se registra con su correo y su nick. La sesión dura semanas en el
dispositivo y es la misma en portal, Inglés, Juegos y Secundaria (comun/auth.js). El servidor valida el token y
toma el correo verificado. Hasta el 2026-10-12 se acepta todavía el correo sin sesión (salvo el admin, que siempre
requiere sesión).
Detalle en docs/backend-standards.md y
docs/frontend-standards.md.
Vigilancia del servidor
Cada 30 minutos, GitHub Actions revisa https://stald.jalducin.deno.net/salud. Si el servidor se bloquea (límite de
la API de GitHub agotado) o no responde, abre un issue "🔴 Servidor bloqueado" que menciona a @jalducin, y GitHub
manda el aviso por correo. Cuando se recupera, lo cierra con "✅ Recuperado". Detalle en
docs/backend-standards.md.
El correo llega a la dirección de notificaciones de la cuenta de GitHub. Para dirigirlo a otra, configúralo en
GitHub → Settings → Notifications → Custom routing (y en Settings → Emails, verifica esa dirección).
Partidas en tiempo real (Supabase)
Las partidas multijugador usan Supabase Realtime del proyecto Portafolio (el mismo que usa el formulario de
contacto del portafolio jalducin.github.io; son dos repos apuntando al mismo proyecto, sin tablas compartidas).
Deno publica cada cambio de la sala en un canal secreto y las páginas lo reciben al instante, con una consulta de
respaldo cada 30 s. Sin las variables SUPABASE_* en Deno, las partidas funcionan con sondeo. Variables en
docs/deno-deploy-setup.md; detalle en docs/backend-standards.md.
Datos vivos en Postgres
Los grupos de clase y los datos vivos de Inglés (alumnos, resultados y avance) están en el Postgres de Supabase. El
registro de alumnos y alumnas (alumnos.json) es la única fuente de identidad de Inglés: Inglés ya no lee Notion. Es
el mismo proyecto Portafolio, con tablas stald_*, protegidas con RLS y accesibles solo desde el servidor. El
contenido (actividades, exámenes y semanas) sigue en el repo. Juegos (salas, partidas, ranking, perfiles) pasa a
Postgres al migrarse con herramientas/migrar-ingles.ts --juegos. Si Postgres no responde, el servidor responde 503
en lugar de mostrar datos viejos. Detalle en docs/data-model.md.
