Frontend¶
SPA em React 18 + TypeScript (strict), build com Vite 6, estilos com Tailwind CSS 4 (tokens de
tema em src/index.css), dados com @tanstack/react-query 5, gráficos ECharts 5, topologia
Cytoscape, grade de dashboards react-grid-layout, ícones lucide-react e fontes locais
(@fontsource-variable). Toda a interface está em pt-BR e funciona sem internet. Referência
completa no frontend/README.md.
Scripts¶
cd frontend
npm install
npm run dev # http://localhost:5173 com proxy /api -> http://127.0.0.1:8000 (QV_API_URL para mudar)
npm run build # tsc -b + vite build → dist/
npm run preview # serve dist/ em :4173 (também com proxy /api)
npm run lint # ESLint (sem any explícito)
npm run typecheck
npm run smoke # teste de fumaça: ~210 chamadas a 104 endpoints com os payloads da GUI
Estrutura de src/¶
| Pasta | Conteúdo |
|---|---|
api/ |
client.ts (fetch com Bearer, renovação automática do token, ApiError com o detail da API), endpoints.ts (uma função tipada por endpoint), hooks.ts (catálogo, plugins, useMetricQuery, useAction com toast e invalidação), types.ts |
auth/ |
AuthContext (sessão, troca obrigatória de senha, can(perm)) |
components/ |
kit base (ui.tsx: Button, Field, Input, Select, Switch, Panel, Tabs, Modal, Drawer, confirmDialog, Pager…), health.tsx (cores e badges de saúde), charts/ (TimeSeries com faixas de threshold, TopN, Heatmap, Histogram, Sparkline, Gauge), EntityPicker, Markdown, EntityLink, toast |
features/ |
dashboards/ (widgets e editor), topology/, insights/, capacity/, automation/ (formulário a partir de params_schema), ai/ (chat e painel flutuante), HealthMap, ChangeDiff |
layout/ |
AppShell, Sidebar (itens em nav.ts), GlobalSearch (Ctrl+K ou /), TimeRangePicker, UserMenu |
lib/ |
format.ts (números pt-BR, bytes binários, unidades, datas em America/Sao_Paulo, WWPN com “:”), entities.tsx, prefs.tsx (tema, período global, contexto da IA), csv.ts |
i18n/pt-BR.ts |
rótulos de domínio (saúde, severidade, categorias, status) |
pages/ |
uma página por rota; pages/admin/* para Administração |
Convenções¶
- Dados: chamadas só via
api.*. Leitura comuseQuerye chaves estáveis; mutações comuseAction(fn, { success, invalidate }). - Permissões:
useAuth().can("…")para ocultar/desabilitar ações. Rotas administrativas com<Perm perm="…">. - Tema: cores só por tokens CSS (
bg-surface,text-muted,text-crit…). Gráficos leem os tokens porchartTheme(). - Saúde: cores fixas para
ok/warning/critical/unknown, com forma redundante (losango, círculo vazado). - Formatação: nunca use
toFixed/toLocaleStringdireto; uselib/format.ts. - CSP: nada de scripts inline novos. O único script inline (tema, em
index.html) tem o hash emfrontend/nginx/security-headers.conf. Se mudá-lo, recalcule o hash (comando no comentário do arquivo).
Adicionar uma página¶
- Crie
src/pages/MinhaPagina.tsxexportandoMinhaPaginaPage. UsePageHeader,Panel, os estadosSkeletonRows/EmptyState/ErrorStateeuseAiPageContext({ page: "minha-pagina" }). - Funções de API em
api/endpoints.tse tipos emapi/types.ts. - Rota em
src/App.tsxcomlazy()(e<Perm>se for o caso). - Item de menu em
src/layout/nav.ts(ícone lucide, permissão opcional). - Inclua as chamadas novas em
scripts/smoke.mjs.
Adicionar um tipo de widget¶
- Registre em
WIDGET_TYPES(src/features/dashboards/widgets.tsx): rótulo,query: true/false,mode(modo doPOST /api/v1/metrics/query), descrição. - Renderize no
switchdeWidgetBody(ou deMetricWidget). Usedata.namespara rótulos e navegue para/entity/:idno clique. - Opções em
widget.options, com campos emWidgetEditor.tsx. - Inclua o tipo em
WIDGET_TYPESdebackend/quantix/api/routers/workspace.py(a API valida ao salvar).
Capturas de tela¶
frontend/scripts/screenshots.mjs gera capturas de todas as páginas (temas claro e escuro) com
Chromium headless, contra npm run preview. Requer puppeteer-core@23 e @sparticuz/chromium@131
instalados fora do pacote. As imagens desta documentação vêm desse script (tema escuro,
1440 px, laboratório de demonstração com 30 dias de histórico).