Irányítópult

MikroCsodák Visitor Experience V2

Az új múzeumi látogatói rendszer külön projektben és külön kiadásokban készül, ezért nem keveredik a jelenlegi Legacy műsortervekkel. Futó, visszaállítási vagy Remote-hivatkozással védett kiadást csak az új V2 helyszíni aktiválása után szabad archiválni. A használaton kívüli korábbi kiadások RECALLED állapotban maradnak, snapshotjuk és a más tartalom által is használt médiafájlok megőrzésével.

Aktuális P0 runtime hiba

A 2026-09-10-i helyszíni audit két külön jelenséget talált. A Felfedező 2.0.5 43 assetes csomagja teljes, de több párhuzamos sync/reload/reconnect hívás ugyanazt a candidate cache-t törölte és újrakezdte. Ezt a Player 3.0.16 / LG 3.0.16-lg.1 single-flight mutexe javítja: az új kérés a már futó letöltéshez csatlakozik. A közben aktív, régi egy-HTML-es Digitális élményloop 2.0.27 nem csomagolta a HTML-ben használt backstage képet, ezért külön PLY_ERR_MEDIA_PRELOAD érkezett. Ez nem tárhelyhiba. A Player a last-known-good kiadást megtartja; valóban hibás csomagokra még véges retry/backoff és teljes HTML-forrás validáció szükséges.

Az elkülönített új munkaterület neve MikroCsodák – Visitor Experience V2. Új Online, Rajzverseny és Szelfi tartalom, valamint az ArenaLive Quiz integráció konfigurációja kizárólag ebbe a projektbe kerüljön; Legacy tartalmat nem mozgatunk bele.

Jóváhagyott Heritage Gold vizuális irány

A Visitor Experience V2 hivatalos iránya a mély petrolzöld vagy éjkék alap, elefántcsont tipográfia, visszafogott arany hierarchia, elegáns serif címbetű, egységes arany vonalikonok, vékony keretek és nyugodt CSS/SVG mikroanimációk. A mobilfelület nagy érintési célokat, rövid szöveget és képdomináns élménykártyákat használ.

Kötelező médiaeredet-szabály: műtárgyat, alkotót, látogatót, múzeumi teret vagy programot csak ellenőrzött, eredeti MikroCsodák-kép ábrázolhat. Generált vagy stock kép nem publikálható valódi múzeumi tartalomként; az AI-látványtervek kizárólag kompozíciós referenciák. Ugyanazt az eredeti assetet nyelvenként és műsortervenként újra kell használni, nem lemásolni.

Tervezett látogatói belépő és főmenü

A Remote belépőjén a múzeum neve, az aktív kapcsolat, a zászlós nyelvválasztó és egyetlen Élmények megnyitása CTA látható. A Mit szeretnél felfedezni? főmenü nyolc kártyája: Alkotások közelről, Minden alkotás, Hogyan készült?, A művész, Híres látogatók, Rajzverseny 2025, Randi a múzeumban és Küldj szelfit. A Kezdőlap a bemutató/reklám állandó navigációs célja, a nyelvválasztó pedig vezérlő, nem külön tartalomkártya.

Az Előző, Következő és Szünet csak az adott élményen belül jelenik meg. Minden parancs betöltési, alkalmazott vagy sikertelen visszajelzést ad; a Kezdőlap mindig elérhető. A közös műtárgy-részletnézet eredeti képet, nagyítást, betűméretet, felolvasást és biztos visszalépést kínál.

Nyelvek és későbbi bővítés

A célzott közös nyelvkészlet: HU, EN, DE, FR, IT, ES, PL, UA és HE. A szlovák nyelv csak valódi fordítással publikálható, mert a korábbi forrás magyar másolatot adott. Egy új nyelvet ugyanahhoz a logikai tartalomhoz kell hozzáadni; a közös képet vagy videót nem szabad nyelvenként lemásolni. A tervezett admin lefedettségi mátrixa élményenként TELJES, RÉSZLEGES vagy HIÁNYZIK állapotot mutat. Fallback: kért nyelv → angol → magyar; új nyelv publikálása mindig új immutable release.

Online kiállítás és Rajzverseny

Az Online kiállítás mind a 17 műtárgyat és a 9 ellenőrzött fordítást megtartja, de portrait-first, görgetésmentes TV-nézetet és telefonos műtárgykatalógust kap. A Rajzverseny 198 pályaműve nem 198 főgombként jelenik meg: korcsoport, nyertesek, közönségkedvencek, összes mű és véletlen felfedezés alapján lehet választani, majd a TV egyetlen képközpontú alkotást mutat.

Szelfi állapota

Az Álló totem oszlop kamerája jelenleg READY, az eszközszintű DEVICE_CAMERA mód engedélyezett és az aktív Totem Szelfi élmény létezik. A V2-ben még szükséges a CAMERA_START Remote-gomb, a többnyelvű és verziózott hozzájárulás, a múzeumi keretek, valamint a capture/retake/accept/download fizikai E2E. A kép megőrzése 24 óra, a letöltési link 60 perc. Kamera-hiba nem állíthatja meg a többi tartalmat.

Quiz állapota

A korábbi „Kvíz bemutatása” csak diás bemutató volt, nem működő játék. A végleges termékdöntés szerint a Quiz tartalmát, pontozását és játékmenetét az ArenaLive szolgáltatja. A KioskPilot feladata a tenant/site/zone mapping, a rövid életű display- és participant-token, az aktuális locale átadása, a Player és telefonos handoff, valamint a kilépés vagy hiba utáni biztos visszatérés a Kezdőlapra.

Aktív Quiz Remote-gomb csak teljes, egészséges ArenaLive capability és sikeres end-to-end UAT után jelenhet meg. Addig alapértelmezetten rejtett; külön marketingbeállítással inaktív Hamarosan kártya mutatható, amely nem indít hibás vagy félkész élményt.

Átállási sorrend

1. Külön V2 projekt, archív nézet és új Remote információs architektúra.
2. Dinamikus nyelvkatalógus és lefedettségi mátrix.
3. Online kiállítás V2, majd a már előkészített eszközkamerás Szelfi.
4. Rajzverseny V2, majd stabil contract esetén ArenaLive Quiz integráció.
5. Helyszíni Browser/HDMI-stick UAT, aktiválás, Legacy recall és 14 napos stabilitás.

A részletes végrehajtási terv fájlja: MIKROCSODAK_VISITOR_EXPERIENCE_V2_PLAN_2026-09-10.md.

Múzeumi Sales Showcase és Élményloop 16:9

Két külön célú megoldás létezik. A Múzeumi élményloop 16:9 V2 a későbbi, szerkeszthető közös sablon. A MikroCsodák Sales Showcase 16:9 szándékosan nem szerkeszthető, márka-specifikus értékesítési referencia: a feltöltött mintához igazodó fix kompozíciót, egységes vonalas ikonrendszert, valódi múzeumi képeket, finom fényeket, csillogást és lassú animációkat használ.

UX-alapelv: a nagy kijelző adja az élményt, a telefon csak vezérli azt.

Hol található és hogyan használható?

1. A Tenant App Médiatár oldalán nyisd meg a HTML Tartalom Varázslót; a képeket később a közös MediaPickerben bármely projektmappából kiválaszthatod.
2. Válaszd a HTML Tartalom Varázsló → Múzeumi élményloop 16:9 V2 sablont.
3. Válassz külön WOW nyitóképet, kiemelt műtárgyképet és Tudtad?-részletképet. Mindhárom mező mappás tallózást, keresést, előnézetet és fájlmetaadatokat kínál.
4. Szerkeszd a főcímet, WOW-mondatokat, két rövid tényt, műtárgycímet/hordozót, visszavezető CTA-t, három csatlakozási lépést és az akcentusszíneket.
5. Mentsd a HTML-t, készíts belőle verziózott tartalmat és publikált műsortervet. Offline lejátszáshoz minden hivatkozott kép és logó legyen BACKGROUND asset.

Jelenetek és mozgás

Az alap loop 78 másodperc és hét jelenet: makró WOW-nyitás, Tudtad?, QR-csatlakozás, három lépés, szolgáltatások, kiemelt műtárgy, majd túra/játék CTA. A mozgás csak GPU-barát transform és opacity animációkat használ; nincs agresszív flash, külső font vagy külső JavaScript. A prefers-reduced-motion beállítás kikapcsolja a folyamatos animációt.

A QR jobb-középső safe area végig szabad marad. A QR pixeltérkép nem mozog és nem torzul; csak a Player kártyájának környezete kap finom glow-t. A jelenetek és kompozíció változása burn-in ellen is segít.

Élő QR és kapcsolódott állapot

A HTML nem generál saját QR-kódot. A Player 3.0.9 / LG 3.0.9-lg.1 a kijelző aktuális visitor sessionjéből rajzolja az élő QR-t. A fix referencia külön SHOWCASE QR-módot kér: a jobb oldali, hangsúlyos üvegkártyába nagy, mozdulatlan és jól olvasható QR kerül. Közvetlen beolvasáskor nincs PIN; a kpgo.pro kézi megnyitásakor a TV-n látható kódot kell megadni.

Kapcsolódáskor a Player KIOSKPILOT_VISITOR_STATE üzenetet küld kizárólag az aktív HTML iframe-nek. A V2 loop ilyenkor megáll, elrejti a QR-t és „A kijelző most a te kezedben van” állapotot mutat. Bontáskor automatikusan visszaáll az idle loop és az élő QR.

MikroCsodák értékesítési referenciapéldány

A MikroCsodák – Értékesítési referenciaélmény 1.2.0 PUBLISHED / VALID kiadás az aktuális bemutatópéldány. Egyetlen, 24 órás fix képernyő: felül nagy „Keltsd életre a kijelzőt!” cím; balra telefon és TV valódi műtárgyképekkel; középen három kapcsolódási lépés; jobbra élő QR; alul öt szolgáltatáskártya és márkázott footer. A HU/EN nyelvváltás és a kapcsolódott állapot működik. Nincs automatikusan kijelzőhöz rendelve.

A csomag a meglévő Karaván, Virágzó ág, aranybolha és hivatalos wordmark fájlokat használja újra, ezért a kiadás egyetlen új fizikai fájlja a 20 850 byte-os HTML; képduplikáció: 0. Az 1.1.0 hétjelenetes V2 és az 1.0.0 első változat immutable rollbackként megmaradt. Regresszió: npm run test:museum-sales-showcase, npm run verify:player-low-memory, npm run verify:lg-player.

HDMI stick és LG

Értékesítési és éles telepítéshez a javasolt út a KioskPilot által kezelt HDMI stick modern Chromium/WebView runtime-mal: stabilabb animáció, több memória és kiszámíthatóbb offline tárhely. Az LG lgplayer.html továbbra is használható otthoni kompatibilitási tesztre; Chromium 53 célra fordított bundle-t kap, és a sablon régebbi motoron is olvasható fade/statikus fallbacket biztosít.

Ellenőrzések: npm run test:museum-experience-loop-template, npm run test:museum-sales-showcase, npm run verify:player-low-memory, npm run build:lg-player, npm run verify:lg-player. Az 1.2.0 publikáló alapból dry-run; apply csak explicit UPGRADE_MIKROCSODAK_SALES_REFERENCE_SHOWCASE megerősítéssel indítható.

2. Android TV & Kioszk Integráció

Ez a dokumentum a TV-alkalmazás (Android TV app) és a mobilalkalmazás számára írja le a központi API és WebSocket csatlakozási és kommunikációs protokollját.

Csatlakozás és Hitelesítés

A csatlakozás a szerverhez biztonságos WebSocket (wss://) protokollon keresztül történik:

• Kapcsolódási végpont: wss://api.kioskpilot.cloud/ws/device/{deviceToken}
• Hitelesítés: A hitelesítés a URL-ben megadott deviceToken alapján automatikusan megtörténik.

Sikeres hitelesítés után a szerver a kijelző státuszát automatikusan ONLINE állapotba állítja az adatbázisban, és a következő választ küldi vissza:

{
	  "event": "auth_success",
	  "deviceId": "UUID_AZONOSÍTÓ",
	  "message": "Eszköz hitelesítve!"
	}

Kijelző párosítása és hibaellenőrzése

Browser Player megjegyzés: a kezelőfelületi „Tartalom újraszinkronizálása” / reload alias a Browser Playerben device.reload-ra normalizálódik, és az immutable release manifestet szinkronizálja; nem tölti újra a Player HTML alkalmazást. Új Player-verzió érvényesítéséhez device.restart szükséges. A siker a következő heartbeat appVersion mezőjében ellenőrizendő. A device.clear_cache csak sérült helyi release-cache hibakeresésére való, normál verziófrissítéshez nem szükséges.

1. A Player POST /v1/devices/pairing-code kéréssel 10 percig érvényes KP-XXXXXX kódot és ideiglenes device UUID-t kér.
2. A Tenant App jogosult adminja a POST /v1/devices/pair végponton elküldi a kódot, nevet, helyet és display profilt.
3. Az API egy tranzakcióban létrehozza a kijelzőt, a kanonikus kp_device_release_states sort, credentialt és device tokent.
4. A Player pollinggal egyszer veszi át a secretet, tokent és display profilt; az API ezután törli a pairing kódot.

Sikertelen admin-próbánál a Tenant App fókuszált, képernyőolvasóval is érzékelhető panelen mutatja a felhasználói üzenetet, a stabil hibakódot és a rövid hivatkozási azonosítót. Ugyanezt a pairing rekordból a Player pollingja is megkapja, és piros státuszsávban megjeleníti a kijelzőn. A technikai stack nem kerül klienshez; csak a szervernaplóban kereshető vissza a hivatkozási ID alapján. A kód lejártáig újra lehet próbálni, siker esetén a korábbi hiba törlődik.

A teljes regresszió: npm run test:device-pairing-api. A teszt saját kódot generál, végigviszi a tenant-párosítást és az egyszeri Player credential-átvételt, ellenőrzi az IDLE release-state sort, majd kontrollált duplikált eszközhibával igazolja a közös DEVICE_PAIRING_FAILED Tenant/Player feedback contractot. Végül eltávolít minden ideiglenes eszköz-, pairing- és auditadatot. A 2026-08-12-én javított ensureDeviceReleaseState is not defined backendhiba hiányzó route-import volt; a párosítás tranzakciója helyesen rollbackelt, ezért félkész kijelző nem maradt.

LG webOS böngészős Player

LG TV beépített böngészőjében a https://kpgo.pro/lgplayer.html útvonalat kell használni. Ez külön, Babellel Chromium 53 szintre fordított Player bundle; a modern player.html változatlan marad. A legacy oldal ES5 bootstrap hibapanelt és flexbox layout fallbacket is tartalmaz, ezért bundle-betöltési vagy indulási hiba esetén a kijelzőn konkrét LG_PLAYER_BOOT_FAILED vagy LG_PLAYER_BOOT_TIMEOUT kód jelenik meg.

Támogatási cél: webOS TV 4.x vagy újabb. Az LG hivatalos motorlistája szerint ez Chromium 53-tól indul; webOS 5 Chromium 68, webOS 6 Chromium 79. A webOS 3 és régebbi motorokra nincs production garancia. A kanonikus forrás továbbra is a player.html; minden Player-módosítás után kötelező npm run build:lg-player, majd npm run verify:lg-player. A teljes npm run build:all automatikusan újragenerálja az LG változatot.

Az LG Player API- és WebSocket-forgalma azonos eredetű átjárón közlekedik: https://kpgo.pro/v1/* és wss://kpgo.pro/ws továbbít a belső API-nak. Így a régi webOS motor nem kapcsolódik közvetlenül az api.kioskpilot.cloud domainhez, és nem akad el cross-origin TLS/CORS korlátozáson. Ha a böngészőben nincs natív fetch, az LG bootstrap XMLHttpRequest-alapú tartalékot biztosít. A PAIRING_CODE_NETWORK_ERROR azt jelzi, hogy a Player a párosítási kód kérésekor egyáltalán nem kapott HTTP-választ; ilyenkor frissítsd teljesen az LG oldalt, ellenőrizd, hogy a Player verzió legalább 3.0.7-lg.1, majd nézd meg a kpgo és API PM2-folyamatot. Az átjáró szerverhibája külön KPGO_API_PROXY_FAILED kódot és HTTP 502 választ ad.

A webOS beépített böngésző Cache Storage API-ja egyes TV-ken hiányzik vagy 0%-nál válasz nélkül marad. Az LG Player ezért a release fájljait saját IndexedDB-alapú cache-rétegben tárolja; támogatja a Player által használt open, put, match, keys és delete műveleteket. A 3.0.5-lg.3 verziótól a letöltés nem használ natív window.caches hívást. Ha a szinkronizáció mégis sikertelen, a Player előbb FAILED / PLY_ERR_SYNC_FAILED állapotot és konkrét hibaüzenetet küld a szervernek, csak utána próbálja törölni a félkész cache-t; így a diagnosztika nem marad néma PENDING 0% állapotban.

A 3.0.5-lg.4 verzió a release média URL-jeit is same-origin címre írja át: az api.kioskpilot.cloud/uploads/... forrásból kpgo.pro/uploads/... lesz. A kpgo /uploads útvonala a kanonikus apps/api/uploads médiatárat szolgálja ki. Ez megszünteti azt a régi webOS cross-origin hibát, amely az első fájlnál Failed to fetch üzenettel állította le a letöltést. A MikroCsodák LG-re kijelölt release-ének publikus ellenőrzése 34/34 fájlnál HTTP 200, pontos méret és helyes SHA-256 checksum eredményt adott.

A 3.0.5-lg.5 verzió a crypto.subtle.digest nélküli régi webOS motorokhoz tiszta JavaScript SHA-256 fallbacket ad. A Cannot read property 'digest' of undefined hiba Web Crypto kompatibilitási probléma, nem tárhelyhiány. A Player a gyors Web Crypto ágat használja, ha elérhető, különben automatikusan fallbackre vált. A MikroCsodák kijelölt release-ének mind a 34 fájlja sikeresen átment a publikus HTTP/méret ellenőrzésen és a fallback SHA-256 validáción is.

A 3.0.7-lg.1 memória-kímélő, két rétegű lejátszást használ: egyszerre csak a most látható és a következőként előkészülő média van a DOM-ban. A jelenlegi kép vagy HTML addig látható marad, amíg a következő elem load, videónál canplay eseményt nem ad; ezután rövid áttűnés következik, a régi réteg pedig felszabadul. Az első elemig márkázott előkészítő képernyő látszik fekete oldal helyett. A 20 másodpercen belül be nem tölthető elem PLY_ERR_MEDIA_PRELOAD eseményt jelent; ha van működő aktuális elem, az képernyőn marad, a hibás elemet a Player átugorja.

Platform Admin kijelző-hibadiagnosztika

Az Eszközök & Diagnosztika nézet bérlőnként és kijelzőnként mutatja a kapcsolatot, a kívánt és aktív release-t, a százalékos/fájlszintű előrehaladást és a Player hibakódját. A felső kártyák összesítik az online, telepítés alatt álló és beavatkozást igénylő kijelzőket. A rendszer a FAILED/ROLLED_BACK állapot mellett azt is hibának jelöli, ha egy eltérő kívánt release PENDING, DOWNLOADING, VERIFYING, READY vagy ACTIVATING állapotban több mint 10 perce nem frissült.

A Diagnosztika gomb megmutatja a TV-n látható normalizált hibakódot – például PLY_ERR_SYNC_FAILED –, a nyers backendkódot, hibaüzenetet, release-állapotot, fájlszámot, időpontokat, heartbeatet, Player/runtime verziót, IP/latency és erőforrásadatokat, valamint célzott teendőjavaslatot. Az elmúlt 30 perc Proof of Play FAILED eseményei – köztük a PLY_ERR_MEDIA_PRELOAD – friss lejátszási hibaként akkor is láthatók, ha a release maga aktív maradt. Az Összefoglaló másolása gomb telefonos vagy ticketes ügyfélszolgálati átadáshoz készít egységes szöveget. A régi RELEASE_SYNC_FAILED rekordokat a felület visszafelé kompatibilisen PLY_ERR_SYNC_FAILED TV-kódként jeleníti meg; az új Player már közvetlenül ezt a kódot jelenti.

Érvénytelen párosítás kezelése

Ha a Player bármely device-auth végponton 401 választ kap - például heartbeat, release manifest lekérés vagy aktív release visszajelzés közben -, akkor a kijelzőt törölt vagy érvénytelenített párosításként kezeli. Ilyenkor törli a helyi párosítási adatokat (deviceId, secret, deviceToken, display profil, aktív release azonosító), leállítja a futó időzítőket/WebSocketet, majd visszatölti a párosítási képernyőt.

Release ütemezés és telephelyi idő

Az ütemezés kizárólag publikált, változtathatatlan release-re mutat. A korábbi műsorterv-gyökér alapú schedule út megszűnt, ezért egy műsorterv későbbi publikálása nem módosítja észrevétlenül a már időzített tartalmat.

A Player és a Visitor Remote ugyanazt a szerveroldali resolvert használja. A helyi napot és időt a kijelző telephelyének IANA időzónája határozza meg. A resolver kezeli a dátumtartományt, heti napokat, egész napos és éjfélen átnyúló idősávot, valamint a device > zone > site specificitást és az 1-10 prioritást.

A Tenant App csak publikált kiadást kínál az Ütemezés nézetben, megmutatja az effektív időzónát, és mentés előtt jelzi az azonos célponton átfedő szabályokat. Ellenőrzés: npm run verify:schedule-db és npm run test:schedule-timezone.

Meglévő kijelző telephelye és zónája utólag a Tenant App Kijelzők → Hely & zóna gombjával módosítható. A zónalistában csak a kiválasztott telephely zónái jelennek meg. Az API tenant-scope-ban ellenőrzi mindkettőt, DEVICE_LOCATION_UPDATE auditot ír, újraszámolja a közvetlen kijelző → zóna → telephely ütemezési precedenciát, majd online Playernek device.sync_release jelzést küld.

Szervertől érkező parancsok fogadása

A TV alkalmazásnak végre kell hajtania a WebSocket csatornán érkező következő parancsokat:

A kanonikus üzenetboríték mind a type, mind a command mezőt tartalmazza azonos parancsnévvel, továbbá kötelező commandId-t és beágyazott payload objektumot ad. Az Android kliens a type mezőt használja elsődlegesen, a Browser Player mindkettővel kompatibilis.

{
  "type": "device.set_language",
  "command": "device.set_language",
  "commandId": "UUID",
  "payload": { "lang": "en", "timeoutSeconds": 3600 }
}

1. URL betöltése / módosítása (device.open_url): A kijelző kezdőoldalának beállítása vagy távoli módosítása.

   { "command": "device.open_url", "url": "https://kioskpilot.cloud/..." }

2. Tartalom újraszinkronizálása (device.reload): A Browser Player újraolvassa és szükség szerint szinkronizálja a desired/active release manifestet. Natív kliens implementációja újratöltheti a WebView-t, de erre a szerver nem támaszkodik.

   { "command": "device.reload" }

3. Gyorsítótár törlése (device.clear_cache): Törölje a WebView gyorsítótárát, majd töltse újra az oldalt.

   { "command": "device.clear_cache" }

4. Képernyőkép kérése (device.screenshot): Készítsen képernyőképet a futó WebView-ról, majd küldje be base64 JPEG-ként az API-nak.

   { "command": "device.screenshot" }

5. Release szinkron (device.sync_release): Kérje le és aktiválja a kijelző effektív desired release-ét.
6. Nyelvváltás (device.set_language): Ideiglenes nyelvi felülírás lang és timeoutSeconds payload-dal.
7. Hangerő és fényerő: device.set_volume, illetve device.set_brightness 0-100 közötti value mezővel.
8. Player újraindítása (device.restart): A Player/WebView újratöltése terminális ACK után; Browser Player-verzióváltáshoz ezt kell használni.
9. Vészleállítás (device.emergency_stop): Az aktuális lejátszás megszakítása és biztonságos fallback megjelenítése.

Release Állapotjelentés

A Player a PENDING → DOWNLOADING → VERIFYING → READY → ACTIVATING → ACTIVE fázisokat jelenti. A desired és active release külön mező; az ACTIVE csak sikeres helyi atomikus aktiválás után küldhető. Hiba esetén FAILED vagy ROLLED_BACK érkezik hibakóddal, miközben a korábbi aktív kiadás megmarad. A párhuzamos heartbeat/release-state írásokat a szerver rendezett zárolással és legfeljebb három deadlock/lock-timeout tranzakciós próbával kezeli. A hibás manifest checksum elvárt 409 MANIFEST_CHECKSUM_MISMATCH kliensválasz, nem szerverhiba; az 5xx hibák továbbra is a PM2 error logba kerülnek.

Player pilot preflight és fizikai UAT

A MikroCsodák pilot szerveroldali kapuja a npm run audit:player-pilot -- --device=01 --output=audit/player-pilot-preflight.json paranccsal ellenőrizhető. Az audit read-only: desired/active/previous release, deployment, minden release-fájl létezése, mérete és checksumja, Proof of Play lefedettség, függő parancs, Player-verzió, natív Android forrás és headless böngésző jelenléte kerül a riportba.

Az automatizált preflight nem helyettesíti a fizikai tesztet. A kijelzőnek ONLINE állapotban kell lennie, majd online hidegindítás, hálózat nélküli cache-elt hidegindítás, reconnect, parancs-ACK, kétirányú release-váltás és dedikált hibás teszt-release rollback szükséges. Valós aktív release assetet tilos a rollback-teszthez megrongálni. A részletes jegyzőkönyv: PLAYER_PILOT_UAT_2026-08-12.md.

Auth pool tranzakciós biztonság

Az érvénytelen refresh token 401-es ága minden megkezdett tranzakciót rollbackel, mielőtt a kapcsolat visszakerül a poolba. Enélkül a kapcsolat REPEATABLE READ snapshotja későbbi API-kérésekben elrejthette a frissen párosított eszközt vagy credentialt. Regresszió: npm run test:auth-refresh-transaction; 12 párhuzamos invalid refresh után a friss eszköz- és device-auth rekordnak azonnal láthatónak kell lennie.

3. Ubuntu 24.04 + HestiaCP Szerver-beállítások

Ez az útmutató segít beállítani és optimalizálni a HestiaCP alapú Ubuntu 24.04-es szervert a modern fejlesztési és éles munkafolyamatokhoz.

SSH Hozzáférés és Biztonság

A biztonságos SSH eléréshez szerkeszd a szerveren a /etc/ssh/sshd_config fájlt:

PasswordAuthentication no
PubkeyAuthentication yes
PermitRootLogin no

FONTOS: Az SSH démon újraindítása előtt (sudo systemctl restart ssh) mindig nyiss meg egy másik terminált és teszteld az új beállításokkal való belépést, nehogy kizárd magad!

Telepítések a Szerverre

Lépj be SSH-n keresztül, és telepítsd a következő alapvető fejlesztési függőségeket:

• NVM (Node Version Manager):

  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
  source ~/.bashrc
  nvm install --lts

• Composer (PHP csomagkezelő):

  sudo apt update && sudo apt install composer -y

Teljesítmény finomhangolása (OPcache & Redis)

A villámgyors válaszidőkért engedélyezd a PHP OPcache-t és telepítsd a Redis szervert:

sudo apt install redis-server php-redis -y
sudo systemctl enable redis-server

4. Camera Experience

A Camera Experience a látogatói fotózási folyamatot kezeli a Visitor Remote sessionhöz kötve. A séma telepítve van: kp_camera_experiences, kp_camera_sessions, kp_camera_captures, kp_camera_download_tokens, kp_camera_events.

Elérhetőség és Jogosultság

A kamera nem automatikusan elérhető minden bérlőnél és minden kijelzőn. Az effektív kameraelérhetőség három egymásra épülő kapu eredménye:

1. Előfizetés: a bérlő előfizetése aktív, és a csomagverzió vagy tenant override engedélyezi a feature_camera_exp funkciót.
2. Telepítés: az adott tenant, telephely, zóna vagy eszköz konfigurációja engedélyezi a kamerát és a használható módot (VISITOR_CAMERA, DEVICE_CAMERA vagy mindkettő).
3. Futásidejű képesség: kijelzőkamera esetén az eszköz ténylegesen rendelkezik kamerával, és a kameraengedély használható.

A funkció csak akkor indítható, ha mindhárom szükséges kapu engedélyezett. A kliens géppel kezelhető állapotot kap, például SUBSCRIPTION_DISABLED, INSTALLATION_DISABLED, CAPTURE_MODE_DISABLED, NO_CAMERA, PERMISSION_DENIED, DISCONNECTED, TIMEOUT vagy READY.

A telepítési konfigurációt a kp_camera_installation_settings tárolja. A feloldási sorrend DEVICE > ZONE > SITE > TENANT; a legkonkrétabb létező beállítás nyer, új telepítés pedig alapból tiltott. A Player által jelentett futásidejű állapot a kp_device_camera_capabilities táblába kerül. Kapcsolódó végpontok: GET /camera/access, GET/PUT /camera/installations, GET /camera/devices/config és POST /camera/devices/capability.

Telepítés: database/migrations/019_camera_installation_settings.sql. A migráció az aktív kameraélménnyel már rendelkező tenantok működését tenant-szintű engedéllyel őrzi meg; minden új konfiguráció kifejezett engedélyezést igényel.

Capture Módok

• VISITOR_CAMERA: a látogató telefonja készíti és tölti fel a képet a kpGo PWA-ból.
• DEVICE_CAMERA: a látogató hozzájárulása után a kijelző vagy kioszk készíti és tölti fel a képet device authentikációval.

A Visitor Remote profilban a CAMERA_START egyetlen, felhasználóbarát kameraengedély. Szerveroldalon umbrella-jogként engedélyezi a teljes kamera-életciklust: CAMERA_CAPTURE, CAMERA_RETAKE, CAMERA_ACCEPT és CAMERA_CANCEL. Ezeket nem kell külön admin checkboxként kezelni.

Hozzájárulás és Letöltés

A látogató a kpGo felületen fogadja el az élményhez tartozó consent_title és consent_text szöveget. A capture után az API letöltési tokent hoz létre a kp_camera_download_tokens.token_hash mezőben, a publikus fotó URL pedig a kpgo.pro/photo/{token} útvonalon nyílik.

DEVICE_CAMERA módban a letöltési token a capture azonosítóból szerveroldali HMAC-kel újraépíthető, ezért a látogatói GET /camera/visitor/sessions/:id válasz API restart után is vissza tudja adni a download URL-t. Régi, memóriában tartott session download map továbbra is kompatibilis, de nem szükséges az új device-camera flow-hoz.

Regressziós Ellenőrzés

A DB séma ellenőrzése: npm run verify:camera-db. A device-camera letöltési lánc restart-határral együtt tesztelhető: CAMERA_SMOKE_RESTART=1 npm run smoke:camera-device. A smoke ideiglenes entitlement override-ot, eszközszintű telepítési engedélyt, kamera-képességet, kameraélményt és teszt capture-t hoz létre, majd visszaállítja az eredeti állapotot.

Valós Browser Player hardverpróba 2026-07-24: az InkognitóAblakTeszt kijelző kamera API támogatást, jelen lévő kamerát, GRANTED engedélyt és effektív READY állapotot jelentett. A tartós teszt fixture ismételhető parancsa: npm run setup:camera-test.

5. Előfizetési és Szerepkör Jogosultságok

Egy funkció akkor használható, ha a felhasználó szerepköre és a tenant effektív előfizetési jogosultsága is engedélyezi. Az effektív entitlement a csomagverzióból és az opcionális tenant override-ból áll elő; inaktív előfizetésnél a feature tiltott.

Feature Kulcsok

• feature_visitor_remote: Visitor QR session, profil és látogatói vezérlés.
• feature_staff_remote: Staff Remote eszközlista, kijelzőparancsok és visitor session beavatkozások.
• feature_camera_exp: Camera Experience, a külön telepítési és hardverkapukkal együtt.
• feature_analytics: Proof of Play riport, statisztika és export.
• feature_api_access: API-kulcsok és inbound integrációs parancsok.
• feature_webhooks: webhook végpontok és kézbesítési naplók.
• feature_white_label: tenant arculat módosítása.
• feature_sso: fenntartott entitlement; az SSO runtime még nincs implementálva.

Szerepkörök és API Kapuk

A Staff Remote felületet STAFF, STAFF_MANAGER és TENANT_ADMIN használhatja, de csak aktív feature_staff_remote mellett. A visitor profilokat kizárólag tenant adminisztrátor kezelheti. A VIEWER nem küldhet kijelzőparancsot és nem avatkozhat visitor sessionbe.

A feature-rel védett végpont tiltáskor 403 FEATURE_NOT_AVAILABLE választ ad a feature kulccsal. A Platform Admin override-listája ugyanazt a nyolc feature kulcsot használja, mint a Tenant App előfizetési nézete és az API entitlement feloldója.

Platform Technikai Tenant

A PLATFORM_SUPER_ADMIN tagság adatbázis-integritás miatt egy külön KioskPilot Platform technikai tenanthoz tartozik. Ez nem előfizető, nincs előfizetése vagy ügyféltartalma, és az API kizárja az előfizetői listából. A csomagváltási végpont is tiltja: 403 TECHNICAL_TENANT_FORBIDDEN. Új ügyfelet mindig a Platform Admin előfizető-létrehozási folyamatával kell felvenni.

Visitor Remote Tartalomvezérlés

A Tenant App kijelzőnkénti Távirányító beállításában külön engedélyezhető az Előző (PREV), Következő (NEXT) és Diaválasztás (SELECT_ITEM). A kpGo csak az engedélyezett vezérlőket jeleníti meg, az API pedig minden műveletnél újra ellenőrzi a profil allowlistjét.

Az aktív kiadás tartalmaihoz ugyanebben az ablakban saját látogatói gombfelirat, ikon és láthatóság állítható. A gomb kizárólag az adott kijelző aktív manifestjében szereplő médiát indíthatja. A többnyelvű médiafájlok egy logikai tartalomgombként jelennek meg; a kiválasztott látogatói nyelvet a Player alkalmazza. Tetszőleges külső URL látogatói gombként nem engedélyezett.

A metadata a kp_media.visitor_remote_visible, visitor_remote_title és visitor_remote_icon mezőkben él. A profilválasz items listája csak az aktív kiadás biztonságosan indítható tartalmaiból épül fel. Regresszió: TST-025 ellenőrzi a PREV, NEXT és SELECT_ITEM Player ACK láncot.

Csomagverziók, Limitek és Árak

A Csomagok & Limitek nézetben új csomag hozható létre, illetve módosítható a csomag neve, leírása, aktív állapota, hat limitje, nyolc szolgáltatása, valamint havi és éves HUF ára. A csomag slugja létrehozás után nem változtatható.

Minden mentett módosítás új, megváltoztathatatlan kp_plan_versions verziót készít. Az új előfizetés és a későbbi kézi csomagváltás mindig a legfrissebb verziót kapja; a meglévő előfizetők nem kerülnek automatikusan új árra vagy limitekre. Ez megakadályozza a csendes szerződésmódosítást. A verzióelőzmény a szerkesztőablakban látható.

Inaktivált csomag új előfizetéshez nem választható, de a már azon lévő előfizetők és korábbi verzióik megmaradnak. A létrehozás PLAN_CREATED, a módosítás PLAN_VERSION_CREATED audit eseményt ír. Kapcsolódó végpontok: GET/POST /platform/plans, PUT /platform/plans/:planId és GET /platform/plans/:planId/versions.

Fejlesztési Frissítési Szabály

Új vagy módosított feature esetén együtt kell frissíteni az API entitlement contractot, a Platform Admin csomag- és override nézetét, a Tenant App elérhetőségi állapotát, az érintett kpGo/Player/Staff felületet, az automatizált contract ellenőrzést, ezt a súgót és a user_task_list.md élő teendőlistát.

6. PM2 Futáskörnyezet & Háttérfolyamatok

A KioskPilot V3 monorepó szolgáltatásai a háttérben PM2 folyamatkezelő alatt futnak.

Aktív PM2 Folyamatok

Háttérmunkás (Worker) indítása

A médiafeldolgozást, a Camera Experience retention takarítását és a webhook kézbesítést a háttérben futó worker kezeli. A Proof of Play eseményeket az API fogadja és tárolja; azok nem worker-jobként érkeznek. A worker indítása a projekt gyökérkönyvtárából:

pm2 start ecosystem.worker.config.js
pm2 status kioskpilot-worker

Adatbázis Migrációk

Éles környezetben az API nem futtat automatikus DDL műveleteket. A verziózott database/migrations/*.sql fájlokat root vagy külön DBA/migration felhasználó telepíti, az alkalmazás kpilot_app felhasználója pedig szándékosan csak SELECT, INSERT, UPDATE és DELETE jogot kap. A dedikált kpilot_migrate kizárólag a kpilot_core sémán kap DDL-jogot. A npm run migrate automatikusan betölti a ~/.config/kioskpilot/migration.env 600-as jogosultságú hitelesítését; egyedi hely a KIOSKPILOT_MIGRATION_ENV változóval adható meg. Runtime route nem hozhat létre és nem módosíthat táblát.

A migration history és az élő séma egyezése a projekt gyökeréből a npm run verify:manual-migrations paranccsal ellenőrizhető. Az ellenőrzés alapból read-only. A --apply kapcsoló kizárólag teljes oszlop-, index-, idegenkulcs- és backfill-fingerprint egyezésnél írhat hiányzó history sort; DDL-t nem futtat és üzleti adatot nem módosít. A 2026-07-24-i DB-REC-01 rendezés után a kézzel telepített 016_visitor_action_events.sql, 017_visitor_controller_state.sql, 018_media_visitor_settings.sql és 019_camera_installation_settings.sql history-bejegyzése konzisztens.

A projektmappa-séma 024_projects_and_folders.sql migrációja naplózott. A korai 025_seed_totem02_flow.sql hibás, verziózás előtti teszt seed volt; most dokumentált történeti no-op, ezért migráció soha nem hoz létre tenant üzleti tartalmat. A valós múzeumi fixture csak az explicit reset:museum-content, import:backstage-museum és import:online-exhibition munkafolyamatokkal kezelhető.

A runtime séma-szerződés ellenőrzése: npm run verify:runtime-schema-contract. Ez igazolja, hogy aktív API route nem futtat projekt-DDL-t, nem hivatkozik a megszűntetett kp_playlist_items táblára, és a médiahasználat a kanonikus ContentVersion/PlaylistVersion/Release/Schedule láncon oldódik fel.

Runtime titkok és JWT rotáció

Productionben a JWT_SECRET kötelező, erős, egyedi környezeti titok. Az API 2026-08-12 óta fail-closed: hiányzó vagy 64 karakternél rövidebb kulccsal nem indul el, és nincs forráskódbeli fallback. A rotáció a projekt gyökeréből az npm run security:rotate-jwt -- --confirm=ROTATE_KIOSKPILOT_JWT_SECRET paranccsal végezhető. A segéd 0600-as rollback másolatot készít, kriptográfiai kulcsot generál annak kiírása nélkül, atomikusan frissíti a .env-et és törli a kp_sessions refresh sessionöket.

A rotáció minden aktív Admin/Tenant munkamenetet megszakít, ezért utána pm2 reload all --update-env, teljes újrabejelentkezés és auth-smoke szükséges. A 2026-08-12-i első éles rotáció 58 refresh sessiont vont vissza; a régi fallback token 403, az új teszttoken 200, a visszavont refresh token 401 eredményt kapott. A titok értéke naplóba, dokumentumba vagy verziókezelt fájlba nem kerülhet.

Kódfrissítés és Ellenőrzés

Kódmódosítás után a szerveren minden PM2 folyamatot újra kell tölteni, majd ellenőrizni kell az API health végpontot és a hét folyamat állapotát:

ssh root@80.211.223.119 "su - kpilot -c 'cd /home/kpilot/web && pm2 reload all'"
curl -fsS https://api.kioskpilot.cloud/health
pm2 status

Ha a távoli root SSH kulcshitelesítés hibás, a reload nem tekinthető igazoltnak. A szerveren helyben, kpilot felhasználóként kell futtatni a cd /home/kpilot/web && pm2 reload all parancsot, majd külön health check és 7/7 online ellenőrzés szükséges.

7. Perzisztens Parancsok és Offline Működés

A kijelzőparancs nem egyszerű WebSocket-üzenet: minden kérés tartós kp_commands ledgerrekordot és kp_command_history állapottörténetet kap. Így az offline kijelzőre küldött, illetve hálózatváltás közben megszakadt művelet követhető és korlátozottan újraküldhető.

Állapotgép

Új parancs mindig PENDING. Csak sikeres WebSocket-küldési kísérletkor lesz SENT. A kijelző ACKNOWLEDGED, majd EXECUTING, végül COMPLETED vagy FAILED állapotot küldhet. Lejárt vagy a kézbesítési keretet kimerítő parancs EXPIRED. Terminális állapotból nincs visszalépés.

PENDING → SENT → ACKNOWLEDGED → EXECUTING → COMPLETED
                                      └──────────────→ FAILED
PENDING / SENT / EXECUTING ──────────→ EXPIRED

Offline Sor és Újrakézbesítés

• Alapértelmezett parancs-érvényesség: 5 perc.
• Legfeljebb 3 kézbesítési kísérlet; a próbák a SENT history bejegyzésekből számolódnak.
• Újracsatlakozáskor a gateway rövid ACK-várakozás után csak a nem terminális, még érvényes parancsot küldi újra.
• A commandId idempotencia-azonosító: ugyanazt a műveletet a Player nem hajthatja végre kétszer.

Player ACK Outbox és Deduplikáció

A Browser Player a terminális eredményt előbb helyi, tartós outboxba menti, és csak utána küldi WebSocketen. Reload vagy kapcsolatvesztés után az outboxot újraküldi, amíg a szerver command_status_ack választ nem ad. Az utolsó 100 terminális commandId receipttel deduplikál: ismételt kézbesítésnél a korábbi eredményt küldi vissza, a parancsot nem futtatja újra.

{
  "event": "command_status",
  "commandId": "UUID",
  "status": "COMPLETED",
  "payload": { "result": "ok" }
}

A szerver csak ahhoz az eszközhöz tartozó parancs státuszát fogadja el, amelyik a WebSocketen hitelesítette magát. Ismeretlen azonosító, érvénytelen státusz, terminális állapot felülírása vagy állapot-visszalépés elutasított.

Regressziós Ellenőrzés

npm run test:command-delivery valós adatbázison és WebSocket gateway-en ellenőrzi az online kézbesítést, offline queue-t, megszakított EXECUTING állapot utáni újraküldést, terminális ACK-ot és azt, hogy a következő reconnectkor nincs újrajátszás. A release-state konkurenciateszt: npm run test:device-release-state-api; ez 12 egyidejű ACTIVE jelentést is küld.