Modul Docházka - čip/čtečka prstu

1. Přehled modulu

1.1 Účel modulu

Modul Docházka - čip/čtečka prstu (WorkAttendanceChips) slouží k automatizovanému zaznamenávání pracovní docházky zaměstnanců pomocí fyzických čipových karet (RFID/NFC), biometrických čteček otisků prstů nebo rozpoznávání obličeje s využitím umělé inteligence.

Modul eliminuje potřebu ručního zadávání časů příchodu a odchodu, zvyšuje přesnost evidence a poskytuje kontrolní mechanismy proti zneužití (např. fotografie při zapípání, minimální délka pauzy, automatické uzavření pracovní doby).

1.2 Klíčové funkce

• Nastavení čipových karet - Evidence bezpečnostního kódu čipu RFID/NFC pro každého zaměstnance
• Čtečka otisků prstů - Biometrická identifikace pomocí otisků prstů (volitelné)
• Rozpoznávání obličeje - AI detekce obličeje pomocí face-api.js (vyžaduje RasPi terminál s kamerou)
• Docházkový terminál RasPi - Fyzický terminál pro zapisování docházky na místě
• IP omezení - Whitelist povolených IP adres pro čtečky (bezpečnost)
• Konfigurovatelná tlačítka - Typy docházky dostupné na terminálu (lékař, služební cesta atd.)
• Automatické uzavření - Automatické ukončení pracovní doby (3 režimy)
• Fotografie při zápisu - Bezpečnostní fotografie z terminálu pro detekci zneužití karet
• Zamezení ručních úprav - Přísný čipový režim s možností výjimek (dovolená, nemoc)
• Minimální pauza - Vynucení minimální délky přestávky
• Tlačítka na dashboardu - Virtuální příchod/odchod přímo v systému bez fyzické karty

1.3 Cílová skupina

Tato dokumentace je určena pro:

• Administrátory systému - Konfigurace modulu, správa čteček, nastavení bezpečnosti
• Personalisty - Správa uživatelských práv, nastavení kódů čipů, kontrola fotografií
• IT administrátory - Instalace RasPi terminálů, nastavení sítě, aktualizace firmware
• Vedoucí pracovníky - Kontrola docházky, schvalování výjimek

2. Nastavení a konfigurace

2.1 Nastavení modulu

Cesta k nastavení: Nastavení → Docházka - čip/čtečka prstu

Modul využívá následující konfigurační parametry uložené v databázové tabulce Company a User:

Parametry tabulky Company

Parametr	Typ	Popis	Výchozí hodnota
wa_RasPi_Face	boolean	Zapnout rozpoznávání obličeje (vyžaduje RasPi s kamerou)	0 (vypnuto)
wa_RasPi_TakePhoto	boolean	Pořizovat fotografie při zápisu z terminálu	0 (vypnuto)
wa_chip_allowed_ips_ser_arr	array	Povolené IP adresy čteček (serializované pole)	['all']
wa_chip_show_active	boolean	Zobrazit stavy (přítomnost) ostatních ve čtečce	0 (vypnuto)
wa_chip_use_WDT_14	boolean	Umožnit zapisovat Obědy zvlášť od Pauz	0 (vypnuto)
wa_chip_buttons_on_dashboard	boolean	Zobrazit tlačítka Příchod/Odchod na hlavním panelu	0 (vypnuto)
wa_chip_WritePause	boolean	Zapisovat pauzu po návratu ve stejný den	0 (vypnuto)
wa_chip_AutoCloseInLastDay	boolean	Upozornění a uzavření docházky z minulého dne	0 (vypnuto)
wa_chip_ChiporFaceDetect	string	Primární režim detekce ('c' = čip, 'f' = obličej)	'c' (čip)

Parametry tabulky User

Parametr	Typ	Popis	Výchozí hodnota
wa_chip_code	string	Bezpečnostní hash kód čipu zaměstnance	NULL
wa_chip_last_inout	enum	Aktuální stav zaměstnance ('in', 'out')	'out'
wa_chip_minimal_pause_min	int	Minimální délka pauzy v minutách	NULL
wa_chip_last_poznamka	string	Poslední poznámka při zapípání	NULL
wa_chip_AllowManualType_ser_arr	array	Povolené typy docházky pro ruční zápis (serializované pole)	[]
rights_workattendance	enum	Práva docházky ('1' = pouze čip, '2' = i ruční zápis)	'2'
FingerPrints_ser_arr	array	Uložené otisky prstů (serializované pole)	[]

2.2 Uživatelská práva

Pro přístup k nastavení modulu je potřeba splnit jednu z následujících podmínek:

• Práva administrátora: $Logged_User->admin == 1
• Správce modulu: in_array('dochazka_cipy', $Logged_User->AdminToModules_ser_arr)

3. Uživatelské rozhraní

3.1 Přehled záložek

Uživatelské rozhraní modulu je rozděleno do 5 hlavních záložek:

1. Uživatelská práva - Nastavení kódů čipů, otisků prstů, zamezení ručních úprav
2. Povolené IP adresy - Whitelist IP adres čteček
3. Navíc povolená tlačítka - Konfigurace tlačítek na terminálu
4. Ostatní nastavení - Obecná nastavení modulu
5. Registrované čtečky - Přehled RasPi terminálů

3.2 Záložka: Uživatelská práva

Hlavní záložka pro nastavení přístupu zaměstnanců k docházkovému systému.

Detekce uživatele

Systém podporuje 3 způsoby identifikace zaměstnance:

Metoda	Popis	Požadavky	Stav
Dle čipu (RFID/NFC)	Standardní čipová karta	Čtečka RFID/NFC	Vždy zapnuto
Dle obličeje	AI rozpoznávání obličeje pomocí face-api.js	RasPi terminál s kamerou, wa_RasPi_Face=1	Volitelné
Dle otisku prstu	Biometrická čtečka otisků	RasPi s čtečkou otisků, FingerPrintReader=1	Volitelné

Tabulka zaměstnanců

Tabulka obsahuje následující sloupce:

Sloupec	Popis	Akce
ID	ID zaměstnance v systému	-
Příjmení, jméno	Celé jméno s odkazem na detail uživatele	Kliknutím otevřete detail zaměstnance
Kód čipu	Bezpečnostní hash kód čipu	Zadejte do textového pole Změna se automaticky uloží (onChange) Ikona schránky zkopíruje API URL
Otisk prstu	Indikátor, zda má zaměstnanec uložené otisky	Zobrazuje 0/1 podle sizeofSafe($User->FingerPrints_ser_arr)
Zamezit úpravy	Checkbox pro zamezení ručních úprav docházky	Zaškrtnutím se nastaví rights_workattendance='1' Zobrazí se tlačítko pro povolení výjimek
Minimální délka pauzy	Počet minut minimální pauzy	Zadejte číslo (např. 30), změna se automaticky uloží
Akce	Speciální akce pro zaměstnance	Pokud je stav "in", zobrazí se tlačítko Resetovat (pro příchod) Resetuje stav na "out"

Tlačítko: Ručně může zapisovat pouze typ docházky...

Toto tlačítko se zobrazí pouze u zaměstnanců, kteří mají zaškrtnuté Zamezit úpravy pracovní doby.

Funkce: Otevře modální okno pro výběr typů docházky, které může zaměstnanec zapisovat ručně i přes zamezení ručních úprav.

Typické použití:

• Dovolená (zaměstnanec si může zadat dovolenou ručně)
• Nemoc (zaměstnanec si může zadat nemoc ručně)
• Homeoffice (zaměstnanec si může zadat homeoffice ručně)

3.3 Záložka: Povolené IP adresy

Tato záložka slouží k nastavení bezpečnostního whitelistu IP adres, ze kterých se mohou čtečky hlásit do systému.

Hlavní checkbox

Povolit přístup čtečky pouze z níže uvedených IP adres

• Zaškrtnuto: Systém kontroluje IP adresu požadavku proti whitelistu
• Nezaškrtnuto: Přístup je povolen ze všech IP adres (wa_chip_allowed_ips_ser_arr = ['all'])

Dynamické pole IP adres

Po zaškrtnutí hlavního checkboxu se zobrazí pole pro zadání IP adres:

• Každá IP adresa má vlastní textové pole
• Po vyplnění se automaticky zobrazí další prázdné pole
• Změny se ukládají automaticky (AJAX)
• Vždy jsou vidět minimálně 2 prázdná pole pro přidání dalších IP

Příklad nastavení:

192.168.1.100
192.168.1.101
10.0.0.50

3.4 Záložka: Navíc povolená tlačítka

Konfigurace dodatečných tlačítek na docházkovém terminálu pro speciální typy docházky (lékař, služební cesta atd.).

Tlačítko: Přidat tlačítko

Otevře modální okno pro přidání nového tlačítka:

1. Vyberte Typ docházky z rozbalovacího seznamu (načítají se pouze typy s chip_buttons_available=1)
2. Klikněte na Uložit
3. Tlačítko se objeví na terminálu a v tabulce

Tabulka tlačítek

Zobrazuje všechny nakonfigurovaná tlačítka s následujícími sloupci:

Sloupec	Popis	Možnosti
Tlačítko	Název typu docházky	Např. "Lékař", "Služební cesta"
Automatické ukončení k počtu pracovních hodin za den	Systém dopočítá konec podle denního úvazku	Radio button Uloží autoclose_user_hour_day=1 Příklad: Úvazek 8h, příchod 7:00 → auto konec 15:00
Automatické ukončení k zadanému času	Pevný čas ukončení	Radio button + časové pole (HH:MM) Uloží autoclose_user_hour_day=0 Uloží autoclose_at_time (např. "15:30:00") Příklad: Vždy ukončit v 16:00
Pevně daná délka v min	Konkrétní počet minut	Radio button + číselné pole Uloží autoclose_user_hour_day=2 Uloží autoclose_at_length (minuty) Příklad: Lékař = 60 min
Akce	Tlačítko pro odstranění	Tlačítko Odstranit tlačítko Nastaví delete=1 Tlačítko zmizí z terminálu

Režimy automatického ukončení - podrobně

1. K počtu pracovních hodin za den

Jak to funguje:

1. Systém načte denní úvazek zaměstnance (např. 8 hodin)
2. Při zapípání příchodu zaznamená čas (např. 7:00)
3. Automaticky vypočítá konec: 7:00 + 8h = 15:00
4. Pokud zaměstnanec nezapíše odchod do půlnoci, systém automaticky ukončí v 15:00

Příklad použití: Služební cesta - zaměstnanec odejde na cestu, systém ukončí dobu automaticky podle jeho úvazku.

2. K zadanému času

Jak to funguje:

1. Administrátor nastaví pevný čas ukončení (např. 15:30)
2. Při zapípání příchodu zaznamená čas (např. 7:00)
3. Pokud zaměstnanec nezapíše odchod do půlnoci, systém automaticky ukončí v 15:30

Příklad použití: Konference - všichni účastníci mají pevný konec v 16:00.

3. Pevně daná délka

Jak to funguje:

1. Administrátor nastaví počet minut (např. 60)
2. Při zapípání příchodu zaznamená čas (např. 9:00)
3. Systém automaticky ukončí za 60 minut: 9:00 + 60 min = 10:00

Příklad použití: Lékař - zaměstnanec jde k lékaři, systém ukončí za 60 minut.

3.5 Záložka: Ostatní nastavení

Obecná nastavení modulu ovlivňující chování celého systému.

Nastavení	Popis	Výchozí hodnota
Zobrazit stavy (přítomnost) ostatních ve čtečce	Na terminálu se zobrazí seznam všech zaměstnanců s jejich aktuálním stavem (přítomen/nepřítomen). Databázový sloupec: wa_chip_show_active	Vypnuto (0)
Umožnit zapisovat Obědy zvlášť od Pauz	Zaměstnanec může na terminálu rozlišit mezi obecnou pauzou a obědem (speciální typ pauzy). Databázový sloupec: wa_chip_use_WDT_14 Typ docházky: WDT_14 (Oběd)	Vypnuto (0)
Zobrazit tlačítka Příchod/Odchod na hlavním panelu po přihlášení	Každý zaměstnanec uvidí po přihlášení na dashboardu tlačítka pro zapípání příchodu/odchodu bez nutnosti fyzické karty. Databázový sloupec: wa_chip_buttons_on_dashboard Použití: Vhodné pro zaměstnance pracující z domova nebo bez přístupu k terminálu	Vypnuto (0)
Zapisovat pauzu po návratu ve stejný den	Pokud zaměstnanec odpípá odchod a poté znovu příchod ve stejný den, systém automaticky zaznamená čas mezi jako pauzu. Databázový sloupec: wa_chip_WritePause Příklad: Odchod 12:00, Příchod 12:30 → Pauza 30 min	Vypnuto (0)
Fotografie při zápisu docházky z terminálu	Při každém zapípání z RasPi terminálu se pořídí fotografie zaměstnance. Slouží k detekci zneužití karet (kontrola, že kartu používá skutečný majitel). Databázový sloupec: wa_RasPi_TakePhoto Požadavky: RasPi terminál s kamerou	Vypnuto (0)
Upozornění a uzavření docházky z minulého dne	Pokud zaměstnanec zapomene odpípat odchod včera a dnes zapíše nový příchod, systém zobrazí upozornění a vyžaduje doplnění včerejšího odchodu s nadřízeným. Databázový sloupec: wa_chip_AutoCloseInLastDay Účel: Prevence "visících" záznamů v docházce	Vypnuto (0)

3.6 Záložka: Registrované čtečky

Přehled všech RasPi terminálů registrovaných v systému.

Tabulka čteček

Sloupec	Popis
ID	Unikátní identifikátor čtečky v databázi (idRasPi)
Datum pořízení	Datum instalace/registrace čtečky (BuyDate)
Instalovaná verze FW	Verze firmware nainstalovaná na RasPi (Version)
Poslední kontrola	Datum a čas poslední komunikace s čtečkou (LastCheck)

Diagnostika čteček

Podle sloupce Poslední kontrola můžete diagnostikovat problémy:

• Zelená: Čtečka se hlásila v poslední hodině - vše v pořádku
• Žlutá: Čtečka se nehlásila více než hodinu - možný problém se sítí
• Červená: Čtečka se nehlásila více než den - závažný problém (vypnuto, síť, hardware)

4. Základní operace

4.1 Nastavení kódu čipu zaměstnanci

Cíl: Přiřadit zaměstnanci bezpečnostní kód čipu, aby mohl zapisovat docházku.

1. Otevřete Nastavení → Docházka - čip/čtečka prstu
2. Přejděte na záložku Uživatelská práva
3. V tabulce zaměstnanců najděte požadovaného zaměstnance (můžete použít vyhledávání)
4. Do sloupce Kód čipu zadejte bezpečnostní hash kód (doporučeno minimálně 16 znaků, náhodné)
5. Systém automaticky uloží změnu při opuštění pole (onChange event)
6. Volitelně: Klikněte na ikonu schránky (fa-clipboard) pro zkopírování API URL pro testování

4.2 Zamezení ručních úprav docházky

Cíl: Nastavit zaměstnanci přísný režim, kde může zapisovat docházku pouze čipem.

1. V záložce Uživatelská práva najděte zaměstnance
2. V řádku zaměstnance zaškrtněte checkbox Zamezit úpravy pracovní doby v docházce
3. Systém nastaví rights_workattendance='1'
4. Zobrazí se zelené tlačítko Ručně může zapisovat pouze typ docházky...
5. Klikněte na tlačítko
6. V modálním okně zaškrtněte povolené typy (např. Dovolená, Nemoc, Homeoffice)
7. Klikněte na Uložit

Výsledek: Zaměstnanec nyní nemůže ručně upravovat docházku, ale může si ručně zadat vybrané typy absence.

4.3 Nastavení minimální pauzy

Cíl: Vynutit minimální délku pauzy (např. oběd minimálně 30 minut).

1. V záložce Uživatelská práva najděte zaměstnance
2. Do sloupce Minimální délka pauzy (minut) zadejte počet minut (např. 30)
3. Systém automaticky uloží změnu

Jak to funguje:

• Zaměstnanec odpípá pauzu (např. 12:00 - 12:10 = 10 minut)
• Systém zkontroluje wa_chip_minimal_pause_min (např. 30)
• Pokud je pauza kratší, automaticky ji prodlouží na minimum (10 min → 30 min)
• V zápisu docházky se objeví pauza 30 minut

4.4 Reset stavu příchod/odchod

Cíl: Resetovat "visící" stav zaměstnance, který zapomněl odpípat odchod.

1. V záložce Uživatelská práva najděte zaměstnance
2. Pokud je zaměstnanec ve stavu "in" (přítomen), zobrazí se tlačítko Resetovat (pro příchod)
3. Klikněte na tlačítko
4. Systém změní stav na "out" (nepřítomen)
5. Zaměstnanec nyní může znovu odpípat příchod

Kdy použít:

• Zaměstnanec zapomněl odpípat odchod včera
• Systém "visí" ve stavu "in" a neumožňuje nový příchod
• Potřebujete rychle odblokovat zaměstnance

5. Pokročilé funkce

5.1 Přidání tlačítka na čtečku

Cíl: Přidat speciální typ docházky (např. Lékař, Služební cesta) jako tlačítko na RasPi terminál.

1. Přejděte na záložku Navíc povolená tlačítka na čtečce čipů
2. Klikněte na zelené tlačítko Přidat tlačítko
3. V modálním okně vyberte Typ docházky z rozbalovacího seznamu
4. Klikněte na Uložit
5. Tlačítko se zobrazí v tabulce
6. Nastavte režim automatického ukončení (viz níže)

Nastavení automatického ukončení

Po přidání tlačítka vyberte jeden ze 3 režimů:

A) K počtu pracovních hodin za den

• Zaškrtněte radio button ve sloupci Automatické ukončení k počtu pracovních hodin za den
• Systém dopočítá konec podle denního úvazku zaměstnance
• Příklad: Služební cesta - zaměstnanec má úvazek 8h, odjede v 9:00 → auto konec 17:00

B) K zadanému času

• Zaškrtněte radio button ve sloupci Automatické ukončení k zadanému času
• Do časového pole níže zadejte čas (např. 15:30)
• Příklad: Školení - všichni mají pevný konec v 16:00

C) Pevně daná délka

• Zaškrtněte radio button ve sloupci Pevně daná délka v min
• Do číselného pole níže zadejte počet minut (např. 60)
• Příklad: Lékař - automaticky ukončit za 60 minut

5.2 Odstranění tlačítka

1. V tabulce tlačítek najděte řádek s tlačítkem, které chcete odstranit
2. Klikněte na červené tlačítko Odstranit tlačítko
3. Tlačítko se odebere z databáze a zmizí z terminálu

5.3 Omezení IP adres

Cíl: Povolit přístup k API pouze z důvěryhodných IP adres (čteček).

1. Přejděte na záložku Povolené IP adresy, ze kterých se může čtečka hlásit
2. Zaškrtněte Povolit přístup čtečky pouze z níže uvedených IP adres
3. Do prvního prázdného pole zadejte IP adresu čtečky (např. 192.168.1.100)
4. Po zapsání se automaticky zobrazí další prázdné pole
5. Opakujte pro všechny čtečky
6. Změny se ukládají automaticky

Bezpečnostní kontrola v kódu:

// Systém kontroluje USER_IP proti wa_chip_allowed_ips_ser_arr
if (!in_array(USER_IP, $Company->wa_chip_allowed_ips_ser_arr)
    && $Company->wa_chip_allowed_ips_ser_arr[0] != 'all') {
    DieUnauthorized();
}

5.4 Zapnutí rozpoznávání obličeje

Cíl: Umožnit zaměstnancům zapípat docházku pomocí obličeje bez čipu.

Požadavky:

• RasPi terminál s kamerou
• Fotografie zaměstnanců v systému (minimálně 1 fotka na zaměstnance)
• JavaScript knihovna face-api.js (součást systému)

Postup aktivace:

1. Přejděte na záložku Uživatelská práva
2. V záhlaví tabulky zaškrtněte Dle obličeje (nutná naše čtečka)
3. Systém nastaví wa_RasPi_Face=1
4. Na RasPi terminálu se aktivuje kamera a detekce obličeje

Jak to funguje:

1. Zaměstnanec přistoupí před kameru RasPi
2. Systém načte všechny uložené fotografie zaměstnanců
3. Face-api.js detekuje obličej v živém videu
4. Porovná detekovaný obličej s uloženými fotografiemi (threshold 0.4)
5. Při shodě automaticky zapíše docházku

5.5 Zobrazení stavů ostatních

Cíl: Na terminálu zobrazit, kdo je přítomen a kdo není.

1. Přejděte na záložku Ostatní nastavení
2. Zaškrtněte Zobrazit stavy (přítomnost) ostatních ve čtečce
3. Systém nastaví wa_chip_show_active=1

Výsledek: Na RasPi terminálu se zobrazí seznam všech zaměstnanců:

• Zelená: Přítomen (wa_chip_last_inout='in')
• Červená: Nepřítomen (wa_chip_last_inout='out')

5.6 Tlačítka na dashboardu

Cíl: Umožnit zaměstnancům zapípat docházku přímo z webového rozhraní bez fyzické karty.

1. Přejděte na záložku Ostatní nastavení
2. Zaškrtněte Zobrazit tlačítka Příchod/Odchod na hlavním panelu po přihlášení
3. Systém nastaví wa_chip_buttons_on_dashboard=1

Výsledek: Po přihlášení uvidí každý zaměstnanec na dashboardu:

• Zelené tlačítko "Příchod" (pokud je stav 'out')
• Červené tlačítko "Odchod" (pokud je stav 'in')

Použití:

• Homeoffice - zaměstnanec nemá přístup k čtečce
• Mobilní zaměstnanci - zapípání z mobilu/tabletu
• Administrativa - zálohový způsob zápisu

5.7 Fotografie při zápisu

Cíl: Pořizovat bezpečnostní fotografii při každém zapípání pro detekci zneužití karet.

1. Přejděte na záložku Ostatní nastavení
2. Zaškrtněte Fotografie při zápisu docházky z terminálu
3. Systém nastaví wa_RasPi_TakePhoto=1

Jak to funguje:

1. Zaměstnanec přiloží čip k čtečce
2. RasPi kamera pořídí fotografii
3. Fotografie se nahraje na server
4. Uloží se do tabulky Files s vazbou na záznam docházky
5. Administrátor může fotografie zkontrolovat v modulu Docházka

Detekce zneužití:

• Na fotografii je jiná osoba než majitel karty → zneužití
• Fotografie je rozmazaná/prázdná → pokus o obejití systému
• Opakované fotografie stejné osoby s cizí kartou → pravidelné zneužití

6. Integrace

6.1 Propojené moduly

Modul	Vztah	Popis
Docházka	Zápis dat	Automatický zápis časů příchodu/odchodu do tabulky Workattendance. Pokud je zapnuto wa_chip_WritePause=1, zapisuje se i délka pauzy.
Uživatelé	Vazba na zaměstnance	Načítání uživatelských dat (cUser třída): - Kód čipu (wa_chip_code) - Otisky prstů (FingerPrints_ser_arr) - Práva docházky (rights_workattendance) - Minimální pauza (wa_chip_minimal_pause_min)
RasPi terminály	Fyzická čtečka	Správa RasPi zařízení (cRasPi třída): - Verze firmware (Version) - Poslední kontrola (LastCheck) - Čtečka otisků (FingerPrintReader) - API endpoint (GetUrl())
Typy docházky	Tlačítka na čtečce	Načítání typů docházky (cWorkattendance_days_type): - Název typu (day_name_cs) - Dostupnost na čtečce (chip_buttons_available) - Vazba přes tabulku Workattendance_chip_buttons
Soubory	Fotografie při zápisu	Ukládání fotografií z terminálu: - Tabulka Files - Vazba na záznam docházky - Přístup přes modul Docházka

6.2 Datové toky

Tok 1: Zapípání čipem z RasPi terminálu

1. Zaměstnanec přiloží čip k RasPi čtečce
   ↓
2. RasPi načte kód čipu z RFID/NFC
   ↓
3. RasPi volá API endpoint:
   GET /?w=wa_chip_inout&idUser=123&hash=abc123xyz
   ↓
4. inc/wa_chip_inout.php zpracuje požadavek:
   - Ověří hash proti User.wa_chip_code
   - Ověří IP adresu proti wa_chip_allowed_ips_ser_arr
   - Zkontroluje stav wa_chip_last_inout
   ↓
5. Zápis do tabulky Workattendance:
   - Příchod: Vytvoří nový záznam s time_start
   - Odchod: Doplní time_end do existujícího záznamu
   ↓
6. Aktualizace User.wa_chip_last_inout:
   - 'in' → 'out' nebo 'out' → 'in'
   ↓
7. Pokud wa_RasPi_TakePhoto=1:
   - RasPi pořídí fotografii
   - Nahraje na server
   - Uloží do tabulky Files
   ↓
8. Odpověď RasPi terminálu:
   - HTML stránka s potvrzením
   - Zobrazení času zápisu
   - Seznam přítomných (pokud wa_chip_show_active=1)

Tok 2: Zapípání z dashboardu (webové rozhraní)

1. Zaměstnanec klikne na tlačítko "Příchod" na dashboardu
   ↓
2. JavaScript volá AJAX:
   $.get('/?w=wa_chip_inout&idUser='+idUser+'&hash='+hash)
   ↓
3. inc/wa_chip_inout.php zpracuje stejně jako RasPi
   ↓
4. Zápis do Workattendance
   ↓
5. Aktualizace wa_chip_last_inout
   ↓
6. Odpověď AJAX:
   - Dashboard se obnoví
   - Zobrazí se nový stav ("Odchod" místo "Příchod")

Tok 3: Rozpoznávání obličeje (Face Recognition)

1. Zaměstnanec přistoupí před kameru RasPi
   ↓
2. RasPi streamuje video na server
   ↓
3. JavaScript face-api.js:
   - Načte všechny fotografie zaměstnanců
   - Vytvoří FaceMatcher s uloženými obličeji
   - Detekuje obličej v živém videu
   - Porovná s uloženými obličeji
   ↓
4. Při shodě (threshold > 0.4):
   window.location.replace('?w=wa_chip_inout&FaceDetection='+hash)
   ↓
5. Server zpracuje FaceDetection parametr:
   - Najde idUser podle hashe
   - Načte wa_chip_code
   - Zapíše docházku
   ↓
6. Stejný tok jako Tok 1 (krok 5-8)

6.3 Závislosti

Komponenta	Závislost	Povinná
RasPi terminál	Fyzické zařízení s čtečkou RFID/NFC	Ano
Docházkový modul	Musí být aktivní pro zápis dat	Ano
Uživatelé	Zaměstnanci musí mít práva docházky	Ano
RasPi s kamerou	Pro rozpoznávání obličeje a fotografie	Volitelné
Čtečka otisků	Pro biometrickou identifikaci	Volitelné
face-api.js	Knihovna pro rozpoznávání obličeje	Volitelné
Síťové připojení	RasPi musí mít přístup na server	Ano

7. API endpoint

7.1 Hlavní endpoint

URL formát:

https://vase-domena.cz/?w=wa_chip_inout&idUser={ID}&hash={HASH}

7.2 Parametry

Parametr	Typ	Povinný	Popis
w	string	Ano	Identifikátor endpointu Hodnota: wa_chip_inout
idUser	int	Ano	ID zaměstnance v systému Příklad: 123
hash	string	Ano	Bezpečnostní hash kód čipu Odpovídá: User.wa_chip_code Příklad: abc123xyz789def456
idWorkattendance_chip_buttons	int	Ne	ID tlačítka na čtečce (speciální typ docházky) Příklad: 5 (Lékař)
FaceDetection	string	Ne	Hash rozpoznaného obličeje Formát: {userHash}-{photoID} Příklad: abc123-1
FingerID	int	Ne	ID rozpoznaného otisku prstu Příklad: 7
wa_chip_action	string	Ne	Specifická akce (např. ruční výběr poznámky) Hodnoty: note, pause

7.3 Bezpečnostní kontroly

API endpoint provádí následující bezpečnostní kontroly:

1. Ověření hashe:

   if ($User->wa_chip_code != $_GET['hash']) {
       DieUnauthorized();
   }

2. Kontrola IP adresy:

   if (!in_array(USER_IP, $Company->wa_chip_allowed_ips_ser_arr)
       && $Company->wa_chip_allowed_ips_ser_arr[0] != 'all') {
       DieUnauthorized();
   }

3. Kontrola existence uživatele:

   $User = new cUser();
   $User->load($_GET['idUser']);
   if ($User->idUser == 0) {
       DieUnauthorized();
   }

4. Kontrola aktivního účtu:

   if ($User->active != 1 || $User->deleted != 0) {
       DieUnauthorized();
   }

7.4 Odpověď API

API vrací HTML stránku s následujícími informacemi:

• Hodiny a datum: Aktuální čas a datum (JavaScript hodiny)
• Potvrzení zápisu: "Příchod zaznamenán" / "Odchod zaznamenán"
• Čas zápisu: Přesný čas zapípání
• Seznam přítomných: Pokud wa_chip_show_active=1
• Fotografie: Pokud wa_RasPi_TakePhoto=1, zobrazí se náhled fotografie

7.5 Příklady volání

Příklad 1: Běžný příchod

GET https://firma.cz/?w=wa_chip_inout&idUser=45&hash=x7k9mN2pQ5rT8vW1

Příklad 2: Odchod k lékaři (tlačítko ID=3)

GET https://firma.cz/?w=wa_chip_inout&idUser=45&hash=x7k9mN2pQ5rT8vW1&idWorkattendance_chip_buttons=3

Příklad 3: Rozpoznání obličeje

GET https://firma.cz/?w=wa_chip_inout&FaceDetection=abc123def456-1

Příklad 4: Otisk prstu

GET https://firma.cz/?w=wa_chip_inout&idUser=45&hash=x7k9mN2pQ5rT8vW1&FingerID=7

8. RasPi terminál

8.1 Popis zařízení

RasPi (Raspberry Pi) terminál je kompaktní počítač velikosti kreditní karty, který slouží jako fyzická docházková čtečka.

Hardwarové komponenty

Komponenta	Popis	Povinná
Raspberry Pi	Základní deska (doporučeno RPi 4 nebo novější)	Ano
Čtečka RFID/NFC	Modul pro čtení čipových karet (např. RC522)	Ano
Displej	Touchscreen displej pro zobrazení tlačítek a stavů	Ano
Kamera	Pi Camera pro fotografování a rozpoznávání obličeje	Volitelné
Čtečka otisků	Biometrická čtečka otisků prstů (např. R307)	Volitelné
Síťové připojení	Ethernet nebo WiFi pro komunikaci se serverem	Ano

8.2 Funkce terminálu

Základní funkce

• Čtení čipů: Automatická detekce RFID/NFC karet
• Zobrazení času: Aktuální čas a datum
• Tlačítka typů docházky: Příchod, Odchod, Pauza, Oběd + konfigurovatelná tlačítka
• Potvrzení zápisu: Vizuální a zvuková signalizace úspěšného zápisu
• Seznam přítomných: Zobrazení, kdo je v práci (pokud zapnuto)

Pokročilé funkce (volitelné)

• Rozpoznávání obličeje: AI detekce pomocí kamery a face-api.js
• Čtení otisků: Biometrická identifikace pomocí otisků prstů
• Fotografování: Pořízení bezpečnostní fotografie při každém zapípání
• Video stream: Živé video z kamery pro rozpoznávání obličeje

8.3 Správa terminálu

Registrace nového terminálu

1. Fyzicky připojte RasPi k síti (Ethernet nebo WiFi)
2. Spusťte instalační skript na RasPi
3. RasPi se automaticky zaregistruje na serveru:

POST https://firma.cz/RestAPI/RasPi.php
{
    "action": "register",
    "hash": "E5tlu8Jg44ZwwlBQgSbCE3lU7RSRvMXa"
}

4. V administraci se zobrazí nový terminál v záložce Registrované čtečky

Kontrola stavu terminálu

Terminál se pravidelně hlásí na server (každých 5 minut):

GET https://firma.cz/RestAPI/RasPiCheck.php?hash={hash}

Server aktualizuje sloupec LastCheck v tabulce RasPi.

Aktualizace firmware

1. Přihlaste se na RasPi přes SSH
2. Spusťte příkaz: sudo /home/pi/UpdateFromeIntranetServer
3. Skript stáhne nejnovější verzi z: https://firma.cz/Apps/RasPiUpdate/
4. Automaticky restartuje služby
5. Verze se aktualizuje v databázi (Version sloupec)

8.4 API URL terminálu

Každý RasPi terminál má unikátní API URL:

https://firma.cz/RasPi/{HASH}/RFID/WorkAttenDance

Kde {HASH} je bezpečnostní identifikátor terminálu (např. E5tlu8Jg44ZwwlBQgSbCE3lU7RSRvMXa).

Použití:

• RasPi načte čip s kódem 12345
• RasPi volá: https://firma.cz/?w=wa_chip_inout&idUser=45&hash=12345
• Server ověří a zapíše docházku
• RasPi zobrazí potvrzení

8.5 Diagnostika problémů

Problém: Terminál se nehlásí

Příznaky: V záložce "Registrované čtečky" je starý čas v sloupci "Poslední kontrola"

Řešení:

1. Zkontrolujte síťové připojení RasPi (ping server)
2. Ověřte, že je IP adresa RasPi v whitelistu
3. Zkontrolujte logy na RasPi: /var/log/eintranet/
4. Restartujte RasPi: sudo reboot

Problém: Čtečka nečte čipy

Příznaky: Přiložení čipu nevyvolá žádnou reakci

Řešení:

1. Zkontrolujte fyzické připojení čtečky k RasPi
2. Ověřte, že běží služba čtečky: sudo systemctl status rfid
3. Restartujte službu: sudo systemctl restart rfid
4. Zkontrolujte, že čip je kompatibilní (RFID/NFC 13.56 MHz)

Problém: Rozpoznávání obličeje nefunguje

Příznaky: Kamera nezobrazuje video nebo nerozpoznává obličeje

Řešení:

1. Ověřte, že je v nastavení zapnuto: wa_RasPi_Face=1
2. Zkontrolujte připojení kamery k RasPi
3. Ověřte, že zaměstnanci mají nahrané fotografie v systému
4. Zkontrolujte JavaScript konzoli v prohlížeči na chyby
5. Zkuste snížit threshold: upravte minConfidence = 0.3 (místo 0.4)

9. Tipy a triky

9.1 Kopírování API URL

Tip: V záložce "Uživatelská práva" klikněte na ikonu schránky (fa-clipboard) vedle kódu čipu. URL se zkopíruje do schránky.

Použití: Můžete URL otevřít v prohlížeči pro ruční testování zapípání bez fyzické čtečky.

9.2 Testování bez RasPi terminálu

Postup:

1. Zkopírujte API URL zaměstnance
2. Otevřete URL v prohlížeči
3. Systém zapíše docházku jako z RasPi

9.3 Reset "visících" stavů hromadně

Situace: Více zaměstnanců zapomnělo odpípat odchod a systém je ve stavu "in".

Řešení SQL dotazem:

UPDATE User
SET wa_chip_last_inout='out'
WHERE Company_idCompany=123
AND wa_chip_last_inout='in';

Poznámka: Toto pouze resetuje stavy, neřeší chybějící záznamy v docházce.

9.4 Nastavení minimální pauzy pro všechny

Situace: Chcete nastavit minimální pauzu 30 minut pro všechny zaměstnance.

Řešení SQL dotazem:

UPDATE User
SET wa_chip_minimal_pause_min=30
WHERE Company_idCompany=123
AND active=1
AND deleted=0;

9.5 Exportování kódů čipů

Postup:

1. V záložce "Uživatelská práva" použijte DataTables export
2. Klikněte na tlačítko "Excel" nebo "CSV"
3. Stáhne se soubor se všemi kódy čipů

9.6 Automatické tlačítko pro homeoffice

Doporučení: Přidejte tlačítko "Homeoffice" s automatickým ukončením k počtu pracovních hodin.

Výhoda: Zaměstnanec zapíše homeoffice, systém automaticky ukončí podle jeho úvazku.

9.7 Kombinace čipu a obličeje

Možnost: Zapněte rozpoznávání obličeje i čipu současně.

Výhoda:

• Zaměstnanec může použít čip (rychlé)
• Nebo obličej (pokud zapomněl kartu)
• Systém podporuje obojí

9.8 Fotografie jako důkaz

Tip: Pokud máte spory o docházce, použijte fotografie z terminálu jako důkaz.

Přístup:

1. Modul Docházka
2. Detail záznamu
3. Zobrazí se fotografie pořízená při zapípání

9.9 Mobilní aplikace jako alternativa

Informace: Systém podporuje i mobilní aplikaci pro zapípání docházky.

Výhoda:

• Zaměstnanec nemusí mít čip
• Zapípání z telefonu odkudkoliv
• GPS lokace při zápisu (volitelné)

9.10 Pravidelné čištění starých fotografií

Tip: Fotografie zabírají místo na serveru. Nastavte automatické mazání starších než 3 měsíce.

Cron job:

DELETE FROM Files
WHERE table_name='Workattendance'
AND created < DATE_SUB(NOW(), INTERVAL 3 MONTH);

10. Řešení problémů

10.1 Čip nefunguje

Příznaky: Přiložení čipu k čtečce nevyvolá žádnou reakci nebo se zobrazí chyba.

Možné příčiny a řešení:

Příčina	Řešení
Chybný nebo prázdný kód čipu	Zkontrolujte, že je v záložce "Uživatelská práva" vyplněn Kód čipu. Musí přesně odpovídat kódu v čipu.
IP adresa čtečky není v whitelistu	Přejděte na záložku "Povolené IP adresy". Přidejte IP adresu RasPi terminálu. Nebo vypněte IP whitelist (nezaškrtnuté).
Čtečka nečte čip	Zkontrolujte fyzické připojení čtečky k RasPi. Restartujte službu RFID: sudo systemctl restart rfid
Nekompatibilní čip	Ověřte, že čip je RFID/NFC 13.56 MHz (např. Mifare). Systém nepodporuje 125 kHz čipy.
Síťový problém	Zkontrolujte připojení RasPi k síti. Ping na server: ping vase-domena.cz

Testování: Zkopírujte API URL (ikona schránky) a otevřete v prohlížeči. Pokud funguje, problém je v RasPi/čtečce. Pokud nefunguje, problém je v nastavení systému.

10.2 Zaměstnanec nemůže zapisovat ručně

Příznaky: Při pokusu o ruční zápis v modulu Docházka se zobrazí chyba "Nemáte oprávnění".

Možné příčiny a řešení:

Příčina	Řešení
Zaškrtnuto "Zamezit úpravy"	V záložce "Uživatelská práva" odškrtněte checkbox Zamezit úpravy pracovní doby. Nebo klikněte na Ručně může zapisovat pouze typ docházky... a povolte konkrétní typy.
Typ docházky není povolen	Klikněte na Ručně může zapisovat pouze typ docházky... Zaškrtněte požadovaný typ (např. Dovolená, Nemoc). Klikněte Uložit.
Nemá práva k docházce	V administraci uživatelů zkontrolujte, že má zaměstnanec rights_workattendance nastaveno. Musí být '1' nebo '2' (ne NULL nebo 0).

10.3 Pauza se automaticky prodlužuje

Příznaky: Zaměstnanec zapíše pauzu 15 minut, ale v systému se objeví 30 minut.

Příčina: Je nastavena minimální délka pauzy.

Řešení:

1. V záložce "Uživatelská práva" najděte zaměstnance
2. Ve sloupci Minimální délka pauzy (minut) smažte hodnotu nebo snižte (např. z 30 na 15)
3. Systém automaticky uloží

Poznámka: Prodloužení pauzy je zamýšlená funkce, ne chyba. Slouží k vynucení oběda.

10.4 Fotografie se nepořizují

Příznaky: V modulu Docházka u záznamů chybí fotografie, i když je funkce zapnutá.

Možné příčiny a řešení:

Příčina	Řešení
Není zapnuto v nastavení	V záložce "Ostatní nastavení" zaškrtněte Fotografie při zápisu docházky z terminálu. Zkontrolujte, že wa_RasPi_TakePhoto=1.
RasPi nemá kameru	Ověřte, že je k RasPi fyzicky připojena Pi Camera. Zkontrolujte připojení kabelu kamery. Spusťte test kamery: raspistill -o test.jpg
Služba kamery neběží	Zkontrolujte stav: sudo systemctl status camera Restartujte: sudo systemctl restart camera
Chyba při nahrávání na server	Zkontrolujte logy RasPi: /var/log/eintranet/camera.log Ověřte síťové připojení a oprávnění k zápisu na serveru.
Zapípání z dashboardu	Fotografie se pořizují pouze při zapípání z RasPi terminálu. Tlačítka na dashboardu fotografie nepořizují (nemají kameru).

10.5 Terminál se nehlásí

Příznaky: V záložce "Registrované čtečky" je v sloupci "Poslední kontrola" starý datum/čas (více než hodinu).

Možné příčiny a řešení:

Příčina	Řešení
RasPi je vypnuté	Zkontrolujte, že je RasPi připojené k napájení a svítí LED. Zkuste fyzicky restartovat (odpojit a zapojit napájení).
Síťový problém	Zkontrolujte Ethernet kabel nebo WiFi připojení. Ping na server z RasPi: ping vase-domena.cz Zkontrolujte firewall a router.
IP adresa není v whitelistu	V záložce "Povolené IP adresy" přidejte IP adresu RasPi. Zkontrolujte, že IP adresa RasPi se nezměnila (DHCP). Doporučujeme nastavit statickou IP.
Služba check se nezapustila	SSH na RasPi. Zkontrolujte stav: sudo systemctl status eintranet-check Restartujte: sudo systemctl restart eintranet-check
Chyba v konfiguračním souboru	Zkontrolujte konfiguraci: /etc/eintranet/config.json Ověřte správnost URL serveru a hashe.

10.6 Rozpoznávání obličeje nefunguje

Příznaky: Kamera zobrazuje video, ale systém nerozpoznává žádného zaměstnance.

Možné příčiny a řešení:

Příčina	Řešení
Není zapnuto v nastavení	V záložce "Uživatelská práva" zaškrtněte Dle obličeje (nutná naše čtečka). Zkontrolujte, že wa_RasPi_Face=1.
Chybí fotografie zaměstnanců	V administraci uživatelů zkontrolujte, že mají zaměstnanci nahrané fotografie. Minimálně 1 fotka na zaměstnance. Fotografie musí být frontální, dobře osvětlené, bez brýlí/čepice.
Špatné světelné podmínky	Zajistěte dostatečné osvětlení před čtečkou. Vyhněte se protisvětlu a tmavým místům. Ideální je rovnoměrné denní světlo.
Příliš vysoký threshold	V souboru inc/wa_chip_inout.php snižte minConfidence: let minConfidence = 0.3 (místo 0.4) Pozor: Nižší threshold = více falešných rozpoznání.
JavaScript chyby	Otevřete JavaScript konzoli v prohlížeči (F12). Zkontrolujte chybové hlášky. Zkuste jiný prohlížeč (doporučeno Chrome).
Face-api.js se nenačetla	Zkontrolujte, že existuje soubor: /_components/face-api.js-0.22.2/dist/face-api.min.js Zkontrolujte síťové připojení (API načítá modely z CDN).

10.7 Tlačítka na dashboardu nejsou vidět

Příznaky: Po přihlášení na dashboard chybí tlačítka Příchod/Odchod.

Možné příčiny a řešení:

Příčina	Řešení
Není zapnuto v nastavení	V záložce "Ostatní nastavení" zaškrtněte Zobrazit tlačítka Příchod/Odchod na hlavním panelu. Zkontrolujte, že wa_chip_buttons_on_dashboard=1.
Cache prohlížeče	Obnovte stránku s vymazáním cache: Ctrl + F5 (Windows) nebo Cmd + Shift + R (Mac). Nebo vymažte cookies a cache v nastavení prohlížeče.
Nemá vyplněný kód čipu	V záložce "Uživatelská práva" zkontrolujte, že má zaměstnanec vyplněný Kód čipu. Tlačítka se zobrazují pouze uživatelům s kódem čipu.
JavaScript chyba	Otevřete JavaScript konzoli (F12). Zkontrolujte chybové hlášky. Zkuste jiný prohlížeč.

10.8 Automatické ukončení nefunguje

Příznaky: Zaměstnanec odpípá speciální typ (např. Lékař), ale docházka se automaticky neukončí.

Možné příčiny a řešení:

Příčina	Řešení
Není nastaven režim	V záložce "Navíc povolená tlačítka" zkontrolujte tlačítko. Musí být zaškrtnut jeden z 3 radio buttonů (k hodinám, času nebo délce). Pokud není, zaškrtněte a nastavte hodnotu.
Zaměstnanec odpípal odchod ručně	Automatické ukončení se aplikuje pouze pokud zaměstnanec NEodpípal odchod do půlnoci. Pokud odpípal ručně, automatika se nepoužije.
Cron job neběží	Automatické ukončení provádí cron job (např. v 00:01). Zkontrolujte, že běží: crontab -l Hledejte řádek s wa_chip_autoclose.php (nebo podobný).
Chybné nastavení času	U režimu "K zadanému času" zkontrolujte formát času: HH:MM Musí být validní čas (např. 15:30, ne 25:00).

10.9 Minimální pauza se neuplatňuje

Příznaky: Zaměstnanec má nastavenou minimální pauzu 30 min, ale systém akceptuje i kratší pauzy.

Možné příčiny a řešení:

Příčina	Řešení
Není vyplněna hodnota	V záložce "Uživatelská práva" zkontrolujte sloupec Minimální délka pauzy. Musí být číselná hodnota (např. 30), ne prázdné pole.
Ruční zápis docházky	Minimální pauza se aplikuje pouze při zapípání z terminálu. Při ručním zápisu v modulu Docházka se kontrola neprovádí.
Logika není implementována	Zkontrolujte, že kód v inc/wa_chip_inout.php obsahuje kontrolu minimální pauzy. Hledejte řádek s wa_chip_minimal_pause_min.

10.10 IP whitelist blokuje legitimní přístup

Příznaky: Čtečka nefunguje, i když je správně nakonfigurovaná. V logu je chyba "Unauthorized".

Možné příčiny a řešení:

Příčina	Řešení
IP adresa není v seznamu	V záložce "Povolené IP adresy" přidejte IP adresu čtečky. Zjistěte skutečnou IP adresu RasPi: hostname -I
Dynamická IP adresa (DHCP)	IP adresa RasPi se mohla změnit po restartu. Doporučujeme nastavit statickou IP adresu v nastavení routeru nebo na RasPi.
NAT/Proxy server	Pokud je RasPi za NAT/proxy, server vidí jinou IP. Zkontrolujte, jakou IP vidí server: echo USER_IP v logu. Přidejte tuto IP do whitelistu.
Formát IP adresy	Zkontrolujte správný formát: 192.168.1.100 Ne: 192.168.1.100:80 nebo http://192.168.1.100