Interaktívny popis systému | VILKA Access Management

📋 Prehľad systému – Čo to je a pre koho je určený?

VILKA Access Management System je komplexná webová aplikácia pre správu inteligentných zámkov značky TTLock. Systém je určený pre ubytovacie zariadenia (hotely, penzióny, apartmány, Airbnb), kancelárske budovy a akékoľvek priestory, kde je potrebné spravovať prístupy viacerých osôb.

Hlavné ciele systému

✅ Eliminácia fyzických kľúčov – žiadne straty, žiadne kopírovanie
✅ Automatizácia check-in/check-out – prístupy sa samy uzatvárajú
✅ Centrálna správa – všetky zámky na jednom mieste
✅ Kompletný audit – história každého vstupu
✅ Diaľkové ovládanie – otvorenie zámku odkiaľkoľvek

Typickí používatelia: Hotely ✦ Penzióny ✦ Apartmány ✦ Airbnb ✦ Kancelárie ✦ Ubytovne pre zamestnancov

⚙️ Technológie a architektúra

Systém je postavený na moderných webových technológiách s dôrazom na bezpečnosť a výkon.

PHP 7.4+

Backend API & databáza

MySQL

Centralizované úložisko

Bootstrap 5

Responzívne UI

JavaScript (Vanilla)

Interaktivita

TTLock API

Ovládanie zámkov

Session Auth

Bezpečné prihlásenie

👤 Používateľ
Prehliadač

🌐 PHP Backend
API & Session

🗄️ MySQL
Databáza

🔌 TTLock API
Zámky, PINy, Karty

🔒 Inteligentné zámky
TTLock kompatibilné

Architektúra: Systém funguje na princípe "cache then sync" – zámky sa načítajú z databázy pre rýchlosť, ale pri obnovení sa synchronizujú s TTLock API.

🎯 Hlavné funkčné celky

Systém je rozdelený do niekoľkých hlavných modulov, ktoré pokrývajú celý proces správy prístupov.

1. Kalendár zámkov

Tabuľkový prehľad – všetky zámky v jednom kalendári
Farebné pruhy – zelené (aktívne), žlté (budúce) prístupy
Stav zámku – batéria, gateway pripojenie, verejné dvere
10-dňový výhľad – posúvanie dopredu/dozadu

2. Správa prístupov hostí

PIN kódy – vlastné (4-8 číslic) alebo náhodne generované
RFID karty – priradenie existujúcich fyzických kariet
Časová platnosť – presný dátum a čas začiatku/konca
Rýchle predvoľby – 1-7 dní, týždeň, 10 dní
Trvalý prístup – možnosť nastaviť do roku 2099

3. Správa zamestnancov

Trvalé prístupy – pre upratovačky, údržbu, recepciu
Filter podľa mena – rýchle vyhľadávanie
Oddelená evidencia – zamestnanci vs. hostia

4. Vyhľadávanie a reporty

Globálne vyhľadávanie – podľa čísla (PIN/karta) alebo mena/miestnosti
Report aktívnych prístupov – prehľad všetkých prístupov
Export do CSV – pre účtovníctvo a štatistiky
Filter podľa dátumu – obmedzenie reportu na obdobie

5. Rýchle filtre

🚪 Voľné izby

📅 Odchod dnes

📅 Odchod zajtra

🚪 Verejné dvere

Tip: Kliknutím na ľubovoľné políčko v kalendári sa automaticky otvorí formulár pre vytvorenie prístupu s predvyplneným dátumom.

🗄️ Dátový model

Systém používa relačnú databázu MySQL s nasledujúcimi hlavnými tabuľkami:

Tabuľka `locks` – Zámky

Stĺpec	Popis
`lock_id`	Primárny kľúč z TTLock API
`lock_name`	Názov zámku z API
`lock_alias`	Vlastný názov (napr. "Izba 101")
`electric_quantity`	Stav batérie (0-100%)
`has_gateway`	Či je pripojený cez gateway
`is_public`	Verejné dvere (prístup pre všetkých)

Tabuľka `lock_pincodes` – PIN kódy

Stĺpec	Popis
`pincode`	PIN kód (4-8 číslic)
`pincode_name`	Meno hosťa
`access_type`	'guest' alebo 'employee'
`start_date / end_date`	Platnosť prístupu
`keyboard_pwd_id`	ID v TTLock API

Tabuľka `card_encoding_log` – Karty

Stĺpec	Popis
`card_number`	Číslo karty (API formát)
`original_card_number`	Pôvodné číslo karty
`guest_name`	Meno hosťa
`card_id`	ID v TTLock API

Dátová integrita: Všetky tabuľky sú prepojené cez customer_id, čo umožňuje oddelenie dát pre rôznych zákazníkov v multi-tenant architektúre.

🔌 API integrácia s TTLock

Systém je plne integrovaný s oficiálnym TTLock API, čo umožňuje priamu komunikáciu s inteligentnými zámkami.

Podporované API endpointy

Endpoint	Funkcia
`get_all_locks`	Získanie všetkých zámkov z TTLock účtu
`unlock`	Diaľkové otvorenie zámku
`create_pincode`	Vytvorenie nového PIN kódu
`get_random_pincode`	Generovanie náhodného PINu (odporúčané)
`change_pincode`	Zmena platnosti PINu
`delete_pincode`	Zmazanie PIN kódu
`add_card`	Priradenie karty k zámku
`change_card_period`	Zmena platnosti karty
`delete_card`	Odstránenie karty
`get_cards`	Zoznam kariet pre zámok

Bezpečnosť: API kľúče a prihlasovacie údaje k TTLock účtu sú uložené v databáze a nie sú prístupné z frontendu.

Dôležité: Zámky bez pripojenia ku gateway nie je možné ovládať na diaľku (otváranie, mazanie PINov). Pre plnú funkčnosť odporúčame gateway pre každý zámok.

🎨 Užívateľské rozhranie a farby

UI je navrhnuté s dôrazom na prehľadnosť a rýchlu orientáciu. Farby majú svoj význam.

Farebná schéma

🔵 Primárne akcie, aktívne prvky

🟢 Aktívny prístup, úspech, online zámok

🟡 Budúci prístup, upozornenie

🔴 Chyba, offline, nízka batéria

🟣 TTLock účet, administrátorské funkcie

Rozloženie obrazovky

┌─────────────────────────────────────────────────────────────────────────┐
│                           HLAVIČKA SYSTÉMU                               │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                      FILTRE A VYHĽADÁVANIE                       │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                       ŠTATISTIKY                                 │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                         KALENDÁR ZÁMKOV                           │   │
│  │  ┌────────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┐   │   │
│  │  │ Izba   │ Po │ Ut │ St │ Št │ Pi │ So │ Ne │ Po │ Ut │ St │   │   │
│  │  │ Izba101│ ██ │    │ ██ │ ██ │    │    │    │    │    │    │   │   │
│  │  │ Izba102│    │    │    │    │ ██ │ ██ │    │    │    │    │   │   │
│  │  └────────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┘   │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────┐ ┌─────────────────────────────────────┐  │
│  │    FORMULÁR PRE PRÍSTUP   │ │         BOČNÝ PANEL (AKCIE)         │  │
│  └──────────────────────────┘ └─────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

Responzivita: Systém funguje na desktopoch, tabletoch aj mobilných telefónoch. Na menších obrazovkách sa prvky preskupujú do stĺpca.

🏨 Typické scenáre použitia

Scenár 1: Check-in hosťa

Hosť prichádza na recepciu
Obsluha vyberie izbu v kalendári (kliknutím na kartu izby)
Zadá meno hosťa a vyberie dĺžku pobytu (napr. 3 dni)
Systém vygeneruje náhodný PIN kód (alebo použije vlastný)
Obsluha vytlačí/odošle uvítaciu správu hosťovi s PINom
Hosť používa PIN na vstup do izby počas celého pobytu

Výhoda: Žiadne fyzické kľúče, žiadne straty, automatický check-out.

Scenár 2: Automatický check-out

V čase 10:00 (predvolený odchod) platnosť PINu vyprší
Hosť už nemôže otvoriť dvere
Izba sa automaticky označí ako "voľná" v kalendári
Žiadna manuálna práca pre recepciu
Systém je pripravený na ďalšieho hosťa

Scenár 3: Upratovanie / údržba

Recepcia priradí zamestnancovi (upratovačka) prístup k izbám
Zamestnanec má trvalý prístup počas pracovnej doby
Po skončení zmeny možno prístup zrušiť
Všetky vstupy sú logované v histórii

Scenár 4: Neskorý check-out

Hosť požiada o neskorší check-out (napr. do 14:00)
Obsluha nájde hosťa v globálnom vyhľadávaní
Upraví platnosť PINu (predĺži do 14:00)
Hosť môže zostať v izbe bez problémov
Zmena sa okamžite synchronizuje so zámkom

📊 Porovnanie s konkurenciou

Funkcia	TTLock System	Manuálne kľúče	Klasické RFID
Dočasné prístupy	Automatické	Nutnosť vrátiť kľúč	Áno
Diaľkové ovládanie	Áno	Nie	Len lokálne
História vstupov	Automatická	Žiadna	Áno
Náklady na kartičky	Nízke (virtuálne PINy)	Vysoké (straty)	Stredné
Check-in bez recepcie	Áno (PIN zaslaný)	Nie	Vyžaduje kartu
Správa cez web	Áno	Nie	Obmedzená
Multi-zariadenie	Áno	Nie	Áno

Víťaz: TTLock System vyhráva v kategóriách diaľkové ovládanie, náklady a flexibilita. Jediná nevýhoda je závislosť na internetovom pripojení.

✅ Výhody a ⚠️ Nevýhody

Výhody

⚡ Rýchlosť – okamžité vytvorenie prístupu
🔒 Bezpečnosť – dočasné prístupy automaticky expirujú
📱 Bez inštalácie – webová aplikácia
🏨 Hotel ready – prednastavené časy 14:00/10:00
👥 Dvojúrovňový systém – hostia + zamestnanci
📊 Prehľadnosť – kalendár s farebnými pruhmi
🔍 Vyhľadávanie – globálne naprieč všetkými prístupmi
📄 Export – reporty do CSV
🔄 Synchronizácia – automatické ukladanie zámkov
🌐 Multi-zákaznícky – podpora viacerých subjektov

Nevýhody a obmedzenia

❌ Závislosť na TTLock API – výpadok API = nemožnosť vytvárať prístupy
❌ Vyžaduje internet – ovládanie zámkov vyžaduje pripojenie
❌ Gateway závislosť – zámky bez gateway nie je možné ovládať na diaľku
❌ Obmedzená kapacita – zámok má limit počtu PINov a kariet (cca 100)
❌ Single-point-of-failure – databáza a API sú kritické

🔐 Bezpečnostné vlastnosti

Implementované bezpečnostné mechanizmy

Vlastnosť	Implementácia
Autentifikácia	Session-based prihlásenie
Autorizácia	Kontrola `customer_id` pri každom požiadavku
Validácia vstupov	Kontrola dĺžky PINu, formátu karty, dátumu
SQL injection prevencia	Prepared statements v PHP
XSS prevencia	`htmlspecialchars()` na výstupe
CORS	API endpointy chránené session
Zálohovanie	Dáta sú centralizované v databáze
Audit log	História vstupov samostatná stránka

Zálohovanie: Dáta sú uložené v centralizovanej MySQL databáze s dennými zálohami na úrovni servera.

API bezpečnosť: TTLock API kľúče a prihlasovacie údaje sú uložené v databáze a nie sú prístupné z frontendu. Všetky API volania prebiehajú cez backend.

📌 Záver a zhrnutie

VILKA Access Management System je komplexné riešenie pre správu prístupov v ubytovacích zariadeniach. Je vhodný najmä pre:

Kľúčové prínosy

✅ Výrazné zjednodušenie procesu check-in/check-out
✅ Eliminácia rizika stratených kľúčov
✅ Kompletný audit prístupov
✅ Diaľkové ovládanie zámkov
✅ Dočasné prístupy bez fyzickej interakcie
✅ Nízke prevádzkové náklady

Budúci rozvoj: Plánovaná je integrácia s rezervačnými systémami, automatické generovanie PINov pri online rezervácii a mobilná aplikácia pre hostí.