# Architektura aplikace Livio ## 1. Účel dokumentu Tento dokument popisuje cílovou technickou architekturu Livio. Aplikace je jedna integrovaná responzivní SPA/PWA provozovaná na sdíleném hostingu Webglobe a vyvíjená lokálně na Windows v Laragonu. Funkční rozsah je v [FUNKCE.md](FUNKCE.md), databáze v [DATABAZE.md](DATABAZE.md) a synchronizace v [OFFLINE_SYNC.md](OFFLINE_SYNC.md). ## 2. Architektonické zásady 1. **Jedna aplikace:** jeden frontend, jedno PHP API, jedna databáze a jednotný model oprávnění. 2. **Bez pluginové architektury:** funkce se nevydávají jako instalovatelné moduly. Vnitřní kód však musí být rozdělen podle odpovědností. 3. **Offline-first:** UI pracuje nad lokálním modelem v IndexedDB; síť slouží k replikaci a získání novějších změn. 4. **Serverová autorita:** server vždy znovu ověřuje identitu, členství, roli, datovou validitu a revizi. 5. **Přenositelnost:** data a média lze exportovat bez závislosti na Livio. 6. **Dlouhodobá udržitelnost:** minimum závislostí, otevřené formáty a verzované migrace. 7. **Soukromí ve výchozím stavu:** žádný obsah není veřejný bez budoucího výslovně schváleného návrhu. ## 3. Logický přehled ```text Prohlížeč / nainstalovaná PWA ├── App Shell (HTML + CSS + vanilla JS) ├── stav obrazovek a navigace ├── aplikační služby ├── IndexedDB │ ├── lokální kopie záznamů │ ├── fronta mutací │ ├── rozpracovaná média │ └── synchronizační metadata └── Service Worker ├── cache verzovaných statických souborů ├── offline spuštění └── pomocné spuštění synchronizace, je-li podporováno │ HTTPS + JSON / řízený upload ▼ PHP aplikace na Webglobe ├── vstupní HTTP bod a směrování ├── session, CSRF a bezpečnostní hlavičky ├── validace a autorizace ├── aplikační/doménové služby ├── synchronizační služba ├── služba médií a exportů ├── repozitáře přes PDO └── auditní a technický log │ ├── MySQL/MariaDB └── neveřejné souborové úložiště médií, náhledů a exportů ``` ## 4. Technologická základna | Oblast | Rozhodnutí | Poznámka | |---|---|---| | Backend | PHP bez frameworku a bez Composeru | Vlastní malý router a jasné vrstvy; žádný požadavek na CLI v produkci. | | Databáze | MySQL/MariaDB, PDO | InnoDB, `utf8mb4`, cizí klíče a parametrizované dotazy. | | Frontend | HTML, CSS, vanilla JS | Bez SPA frameworku a produkčního bundleru. | | Lokální úložiště | IndexedDB | Autoritativní lokální pracovní kopie a fronta. | | Offline spuštění | Service Worker + Cache Storage | Pouze App Shell a bezpečně cachovatelná aktiva; osobní API data patří do IndexedDB. | | Vývoj | Laragon na Windows | PHP, webový server a MySQL ve verzích co nejbližších hostingu. | | Produkce | Webglobe sdílený hosting | Bez dlouho běžících procesů; periodické úlohy jen přes hostingový cron, pokud je dostupný. | **Návrh k potvrzení:** minimální PHP 8.2 a MySQL 8.0/MariaDB odpovídající nabídce konkrétního tarifu Webglobe. Před implementací se musí ověřit skutečné verze, limity uploadu, `memory_limit`, `max_execution_time`, cron, dostupnost Imagick/GD a možnost ukládat soubory mimo veřejný kořen. ## 5. Doporučená struktura projektu ```text / ├── AGENTS.md ├── docs/ ├── public/ # jediný veřejný webový kořen │ ├── index.php # vstup SPA a nouzový fallback │ ├── api/index.php # vstup HTTP API │ ├── manifest.webmanifest │ ├── service-worker.js │ └── assets/ │ ├── css/ │ ├── js/ │ ├── icons/ │ └── fonts/ ├── src/ │ ├── Http/ # request, response, router, middleware │ ├── Auth/ # session, přihlášení, CSRF, role │ ├── Domain/ # případy užití a doménová pravidla │ ├── Sync/ # push, pull, konflikty, idempotence │ ├── Media/ # upload, kontrola, náhledy, autorizovaný výdej │ ├── Export/ # PDF a archivní balíčky │ ├── Repository/ # PDO dotazy │ └── Support/ # konfigurace, čas, UUID, logování ├── config/ │ ├── app.example.php # bezpečný příklad bez tajných údajů │ └── routes.php ├── database/ │ └── migrations/ ├── storage/ # mimo public; v produkci může být přesunuto konfigurací │ ├── media/ │ ├── previews/ │ ├── exports/ │ ├── logs/ │ └── tmp/ ├── tests/ └── tools/ # ručně spouštěné servisní skripty, pokud budou potřeba ``` Jde o cílovou strukturu, nikoli pokyn ji nyní vytvářet. Pokud Webglobe nepovolí změnit document root na `public/`, veřejná část se nasadí do hostingového webového adresáře a zbytek nad něj; konfigurace serveru musí zabránit přístupu ke zdrojům, migracím, logům a úložišti. ## 6. Frontendová architektura ### 6.1 App Shell a navigace - Server vrací základní HTML dokument, manifest a odkazy na verzovaná aktiva. - Vanilla JS převezme navigaci pomocí History API a vykresluje obrazovky bez úplného znovunačtení. - Aktuální klientský router zachovává hlavičku, obě navigace, dialog nabídky a globální stav jako trvalý App Shell. Při změně trasy vyměňuje pouze obsah elementu `main`, aktualizuje aktivní odkazy a obsluhuje `popstate`; opakované otevření právě aktivní trasy pouze zavře nabídku a nevykresluje obsah znovu. - Přímé otevření podporované adresy musí přes server vrátit App Shell; API a soubory se nesmí přesměrovat na SPA. - URL mají stabilní české či technicky neutrální cesty, například `/casova-osa`, `/deti/{id}`, `/kroniky`. - Kritické funkce musí mít srozumitelný stav při načítání, prázdných datech, offline režimu, chybě a nedostatečném oprávnění. ### 6.2 Vrstvy v JavaScriptu | Vrstva | Odpovědnost | |---|---| | `ui` | komponenty, formuláře, dialogy, přístupnost, navigace | | `application` | případy užití, validace pro okamžitou odezvu, orchestrace | | `store` | dotazy a transakce IndexedDB, lokální projekce | | `sync` | fronta, push/pull, stavy synchronizace a konflikty | | `api` | HTTP klient, CSRF, jednotné chyby a timeouty | | `media` | lokální soubory, náhledy, upload po částech nebo opakovatelný upload | Serverová validace zůstává povinná, i když stejná pravidla pro pohodlí kontroluje klient. ### 6.3 Ukládání osobních dat - Osobní JSON odpovědi se neukládají do běžné HTTP cache ani do Cache Storage. - Offline záznamy jsou oddělené klíčem účtu a rodiny. Po odhlášení se odstraní aktivní offline oprávnění; šifrované snímky zůstávají lokálně a bez nového platného serverového oprávnění se neotevřou. - Aktuální obsah Přehledu se stále vykresluje z demo dat. Offline snímek proto zatím není synchronizovaným rodinným datovým modelem; tento rozdíl a omezení jsou popsány v `docs/OFFLINE_SYNC.md`. - Citlivá data na sdíleném zařízení nejsou automaticky bezpečná jen proto, že jsou v IndexedDB. Viz návrh místního zámku v `FUNKCE.md`. - Rodinný klíč může být pro stejné přihlášené zařízení uložen jako AES-GCM obal pod neexportovatelným klíčem Web Crypto v IndexedDB. Obal se nikdy neposílá serveru. Nové zařízení nebo odstraněné/poškozené místní úložiště nadále vyžaduje vlastní obnovovací seed. Nejde o hardwarově vázaný klíč: skript běžící pod stejným původem může žádat o jeho použití, proto zůstává ochrana proti XSS zásadní. ### 6.4 Průvodce rodinou po přihlášení Před vykreslením Přehledu klient ověří stav členství na serveru. Existující člen pokračuje do stávajícího Přehledu; účet bez členství může založit rodinu, přijmout pozvánku jako přihlášený uživatel nebo vytvořit účet přímo přes QR pozvánku. QR registrace vyžaduje současně jednorázové 256bitové tajemství z QR a šestimístný kód doručený na pozvaný e-mail. Čitelný QR obsah ani rodinný klíč neopouštějí zařízení. Nedostupný server, HTTP 503 ani offline stav nejsou důkazem absence rodiny a nesmějí vyvolat falešný Přehled ani odhlášení. Údaje průvodce se ukládají v IndexedDB šifrovaně klíčem odvozeným pro přihlášený účet. Kód pozvánky se neukládá; po restartu se musí zadat znovu. Založení rodiny, odeslání pozvánky a přijetí pozvánky vyžadují online spojení. QR registrace ověřuje pozvánku a e-mailový kód před vytvořením účtu; konečné vytvoření členství, uložení obnovovacího obalu, aktivaci účtu a spotřebování QR server provádí atomicky. Detail endpointů a migrace je v `docs/DATABAZE.md`, část 12.1.9. ## 7. Backendová architektura ### 7.1 Tok požadavku ```text HTTPS požadavek → normalizace a korelační ID → bezpečnostní hlavičky a limity → načtení session → ověření CSRF u stavové operace → směrování → validace vstupu → autorizace rodiny a objektu → doménová operace v transakci → audit citlivé akce → JSON odpověď bez citlivých detailů ``` ### 7.2 Rozhraní API - Prefix: `/api/v1`. - Kódování: UTF-8, JSON; média používají samostatný řízený přenos. - Časy: ISO 8601 v UTC, např. `2026-11-04T14:30:00Z`. - ID: UUID generované klientem nebo serverem; interní číselné klíče se nevystavují jako bezpečnostní prvek. - Chyba má stabilní tvar: ```json { "error": { "code": "REVISION_CONFLICT", "message": "Záznam byl mezitím změněn na jiném zařízení.", "correlation_id": "…", "details": {} } } ``` - `details` smí obsahovat pouze bezpečná, strojově zpracovatelná validační data. - Synchronizační endpointy jsou popsány v `OFFLINE_SYNC.md`. - Běžné čtení může používat stránkování kurzorem. Nepoužívat offset pro dlouhé měnící se časové osy. ### 7.3 Transakce a souběh - Jedna doménová změna a zápis do serverového change logu proběhnou v jedné databázové transakci. - Aktualizace používá očekávanou revizi; `UPDATE ... WHERE uuid = ? AND revision = ?` zabrání tichému přepsání. - `operation_id` má unikátní omezení pro idempotentní opakování. - Smazání synchronizovaných objektů je měkké (`deleted_at`). Fyzické vyčištění může proběhnout až po schválené retenční době a po záloze. ## 8. Média ### 8.1 Životní cyklus 1. Uživatel vybere fotografii nebo video i offline. 2. Klient vytvoří lokální metadata, náhled, UUID a položku fronty; originální Blob uloží do IndexedDB, pokud to kapacita dovolí. 3. Po připojení server založí upload session a ověří oprávnění a kvótu. 4. Klient odešle obsah opakovatelně; u velkých videí se použijí části, pokud to omezení hostingu vyžaduje. 5. Server ověří velikost, skutečný MIME, povolený formát, hash a bezpečný název. 6. Originál uloží jako neměnný soubor, vytvoří metadata a případné náhledy. 7. Teprve potvrzený hash označí médium jako synchronizované. ### 8.2 Uložení a výdej - Fyzická cesta se odvozuje z náhodného UUID a členění, nikoli z původního názvu. - Originál a náhled mají oddělené záznamy/varianty. Originál se nikdy nepřepisuje. - PHP endpoint při každém stažení ověří session, členství v rodině a vazbu na médium; podporuje `Range` pro video, pokud hosting dovolí efektivní streamování. - Hlavičky mají zabránit veřejnému cachování osobního obsahu. - Metadata EXIF mohou obsahovat polohu. Aplikace polohu zobrazí nebo exportuje pouze podle nastavení soukromí; originál však zůstane nezměněný. **Návrh k potvrzení:** maximální velikost jedné fotografie, videa, celková kvóta rodiny a seznam podporovaných kodeků. Hodnoty se určí až podle tarifu Webglobe a očekávaného počtu médií. ## 9. Generování kronik a exportů ### 9.1 Krásná PDF kronika - Uživatel zvolí dítě nebo rodinu, období, typy událostí, členy, média a vzhled. - Server vytvoří neměnný snapshot zadání a zdrojových revizí. - Generátor sestaví titulní stranu, kapitoly, chronologickou osu, texty, popisky a vybrané fotografie. - Výsledek obsahuje datum vytvoření, rozsah a identifikátor exportu; nestává se zdrojem pravdy. ### 9.2 Úplná archivní kronika Navržená struktura ZIP balíčku: ```text livio-archiv-YYYY-MM-DD/ ├── README.txt ├── manifest.json ├── checksums-sha256.txt ├── data/ │ ├── family.json │ ├── children.json │ ├── records.json │ ├── relationships.json │ └── csv/ ├── chronicle/ │ ├── beautiful.pdf │ └── archival.pdf └── media/ ├── originals/ └── previews/ ``` - `manifest.json` uvádí verzi formátu, kódování, čas vytvoření, rozsah, počty, vazby a hashe. - Originály jsou exportovány zvlášť pod stabilními názvy; mapování na původní názvy a záznamy je v manifestu. - Export musí být možné ověřit bez aplikace Livio pomocí SHA-256. - Dočasné exporty se po definované době bezpečně odstraní; vytvoření a stažení se auditují. **Návrh k potvrzení:** knihovna nebo vlastní postup generování PDF bez Composeru, požadavek na PDF/A-2b a způsob validace. Před rozhodnutím se musí ověřit licence, české fonty, dostupná paměť a časové limity Webglobe. U velkých kronik může být nutné stránkované dávkové generování spouštěné opakovanými HTTP kroky nebo cronem. ## 10. PWA a Service Worker - Manifest definuje název Livio, barvy, `standalone` režim a explicitní ikony. - PWA používá stabilní jednoznačné `id` `/livio/public/livio-family-chronicle-v1`; `start_url` a `scope` jsou omezené na `/livio/public/`. Manifest má vlastní cestu `livio-v1.webmanifest`, aby se instalace ani její cache nekřížila s dalšími PWA na stejném originu. - `release.json` je jediným zdrojem verze a čísla buildu. Při přípravě distribuce `php scripts/priprav-vydani.php` porovná otisk obsahu veřejných souborů aplikace, aktiv a dat Přehledu. Při změně ho uloží a zvýší build o jeden. První vydání začíná číslem 1. PHP při požadavku údaje pouze čte. - Číslo buildu je součástí URL CSS, JavaScriptu, manifestu a Service Workeru. Viditelné označení verze je součástí HTML dokumentu, takže offline zobrazuje skutečně načtené vydání. - Klient kontroluje `index.php?release=1` mimo mezipaměť každých 15 sekund ve viditelné aplikaci a také při načtení, návratu do popředí nebo obnovení připojení. Nový Service Worker před aktivací ověří build dokumentu a připraví samostatnou mezipaměť vydání. - Navigační dokument aktivního vydání se vrací nejprve z jeho App Shell cache; samostatná kontrola buildu a instalace nového Service Workeru zůstává autoritou pro aktualizace. Verzovaná statická aktiva se také nejdřív hledají v mezipaměti. - API požadavky se necachují jako obecné response objekty; o data se stará IndexedDB. - Viditelná stránka požádá o aktivaci hned po dokončení instalace, pokud je obnovení bezpečné. Po převzetí řízení se obnoví jednou na aktuální trase. Rozepsané přihlášení, vybraný soubor, rozpracovaná data nebo probíhající upload obnovení odloží. Editory označí neuložená data pomocí `data-unsaved="true"` a uploady pomocí `data-uploading="true"`, dokud nelze bezpečně obnovit stránku. Čekající aktualizace se zkusí znovu při další kontrole. Po aktivaci se odstraní pouze starší mezipaměti Livio. IndexedDB, fronta operací a mezipaměti jiných aplikací zůstávají nedotčené. - PWA neslibuje neomezené offline uložení videí; aplikace zobrazuje kapacitu a stav trvalého úložiště. ## 11. Bezpečnostní architektura Přihlášení je součástí App Shellu a jeho grafika je dostupná i z offline mezipaměti. Server do Přehledu načte `demo.php`, pokud existuje, a jinak použije `demo.example.php`. Přepínání obrazovek řídí stávající SPA. Online start ověřuje `session.php` pod startovní vrstvou. Při síťové chybě nebo HTTP 5xx může klient otevřít pouze šifrovaný poslední snímek Přehledu, pokud má platné 7denní serverem podepsané oprávnění svázané s neexportovatelným klíčem instalace. HTTP 200 s neplatnou relací a HTTP 401 oprávnění odmítnou; neúspěšné ověření se nikdy nenahrazuje samotným ID či příznakem. Podrobnosti a omezení jsou v `docs/OFFLINE_SYNC.md`. ### 11.1 Autentizace - E-mail a heslo, bezpečný hash pomocí PHP `password_hash()`. - Session ID pouze v cookie `HttpOnly`, `Secure`, `SameSite=Lax` nebo přísněji podle ověřených toků. - Regenerace relace po přihlášení a citlivé změně; absolutní a neaktivní expirace. - Reset hesla jednorázovým, krátce platným, hashovaně uloženým tokenem; odpověď nesmí prozradit existenci účtu. - Rate limit přihlášení a resetu podle účtu i zdroje s rozumným zohledněním sdílených IP. ### 11.2 Autorizace Každá operace ověřuje: 1. přihlášeného uživatele; 2. aktivní členství v cílové rodině; 3. roli a konkrétní oprávnění; 4. příslušnost dítěte, záznamu, média či exportu k rodině; 5. případné omezení dopisu do budoucna do data odemčení. ID v URL nebo JSON není důkaz oprávnění. ### 11.3 Další ochrany - CSRF token pro všechny stavové požadavky používající cookie session. - Content Security Policy bez `unsafe-eval`; inline skripty nepoužívat. - `X-Content-Type-Options: nosniff`, rozumná `Referrer-Policy`, zákaz framingu a HSTS po ověření HTTPS. - Serverově escapované HTML; dynamický text na klientovi vkládat přes `textContent`. - Audit změn rolí, exportů, stažení originálů, obnovy, mazání a bezpečnostních změn. ## 12. Konfigurace, logy a provoz - Tajná konfigurace je mimo Git a pokud možno mimo veřejný kořen. Repozitář obsahuje jen příklad s popisem. - Prostředí `development` a `production` se liší konfigurací, ne větvením zdrojového kódu. - Produkce nezobrazuje stack trace ani SQL chyby. - Každá chyba má korelační ID. Log obsahuje čas UTC, úroveň, událost a bezpečný kontext bez osobních textů a tokenů. - Logy se rotují a mažou dle retenční politiky. Kritické chyby záloh a exportů musí být zjistitelné správcem. - Zdravotní kontrola ověřuje běh PHP, databázi a zapisovatelnost potřebných adresářů, ale nezveřejňuje verze ani tajné údaje. ## 13. Zálohování a 50letý horizont Technická životnost 50 let nevznikne jedním formátem, ale procesem: - pravidelná databázová záloha a oddělená záloha originálních médií; - šifrovaná kopie alespoň na druhém fyzickém místě; - pravidelný test obnovy do izolovaného prostředí; - kontrolní součty a periodická kontrola integrity médií; - otevřený archivní export, dokumentovaná verze formátu a migrační cesta; - pravidelná obnova zastaralých formátů bez odstranění originálu; - sledování podporovaných verzí PHP, MySQL, prohlížečů a kryptografických doporučení. **Návrh k potvrzení:** konkrétní cíle obnovy `RPO` a `RTO`, retenční plán záloh, druhé úložiště a osoba odpovědná za pravidelné testy obnovy. ## 14. Nasazení ### 14.1 Laragon - Lokální HTTPS, aby bylo možné testovat Service Worker a secure cookies co nejblíže produkci. - Samostatná vývojová databáze a neveřejná konfigurace. - Testovací média bez skutečných rodinných údajů. - Verze PHP/MySQL mají odpovídat potvrzenému Webglobe prostředí. ### 14.2 Webglobe 1. vytvořit přednasazovací zálohu; 2. nahrát verzované soubory do nové nebo bezpečně přepínané verze; 3. nastavit neveřejnou konfiguraci a oprávnění adresářů; 4. spustit dopředné migrace jednou pod zámkem; 5. provést smoke test přihlášení, API, uploadu, offline App Shellu a exportu; 6. sledovat logy a mít připraven návrat aplikace bez vracení nekompatibilní databáze. Nasazení nesmí proběhnout automaticky jen proto, že testy prošly; vyžaduje výslovné zadání. ## 15. Testovací strategie - PHP unit testy doménových pravidel a autorizace bez produkčních dat. - Integrační testy PDO repozitářů, migrací a transakcí. - API testy validace, session, CSRF, rolí, cizí rodiny a idempotence. - JavaScript testy IndexedDB, fronty, slučování a práce s časem. - End-to-end scénáře online/offline, dvě zařízení, restart, limit úložiště a aktualizace Service Workeru. - Bezpečnost uploadu: podvržený MIME, dvojitá přípona, příliš velký soubor, cizí UUID a pokus o přímé stažení. - Export: počty, vazby, otevření PDF, kontrola hashů, česká diakritika a obnova z balíčku. - Vizuální testy na 360, 768, 1024 a 1440 px a při 200% zoomu. ## 16. Otevřené návrhy k potvrzení | Téma | Návrh / otázka | |---|---| | Verze serveru | PHP 8.2+ a konkrétní MySQL/MariaDB podle tarifu. | | E-mail | Způsob spolehlivého odesílání pozvánek a resetů na Webglobe. | | Média | Kvóty, maximální velikosti, video kodeky a zpracování náhledů. | | PDF | Generátor bez Composeru, licence, PDF/A a dávkové zpracování. | | Zálohy | Druhé úložiště, frekvence, retence, RPO/RTO a odpovědnost. | | Lokální ochrana | Zda přidat volitelný PIN/biometrický zámek PWA nad rámec session. | | Fyzické mazání | Retenční doba koše, synchronizačních náhrobků, auditů a exportů. | | Velké archivy | Maximální velikost ZIP a případné dělení na více svazků. | ## 17. Rodinný tarif a úložiště Serverové rozhraní v `public/api/v1/billing/` je jedinou autoritou pro rodinný tarif, kredit a inventuru R2. Každý požadavek ověřuje relaci a členství v rodině; změny tarifu a žádost o dobití vyžadují rodinnou roli správce nebo rodiče, ruční potvrzení plateb a administrace ceníku systémovou roli administrátora či vývojáře. Klient nikdy neposílá autoritativní zůstatek ani tajné klíče. Tarifové období ukládá cenový a kapacitní snímek. Odečet z rodinného kreditu probíhá v transakci se zámkem peněženky a idempotentním klíčem. Dobití probíhá pouze bankovním převodem nebo QR Platbou. Vytvoření žádosti kredit nemění; administrátor nebo vývojář musí platbu ověřit v bankovnictví a ručně potvrdit. Potvrzení atomicky uzamkne žádost i peněženku, připíše kredit a vloží neměnnou účetní transakci s unikátním idempotentním klíčem. QR payload ve formátu SPD se vykresluje lokálním JavaScriptem, platební údaje se načítají výhradně ze serverové konfigurace a při jejich absenci je žádost zablokována. Stav prostoru se získává úplným stránkovaným ListObjectsV2 nad prefixem `rodiny/{id}/`; tím se do kvóty započítává rodinné médium i profilové fotografie členů. Profilová fotografie má vlastní klíč na členství rodiny v `rodina_clenove.profil_fotografie_klic` a ukládá se pod `rodiny/{rodina_id}/uzivatele/{uzivatel_id}/profil/`, takže uživatel může mít v každé rodině jiný obrázek. Rodinná média mají používat podprefixy `rodiny/{id}/media/fotografie/` a `rodiny/{id}/media/videa/`. Uploadové API rodinných médií zatím v aplikaci není implementováno; při jeho doplnění musí použít tyto prefixy a stávající kontrolu členství, kvóty a autorizovaného výdeje. ## 18. Osobní účet a profilová fotografie Osobní nastavení se otevírá jako SPA sekce `nastaveni-uctu`. API `account/profile.php` vrací údaje přihlášeného účtu a pouze jeho aktivní členství; `account/save.php` ověřuje session, CSRF, příslušnost k vybrané rodině a oprávnění změnit vztah. Systémová role se nikdy nemění tímto formulářem. Datum narození je volitelné a kontroluje se proti budoucímu datu. Karty rodičů v Přehledu načítá `family/parents.php` podle aktuálně vybrané rodiny. Server vrací jen aktivní členy se vztahem `matka` nebo `otec` a vždy nejprve ověří aktivní členství požadujícího uživatele. Profilová fotografie se vydává přes `family/parent-photo.php`, který při každém požadavku opakuje kontrolu členství i vztahu a načítá ověřený objekt z neveřejného R2. Oba endpointy odpovídají bez HTTP cache. Klient mění pouze obsah dvou rodičovských karet; při chybě připojení ponechá poslední údaje v existujícím šifrovaném snímku Přehledu a fotografii nahradí náhradní ikonou. Výřez fotografie vytváří klientský canvas 512 × 512 px. Zdroj může mít nejvýše 15 MB; otáčení podle EXIF respektuje dekódování prohlížeče, výřez lze ručně posouvat a přibližovat. Před odesláním se nový výřez v zařízení zašifruje AES-256-GCM existujícím rodinným klíčem. Binární obálka `LIVIOP01` obsahuje verzi, MIME, rozměry a jedinečný IV; rodina, vlastník fotografie a metadata jsou navázány jako autentizovaná doplňková data. `account/save.php` i synchronizační endpoint přijímají pouze tuto obálku a PHP ji nerozšifrovává. Objekt `.enc` zůstává v neveřejném R2 pod dosavadním prefixem. Endpointy fotografii vydávají pouze oprávněnému členu jako neprůhlednou obálku; společná klientská služba ji po ověření rodinného klíče dešifruje. Starší obrázkové objekty se nadále vydávají a zobrazují beze změny. Poslední úspěšně načtené údaje profilu a rozpracované textové změny se ukládají odděleně podle uživatele do existujícího šifrovaného úložiště `scopedDrafts` v IndexedDB. Lokální zobrazená fotografie je uložena v `scopedPhotos` šifrovaná klíčem účtu a rodiny. Při změně fotografie bez sítě se v jediné transakci uloží tato lokální kopie a položka `profile-photo-upload` do existujícího `outbox`; fronta obsahuje pouze E2EE šifrovaný soubor, nikdy čitelný obrázek. Po obnovení sítě se upload opakuje idempotentně, server kontroluje členství a verzi předchozí fotografie a při konfliktu ponechá položku i místní kopii. Textové změny zůstávají samostatným návrhem a nejsou předstírány jako synchronizované. Přístupová ztráta dané rodiny odstraní její čekající profilové uploady. Při zapnutém „Zůstat přihlášen“ se poslední serverem potvrzený přehled tarifu a prostoru ukládá jako šifrovaný rodinný snímek do existujícího offline úložiště, se stejným klíčem vázaným na účet a rodinu. Offline režim je pouze pro čtení; tarif nelze koupit, kredit dobít ani prostor měřit bez serveru. ## 18. Průběžné ověřování serverového stavu Přihlášená a viditelná SPA ověřuje přes `GET /api/v1/state/snapshot.php` změny identity, systémové role, členství a oprávnění, názvu rodiny a uloženého stavu kreditu, tarifu a úložiště. Kontrola běží přibližně každých 15 sekund, při návratu do popředí nebo připojení se spouští bez čekání. Při skryté stránce či offline stavu se pozastaví; při chybách používá omezené exponenciální opakování. Požadavky se v jednom panelu nepřekrývají a změna se mezi otevřenými panely oznamuje přes `BroadcastChannel` bez ukládání osobních údajů do něj. Server sestavuje malý deterministický snímek pouze z účtu, členství přihlášeného uživatele a existujících databázových evidencí tarifu, kreditu a měření. SHA-256 kurzor pokrývá hodnoty samotné, takže zachytí i přímé změny v MariaDB bez spoléhání na `aktualizovan_at`. Nezměněný stav vrací pouze kurzor. Dotaz neprovádí inventuru Cloudflare R2 a nemění databázi. Každé chráněné API nadále samo ověřuje aktuální relaci a oprávnění. Klient při změně upravuje existující texty a navigační oprávnění bez obnovení dokumentu, výměny celé stránky, loaderu nebo úspěšné toast hlášky. Odpověď 503 či síťová chyba neodhlašuje uživatele; při 401 se samostatně ověří relace a pouze skutečně neplatná relace přejde na přihlášení. Odebrání členství zneplatní uložený offline přístup k rodinným datům. Žádná databázová migrace pro kontrolní mechanismus není potřeba. ## 19. Rodinný šifrovací klíč – obnovovací fráze Rodina používá náhodný 256bitový klíč. Při prvním zabezpečení správce rodiny obdrží 12slovnou BIP-39 frázi a ověří dvě náhodná slova v samostatném kroku. Fráze odvozuje AES-256-GCM obal klíče přes BIP-39 PBKDF2-HMAC-SHA512 a HKDF-SHA256. Server ukládá pouze tento šifrovaný obal; čitelná fráze se po dokončení zahodí a v nastavení se znovu nezobrazuje. Při obnově na novém zařízení, v novém prohlížeči nebo pod novým původem HTTPS uživatel jednorázově zadá svou 12slovnou frázi. PWA stáhne pouze šifrovaný obnovovací obal serveru a rozbalí jej lokálně. Čitelný seed ani nezašifrovaný rodinný klíč se na server neposílají. Po obnově se klíč znovu uloží jako obal za neexportovatelným klíčem Web Crypto v IndexedDB daného původu, aby se při dalších spuštěních obnovoval bez seedu. Pokud prohlížeč bezpečné uložení nepodporuje nebo jeho úložiště odstraní, je nutná další obnova. Hosté rodinný klíč nedostávají. Migrace `0015_rodinne_sifrovani` vytváří tabulky rodinných klíčů a obnovovacích obalů. Migrace `0016_rodinne_e2ee_prf` zůstává zachována kvůli kompatibilitě; PRF tabulky klient nepoužívá. Pozvánka do šifrované rodiny používá dvě nezávislé podmínky: e-mailový kód a 256bitové jednorázové tajemství v QR. Klient tajemstvím šifruje rodinný klíč; server ukládá ciphertext, ověřovací hash a tajemství zabalené šifrováním pod rodinným klíčem. PHP nedostává čitelný klíč ani původní QR tajemství. Původní QR se na zařízení správce ukládá v IndexedDB za neexportovatelným klíčem zařízení; jeho zobrazení neobnovuje seed ani rodinný klíč. Po přijetí, expiraci nebo zrušení se serverové přenosové hodnoty zneplatní. Podrobnosti jsou v `docs/DATABAZE.md`, část 12.1.9. Tato etapa připravuje ochranu rodinného klíče a jeho obnovu. Nové profilové fotografie jsou klientsky šifrovány podle části 18; rodinná metadata, videa a ostatní vzpomínky zatím šifrovány nejsou. Nelze proto tvrdit, že aplikace již poskytuje úplné E2EE rodinných dat. Schéma klíčů je v [DATABAZE.md](DATABAZE.md#12110-rodinné-šifrovací-klíče). ## 20. Stav aplikace SPA sekce `stav-aplikace` zobrazuje dostupnost serveru, databáze a šifrování aktuálně vybrané rodiny. Stránka i její samostatný CSS a JavaScript jsou součástí App Shell a fungují offline. `GET /api/v1/system/status.php` vyžaduje existující přihlášenou relaci, přijímá pouze volitelné kladné číselné `family_id` a vrací jen obecné stavy služeb. Databázovou dostupnost ověřuje server přes centrální konfiguraci běžným připojením a `SELECT 1`; pro tuto diagnostiku se přeskočí automatický úklid relací, takže endpoint databázi nemění. Přístup k rodinnému stavu se ověřuje aktivním členstvím. Serverový stav `configured` potvrzuje pouze existenci aktivního šifrovacího klíče rodiny. Klient jej označí jako „Aktivní“ teprve po ověření, že klíč drží v paměti nebo jej dokáže obnovit z místního obalu zařízení. Pokud je rodina nastavena, ale klíč v tomto původu chybí, zobrazí se „Zamčeno“ a možnost obnovy. Obnova používá stávající endpoint `family-e2ee-recovery`; server ověřuje členství a vrací pouze šifrovaný obnovovací obal.