Konkurs fotograficzny — dokumentacja aplikacji

1. E-mail → Functions sprawdza allowlist (users). Brak → odmowa.
2. Losowany PIN, hash do KV z TTL (~10 min), PIN wychodzi mailem przez Resend.
3. Wpisany PIN → weryfikacja (hash, niewygasły, limit prób, jednorazowość) → sesja (JWT w cookie).
4. Sesja 7 dni → PIN mniej więcej raz w tygodniu (skrócone, bo cichych wejść nie logujemy).

PIN ponownie tylko gdy: sesja wygaśnie, wylogowanie, czyszczenie ciasteczek, nowe urządzenie. WhatsApp jako kanał — odrzucony.

CREATE TABLE users (
  id INTEGER PRIMARY KEY, name TEXT NOT NULL,
  email TEXT NOT NULL UNIQUE,
  gender TEXT,                          -- poprawna odmiana / zwroty AI
  is_admin INTEGER NOT NULL DEFAULT 0,
  is_owner INTEGER NOT NULL DEFAULT 0,  -- chroniony superadmin
  active   INTEGER NOT NULL DEFAULT 1,  -- dezaktywacja zamiast usuwania
  ai_sessions_used INTEGER NOT NULL DEFAULT 0);  -- licznik sesji AI

CREATE TABLE categories (id INTEGER PRIMARY KEY, name TEXT NOT NULL);  -- definiuje owner (obecnie 4)

CREATE TABLE photos (
  id INTEGER PRIMARY KEY,
  owner_id    INTEGER NOT NULL REFERENCES users(id),
  category_id INTEGER NOT NULL REFERENCES categories(id),
  r2_key_original TEXT NOT NULL,        -- oryginał (nietknięty)
  r2_key_display  TEXT,                 -- lekka kopia do siatki / AI (~1500 px)
  title TEXT,
  created_at TEXT DEFAULT (datetime('now')));

CREATE TABLE votes (
  voter_id    INTEGER NOT NULL REFERENCES users(id),
  category_id INTEGER NOT NULL REFERENCES categories(id),
  photo_id    INTEGER NOT NULL REFERENCES photos(id),
  rank   INTEGER NOT NULL,              -- 1..3
  points INTEGER NOT NULL,              -- 5-3-1
  PRIMARY KEY (voter_id, category_id, rank),
  UNIQUE (voter_id, category_id, photo_id));

CREATE TABLE ai_reviews (               -- cache „Zapytaj Claude" — per zdjęcie
  photo_id INTEGER PRIMARY KEY REFERENCES photos(id),
  review_text TEXT NOT NULL,
  titles_json TEXT,                     -- 3 tytuły + wskazany najlepszy
  followups_json TEXT,                  -- pytanie z 3 chipów + odpowiedź
  created_at TEXT DEFAULT (datetime('now')));

PIN-y w KV z TTL; sesja jako JWT w cookie.

Fazy upload → voting → results sterowane flagą w KV.

• TOP3 → 5-3-1 (jedno źródło: functions/lib/scoring.js, POINTS=[5,3,1], liczba miejsc = POINTS.length); wynik zdjęcia = suma punktów od wszystkich.
• Ranking pełny — zawsze 3 miejsca (dopasowany, gdy w kategorii <3 cudzych zdjęć).
• Głosowanie dobrowolne — nie trzeba głosować w każdej kategorii.
• Remisy: wygrywa zdjęcie z większą liczbą wyższych miejsc (więcej „1.", potem „2."…); przy identycznym rozkładzie ex aequo.
• Podium 1-2-3 per kategoria + ranking zbiorczy + uznaniowe wyróżnienia komisji.
• Progresywne odsłanianie wyników przez admina (do zaprojektowania). Eksport / link read-only.

• 2 punkty przełamania układu: PC / tablet / telefon.
• Siatka zdjęć (3 w kategorii): PC — 3 w wierszu, tablet — 2, telefon — 1.
• Gęstość siatki (większe/mniejsze kafelki) sterowana przez oglądającego.
• Lightbox — podgląd pełnego zdjęcia w galerii i przy głosowaniu.

W kategorii może być 20+ (nawet ~100) zdjęć → przeciąganie z dużej puli jest niepraktyczne. Dlatego:

• Sekcja TOP3: 3 numerowane miejsca, przy każdym widoczne punkty (1→5, 2→3, 3→1).
• Pula poniżej: pozostałe miniaturki w losowej kolejności.
• Wybór z puli = tap/klik („dodaj do TOP3" → kolejne wolne miejsce) — na PC, tablecie i telefonie. Wybrane zdjęcie dostaje plakietkę z numerem.
• Drag & drop tylko wewnątrz TOP3 — zmiana kolejności miejsc bez przerzucania do puli. Przeciągnięcie z TOP3 do puli zwalnia miejsce.
• Ulubione / krótka lista: najpierw serduszkowanie kandydatów, potem układanie TOP3 z krótkiej listy.
• Ponowne wejście: TOP3 bez zmian, pula znów losowa. Liczba miejsc dopasowana, gdy <3 kandydatów.
• Głosujący widzi tylko cudze zdjęcia (swoje w osobnej zakładce). Możliwa modyfikacja głosów.

• Oryginał zostaje w R2 bez zmian (pełna jakość; lightbox, ewentualne pobranie).
• Lekkie kopie generowane obok oryginału — do siatki galerii i do API AI (~1500 px). Nie nadpisują oryginału.
• HEIC: część przeglądarek go nie wyświetla → generujemy wersję wyświetlaną (JPG/WEBP); oryginalny HEIC zostaje.

• Wskaźniki postępu: „wgrałeś X/12", „zagłosowałeś w k/4 kategorii".
• Anonimowość autorów w trakcie głosowania (odsłaniani w wynikach) — jako dobry standard (częściowo „teoretyczny").
• Maile potwierdzające + przypomnienia (admin ponagla spóźnialskich).
• „Moje zgłoszenia / Moje głosy" — podgląd i edycja/usuwanie własnych zdjęć w fazie upload.

1. Fundament / scaffold — katalog + git (osobne, prywatne repo), Cloudflare Pages, wrangler.toml (D1/R2/KV), sekrety (Resend, Anthropic), schema.sql + seed, flaga fazy, domena.
2. UX / prototyp — klikalna makieta HTML w PREVIEW (logowanie, upload, „Zapytaj Claude", głosowanie TOP3, wyniki, panel admina). Zatwierdzenie przed kodem.
3. Autentykacja — OTP PIN (Resend), allowlist, długa sesja (JWT), anty-brute-force.
4. Ładowanie zdjęć — upload R2 (oryginał + kopia), HEIC→wyświetlana, lightbox, limit 3/kategorię, „Moje zgłoszenia", postęp.
5. „Zapytaj Claude" — Opus 4.8 streaming, budżet sesji + licznik, cache per zdjęcie, kopiuj/udostępnij.
6. Ocena — galeria per kategoria (bez własnych, anonimowo, losowa), ulubione → TOP3 (tap + drag), modyfikacja głosów.
7. Komunikacja — maile potwierdzające + przypomnienia (admin).
8. Panel admina — uczestnicy, kategorie, postęp (bez cudzych ocen), usuwanie zdjęć, etapy, wyróżnienia komisji, odsłanianie.
9. Wyniki — podium per kategoria + zbiorczo + wyróżnienia, progresywne odsłanianie, eksport/link.
10. Testy + wdrożenie — smoke (logowanie, upload, AI, głos, wynik), deploy, seed realnych osób, próbny przebieg.

Osobno od Rambulo — celowo. Rambulo = Vite + Express + SQLite na Railway. Konkurs = serverless w całości na Cloudflare, lekka technologia.

• Katalog: /Users/tomaszkossut/konkurs-foto/ (SPEC + PREVIEW + kod).
• Git: osobne, prywatne repo. Nie mieszać z Rambulo.
• Deploy: Cloudflare Pages podpięte do repo GitHub (auto-deploy) albo wrangler pages deploy.
• Narzędzia: wrangler CLI. Sekrety: .dev.vars lokalnie, wrangler secret na produkcji.

konkurs-foto/
  SPEC.md  PREVIEW/                     # dokumentacja + makiety
  public/                              # frontend (vanilla JS, lekko)
  functions/api/...                    # Pages Functions (login, photos, vote, ai, results, admin)
  schema.sql                           # tabele D1 + seed
  wrangler.toml  .dev.vars  .gitignore  README.md

konkurs-foto/
  public/                         # frontend (serwowany)
    app.js
    dla-komisji.html
    dyplom.html
    index.html
    konkurs-foto.html
    manifest.webmanifest
    przewodnik.html
    regulamin.html
    style.css
    sw.js
    js/                           # moduły ES
      about.js
      accordion.js
      ai.js
      auth.js
      confirm.js
      consent.js
      dom.js
      help.js
      infobar.js
      lightbox.js
      phone.js
      photos.js
      results.js
      session.js
      settings-events.js
      settings-handlers.js
      settings-jury.js
      settings-views.js
      settings.js
      tabs.js
      toast.js
      version.js
      voting.js
  functions/
    api/                          # Pages Functions (endpointy)
      accept-regulamin.js
      admin/categories.js
      admin/categories/[id].js
      admin/deadlines.js
      admin/events.js
      admin/jury-favorites.js
      admin/jury.js
      admin/notify.js
      admin/overview.js
      admin/params.js
      admin/phase.js
      admin/photos.js
      admin/test-mode.js
      admin/users.js
      admin/users/[id].js
      ai/[id].js
      auth/logout.js
      auth/request-pin.js
      auth/verify-pin.js
      health.js
      img/[id].js
      jury/img/[pos].js
      me.js
      my-awards.js
      photos.js
      photos/[id].js
      photos/upload.js
      results.js
      vote.js
      vote/[category].js
    lib/                          # wspólna logika
      ai.js
      auth.js
      email.js
      events.js
      jwt.js
      notify.js
      params.js
      phase.js
      regulamin.js
      scoring.js
      testmode.js
      version.js
  schema.sql  wrangler.toml  package.json  scripts/  PREVIEW/

Razem: JS — 67 plików, 6609 linii, ~274 KB · CSS — 1 plik, 742 linii, ~49 KB.