Konkurs fotograficzny — dokumentacja aplikacji

1. E-mail → Functions sprawdza allowlist (users). Brak → odmowa.
2. PIN losowany kryptograficznie (CSPRNG), przechowywany jako hash z solą w D1 (~10 min), PIN wychodzi mailem przez Resend.
3. Wpisany PIN → weryfikacja (hash, niewygasły, limit prób, jednorazowość) → sesja (JWT w cookie HttpOnly, ~7 dni).
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.

Ochrona przed nadużyciem (wdrożone): prośba o kod — maks. 10 kodów/h na e-mail i 30 żądań/h na IP; weryfikacja — 5 prób na kod + twardy licznik 20 nietrafień/h na e-mail (domyka brute-force). Liczniki w KV, przy awarii KV fail-open (nie blokuje logowania). Podgląd PIN na ekranie (tryb dev) tylko z localhost/LAN.

Konkurs (foto-konkurs.czwarta-b.com) i portal czwarta-b.com dzielą jedną sesję. Zalogowanie w jednej aplikacji uznaje druga; wylogowanie kończy sesję po obu stronach.

• Wspólny sekret AUTH_SECRET (ustawiony jako sekret Pages w obu projektach, ta sama wartość) — nim podpisywana i weryfikowana jest sesja. Ciasteczko sesji cbsession ustawiane z Domain=.czwarta-b.com, więc jest współdzielone między subdomenami.
• Uwierzytelnienie wspólne, autoryzacja per-aplikacja. Tożsamością jest e-mail. getUser (lib/auth.js) rozpoznaje usera po sub=id (token konkursu) albo po e-mailu (token portalu ma sub=e-mail; token konkursu niesie pole email). Konkurs wpuszcza tylko osoby z tabeli users — bycie zalogowanym w portalu nie daje wstępu do konkursu.
• Zalogowany w portalu, ale spoza konkursu: GET /api/me zwraca 401 { ssoEmail }, a front pokazuje na ekranie logowania komunikat „ten adres nie bierze udziału w konkursie — skontaktuj się z organizatorem".
• Wspólne wylogowanie: auth/logout czyści cbsession w obu wariantach (host-only i z Domain=.czwarta-b.com) oraz starą nazwę session — inaczej stare host-only ciasteczko trzymałoby zalogowanie.
• Reakcja na zmianę stanu: po powrocie do karty (focus/visibilitychange) front woła /api/me i jeśli logowanie zmieniło się po drugiej stronie — odświeża widok (bez ręcznego odświeżania).
• Zero regresji / włącznik: całe SSO aktywuje się TYLKO gdy ustawiony jest AUTH_SECRET. Bez niego aplikacja działa jak wcześniej (własne ciasteczko session, podpis JWT_SECRET). Weryfikacja akceptuje oba sekrety i obie nazwy ciasteczka, więc sesje sprzed włączenia SSO nie wypadają.
• Ograniczenie iOS (nie błąd aplikacji): na iPhonie/iPadzie każda zainstalowana PWA ma własny, odizolowany magazyn ciasteczek — oddzielny od Safari i od innych PWA. Dlatego wspólne logowanie działa między zakładkami Safari, ale nie przenosi się między dwiema osobnymi PWA (konkurs i portal jako oddzielne ikony na ekranie początkowym) — ani zalogowanie, ani wylogowanie. To ograniczenie systemu, nie kodu; cookie‑owego SSO między osobnymi PWA na iOS nie da się osiągnąć. W praktyce (iOS) w zainstalowanych aplikacjach logujemy się osobno (sesja ~7 dni). Na Androidzie zainstalowana PWA działa w tym samym profilu Chrome (WebAPK) — ciasteczka są współdzielone z przeglądarką i między PWA, więc SSO tam działa niezależnie od wersji systemu (potwierdzone empirycznie na Androidzie 9). Warunek na Androidzie: ciasteczko nie może mieć SameSite=Strict — u nas jest Lax, więc OK.

Warstwa SSO: lib/session.js (wspólne podpisywanie/weryfikacja/kasowanie ciasteczka).

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
  voter_only INTEGER NOT NULL DEFAULT 0,-- „tylko głosuje": nie wgrywa zdjęć
  ai_sessions_used INTEGER NOT NULL DEFAULT 0,  -- licznik sesji AI
  invited_at TEXT);                     -- znacznik wysłania zaproszenia

CREATE TABLE categories (id INTEGER PRIMARY KEY, name TEXT NOT NULL, description TEXT);  -- 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, filename TEXT, bytes INTEGER,
  taken_at TEXT,                        -- data wykonania z EXIF (jeśli jest)
  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 5 chipów + odpowiedź
  created_at TEXT DEFAULT (datetime('now')));

Pozostałe tabele (pełny schemat w schema.sql): favorites (ulubione per głosujący), ai_usage (tokeny Anthropic), jury_awards (3 wyróżnienia: pos, photo_id, degree, reason), login_codes (kody PIN — OTP), events (log zdarzeń, retencja 60 dni).

PIN-y w D1 (login_codes, mocna spójność); sesja jako JWT w cookie. Faza/terminy/parametry/akceptacje/limit maili — w KV.

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, oraz rankingOrderBy() z regułą remisu); 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 — pełny łańcuch (zgodny z Regulaminem §6 ust. 2): suma punktów → więcej wyższych miejsc (najpierw pierwszych, potem drugich, potem trzecich) → zdjęcie zgłoszone wcześniej (created_at) → numer zdjęcia (id).
  • Aplikacja nie pokazuje „ex aequo" — dwa ostatnie człony zawsze dają ścisłą kolejność, więc zdjęcia równe co do punktów i rozkładu miejsc dostają różne medale i różne dyplomy; rozstrzyga czas zgłoszenia.
  • created_at przed id, bo „zgłoszone wcześniej" to reguła, a nie szczegół silnika bazy (migracja może wiersze przenumerować); id domyka remis w tej samej sekundzie.
  • Ten sam porządek obowiązuje dyplomy — /api/results i /api/my-awards wołają rankingOrderBy(), żeby podium na ekranie nie rozjechało się z wydrukiem.
  • Zmiana z 2026-10-04 (1.15.0): wcześniej remis rozstrzygała liczba głosujących (votes DESC) — reguła inna niż regulaminowa, potrafiła dać odwrotny wynik.
• Podium 1-2-3 per kategoria + uznaniowe wyróżnienia komisji. Rankingu zbiorczego ponad kategoriami nie ma — nigdy go nie zaimplementowano; ekran wyników ma przyciski „Wyróżnienia" + po jednym na kategorię. Regulamin §6 ust. 1 mówi (poprawnie) tylko o podium w kategoriach.
• Progresywne odsłanianie wyników przez admina (sekcja 14).

• 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; właściciel może go pobrać („pobierz", GET /api/download/:id).
• Lekka kopia (~2048 px) — do podglądu pełnoekranowego i do API AI; miniatura (~640 px) — do siatek/kafelków. Robi je przeglądarka (canvas).
• HEIC: aplikacja dostaje i przechowuje surowy plik HEIC (oryginał zapisuje się jako .heic). Lekką kopię i miniaturę robi przeglądarka, więc musi umieć zdekodować HEIC — na urządzeniach Apple (Safari) to działa; przeglądarka bez obsługi HEIC (np. Windows) takiego pliku nie wgra (blokada z jasnym komunikatem). Dla HEIC powstaje dodatkowo pełna kopia JPEG jako podgląd zastępczy dla oglądających bez HEIC (np. jury na Windows); ocena zawsze idzie z oryginału (sekcja 17).

Kopie (lekka + miniatura, a dla HEIC także pełna kopia JPEG) robi przeglądarka (canvas), bez Cloudflare Images. Aplikacja przechowuje surowy HEIC (Apple nie zamienia go na JPEG przed wysłaniem), dlatego dekodowanie HEIC wymaga przeglądarki Apple (Safari), a oglądającym bez HEIC (np. Windows) służy pełna kopia JPEG. Miniatury starszych zdjęć dorabiają się w tle po zalogowaniu (przeglądarka właściciela).

• 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 + wyróżnienia, progresywne odsłanianie. (Z pierwotnego planu nie powstał ranking zbiorczy ani eksport/link read-only.)
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  README.md  LOG-ZDARZEN.md     # specyfikacja (źródło prawdy), opis repo, typy zdarzeń logu
  dokumenty/                           # źródła .md dokumentów ze stopki (→ public/*.html)
  PREVIEW/                             # katalog do prezentacji makiet na żywo (prototypy UX, nieserwowane)
  public/                              # frontend (vanilla JS, lekko)
  functions/api/...                    # Pages Functions (login, photos, vote, ai, results, admin)
  schema.sql                           # tabele D1 + seed
  scripts/                             # stamp-version, tag-release
  _WYDANIE.COMMAND  _WDROZENIE.COMMAND # launchery wydania (dwuklik) + _STATUS / _SERWER
  wrangler.toml  .dev.vars  .gitignore  README.md

Dokumenty tekstowe (.md) — gdzie i po co

Wszystkie pliki .md to źródła (edytujemy je, nie rendery). Trzy z nich zasilają dokumenty widoczne w stopce aplikacji; po zmianie treści źródła ręcznie przenosimy ją do odpowiadającego pliku public/*.html (nie ma konwertera md→html — polecenie „zsynchronizuj …"). Numer wersji, tabela „Rozmiary plików" i drzewo plików trafiają do obu plików automatycznie przy wydaniu.

Dokumenty ze stopki (źródło → render serwowany):

• dokumenty/przewodnik.md → public/przewodnik.html — przewodnik uczestnika (po edycji: „zsynchronizuj przewodnik").
• dokumenty/regulamin.md → public/regulamin.html — regulamin i harmonogram (po edycji: „zsynchronizuj regulamin").
• dokumenty/dokumentacja.md → public/dokumentacja.html — ta dokumentacja techniczna (po edycji: „zsynchronizuj dokumentację").
• dokumenty/README.md — opis samego katalogu źródeł (nie serwowany).

Dokumenty projektowe w katalogu głównym (nie serwowane w aplikacji):

• SPEC.md — specyfikacja i decyzje projektu (źródło prawdy).
• README.md — krótki opis repozytorium.
• LOG-ZDARZEN.md — opis typów zdarzeń zapisywanych w logu (tabela events).

Struktura style.css (sekcje)

Spis sekcji arkusza stylów — generowany automatycznie z banerów „SECTION:" w public/style.css (kolejność = kolejność w pliku; npm run cssmap, także przy wydaniu). Nie edytuj poniższej listy ręcznie.

1. Podstawy — zmienne, reset, paski przewijania, body
2. Układ i nawigacja — wrap, zakładki, nagłówek, panel, stopka
3. Modale wspólne — QR, potwierdzenie, bramka zgody
4. Diagram faz (Ustawienia)
5. Głosowanie — TOP, toast, filtry, pula miniatur
6. Wyniki — pulpit, podium, medale, lightbox wyników
7. Lightbox (podgląd zdjęć)
8. Logowanie
9. Moje zdjęcia — liczniki, pasek etapu, kategorie, lista zdjęć
10. Ustawienia (admin) — uczestnicy, tryb testowy, log zdarzeń
11. Wyróżnienia komisji — sloty, medale/stopnie
12. Aktywność AI (panel admina)
13. Kategorie (Ustawienia)
14. Modal pomocy
15. Modal „O aplikacji"
16. Modal „Zapytaj Claude" — recenzja, tytuły, loader, chipy
17. Mobile (≤560px)
18. Przełącznik (pigułka)
19. Filtr uczestników
20. Treść maili (Ustawienia) — akordeon, podgląd, wysyłka
21. Baner instalacji PWA
22. Dyplomy i odznaka zakładki

Wydanie i wdrożenie — dwa skrypty (model jak w Rambulo)

Zamiast osobnych skryptów COMMIT / RELEASE / DEPLOY / PUSH są dwa launchery .command (dwuklik w Finderze):

• _WYDANIE.COMMAND — przygotowanie wydania: zapisuje wszystkie zmiany jako jedno „wydanie". Po kolei: bramka „brak zmian" → wybór typu [1] patch / [2] minor → opis → podbicie wersji + npm run stamp (+ wpis wersji do SPEC.md i tej dokumentacji) → commit chore(release): WERSJA - opis. Na końcu pyta „Wdrożyć teraz?" i po zgodzie sam uruchamia wdrożenie (całość jednym przebiegiem).
• _WDROZENIE.COMMAND — publikacja na produkcję: npm run deploy (stempel + wrangler pages deploy + tag git-WERSJA) → kontrola /api/health (porównanie wersji) → push commitów i tagów na GitHub. Uruchomione z _WYDANIE (flaga --potwierdzono) nie pyta ponownie i dziedziczy okno.

Bramką „nie wdrażaj tej samej wersji dwa razy" jest tag git-WERSJA (tworzony w postdeploy) — przy powtórnym wdrożeniu tej samej wersji predeploy przerywa i odsyła do _WYDANIE. W odróżnieniu od Rambulo nie ma tu maszyny stanów .deploy-state, testów E2E, mirrora GitLab ani purge Cloudflare — konkurs wdraża bezpośrednio przez wrangler. Pomocniczo: _STATUS.COMMAND (podgląd stanu) i _SERWER.COMMAND (serwer lokalny).

Testy i piaskownica testowa (E2E na życzenie)

npm test — testy jednostkowe, bez sieci i bazy (szybkie, wpięte w wydanie): scripts/filesizes.test.mjs + scripts/imgver.test.mjs (token wersji obrazka imgVer — sedno ochrony przed pokazaniem starego zdjęcia po odzyskaniu numeru).

Cięższy scenariusz end‑to‑end (obrazy, głosowanie, wyniki, dyplomy, panel admina) uruchamiamy na życzenie w izolowanej piaskownicy — świadomie poza npm test i poza wydaniem, bo zasiewa i mutuje dane. Nigdy nie ruszamy żywego serwera dev ani danych produkcyjnych.

1. Osobny worktree (własna kopia, nie pod żywym serwerem): git worktree add -b test-sandbox ../konkurs-foto-sandbox.
2. Zależności: npm --prefix ../konkurs-foto-sandbox install.
3. .dev.vars w piaskownicy: JWT_SECRET, DEV=1, MAIL_PROVIDER/MAIL_FROM/MAIL_DAILY_CAP oraz AUTH_SECRET — bez niego serwer używa ciasteczka session, które na localhost bywa przesłaniane przez stare cbsession z innych lokalnych aplikacji (ciasteczka ignorują port) i logowanie w przeglądarce nie działa.
4. Baza (własny persist): wrangler d1 execute konkurs --local --persist-to ../konkurs-foto-sandbox/.wrangler/state --file schema.sql, potem wstaw usera i kategorię.
5. Serwer na INNYM porcie: npm --prefix ../konkurs-foto-sandbox run dev -- --port 8790 --persist-to ../konkurs-foto-sandbox/.wrangler/state.
6. Logowanie: w DEV PIN pokazuje się na ekranie (auto‑wpisany). Dane demonstracyjne: tryb testowy (POST /api/admin/test-mode {on:true}, rola owner) → 10 osób × 3 zdjęcia SVG; etap: POST /api/admin/phase {phase:"upload|voting|results"}.
7. Co przejść: wstaw/usuń/podgląd po odzyskaniu numeru (miniatura + lightbox pokazują bieżące zdjęcie), dodanie do TOP3, dodanie do wyróżnień, karty wyników, dyplom (/dyplom.html?photo=ID).

Pułapki: konto @test.test blokuje seed (testDataExists uznaje je za dane testowe — na czas seedu zmień e‑mail konta na nietestowy; sesja działa po numerze konta, nie po e‑mailu) · sprzątanie: POST /api/admin/test-mode {on:false} lub DELETE (purge) · obrazy loading="lazy" poza ekranem mają chwilowo naturalWidth=0 — to nie błąd. Po testach: zatrzymaj serwer i git worktree remove --force ../konkurs-foto-sandbox.

_konkurs-foto/
  public/                         # frontend (serwowany)
    _headers
    app.js
    dokumentacja.html
    dyplom.html
    icon_180.png
    icon_192.png
    icon_512.png
    index.html
    manifest.webmanifest
    portal-4b.svg
    przewodnik.html
    regulamin.html
    style.css
    sw.js
    trophy_192.png
    trophy_512.png
    js/                           # moduły ES
      about.js
      accordion.js
      ai.js
      auth.js
      confirm.js
      consent.js
      diag.js
      dom-anim.js
      dom.js
      help.js
      infobar.js
      inspect.js
      install-banner.js
      lightbox.js
      phone.js
      photo-image.js
      photos-view.js
      photos.js
      reason-limit.js
      results.js
      session.js
      settings-comm.js
      settings-dyplomy.js
      settings-events.js
      settings-forms.js
      settings-handlers.js
      settings-help.js
      settings-jury.js
      settings-protokol.js
      settings-views.js
      settings.js
      tabs.js
      toast.js
      update.js
      version.js
      voting-view.js
      voting.js
    vendor/                       # biblioteki PDF + fonts/ (kroje dyplomu)
      html2canvas-1.4.1.min.js
      jspdf-2.5.2.umd.min.js
  functions/
    api/                          # Pages Functions (endpointy)
      accept-regulamin.js
      admin/categories.js
      admin/categories/[id].js
      admin/check-delivery.js
      admin/deadlines.js
      admin/derivatives.js
      admin/dyplom-text.js
      admin/dyplomy.js
      admin/events.js
      admin/hashes.js
      admin/jury-favorites.js
      admin/jury-oglos.js
      admin/jury.js
      admin/maintenance-summary.js
      admin/notify.js
      admin/orphans.js
      admin/overview.js
      admin/params.js
      admin/phase.js
      admin/photos.js
      admin/protokol.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
      diag-mode.js
      diag.js
      download/[id].js
      dyplom-text.js
      full/[id].js
      health.js
      img/[id].js
      me.js
      my-awards.js
      photos.js
      photos/[id].js
      photos/upload.js
      results.js
      thumbs/[id].js
      thumbs/missing.js
      vote.js
      vote/[category].js
    lib/                          # wspólna logika
      ai.js
      auth.js
      diag.js
      dyplom-text.js
      email.js
      events.js
      exif.js
      imgver.js
      jwt.js
      keys.js
      notify.js
      params.js
      phase.js
      ratelimit.js
      regulamin.js
      scoring.js
      session.js
      testmode.js
      version.js
      wyroznienia.js
  schema.sql  wrangler.toml  package.json  scripts/  dokumenty/

Razem: JS — 104 plików, 13831 linii, ~693 KB · CSS — 1 plik, 1347 linii, ~99 KB.

wyróżnione = pliki ponad 400 linii (kandydaci do podziału).

Sekcja Ustawienia → Konserwacja, widoczna wyłącznie dla właściciela (owner). Służy do wykrywania i naprawy rozjazdów między bazą (rekordy zdjęć w D1) a magazynem (pliki w R2). Zawiera trzy narzędzia oraz proaktywny znacznik.

Przypomnienie o plikach zdjęcia. Każde zdjęcie ma oryginał (nietknięte archiwum pracy) oraz pliki pochodne liczone z niego: lekką kopię (~2048 px), miniaturę (~640 px) i — tylko dla HEIC — pełną kopię JPEG. Pełna kopia to podgląd zastępczy: ocena zawsze idzie z oryginału, a kopia wchodzi jedynie wtedy, gdy przeglądarka nie pokaże oryginału HEIC (np. Windows). Klucze wszystkich pochodnych liczy jedno źródło prawdy (functions/lib/keys.js) — używane wszędzie (upload, serwowanie, kasowanie, konserwacja), żeby ten sam plik zawsze miał ten sam klucz.

Osierocone zdjęcia (pliki bez zdjęcia)

Pliki, które zostały w magazynie po usuniętych zdjęciach (nie wskazuje ich żaden rekord).

• Jednym przejściem po magazynie zbiera sieroty i grupuje je po typie (oryginały / lekkie kopie / miniatury / pełne kopie) z liczbą, rozmiarem i zakresem dat — do kontroli przed skasowaniem.
• Zaznaczasz typy i klikasz „Usuń zaznaczone" (z potwierdzeniem; kasowanie z ponowieniami). Gdy sierot nie ma — przycisku w ogóle nie ma.
• Całość przez POST (/api/admin/orphans, kasowanie ?potwierdz=USUN) — świadomie żadnego linku GET, żeby obcy adres nie odpalił kasowania Twoim ciasteczkiem.

Braki zdjęć pochodnych (zdjęcie bez pliku)

Odwrotność sierot: rekord zdjęcia jest, ale brakuje mu pliku — cichy, częściowy upload (na ekranie wygląda dobrze). Dla każdego zdjęcia sprawdzane są: oryginał, lekka kopia, miniatura oraz — dla HEIC — pełna kopia.

• Po otwarciu podsekcji od razu pojawia się lista zdjęć z brakami (numer, plik, czego brakuje) i jeden przycisk „Odbuduj" pod listą.
• Odbudowa dzieje się w przeglądarce (serwer nie przerabia obrazów): brakujący plik jest liczony z oryginału i odsyłany do zapisu. Naprawione pozycje znikają z listy na bieżąco, bez migotania.
• Brak oryginału = „nie do odbudowania" — pochodne robi się z oryginału, więc bez niego nie ma z czego niczego odtworzyć (jedyne wyjście: ponowne wgranie zdjęcia).
• HEIC: pełną i lekką kopię HEIC odtworzy tylko przeglądarka, która dekoduje HEIC (urządzenie Apple/Safari); gdzie indziej narzędzie mówi to wprost. Miniatura powstaje z lekkiej kopii, więc jej odbudowa działa wszędzie.
• Endpoint: POST /api/admin/derivatives (sam podgląd, nic nie zmienia); zapis odbudowanych plików przez POST /api/thumbs/:id, POST /api/full/:id, POST /api/img/:id.

Brakujące sygnatury (zdjęcie bez odcisku treści)

Każde zdjęcie ma sygnaturę — skrót treści oryginału (SHA-256), dzięki któremu to samo zdjęcie bierze udział w Konkursie tylko raz (także w innym rozmiarze czy formacie pliku — patrz Regulamin §3). Nowe zgłoszenia dostają sygnaturę od razu przy wysyłce; to narzędzie dolicza ją zdjęciom sprzed wprowadzenia blokady (mają sygnaturę pustą).

• Po otwarciu podsekcji od razu pojawia się podsumowanie (ile zdjęć sprawdzono, w tym HEIC) i lista zdjęć bez sygnatury (numer, plik, data zgłoszenia), a pod listą przycisk „Wstaw sygnatury".
• Wstawianie idzie partiami (serwer czyta oryginały z magazynu i liczy skrót), aż policzy wszystkie.
• Duplikat: zdjęcie, którego identyczna kopia jest już zgłoszona, zostaje bez sygnatury — to nierozstrzygnięty duplikat sprzed blokady; narzędzie mówi to wprost, a którą kopię zostawić, decyduje Administrator (usunięcie ręczne, „kto pierwszy, ten lepszy").
• Endpoint: POST /api/admin/hashes (podgląd { probe } — sam odczyt; wstawianie partiami po kursorze). Podstawa w bazie: kolumna content_hash z globalnym unikalnym indeksem, który twardo blokuje powtórki także przy wgrywaniu.

Znacznik „jest coś do zrobienia"

Przy każdym wejściu w Ustawienia (dla ownera) jedno szybkie sprawdzenie liczy naraz sieroty, braki pochodnych i brakujące sygnatury. Gdy jest robota, zapala się czerwona kropka:

• na belce „Konserwacja" — gdy jest cokolwiek do zrobienia,
• na konkretnej podsekcji — celnie tam, gdzie faktycznie coś jest (osobno sieroty, osobno braki pochodnych, osobno brakujące sygnatury).

Sprawdzenie jest ciche i nieblokujące (widok pojawia się od razu, kropka dochodzi po odpowiedzi). Endpoint: POST /api/admin/maintenance-summary — tylko odczyt, jedno przejście po magazynie, zwraca liczbę sierot, braków pochodnych i brakujących sygnatur oraz todo.

Ograniczenie z natury rzeczy: odbudowa jest po stronie przeglądarki, więc pełne/lekkie kopie HEIC naprawisz tylko na urządzeniu Apple. Oryginał to chronione archiwum — jego utrata jest nieodwracalna (dlatego Konserwacja nigdy sama nie kasuje oryginałów zdjęć, a jedynie osierocone pliki wskazane przez Ciebie).