# PO Sem zapisuj pouze produktové a funkční požadavky v netechnickém jazyce. ## Table of Contents - [Zásady](#zásady) - [Cíl projektu](#cíl-projektu) - [Hlavní uživatel](#hlavní-uživatel) - [Základní pravidla procesu](#základní-pravidla-procesu) - [Hlavní výsledek](#hlavní-výsledek) - [Hlavní kroky procesu](#hlavní-kroky-procesu) - [Přihlášení existujícím účtem](#přihlášení-existujícím-účtem) - [Vytvoření účtu a následné přihlášení](#vytvoření-účtu-a-následné-přihlášení) - [Rozpracované registrace](#rozpracované-registrace) - [Rezervace zařízení](#rezervace-zařízení) - [Význam rezervace zařízení](#význam-rezervace-zařízení) - [Údaje potřebné pro rezervaci](#údaje-potřebné-pro-rezervaci) - [Chování při neúspěšné rezervaci](#chování-při-neúspěšné-rezervaci) - [Speciální chybové stavy](#speciální-chybové-stavy) - [UNAUTHORIZED.INVALID_INDEXA_AUTHORIZATION_CODE](#unauthorizedinvalid_indexa_authorization_code) - [FORBIDDEN.INVALID_ROLE](#forbiddeninvalid_role) - [CONFLICT.DEVICE_ALREADY_EXISTS](#conflictdevice_already_exists) - [CONFLICT.SIM_CARD_ALREADY_CONNECTED_TO_DEVICE](#conflictsim_card_already_connected_to_device) - [BAD_REQUEST.INVALID_DEVICE_IDENTIFICATION](#bad_requestinvalid_device_identification) - [UNPROCESSABLE_ENTITY.UNSUPPORTED_DEVICE_TYPE](#unprocessable_entityunsupported_device_type) - [UNPROCESSABLE_ENTITY.SIM_CARD_ASSIGNED_TO_OTHER_DISTRIBUTOR](#unprocessable_entitysim_card_assigned_to_other_distributor) - [UNAUTHORIZED.WRONG_AUTHORIZATION](#unauthorizedwrong_authorization) - [BAD_REQUEST.CONTROL_INVALID_AUTHORIZATION_CODE_FORMAT](#bad_requestcontrol_invalid_authorization_code_format) - [GATEWAY_TIMEOUT.CONTROL_DEVICE_CONNECTION_TIMEOUT](#gateway_timeoutcontrol_device_connection_timeout) - [GATEWAY_TIMEOUT.OPERATION_TIMEOUT](#gateway_timeoutoperation_timeout) - [INTERNAL_SERVER_ERROR](#internal_server_error) - [Rozhodovací mechanismus výběru dalšího kroku](#rozhodovací-mechanismus-výběru-dalšího-kroku) - [Informace o zákazníkovi](#informace-o-zákazníkovi) - [Nastavení zařízení](#nastavení-zařízení) - [Detail konfiguračního požadavku](#detail-konfiguračního-požadavku) - [Speciální chybové stavy detailu konfiguračního požadavku](#speciální-chybové-stavy-detailu-konfiguračního-požadavku) - [NOT_FOUND nebo TIMEOUT](#not_found-nebo-timeout) - [CONFLICT](#conflict) - [Ostatní chyby](#ostatní-chyby) - [Vytvoření služby](#vytvoření-služby) - [Business význam klíčových údajů](#business-význam-klíčových-údajů) - [Doplnění z testování 2026-05-27](#doplnění-z-testování-2026-05-27) ## Zásady - Popisuj cíl funkce, očekávané chování a business pravidla. - Nepoužívej technické implementační detaily. - Piš tak, aby textu rozuměl i netechnický člověk. - Pokud je něco nejasné nebo si to odporuje, nejprve se doptat. ## Cíl projektu - Cílem projektu je umožnit koncovému zákazníkovi pod distributorem Indexa zaregistrovat zařízení do cloudu a vytvořit si službu. - Po dokončení procesu musí být zařízení zaregistrované a služba vytvořená tak, aby zákazník mohl používat aplikaci MyJABLOTRON 2. ## Hlavní uživatel - Hlavním uživatelem je koncový zákazník. - Zákazník může být už v cloudu evidovaný, nebo si musí nejprve vytvořit účet. ## Základní pravidla procesu - Pokud zákazník ještě nemá účet, musí si ho vytvořit, aby mohl pokračovat v registraci zařízení. - Pokud už účet má, přihlásí se a pokračuje rovnou v registraci. - Po vytvoření účtu následuje přihlášení a pokračování v procesu registrace. - Proces typicky začíná tím, že zákazník otevře odkaz získaný z QR kódu vygenerovaného po přípravě zařízení montážním technikem. - Odkaz může obsahovat předvyplněné údaje potřebné pro zahájení rezervace zařízení. - Pokud zákazník otevře projekt bez těchto předvyplněných údajů, musí je zadat ručně. - Pokud uživatel po přihlášení nemá v seznamu žádnou rozpracovanou registraci, rovnou se mu otevře proces nové registrace. - Pokud má uživatel rozpracované registrace, ale URL obsahuje parametry pro zahájení nové registrace, i tak se otevře nová registrace (rezervace). - Pokud uživatel nemá v URL parametry pro novou registraci a současně má nedokončený objekt, zůstane na seznamu rozpracovaných registrací. - V seznamu rozpracovaných registrací má možnost přes tlačítko `Dokončit registraci` pokračovat u daného objektu tam, kde skončil, nebo tlačítkem `Registrovat` ručně zahájit proces nové registrace. ## Hlavní výsledek - Výsledkem procesu je úspěšně zaregistrované zařízení. - Současně musí být vytvořená služba navázaná na daného zákazníka. ## Hlavní kroky procesu ### Přihlášení existujícím účtem - Pokud zákazník účet má, přihlásí se a pokračuje rovnou v registraci. - Pokud zákazník vstoupil na stránku s předvyplněnými údaji pro registraci v URL, po přihlášení musí pokračovat právě s těmito údaji. ### Vytvoření účtu a následné přihlášení - Pro registraci nového účtu je povinné zadat e-mailovou adresu, registrační kód zařízení a autorizační kód. - Bez registračního kódu a autorizačního kódu nelze registraci nového účtu provést. - Nový účet se vytvoří jen pokud zadaný e-mail ještě neexistuje. - Pokud e-mail už existuje, účet se nevytvoří a uživateli odejde e-mail s informací, že účet už existuje a že se má přihlásit. - Pokud se účet vytvoří, uživateli odejde e-mail s odkazem na dokončení registrace účtu (nastavení hesla). - Po dokončení registrace účtu přes e-mailový odkaz je uživatel automaticky přihlášen a přesměrován do procesu registrace s předvyplněnými údaji (registrační kód a autorizační kód). ### Rozpracované registrace Rozhodovací větev po přihlášení: 1. Pokud URL obsahuje parametry pro zahájení nové registrace: - otevře se formulář nové registrace s těmito předvyplněnými údaji - větev seznamu rozpracovaných registrací se v tomto kroku neotevírá 2. Pokud URL parametry pro novou registraci neobsahuje: - načte se seznam rozpracovaných registrací - pokud je seznam prázdný, otevře se formulář nové registrace - chyba `NOT_FOUND` při načtení seznamu znamená validní prázdný stav (žádné rozpracované registrace), ne technickou chybu - pokud seznam obsahuje alespoň jednu položku, zobrazí se samostatný přehled rozpracovaných registrací bez současně zobrazeného formuláře nové registrace - V jednom okamžiku se zobrazuje buď seznam rozpracovaných registrací, nebo registrační proces; nikdy ne oboje současně. - V přehledu je u každé položky akce `Dokončit registraci` pro návrat do konkrétního nedokončeného objektu. - V přehledu je současně akce `Registrovat` pro ruční zahájení nové registrace. - Registrační proces lze z každého kroku přerušit a vrátit se na seznam rozpracovaných registrací. - Rozpracovaná registrace znamená, že zákazník zahájil proces, ale nedokončil ho v krocích rezervace, doplnění údajů o sobě nebo vytvoření služby. - K rozpracované registraci se zákazník může vrátit a pokračovat od místa, kde proces přerušil. - Při návratu k rozpracované registraci může upravit zadané údaje. - Pokud zákazník projde celý proces až do vytvoření služby, registrace se už mezi rozpracovanými nezobrazuje. - Zákazník může mít více rozpracovaných registrací současně. - Pro jedno zařízení může existovat jedna rozpracovaná registrace. - V přehledu rozpracovaných registrací se u každé položky zobrazuje registrační kód zařízení, datum rezervace a název instalace nebo služby. - Rozpracovaná registrace zatím nemá časové omezení. - Po úspěšné rezervaci zařízení uživatel pokračuje rovnou do dalšího kroku flow a nezůstává v přehledu rozpracovaných registrací. ### Rezervace zařízení #### Význam rezervace zařízení - Rezervace zařízení je první část registrace zařízení po přihlášení uživatele. - Uživatel v tomto kroku zadává registrační kód zařízení a autorizační kód. - Součástí rezervace je také zadání uživatelského kódu správce v zařízení. - Součástí rezervace může být také časová zóna. - Pokud zákazník přišel přes odkaz z QR kódu, mohou být tyto údaje už předvyplněné. - Smyslem rezervace je ověřit, že zařízení splňuje podmínky pro pokračování v procesu. - V rámci rezervace se ověřuje, že je možné se zařízením navázat online spojení. - Dále se ověřuje, že zařízení splňuje všechny potřebné podmínky a že jeho typ je pro tento proces povolený. - Součástí ověření je i potvrzení, že registrační údaje vznikly správným procesem po přípravě zařízení montážním technikem. - Pokud vše proběhne úspěšně, vznikne vazba mezi zařízením a distributorem a proces může pokračovat dál. - Výsledkem úspěšné rezervace je vznik objektu, se kterým se pokračuje do dalších kroků registrace. #### Údaje potřebné pro rezervaci - Pro rezervaci je povinné zadat registrační kód zařízení, autorizační kód a uživatelský kód správce v zařízení. - Součástí rezervace může být i telefonní číslo zařízení. - Telefonní číslo zařízení je volitelné, ale pokud je vyplněné, musí mít mezinárodní tvar s předvolbou `+` a bez mezer. - Pole telefonního čísla zařízení je v rezervačním formuláři vždy viditelné jako volitelné. - Pokud je telefonní číslo zařízení součástí URL odkazu, má se v rezervačním formuláři předvyplnit. - Klient detekuje časovou zónu uživatele z prohlížeče. - Pokud je detekovaná časová zóna `Europe/Berlin`, volba časové zóny se v rozhraní nezobrazuje a hodnota `Europe/Berlin` se odešle na backend skrytě. - Pokud je detekovaná jiná časová zóna, klient zobrazí select s časovými zónami podporovanými backendem a předvyplní detekovanou časovou zónu uživatele, aby ji mohl případně změnit. #### Chování při neúspěšné rezervaci - Pokud rezervace neprojde, uživatel může pokus opakovat bez omezení počtu pokusů. - Při neúspěchu se vrací jednoznačný důvod, proč rezervace neprošla. - Aplikace musí uživateli vždy srozumitelně vysvětlit, co se nepovedlo. - Součástí sdělení má být i doporučení, co může uživatel udělat, aby mohl v registraci pokračovat. - Pokud se například nepodaří navázat spojení se zařízením, má uživatel dostat informaci, že zařízení je pravděpodobně offline nebo nekomunikuje, a co má udělat pro obnovení spojení. #### Speciální chybové stavy - Tato sekce slouží jako přehled známých chyb, které mají mít v aplikaci vlastní speciální vysvětlení místo obecné chybové hlášky. - Chyby níže se vztahují přímo ke kroku rezervace zařízení (`registerIndexaReservation`). ###### UNAUTHORIZED.INVALID_INDEXA_AUTHORIZATION_CODE - Znamená, že zadaný autorizační kód neodpovídá zadanému zařízení. - Aplikace má uživateli oznámit, že nesouhlasí zadaný autorizační kód pro zadané zařízení, a vyzvat ho ke kontrole kódu obdrženého od montážního technika. ###### FORBIDDEN.INVALID_ROLE - Znamená, že zadaný uživatelský kód nepatří roli Správce systému. - Aplikace má uživateli oznámit, že pro registraci je zapotřebí zadat platný uživatelský kód Správce systému. ###### CONFLICT.DEVICE_ALREADY_EXISTS - Znamená, že zadané zařízení je v systému evidované a nelze ho znovu registrovat. ###### BAD_REQUEST.INVALID_DEVICE_IDENTIFICATION - Znamená, že zadaný registrační klíč odkazuje na neznámé nebo neplatně identifikované zařízení. - Aplikace má uživateli oznámit, že zadal neplatnou identifikaci zařízení, a vyzvat ho ke kontrole registračního klíče. ###### UNPROCESSABLE_ENTITY.UNSUPPORTED_DEVICE_TYPE - Znamená, že zařízení zadané registračním klíčem není pro tento registrační proces podporované. - Aplikace má uživateli oznámit, že zadané zařízení není podporované, a doporučit kontrolu registračního klíče nebo typu zařízení. ###### CONFLICT.SIM_CARD_ALREADY_CONNECTED_TO_DEVICE - Znamená, že zadaná SIM karta je už navázaná na jiné zařízení. - Aplikace má uživateli oznámit, že SIM karta je už použitá jinde. ###### UNPROCESSABLE_ENTITY.SIM_CARD_ASSIGNED_TO_OTHER_DISTRIBUTOR - Znamená, že zadaná SIM karta je přiřazená jinému distributorovi. - Aplikace má uživateli oznámit, že tuto SIM kartu není možné použít pro tuto registraci. ###### UNAUTHORIZED.WRONG_AUTHORIZATION - Znamená, že zadaný uživatelský kód má platný formát, ale není správný. - Aplikace má uživateli oznámit, že zadaný kód není platný a že při opakovaném zadání více chybných kódů za sebou se spustí alarm překročení neplatných autorizací. ###### BAD_REQUEST.CONTROL_INVALID_AUTHORIZATION_CODE_FORMAT - Znamená, že zadaný uživatelský kód nemá platný formát. - Aplikace má uživateli doporučit kontrolu formátu kódu, počtu znaků a případně i toho, zda není potřeba zadat kód s prefixem. ###### GATEWAY_TIMEOUT.CONTROL_DEVICE_CONNECTION_TIMEOUT - Znamená, že se nepodařilo navázat spojení se zařízením. - Aplikace má uživateli oznámit, že má zkontrolovat, zda je zařízení zapnuté, a při přetrvávající chybě se obrátit na svého montážního partnera. ###### GATEWAY_TIMEOUT.OPERATION_TIMEOUT - Je alias stejného timeout stavu a má se zpracovat stejně jako `GATEWAY_TIMEOUT.CONTROL_DEVICE_CONNECTION_TIMEOUT`. ###### INTERNAL_SERVER_ERROR - V tomto procesu znamená neočekávané selhání na straně služby. - Aplikace má zobrazit srozumitelné sdělení, že nastala neočekávaná chyba, že má uživatel zkusit pokus později a že se má při přetrvávajícím problému obrátit na svého montážního technika. ### Rozhodovací mechanismus výběru dalšího kroku - Po úspěšné rezervaci zařízení systém vrací informaci, které další kroky jsou dostupné. - Systém současně vrací, které kroky jsou povinné pro dokončení celé registrace. - Součástí rozhodnutí je i pořadí a závislosti mezi jednotlivými kroky. - Systém vrací také doporučený další krok, od kterého má zákazník pokračovat při rozpracované registraci. - V této části procesu se rozhoduje mezi kroky `Informace o zákazníkovi`, `Nastavení zařízení` a `Vytvoření služby`. - Klient podle doporučeného kroku načte aktuální detail stavu tohoto kroku, který určí, co je v daném kroku potřeba splnit. - Po splnění daného kroku klient znovu načte celkový stav registrace. - Na základě nového celkového stavu registrace klient získá další doporučený krok a stejným způsobem pokračuje dál. - Tento cyklus se opakuje, dokud klient neprojde všemi požadovanými kroky procesu. ### Informace o zákazníkovi - Tento krok slouží k doplnění údajů o zákazníkovi pro konkrétní rezervované zařízení. - Informace o zákazníkovi se vyplňují znovu pro každou novou registraci zařízení, protože se mohou mezi zařízeními lišit. - Pokud backend vrátí, že je dalším krokem `Informace o zákazníkovi`, klient musí načíst aktuální stav tohoto kroku. - Backend vrací dynamický formulář s pravidly pro zobrazení a validaci, který se může měnit podle typu zákazníka a dalších podmínek. - Ve formuláři se zobrazují skupiny údajů a jejich pole v pořadí definovaném backendem. - Některé skupiny polí se zobrazí až po splnění podmínky navázané na předchozí odpověď uživatele. - Pokud backend vrátí, že jsou údaje v kroku `Informace o zákazníkovi` už kompletní, klient pokračuje rovnou do dalšího kroku registrace. ### Nastavení zařízení - Klient načte detail stavu kroku `Nastavení zařízení`, který vrací stav `Nastavení zařízení` a stav `Stažení konfigurace ze zařízení`. - Pokud zařízení ještě není nastavené (nakonfigurované), klient nejprve řeší konfiguraci zařízení. - Pokud backend vrátí, že konfigurační požadavek už probíhá nebo je naplánovaný, klient rovnou zobrazí detail tohoto požadavku. - Pokud zařízení není nastavené a současně pro konfiguraci neexistuje založený požadavek, klient automaticky založí nový požadavek na konfiguraci zařízení. - Po založení požadavku backend vrátí identifikátor požadavku a klient podle něj ihned zobrazí jeho aktuální stav. - Pokud je zařízení už nastavené, ale konfigurace ještě není stažená, klient pokračuje stejným mechanismem pro krok `Stažení konfigurace ze zařízení`. - Klient nejdřív ověří, zda už není požadavek na stažení konfigurace založený ve frontě. - Pokud je požadavek na stažení už založený, klient rovnou zobrazí detail požadavku. - Pokud požadavek na stažení založený není, klient ho automaticky vytvoří. - Výsledkem založení je opět identifikátor požadavku, podle kterého klient začne zobrazovat stav tohoto požadavku. - Dokud není dokončené nastavení zařízení i stažení konfigurace, proces nemůže pokračovat do finálního dokončení registrace. #### Detail konfiguračního požadavku - Detail konfiguračního požadavku zobrazuje aktuální stav konkrétního požadavku podle jeho identifikátoru. - Stav požadavku může být `Vytvořen`, `Zpracováván` nebo `Hotový`. - Stav `Vytvořen` znamená, že požadavek čeká na zpracování a je známý čas, kdy má dojít ke spuštění. - Stav `Zpracováván` znamená, že se na požadavku právě pracuje. - Stav `Hotový` rozlišuje výsledek `Úspěch` nebo `Chyba`. - Klient standardně zjišťuje stav požadavku pollingem každých 5 sekund. - Ve stavu `Vytvořen` klient zobrazuje realtime odpočet do plánovaného času spuštění. - Pokud odpočet doběhne na `00:00`, klient místo času zobrazí informaci, že zpracování začne každou chvíli. - Ve stavu odpočtu klient dočasně nepolluje a polling znovu spustí až po dosažení `00:00`. - Pokud je u požadavku na stažení konfigurace dostupné manuální urychlení naplánovaného požadavku, klient nabídne akci `Spustit ihned`. - Jakmile se požadavek dostane do stavu `Hotový` s výsledkem `Chyba`, klient zobrazí informaci o chybě. - Pokud jde o předem definovanou chybu se specifickou reakcí, klient zobrazí i doporučení dalšího postupu. - Ve chybové větvi má uživatel k dispozici akci opakování požadavku. - Jakmile se požadavek dostane do stavu `Hotový` s výsledkem `Úspěch`, klient znovu načte detailní stav kroku `Nastavení zařízení`. - Pokud po úspěchu ještě není dokončený poslední krok `Stažení konfigurace`, klient pokračuje dalším krokem uvnitř záložky `Nastavení zařízení`. - Pokud je po úspěchu dokončený i poslední krok `Stažení konfigurace`, klient načte celkový stav registrace a pokračuje podle nově doporučeného dalšího kroku. #### Speciální chybové stavy detailu konfiguračního požadavku ##### NOT_FOUND nebo TIMEOUT - Pokud se vrátí stav `NOT_FOUND` nebo `TIMEOUT`, zobrazí se speciální chyba s ikonou offline. - Zpráva uživatele informuje, že zařízení není připojené k internetu, má zkontrolovat připojení a zkusit akci znovu. - Pokud potíže přetrvávají, uživatel se má obrátit na svého montéra. ##### CONFLICT - Pokud se vrátí stav `CONFLICT`, zobrazí se informace, že zařízení je právě konfigurováno jiným procesem. - Uživatel má pokračovat až ve chvíli, kdy konfigurace v jiném procesu skončí. ##### Ostatní chyby - Všechny ostatní chyby se zobrazují jako obecná chyba, že se akce nepovedla. - Při přetrvávajícím problému má uživatel kontaktovat svého montéra. ### Vytvoření služby - Služba se v tomto kroku vytváří na účet přihlášeného uživatele. - Pole `Majitel služby` obsahuje e-mail přihlášeného uživatele a je pouze pro čtení. - Backend v tomto kroku vrací název objektu zadaný při rezervaci a klient tuto hodnotu předvyplní do pole `Název služby`. - Formulář nelze odeslat (vytvořit službu), pokud není vyplněné pole `Název služby`. ## Business význam klíčových údajů - Registrační kód zařízení identifikuje zařízení, které chce zákazník registrovat. - Tento kód zákazník typicky získá v odkazu z QR kódu po přípravě zařízení montážním technikem. - Pokud zákazník nepřišel přes tento odkaz, musí registrační kód zadat ručně. - Autorizační kód potvrzuje, že registrační údaje pocházejí z důvěryhodného procesu přípravy zařízení. - Pokud zákazník nepřišel přes odkaz s předvyplněnými údaji, musí autorizační kód zadat ručně společně s registračním kódem. - Telefonní číslo zařízení je doplňkový údaj z odkazu od montážního technika a propsává se do rezervace zařízení. ## Doplnění z testování 2026-05-27 - V kroku `Informace o zákazníkovi` není telefonní číslo blokující podmínkou pro dokončení registrace. - Pole jména v kroku `Informace o zákazníkovi` očekává jméno i příjmení. - V německé mutaci je textace pole jména `Vorname und Nachname`. - Ve verzi `PRD` se ve footeru nezobrazují patičkové odkazy ani odkaz na pomocný `AuthCode` nástroj. - V registračním flow je zablokované použití browser navigace `Zpět`, protože rozbíjí průběh registrace.