Požadavky (REQUIREMENTS.md)

Tento dokument obsahuje funkční a nefunkční požadavky na aplikaci Kosmo.

[!IMPORTANT] MVP scope: Pouze ZŠ (1.-7. třída). MŠ bude řešena v pozdější fázi — jiný workflow, jiné kompetence, jiný denní souhrn.

Funkční požadavky

1. Komunikace s Rodiči (Sofie) — PRIORITA Č. 1

• Cíl: "Odbavit" rodiče okamžitě (24/7), nezatěžovat učitele rutinou.
• Detailní popis viz SOFIE.md.
• Koncept:
  • Rodič komunikuje s chatbotem "Sofie".
  • Sofie má kontext: zná rozvrh, jídelníček, akce, manuály.
  • Triage (Třídění):
    1. Okamžitá odpověď: "Co má mít na školu v přírodě?" → Sofie pošle seznam (RAG).
    2. Akce: "Omlouvám Aničku." → Sofie zapíše do DB a notifikuje učitele.
    3. Eskalace: "Máme problém..." → Sofie vytvoří Ticket a předá ho řediteli/učiteli.
  • Hlasový vstup (Voice Mode):
    • Rodič může zprávu rovnou namluvit (na mobilu podrží tlačítko).
    • "Sofie, omluv Aničku na zítra, má kašel." → AI zpracuje audio přímo.
• Funkce:
  • Automatické pravidelné zprávy: Co se děti učily (generováno z Evidence, zobrazeno ve Feedu).
  • Kalendář a Připomínky: Automatické notifikace.

2. Evidence a Hodnocení Žáků — PRIORITA Č. 2

• Cíl: Digitalizace prací s minimálním úsilím.
• Architektura úložiště: Viz Úložiště souborů v INTEGRATIONS.md.
• Funkce:
  • Role "Služba": Dítě nebo učitel rychle nafotí/naskenuje práce celé třídy.
  • Individuální nahrávání: Žák (starší) si nahrává své projekty.
  • API First: Evidence musí jít vytvořit strojově (např. AI agentem z emailu, z n8n).
    • Use Case: Učitel pošle fotku na evidence@sofie.education → AI vytvoří draft, oštítkuje a připraví ke schválení.
  • Štítkování: Vazba na kompetence a předměty (ideálně automatizovaně pomocí AI).
  • Dopad: Každá naevidovaná práce se automaticky objeví ve Feedu rodiče.

3. Integrace se ŠkolaOnline — PRIORITA Č. 3

• Cíl: Odlehčení administrativy (jedna pravda o žácích).
• Funkce:
  • Synchronizace databází žáků a rodičů.
  • Přenášení absencí/kompetencí (pokud relevantní).

4. Docházka a Vyzvedávání (AI Action)

• Cíl: Bezpečnost dětí a přehled pro školu.
• Funkce (Chat Interface):
  • Vyzvedávání: "Dnes vyzvedne babička." → Sofie to založí a dá vědět učiteli.
  • Bezpečnostní Pojistka (Safety Gate):
    • AI nikdy neprovede akci "tiše".
    • Vždy vrátí Potvrzovací kartu: "Chápu správně, že dnes (9.2.) vyzvedne Aničku paní Marie Nováková?"
    • Rodič musí kliknout na [Potvrzuji a přebírám odpovědnost].
    • Teprve poté se vytvoří záznam.
  • Omluvenky: "Anička je nemocná." → Sofie se doptá na detaily (od-do) a vytvoří omluvenku.
  • Validace: Učitel na tabletu vidí "Dnes: Babička Nováková (tel: 777...)" a jen potvrdí předání.
  • Zjednodušení: Není třeba spravovat "seznam oprávněných osob" v DB rodičem složitě. Rodič to napíše do chatu, AI to vytáhne.
• Družina (Odpolední provoz):
  • Rodič ve feedu vidí: "Anička je v družině. Plánovaný odchod: 15:30."
  • Vyzvedávání z družiny = stejný Safety Gate jako ze školy.
  • Vychovatel/ka družiny zadává docházku a aktivity (jako učitel).
• Kroužky:
  • Rozvrh kroužků v kalendáři (úterý šachy 14:00-15:00).
  • Přihlašování na kroužky (anketa / formulář).
  • Notifikace při zrušení kroužku: "Kroužek šachů ZRUŠEN — nemoc lektora."
  • Feed item: "Anička dnes na kroužku šachů."

5. Ankety a Sběr Dat (Interaktivní Chat)

• Cíl: Rychlé rozhodování.
• Funkce:
  • Rychlé otázky: Sofie se v chatu zeptá: "Máte zájem o kroužek šachů?"
  • Odpověď: Rodič klikne na vygenerovaná tlačítka (Ano / Ne / Více info).
  • Výhoda: Vypadá to jako konverzace, ne jako "úřední deska".
  • Dashboard: Ředitel vidí graf výsledků hned.

6. Sokratův Průvodce — Fáze 4+

• Cíl: Osobní AI průvodce pro každého žáka.
• Funkce:
  • Pomoc s učením ve škole i doma.
  • Reakce na fotky a zájmy žáka ("Vyfotil jsem brouka" → AI navrhne projekt).
  • Bezpečné prostředí (moderováno, schváleno rodiči).

7. Podpora Rodičů — Fáze 4+

• Cíl: Pomoci rodičům rozvíjet dítě doma v souladu se školou.
• Funkce:
  • Tipy na aktivity: "Ve škole probíráme zlomky, zkuste doma krájet pizzu."
  • Knihovna materiálů: Odkazy na Montessori pomůcky/literaturu.

8. Export Dat (Excellence)

• Cíl: Podpora administrativy a reportingu.
• Funkce:
  • Export do Excelu: Tlačítko "Stáhnout .xlsx" u všech tabulek (Seznam žáků, Docházka, Ankety).
  • Export do Google Sheets: Tlačítko "Otevřít v Google Sheets" (vytvoří nový list na Drive).
  • Export do PDF: Tlačítko "Stáhnout PDF" u všech tabulek (Seznam žáků, Docházka, Ankety).
  • Export do CSV: Tlačítko "Stáhnout CSV" u všech tabulek (Seznam žáků, Docházka, Ankety). Pokud je relevantní, tak formát pro ŠkolaOnline.
  • Struktura: Čitelná pro člověka i stroje (žádné sloučené buňky).

9. Marketing a Komunikace (Newsletter) — Listmonk (Fáze 2+)

• Nástroj: Listmonk (self-hosted newsletter).
• Status: Odloženo na Fázi 2. MVP focus = Chat + Evidence + Docházka.

10. Generování Metodických Listů — Fáze 2

• Pipeline: Sofie chat → n8n → Typst → PDF.
• Viz BACKLOG.md.

11. Integrace

• Viz dedikovaný dokument: Integrace (úložiště souborů, channel adapters, Pohoda, ŠkolaOnline, Google, Strava.cz, CLIL).

12. Notifikace a Upozornění

• Cíl: Dostatečně informovat, ale neobtěžovat ("Signal, not Noise").
• Kanály:
  • Email: Pro kritické věci (Faktura, Reset hesla, Urgentní zpráva ředitele). Walled Garden policy — no-reply emaily, odpovědi směřují zpět do aplikace.
  • Push Notifikace: Pro web/mobil (Nový příspěvek v evidenci, Zpráva v chatu).
• Nastavení: Uživatel si může vybrat, co chce dostávat (např. vypnout upozornění na obědy).

13. Feed (Killer Feature)

• Cíl: "Proč si nainstalujete appku? Protože pokaždé, když ji otevřete, víte, co se děje."
• Dopad: Souhrn je pinnutá karta v Feedu — hlavní důvod otevřít appku.
• Adaptivní souhrn ("Od poslední návštěvy"):
  • Systém trackuje last_seen_at pro každého rodiče.
  • Při otevření appky AI vygeneruje souhrn za období od poslední návštěvy:
    • < 4 hodiny: "Právě probíhá: Matematika — zlomky. Od rána: dorazila 8:05, 1 nová fotka."
    • 1 den: "Včera: 2 nové práce, oběd č. 2, odchod 15:30."
    • 1 týden: "Minulý týden: 5 prací, docházka 100 %, výlet na Šumavu (fotky)."
    • 3+ týdny: "Za 3 týdny: 12 prací, 3 omluvenky, docházka 92 %." → po týdnech → dnech → detail.
  • Zero config — rodič nemusí nic nastavovat, vše automaticky.
• Push re-engagement: Pokud se rodič nepřihlásí 3+ dny → "Anička měla zajímavý týden — mrkněte se!"
• Přehled zítřka: Každý den od ~14:00 karta s rozvrhem, obědem, kroužky + zvýrazněné výjimky. Viz Feed v ARCHITECTURE.md.
• Drill-down navigace (ve 2 osách):
  • Časová: Souhrn → Týden → Den → Detail (granularita dle období).
  • Tematická: Souhrn → Detail kategorie (Fotky / Evidence / Docházka / Komunikace).
• Pro ředitele: "Dnes chyběli 3 žáci, Sofie odbavila 15 dotazů, 2 tickety čekají."
• Generováno AI: Sofie automaticky sestaví z dat v DB (evidence, docházka, tickety).
• Personalizovaný styl (nastavitelný rodičem):
  • Příběh: "Anička dnes pracovala na projektu o vesmíru..." (narativní, emoční).
  • Odrážky: "Matematika: zlomky. Čtení: 20 min. Oběd: č. 2. Odchod: 15:30." (strohé, faktické).
  • AI si pamatuje preferenci a generuje souhrn v odpovídajícím tónu.

Nefunkční požadavky

• UX/UI: Maximální jednoduchost ("Apple-like"). Učitel nesmí trávit čas klikáním.
• AI: Využití Gemini API.
• Dostupnost: Webová aplikace (responzivní pro mobily/tablety).
• Bezpečnost: Ochrana osobních údajů dětí (GDPR). Data musí být uložena v EU (Supabase Frankfurt).
• IVP: Individuální vzdělávací plány se ukládají jako work_item (source: 'ivp') + soubory v GCP Cloud Storage. Separátní tabulku řešit až bude jasný workflow.
• Fallback (odpůrci appky): Rodič, který odmítá technologii → telefonát kanceláři, učitel zadá za rodiče. Kritické akce (omluvenky, vyzvedávání) musí jít přes appku — škola toto definuje jako minimum.

Měřitelné cíle (KPI)

Adopce

• 80 % rodičů s aktivním účtem do 1 měsíce od spuštění.
• 90 % omluvenek zadáno přes appku do 3 měsíců.

Efektivita AI

• 70 %+ dotazů odbaveno Sofií bez eskalace.
• Snížení emailů řediteli o 50 % do 6 měsíců.

Spokojenost

• Pravidelný sběr zpětné vazby od rodičů (kvartálně):
  • "Co vás trápí? Co byste chtěli zlepšit? Jak hodnotíte? Co se vám líbí?"
  • Realizováno přes ankety v appce (Sofie se zeptá).
• Dashboard pro ředitele: Vyhodnocení spokojenosti v čase (trendy, grafy).