Ambiente local
O ambiente local separa os serviços de dados das interfaces. O Compose da API sobe PostgreSQL, Redis, MinIO, Mailpit, API e worker. As três SPAs rodam como processos do host.
Pré-requisitos
Use Python 3.12 ou superior para a API, Docker com Compose para a stack local e Node compatível com os pacotes frontend. Os testes do portal exigem Node 22.18 ou superior. Respeite a versão de pnpm indicada no packageManager de cada projeto.
Preparar a API
A partir da raiz do repositório:
cd application/api
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
cd ..
make up
make migrate
make up prepara a configuração local quando ausente, inicia o PostgreSQL e reaplica o bootstrap idempotente de roles antes de subir a stack. Use os modelos locais de configuração e mantenha arquivos reais de ambiente fora do controle de versão.
O primeiro titular de plataforma é criado pelo target make seed. Ele é exclusivo da preparação local e usa variáveis próprias de bootstrap. Defina os dados da sua conta de desenvolvimento antes de executá-lo; não reutilize os valores de exemplo em ambientes compartilhados.
Executar as interfaces
Abra um terminal para cada SPA:
cd application/console
pnpm install
pnpm dev
Repita em application/backoffice e application/portal.
| Superfície | Endereço local |
|---|---|
| API | http://localhost:8000 |
| Console | http://localhost:5173 |
| Backoffice | http://localhost:5174 |
| Portal | http://localhost:5175 |
Não adicione essas SPAs ao Compose. A API também não deve servir o HTML das interfaces.
Conferir funcionamento
Use GET /health/live para verificar se o processo responde e GET /health/ready para verificar dependências. No desenvolvimento, /docs, /redoc e /openapi.json expõem o contrato da API. Esses três caminhos estão desligados em produção.
make logs acompanha API e worker. make down interrompe a stack preservando os volumes. Mudanças em migrações exigem make migrate; mudanças em roles de cluster exigem make roles.
Problemas de login, OAuth e serviços locais devem ser reproduzidos com dados fictícios. Veja testes para o mock OIDC e os testes de integração.