Předvolby a kontrola konfigurace¶

Nová instalace by se neměla nastavovat kopírováním JSON konfigurací z jiného prostředí. Dveřník proto u konfigurovatelných částí nabízí předvolby (hotové, ověřené šablony) a kontrolu konfigurace (pravidla, která backend vynucuje při ukládání).

Předvolby zařízení¶

V Administrace → Zařízení → Přidat zařízení zvolte typ a adaptér; nad polem adapter_config se objeví Začít z předvolby. Seznam je filtrovaný podle zvoleného typu a adaptéru. Po stisku Použít se předvolba pouze vyplní do formuláře — zkontrolujete ji, upravíte a uložíte sami.

Předvolby REST API adaptéru obsahují zástupné hodnoty http://192.168.1.50:9999 a Bearer CHANGE_ME — nahraďte je adresou a tokenem svého řadiče a čísla pinů upravte podle zapojení.

Předvolby jsou součástí aplikace (nelze je v databázi upravovat) a automatické testy zaručují, že každá z nich prochází stejnou kontrolou jako uložení zařízení.

Předvolby produktů¶

V Administrace → Produkty → Přidat definici je nad formulářem Začít z předvolby. Předvolba vyplní název (v jazyce rozhraní), cenu, typ a parametry; formulář parametrů se přitom řídí schématem daného typu (viz Produkty). Ceny jsou příkladové (Kč) — upravte je.

U slevy na zařízení obsahuje předvolba jen zástupné ID zařízení. Formulář ho po použití předvolby zahodí a nabídne seznam skutečných zařízení — vyberte alespoň jedno. Kontrola záměrně neověřuje, že zařízení existuje (jen strukturu); zástupná hodnota vyvolá pouze upozornění.

Každá předvolba prochází stejnou kontrolou jako uložení produktu (TestAllPresetsValid) a každý registrovaný typ produktu musí mít kontrakt a alespoň jednu předvolbu (TestRegistryCompleteness).

Předvolby regionu¶

V Administrace → Konfigurace je Předvolba regionu (kind: "region"): Česko, Slovensko, Polsko, Ukrajina. Každá nastavuje právě čtyři klíče COUNTRY_CODE, CURRENCY_CODE, FACILITY_TIMEZONE a PRICE_DECIMAL_PLACES (hodnoty a upozornění k platebnímu QR kódu viz Konfigurace). Předvolba nikdy nemění bankovní ani platební klíče a hodnoty se jen předvyplní ke kontrole — ukládá je až Uložit změny. Test TestAllPresetsValid ověřuje, že hodnoty projdou kontrolou registru klíčů, a TestRegionPresets pevně zná očekávané hodnoty.

Předvolby bankovních e-mailových parserů (bank_email_parser) se záměrně nenabízejí: vestavěné parsery bank jsou nativní Go kód aktivní vždy a jediná regex definice v repozitáři je dokumentační příklad ČSOB CEB, který ten samý nativní parser duplikuje. Regexy se nevymýšlejí.

Tarifní šablony (ceníky)¶

Šablony druhů zone_pricing (cíl: session_mode zóny time_based / entry_based) a device_pricing jsou sady pravidel (values.rules), ne jedna hodnota: nonstop sazba za minutu, denní/večerní sazba, všední dny/víkend, prvních 10 minut zdarma, otevírací doba Po-Pá 6-22 a So-Ne 8-20, vstupné (jednotná cena) a pro zařízení cena za použití, za minutu a zdarma. Názvy pravidel jsou ve 4 jazycích (webový formulář vezme jazyk rozhraní). V Administrace → Zóny a zařízení tlačítko Použít tarifní šablonu zobrazí sadu jako upravitelnou tabulku a po potvrzení ji vytvoří v jedné transakci (přidat, nebo nahradit = stávající aktivní pravidla se jen deaktivují). Podrobně v Ceníky.

TestAllPresetsValid kontroluje každé pravidlo každé sady stejným kontraktem jako ukládání pravidla (ve všech 4 jazycích názvu) a navíc sémantiku sady: žádná dvě pravidla stejného typu, která se mohou překrývat (čas i dny), nesmí mít stejnou prioritu (nejednoznačné - vybere se libovolné), typ pravidla musí dávat smysl pro režim zóny a sada musí něco cenit (per_minute u time_based, flat_fee u entry_based). Při použití šablony v UI jde o varování (nad rámec šablony už mohou existovat jiná pravidla), ve vestavěných šablonách je to chyba sestavení.

Kontrakt pravidla (GET /api/v1/admin/contracts → pricing_rules.zone_pricing_rule / device_pricing_rule, dry-run kind stejného jména): typ pravidla z výčtu, amount ≥ 0, time_from/time_to prázdné nebo HH:MM (jedna sdílená kontrola s ukládáním), days_of_week null/prázdné/unikátní čísla 1-7, priority celé číslo ≥ 0. Při ukládání pravidla se kontrola spouští při vytvoření a při změně kontrolovaného pole, takže starší pravidla zůstávají upravitelná; zdraví konfigurace je vypisuje (kind: "zone_pricing_rule" / "device_pricing_rule").

Živá kontrola ve formuláři¶

Při psaní konfigurace formulář průběžně (po krátké pauze) dotazuje backend a pod polem zobrazuje nalezené problémy s cestou, např. pin_mapping.open.pins[0].state — value must be one of on, off. Chyby (červeně) uložení zablokují, upozornění (žlutě) ne. Totéž platí pro každý řádek tabulky tarifní šablony. Pravidla nejsou duplikována ve webu — jediným zdrojem pravdy je backend.

Kontrola stavu konfigurace¶

Administrátor může zobrazit všechny již uložené záznamy (zařízení včetně neaktivních, definice produktů a cenová pravidla zón i zařízení), které dnešním pravidlům neodpovídají. Položka má kind device nebo product; produkt s typem bez registrované strategie se hlásí také:

GET /api/v1/admin/config/health

{
  "ok": false,
  "checked": {"devices": 5, "product_definitions": 12},
  "problems": [
    {"kind": "device", "id": "…", "name": "Vstup", "is_active": false,
     "issues": [{"path": "pin_mapping", "message": "is required", "severity": "error"}]}
  ],
  "warnings": []
}

Konfigurační klíče (app_config) se hlásí jako kind: "app_config" (name je klíč, issues[].path je value). Výpis je jen ke čtení. problems obsahuje záznamy s chybou, warnings záznamy jen s upozorněním.

Stejnou kontrolu stavu, seznam předvoleb a zkušební kontrolu nabízí i MCP (administrátorské nástroje get_config_health, list_presets, validate_config, viz MCP API). Export a import instalace přes MCP dostupné nejsou.

Další koncové body (pouze administrátor)¶

Bez přihlášení vrací endpointy 401, pro uživatele bez role admin 403.

Balíček instalace¶

Celé nastavení provozu lze exportovat do JSON a naimportovat do nové instalace (GET /api/v1/admin/installation/export, POST /api/v1/admin/installation/import se zkušebním importem dry_run). Import používá stejné kontrakty jako ruční uložení, takže balíček vytvořený z předvoleb i z ruční konfigurace projde stejnou kontrolou. Podrobně: Nová instalace.

Pro vývojáře: jak přidat předvolbu nebo bezpečně změnit kontrakt popisuje Kontrakty a předvolby.