Nová instalace¶

Postup pro zprovoznění nové, nezávislé instalace (jedna instalace = jeden kontejner = jedno hřiště nebo posilovna). Nic z konfigurace se nemusí kopírovat ručně z jiného prostředí: buď ji naimportujete jako balíček instalace z funkční instalace, nebo ji složíte z předvoleb přímo v administraci.

1. Server a aplikace (Ansible)¶

Server, systemd služba a vault s hesly se zakládají přes Ansible. Postup (přidání hosta do inventory.yml, vault soubor, provision.yml, deploy.yml) je popsán v souboru ansible/README.md v repozitáři (kapitola „Přidání nové instance“). Po nasazení aplikace běží prázdná: žádné zóny, zařízení, produkty ani ceník.

2. První administrátor¶

1. Otevřete administraci PocketBase na /_/ a vytvořte superuživatele.
2. V aplikaci se zaregistrujte a v kolekci users nastavte svému účtu role = admin a is_approved = true.
3. Přihlaste se do webové aplikace. Další kroky se dělají v záložce Administrace.

3. Region a základní nastavení¶

V záložce Konfigurace použijte předvolbu regionu (CZ, SK, PL, UA). Nastaví jen COUNTRY_CODE, CURRENCY_CODE, FACILITY_TIMEZONE a PRICE_DECIMAL_PLACES; bankovní a platební klíče se nikdy nemění. Poté doplňte zbytek (EMAIL_APP_NAME, kontakty, provozní řád, kredit a dluh). Přehled všech klíčů: Konfigurace.

Bankovní účet (BANK_NUM, BANK_NUM_SHORT) a platební integraci vždy nastavujte přímo v nové instalaci, viz Bankovní integrace. Balíček je záměrně nepřenáší.

4a. Varianta A: import balíčku z jiné instalace¶

Hodí se, když už existuje podobná instalace (šablona), ze které chcete převzít zóny, zařízení, ceník a produkty.

Export ze zdrojové instalace¶

V záložce Systém v panelu Balíček instalace stiskněte Exportovat balíček (nebo GET /api/v1/admin/installation/export). Stáhne se soubor JSON.

• Hlavičky auth_header zařízení jsou nahrazeny zástupným Bearer CHANGE_ME. Zaškrtnutím Zahrnout autorizační hlavičky (?include_secrets=true) se přenesou skutečné hodnoty. Takový soubor je tajný: neposílejte ho e-mailem, nesdílejte ho a po použití ho smažte.
• Přihlašovací údaje uvedené přímo v URL zařízení (http://uzivatel:heslo@host) se bez include_secrets odstraní.
• Tajné hodnoty v dotazu URL (?token=, ?key=, ?api_key=, ?password=, ?secret=, ?auth=, ?access_token=, ?sig= apod.) se bez include_secrets nahradí CHANGE_ME, ostatní parametry zůstanou beze změny.

Co balíček obsahuje¶

Záznamy se odkazují exportními klíči (zone:1, device:2), nikdy databázovými ID. Identifikátory vložené ve vnořeném JSON (např. parameters.device_ids u produktu device_discount, JSON layout a position) se přepisují stejným způsobem. Zařízení, které už neexistuje a je ještě uvedeno v device_ids, se při exportu nahradí zástupným REPLACE_WITH_DEVICE_ID (a do balíčku se přidá varování), takže se do souboru nedostane syrové ID.

Hlavička souboru: format_version (nyní 1), exported_at (UTC), app_version, source.name (název instalace) a includes_secrets.

Co se nikdy neexportuje¶

• uživatelé, relace, platby, dobití, bankovní transakce, e-maily a jejich logy, rezervace, uzavírky zón, tokeny (API, MCP, OAuth);
• tajné klíče app_config (FIO_TOKEN, ERSTE_API_KEY, ERSTE_CLIENT_ID, ERSTE_CLIENT_SECRET, EMAIL_HOST_PASSWORD, PLATBY_EMAIL_PASSWORD, INCOMING_PAYMENT_NOTIFICATION_EMAIL_PASSWORD, AUTH_HEADER, AI_CHAT_SETTINGS). Ani include_secrets=true je nezahrne;
• identita instalace: celá skupina platebních klíčů (BANK_NUM, BANK_NUM_SHORT, FIO_URL, ERSTE_*_URL, INCOMING_PAYMENT_NOTIFICATION_*, PAYMENT_CHECK_*, BANK_EMAIL_REGEX_PROVIDERS) a účty pošty EMAIL_HOST_USER, PLATBY_EMAIL. Zkopírované číslo účtu by posílalo platby nové provozovny na účet šablony;
• stav za běhu (HEARTBEAT_DEVICE_*, PAYMENT_LAST_RUN_TIMESTAMP, BANK_EMAIL_IMAP_CURSOR, DEMO_*) a neregistrované klíče;
• prázdné hodnoty (prázdná hodnota znamená „nenastaveno“ a přepsala by výchozí hodnotu cíle).

Import do nové instalace¶

V záložce Systém v panelu Balíček instalace vyberte soubor. Hned se provede zkušební import (dry run): celý balíček se zapíše do transakce, zkontroluje stejnými pravidly jako ruční uložení (kontrakty zařízení, produktů, cenových pravidel a klíčů app_config, včetně hooků PocketBase) a transakce se vrátí zpět. Zobrazí se počty záznamů a úplný seznam problémů (sekce, odkaz, cesta, zpráva, závažnost). Tlačítko Importovat balíček je aktivní jen tehdy, když zkušební import nemá žádnou chybu. Upozornění (např. Bearer CHANGE_ME ve zbylé hlavičce) import neblokují, ale je potřeba je po importu opravit.

Zkušební import vždy vrací také seznam config_changes ([{key, from, to}]): všechna nastavení app_config, jejichž hodnota by se importem změnila. Panel je zobrazí v tabulce. Balíček neobsahuje tajné klíče a hodnoty tajných klíčů se nikdy nevypisují.

Import je atomický: buď se zapíše všechno, nebo nic. Po úspěšném importu se registr zařízení znovu načte, takže importovaná zařízení jsou hned použitelná.

API¶

POST /api/v1/admin/installation/import:

{ "bundle": { "format_version": 1, "...": "..." }, "dry_run": true, "sections": ["zones", "devices"], "allow_live_config": false }

• allow_live_config (volitelné, výchozí false) viz výše: potvrzení změny app_config na živé instalaci.
• dry_run je povinné (vynechané pole nikdy nezapíše data), sections je volitelné (výchozí: všechny sekce v balíčku; závislé sekce bez rodičů hlásí chybu neznámého odkazu).
• 200 {"ok", "dry_run", "issues": [{"section","ref","path","message","severity"}], "counts": {…}, "config_changes": [{"key","from","to"}], "target_non_empty"}. U zkušebního importu je ok: false také 200; u ostrého importu s chybami 422 a nic se nezapíše.
• 400 neplatný JSON, neznámá sekce nebo neznámá/vyšší format_version; 409 neprázdná instalace nebo změna app_config živé instalace bez allow_live_config; 500 má obecnou zprávu, podrobnosti jsou jen v logu serveru; 401/403 bez role admin.
• Limit těla požadavku je 128 MiB (layout_background může mít až 5 MB na zónu); sekce mají maximálně 5000 záznamů.

Starší format_version se před importem automaticky převedou řetězcem upgradů, takže dnes uložený balíček půjde importovat i po budoucí změně formátu. Balíček s vyšší verzí, než umí aplikace, se odmítne.

4b. Varianta B: složení z předvoleb¶

Bez zdrojové instalace všechno složíte ve formulářích administrace. Předvolby jsou vždy platné, validace běží při každém uložení:

1. Zařízení: při vytvoření zvolte předvolbu (zámek, světlo, zásuvka, demo), přepište adresu a autorizační hlavičku (CHANGE_ME). Viz Zařízení.
2. Zóny a přiřazení zařízení (každá zóna potřebuje aspoň jedno primární zařízení).
3. Ceník: na zóně nebo zařízení použijte tarifní šablonu, upravte částky a časy a potvrďte. Viz Ceníky.
4. Produkty: při vytvoření zvolte předvolbu (permanentka, vstupy, sleva…), u device_discount vyberte skutečná zařízení. Viz Produkty.

5. Kontrola¶

GET /api/v1/admin/config/health (v administraci kontrola stavu konfigurace) projde všechna zařízení, produkty, cenová pravidla a klíče app_config a vypíše záznamy, které pravidlům neodpovídají. Po importu s CHANGE_ME v hlavičkách zobrazí upozornění u každého zařízení, dokud nevyplníte skutečné hodnoty. Dokončete:

• skutečné autorizační hlavičky zařízení (pokud jste neexportovali s include_secrets) a adresy (base_url apod.) hardwaru nové provozovny, potom zařízení aktivujte (importovaná zařízení se zástupnými hodnotami jsou neaktivní);
• bankovní účet a platební integraci (Bankovní integrace);
• e-mailový účet, pokud se mají posílat zprávy;
• test s demo uživatelem: zahájení relace, odezva zařízení, výpočet ceny.