docs/DEV-ONBOARDING.md

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.