Naming Convention (Jmenné konvence)

Pro udržení pořádku v síti (a v hlavě) používáme systematické pojmenování hostname a entit.

Obecná pravidla

Jazyk: Angličtina (preferováno pro id a hostname) nebo Čeština bez diakritiky. Buďte konzistentní.
Formát: kebab-case (malá písmena, pomlčky).
Zákaz: Mezery, diakritika, speciální znaky.

1. Síťové prvky (Network)

Schéma: [typ]-[umisteni]-[index/role]

Typ	Předpona	Příklad	Starý název (špatně)
Switch	`sw`	`sw-rack-01`, `sw-rack-02`	`aruba`, `VN57KYD0K3`
Access Point	`ap`	`ap1-chodba`, `ap3-bazen`	`UniFi-AP-1`, `obyvak`
Router/FW	`gw` / `fw`	`pfSense-router`	`pfsense`
Printer	`prn`	`prn-office`	`print`

2. Servery a VM

Schéma: [role]-[sluzba] nebo [node]-[index]

Typ	Příklad	Poznámka
Hypervisor	`pmx1`, `pmx2`	Proxmox nody (bez pomlčky kvůli Proxmox omezení)
Backup	`pbs`	Proxmox Backup Server (VM 105)
VM/LXC	`homeassistant`, `debian-services`	Pojmenováno dle funkce/služby
Storage	`truenas`	TrueNAS Scale

3. IoT a Technologie

Schéma: [technologie]-[typ]-[umisteni]

Technologie: modbus, dali, zigbee, wifi
Typ: gw (gateway), relay, sensor, btn (tlačítko)
Umístění: vzt (vzduchotechnika), boiler, kitchen

Příklad	Rozbor
`modbus-gw-vzt`	Modbus brána pro vzduchotechniku
`dali-gw-dilna`	DALI brána pro dílnu
`zigbee-gw-rack`	Zigbee koordinátor v racku
`wifi-shelly-kitchen`	Shelly relé v kuchyni

4. IP Adresace (VLAN Policy)

Pravidlo: Rezervované adresy < .100, DHCP pool ≥ .100

Na každém VLANu platí:

.1 — Gateway (pfSense)
.2 – .99 — Statické / DHCP rezervace (seskupené dle umístění/funkce)
.100 / .150+ — DHCP pool (dynamické přidělování)

IoT VLAN (40) — skupiny rezervací

Rozsah	Skupina	Příklady
`.2` – `.9`	Koordinátory, tiskárny	zigbee, velux, print
`.21` – `.29`	Dílna (vč. FTV)	DALI, switch, Cerbo GX, Fronius
`.31` – `.39`	Topení / VZT	EcoGeo, rekuperace, Modbus GW
`.41` – `.49`	VZT / Sklad	Modbus relé
`.51` – `.59`	Senzory	Aqara FP2

LAN (20) — politika

Rozsah	Účel
`.1` – `.9`	Infrastruktura (pfSense, Proxmox, TrueNAS, switche)
`.10` – `.29`	Servery a služby (HA, PBS, debian-services, scrypted)
`.100`+	DHCP pool (osobní zařízení)

5. Entity v Home Assistant

5.1 Obecná pravidla

Pole	Jazyk	Formát	Příklad
`entity_id`	Angličtina (bez diakritiky)	`snake_case` — generuje se z `unique_id` nebo `name`	`sensor.atrea_outdoor_temp`
`unique_id`	Angličtina (bez diakritiky)	`snake_case`, popisný, nikdy generický (`switch_1`)	`dilna_rele_rekuperace`
`friendly_name`	Čeština	Lidsky čitelný, bez technických prefixů	"Venkovní teplota"

Pravidla:

Vždy explicitně nastavit unique_id — umožňuje přejmenování v UI a brání kolizím.
entity_id nepřejmenovávat ručně bez impact analysis (viz závislé automatizace, dashboardy, skripty, Grafana).
Preferovat entity_id nad device_id (viz AGENTS.md).

5.2 Schéma entity_id podle platformy

Obecný vzor: [platforma].[oblast]_[zarizeni]_[funkce]

Platforma	Vzor	Příklad
`sensor`	`sensor.[zdroj]_[velicina]`	`sensor.atrea_outdoor_temp`, `sensor.victron_grid_power_l1`
`binary_sensor`	`binary_sensor.[oblast]_[funkce]`	`binary_sensor.kuchyne_occupancy`
`switch`	`switch.[oblast]_[zarizeni]`	`switch.bazen_topeni`, `switch.dilna_rekuperace`
`light`	`light.[oblast]_[svitidlo]`	`light.loznice_strop`, `light.jidelna_lista`
`cover`	`cover.[oblast]_[index]`	`cover.bazen_01`, `cover.herna_02`
`climate`	`climate.[oblast]` nebo `climate.[zarizeni]_[unit]`	`climate.loznice`, `climate.daikin_1_00`
`lock`	`lock.[oblast]_[zarizeni]`	`lock.hlavni_vchod`
`automation`	`automation.[trigger]_[akce]`	`automation.zavlaha_rano_vecer`
`script`	`script.[akce]_[cil]`	`script.velux_recovery`

Poznámky:

Senzory ze zařízení (Victron, Fronius, Atrea, Ecoforest) — prefix = název zdroje, ne oblast. Oblast se řeší přiřazením do Area.
Světla a kryty — prefix = oblast, protože fyzicky patří do místnosti a oblast je hlavní rozlišovač.
Automatizace a skripty — popisný slug, nepoužívat timestampy jako ID.

5.3 Oblasti (lokace)

Zkratky oblastí odpovídají area_id v Home Assistant. Referenční seznam:

`area_id`	Název	Patro
`bazen`	Bazén	Přízemí
`belka`	Belka	Patro
`betka`	Bětka	Patro
`chodba_tv`	Chodba TV	Patro
`dilna`	Dílna	Přízemí
`galerie`	Galerie	Patro
`hala`	Hala	Přízemí
`herna`	Herna	Patro
`janca`	Janča	Patro
`jidelna`	Jídelna	Přízemí
`koupelna`	Koupelna	Přízemí
`koupelna_holky`	Koupelna holky	Patro
`koupelna_tv`	Koupelna TV	Patro
`kuchyne`	Kuchyně	Přízemí
`loznice`	Ložnice	Přízemí
`lucka`	Lucka	Patro
`minisatna`	Minišatna	Přízemí
`relax`	Relax	Přízemí
`spiz`	Spíž	Přízemí
`tomas`	Tomáš	Patro
`telocvicna`	Tělocvična	Patro
`technicka`	Technická	Přízemí
`vzt`	VZT	Přízemí
`wc`	WC	Přízemí
`wc_holky`	WC holky	Patro
`satna_holky`	Šatna holky	Patro
`jih`	Jih	Venku
`sever`	Sever	Venku
`vjezd`	Carport	Venku

5.4 Zkratky a slovníček

Standardizované zkratky pro unique_id a entity_id:

Technologie / zdroje:

Zkratka	Význam
`atrea`	Rekuperace Atrea
`ecoforest`	Tepelné čerpadlo EcoGeo
`victron`	Victron Cerbo GX (baterie, střídače, síť)
`fronius`	Fronius střídač (FTV)
`daikin`	Daikin klimatizace
`dali`	DALI osvětlení
`rele`	Modbus relé desky

Veličiny a funkce:

Zkratka	Význam
`temp`	Teplota
`hum`	Vlhkost
`power`	Výkon (W)
`energy`	Energie (kWh)
`l1`, `l2`, `l3`	Fáze (vždy lowercase)
`soc`	State of Charge (baterie)
`occupancy`	Přítomnost
`gw`	Gateway

5.5 Speciální případy

Modbus relé desky: Unique ID musí být popisný: [board]_[funkce] místo generického [board]_switch_N.

Špatně	Správně
`rele_topeni_switch_1`	`rele_topeni_rekuperace`
`rele_sklad_switch_7`	`rele_sklad_svetla_zahrada_sever`

Zigbee zařízení: Nově přidaná zařízení přejmenovat v Zigbee2MQTT na popisný název (např. presence_kuchyne). Entity s IEEE adresou (0x...) v názvu jsou kandidáti na přejmenování.

Integrační entity (Victron, Fronius, Daikin): Respektovat upstream naming z integrace. Přejmenovávat jen friendly_name pro lepší čitelnost v UI. entity_id měnit jen pokud je výrazně matoucí.

Covers (rolety/žaluzie): Aktuální numerické ID (cover.26) nahradit popisným názvem při nejbližší příležitosti (vyžaduje impact analysis).