Primeiro dia: desenvolvimento local¶

Local usa Docker Compose; produção usa Kubernetes. Este roteiro não cria HML no cluster e não deve usar dados ou credenciais reais de lojas.

Preparação¶

Git e acesso ao repositório oficial.
Docker Engine/Desktop ativo, com Compose compatível com include.
Para testes fora dos containers: Python 3.12, Poetry compatível com lockfiles e Node/npm conforme CI e lockfile do painel.
Recursos para PostgreSQL, Redis, MinIO, Weaviate e módulos necessários.

Crie a branch conforme o fluxo do desenvolvedor. Prepare arquivos locais ignorados pelo Git a partir de infra/.env.example e exemplos dos módulos; marketing também tem .env.local.example. Gere chaves internas locais e mantenha pares cliente/servidor coerentes. Não copie secrets de produção.

Compose também executa integrações

O agregado inclui proxy/túnel opcionais e tarefas automáticas. Revise a configuração e escolha serviços explicitamente. Não inicie tudo com credenciais reais para descobrir como funciona.

Infraestrutura local e migrations¶

Na raiz do repositório:

docker compose -f infra/docker-compose.yaml config --quiet
docker compose -f infra/docker-compose.yaml up -d merchants-db redis minio weaviate
docker compose -f infra/docker-compose.yaml run --rm minio-init
docker compose -f infra/docker-compose.yaml run --rm db-migrate

Antes da migration, confira que o banco é o serviço local merchants-db, nunca produção. Investigue erros antes de iniciar consumidores. Não usar stamp ou apagar tabelas para contornar falhas.

Módulos da aplicação¶

Após preparar dependências e integrações locais de teste:

docker compose -f infra/docker-compose.yaml up -d --build frontend-entrypoint whatsapp-entrypoint genai-wrapper woocommerce-wrapper b2b b2c marketing-campaigns landing panel flow-gateway
docker compose -f infra/docker-compose.yaml ps
docker compose -f infra/docker-compose.yaml logs --tail=100 frontend-entrypoint

Gateway local: http://127.0.0.1:3080 por padrão, alterável por FLOW_GATEWAY_PORT. /health não comprova todas as integrações. WhatsApp precisa de callback HTTPS acessível e recursos Meta próprios de teste; localhost não recebe eventos externos sozinho. Não expor banco, Redis ou APIs internas por túnel.

Para trabalhar no frontend, em modules/panel:

npm ci
npm run dev

Confira proxy em vite.config.ts e API local antes de testar autenticação. Não apontar frontend de desenvolvimento para produção como atalho.

Testes antes do MR¶

No módulo Python alterado:

poetry install --with dev --no-root
poetry check
poetry run task test

Se não houver task test, use poetry run pytest tests. Tasks com PYTHONPATH=... usam sintaxe POSIX: no Windows, execute em WSL/shell compatível ou configure o equivalente no PowerShell. Use fakes ou recursos descartáveis, sem kubeconfig/secrets de produção.

No painel:

npm test
npm run build

Para documentos: build estrito. CI repete testes no commit integrado; aprovação local não substitui a esteira.

Encerrar sem apagar dados¶

docker compose -f infra/docker-compose.yaml stop

Não adicionar remoção de volumes sem confirmar que são descartáveis. READMEs dos módulos complementam o roteiro, mas confira nomes/variáveis efetivos no código e Compose atual.