Carbon Exchange — Manual

Plataforma de monitoramento ambiental para vinícolas, agro e brigadas de incêndio. Recebe dados de sensores LoRaWAN, classifica risco, alerta brigadistas via WhatsApp e expõe dashboard com mapa e previsão meteorológica.

1. Overview

Carbon Exchange é uma stack de três componentes:

• Webhook/API (POST /carbon) — recebe leituras de sensores em JSON, persiste em PostgreSQL e arquivo JSONL, calcula risco e dispara mensagens WhatsApp.
• WhatsApp instance — cliente Baileys que envia alertas formatados para o grupo administrativo (e, na Fase 2, para grupo do cliente).
• Dashboard — interface web com KPIs, mapa de devices, gráficos históricos e previsão 24 h.

2. Arquitetura

3. Fluxo de dados (request lifecycle)

1. Sensor envia POST com JSON para https://api.danhausch.cloud/carbon.
2. nginx encaminha para 127.0.0.1:5000 (gunicorn → Flask funnel_backend.py).
3. Handler carbon_webhook():
   1. Persiste body completo em carbon_webhook_events.jsonl.
   2. Extrai leitura via _extract_sensor_reading().
   3. Calcula risco via _compute_environment_risk().
   4. Encaminha mensagem formatada para WhatsApp via _forward_carbon_webhook_to_whatsapp().
   5. Salva em PostgreSQL (_carbon_db_save_reading): faz upsert em carbon.clients + carbon.devices, insere em carbon.sensor_readings.
   6. Se CO₂ > threshold, dispara alerta de áudio (_dispatch_carbon_audio_alert).
4. Resposta JSON síncrona em < 2 s (depende do RTT do Open-Meteo se for chamado).

4. Casos de uso

UC-01 · Brigada recebe alerta de CO₂

Sensor detecta CO₂ acima de 800 ppm. POST /carbon recebe payload, classifica risco como vermelho e dispara mensagem WhatsApp para grupo admin com nível de risco, leitura completa, link para mapa e previsão de chuva/vento das próximas 24 h. Brigadista decide ir ao local.

UC-02 · Sensor é movido

Payload chega com movimento: 1. Mensagem WhatsApp recebe linha destacada "Sensor movido do local original!". Dashboard mostra badge laranja no card "Movimento". Operador investiga.

UC-03 · Operador consulta histórico

Acessa /carbon/dashboard, filtra por cliente Vinícola e device mile_07, ajusta janela para 168 h (7 dias). Vê 4 séries temporais (umidade, temp, pressão, CO₂) + última leitura + posição no mapa.

UC-04 · Admin provisiona novo cliente Fase 2

Admin loga com JWT, abre /carbon/admin, cria tenant Fazenda Boa Vista com seu JID de grupo WhatsApp. Adiciona 5 devices. A partir do próximo POST, mensagens vão para o grupo do cliente (e mantém cópia no admin).

UC-05 · Cliente vê apenas seu ambiente Fase 2

Usuário client_admin da Vinícola loga e o dashboard filtra automaticamente todos os queries por seu tenant_id. Não vê devices de outros clientes.

5. Telas

6. Features

• Ingestão idempotente: payload bruto sempre persistido em JSONL antes de qualquer transformação.
• Multi-formato de chave: extrator aceita temp/temperature/temperatura, pa/pressure/pressao, umid/humidity/umidade, co2/co2_ppm etc.
• Risco ambiental: classifica leitura em escala (azul / verde / amarelo / laranja / vermelho) considerando CO₂, temperatura, umidade e pressão.
• WhatsApp formatado: filtra fCnt, fPort, token, devname da mensagem; inclui link Google Maps a partir de lat/lon; destaque para movimento=1.
• Mapa de devices: Leaflet com OpenStreetMap (sem API key); fitBounds automático.
• Previsão 24 h: Open-Meteo (free, no key) com cache em memória de 10 min por coordenada arredondada a 4 casas decimais.
• Alerta crítico CO₂: se co2 > CARBON_CO2_ALERT_THRESHOLD, dispara mensagem "🚨 SIRENE CARBON" para lista de telefones em CARBON_AUDIO_ALERT_PHONES.
• Catálogo dinâmico: /carbon/catalog retorna clientes e devices a partir do PostgreSQL para popular filtros e mapa.

7. API / Endpoints

Base URL pública: https://api.danhausch.cloud · Base local: http://127.0.0.1:5000

Exemplo de chamada

curl -X POST "https://api.danhausch.cloud/carbon" \
  -H "Content-Type: application/json" \
  -d '{
    "movimento": 0,
    "temp": 30.1,
    "umid": 47,
    "co2": 305,
    "pa": 949.5,
    "bat": 3.48,
    "device_id": "24e124126f099489",
    "device_name": "mile_07",
    "cliente": "Vinícola",
    "latitude": -22.548545,
    "longitude": -48.819028,
    "fCnt": 144,
    "fPort": 85,
    "token": "pgpanfd115jpr7yu0dv5",
    "devname": "mile-07"
  }'

Resposta típica

{
  "ok": true,
  "saved": true,
  "forwarded": true,
  "forward_status": "sent",
  "reading": {
    "temperature": 30.1, "humidity": 47.0, "pressure": 949.5, "co2": 305.0,
    "battery": 3.48, "movimento": 0,
    "latitude": -22.548545, "longitude": -48.819028
  },
  "db_saved": true,
  "db_status": "db_saved",
  "audio_alert": false,
  "audio_alert_status": "co2_normal"
}

8. Payload do sensor

9. Risco ambiental

Função _compute_environment_risk(reading) em funnel_backend.py:1129. Decisão atual:

10. WhatsApp routing

Backend Baileys

Node.js rodando em 127.0.0.1:8790. Service systemd openclaw-wa-backend.service. Workdir: /root/.openclaw/workspace/apps/openclaw-cockpit/wa-backend.

Endpoints internos do Baileys

• GET /wa/status
• GET /wa/pairing
• GET /wa/chats
• POST /wa/send — body {phone, text}
• POST /wa/reconnect

Forward webhook → grupo

Função _forward_carbon_webhook_to_whatsapp(payload, reading, risk) formata mensagem PT-BR com _format_carbon_whatsapp_message() e envia via _wa_send_to(target, text).

Target controlado por env var CARBON_WEBHOOK_FORWARD_PHONE. Se terminar em @g.us ou @s.whatsapp.net, é tratado como JID e enviado direto; caso contrário, normalize_phone() converte para digits-only.

Atualmente: [email protected] = grupo Carbon Software.

Formato da mensagem

🌿 Carbon Exchange — Vinícola / mile_07
🌡️ Temp: 30.1 °C    💧 Umid: 47.0 %
🫁 CO₂: 305 ppm     🌐 Pressão: 949.5 hPa
🔋 Bateria: 3.48 V
📍 -22.548545, -48.819028  https://maps.google.com/?q=-22.548545,-48.819028
🛰️ Sensor no local original.
🟡 Risco: risco médio — Calor com humidade moderada.

11. Previsão (Open-Meteo)

Endpoint /carbon/forecast?lat=…&lon=… faz proxy de:

https://api.open-meteo.com/v1/forecast
  ?latitude=&longitude=
  &hourly=precipitation,precipitation_probability,wind_speed_10m,wind_gusts_10m,wind_direction_10m
  &forecast_hours=24&timezone=auto&wind_speed_unit=kmh

Retorna summary (total chuva mm, máx vento, máx rajada, máx prob. chuva) + hourly[] com 24 pontos. Cache em memória 10 min, chave por coordenada arredondada a 4 casas decimais.

12. Schema PostgreSQL

Schema carbon em goku_games @ 127.0.0.1:5432. Migrações idempotentes via _carbon_db_ensure_schema() rodam a cada save.

carbon.clients (
  id BIGSERIAL PK,
  client_id TEXT UNIQUE NOT NULL,
  name TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
)

carbon.devices (
  id BIGSERIAL PK,
  device_id TEXT UNIQUE NOT NULL,
  client_id TEXT REFERENCES carbon.clients,
  label TEXT,           -- = device_name do payload
  location TEXT,
  active BOOLEAN DEFAULT TRUE,
  latitude DOUBLE PRECISION,    -- adicionado Fase 1
  longitude DOUBLE PRECISION,   -- adicionado Fase 1
  created_at TIMESTAMPTZ DEFAULT NOW()
)

carbon.sensor_readings (
  id BIGSERIAL PK,
  device_id TEXT REFERENCES carbon.devices,
  client_id TEXT REFERENCES carbon.clients,
  humidity NUMERIC(6,2),
  temperature NUMERIC(6,2),
  pressure NUMERIC(8,2),
  co2 NUMERIC(10,2),
  battery NUMERIC(5,2),         -- adicionado Fase 1
  movimento SMALLINT,           -- adicionado Fase 1
  latitude DOUBLE PRECISION,    -- adicionado Fase 1
  longitude DOUBLE PRECISION,   -- adicionado Fase 1
  risk_level TEXT,
  raw_payload JSONB NOT NULL,
  measured_at TIMESTAMPTZ DEFAULT NOW(),
  received_at TIMESTAMPTZ DEFAULT NOW()
)

-- Índices
idx_carbon_readings_received_at  ON sensor_readings (received_at DESC)
idx_carbon_readings_device_time  ON sensor_readings (device_id, measured_at DESC)

13. Infraestrutura

Variáveis de ambiente relevantes

14. Deploy / Operação

Restart de serviços

# API/webhook (após editar funnel_backend.py)
sudo systemctl restart funnel_backend.service

# WhatsApp Baileys
sudo systemctl restart openclaw-wa-backend.service

# Logs
sudo journalctl -u funnel_backend.service -f
sudo journalctl -u openclaw-wa-backend.service -f

Configurar grupo WhatsApp (admin)

# Listar grupos
curl -s http://127.0.0.1:8790/wa/chats | jq '.items[] | select(.id | endswith("@g.us"))'

# Setar grupo via systemd drop-in
sudo mkdir -p /etc/systemd/system/funnel_backend.service.d
sudo tee /etc/systemd/system/funnel_backend.service.d/carbon-forward.conf <<EOF
[Service]
Environment="CARBON_WEBHOOK_FORWARD_PHONE=<jid>@g.us"
EOF
sudo systemctl daemon-reload
sudo systemctl restart funnel_backend.service

Smoke test

curl -s -X POST http://127.0.0.1:5000/carbon \
  -H 'Content-Type: application/json' \
  -d '{"temp":30.1,"umid":47,"co2":305,"pa":949.5,"bat":3.48,"movimento":0,
       "device_id":"test-001","device_name":"smoke","cliente":"QA",
       "latitude":-22.5,"longitude":-48.8}'

Status check

curl -s http://127.0.0.1:8790/wa/status
curl -s http://127.0.0.1:5000/carbon/dashboard/data | jq
curl -s "http://127.0.0.1:5000/carbon/forecast?lat=-22.5&lon=-48.8" | jq .summary

14.1 Testing — checklist E2E

Plano de teste para validar todas as features. Substitua $BASE pelo host (http://127.0.0.1:5000 em dev ou https://api.danhausch.cloud em prod).

14.2 Smoke test rápido

BASE=https://api.danhausch.cloud

# 1. Login
TOKEN=$(curl -s -X POST $BASE/carbon/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"<senha>"}' | jq -r .access_token)

# 2. Webhook + verificar dual-routing
curl -s -X POST $BASE/carbon -H 'Content-Type: application/json' -d '{
  "movimento":0,"temp":31.0,"umid":42,"co2":380,"pa":947.2,"bat":3.45,
  "device_id":"sensor-test-01","device_name":"caixa-d-agua",
  "cliente":"Vinícola Teste",
  "latitude":-22.548545,"longitude":-48.819028
}' | jq '{ok,forward_legs,reading}'

# 3. Audit
curl -s "$BASE/carbon/admin/audit?limit=5" \
  -H "Authorization: Bearer $TOKEN" | jq '.events[] | {channel,target,status,attempts}'

15. Fase 2 — entregue

Implementação do design em /carbon/phase2-design. Ativada via flag CARBON_AUTH_ENFORCE (default false para migração suave).

15.1 Auth (JWT)

• POST /carbon/auth/login — bcrypt verify, devolve access (60 min) + refresh (30 d).
• POST /carbon/auth/refresh — novo access via refresh token; verifica revogação e expiração.
• POST /carbon/auth/logout — revoga refresh.
• GET /carbon/auth/me — devolve user + memberships (lê do JWT).
• Decorator _carbon_require_auth implementa soft-mode: quando CARBON_AUTH_ENFORCE=false, anônimo passa; quando true, retorna 401 sem JWT.
• Bootstrap inicial: scripts/bootstrap_admin.py com env vars CARBON_BOOTSTRAP_ADMIN_EMAIL/PASSWORD/NAME. Idempotente.

15.2 Multi-tenant

• Tabelas: tenants, users, tenant_members, auth_refresh_tokens (criadas e populáveis pela admin UI).
• Backfill executado: 4 tenants criados a partir dos clients existentes; clients.tenant_id setado.
• Queries _carbon_db_latest_reading, _carbon_db_readings_history, _carbon_db_catalog recebem parâmetro tenant_filter.
• Helper _carbon_tenant_filter_from_g() deriva o filtro do JWT — admin vê tudo, demais usuários ficam restritos aos tenants das suas memberships.

15.3 WhatsApp routing por tenant

• _carbon_resolve_tenant_for_device(device_id, cliente) resolve o tenant a partir do device cadastrado ou do nome do cliente.
• _forward_carbon_webhook_to_whatsapp agora envia duas mensagens: para o JID do tenant (se houver) + para o JID admin global. Cada leg vira uma linha em alert_events.
• Se tenant JID = admin JID, o segundo envio é pulado (status skipped_same_as_tenant).

15.4 Audit + replay queue

• Toda mensagem WhatsApp (envio, audio alert, retry) gera linha em alert_events.
• Falhas recebem next_attempt_at = NOW() + 60s; worker carbon-replay.service roda a cada 60 s via timer systemd.
• Backoff exponencial até 8 tentativas (60 s → 1 h); depois marca status='dead'.
• Admin UI lista o histórico em /carbon/admin aba Auditoria.

15.5 Backup automático

• carbon-backup.timer roda diariamente às 03:30 UTC; chama /opt/carbon-backup/backup.sh.
• Faz pg_dump -Fc da DB carbon (via docker exec) + tar.gz das credenciais Baileys em /root/.openclaw/credentials/whatsapp/.
• Rotação keep-last-14 em /var/backups/carbon/{db,wa}/.

15.6 UI admin

• /carbon/login — autenticação; persiste tokens em localStorage; redireciona admins para /carbon/admin e demais para /carbon/dashboard.
• /carbon/admin — três tabs:
  • Tenants — lista, criar, editar JID via dropdown alimentado por /carbon/admin/wa-groups, adicionar membro.
  • Usuários — list global, criar com email + senha + flag is_admin.
  • Auditoria — últimos 200 alert_events com status, tentativas, próximo retry.

15.7 Anti-spoof: token por device

Cada device tem um platform_token (string opaca ~20 chars) atribuído pela plataforma da Greenbug e enviado no campo token de cada payload. Quando CARBON_TOKEN_ENFORCE=true:

• Webhook compara payload.token com devices.platform_token cadastrado.
• Bate → 200; não bate → 401 {reason:"token_mismatch"}.
• Device desconhecido → primeiro POST registra o token (TOFU); a partir do 2º, qualquer token diferente é rejeitado.
• Em soft mode (default), backend só loga via token_check sem bloquear.

Os 19 devices conhecidos da Greenbug (iza01–iza10, khomp, mile-01–mile-08) foram seedados via scripts/seed_greenbug_tokens.py.

15.8 Pendente para Fase 3

• Endpoint admin para CRUD de devices com platform_token visível.
• Convite por email (hoje admin define senha temporária ao criar usuário).
• Login rate-limit / lockout.
• Dedup por (device_id, fCnt).
• Detecção de device offline (last-seen alert).

Documento atualizado em 2026-05-10. Carbon Exchange • funnel_backend.py · repo danielharagao/carbon.