Hrnčiarka — referenčný projekt PK01

Jednostránkový web pre fiktívny hrnčiarsky ateliér v Bratislave. Postavený ako prvý PK01 referenčný end-to-end projekt — zámerne preverenie cesty brief → scaffold → preview deploy skôr, než príde reálny zákazník. Sleduje sa pod issue PK-4.

Fiktívny brief: „Sme malý hrnčiarsky ateliér. Chceme jednostránkový web, kde si návštevník pozrie rozvrh hodín, vyberie si jednu a rezervuje si miesto. Platba v hotovosti pri príchode — stačí, ak nám meno a e-mail prídu do schránky. Pokojný, teplý vzhľad. Ship it today."

Stack a konvencie

• Next.js 16 (App Router, output: "standalone") · React 19 · TypeScript strict
• Tailwind v4 (@theme tokeny) · Fraunces + Inter (variabilné, latin-ext)
• npm (per skeleton forge-admin/_skeleton-nextjs)
• Docker + bot/preview-start.sh (entry point pre kokpit-bot orchestrátor)
• Spĺňa všetkých 7 pravidiel z forge-admin/kokpit/docs/processes/app-conventions.md:
  • GET /health → {"status":"ok"}
  • GET /version → { version, commit, builtAt }
  • port z env PORT (preview pridelený: 5111, rozsah 5100–5199)
  • restart: unless-stopped v compose
  • logy iba do stdout/stderr
  • .env.example + reálne hodnoty mimo gitu
  • owner v forge-admin/kokpit/apps.json (doplniť pri zaradení do registra)

Čo je naozaj a čo placeholder

Vrstva	Dnes	Čo by skutočný zákazník nahradil
Rozvrh hodín	Hardkódovaný v src/data/classes.ts (5 hodín)	CMS feed (Sanity/Contentful) alebo classes tabuľka v Postgres
Rezervačný formulár	Reálna Server Action v src/app/actions.ts, validuje meno/e-mail/hodinu	Rovnaká akcia; mení sa iba sink
Submission sink	Console + JSONL append do BOOKING_LOG_PATH (default /tmp/...)	Reálny e-mail provider — formálne rozhodnutie sa robí v rámci kokpit-stack-u (vlastné SMTP / Postmark / Resend); kým neexistuje, ostáva JSONL
Identita ateliéru	Fiktívna („Hrnčiarka", Dunajská 3, ahoj@hrnciarka.example)	Skutočné meno/adresa/kontakt v layout.tsx metadata + footer
Auth	Žiadny	Out of scope per brief — pridáme až keď ateliér chce členský portál
Databáza	Žiadna	Pridáme keď chceme aby rezervácie prežili redeploy alebo riešili kapacitu

Akcia je plne zapojená — výmena za reálny mail provider je zmena jedného súboru (src/lib/booking-log.ts).

Dizajnové rozhodnutia (pokojný, teplý vzhľad)

• Paleta. Krémová #FAF6EE stránka, teplý hrnčiarsky odtieň #C97B5A ako akcent, terakota #9C5638 na zdôraznenie, mocha #3F2E25 text, jemná šalvia v halóne. Tokeny žijú v globals.css v @theme bloku a sú adresovateľné cez Tailwind utility (bg-cream, text-mocha, bg-clay…).
• Typografia. Fraunces (variabilný, SOFT axis) na nadpisy — mäkké serify, ktoré pôsobia ručne tvarované, nie korporátne. Inter na bežný text. Oba s latin-ext (kvôli diakritike).
• Tvar. rounded-2xl karty, full-pill tlačidlá, štedrý whitespace, dva mäkké rozmazané glow-y za stránkou — povrch pôsobí osvetlene, nie ploché.
• Hlas. Slovenčina, jednoduché vety, žiadne marketingové superlatívy. Brief povedal „pokojný a teplý" a to viedlo každú voľbu textu.

Lokálny dev

npm install
npm run dev      # http://localhost:3000
npm run build    # type-check + production build
npm run smoke    # tsx scripts/smoke-booking.mts — exercises the booking action
npm run lint     # ESLint

Smoke skript píše do /tmp/pottery-studio-bookings.smoke.log, takže neznečisťuje hlavný log.

Override log path:

BOOKING_LOG_PATH=/var/log/pottery-bookings.log npm run start

Preview / produkcia

bot/preview-start.sh je entry point pre kokpit-bot orchestrátor:

PORT=3000 ./bot/preview-start.sh

Skript: načíta .env, exportne GIT_COMMIT+BUILT_AT (pre /version), npm ci ak chýbajú deps, npm run build ak chýba .next/, npm run start.

Manuálne spustenie cez Docker (host-side):

docker compose build --build-arg GIT_COMMIT=$(git rev-parse --short HEAD) \
                     --build-arg BUILT_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
docker compose up -d
curl -s http://127.0.0.1:5111/health

Caddy reverse proxy (host-managed, nepatrí do tohto repa):

pottery-studio.sitecraft.sk {
    reverse_proxy 127.0.0.1:5111
}

Repo layout

src/
  app/
    layout.tsx        — fonts (Fraunces + Inter), metadata, lang="sk"
    page.tsx          — hero / klassen list / booking section / footer
    actions.ts        — `bookClass` Server Action
    globals.css       — @theme paleta + base
    health/route.ts   — GET /health
    version/route.ts  — GET /version (verzia, commit, builtAt)
  components/
    BookingForm.tsx   — Client Component, useActionState
  data/
    classes.ts        — hardkódovaný rozvrh + Intl.DateTimeFormat (sk-SK / Europe/Bratislava)
  lib/
    booking-log.ts    — recordBooking() — console + JSONL append
scripts/
  smoke-booking.mts   — direct unit test booking akcie
bot/
  preview-start.sh    — kokpit-bot preview/prod entry point
Dockerfile            — multi-stage standalone build
docker-compose.yml    — host-side preview deploy