ePersonal

# ePersonal 0.1.0 Evidence zaměstnanců pro eLoader, vydání 17. 9. 2026. **První verze k ověření na testovací instalaci.** Balíček obsahuje aplikaci, SQL schéma, české a anglické rozhraní, synchronizační adaptér isEDU a testy. Nepřepisuje zdrojové soubory eLoaderu ani isEDU. Neobsahuje skutečné zaměstnance, hesla, databázové připojení ani šifrovací klíč. ## Co je implementováno | Oblast | Funkce | | --- | --- | | Zaměstnanci | Osobní číslo, jméno, příjmení, tituly, aktivní/neaktivní/archivovaný stav, oddělení, pracovní pozice; hledání a stránkování. | | Osobní karta | Rodné jméno i rodné příjmení, rodné číslo, datum a místo narození, občanství, adresa, zdravotní pojišťovna a její kód, data zaměstnání a interní poznámka. | | Kontakty | Více e-mailů a telefonů s popisem; hlavní kontakt, u e-mailu také záložní. | | Bankovní účty | Více účtů, označení hlavního, majitel, země, měna, tuzemský formát, IBAN, BIC/SWIFT a poznámka. Kontrola IBAN; převod českého účtu na IBAN a zpět. | | Životopis | Formulářové přidávání vzdělání, zaměstnání, kurzů, certifikátů, jazyků, dovedností a dalších položek; období, organizace, popis a pořadí. | | Díla a publikace | Knihy, články, studie, kapitoly, zprávy a jiné výstupy; název, autoři, rok, vydavatel/časopis, ročník, číslo, strany, ISBN, ISSN, DOI a odkaz. | | Fotografie | Nahrání JPEG/PNG/WebP do 5 MiB, zmenšení, vytvoření náhledu a uložení nového JPEG bez původních metadat. | | Tisk | Tiskové HTML životopisu a publikací; uložení do PDF je funkcí prohlížeče, nikoli serverový PDF export. | | isEDU | Potvrzované párování se studentem a/nebo lektorem; výběr sdílených polí, obousměrné změny, řešení konfliktů a zrušení vazby bez smazání osoby v isEDU. | | Správa | Historie operací bez ukládání osobních hodnot do logů; pauza synchronizace, ruční synchronizace, CLI worker. | Rozhraní přebírá jazyk a motiv eLoaderu; otestována vykreslení CZ/EN a motivy academic-blue, b-w a ea. Nejde o mzdový systém. Přístup v tomto vydání má **jen superadmin eLoaderu**; zaměstnanec nezíská přihlášení samotným založením ani spárováním. ## Požadavky a kompatibilita - PHP 8.2 až 8.x: PDO MySQL (`pdo_mysql`), Sodium, Fileinfo, GD a Mbstring. Pro WebP je nutná jeho podpora v GD. Webové PHP i CLI pro cron musí mít odpovídající rozšíření. - eLoader SDK 1; manifest povoluje eLoader `>=1.16.0 <2.0.0`. Skutečné třídy ověřeny z 1.16.0, nikoli nasazení 1.23.0. Novější společná navigace se použije pouze při dostupnosti příslušné metody SDK; jinak se zobrazí navigace aplikace. - MySQL/MariaDB s InnoDB, utf8mb4, transakcemi a pojmenovanými zámky. Cílové prostředí: MySQL 8 nebo MariaDB 10.6+. Konkrétní databázové sestavení ověřte před ostrým provozem; zde nativní server nebyl dostupný. - HTTPS. ePersonal vyžaduje správně nastavené serverové `HTTPS`; nedůvěřuje libovolnému klientskému `X-Forwarded-Proto`. Za reverzní proxy nastavte tuto informaci bezpečně na hostingu. - Zapisovatelný privátní datový adresář aplikace z `Context::dataPath()`; nemá být veřejně dostupný. Změna hostingu/PHP limitů není součástí aplikace. **Synchronizace 0.1.0 pracuje ve stejné skutečné MySQL databázi jako isEDU.** V eLoaderu přidělte ePersonal totéž spojení jako isEDU. Samotný shodný název databáze na jiném serveru nestačí. Důvodem je společná transakce pro jeden synchronizovaný pár. Samostatná evidence funguje i bez isEDU; synchronizace mezi oddělenými databázemi ani vzdálenými instalacemi není součástí tohoto vydání. Adaptér odpovídá isEDU **0.3.11, schéma 5**. Kontroluje tabulky a sloupce. Při jiné verzi schématu synchronizaci odmítne; nedoplní neznámé sloupce odhadem. Pouhá přítomnost tabulek v databázi nenahrazuje správné přidělení aktuálního spojení správcem; nepřipojujte aplikaci na starou kopii isEDU. ## Instalace přes eUpdate a eLoader 1. Na eUpdate vytvořte projekt **ePersonal**, identifikátor `epersonal`. Publikujte `epersonal-0.1.0.zip` jako verzi `0.1.0`, balíček `release` s cílem `eloader_app`. `install.json` je v kořeni ZIPu; balíček znovu nevnořujte do složky. Zachovejte identitu a požadavky manifestu. 2. V eLoaderu nainstalujte aplikaci přes odkaz eUpdate a případný secretID. Alternativně lze stejný ZIP nahrát do instalátoru aplikací ručně. Nejde o aktualizaci jádra eLoaderu. 3. V centrální konfiguraci databází přidělte ePersonal funkčné MySQL spojení. Pro párování vyberte stejné jako u isEDU. Otevřete ePersonal jako superadmin a potvrďte vytvoření evidence. Instalační krok vytváří pouze devět tabulek s prefixem `epersonal_` a privátní klíč. 4. Založte nejprve testovací osobu; ověřte kontakty, bankovní účet, fotografii a párování s testovací osobou isEDU. Teprve po akceptační kontrole v `docs/OVERENI.md` použijte skutečná data. Databázový uživatel potřebuje běžná oprávnění SELECT/INSERT/UPDATE/DELETE nad vlastními tabulkami, pro instalaci CREATE a tvorbu cizích klíčů (podle serveru REFERENCES). Pro synchronizaci navíc SELECT nad odpovídajícími tabulkami isEDU a UPDATE nad `isedu_students`, `isedu_lectors` a `isedu_people`. Aplikace potřebuje vidět jejich metadata v information_schema. Nepoužívejte zbytečně globální databázová oprávnění. Balíček nebyl z tohoto prostředí publikován na eUpdate ani instalován na produkční server. ## Použití evidence V přehledu zvolte **Přidat zaměstnance**. Povinné je jméno a příjmení. Nevyplněné osobní číslo dostane náhodný identifikátor `EP-...`; lze zadat vlastní. Přehled standardně filtruje aktivní osoby, proto pro neaktivní vyberte stav **Vše**. V kartě jsou záložky Osobní údaje, Kontakty, Bankovní účty, Životopis, Díla a publikace, isEDU a Historie. Formulářem lze každý opakovaný záznam přidat, upravit nebo po potvrzení odstranit. Kód a název pojišťovny jsou editovatelné; nejde o napojení na aktuální číselník pojišťoven. U českého účtu lze zadat např. `19-2000145399/0800`; aplikace dopočítá `CZ6508000000192000145399`. Při vyplnění obou tvarů musí odpovídat. Kontrola ověřuje formát a kontrolní číslice, nikoli existenci účtu ani jeho majitele. Pro zahraniční účet lze uvést IBAN/BIC, měnu a zemi; země se neodvozuje ze státního občanství zaměstnance. Rodné číslo má pouze kontrolu zápisu 9/10 číslic s případným lomítkem. Nejde o ověření vydání čísla ani úplnou historickou kontrolu jeho platnosti. Z tohoto údaje se automaticky neodvozuje pohlaví ani datum narození. Tisk životopisu zahrnuje kontakty, vzdělání/praxi a publikace. Neobsahuje rodné číslo, bankovní účty, pojišťovnu, adresu ani interní personální poznámku. Samostatný upload hotového CV, dokumentů publikací nebo pracovních smluv není v tomto vydání implementován; životopis i díla se vyplňují formuláři. ## Spárování s isEDU V kartě otevřete **isEDU**, vyberte Student nebo Lektor a vyhledejte osobu podle ID, jména nebo e-mailu. Vyhledávání vrací nejvýše 50 kandidátů; shoda jména sama osobu nespáruje. Otevřete porovnání, vyberte společná pole a u rozdílných hodnot zvolte počáteční zdroj. Nakonec potvrďte, že jde o tutéž osobu. **Student:** jméno, příjmení, tituly, hlavní a záložní e-mail, hlavní telefon, datum/místo narození, rodné číslo a adresní pole, pokud je zvolíte. **Lektor:** jméno, příjmení, tituly, hlavní e-mail a telefon. Taková jsou společná pole ověřené struktury isEDU 0.3.11; ostatní se nesdílejí jen podle podobného názvu. Výchozí výběr obsahuje pouze jméno, příjmení, tituly a hlavní kontakty. Rodné číslo, narození a adresa vyžadují zvláštní výběr. Pole `firstname_p`/`surname_p` studenta nejsou rodná jména: nejsou proto mapována. Bankovní účty, pojišťovna, poznámky a fotografie zůstávají v ePersonal. Vazba je na stabilní UUID osoby isEDU, nikoli jen na číslo studenta. Po přečíslování se sleduje původní UUID; znovu použité číselné ID se nepřiřadí jiné osobě. Zaměstnanec může být studentem i lektorem. Stejná osoba isEDU nemůže být přiřazena dvěma různým zaměstnancům. ### Jak se řeší změny Aplikace porovnává obě aktuální hodnoty s poslední společnou hodnotou. Jednostranná neproblematická změna se přenese. Dvě různé souběžné změny vytvoří konflikt pro ruční rozhodnutí. **Prázdná hodnota sama nesmaže vyplněný údaj na druhé straně.** Takové vymazání musí správce v porovnání výslovně potvrdit. Při změně hodnot od otevření porovnání se staré potvrzení odmítne. Další e-maily/telefony se nepřepisují jako celý seznam. Původní hlavní kontakt se při výměně zachová jako další kontakt, pokud tomu nebrání limit nebo jiná kontrola; v takovém případě se operace vrátí a nahlásí chybu. Při aktivním připraveném/běžícím importu isEDU synchronizace čeká. Neplatná stará nepovinná data se v počátečním porovnání označí a nelze je zvolit ke sdílení; zbytek lze spárovat. Chybějící cílová osoba se označí k ověření a nevyvolá smazání zaměstnance. **Přihlášení, PIN, hesla, oprávnění, aktivace účtů, stav studia ani pracovní stav se nesynchronizují.** Přihlašovací kontakty isEDU (`login_email`, `login_phone`) se nemění spolu s obecným kontaktem; jejich úprava musí proběhnout příslušným ověřeným postupem isEDU/eLoaderu. Zrušení párování ponechá obě evidence beze změny. Pro změnu výběru sdílených polí vazbu zrušte a znovu spárujte s novým porovnáním. Vymazání zaměstnance odstraní jeho záznamy v ePersonal, nikoli záznamy isEDU. ## Automatická synchronizace a cron Po uložení v ePersonal se provede pokus o synchronizaci jeho vazeb. **Lokální uložení je samostatné od následné synchronizace**: pokud synchronizace selže, uložení zůstává platné a zobrazí se upozornění. Synchronizační transakce naopak zahrnuje oba konce jednoho páru i jeho porovnávací stav. Změny provedené v isEDU přebírá tlačítko synchronizace, kontrola po 60 sekundách na otevřené viditelné stránce ePersonal bez rozepsaného formuláře, nebo cron. **Pro synchronizaci i bez otevřené aplikace nastavte cron.** Nejde o okamžitý push z isEDU. Zkopírujte `bin/sync-runner.php` do stabilního privátního umístění mimo verzovaný adresář aplikace, např. `/ABSOLUTNI/PRIVATE/epersonal-sync.php`. Launcher si při každém spuštění vyhledá aktuální aktivní ePersonal přes eLoader. Není nutné do cronu zadávat adresář konkrétní verze. ```cron * * * * * /usr/bin/php /ABSOLUTNI/PRIVATE/epersonal-sync.php --eloader=/ABSOLUTNI/ELOADER --limit=100 --budget=45 ``` Zástupné absolutní cesty nahraďte skutečnými. `--eloader` ukazuje na stabilní kořen eLoaderu obsahující `bootstrap.php`. Spouštějte pod systémovým účtem, který smí číst konfiguraci a klíč eLoaderu/ePersonal. Používá-li hosting vlastní `ELOADER_DATA`, nastavte tutéž hodnotu i pro cron. Nejprve spusťte příkaz ručně a ověřte výstup. Worker zpracovává omezenou dávku a ukládá kurzor pro další běh. Limit je nejvýše 200 osob/běh; časový rozpočet 1–45 sekund se kontroluje mezi osobami a není tvrdým přerušením databázového příkazu. Souběžné spuštění brání pracovní zámek. Logujte agregovaný výstup do chráněného místa; není v něm obsah osobních polí. U dvou rolí jedné osoby může navazující propagace dokončit další cyklus. ## Ochrana dat a zálohy Privátní osobní pole, celé bankovní účty, fotografie a stav porovnání se ukládají autentizovaně šifrované pomocí Sodium XChaCha20-Poly1305. **Ne všechny údaje jsou šifrované:** základní jména, kontakty, pracovní označení, strukturované CV a publikační údaje jsou uloženy pro běžné vyhledávání/zobrazení. Šifrování nechrání před správcem, který má současně klíč i databázi. Klíč `epersonal.key` vzniká v privátním `Context::dataPath()` s oprávněním 0600. **Zálohujte databázi i původní klíč.** Samotný SQL dump nestačí. Ztracený nebo jiný klíč aplikace nenahradí novým nad existujícími daty. Při chybě klíče obnovte jeho odpovídající originál a nic nemažte jen proto, aby zmizela hláška. Funkce pravidelné rotace klíče zatím není součástí verze. **Důležité pro rodné číslo:** zvolíte-li jeho synchronizaci do isEDU, cílové `isedu_students.rc` použije dosavadní uložiště isEDU, které tento adaptér nepřevádí na šifrované. Šifrování v ePersonal tedy automaticky nešifruje kopii v isEDU. Bez potřeby toto pole ke sdílení nevybírejte. Rodné číslo a bankovní účet jsou v běžném přehledu maskované; plné hodnoty vidí superadmin v editaci a vybrané osobní hodnoty v synchronizačním porovnání. Audit zaznamenává událost, identifikátor osoby, správce, názvy polí a chybový kód, ne původní/nové osobní hodnoty. Audit s identifikátorem přežije odstranění karty; jeho retenční pravidla musí zajistit provozovatel. Ve verzi není automatická retenční politika ani role personalisty oddělená od superadmina. Před obnovou, aktualizací schématu nebo přesunem databáze pozastavte synchronizaci a cron. Uchovávejte konzistentní zálohu ePersonal i isEDU a jeho vazeb. Návrat ke staršímu ZIPu sám nevrací již synchronizované osobní údaje. Odinstalace s výmazem tabulek může trvale odstranit obsah; nejprve ověřte obnovitelnou zálohu. ## Testy a soubory Podrobné výsledky, omezení ověření a akceptační postup: `docs/OVERENI.md`. Architektura a mapování: `docs/ARCHITEKTURA.md`. `tests/run.php` je CLI test; bez dostupného MySQL používá Python 3/SQLite testovací bridge. Nevydávejte jeho výsledek za nativní MySQL test. Pro nativní test lze zadat `EPERSONAL_TEST_DSN`, `EPERSONAL_TEST_USER`, `EPERSONAL_TEST_PASSWORD`; databáze musí být prázdná a její název začínat `epersonal_test_`. Test vytváří také testovací tabulky isEDU. **Nikdy jej nespouštějte nad provozní databází.** ```sh php tests/run.php ``` ## Externí technické podklady - PHP Sodium: https://www.php.net/manual/en/function.sodium-crypto-aead-xchacha20poly1305-ietf-encrypt.php - PHP PDO: https://www.php.net/manual/en/pdo.prepare.php - OWASP, příjem souborů: https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html - ČNB, IBAN: https://www.cnb.cz/cs/platebni-styk/iban/iban-mezinarodni-cislo-uctu/ Tyto podklady nejsou certifikací aplikace ani potvrzením jejího souladu s právními požadavky. Rozsah osobních údajů, oprávnění, retenční lhůty a provozní pravidla určuje jejich správce.