Dev onboarding

Aktualizováno: 2025-12-09T18:28:33.300Z

Cíl: rychlý start pro vývojáře včetně lokálního běhu, testů a synchronizace. Detaily k PR a workflow viz `.github/CONTRIBUTING.md` (neopakujeme se).

- TypeScript striktní, Zod validace vstupů, důsledný error handling a logging.
- DRY a čistá architektura: sdílené konstanty/utilities/hooks; žádné kopírování kódu ani instrukcí.
- Testovatelnost a výkon: přidej testy před refaktorem; hlídej 80 % statements coverage gate.
- Design/UX: drž se podkladů v `doc/design`; komponenty stavěj na stávajícím UI (Tailwind, Zustand, Headless UI).
- Design implementation: HTML šablony `doc/design/template/`, CSS `doc/design/storage/css/style.css`.
  - Auth: `.page.imageleft` (obrázek vlevo, obsah vpravo, bez patičky).
  - Dashboard/Profil: `.page.full`.
  - Chat: `.page.leftright`.
  - Testovací místnost: `/about?test=1` (rychlé UI ověření bez backendu).
- Funkční zadání: ověřuj chování podle `docs/REQUIREMENTS.md` (shrnutí `doc/lestchat.md`).

1) Prerequisites
- Node.js 20.
- Nainstaluj závislosti: `npm ci`.
- Environment: `.env.local` s `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`, případně `LOCAL_DATABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, `LOG_LEVEL` (all|light|mini|off). `ALLOW_IN_MEMORY_FALLBACK=1` lze ponechat pro demo/offline běh bez Supabase; `LOCAL_FILE_STORE=1` + `LOCAL_FILE_STORE_PATH` umožní file-store místo paměti. `ADMIN_API_TOKEN` chrání `/api/admin/logs`. `NEXT_PUBLIC_SUPABASE_*` + `SUPABASE_SERVICE_ROLE_KEY` jsou nutné pro login/registraci. Secrets patří do GitHub Secrets, ne do repa. Veřejné Supabase klíče se při startu injectují do `window.__SUPABASE_CONFIG__`, takže fungují i když byl build vytvořen bez nich (po změně proměnných vždy rebuildni).

2) Lokální databáze (doporučeno)
- Spusť Postgres (např. Docker) a nastav `LOCAL_DATABASE_URL=postgres://dev:pass@localhost:5432/letschat`.
- Inicializuj schéma: `npm run db:local:init` (použije `src/db/localSQLcreate.sql`, vytvoří i `logs`).

3) Spuštění aplikace
- Dev server: `npm run dev` (Next.js App Router, port 3000).
- Nové stránky: `/rooms/create` (formulář pro založení místnosti) a `/transfer` (převod anonymního kódu). Dashboard nyní naviguje na tyto samostatné stránky místo inline formulářů a po založení místnosti proběhne přesměrování do `/room/{id}?code={CODE} `.
- Backend i frontend běží v jednom procesu; Supabase klient respektuje lokální/vzdálené URL dle env. Datový přístup je centralizovaný v `lib/persistence` (lokální DB preferovaná); Supabase slouží pro auth/sync/log fallback (viz `docs/ARCHITECTURE.md`).
- Offline zprávy: klient ukládá zprávy do IndexedDB (`lib/offlineStore`) při výpadku sítě a po návratu online se fronta odešle přes `/api/sync/push` (z `lib/messages.syncPendingMessages`).
- Auth routy: jediný `/login` a `/register` v `src/app/(auth)/*`; statické HTML v `doc/design/template` jsou jen reference.

4) Testy a kvalita
- Jednorázově: `npm test` (Vitest, reporter dot).
- Coverage: `npm test -- --coverage` (CI očekává ≥80 % statements).
- Lint: `npm run lint` (ignoruj vendor skripty v `doc/design/vendor/**` - nejsou součástí runtime). Build: `npm run build`.

5) Sync do Supabase
- Lokálně pracuj nad Postgres; do Supabase pushni až ověřené změny: `npm run sync:push` (vyžaduje `SUPABASE_SERVICE_ROLE_KEY`, upsertuje rooms/codes/room_messages pomocí service role).
- Volitelně pull ze Supabase zpět do lokální DB: `npm run sync:pull` (service role + LOCAL_DATABASE_URL) pro dotažení nových zpráv/kódů z cloudu.

6) Kde hledat kontext
- Data model: `docs/DATAMODEL.md`, SQL ve `src/db/*`.
- Funkční zadání: `docs/REQUIREMENTS.md` (shrnutí `doc/lestchat.md`).
- Architektura a workflow: `.github/CONTRIBUTING.md`, `docs/ARCHITECTURE.md`.
- Designové podklady: `doc/design/`.

Poznámka: před většími UI/arch změnami otevři issue/PR draft s návrhem a odkazy na design/datamodel.