Quickstart — validar la 001 de punta a punta

Guía runnable (sin código de implementación; este se genera en /speckit.tasks + /speckit.implement). Referencias: contracts/agenda-api.md, contracts/ui-agenda.md, data-model.md.

Requisitos

Node 22, npm 11, Docker + Compose, Playwright browsers. Puertos 3000 (app) y 5432 (postgres:16).

Arranque

cd tema5/citaclara
cp .env.example .env            # DATABASE_URL=postgresql://citaclara:citaclara@localhost:5432/citaclara TZ=Europe/Madrid
docker compose up -d db         # postgres:16
npm install
npx prisma migrate dev          # crea exclusión RN1 + índices
npm run seed                    # Eleva seedVersion=1 (3 profs, 4 servs, ~40 pacs, 8+2 semanas)
npm run dev                     # http://localhost:3000 (es-ES)

Regeneración determinista (SC-005): npm run seed && npm run seed:verificar debe dar mismo conteo y repartos (~82/10/8 ±2).

Validación por historia (trazable a spec)

ID	Escenario	Comando / pasos	Esperado
US1/SC-001	Agenda María día con citas; Jorge día vacío	Abrir `/agenda` en 1440px y 390px	Tramos ocupados + resto libre distinguibles <10 s; `La jornada está libre` en vacío
US2/RN1	Alta válida 10:00 30′; solape 10:15; contigua 10:30	`POST /api/citas` ×3 o formulario	`201` + `fin=10:30`; `409 Ese tramo ya está ocupado`; contigua `201`
US2/conc	Doble `POST` mismo hueco en `Promise.all`	`npm test -- antisolape`	Máximo 1 `201`, otra `409`; cero solapes vigentes (SC-002)
US2/RN2	`inicio` en pasado	`POST /api/citas` pasada	`422 No se pueden crear citas en el pasado` (SC-003)
US3	`reservada→completada/cancelada/no_asistida`; ilegal desde final	`PATCH /api/citas/[id]/estado`	`200` final; ilegal `409`; `cancelada` libera hueco
US4	Clave ok/ko; semilla	`/acceso` + `GET /api/semilla`	Entra / `401 Clave incorrecta`; `version:1` idéntico tras reset
Exactitud	`40,00 €`, `29/09/2026, 10:00–10:45`	Inspección UI + `npm test -- formato`	Coma decimal, `€` pospuesto, día/mes/año+hora

Suites

npm test                    # Vitest unit+integración (incl. concurrente) — todo verde para merge
npm run test:e2e             # Playwright 1440px + 390px
npm run comprobar:es         # grep: ningún string visible fuera de es-ES

Puerta de merge (constitución): suite verde + antisolape verde + textos es-ES + revisión de simplicidad (sin tablas/endpoints fuera de data-model.md/contracts/).