Ambiente local¶
Instalar a aplicação¶
Execute os comandos na raiz do repositório. O Windows procura .venv312 antes de .venv; o launcher Unix exige .venv/bin/python.
py -3.12 -m venv .venv312
.\.venv312\Scripts\Activate.ps1
python --version
python -m pip install -e '.[dev]'
Copy-Item .env.example .env
python3.12 -m venv .venv
source .venv/bin/activate
python --version
python -m pip install -e '.[dev]'
cp .env.example .env
Copie o exemplo somente quando ainda não existir .env. Edite o arquivo localmente para configurar a chave OpenAI se for usar o chat. python --version deve mostrar 3.12.x para reproduzir o runtime AWS. O extra dev instala moto, pytest, HTTPX e Uvicorn, necessários para o dashboard e testes.
Se a política do PowerShell impedir a ativação, use o executável completo: .\.venv312\Scripts\python.exe -m pip install -e '.[dev]'. Ativação só muda a resolução de comandos no terminal; não é requisito para executar Python.
Isolar efeitos externos¶
Para uma sessão de desenvolvimento com adapters fictícios, sobrescreva explicitamente as flags antes de iniciar. O loader do dashboard usa os.environ.setdefault, portanto variáveis exportadas pelo terminal têm precedência sobre .env.
$env:WHATSAPP_CLOUD_ENABLED = 'false'
$env:HUBSPOT_ENABLED = 'false'
$env:EGESTOR_ENABLED = 'false'
$env:HANDOFF_NOTIFIER_ENABLED = 'false'
$env:SMOKE_ALLOW_REAL_SEND = 'false'
$env:SMOKE_ALLOW_REAL_WRITE = 'false'
$env:SMOKE_ALLOW_REAL_EMAIL = 'false'
$env:DEV_UI_ENABLED = 'true'
.\.venv312\Scripts\python.exe scripts/dashboard.py
export WHATSAPP_CLOUD_ENABLED=false HUBSPOT_ENABLED=false
export EGESTOR_ENABLED=false HANDOFF_NOTIFIER_ENABLED=false
export SMOKE_ALLOW_REAL_SEND=false SMOKE_ALLOW_REAL_WRITE=false
export SMOKE_ALLOW_REAL_EMAIL=false DEV_UI_ENABLED=true
.venv/bin/python scripts/dashboard.py
Esses comandos não desabilitam a OpenAI. O chat continua usando o cliente real. Sem chave, o processo imprime um aviso; partes da UI que constroem Dependencies podem falhar porque load_settings() exige a chave. Para executar somente os testes/replays, siga testes unitários, cujas fixtures fornecem doubles e configuração fictícia.
Modo local não significa todos os providers simulados
mock_aws intercepta AWS. Ele não intercepta a API HTTP da OpenAI, Meta, CRM ou eGestor. Uma flag habilitada pode causar tráfego real. O servidor do dashboard escuta 0.0.0.0; mantenha-o em uma rede de desenvolvimento controlada.
Usar os launchers existentes¶
.\start.bat
# Para encerrar a instância local:
.\stop.bat
./start
# Se o checkout não preservou a permissão executável:
bash start
# Para encerrar a instância local:
./stop
start.bat seleciona o primeiro Python funcional em .venv312, .venv ou VIRTUAL_ENV, exige .env e chave, inicia em background e abre http://localhost:8080. Os logs ficam em gogenetic-dashboard.log e gogenetic-dashboard.err.log.
start termina processos que correspondam a scripts/dashboard.py, faz source .env, inicia o servidor e consulta /healthz. Usa o comando macOS open para abrir o navegador; no Linux, se esse comando não existir, abra a URL manualmente. Os logs ficam em /tmp/gogenetic-dashboard.log. Como source .env executa atribuições no shell, as flags desse arquivo substituem exports anteriores nesse launcher.
Limitações dos launchers
Ambos imprimem um prefixo da chave no terminal; não compartilhe a saída bruta. Ambos verificam a porta 8080 mesmo que DASHBOARD_PORT seja diferente. stop.bat também encerra qualquer processo que esteja escutando 8080; confira que essa porta pertence ao dashboard. Para desenvolvimento previsível, o comando Python em primeiro plano permite encerrar com Ctrl+C.
DynamoDB local¶
scripts/dashboard.py cria uma tabela moto com PK, SK, GSI1 e TTL ttl. O nome é DYNAMODB_TABLE, com fallback gogenetic-agent-local. Remove AWS_ENDPOINT_URL e AWS_ENDPOINT_URL_DYNAMODB para evitar que .env.example redirecione as chamadas para a porta 8000.
Os dados são descartados ao encerrar o processo. Não instale DynamoDB Local para esse percurso. Já build_dependencies() fora desse launcher usa boto3.resource('dynamodb'): sem moto, o endpoint e as credenciais passam a importar. O repositório não inicializa automaticamente uma tabela em um servidor DynamoDB Local independente.
Diagnóstico de instalação¶
| Sintoma | Verificação e ação |
|---|---|
py -3.12 indisponível |
Instale Python 3.12; py -0p lista os runtimes registrados no Windows |
| Venv ausente ou quebrado | Recrie o venv no path esperado e repita pip install -e '.[dev]' |
ModuleNotFoundError: moto / uvicorn |
O extra dev não está instalado nesse Python; use o executável do venv no comando pip |
| Porta ocupada | Confirme o PID antes de encerrar; ou use DASHBOARD_PORT com execução Python direta |
EndpointConnectionError na porta 8000 |
Confirme que usou scripts/dashboard.py; ele remove overrides de DynamoDB antes do moto |
| Chave não carregada | Confirme nome da variável e loader utilizado, sem imprimir seu valor |
| UI indisponível | DEV_UI_ENABLED=false herdado não é sobrescrito por setdefault; exporte true para uso local |
Implementação: start, start.bat, stop, stop.bat, scripts/dashboard.py, src/core/integrations/factory.py. Validação: tests/unit/lambdas/test_emulator.py, tests/conftest.py.
Continue em primeira execução e dashboard local.