# Livio – pravidla pro Codex Tento soubor je závazným pracovním zadáním pro všechny změny v projektu Livio. Platí pro celý repozitář, pokud podřízený `AGENTS.md` výslovně neurčí přísnější pravidla. Dokumentace v `docs/` je součástí specifikace; při rozporu se změna zastaví a rozpor se předloží uživateli. ## KRITICKÉ PRAVIDLO – ZÁKAZ ZÁSAHŮ DO LOCALHOSTU Toto pravidlo má nejvyšší prioritu v rámci projektových pravidel Livio a platí pro všechny budoucí úkoly. Bez předchozího výslovného pokynu uživatele Codex nesmí měnit konfiguraci, nastavení ani provoz lokálního vývojového prostředí Laragon a žádné jeho součásti. Zákaz platí i tehdy, pokud se změna zdá potřebná k dokončení úkolu. Bez výslovného pokynu uživatele je zakázáno: - Měnit nastavení Laragonu ani konfiguraci MariaDB/MySQL, Apache/Nginx nebo PHP. - Měnit porty, hostitele, služby, systémové proměnné, datové adresáře, virtuální hostitele, lokální domény nebo systémový soubor `hosts`. - Měnit soubory `my.ini`, `my.cnf`, `httpd.conf`, `php.ini` a jiné systémové konfigurační soubory; upravovat `.htaccess` mimo projekt Livio. - Měnit databázové uživatele, hesla, oprávnění nebo systémové databáze. - Instalovat, aktualizovat, odinstalovat či přepínat verze PHP, MariaDB, MySQL, Apache nebo jiných komponent. - Spouštět, zastavovat či restartovat služby Laragonu. - Zasahovat do jiných projektů v localhostu nebo spouštět příkazy, které mohou změnit konfiguraci či chování lokálního serveru. - Provádět automatické opravy, optimalizace nebo změny bezpečnostních nastavení localhostu. Bez dalšího souhlasu je dovoleno pouze číst konfiguraci localhostu pro diagnostiku, kontrolovat stav služeb bez změny, zjišťovat verze komponent, pracovat se zdrojovými soubory projektu Livio podle zadání, upravovat tabulky výhradně v databázi Livio, pokud je to výslovnou součástí aktuálního zadání, a spouštět bezpečné testy, které nemění nastavení localhostu. Povolení měnit databázové tabulky nikdy neznamená povolení měnit konfiguraci databázového serveru. Pokud úkol vyžaduje změnu nastavení Laragonu nebo jeho součástí, Codex musí zastavit pouze závislou část práce, popsat konkrétní problém a navrhované nastavení a vyčkat na výslovné povolení. Změnu nesmí provést automaticky. Toto pravidlo je závazné pro všechny části projektu a má přednost před jakýmkoli jiným projektovým pokynem, který by povoloval zásah do localhostu bez výslovného souhlasu uživatele. ## Práce s databází Livio – závazný postup pro Codex - Jediným zdrojem připojovacích údajů je `public/config/config.php`. Nikdy nezobrazuj ani nekopíruj jeho tajné hodnoty do výstupů. - Aplikační PHP používá `livio_auth_db()` v `public/api/v1/auth/common.php`. Databázové migrace používají stejné centrální nastavení přes `scripts/migrate.php`. - Ověřený místní postup pro PHP CLI je použít binární soubor Laragon PHP 8.3.33 a načíst konfiguraci přímo z `public/config/config.php`. Bezpečný kontrolní dotaz je `SELECT DATABASE(), VERSION()`; ověřený výsledek 16. 11. 2026 byl databáze `livio`, MariaDB `11.8.3-MariaDB-log`, následně byla potvrzena i tabulka `rodiny`. - Ověřovací příkaz PowerShellu (vypisuje pouze název databáze a verzi, nikoli tajné údaje): `& 'C:\laragon\bin\php\php-8.3.33-Win32-vs16-x64\php.exe' -r '$c=require "public/config/config.php"; $d=$c["database"]; $p=new PDO("mysql:host={$d["host"]};port={$d["port"]};dbname={$d["name"]};charset={$d["charset"]}",$d["username"],$d["password"],[PDO::ATTR_ERRMODE=>PDO::ERRMODE_EXCEPTION]); echo json_encode($p->query("SELECT DATABASE() AS db, VERSION() AS version")->fetch(PDO::FETCH_ASSOC));'` - V tomto prostředí může neprivilegovaný PHP CLI pokus skončit chybou MySQL 2002 „přístup k socketu byl zakázán oprávněními prostředí“. Ověřený postup je spustit tentýž PHP CLI přístup přes schválené zvýšené oprávnění nástroje. Tím se nemění hostitel, port, přihlašovací údaje ani konfigurace serveru. Pokud zvýšený přístup není dostupný, zastav databázovou operaci a popiš omezení; nevytvářej jiný připojovací mechanismus a neobcházej ochrany prostředí. - Pro migrace použij existující příkaz `& 'C:\laragon\bin\php\php-8.3.33-Win32-vs16-x64\php.exe' scripts/migrate.php` a stejný schválený způsob spuštění, pokud jej omezuje přístup k socketu. Migrace vždy nejprve prověř, neměň její evidenci ručně a ověř výsledek skutečným SQL dotazem. - Úplnou komprimovanou zálohu vytvoř existujícím nástrojem `& 'C:\laragon\bin\php\php-8.3.33-Win32-vs16-x64\php.exe' public/mysql_dump.php`. Ověř výsledek a soubor v `public/backup/mysql/`; nástroj omezuje historii na 10 záloh a nastavuje omezená oprávnění. Zálohu neoznačuj za ověřenou, dokud existuje a lze ji celou dekomprimovat. - Při změnách dat nejprve ověř skutečná cizí omezení a počty, proveď parametrizované dotazy v transakci, zachovej ostatní rodiny a po potvrzení transakce znovu ověř výsledek SQL. Nikdy nevypínej kontrolu cizích klíčů a nevytvářej veřejný endpoint pro obecné SQL. - Před každým úkolem vyžadujícím přístup k databázi musí Codex automaticky použít tento ověřený projektový postup. Nesmí opakovaně zkoušet známý neprivilegovaný PHP CLI pokus ani požadovat nové vysvětlování stejného omezení. ## 1. Cíl produktu Livio je soukromá rodinná SPA/PWA pro bezpečné uchování vzpomínek od těhotenství dítěte přes narození a dětství až do dospělosti. Základ tvoří chronologická časová osa, média, milníky, růst, výlety, porodnice, rodinné vztahy a dopisy do budoucna. Hlavním výstupem je krásná tisková PDF kronika a úplná archivní kronika s originálními médii exportovanými samostatně. Data mají zůstat čitelná a exportovatelná nejméně 50 let. Přenositelnost, zálohování a obnovitelnost proto mají přednost před krátkodobým technickým pohodlím. ## 2. Závazná technologická omezení - Jedna integrovaná, nemodulární a responzivní SPA/PWA. „Nemodulární“ znamená bez systému instalovatelných modulů či pluginů; neznamená jeden obří soubor. Kód se dělí podle odpovědností. - Backend: PHP podporované aktuálním sdíleným hostingem Webglobe. - Databáze: MySQL/MariaDB poskytovaná Webglobe; používat jen funkce dostupné na cílové verzi. - Frontend: sémantické HTML, CSS a vanilla JavaScript bez frameworku. - Bez Composeru a bez požadavku na Node.js v produkci. - Lokální vývoj: Windows a Laragon. - Produkce: sdílený hosting Webglobe; řešení nesmí vyžadovat trvale běžící proces, worker, WebSocket server, Docker, SSH démon ani vlastní systémovou službu. - Offline-first: App Shell, Service Worker, IndexedDB a synchronizační fronta. Všechny běžné typy záznamů musí jít vytvořit, upravit i připravit ke smazání bez připojení. - Uživatelské rozhraní, validace, chybové zprávy, dokumentace a smysluplné komentáře jsou česky. Technické identifikátory mohou zůstat anglicky. - Nepřidávat závislost ani externí službu bez předchozího zdůvodnění a souhlasu. ## 3. Než se začne měnit kód 1. Přečti tento soubor a relevantní dokumenty v `docs/`. 2. Prozkoumej stávající strukturu, vstupní body, databázové migrace, konfiguraci, testy a způsob nasazení. 3. Ověř skutečné verze PHP a MySQL na cílovém hostingu; pokud nejsou zapsané, označ jejich volbu jako návrh k potvrzení. 4. Najdi všechna použití měněného veřejného rozhraní, databázové struktury nebo datového formátu. 5. U větší nebo nevratné změny nejprve popiš krátký plán, dopady, migraci a návratový postup. 6. Zachovej nesouvisející funkčnost i cizí necommitnuté změny. ## 4. Architektonická pravidla - Zachovej jednu aplikaci a jedno společné datové jádro. Nevytvářej microservices, pluginový systém ani samostatné aplikace pro jednotlivé funkce. - Odděluj prezentační vrstvu, stav a aplikační logiku, lokální úložiště, synchronizaci, HTTP API, doménovou logiku a databázový přístup. - Veřejné API používá JSON, stabilní chybové kódy, ISO 8601 v UTC a jednoznačné identifikátory UUID generované již na klientovi. - Všechny zápisy musí být opakovatelné bez vzniku duplicit. Každá mutace nese unikátní `operation_id`. - Každý synchronizovaný záznam má revizi, čas poslední změny, autora změny a případně náhrobek smazání (`deleted_at`). - Server je autoritou pro oprávnění, členství, přidělení serverové revize a konečný stav synchronizace. Klient je dočasnou autoritou pro lokální rozpracovaná data. - Média se synchronizují odděleně od metadat a jejich integrita se kontroluje hashem. - Přímé URL nesmí obcházet autorizaci médií. - Časová osa je společný pohled nad jednotlivými typy záznamů, nikoli druhá kopie stejných dat. - Generování kronik je reprodukovatelné z uložených dat a konfigurace výběru. Export nesmí měnit zdrojové záznamy. Podrobnosti jsou v [architektuře](docs/ARCHITEKTURA.md), [datovém modelu](docs/DATABAZE.md) a [offline synchronizaci](docs/OFFLINE_SYNC.md). ## 5. Databáze a migrace - Databázi měň výhradně verzovanou migrací. Neměň ručně produkční schéma bez odpovídající migrace. - Migrace jsou dopředné, malé, opakovatelné nebo bezpečně detekují již provedený stav. - Nikdy automaticky nemaž uživatelská data jako vedlejší efekt nasazení. - Destruktivní změna vyžaduje předchozí zálohu, výslovné potvrzení, popsaný dopad a ověřený návratový postup. - Používej InnoDB, `utf8mb4`, cizí klíče, unikátní omezení a indexy odpovídající skutečným dotazům. - SQL dotazy parametrizuj přes PDO. Nikdy neskládej SQL z uživatelského vstupu. - Peněžní, fyzické a časové hodnoty ukládej v jednoznačných jednotkách; výšku v milimetrech, hmotnost v gramech, čas v UTC a lokální kalendářní datum samostatně tam, kde na čase nezávisí. - Změna schématu musí aktualizovat `docs/DATABAZE.md`, exportní formát a případně offline schéma IndexedDB. ## 6. Offline-first a synchronizace - Síť nesmí být podmínkou pro otevření již navštívené aplikace a práci s lokálně dostupnými rodinami. - Uživatelská mutace se nejprve atomicky uloží do IndexedDB spolu s položkou fronty; teprve poté se UI tváří jako uložené. - Stav „uloženo v zařízení“ se nesmí vydávat za „synchronizováno“. - Fronta přežije zavření aplikace, opakuje přenos s exponenciálním zpožděním a bezpečně snese opakované odeslání. - Nepoužívej jako jediný mechanismus Background Sync; na iOS a jiných omezených prohlížečích musí fungovat synchronizace při spuštění, návratu do popředí a ručním pokynu. - Konflikt se nikdy tiše nezahodí. Automaticky lze slučovat jen bezpečně nezávislé změny; jinak uživatel dostane srozumitelnou volbu a obě varianty zůstanou zachované do vyřešení. - Před změnou protokolu synchronizace doplň testy duplicit, změny pořadí, výpadku uprostřed přenosu, konfliktu, smazání a obnovy. ## 7. Bezpečnost a soukromí - Vše je ve výchozím stavu soukromé. Nezaváděj veřejné profily ani veřejně odhadnutelné odkazy. - Každý serverový požadavek ověřuje přihlášení, členství v rodině a oprávnění k cílovému objektu. Oprávnění v UI jsou jen nápověda, nikoli bezpečnostní kontrola. - Role jsou nejméně `owner`, `editor` a `viewer`; přesný rozsah je v `docs/FUNKCE.md` a musí se ověřit na serveru. - Hesla ukládej výhradně pomocí `password_hash()` a ověřuj `password_verify()`; algoritmus ponech na bezpečné výchozí hodnotě PHP. - Používej bezpečné session cookies (`HttpOnly`, `Secure`, `SameSite`), regeneraci ID relace po přihlášení, ochranu CSRF u stavových operací a omezení pokusů o přihlášení. - Vstupy validuj serverově podle whitelistu; výstupy do HTML escapuj podle kontextu. Soubory neposuzuj jen podle přípony nebo klientského MIME. - Povolené formáty, limity, hash, skutečný MIME a rozměry médií kontroluj na serveru. Název souboru generuj; původní název uchovej pouze jako metadata. - Média ukládej mimo veřejný webový kořen, pokud to hosting dovolí. Jinak je chraň serverovou konfigurací a vydávej pouze přes autorizovaný PHP endpoint. - Tajné údaje patří mimo Git a pokud možno mimo veřejný kořen. Do logů nepatří hesla, celé session tokeny, resetovací tokeny ani osobní obsah. - Export, záloha, stažení originálů a správa členů jsou citlivé operace: auditovat je a podle rizika vyžadovat nové ověření heslem. - Neoslabuj bezpečnost kvůli průchodu testů nebo omezení hostingu; omezení nejprve popiš a navrhni bezpečnou variantu. ## 8. Média, export a dlouhodobá archivace - Originál média je neměnný. Náhledy, zmenšeniny a varianty jsou odvoditelné a mohou se znovu vytvořit. - Při importu ukládej SHA-256, velikost, MIME, rozměry/délku, datum pořízení, časové pásmo, autora a vazby na záznamy. - Nikdy nezahazuj originál po vytvoření optimalizované varianty. - Krásná PDF kronika je čitelný redakční výstup. Úplná archivní kronika je přenositelný balíček dat, manifestu, PDF/PDF-A dle ověřených možností a originálních médií v samostatných složkách. - Archivní balíček musí obsahovat verzi formátu, kontrolní součty a lidsky čitelné otevřené formáty (nejméně JSON a CSV tam, kde dává smysl). - Tvrzení o PDF/A, 50leté životnosti nebo bezchybné obnově musí být podloženo validací; jinak jej označ jako návrh nebo cíl. ## 9. Uživatelské rozhraní - **RESPONZIVITA JE POVINNÁ PRO KAŽDOU NOVOU FUNKCI.** Každá nová stránka, komponenta i úprava používá centrální responzivní designový systém Livio. Pevné rozměry textů a tlačítek bez odůvodnění jsou nepřípustné, pokud zhoršují zobrazení na jiných zařízeních. - Při změně rozhraní ověř skutečné vykreslení podle matice v `docs/DESIGN_SYSTEM.md`, včetně orientace na šířku, zvětšení textu a ovládání navigace. - Dodržuj `docs/DESIGN_SYSTEM.md`: krémovo-béžový základ, šalvějově zelené akcenty, přírodní pastelový charakter a logo Livio. - Mobil používá spodní hlavní navigaci; desktop boční navigaci. Obsah na desktopu má maximální šířku 1250 px. - Začni mobilním rozvržením, poté ověř tablet a desktop. Nevytvářej pouhou zmenšenou desktopovou obrazovku. - Všechny ovládací prvky musí být dostupné klávesnicí, mít správný popisek, dostatečný kontrast a dotykovou plochu alespoň 44 × 44 CSS px. - Na výslovné zadání nepoužívej v Livio viditelné zvýraznění fokusu, dokud uživatel neurčí jinak. Zachovej samotný fokus a ovládání klávesnicí. Tlačítka po dotyku na iOS nezobrazují systémový tap highlight. - Respektuj `prefers-reduced-motion`. Pohyb nesmí být nutný k pochopení ani ovládání. - Offline stav, čekající změny, konflikt a chyba synchronizace musí být viditelné, ale nesmí uživatele zbytečně strašit. - Nevytvářej duplicitní komponentu, pokud existuje odpovídající sdílený vzor. - Výchozí generované grafiky mají průhledné pozadí a žádné automaticky přidané zaoblené rohy, pokud uživatel výslovně neurčí jinak. Výjimkou jsou technicky povinné PWA ikony; jejich konkrétní pozadí musí odpovídat schválenému návrhu nebo být potvrzeno uživatelem. - Nové grafiky nyní nevytvářej bez samostatného zadání. ### Závazné pravidlo – všechny hlášky pouze přes toast - Veškerou dočasnou zpětnou vazbu aplikace zobrazuj výhradně prostřednictvím existujícího globálního toast systému. - Platí to pro validační chyby včetně polí `required`, chyby API a sítě, úspěšná potvrzení, upozornění, dokončení akcí i stavové hlášky. - Nezobrazuj hlášku současně v toastu a uvnitř formuláře, karty, dialogu nebo stránky. Nevytvářej inline bannery ani vlastní alternativní oznamovací komponenty. - Zabraň také nativním validačním bublinám prohlížeče; konkrétní zprávu sestav podle popisku pole a zobraz ji v toastu. - Přístupné oznámení zajišťuje toast systém. Dočasné hlášky nevkládej do dalších oblastí `aria-live`. - Toto pravidlo se nevztahuje na běžný trvalý obsah rozhraní, jako jsou nadpisy, popisky polí, instrukce, odpočty a vysvětlující texty, které nejsou výsledkem akce ani stavovou notifikací. ## 10. Kvalita kódu ### Verzování - Každé distribuované vydání má jedinečný číselný build. Před distribucí spusť `php scripts/priprav-vydani.php`. Při změně distribuovaných souborů zvýší build o jeden a uloží jej do `release.json`. - Zobrazená verze patří k právě načtenému vydání. Aktualizace nesmí smazat IndexedDB ani frontu offline operací a nesmí vynutit obnovení rozpracované stránky. - Hlavní vzdálený repozitář je `https://github.com/WassermannCursor/livio.git`, pojmenovaný `origin`. Hlavní větev je `main`. - Před každým commitem zkontroluj změny i přesný seznam připravených souborů. Nikdy neukládej přístupové údaje, rodinná data ani uživatelské fotografie a videa. - Pro průběžné commity používej srozumitelné české popisy. Historii nepřepisuj bez výslovného souhlasu. - Změny odesílej na GitHub podle zadání uživatele. Neukládej automatický push do události při uložení souboru. - Upřednostňuj malé, cílené změny a jasné názvy. Neprováděj nesouvisející refaktoring. - Nepoužívej globální proměnné, inline události, `eval`, dynamické spouštění řetězců ani nebezpečné vkládání HTML. - JavaScript piš s jasnými hranicemi odpovědností a bez implicitních vedlejších účinků. PHP odděluje HTTP vrstvu, autorizaci, validaci, doménové operace a repozitáře. - Chyby nepolykej. Uživateli ukaž bezpečnou českou zprávu, do logu ulož korelační ID a technický kontext bez citlivých dat. - Veškeré datumové a časové chování testuj vůči UTC, místnímu času, letnímu času a událostem bez přesného času. - Nepřepisuj originální média, neupravuj je destruktivně a nepoužívej generativní nástroje k jejich změně bez výslovného zadání. ## 11. Testování a definice hotové změny Podle dopadu spusť a pravdivě zaznamenej: - syntaktickou kontrolu PHP; - automatické testy doménové logiky, autorizace, API a synchronizace; - migraci na čisté databázi i upgrade z podporované předchozí verze; - test offline vytvoření, úpravy, smazání, restartu aplikace a následné synchronizace; - test duplicitní mutace a konfliktu ze dvou zařízení; - kontrolu exportu, manifestu a hashů; - kontrolu přístupnosti a responzivity alespoň na šířkách 360, 768, 1024 a 1440 px; - instalaci PWA, aktualizaci Service Workeru a chování po ztrátě sítě; - základní bezpečnostní testy přístupu k cizí rodině, CSRF, uploadu a session. Změna je hotová pouze tehdy, když: 1. splňuje zadání a související dokumentaci; 2. zachovává stávající data a funkčnost; 3. má odpovídající testy nebo jasně popsaný důvod, proč je nebylo možné provést; 4. obsahuje potřebnou migraci a aktualizaci dokumentace; 5. nezanechává tajné údaje, ladicí výpisy ani nevyřešenou chybu; 6. je ověřena v relevantním online i offline scénáři. ## 12. Dokumentace rozhodnutí - Schválené požadavky zapisuj jako rozhodnutí. - Nejasné varianty zapisuj přesně ve formátu `**Návrh k potvrzení:** ...`; nevydávej je za hotové rozhodnutí. - Po potvrzení návrhu uprav všechny dotčené dokumenty, aby nezůstaly rozpory. - Změna veřejného API, datového modelu, synchronizace, rolí, exportu nebo designových tokenů vždy vyžaduje aktualizaci příslušného dokumentu v `docs/`. ## 13. Závěrečné hlášení Codexu Po významnější práci stručně uveď: 1. co se změnilo; 2. které soubory a části byly dotčeny; 3. jaké kontroly proběhly a s jakým výsledkem; 4. co zůstalo neověřené; 5. jaké existují dopady, rizika nebo kroky uživatele; 6. které položky čekají na potvrzení.