Cancha Total F5 — Sistema de reservas

En vivo: https://cancha-total-f5.vercel.app · salud de la base: https://cancha-total-f5.vercel.app/api/health

Sistema de reservas para las dos canchas techadas de fútbol 5 de Cancha Total F5. Permite ver la disponibilidad del día, registrar reservas y cancelarlas.

Node + Express con las vistas renderizadas en el servidor, y los datos en SQLite: un archivo local en desarrollo, Turso —que es SQLite en la nube— en producción. El mismo driver para las dos, así que el camino que ejercitan las pruebas es el que corre desplegado.

La pantalla

La grilla de disponibilidad cuenta por qué la tarifa cambia. A las 17:00 se encienden las luces y el bloque pasa de ₡15.000 a ₡20.000: por eso las horas con luz van sobre fondo cálido, llevan la marca de un foco, y una regla ámbar cruza la tabla exactamente donde se aprieta el interruptor. El precio deja de ser un número que sube sin explicación.

Y cada bloque es una acción: el libre abre la reserva con su cancha, su fecha y su hora ya puestas; el ocupado lleva a la reserva que lo ocupa, para verla o anularla. Nadie tiene que volver a elegir a mano el bloque que acaba de mirar.

  HORA     ESTADO              TARIFA     ACCIÓN
  16:00    ⊘ Libre            ₡15.000    ⊕ Reservar
 ═══════════════════════════════════════════════════  ← se encienden las luces
  17:00 ⚲  ⊗ Ocupado          ₡20.000    ✎ Administrar
  18:00 ⚲  ⊘ Libre            ₡20.000    ⊕ Reservar

Lo demás que hay que saber para usarlo:

• Se puede usar desde un teléfono. Las dos canchas se ven lado a lado cuando hay ancho y se apilan cuando no. La lista del día, que tiene siete columnas, scrollea dentro de su propio marco: la página nunca se corre de lado.
• Sigue el tema del sistema operativo, claro u oscuro. No hay que elegir nada.
• El color nunca es la única señal. Cada estado lleva su texto y su icono, así que se distingue igual sin percibir el color y igual en una impresión en blanco y negro.
• Funciona sin internet. No pide tipografías, iconos ni bibliotecas a ningún servidor: todo viaja dentro de la página. Si el local se queda sin red, el sistema se ve igual.

Las capturas de todas las pantallas —claro y oscuro, a 375 px y a pantalla completa— están en Week5/capturas/interfaz/ del repositorio del curso: https://github.com/jcyanez/LEClaudeCode_JuanCa_Cenfotec

Arrancar

npm ci          # o npm install
npm run datos   # crea reservas.db con 10 reservas de ejemplo
npm start

El servidor queda escuchando en http://localhost:3000

npm run datos borra reservas.db si existe y la recrea desde cero, con fechas relativas al día en que se corre. reservas.db no está en el repositorio: sin correr ese comando, el sistema arranca igual, con cero reservas.

Verificar

./verificar.sh

Un solo comando: corre las mismas etapas que el CI, en el mismo orden, y devuelve un código de salida. La idea es que un turno que cierra en verde no descubra en el pipeline algo que se podía ver acá.

Etapa	Qué revisa
Lint	ESLint 9, reglas de defecto (no de estilo)
Pruebas	las 129 pruebas de node:test
Build	que el artefacto desplegable sea coherente (ver más abajo)
Humo	que el sistema arranque, responda y llegue a su base

Código	Qué significa
0	Todo pasa. Se puede cerrar el turno.
2	Algo falló, o faltan las dependencias.

Ese código es el que usa el hook Stop de .claude/settings.json para impedir que un turno del agente cierre con la verificación en rojo.

Para correr una prueba suelta, o un archivo, se usa el corredor de Node directamente:

node --test pruebas/tarifas.test.js
node --test --test-name-pattern "17:00" "pruebas/*.test.js"

Las pruebas no dependen del reloj, ni de la red, ni del orden, ni unas de otras: cada una levanta el sistema en un puerto libre, sobre una base de datos propia que desecha al terminar, y con el reloj puesto en un instante fijo. Correrlas no toca reservas.db.

Configuración

Sin variables de entorno el sistema arranca como siempre, contra el archivo local. Existen para poder levantarlo en otro puerto, contra otra base o con el reloj fijo, sin tocar el código:

Variable	Por omisión	Para qué
TURSO_DATABASE_URL	—	Dirección de la base en Turso. Si está, el sistema habla con Turso.
TURSO_AUTH_TOKEN	—	Credencial de Turso. Va junto con la anterior; una sin la otra falla al arrancar y lo dice.
CANCHA_PUERTO	3000	Puerto. Con 0 pide uno libre al sistema operativo.
CANCHA_BD	reservas.db	Ruta del archivo de la base de datos.
CANCHA_AHORA	el reloj real	Fija el instante que el sistema considera «ahora».

Los nombres están en .env.example, sin valores. Para trabajar en local se copia a .env y se llena; npm start y los scripts de base de datos lo leen solos, con --env-file-if-exists de Node. .env está en .gitignore y no se sube nunca.

Dónde vive cada variable

Las mismas dos variables de Turso están cargadas en dos lugares distintos, que no se hablan entre sí, y confundirlos es la causa más común de "funciona el pipeline pero la app da error":

	GitHub Actions Secrets	Vercel Environment Variables
Quién las lee	Los workflows, mientras corren en el runner	La aplicación desplegada, en tiempo de ejecución
Para qué acá	Aplicar migraciones a Turso, y autenticar la CLI de Vercel	Que la app conecte a Turso al atender un pedido
Dónde se cargan	Settings → Secrets and variables → Actions	Vercel → Project Settings → Environment Variables
Qué contiene	TURSO_DATABASE_URL, TURSO_AUTH_TOKEN, VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID, VERCEL_AUTOMATION_BYPASS_SECRET	TURSO_DATABASE_URL, TURSO_AUTH_TOKEN

Cargar el token de Turso solo en GitHub deja el despliegue verde y la aplicación sirviendo errores: el workflow pudo migrar, pero la función desplegada no tiene con qué conectarse. Cargarlo solo en Vercel deja la app funcionando y el job de migraciones rojo. Hacen falta los dos.

Ninguno de esos valores aparece en el repositorio, en un log ni en este README: lo único versionado son los nombres, en .env.example. El detalle está en docs/CI-CD.md § 8.

El orden de precedencia de la base importa: CANCHA_BD gana sobre TURSO_DATABASE_URL. Quien nombra un archivo concreto está pidiendo ese archivo, y quien lo hace siempre es el arnés de pruebas. Si Turso ganara, bastaría con tener TURSO_DATABASE_URL exportada en la terminal para que npm test escribiera —y borrara— en la base de producción.

Base de datos

El esquema vive en archivos .sql versionados, no en el código:

database/
  migrations/
    001-crear-tabla-reservas.sql
    002-indices-de-consulta.sql
  migrar.js
  sembrar.js

npm run db:migrate    # aplica lo que falte, contra la base que digan las variables
npm run db:seed       # reservas de ejemplo

Las migraciones son idempotentes y no destructivas: todas usan IF NOT EXISTS y ninguna lleva DROP. Correr db:migrate sobre la base de producción no toca un dato, y por eso el pipeline lo hace en cada despliegue. El servidor también las corre al arrancar, así que una base vacía queda usable sin pasos previos.

La siembra es deliberadamente arisca: por omisión no borra nada —si la tabla tiene filas, se detiene y lo dice—, hace falta --reiniciar para reemplazarlas, y sobre una base remota hace falta además --confirmar-remoto.

npm run datos sigue siendo el atajo de desarrollo de siempre: borra el archivo local y lo recrea sembrado. Se niega a correr si las variables apuntan a una base remota.

CI/CD

Desarrollador → Git → GitHub → GitHub Actions → CI → Vercel → Turso
                                                │
                                          ¿CI falló?
                                                │
                                          NO HAY DESPLIEGUE

Tres workflows en .github/workflows/:

Workflow	Cuándo	Qué hace
ci.yml	push a una rama · pull request	install → lint → typecheck (N/A) → pruebas → build → humo
deploy-preview.yml	pull request	CI, y si pasa, un preview en Vercel con su propia URL
deploy-production.yml	push a main	CI → migrar Turso → vercel deploy --prod → verificar /api/health

El CI está escrito una sola vez: los dos workflows de despliegue lo invocan con uses: ./.github/workflows/ci.yml. Así no puede pasar que la puerta del preview y la de producción revisen cosas distintas.

La regla del despliegue está en el grafo de dependencias, no en un comentario: un job con needs: ci no arranca si el CI falló. Y el despliegue lo dispara el pipeline en vez del auto-deploy de Vercel justamente por eso — el auto-deploy publica antes de saber si las pruebas pasaron.

El CI corre contra un archivo temporal del runner y no recibe los secretos de Turso: no tiene con qué tocar la base de producción. La puerta funciona sin ningún servicio externo.

Nada del pipeline flota: las ocho referencias a acciones externas están fijadas al SHA completo (actions/checkout@3d3c42e… # v7) en vez de a la etiqueta móvil @v7, y la CLI de Vercel es una devDependency exacta (59.10.0, sin ^ ni ~) fijada en el package-lock.json, en vez de vercel@latest.

La política de main

main está protegida. No se puede empujar a main, ni siquiera siendo el dueño del repositorio:

Regla	Estado
Pull request obligatorio	sí
Aprobaciones requeridas	0 — la puerta la hace el CI, no una firma
Check obligatorio	Lint · Pruebas · Build · Humo
Rama al día antes de fusionar	sí (strict)
Aplicada a administradores	sí (enforce_admins)
Force-push · borrado de la rama	deshabilitados
Actores de bypass	ninguno

Se comprueba leyendo la API, no la interfaz:

gh api repos/jcyanez/cancha-total-f5/branches/main/protection \
  --jq '{admins:.enforce_admins.enabled, checks:.required_status_checks.contexts}'

La demostración de que la puerta cierra y abre está dentro de un mismo pull request, el #2:

	Commit	Corrida pull_request	Resultado
Rojo	65f5c90	runs/33446508303	88 pruebas, 1 falla · PR BLOCKED · preview skipped
Verde	6f4921e	runs/33446710929	87 pruebas, 87 pasan

El preview del PR también quedó verde —runs/33451632482, 10/10 con backend=turso—, después de corregir dos defectos de la sonda de humo y de cargar las variables de Turso en el entorno Preview de Vercel. La historia completa está en docs/ENTREGA-CASO-6.md § 3.

main tiene además un commit directo histórico, d4fa9f9, anterior a la activación de la protección. No se oculta ni se reescribe: borrarlo eliminaría la evidencia de cuándo empezó a regir la política. El detalle está en docs/CI-CD.md § 10.

Todo el detalle está en docs/CI-CD.md: qué es CI, qué es CD y cuál se usa acá, el vocabulario de GitHub Actions, la explicación de cada YAML, la diferencia entre GitHub Secrets y las variables de entorno de Vercel, y la lista de evidencias para la entrega.

Comprobar el despliegue

curl https://cancha-total-f5.vercel.app/api/health

{ "status": "ok", "database": "connected", "driver": "libsql", "backend": "turso", "reservas": 10 }

Hace una lectura real contra la base. No devuelve la URL de la base ni el token, y la prueba de humo verifica activamente que no los filtre.

node herramientas/humo.js https://cancha-total-f5.vercel.app

Interroga una aplicación ya desplegada: la salud, las pantallas, la cotización. Contra una URL remota solo hace lecturas, y exige que el backend reportado sea turso — una app serverless sirviendo desde un archivo estaría perdiendo cada reserva.

Los documentos

El sistema se recibió sin un solo documento. Estos se escribieron reconstruyéndolo:

• ESPECIFICACION.md — qué debe hacer el sistema. Cada afirmación con su fuente declarada: la administradora, el comportamiento del sistema recibido, o una decisión explícita del cliente. Es la fuente de verdad: las pruebas responden a este documento, nunca al código.
• HALLAZGOS.md — todo lo que la suite descubrió al contrastar el sistema contra la especificación, con la prueba que delata cada cosa y la evidencia de cierre.
• STATUS.md — el estado del trabajo.
• docs/CI-CD.md — el pipeline de integración y despliegue continuo, explicado de cero. Posterior a la entrega del caso.
• docs/ENTREGA-CASO-6.md — la matriz requisito → evidencia del Caso práctico 6, con el enlace real de cada comprobación y el estado honesto de lo que no se pudo verificar.
• docs/MEJORA-RESERVAS-INTERACTIVAS.md — los bloques de la grilla se vuelven accionables. Mejora de producto posterior a los casos, con sus rutas nuevas, sus decisiones y el relato de cómo la suite existente le fijó la forma al diseño.

Cómo está armado

server.js         el sistema: rutas, reglas del negocio y vistas
bd.js             acceso a datos: el único archivo que sabe con qué base habla
datos.js          atajo de desarrollo: rehace la base local sembrada
verificar.sh      la puerta de calidad
api/index.js      punto de entrada serverless de Vercel
vercel.json       manda todas las rutas a esa función única
database/         el esquema versionado y la siembra
herramientas/
  construir.js    verificación del artefacto desplegable
  humo.js         interroga la app —local o desplegada— y su base
pruebas/          la suite
  soporte/        lo que las pruebas usan para hablar con el sistema
docs/CI-CD.md     el pipeline explicado
.github/workflows/  CI y despliegue

El esquema no está en el código: vive en database/migrations/*.sql. Estuvo escrito dos veces —en server.js y en datos.js— y eso fue el hallazgo E-9 del caso práctico; después pasó a un esquema.js compartido, y con la llegada de las migraciones quedó donde corresponde, en SQL versionado.

No hay build de compilación, ni bundler, ni carpeta de archivos estáticos: el HTML se arma en el servidor y la hoja de estilo viaja dentro de él, en la constante ESTILOS de server.js. Lo que sí verifica npm run verificar-artefacto es que el artefacto desplegable sea coherente: que todo parsee, que la entrada serverless cargue, y que ningún archivo de tiempo de ejecución dependa de una devDependency. Esto último es lo que justifica el script: better-sqlite3 es un módulo nativo que quedó como dependencia de desarrollo —lo usa el arnés de pruebas, no el sistema—, y si alguien vuelve a requerirlo desde server.js o bd.js, en local funciona y en producción el despliegue arranca roto.

La hoja de estilo está organizada en dos pisos: primero los tokens —un nombre por cada decisión de color, espacio, tipografía y forma, declarados una sola vez en :root— y después las reglas, que solo consumen tokens. Ningún color literal aparece fuera de ese bloque, y el tema oscuro se limita a redefinir los mismos nombres. Para cambiar el verde de la marca en todo el sistema se toca una línea.

Los cuatro iconos —check-circle, x-circle, warning y lightbulb, del vocabulario de Phosphor— van dibujados como data: URI y se pintan con mask, así que heredan el color del texto: una sola definición sirve para todos los estados y ninguno se pide a un servidor externo.

Una advertencia para quien toque las vistas

Quince pruebas leen el HTML con expresiones regulares que exigen etiquetas pegadas. En concreto:

No tocar	Por qué
<td>8:00</td><td …>Libre</td>	El estado tiene que ser texto directo del <td>, sin nada anidado adentro.
<td>₡15.000</td>	La celda de la tarifa no admite atributos.
<li>texto</li>	Cualquier etiqueta dentro del <li> deja el conteo de errores en cero.
<h2>	Sin atributos: dos pruebas parten el HTML por esa cadena literal.
<option value="8">	Sin atributos extra.
<select name="hora"	name va primero; poner id antes rompe el regex.

Por eso las píldoras, los iconos y la regla de la luz están hechos con CSS sobre el markup que ya existía, y no envolviendo texto en etiquetas nuevas. Si algo hace falta cambiar ahí, el camino es hablarlo antes: aflojar un helper de pruebas es una decisión, no un descuido.