hlasuju.cz

Jednoduchá webová appka pro živé hlasování během prezentací, školení a porad. Moderátor založí hlasování bez registrace, sdílí krátký kód nebo QR kód, spouští otázky a promítá výsledky. Účastníci se připojí přes hlasuju.cz/KOD, žádný účet, žádné heslo.

Žádné WebSockets — účastnická i moderátorská stránka si stav prostě pravidelně stahují (polling každé ~2,5 s; veřejný stav má 1s CDN cache, takže stovky účastníků jedné přednášky = ~1 dotaz za sekundu do DB). Hlasování automaticky "vyprší" 30 dní po vytvoření (respektuje se při čtení, data v DB se nemažou; obrázky maže denní cron).

Jak to funguje

• Moderátor vytvoří hlasování na /vytvorit → dostane veřejný kód (např. 381742) a tajný moderátorský odkaz (/m/<token>).
• Moderátorský token je dlouhý, kryptograficky náhodný řetězec — je to jediná "autentizace" moderátora (capability URL), nikdy se neposílá do žádné veřejné/účastnické odpovědi.
• Účastník otevře hlasuju.cz/<kod> (ručně, nebo přes QR), počká na aktivovanou otázku, klikne na odpověď.
• Ochrana proti dvojímu hlasování: náhodné ID uloženo v localStorage účastníka + unikátní DB constraint (question_id, participant_id). Není to neprůstřelný volební systém, jen ochrana proti běžnému dvojímu kliknutí.
• Otázka má stavy prepared → active → ended. Moderátor ji spustí, ukončí ("vyhodnocení" — účastníci vidí odkaz, hlasovat už nejde) a pak spustí další. Ukončenou otázku jde s potvrzením znovu otevřít (hlasy zůstávají). Účastníci nikdy nevidí nespuštěné otázky; finální výsledky (/final-results) jsou veřejné až po ukončení celého hlasování.
• Editace (/m/<token>/upravit): nespuštěné otázky jde měnit, přidávat, mazat a přeřazovat i během prezentace; spuštěné otázky (nebo s hlasy) jde jen přeřadit. Ukončené hlasování je uzamčené. Souběžné úpravy ve dvou oknech chrání polls.version (starší verze se odmítne, nic se tiše nepřepíše).
• Obrázky u otázek (JPEG/PNG/WebP; GIF se převede na statický obrázek; SVG nikdy; prohlížeč zmenší na max. 4096 px, příp. 2400 px, a max. 4 MB) jsou v Universal Content API (content-api.darbujan.com), v DB je jen URL + evidence uploadů (poll_images). Prohlížeč nahrává na náš endpoint s moderátorským tokenem, server teprve pak posílá soubor do Content API — API token nikdy neodchází do prohlížeče. Nové hlasování se proto nejdřív vytvoří a editor obrázky nahraje hned potom.
• Odkaz u otázky (jen http/https) se studentům ukáže až po ukončení otázky, pokud ho moderátor výslovně nepovolí už během hlasování.
• Promítání (▶ Promítat v konzoli): celá obrazovka, ovládání klávesnicí/prezentérem — mezerník = další krok, ←/→ (PageUp/PageDown) = otázky, R = výsledky, Q = QR kód, F = celá obrazovka, Esc = zpět.

Ankety pro web (veřejné ankety a widget)

Druhý režim hlasování (polls.mode = "self_service", výchozí a všechna historická hlasování jsou "live"). Vytváří se na /pro-weby/vytvorit.

• Jedna otázka, 2–10 odpovědí, hlasuje se hned po vytvoření (otázka je od začátku active) přes stejný endpoint, identitu účastníka a ochranu jako živé hlasování. Moderátor anketu jen ukončí (spouštění/ukončování otázek API odmítne).
• Úprava jen do prvního hlasu (pak je otázka zamčená). Editace zamyká řádky odpovědí (FOR UPDATE), takže souběžný hlas buď otázku zamkne, nebo dorazí až po uložení (hlas pro smazanou odpověď skončí chybou 400).
• Výsledky (/api/polls/public/<kód>/final-results) vidí jen ten, kdo už hlasoval (nebo všichni po ukončení). Pravidlo pro správnou odpověď: během hlasování se neprozradí nikomu (ani hlasujícímu, ani v Open Graph náhledu) — zobrazí se všem až po ukončení ankety moderátorem.
• Platnost 30 dní od posledního hlasu (zápis do DB nejvýš jednou denně).
• Stránka /<kód> má vlastní Open Graph (otázka, výzva, obrázek /og/<kód>?v=<verze> 1200×630 bez výsledků a správné odpovědi) a je noindex (Facebook náhled načte i tak). Živá hlasování mají dál obecná metadata — jejich otázky jsou před spuštěním tajné.
• Widget /embed/<kód> (iframe): jediná route, kterou smí cizí web vložit (frame-ancestors *); všechny ostatní stránky mají X-Frame-Options: DENY + frame-ancestors 'none' (next.config.ts). Bez navigace, banneru a analytiky. Když prohlížeč v iframe blokuje úložiště třetích stran, widget hlasování nenabídne a odkáže na hlasuju.cz (jinak by každé načtení = nové ID = další hlas).
• Sdílení: obyčejné URL (Facebook sharer, WhatsApp, e-mail, Web Share API na mobilu, kopírování). Žádné Graph API.

Limity ochrany (záměrně jednoduchá): jeden hlas na prohlížeč (ID v localStorage) + DB unique (otázka, účastník) + nejvýš 30 hlasů za hodinu z jedné IP do jedné ankety. Kdo smaže data prohlížeče, použije anonymní okno nebo jiné zařízení/síť, může hlasovat znovu; úložiště ve widgetu je oddělené podle webu, kam je vložený. Výsledky jsou orientační, ne reprezentativní průzkum (uvedeno i v UI). Kódy jsou 6místné — kdo zkouší kódy, najde jen veřejné otázky a hlasovat může; výsledky bez hlasu neuvidí.

Ochrana proti zneužití

• Rate limiting je v Postgresu (tabulka rate_limits, fixní okna, lib/rate-limit.ts) — funguje napříč serverless instancemi, žádná další služba. Limity jsou velkorysé kvůli školám za jednou IP (600 hlasů/min z jedné IP do jednoho hlasování, 30/min na jeden prohlížeč, 10 nových hlasování / 10 min a 60 / den z IP, 60 uploadů / h na hlasování). Při výpadku vrstvy limitů se požadavek pustí (fail-open).
• Limity velikosti těla požadavků, honeypot pole ve formuláři.
• Neplatné URL hlasování vrací skutečné HTTP 404.

Lokální spuštění

npm install
cp .env.example .env.local   # doplň DATABASE_URL, viz níže
npm run db:migrate
npm run dev
# → http://localhost:3000

This is the beginning of the README. Read the rest at the original. Read the full README ↗