Setup e instalação
Versão detalhada do README.
Requisitos
| Ferramenta | Versão |
|---|---|
| Node.js | 20 (CI e Docker node:20-alpine) |
| npm | o que vem com Node 20; use package-lock.json |
| Git | qualquer recente |
| Docker Desktop | opcional, para docker compose |
Não há .nvmrc; alinhe o Node ao CI.
1. Clonar e instalar
git clone https://github.com/Gevtech/ARKUS_FRONTEND.git
cd ARKUS_FRONTEND
cp .env.example .env
npm ci
npm install só se precisar regenerar o lockfile (PR separado).
2. Variáveis de ambiente
Contrato: .env.example. Tipos: src/vite-env.d.ts.
| Variável | Obrigatória | Notas |
|---|---|---|
VITE_API_BASE_URL | de facto em prod | Central. Vazio = same-origin + proxy |
VITE_GOVERNANCE_API_BASE_URL | de facto em prod | Default. Em DEV ausente → same-origin |
VITE_API_PROXY_TARGET | só dev same-origin | alvo do proxy Central |
VITE_GOVERNANCE_API_PROXY_TARGET | só dev same-origin | alvo do proxy Default |
VITE_SESSION_VAULT_SECRET | produção | ≥16 chars; cifra localStorage |
VITE_TENANT_ID | opcional | header se JWT sem tenant |
VITE_DEFAULT_GOVERNANCE_COMPANY_UUID | opcional | fallback de empresa-mãe |
VITE_LOGIN_TENANT_SLUG | opcional | logo/banner do login |
Nunca commitar .env. VITE_* vai para o JavaScript do cliente.
3. Subir o front
npm run dev
Abra a URL que o Vite imprimir (em geral http://localhost:5173). Sem backends locais, o proxy tenta localhost:3000 / :3001 e cai nos hosts remotos de src/config/api.ts.
Login: usuário da API Central. Primeiro acesso / reset dependem de e-mail configurado no backend.
4. Docker local
# .env na raiz com VITE_API_BASE_URL (build-arg)
docker compose up --build
- Porta host: 3000 → container 80
- Nginx:
try_filesSPA (nginx.conf) - Rebuild obrigatório se mudar
VITE_*
5. Qualidade local
npm run lint
npm run test
npm run test:coverage
npm run build
Sonar: sonar-project.properties + secrets SONAR_TOKEN / SONAR_HOST_URL no GitHub (não rode token no laptop a menos que o time peça).
6. i18n e tema
- Textos:
src/locales/pt-BR/translation.jsoneen/translation.json - Tema:
src/theme— spec emdoc-dark-mode.md
Problemas comuns
| Sintoma | Causa típica |
|---|---|
| CORS no login | VITE_API_BASE_URL absoluto sem CORS no backend; use same-origin vazio + proxy |
| Presença não conecta | WebSocket /socket.io não proxied; ver getSocketApiOrigin |
| Lista de empresas vazia | host Default vs Central; JWT sem permissão; filtro “Todas” vs filiais |
| Sessão some no F5 | vault; VITE_SESSION_VAULT_SECRET mudou |
| 401 imediato | interceptor; token expirado; relogin |
| Form-fields 404 | rota Default-only indo para Central — proxy isDefaultApiOnlyGovernanceRoute |