Konfigurace¶

Veškeré nastavení se ukládá v kolekci app_config. Každý záznam má klíč (key), hodnotu (value) a příznak tajnosti (is_secret).

Registr klíčů¶

Každý konfigurační klíč je popsán na jednom místě v backendu (internal/config/registry.go): typ (string, int, float, bool, json, html, timezone, enum), výchozí hodnota, příznak tajnosti, skupina, popis, případná doplňková kontrola a to, kterou službu je po změně nutné znovu inicializovat (platby, produkty, MCP, heartbeat, varování před zavřením). Z registru se odvozují:

• typové čtečky konfigurace (BankNum(), EmailPort(), …) a jejich výchozí hodnoty,
• seedování výchozích hodnot (SeedDefaults),
• kontrola hodnot při ukládání,
• editor v administraci (přes GET /api/v1/admin/contracts → app_config; nikdy se neposílají hodnoty tajných klíčů),
• seznam klíčů, jejichž změna znovu inicializuje platební službu.

Výchozí hodnoty se nezměnily. Registr přesně zachovává dosavadní chování; hlídá to charakterizační test (internal/config/characterization_test.go), který pevně zná výchozí hodnotu každého klíče (včetně BANK_NUM, BANK_NUM_SHORT, OPERATING_RULES_HTML). Dva klíče mají historicky jinou hodnotu při seedování než „výchozí" čtečky — obojí zůstává:

Kontrola hodnot při ukládání¶

Při vytvoření nebo změně hodnoty registrovaného klíče backend hodnotu zkontroluje (HTTP 400, data.value.message, např. EMAIL_PORT: must be an integer). Pravidla:

• Prázdná hodnota = nenastaveno a je vždy povolená.
• Kontrola přijímá přesně to, co čtečky dnes úspěšně přečtou: bool cokoli, co přijme strconv.ParseBool (1, t, T, TRUE, true, True, 0, f, F, FALSE, false, False), int jako strconv.Atoi (např. +25, -1, 007), float jako strconv.ParseFloat, timezone přes time.LoadLocation, enum (poskytovatel plateb; velikost písmen se ignoruje, protože ji tak čte i běh).
• JSON klíče kontroluje jejich vlastní parser: AI_CHAT_SETTINGS (ai.ParseSettings), BANK_EMAIL_REGEX_PROVIDERS (bankemail.ProvidersFromJSON), CLOSING_WARNING_CONFIG (config.ParseClosingWarning). Za běhu se chování při špatné hodnotě nemění (tiše se použije výchozí) — kontrola se týká jen nových zápisů.
• Při změně existujícího záznamu se kontroluje jen když se změnila hodnota. Starší záznam s neplatnou hodnotou jde dál upravovat (např. přepnout is_secret) a opravit.
• Neznámé klíče a provozní stav se nekontrolují.
• Programové zápisy (seed, aktivace poskytovatele, ukládání AI nastavení, heartbeaty, kurzory, demo zařízení) procházejí stejnou kontrolou; jejich hodnoty jí vyhovují.

Už uložené neplatné hodnoty vypíše GET /api/v1/admin/config/health (kind: "app_config"; hodnoty tajných klíčů se nikdy nevypisují). Zkušební kontrola bez uložení: POST /api/v1/admin/contracts/validate s {"kind":"app_config","target":{"key":"EMAIL_PORT"},"value":"587"}.

Provozní stav (není konfigurace)¶

Některé řádky v app_config jsou provozní stav zapisovaný systémem, ne nastavení. Editor je zařazuje do sbalené sekce Systém / ostatní a export instalace je vynechává:

Editor v administraci¶

Administrace → Konfigurace zobrazuje klíče po skupinách (Areál a region, Platby a banka, E-mail, Provoz, Dobíjení, Funkce, Zařízení, Uchování dat, Obsah stránek). U každého klíče je název, technický klíč, popis, vstup podle typu (přepínač/výběr pro bool a enum, textové pole pro čísla, text, JSON a HTML), výchozí hodnota s tlačítkem Obnovit výchozí a průběžná kontrola backendem.

• Tajné hodnoty se nikdy nezobrazují (pole je maskované, vidíte jen „Nastaveno / Nenastaveno"). Prázdné pole hodnotu ponechá, Smazat hodnotu ji vymaže.
• Změny se ukládají až tlačítkem Uložit změny; při chybě kontroly je uložení zablokováno.
• Klíče se samostatným postupem jsou jen pro čtení s odkazem na správnou záložku: PAYMENT_CHECK_SERVICE_ENABLED / PAYMENT_CHECK_SERVICE_NAME (Integrace → Aktivovat) a AI_CHAT_SETTINGS (Systém → AI asistent).
• Sekce Systém / ostatní (sbalená) zachovává původní surový editor (úprava, mazání, přidání, odkrytí tajných) pro provozní stav a vlastní klíče.

Předvolba regionu¶

Nad klíči je Předvolba regionu (CZ, SK, PL, UA). Vyplní pouze COUNTRY_CODE, CURRENCY_CODE, FACILITY_TIMEZONE a PRICE_DECIMAL_PLACES; hodnoty se jen předvyplní jako neuložené změny ke kontrole. Bankovní ani platební klíče předvolba nikdy nemění.

Priorita konfigurace¶

1. Proměnné prostředí (nejvyšší priorita)
2. Databáze (kolekce app_config)
3. Výchozí hodnoty (nejnižší priorita)

Proměnné prostředí vždy přebíjejí hodnoty v databázi. To je užitečné pro tajné klíče v produkci.

Konfigurační klíče¶

Země / Jazyk¶

Klíč COUNTRY_CODE je semí pro jazyk notifikací — z něj se automaticky odvodí jazyk e-mailů a frontendu:

Jazyk se předává frontendu přes endpointy /api/v1/public/system-config a /api/v1/me/dashboard, aby si SPA mohla nastavit fallback locale pro i18n.

Banka / Platby¶

Ceny¶

Limity¶

Hardware / Terminál¶

Email¶

Platební služba¶

Erste banka¶

Provoz zařízení¶

Provozní hodiny zón se nastavují pomocí time_from a time_to v zone_pricing_rules. Mimo tyto hodiny nelze spustit novou relaci a aktivní relace jsou automaticky ukončeny po uplynutí doby od konce provozní doby (viz AUTO_CLOSE_GRACE_MINUTES dole).

Automatické ukončení relací¶

Poznámka k přejmenování: dřívější klíč AUTO_CLOSE_LIGHTS_OFF_AFTER_CLOSE byl přejmenován na LIGHTS_OFF_AFTER_CLOSE, aby byl nezávislý na auto-close. Seed starý klíč automaticky odstraňuje.

AUTO_CLOSE_ENABLED a LIGHTS_OFF_AFTER_CLOSE jsou dva nezávislé přepínače — kombinace určuje chování po zavírací době:

Ve všech režimech platí: - Nový vstup je stále blokovaný — mimo provozní hodiny nelze spustit novou relaci (OperatingHoursCheckValidator), takže noví lidé se dovnitř nedostanou. - Uživatel s aktivní relací si ponechává ovládání zařízení (světla, zámky dveří atd.), protože ovládání zařízení kontroluje jen, že relace je aktivní, ne provozní hodiny. - Účtování pokračuje poslední známou sazbou, protože cena se počítá při ukončení relace (delší relace = vyšší poplatek). - Varovné blikání (CLOSING_WARNING_CONFIG) funguje ve všech režimech. - Admin a uživatelé s maintenance produktem auto-close bypassují vždy. - Zhasnutí světel (LIGHTS_OFF_AFTER_CLOSE) se provede jednou za den a zónu, hned v okamžiku konce provozní doby (bez čekání na odklad).

Výstraha před zavírací dobou¶

JSON struktura:

{
  "enabled": true,
  "blink_minutes_before": [10, 5]
}

• enabled — zapne/vypne celý systém varování
• blink_minutes_before — pole minut před koncem provozní doby, kdy se blikne světly (sestupně). Cron běží každou minutu a pro každou zónu s aktivními relacemi kontroluje, zda se blíží zavírací doba.

Příklad: {"enabled":true,"blink_minutes_before":[10,5]} — blikne 10 a 5 minut před koncem.

Produkty¶

Dobíjení kreditu¶

AI asistent (chatbot)¶

AI asistent se konfiguruje jediným klíčem AI_CHAT_SETTINGS (JSON, tajný klíč). Umožňuje definovat seřazený seznam poskytovatelů LLM — při dotazu se zkoušejí postupně a první, který odpoví, vyhraje (fallback). API klíče se ukládají na serveru a nikdy se neposílají do prohlížeče (admin přes API vidí jen has_key).

Odpovědi asistenta jsou založené výhradně na nástrojích MCP (vyhledávání v dokumentaci, zóny, rezervace atd.). Bez dostupných nástrojů (MCP vypnutý) chat selže s chybou — žádný fallback bez nástrojů neexistuje.

Přednost: hodnota z prostředí AI_CHAT_SETTINGS má přednost před hodnotou v databázi. Hodnota se čte čerstvě z databáze při každém dotazu, změny se projeví okamžitě.

Schéma AI_CHAT_SETTINGS:

{
  "enabled": true,
  "max_tool_rounds": 10,
  "system_prompt": "",
  "providers": [
    {
      "id": "openrouter-1",
      "order": 1,
      "label": "OpenRouter",
      "provider": "openrouter",
      "base_url": "https://openrouter.ai/api/v1/chat/completions",
      "models_url": "https://openrouter.ai/api/v1/models",
      "model": "openrouter/free",
      "api_key": "sk-or-v1-..."
    },
    {
      "id": "opencode-1",
      "order": 2,
      "label": "OpenCode",
      "provider": "opencode",
      "base_url": "https://opencode.ai/zen/v1/chat/completions",
      "model": "big-pickle",
      "api_key": ""
    }
  ]
}

• enabled — zapnutí/vypnutí AI asistenta.
• max_tool_rounds — maximální počet kol volání nástrojů na jeden dotaz. 0 = bez limitu.
• system_prompt — volitelná systémová výzva (osobnost + pravidla asistenta). Prázdné = vestavěný default. Změna se projeví okamžitě u nových konverzací; admin API vrací výchozí text jako default_system_prompt.
• providers — seznam poskytovatelů, seřazený podle order (řazení vždy vzestupně podle order, nezávisle na pořadí v poli).
• Podporované typy poskytovatelů (provider):
• openrouter — vyžaduje api_key.
• opencode — anonymní režim (klíč se nevyplňuje), ověřuje se public tokenem.
• ollama — lokální Ollama (default base_url = http://localhost:11434/v1/chat/completions, modely z …/api/tags).
• custom — libovolný OpenAI-kompatibilní endpoint.
• base_url — OpenAI-kompatibilní chat completions URL (povinné u každého poskytovatele).
• models_url — volitelná URL pro seznam modelů; když chybí, odvodí se z base_url (pro openrouter/opencode z ${base bez /chat/completions}/models, pro ollama /api/tags).
• api_key — API klíč; prázdný / __keep__ při uložení přes admin API zachová uložený klíč. U openrouter je povinný, u opencode se ignoruje.

Retence / cleanup¶

Obsah¶

Tajné klíče¶

Následující klíče jsou označeny jako is_secret = true a měly by být chráněny:

• AUTH_HEADER
• EMAIL_HOST_PASSWORD
• PLATBY_EMAIL_PASSWORD
• FIO_TOKEN
• ERSTE_API_KEY
• ERSTE_CLIENT_ID
• ERSTE_CLIENT_SECRET
• AI_CHAT_SETTINGS (obsahuje API klíče poskytovatelů — server je maluje jako has_key)

Nastavení přes prostředí¶

export MAX_DEBT=500
export TERMINAL_ENABLED=true
export FIO_TOKEN=váš_tajný_token

Nastavení přes databázi¶

V PocketBase administraci (/_/) v kolekci app_config vytvořte nebo upravte záznam:

Datové typy¶

• Boolean hodnoty přijímají: true, false, 1, 0, yes, no (bez ohledu na velikost písmen)
• Číselné hodnoty se validují a při chybě parsování se použije výchozí hodnota
• Prázdné řetězce vrací výchozí hodnotu
• Nové klíče lze přidávat za běhu bez změny kódu (přístup přes config.Get())

Seedování výchozích hodnot¶

Při prvním spuštění aplikace se do app_config automaticky vloží výchozí hodnoty všech klíčů. Seedování:

• Vkládá pouze klíče, které ještě neexistují
• Nastavuje odpovídající výchozí hodnoty
• Označuje citlivé klíče jako tajné