Pular para conteúdo

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 com useQuery e chaves estáveis; mutações com useAction(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 por chartTheme().
  • Saúde: cores fixas para ok/warning/critical/unknown, com forma redundante (losango, círculo vazado).
  • Formatação: nunca use toFixed/toLocaleString direto; use lib/format.ts.
  • CSP: nada de scripts inline novos. O único script inline (tema, em index.html) tem o hash em frontend/nginx/security-headers.conf. Se mudá-lo, recalcule o hash (comando no comentário do arquivo).

Adicionar uma página

  1. Crie src/pages/MinhaPagina.tsx exportando MinhaPaginaPage. Use PageHeader, Panel, os estados SkeletonRows/EmptyState/ErrorState e useAiPageContext({ page: "minha-pagina" }).
  2. Funções de API em api/endpoints.ts e tipos em api/types.ts.
  3. Rota em src/App.tsx com lazy() (e <Perm> se for o caso).
  4. Item de menu em src/layout/nav.ts (ícone lucide, permissão opcional).
  5. Inclua as chamadas novas em scripts/smoke.mjs.

Adicionar um tipo de widget

  1. Registre em WIDGET_TYPES (src/features/dashboards/widgets.tsx): rótulo, query: true/false, mode (modo do POST /api/v1/metrics/query), descrição.
  2. Renderize no switch de WidgetBody (ou de MetricWidget). Use data.names para rótulos e navegue para /entity/:id no clique.
  3. Opções em widget.options, com campos em WidgetEditor.tsx.
  4. Inclua o tipo em WIDGET_TYPES de backend/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).