Add production installer and observability tooling

2026-05-07 12:11:15 -03:00
parent a19ac9f00c
commit 5d92a6c99a
30 changed files with 3493 additions and 1015 deletions
@@ -0,0 +1,123 @@
+# Grafana e Planta Baixa
+
+Este guia cobre o uso do Grafana com o `V-Fire Monitor` para dashboards baseados em planta baixa.
+
+## Arquivos de apoio
+
+- [floorplan/floorplan-map.example.json](/mnt/c/Users/Syllas/Documents/V-Fire-Monitor/floorplan/floorplan-map.example.json)
+- [tools/build_floorplan_bundle.py](/mnt/c/Users/Syllas/Documents/V-Fire-Monitor/tools/build_floorplan_bundle.py)
+
+## O que o instalador ja deixa pronto
+
+Na instalacao Debian 13:
+
+- plugin Zabbix do Grafana instalado
+- datasource `Zabbix` provisionado
+- dashboard inicial `V-Fire Floorplan Starter`
+- icones SVG servidos pelo proprio `V-Fire Monitor`
+
+## URLs dos icones
+
+Substitua `SEU_HOST` pelo host do V-Fire Monitor.
+
+- `http://SEU_HOST:8088/static/grafana-icons/detector-smoke.svg`
+- `http://SEU_HOST:8088/static/grafana-icons/detector-heat.svg`
+- `http://SEU_HOST:8088/static/grafana-icons/module-input.svg`
+- `http://SEU_HOST:8088/static/grafana-icons/siren.svg`
+- `http://SEU_HOST:8088/static/grafana-icons/panel-nfs320.svg`
+
+## Dashboard inicial
+
+O instalador provisiona a pasta `V-Fire` no Grafana e um dashboard chamado:
+
+- `V-Fire Floorplan Starter`
+
+Esse dashboard serve como ponto de partida e lembra as URLs dos icones.
+
+## Formato versionavel da planta
+
+Para nao depender apenas de arrastar elementos manualmente no Grafana, o repositorio agora inclui um formato JSON de mapa de planta.
+
+Campos principais:
+
+- `title`
+- `grafana_dashboard_uid`
+- `background_image_url`
+- `vfire_base_url`
+- `zabbix_host`
+- `items`
+
+Cada item descreve:
+
+- `id`
+- `label`
+- `item_key`
+- `icon`
+- `x`
+- `y`
+- `width`
+- `height`
+- `rotation`
+
+## Gerar bundle normalizado
+
+Exemplo:
+
+```bash
+python3 tools/build_floorplan_bundle.py floorplan/floorplan-map.example.json
+```
+
+Isso gera um arquivo `.bundle.json` com:
+
+- URLs completas dos icones
+- referencia do host do Zabbix
+- referencias dos `item_key`
+- coordenadas prontas para uso em futuras automacoes
+
+## Montando a planta baixa
+
+Abordagem recomendada:
+
+1. Abra o dashboard `V-Fire Floorplan Starter`
+2. Crie ou edite um painel do tipo `Canvas`
+3. Defina a imagem de fundo com a planta baixa do local
+4. Adicione elementos visuais ou imagens representando cada ponto
+5. Use os SVGs do `V-Fire Monitor` como base visual
+6. Associe cada elemento ao item correspondente no datasource `Zabbix`
+
+## Como mapear itens
+
+Os itens que o app envia ao Zabbix seguem chaves como:
+
+- `notifier.status[NomeDoPonto]`
+- `notifier.comm[NomeDoPonto]`
+- `node.status[NomeDaCentral]`
+
+Os nomes dos pontos sao descobertos automaticamente a partir do monitoramento.
+
+## Estrategia recomendada de planta baixa
+
+- use a planta como imagem base
+- posicione um icone por detector, modulo ou sirene
+- use cor dinamica para refletir estado
+- crie uma legenda simples com:
+  - normal
+  - incidente
+  - ack
+  - removido
+  - offline
+
+## Observacao pratica
+
+O instalador nao conhece a planta baixa real do cliente.
+
+Por isso, ele consegue deixar:
+
+- Grafana integrado
+- datasource pronto
+- dashboard inicial provisionado
+- icones prontos
+- formato versionavel da planta baixa
+- bundle normalizado para futuras importacoes
+
+Mas o posicionamento exato dos elementos na planta baixa ainda precisa ser feito conforme o layout real da instalacao.