# Datový model Livio ## 1. Cíl a pravidla Datový model podporuje více rodin, více dětí, role členů, chronologickou časovou osu, všechny požadované typy záznamů, média, offline synchronizaci, kroniky, audit a dlouhodobý export. Níže uvedené názvy jsou cílovou specifikací před implementací. Závazná pravidla: - MySQL/MariaDB, InnoDB a `utf8mb4`. - Primární interní klíč může být `BIGINT UNSIGNED`, ale každý synchronizovaný objekt má také stabilní `uuid CHAR(36)` s unikátním indexem. - Klientské UUID se vytvoří offline před prvním odesláním. - Časové okamžiky jsou `DATETIME(6)` v UTC. Kalendářní datum bez času je `DATE`. - Synchronizované tabulky mají `revision BIGINT UNSIGNED`, `created_at`, `updated_at`, `created_by_user_uuid`, `updated_by_user_uuid` a `deleted_at`. - Smazání je nejprve logické. Fyzické vyčištění se řídí schválenou retencí, zálohou a synchronizačními náhrobky. - Osobní text se neukládá do auditního logu ani diagnostických logů. - JSON se používá pouze pro proměnlivá doplňková data, nikoli jako náhrada relací a důležitých indexovaných polí. **Návrh k potvrzení:** zda cílová databáze bezpečně podporuje nativní typ `JSON`. Pokud ne, použije se `LONGTEXT` s aplikační validací JSON. ## 2. Vztahy na vysoké úrovni ```text uzivatele ──< rodina_clenove >── rodiny ──< children │ │ │ │ │ ├──< pregnancies │ │ ├──< birth_records │ │ ├──< growth_measurements │ │ ├──< milestones │ │ ├──< future_letters │ │ └──< record_subjects >── records │ │ │ │ ├──< family_people ├──< record_media >── media │ ├──< family_relationships ├──< trip_details │ ├──< records └──< hospital_stays │ ├──< invitations │ ├──< chronicle_exports │ └──< audit_events │ └── role v databázi: spravce / rodic / host sync_operations + change_log zajišťují idempotenci a přírůstkový pull. ``` ## 3. Společná pole synchronizovaných tabulek Následující pole se použijí u `families`, `children`, `family_people`, `family_relationships`, `records`, specializovaných detailů, `media`, vazeb a nastavení, pokud dokument výslovně neurčí jinak. | Sloupec | Typ | Význam | |---|---|---| | `id` | `BIGINT UNSIGNED` | Interní primární klíč, nevystavuje se jako oprávnění. | | `uuid` | `CHAR(36)` | Globálně stabilní veřejné ID. `UNIQUE`. | | `family_id` | `BIGINT UNSIGNED` | Tenant/rodina; povinné u rodinných dat. | | `revision` | `BIGINT UNSIGNED` | Monotónní revize konkrétního objektu, začíná 1. | | `created_at` | `DATETIME(6)` | Vytvoření na serveru v UTC. | | `updated_at` | `DATETIME(6)` | Poslední potvrzená změna na serveru v UTC. | | `created_by_user_id` | `BIGINT UNSIGNED NULL` | Autor; může zůstat `NULL` po anonymizaci účtu. | | `updated_by_user_id` | `BIGINT UNSIGNED NULL` | Poslední autor změny. | | `deleted_at` | `DATETIME(6) NULL` | Náhrobek logického smazání. | `family_id`, `uuid`, `revision` a `deleted_at` musí být součástí vhodných indexů. Databáze sama nevynucuje každou mezitabulkovou shodu `family_id`; tuto hranici vždy ověřuje aplikační služba v transakci. ## 4. Identity, relace a bezpečnost ### 4.1 `users` | Sloupec | Typ | Omezení / význam | |---|---|---| | `id` | `BIGINT UNSIGNED` | PK | | `uuid` | `CHAR(36)` | `UNIQUE`, veřejné ID | | `email_normalized` | `VARCHAR(254)` | `UNIQUE`, normalizovaný e-mail | | `email_display` | `VARCHAR(254)` | Podoba pro zobrazení | | `password_hash` | `VARCHAR(255)` | Výstup `password_hash()` | | `display_name` | `VARCHAR(120)` | Jméno v aplikaci | | `locale` | `VARCHAR(10)` | Výchozí `cs-CZ` | | `timezone` | `VARCHAR(64)` | IANA zóna, např. `Europe/Prague` | | `email_verified_at` | `DATETIME(6) NULL` | Ověření e-mailu | | `status` | `VARCHAR(20)` | `active`, `blocked`, `pending_deletion` | | `last_login_at` | `DATETIME(6) NULL` | Poslední úspěšné přihlášení | | `created_at`, `updated_at` | `DATETIME(6)` | UTC | E-mail se nepoužívá jako neměnné ID. Změna e-mailu je citlivá operace. ### 4.2 `user_sessions` - `id`, `user_id`, `token_hash`, `created_at`, `last_seen_at`, `expires_at`, `revoked_at`. - Volitelně bezpečně zkrácené informace o zařízení a IP pro správu aktivních relací. - Neukládat surový session token. ### 4.3 `password_reset_tokens` a `email_verification_tokens` - `user_id`, `token_hash`, `created_at`, `expires_at`, `used_at`. - Token jednorázový, krátce platný, v databázi pouze hash. ### 4.4 `families` - společná pole; - `name VARCHAR(160)`; - `slug VARCHAR(100) NULL` pouze pro pohodlnou neveřejnou URL, nikdy jako oprávnění; - `default_timezone VARCHAR(64)`; - `settings_json JSON/TEXT` pro nebezpečnostně nekritické preference. ### 4.5 `rodina_clenove` | Sloupec | Význam | |---|---| | `id` | Interní primární klíč. | | `rodina_id`, `uzivatel_id` | Unikátní dvojice rodiny a uživatele. | | `role` | `spravce`, `rodic`, `host`; odpovídají produktovým oprávněním vlastníka, editora a čtenáře. | | `vztah` | Volitelně `otec`, `matka`, `jiny`. | | `profil_fotografie_klic` | Volitelný soukromý klíč avatara konkrétního uživatele v této rodině, pod `rodiny/{rodina_id}/uzivatele/{uzivatel_id}/profil/`. | | `stav` | `aktivni` nebo `pozastaven`. | | `potvrzen_at` | Čas potvrzení členství v UTC, může být `NULL`. | | `vytvoren_at` | Čas vytvoření členství v UTC. | Rodina musí mít alespoň jednoho aktivního správce. Odebrání posledního správce databáze sama obtížně zajistí; kontroluje je transakční doménové pravidlo. ### 4.6 `family_invitations` - `uuid`, `family_id`, `email_normalized`, `role`, `token_hash`; - `invited_by_user_id`, `created_at`, `expires_at`, `accepted_at`, `revoked_at`; - aktivní pozvánky indexované podle hashovaného tokenu a rodiny. ## 5. Rodina, osoby a děti ### 5.1 `family_people` Obsahuje osoby z rodinné historie, které nemusí mít uživatelský účet. - společná pole; - `linked_user_id BIGINT UNSIGNED NULL`; - `first_name`, `last_name`, `display_name`; - `birth_date DATE NULL`, `death_date DATE NULL`; - `gender VARCHAR(30) NULL` jako volitelné uživatelské označení; - `note TEXT NULL`; - `avatar_media_id BIGINT UNSIGNED NULL`. **Návrh k potvrzení:** přesný způsob zadání pohlaví a příbuzenských označení, aby nebyl zbytečně omezující a zároveň zůstal srozumitelný v češtině. ### 5.2 `family_relationships` - společná pole; - `from_person_id`, `to_person_id`; - `relationship_type VARCHAR(40)` například `parent`, `partner`, `sibling`, `guardian`, `other`; - `label VARCHAR(100) NULL` pro vlastní český popis; - `valid_from DATE NULL`, `valid_to DATE NULL`; - `UNIQUE(family_id, from_person_id, to_person_id, relationship_type, deleted_at)` nelze v MySQL spolehlivě použít s `NULL` pro všechny případy; duplicitu ověřuje i aplikace. Odvozené vztahy (např. prarodič) se pokud možno počítají, neukládají duplicitně. ### 5.3 `children` - společná pole; - `person_id BIGINT UNSIGNED` vazba na `family_people`; - `preferred_name VARCHAR(120)`; - `birth_date DATE NULL`; - `expected_birth_date DATE NULL`; - `birth_timezone VARCHAR(64) NULL`; - `profile_media_id BIGINT UNSIGNED NULL`; - `status VARCHAR(20)` například `expected`, `born`, `adult`, `memorial`; - `privacy_note TEXT NULL` pouze pokud bude mít jasné použití. Citlivé zdravotní údaje se ukládají jen v nezbytném rozsahu a nejsou náhradou zdravotnické dokumentace. ## 6. Časová osa a obecné záznamy ### 6.1 `records` Společný chronologický základ všech událostí. | Sloupec | Typ | Význam | |---|---|---| | společná pole | | UUID, rodina, revize, audit změny | | `record_type` | `VARCHAR(40)` | `pregnancy`, `birth`, `milestone`, `trip`, `hospital`, `growth`, `memory`, `future_letter`, `family_event`, `other` | | `title` | `VARCHAR(220)` | Nadpis | | `body` | `LONGTEXT NULL` | Formátovaný obsah v bezpečně omezeném formátu | | `event_date` | `DATE` | Kalendářní datum pro řazení | | `event_time` | `TIME(6) NULL` | Volitelný místní čas | | `event_timezone` | `VARCHAR(64) NULL` | IANA zóna, pokud existuje přesný čas | | `date_precision` | `VARCHAR(20)` | `day`, `month`, `year`, `approximate`, `range` | | `end_date` | `DATE NULL` | Konec výletu/pobytu/období | | `location_name` | `VARCHAR(220) NULL` | Lidský název místa | | `latitude`, `longitude` | `DECIMAL(...) NULL` | Volitelné; citlivé | | `visibility` | `VARCHAR(20)` | Zatím `family`; budoucí hodnoty až po schválení | | `is_favorite` | `TINYINT(1)` | Oblíbený záznam | | `sort_hint` | `INT` | Stabilní ruční pořadí při shodném datu | Text `body` se doporučuje ukládat jako prostý text s omezenou strukturou, ne libovolné HTML. **Návrh k potvrzení:** lehký formát textu – prostý text s odstavci, nebo omezený Markdown s bezpečným vlastním rendererem. Libovolné HTML není doporučeno. ### 6.2 `record_subjects` - `uuid`, `family_id`, `record_id`, `child_id NULL`, `person_id NULL`; - právě jeden z `child_id`/`person_id` je vyplněn; - `subject_role VARCHAR(30)` například `primary`, `participant`, `author`, `recipient`; - revize a `deleted_at` pro offline synchronizaci; - unikátní živá vazba záznam–subjekt se hlídá aplikačně a vhodným pomocným klíčem. Záznam může patřit více dětem i celé rodině. Pokud nemá subjekt, je rodinný. ### 6.3 `record_tags` a `tags` - `tags`: společná pole, `name`, `color_token NULL`; unikátní normalizovaný název v rodině. - `record_tags`: synchronizovaná vazba `record_id` + `tag_id`. ## 7. Specializované typy záznamů Specializovaná tabulka sdílí UUID nebo má `record_id UNIQUE`. Základní nadpis, datum, text, média a subjekty zůstávají v `records`. ### 7.1 `pregnancies` - `record_id UNIQUE`; - `child_id`; - `pregnancy_start_date DATE NULL`; - `expected_due_date DATE NULL`; - `pregnancy_week SMALLINT UNSIGNED NULL`; - `pregnancy_day TINYINT UNSIGNED NULL`; - `care_provider VARCHAR(220) NULL`; - `notes_private TEXT NULL`. Jednotlivé prenatální události mohou být samostatné `records` typu `pregnancy` a sdílet stejné dítě. ### 7.2 `birth_records` - `record_id UNIQUE`, `child_id UNIQUE` pro hlavní porodní záznam; - `born_at_utc DATETIME(6) NULL`, `born_local_date DATE`, `born_local_time TIME NULL`, `timezone`; - `place_name`, `facility_name`; - `weight_g INT UNSIGNED NULL`, `length_mm INT UNSIGNED NULL`, `head_circumference_mm INT UNSIGNED NULL`; - `birth_story LONGTEXT NULL`; - další zdravotní hodnoty jen po výslovném schválení jejich potřeby. ### 7.3 `growth_measurements` - `record_id UNIQUE`, `child_id`; - `measured_on DATE`; - `age_days INT UNSIGNED NULL` jako odvozená uložená hodnota pro stabilitu, přepočitatelná z data narození; - `weight_g INT UNSIGNED NULL`; - `height_mm INT UNSIGNED NULL`; - `head_circumference_mm INT UNSIGNED NULL`; - `source VARCHAR(30)` například `home`, `doctor`, `other`; - `note TEXT NULL`. Aplikace nevyvozuje zdravotní diagnózy. Referenční percentily, pokud budou přidány, musí mít zdroj, verzi a upozornění. ### 7.4 `milestones` - `record_id UNIQUE`, `child_id`; - `milestone_category VARCHAR(40)` například `movement`, `speech`, `school`, `social`, `custom`; - `custom_label VARCHAR(160) NULL`; - `achieved_on DATE`; - `is_first TINYINT(1)`. ### 7.5 `trip_details` - `record_id UNIQUE`; - `destination VARCHAR(220)`; - `started_on`, `ended_on`; - `transport VARCHAR(100) NULL`; - `accommodation VARCHAR(220) NULL`; - `route_json JSON/TEXT NULL` pouze pokud bude funkce map potvrzena. ### 7.6 `hospital_stays` - `record_id UNIQUE`, volitelně `child_id`; - `facility_name`, `department NULL`; - `admitted_on DATE`, `discharged_on DATE NULL`; - `reason TEXT NULL`, `summary TEXT NULL`; - `sensitivity VARCHAR(20)` s výchozí hodnotou `private_family`. Tato data mohou být zdravotně citlivá. Role `viewer` je dle současného návrhu vidí, protože je člen rodiny; jemnější oprávnění je návrh k potvrzení. ### 7.7 `future_letters` - `record_id UNIQUE`; - `author_person_id NULL`, `author_user_id NULL`; - `recipient_child_id` nebo `recipient_person_id`; - `unlock_at_utc DATETIME(6) NULL`; - `unlock_on_date DATE NULL`; - `sealed_at DATETIME(6) NULL`; - `delivery_status VARCHAR(20)` například `draft`, `sealed`, `unlocked`; - `content_ciphertext LONGTEXT NULL` pouze pokud bude potvrzeno aplikační šifrování; - bez šifrování je obsah v `records.body` a serverově omezen podle data a oprávnění. **Návrh k potvrzení:** skutečně „zapečetěný“ dopis vyžaduje vyřešit, kdo může obsah před odemčením obnovit, zálohovat a dešifrovat. Pouhé skrytí v UI není zapečetění. Do potvrzení se implementuje pouze řízená viditelnost na serveru, ne tvrzení o end-to-end šifrování. ## 8. Média ### 8.1 `media` | Sloupec | Význam | |---|---| | společná pole | rodina, UUID, revize, autor, náhrobek | | `kind` | `photo`, `video`, `audio`, `document`, `other` | | `storage_key` | Neveřejná relativní cesta/klíč, unikátní | | `original_filename` | Pouze metadata pro export a zobrazení | | `mime_type` | Serverem ověřený MIME | | `extension` | Serverem povolená přípona | | `byte_size` | Velikost originálu | | `sha256` | 64 hex znaků, index pro detekci duplikátů v rodině | | `width_px`, `height_px`, `duration_ms` | Technická metadata dle typu | | `captured_at_utc` | Okamžik pořízení, pokud známý | | `captured_local_date` | Datum pro časovou osu | | `captured_timezone` | IANA zóna, pokud známá | | `status` | `pending`, `ready`, `failed`, `quarantined` | | `metadata_json` | Whitelist bezpečných technických údajů | `UNIQUE(family_id, sha256, byte_size)` může pomoci s deduplikací, ale před sloučením se ověří úplný hash a uživatelský význam. Dva záznamy mohou odkazovat na stejné fyzické médium. ### 8.2 `media_variants` - `media_id`, `variant_type` (`thumbnail`, `screen`, `poster`, `transcoded`); - `storage_key`, `mime_type`, `byte_size`, `sha256`, rozměry/délka; - `generator_version`, `created_at`; - `UNIQUE(media_id, variant_type, generator_version)`. Varianty jsou odvoditelné a mohou být smazány a znovu vytvořeny; originál nikoli. ### 8.3 `record_media` - synchronizovaná vazba `record_id`, `media_id`; - `caption TEXT NULL`, `alt_text VARCHAR(500) NULL`; - `sort_order INT`, `is_cover TINYINT(1)`; - `taken_on_override DATE NULL`; - unikátní živá vazba a nejvýše jedna obálka záznamu se kontroluje transakčně. ### 8.4 `upload_sessions` a `upload_parts` - session: UUID, rodina, uživatel, očekávaná velikost/hash/MIME, stav, expirace; - části: session, číslo části, offset, velikost, hash, stav; - po dokončení se dočasné části spojí, ověří a atomicky přesunou do úložiště originálů. ## 9. Kroniky, exporty a zálohy ### 9.1 `chronicle_exports` - `uuid`, `family_id`, `requested_by_user_id`; - `export_type`: `beautiful_pdf`, `archival_bundle`, `data_only`; - `scope_json`: děti, osoby, období, typy a volby; - `source_revision_cursor`: poslední zahrnutá serverová změna; - `status`: `queued`, `building`, `ready`, `failed`, `expired`; - `progress_percent`, `current_step`, `error_code NULL`; - `storage_key NULL`, `byte_size NULL`, `sha256 NULL`; - `format_version`, `created_at`, `completed_at`, `expires_at`, `downloaded_at`. Do `error_code` nepatří osobní obsah ani technický stack trace. ### 9.2 `export_items` - `export_id`, `entity_type`, `entity_uuid`, `entity_revision`; - `path_in_archive NULL`, `sha256 NULL`; - umožní auditovat přesný snapshot a opakovatelně ověřit výsledek. ### 9.3 `backup_runs` Pokud Livio samo řídí doplňkovou zálohu: - `uuid`, `started_at`, `completed_at`, `status`; - počty databázových a mediálních položek, kontrolní hash manifestu; - cílové úložiště jen jako bezpečný identifikátor, ne přístupové údaje; - výsledek testu integrity a případné bezpečné chybové kódy. Hostingová záloha mimo aplikaci nemusí být v této tabulce, ale postup a test obnovy musí být dokumentován. ## 10. Synchronizace a audit ### 10.1 `sync_operations` Zajišťuje idempotenci příchozích mutací. - `operation_id CHAR(36) UNIQUE`; - `family_id`, `user_id`, `device_id`; - `entity_type`, `entity_uuid`, `operation_type`; - `base_revision NULL`, `result_revision NULL`; - `payload_hash CHAR(64)`; - `status`: `accepted`, `conflict`, `rejected`; - `result_json` s bezpečným zopakovatelným výsledkem; - `received_at`, `completed_at`. Opakovaný `operation_id` se stejným hashem vrátí původní výsledek. Stejné ID s jiným hashem je bezpečnostní chyba a požadavek se odmítne. ### 10.2 `change_log` - `sequence BIGINT UNSIGNED AUTO_INCREMENT` jako globální serverový kurzor; - `family_id`, `entity_type`, `entity_uuid`, `entity_revision`; - `change_type`: `upsert`, `delete`; - `changed_by_user_id`, `changed_at`; - volitelně `changed_fields_json` bez osobních hodnot. Index `family_id, sequence` umožní přírůstkový pull. Zápis vzniká ve stejné transakci jako doménová změna. ### 10.3 `devices` - `uuid`, `user_id`, `display_name`, `created_at`, `last_seen_at`, `revoked_at`; - bez invazivního fingerprintingu; - slouží ke správě synchronizace a aktivních zařízení, ne jako jediný autentizační faktor. ### 10.4 `audit_events` - `id`, `uuid`, `family_id NULL`, `actor_user_id NULL`; - `event_type`, `target_type`, `target_uuid NULL`; - `occurred_at`, `correlation_id`, zkrácené síťové/zařízení metadata; - `metadata_json` pouze s whitelistem neobsahujícím osobní text, hesla ani tokeny. Auditovat zejména přihlášení, změny rolí, pozvánky, export, stažení originálů, obnovu, hromadné a fyzické mazání. ## 11. Indexy a omezení Minimální indexy: - každé `uuid` unikátní; - `rodina_clenove(uzivatel_id, stav)` a unikátní `(rodina_id, uzivatel_id)`; - `records(family_id, event_date, sort_hint, uuid)` pro časovou osu; - `records(family_id, record_type, event_date)`; - `record_subjects(child_id, deleted_at, record_id)`; - `growth_measurements(child_id, measured_on)`; - `media(family_id, captured_local_date)` a `(family_id, sha256, byte_size)`; - `record_media(record_id, sort_order)`; - `change_log(family_id, sequence)`; - `sync_operations(operation_id)` unikátní; - `chronicle_exports(family_id, created_at)`. Indexy se po vzniku reálných dotazů ověří pomocí `EXPLAIN`; nevytvářejí se slepě pro každý sloupec. ## 12. Migrace ### 12.1 Formát ```text database/migrations/ ├── 0001_initial_schema.php ├── 0002_add_media_variants.php └── ... ``` Každá migrace má jednoznačné pořadí, popis, kontrolu předpokladů a bezpečný výstup při druhém spuštění. Tabulka `schema_migrations` obsahuje `version`, `name`, `checksum`, `applied_at` a `execution_ms`. ### 12.1.1 Účty a ověření e-mailu První databázová migrace `0001_uzivatele_a_aktivace_uctu` zavádí tabulky `uzivatele` a `aktivace_uctu`. Spouští se pouze ručně z příkazové řádky příkazem `php scripts/migrate.php`; skript načítá databázové údaje z `public/config/config.php` absolutní cestou a při opakovaném spuštění ověřuje kontrolní součet migrace. Neprovádí mazání ani přepis existujících tabulek. Pokud některá cílová tabulka existuje s nekompatibilními sloupci, migrace skončí bez pokusu její strukturu automaticky opravit. E-mail se před uložením validuje a normalizuje oříznutím okolních ASCII mezer a převodem celé adresy na malá písmena. Tečky ani část za znaménkem `+` se nemění. Databázový sloupec používá binární porovnávání; unikátní index proto porovnává přesně normalizovanou hodnotu. Heslo ukládá aplikační vrstva výhradně jako výstup `password_hash()` a ověřuje přes `password_verify()`. Tabulka `aktivace_uctu.kod_hash` ukládá 32 bajtů HMAC-SHA256, nikoliv šestimístný kód ani obyčejný hash. Tajný klíč HMAC je samostatné náhodné tajemství dostupné pouze procesu PHP přes `security.activation_hmac_key` v neveřejně přístupném a z Gitu vyloučeném `public/config/config.php`; nesmí být databázovou hodnotou ani klientským údajem. Vstup HMAC obsahuje verzi, ID uživatele a kód; výsledek se vypočítává v binárním režimu. Aktivační služba generuje přesně šest číslic včetně počátečních nul pomocí `random_int()` a nastavuje platnost 10 minut. Kód ukládá jako binární HMAC-SHA256 s odděleným serverovým klíčem z `public/config/config.php` (`security.activation_hmac_key`). Produkční instalace musí mít vlastní náhodný klíč alespoň 32 bajtů; klíč nesmí být ve verzi, databázi ani klientovi. Vstup HMAC obsahuje verzi, ID uživatele a kód. ### 12.1.2 Registrace a aktivace (Etapa 2) API je v `public/api/v1/auth/`: `session.php` připraví CSRF token a vrátí ověřený stav relace, `register.php` ověří e-mail a heslo a založí pouze účet `ceka_na_overeni`, `resend.php` znovu odešle kód a `verify.php` účet atomicky aktivuje. `login.php` ověřuje přihlašovací údaje proti aktivnímu účtu a jednotně odmítá neplatný, neaktivní i blokovaný účet. E-mail se normalizuje oříznutím okolních mezer a převodem celé adresy na malá písmena; tečky ani část za `+` se nemění. Heslo musí mít 8 až 64 znaků, alespoň jedno velké písmeno, číslici a speciální znak a ukládá se pouze přes `password_hash()`. Ověření zamyká účet a jeho aktivní kódy ve stejné transakci, používá konstantní časové porovnání HMAC, omezuje pokusy na pět pro kód a po pátém chybném zadání zneplatní kód. Formulář dává od potvrzeného odeslání 120 sekund na vložení kódu; server tento limit zachová v registrační relaci, takže obnovení stránky jej nevynuluje. Po limitu UI vymaže vstup a nabídne nový kód. Databázová platnost kódu přesto zůstává 10 minut od vystavení. Opětovné vystavení má 60sekundový limit; starší aktivní kód se zneplatní teprve po potvrzeném `PHPMailer::send()`. Při selhání SMTP zůstává uživatel neaktivovaný a nový neodeslaný kód se zneplatní. Pokud SMTP zprávu přijme, ale databázové potvrzení selže, API stav označí jako neověřený a neprohlašuje odeslání za potvrzené. Omezení četnosti se vedou v uzamčených souborech v dočasném adresáři serveru a při jejich nedostupnosti API selže bezpečně. Odpovědi API jsou `no-store`; Service Worker požadavky pod `/api/` ukládání do cache vynechává. Registrační heslo ani aktivační kód se neukládají do IndexedDB, `localStorage`, `sessionStorage` ani offline fronty. Serverová relace pro registrační proces uchovává interní ID čekajícího účtu, stav a čas procesu a CSRF token; heslo ani kód v ní nejsou. Tato etapa nemění schéma databáze a neimplementuje přihlášení, řízení přístupu k rodinám ani průvodce rodinou. Po aktivaci účet zatím není automaticky přihlášen. ### 12.1.3 Systémová role účtu Migrace `0002_systemova_role` přidává do `uzivatele.systemova_role` hodnoty `uzivatel`, `administrator` a `vyvojar`, s `NOT NULL` a databázovým `DEFAULT 'uzivatel'`. Migrace `0011_systemova_role_tester` bezpečně rozšiřuje tento výčet o `tester`, aniž by měnila role existujících účtů. Při přidání sloupce MariaDB doplní výchozí hodnotu i existujícím řádkům. Veřejná registrace roli nepřebírá z požadavku klienta a do INSERTu zapisuje pevně `uzivatel`. Role samy o sobě nepřidělují přístup k rodinným datům; role `tester` také neposkytuje administrátorská oprávnění. ### 12.1.4 Přihlášení a dlouhodobá relace Migrace `0003_uzivatelske_relace` vytváří `uzivatelske_relace` pro bezpečné obnovení přihlášení. Ukládá pouze SHA-256 hash náhodného 256bitového tokenu, ID uživatele, časy vytvoření a poslední aktivity, expiraci a případné zneplatnění. Surový token je pouze v `HttpOnly`, `Secure` na HTTPS a `SameSite=Strict` cookie. Při zapnutí „Zůstat přihlášen“ je relace platná nejvýše jeden rok od poslední ověřené aktivity; ověřený požadavek ji může nejvýše jednou denně prodloužit o další rok. Nejde o nekonečně platný token: po roce bez ověřeného použití expiruje a server jej lze kdykoli odvolat. Při odhlášení nebo výměně zapamatované relace se její záznam smaže. Migrace `0004_index_uklidu_relaci` přidává index pro efektivní dávkové mazání zneplatněných a expirovaných relací. Při prvním přístupu k databázi autentizačního API probíhá úklid nejvýše jednou za 24 hodin, pokud se podaří získat procesní zámek v dočasném adresáři. V jedné dávce smaže maximálně 10 000 záznamů každého typu, aby úklid nezdržoval běžné požadavky; další dávky proběhnou při následujících denních spuštěních. Úklid neovlivňuje platné tokeny. Při vypnutém „Zůstat přihlášen“ používá aplikace relaci prohlížeče a po 15 minutách neaktivity ji server i otevřená aplikace ukončí. Klientská aktivita se průběžně potvrzuje API; heslo ani přihlašovací stav se neukládají do `localStorage`, `sessionStorage`, IndexedDB ani Service Worker cache. Při nedostupném serveru nebo HTTP 5xx se již ověřená obrazovka nepřesměruje sama na přihlášení; stav zůstává označen jako neověřitelný. HTTP 200 s nepřihlášeným stavem nebo HTTP 401 se naopak považují za skutečně odmítnutou relaci. Veřejné přihlášení přijímá pouze aktivní účet a chybný e-mail, heslo, čekající ověření i blokovaný účet dostávají stejnou obecnou odpověď. Po úspěšném přihlášení klient ověří členství a stav průvodce dříve, než vykreslí Přehled. Případné změny schématu se aplikují výhradně ručně přes stávající `php scripts/migrate.php`. Při startu jsou login i Přehled skryté, dokud `session.php` neověří účet. Aplikace pak provede jediný přechod přímo na cílovou obrazovku. Dočasný výpadek serveru se nebere jako neplatná relace: při běžícím přihlášeném běhu se uživatel automaticky neodhlásí; při studeném offline startu se identita bez ověření nepředstírá a zapamatovaný token se nemaže. ### 12.1.5 Jméno a příjmení uživatele Migrace `0005_jmeno_a_prijmeni_uzivatele` přidává do tabulky `uzivatele` volitelné sloupce `jmeno` a `prijmeni`, oba typu `VARCHAR(100) NULL`. Dosavadní účty a data zůstávají zachovány; nová pole mohou být nevyplněná. Migrace ověřuje, že oba sloupce buď chybí, nebo již existují ve správném tvaru. Při částečném či nekompatibilním stavu se zastaví bez automatického přepisování. ### 12.1.6 Rodiny Migrace `0006_rodiny` vytváří tabulku `rodiny` se stavem `aktivni` nebo `archivovana`, zakladatelem z tabulky `uzivatele` a automatickými časovými značkami. Vazba na zakladatele používá `ON DELETE RESTRICT` a `ON UPDATE RESTRICT`; zakladatelův účet tedy nelze smazat nebo přejmenovat klíč, dokud na něj rodina odkazuje. Migrace zachová již existující tabulku jen tehdy, pokud její ověřená struktura odpovídá očekávání; nekompatibilní tabulku automaticky nepřepisuje. ### 12.1.7 Členové rodiny Migrace `0007_rodina_clenove` vytváří tabulku `rodina_clenove`. Členství používá role `spravce`, `rodic` a `host`, volitelný vztah `otec`, `matka` nebo `jiny` a stav `aktivni` či `pozastaven`. Jedna dvojice rodiny a uživatele může existovat pouze jednou. Obě vazby používají `ON DELETE RESTRICT` a `ON UPDATE RESTRICT`; migrace existující nekompatibilní tabulku automaticky nepřepisuje. ### 12.1.8 Pozvánky do rodiny Migrace `0008_rodina_pozvanky` vytváří tabulku `rodina_pozvanky` pro evidenci pozvánek včetně bezpečně uloženého hashe kódu, expirace, počtu pokusů, stavu odeslání a přijetí a volitelného účtu, který pozvánku přijal. Tabulka odkazuje na rodinu, zvoucího uživatele a případného příjemce; všechny tři cizí klíče používají `ON DELETE RESTRICT` a `ON UPDATE RESTRICT`. Migrace ověřuje existující strukturu, indexy, kolaci e-mailu a pravidla vazeb a nekompatibilní tabulku nepřepisuje. Migrace `0018_bezpecne_predani_klice_pozvankou` a `0019_sifrovane_tajemstvi_pozvanky` přidávají sloupce přenosového obalu. Klient vygeneruje náhodné 256bitové QR tajemství, odvodí z něj klíč HKDF-SHA256 a rodinný klíč zašifruje AES-256-GCM s AAD svázaným s rodinou a pozvánkou. Databáze ukládá hash QR tajemství, šifrovaný rodinný klíč a QR tajemství samostatně zašifrované společným rodinným klíčem. Čitelná hodnota QR není součástí API požadavku ani e-mailu. Opětovné sestavení QR probíhá v prohlížeči z obalu a odemčeného rodinného klíče. PHP nezná klíč k rozšifrování těchto obalů. ### 12.1.9 Průvodce založením rodiny a pozváním rodiče Migrace `0009_rodinny_pruvodce` přidává do `rodiny.zakladatel_operation_id` jedinečný identifikátor opakování založení a do `rodina_clenove.pruvodce_dokoncen_at` čas dokončení úvodního průvodce. U existujících členství vyplní čas dokončení z `potvrzen_at` nebo `vytvoren_at`, aby se již založené rodiny znovu neotevíraly v průvodci. Migrace nic nemaže a při existujících sloupcích ověřuje jejich tvar. Po přihlášení serverové API ověří členství dříve, než klient zobrazí Přehled. Účet bez rodiny dostane volbu založit rodinu nebo zadat pozvánkový kód; chyba serveru se nesmí zaměnit za stav bez členství. Rozpracované údaje průvodce jsou uloženy lokálně pouze v šifrovaném úložišti vázaném na účet; pozvánkový kód se do něj neukládá. Zakladatel zadá jméno, příjmení, vztah (`otec`/`matka`) a název rodiny. Operace založení je svázána s UUID, takže opakování stejného kroku nevytvoří další rodinu. Jméno a příjmení se ukládají do existujících sloupců uživatele a vztah do členství. Pozvánka používá stávající tabulku `rodina_pozvanky`: server generuje přesně šest číslic pomocí `random_int()`, do databáze ukládá pouze HMAC-SHA256 hash kódu s tajemstvím centrální konfigurace, nastaví platnost 14 dnů a limit pěti chybných pokusů. E-mail obsahuje pouze kód. První rodič připraví šifrovaný předávací obal a QR s náhodným 256bitovým tajemstvím na klientovi. Původní QR se před odesláním uloží do IndexedDB šifrovaně neexportovatelným klíčem zařízení, takže jej lze na stejném zařízení opakovaně zobrazit i po restartu PWA bez seedu. Server uchovává jen ověřovací hash QR tajemství a šifrovaný rodinný klíč; čitelný QR payload není součástí požadavku. Nová registrace rodiče přes QR nejprve vyžaduje QR a e-mailový kód, poté vytvoří účet ve stavu čekajícím na ověření. Dokončovací endpoint v jedné transakci aktivuje účet, ověří jeho e-mail kódem, vytvoří členství a vlastní obnovovací obal stejného rodinného klíče, označí pozvánku jako přijatou a odstraní její přenosové ciphertexty. Opakované přijetí je blokováno stavem pozvánky. SMTP používá existující PHPMailer a centrální konfiguraci. API průvodce a správy pozvánek: `family-status`, `family-profile`, `family-create`, `family-invite-prepare`, `family-invite-send`, `family-invite-list`, `family-invite-verify`, `family-invite-accept`, `family-invite-register` (ověření pozvánky, příprava čekajícího účtu a atomické dokončení registrace), `family-finish` a `family-invite-cancel` pod `public/api/v1/auth/`. Odpovědi se necachují; zápisy ověřují session a CSRF a používají parametrizované dotazy. QR dekodér `jsQR` je součástí lokálních aktiv aplikace, takže skenování obrázku nevolá externí službu. ### 12.1.10 Rodinné šifrovací klíče Migrace `0015_rodinne_sifrovani` přidává `rodiny.e2ee_pozadovano` a stav kryptografického propojení `rodina_clenove.e2ee_stav`. Tabulka `rodina_sifrovani` eviduje stav a verzi formátu, `rodina_sifrovaci_klice` verze rodinných klíčů a `rodina_klice_obnovy` samostatný šifrovaný obal pro každého rodiče. Obal obsahuje AES-GCM ciphertext, náhodný salt a nonce; rodinný klíč ani obnovovací fráze se v databázi neukládají čitelně. Klíč vzniká v prohlížeči z 256 náhodných bitů. Každý rodič vytvoří vlastní 12slovnou BIP-39 English frázi (128bitová entropie a checksum) a vlastní obnovovací obal stejného rodinného klíče. Z fráze se přes PBKDF2-HMAC-SHA512 a HKDF-SHA256 odvodí AES-256-GCM klíč; AAD váže obal na rodinu, uživatele a verzi. Čitelná fráze se po prvotním zobrazení a ověření zahodí. Pro běžný návrat na autorizované zařízení se rodinný klíč uloží ještě jednou, zašifrovaný neexportovatelným AES-GCM klíčem zařízení v IndexedDB. Po ověření přihlášení a členství jej klient může odemknout bez seedu. Tento klíč není vázán na hardwarový bezpečnostní prvek: stejný původ aplikace jej může používat a napadený skript stejného původu by mohl žádat o dešifrování. Vymazání IndexedDB, přechod na nové zařízení nebo poškození lokálního klíče vyžaduje obnovu vlastním seedem; serverový přístup k lokálnímu klíči neexistuje. Migrace `0016_rodinne_e2ee_prf` a tabulky `rodina_klice_prf_obnovy` a `rodina_e2ee_propojeni` zůstávají kvůli kompatibilitě a zachování případných záznamů. Tabulky PRF klient nepoužívá; starší čekající ECDH požadavky lze dokončit původním ověřeným postupem. Migrace 0016 aktivovala požadavek pouze pro nezašifrovanou rodinu ID 1, pokud neexistoval její záznam šifrování, a označila její aktivní rodiče jako čekající. Migrace se nevrací zpět a žádné účty, rodiny ani existující kryptografické záznamy se nemažou. Hosté rodinný klíč nedostávají. Média a rodinný obsah zůstávají v této etapě nezašifrované. Nová pozvánková cesta předává stejný rodinný klíč lokálně přes QR a e-mailový kód; starší čekající požadavky v `rodina_e2ee_propojeni` si ponechávají svůj původní ECDH P-256 postup. Nejde o šifrování rodinných metadat ani médií, která zůstávají nešifrovaná. Migrace `0017_rodicovsky_obnovovaci_seed` přidala nullable sloupec `rodina_clenove.obnovovaci_frase_pripravena_at`. Předchozí klient v něm evidoval pouze dokončení samostatného seedového kroku, který nevytvářel obnovovací obal rodinného klíče. Současná aplikace tento sloupec ignoruje; záznamy a migrace se ponechávají kvůli zachování historie a bez nutnosti odstraňovat data. ### 12.1.11 Rodinný kredit, tarify a evidence R2 Migrace `0010_rodinny_kredit_tarify_a_uloziste` přidává katalog `livio_tarify`, rodinné peněženky `rodina_kredit`, neměnný účetní deník `rodina_kredit_transakce`, evidenci pokusů o dobití `rodina_kredit_dobiti`, cenové snímky období `rodina_tarif_obdobi`, aktuální a plánovaný tarif `rodina_tarif_aktivni`, stav inventury R2 `rodina_uloziste_stav`, rezervace kapacity `rodina_uloziste_rezervace` a audit změn ceníku `livio_tarif_audit`. Katalog se počátečně naplní tarify FREE (1 GiB, 0 Kč), L10 (10 GiB, 29 Kč), L20 (20 GiB, 49 Kč) a L50 (50 GiB, 79 Kč). Migrace idempotentně založí nulový kredit, prefix `rodiny/{id}/` a neomezené období FREE pro existující rodiny, které ještě nemají aktivní období. Založení nové rodiny inicializuje tytéž záznamy uvnitř transakce založení; průvodce se nemění. Zakoupená období ukládají cenu, název i limit jako neměnný snímek, takže změna katalogu nemění historii. Rodinné API pod `public/api/v1/billing/` kontroluje členství a oprávnění, zobrazuje tarif/kredit/úložiště, umožňuje čerpat existující kredit na tarif a plánovat další tarif po skončení placeného období. Kredit nelze připsat z klienta; bez důvěryhodného poskytovatele plateb je dobíjení vypnuté. Tarify se spravují vytvořením, úpravou, skrytím nebo archivací. Fyzické mazání není zpřístupněno. Inventura R2 používá serverové S3 podepisování ListObjectsV2 s přesným rodinným prefixem a stránkováním. Výsledek přepíše uložené počty pouze po kompletní úspěšné inventuře; poslední platné hodnoty zůstávají při chybě zachované. Přehled lze při offline oprávnění zobrazit ze šifrovaného lokálního snímku. V aktuálním projektu zatím není uploadové API; tabulka rezervací sama o sobě uploady neomezuje. Limit při nahrávání proto zůstává neimplementovaný do doby, než bude k dispozici uploadová cesta. Platformový souhrn v administrátorském a vývojářském režimu menu poskytuje `GET public/api/v1/billing/platform-storage.php`. Server jej povoluje jen systémovým rolím `administrator` a `vyvojar` a sečte poslední evidované hodnoty všech rodin včetně archivovaných. Neprovádí hromadné skenování R2; odpověď uvádí počet rodin bez měření nebo se zastaralým měřením (starším než 15 minut), takže neúplný součet není vydáván za aktuální. Běžný režim Livio nadále zobrazuje pouze úložiště právě vybrané rodiny. Migrace `0010` byla provedena v databázi Livio. Ověření/skutečné fyzické mazání tarifů vyžadovalo dodatečnou migraci rozšiřující enum auditu; tato migrace nebyla provedena, protože ji automatická kontrola vyhodnotila jako potenciálně nevratnou. Pro zachování bezpečného rozsahu se fyzické mazání tarifů nepoužívá a doporučuje se archivace. #### 12.1.11 Ruční bankovní dobíjení rodinného kreditu Migrace `0012_rucni_bankovni_dobiti` rozšiřuje existující `rodina_kredit_dobiti`; nezakládá druhou peněženku ani nový účetní deník. Přidává unikátní variabilní symbol, způsob platby, identifikaci potvrzujícího a zamítajícího uživatele, časy zamítnutí a zrušení a poznámku administrátora. Stav žádosti rozšiřuje o `potvrzena` a `zamitnuta`, přičemž zachovává existující stavy i historická pole platebního poskytovatele. Historické žádosti se automaticky nepřeklasifikují. Nová žádost má stav `ceka`, bankovní způsob platby, náhodný desetimístný variabilní symbol a klíč idempotence vytvořený z UUID operace klienta. V rámci transakce se uzamkne rodinná peněženka, takže může být současně otevřena nejvýše jedna čekající bankovní žádost na rodinu. Rodič může zrušit jen vlastní čekající žádost. Administrátor nebo vývojář ji může ručně potvrdit či zamítnout. Potvrzení uzamkne žádost a peněženku, ověří čekající stav a následně v jedné transakci navýší zůstatek, vloží účetní záznam s jedinečným klíčem `manual-bank-topup-{id}` a spojí jej s žádostí. Druhé či souběžné potvrzení již stav žádosti nesplní, takže nemůže připsat kredit znovu. Zamítnutí kredit nemění. Vytvoření žádosti ani QR kódu kredit nepřipisuje. Bankovní údaje se načítají ze serverové sekce `payments` v centrální konfiguraci. Číslo účtu, kód banky, IBAN a příjemce musí provozovatel vyplnit; aplikace žádné údaje nevymýšlí. QR obsahuje český formát QR Platba/SPD, částku CZK a variabilní symbol a vykresluje se lokálně bez externí služby. Dokud nejsou platební údaje kompletní, vytvoření žádosti je vypnuté. Migrace `0012` byla provedena přes `php scripts/migrate.php` v databázi nastavené pro tento projekt. Následná kontrola potvrdila nové sloupce, unikátní index variabilního symbolu, vazby na potvrzujícího/zamítajícího uživatele a evidenci migrace. Před migrací ani po ní nebyly v tabulce žádosti o dobití; žádný kredit ani historický záznam se nezměnil. Staré sloupce `poskytovatel` a `externi_platba_id` zůstaly zachované. ### 12.1.12 Osobní profil uživatele Migrace `0013_osobni_profil` přidává do `uzivatele` volitelné `datum_narozeni DATE NULL` a dočasný migrační sloupec `profil_fotografie_klic VARCHAR(512) CHARACTER SET ascii COLLATE ascii_bin NULL`. Původní klíče pod `uzivatele/{id}/profil/` se z tohoto sloupce bezpečně přesouvají migrací `0014`; sloupec zůstává zachován, ale po ověřeném přesunu se vyprázdní. Matka/Otec zůstává výhradně hodnotou `rodina_clenove.vztah` konkrétního aktivního členství, nikoli systémovou rolí uživatele. Migrace `0014_rodinne_fotografie_profilu` přidává `rodina_clenove.profil_fotografie_klic VARCHAR(512) CHARACTER SET ascii COLLATE ascii_bin NULL`. Pro každou existující profilovou fotografii vytvoří kopii v rodinném prefixu každého členství. Před aktualizací odkazu ověří, že kopie v R2 má shodný SHA-256 a rozměr 512 × 512 px. Původní objekt odstraní až po ověření všech kopií; při chybě lze migraci bezpečně opakovat. Členství bez rodiny nelze do rodinného prefixu přesunout, proto jeho původní objekt migrace zachová. Migrace `0014` byla provedena. U jednoho existujícího databázového odkazu se původní objekt v R2 nepodařilo najít ani pod původním klíčem, ani v jeho uživatelském profilovém prefixu. Migrace proto zachovala tento odkaz a žádný objekt nesmazala. Jde o již chybějící soubor, který bude potřeba znovu nahrát, pokud má být profilová fotografie obnovena. Osobní profil obsluhuje přihlášené API pod `public/api/v1/account/`. Zápis jména, příjmení, data narození a případné změny vztahu zůstává na účtu/členství; klíč profilové fotografie je však uložen pro konkrétní rodinu a uživatele. Objekty patří pod `rodiny/{rodina_id}/uzivatele/{uzivatel_id}/profil/`; načtení fotografie vždy ověřuje aktivní členství k rodině z požadavku. Nový objekt se nejprve nahraje, následně se v transakci aktualizuje klíč konkrétního členství a až po potvrzení se zkusí odstranit předchozí objekt stejné rodiny. Rodinná média mají používat `rodiny/{rodina_id}/media/fotografie/` a `rodiny/{rodina_id}/media/videa/`. Uploadové API médií zatím není implementované. Celková inventura již používá prefix `rodiny/{rodina_id}/`, takže zahrnuje profilové fotografie i budoucí rodinná média. Migrace `0013_osobni_profil` byla provedena v databázi Livio přes `php scripts/migrate.php`; ověřeny byly oba sloupce, jejich nulovatelnost, kódování klíče a záznam migrace `0013`. ### 12.2 Pravidla změn - Preferovat rozšířit → naplnit → přepnout čtení/zápis → později odstranit. - U velké tabulky nepředpokládat, že `ALTER TABLE` je okamžitý. - Před `NOT NULL` nejprve doplnit data a ověřit je. - Před změnou významu pole zachovat kompatibilitu s předchozím klientem alespoň po dobu řízené aktualizace. - Změnu IndexedDB a serveru navrhnout jako jeden verzovaný kompatibilní přechod. - Rollback databáze nesmí předstírat bezpečnost, pokud by ztratil data; v takovém případě je návratem obnova zálohy a starší aplikace. ## 13. Retence a fyzické mazání Logické smazání umožňuje synchronizaci a obnovu. Fyzické mazání musí respektovat: - koš viditelný vlastníkovi; - všechna známá zařízení nebo dostatečně dlouhou životnost náhrobku; - zálohovací politiku; - vazby v exportech a auditní povinnosti; - explicitní potvrzení u smazání celé rodiny nebo účtu. **Návrh k potvrzení:** koš 90 dnů, synchronizační náhrobky nejméně 1 rok, dočasné exporty 7 dnů, bezpečnostní audit 2 roky a zálohy podle samostatné retenční matice. Jde o provozní návrh, nikoli schválené hodnoty. ## 14. Exportní datový formát - UTF-8 bez BOM pro JSON; CSV s UTF-8 a jednoznačně popsaným oddělovačem. - Časy ISO 8601 UTC a samostatná časová zóna, datumy `YYYY-MM-DD`. - UUID místo interních ID; relace přes UUID. - Každá entita obsahuje `schema_version`, `uuid`, `revision`, `created_at`, `updated_at`, případně `deleted_at`. - Manifest uvádí počty, názvy souborů, velikosti a SHA-256. - Import budoucího archivu nesmí slepě důvěřovat obsahu; ověří schéma, hashe, limity, oprávnění a konflikt UUID. ## 15. Návrhy k potvrzení 1. Přesná verze MySQL/MariaDB a podpora `JSON`, check constraints a dalších funkcí. 2. Formát bohatšího textu záznamů. 3. Jemnější viditelnost zdravotních záznamů mezi členy rodiny. 4. Skutečné kryptografické zapečetění dopisů do budoucna. 5. Retence koše, náhrobků, auditu, exportů a záloh. 6. Limity médií a kvóta rodiny. 7. Zda se mapa a přesné GPS souřadnice stanou součástí první verze.