Pular para conteúdo

Setup do Ambiente de Desenvolvimento

Pré-requisitos

  • Python 3.11, versão declarada em .python-version na raiz (o pyenv a aplica sozinho, e o CI a lê do mesmo arquivo). É a versão da imagem de produção, python:3.11-slim no Dockerfile
  • PostgreSQL 16 com extensão TimescaleDB
  • Node.js (para o build do TailwindCSS)

Instalação

# 1. Clonar o repositório
git clone <url-do-repositorio>
cd EnergIA

# 2. Criar e ativar o ambiente virtual
python -m venv venv
source venv/bin/activate        # Linux/macOS
venv\Scripts\activate           # Windows

# 3. Instalar dependências Python
pip install -r requirements.txt

Variáveis de ambiente

Criar um arquivo .env na raiz do projeto (nunca commitar este arquivo). A referência completa e sempre atualizada é o .env.example na raiz do repositório — copie-o e preencha. Principais grupos:

SECRET_KEY=sua-secret-key-aqui
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1

# Banco de dados (PostgreSQL 16 + TimescaleDB)
DB_NAME=energia_db
DB_USER=postgres
DB_PASSWORD=
DB_HOST=localhost
DB_PORT=5432

# MQTT (HiveMQ Cloud)
MQTT_HOST=seu-host.hivemq.cloud
MQTT_PORT=8883
MQTT_USERNAME=seu-usuario-mqtt
MQTT_PASSWORD=sua-senha-mqtt

# LangChain / OpenAI (assistente)
OPENAI_API_KEY=sua-chave-openai

# WhatsApp (Evolution API)
EVOLUTION_API_URL=http://localhost:8080
EVOLUTION_INSTANCE=energiabot
EVOLUTION_API_KEY=sua-chave-aqui

# Clima — Open-Meteo (gratuita, SEM API key; só coordenadas)
CLIMATE_LAT=-27.64
CLIMATE_LON=-48.67
CLIMATE_CITY=Palhoça, SC

# Alertas de anomalia (ver docs/alertas.md — modo demo: N=1 e cooldown=0)
ANOMALY_EVAL_EVERY_N=5
ANOMALY_COOLDOWN_MINUTES=30

Banco de dados

# Criar o banco no PostgreSQL
createdb energIA

# Ativar a extensão TimescaleDB no banco
psql energIA -c "CREATE EXTENSION IF NOT EXISTS timescaledb;"

# Rodar as migrações Django
python manage.py migrate

A conversão da tabela TelemetryReading em hypertable é feita automaticamente pela migração telemetry.0002_hypertable, que verifica se a função create_hypertable existe antes de executar — em um Postgres sem TimescaleDB a migração vira no-op e o sistema funciona normalmente (é o caso da produção atual, ver docs/arquitetura.md).

Executar o servidor

python manage.py runserver

Subscriber MQTT

O subscriber roda como processo separado:

python manage.py run_mqtt_subscriber

Em desenvolvimento, pode rodar em um segundo terminal junto com o servidor Django.

Site de documentação (MkDocs)

A pasta docs/ vira um site estático (MkDocs + Material, config em mkdocs.yml na raiz). Em desenvolvimento:

# Servidor com live-reload (porta 8002 para não conflitar com o runserver)
mkdocs serve -a 127.0.0.1:8002

# Build estático (gera ./site/, ignorado pelo git)
mkdocs build --strict

Em produção o site é servido em /docs/ pelo nginx — ver docs/DEPLOY.md seção 13.

TailwindCSS

# Instalar dependências Node
npm install

# Build de desenvolvimento (watch)
npm run dev

# Build de produção
npm run build

Apps Django registradas

Todas as apps já estão registradas em core/settings.py:

INSTALLED_APPS = [
    ...
    'accounts',
    'meters',
    'telemetry',
    'tariffs',
    'dashboard',
    'analytics',
    'assistant',
    'api',
]

Testes e CI

python manage.py check
python manage.py test

O workflow .github/workflows/tests.yml roda exatamente esses dois comandos automaticamente em todo push e pull_request, contra um postgres:16 comum (sem TimescaleDB — a migração telemetry.0002_hypertable já é condicional, ver seção "Banco de dados" acima). Badge de status no topo do README.md. SECRET_KEY/DB_* do job são valores fixos só para CI, não segredos reais — não é preciso configurar nada em "Secrets" do repositório para esse workflow funcionar.

Criar superusuário

python manage.py createsuperuser

O Django admin fica em /admin/.