Pular para conteúdo

Padrões de código

Python

  • Python ≥ 3.11, from __future__ import annotations, tipagem em funções públicas.
  • Código e docstrings em português (domínio) e identificadores em inglês. Cada módulo começa com docstring explicando o porquê (ex.: tsdb.py, bus.py, ratings.py).
  • Linhas de até ~120 colunas. ruff é usado no desenvolvimento (sem configuração versionada na v1.0.0); mypy opcional.
  • I/O assíncrono. Bibliotecas bloqueantes em asyncio.to_thread.
  • except Exception só em fronteiras (job da engine, ciclo de um dispositivo, envio de alerta, ferramenta da IA), sempre com # noqa: BLE001 e log. Um item com falha não derruba os demais.
  • Erros para o usuário: HTTPException(status, "mensagem em português") na API; PluginError / AuthError nos plugins (a mensagem aparece em last_error e no teste de conexão).
  • Nada de SQL com texto do usuário concatenado: SQLAlchemy com parâmetros; ClickHouse via QueryEngine/parâmetros {nome:Tipo}.
  • Segredos nunca em log nem em resposta da API. Use encrypt_json/encrypt_str para persistir.

Logging

setup_logging(service) configura JSON em stdout (QV_LOG_JSON). Use loggers quantix.<área> e campos estruturados via extra:

log = logging.getLogger("quantix.collector")
log.info("inventário publicado", extra={"device": d["name"], "rows": n})

Campos reconhecidos: device_id, device, plugin, collector, job, duration_ms, rows. Bibliotecas ruidosas (httpx, asyncssh, nats…) ficam em WARNING.

Internacionalização

A v1.0.0 é somente pt-BR: mensagens da API, textos de achados (detalhe e recomendação) e interface. Rótulos de domínio da GUI estão centralizados em frontend/src/i18n/pt-BR.ts; números e datas em lib/format.ts (formato brasileiro, America/Sao_Paulo). general.language existe no registro de variáveis para uma futura tradução, mas ainda não tem efeito.

Catálogo como contrato

Novos tipos de objeto, relações ou métricas entram primeiro em common/catalog.py. Plugins, engine, consultas e GUI dependem dele. Depois de alterar, rode python docs/gen_reference.py.

Versionamento

  • Versão única do produto em backend/quantix/__init__.py (__version__), pyproject.toml, Chart.yaml (version/appVersion), QV_VERSION e tags das imagens (1.0.0, 1.0.0-lab).
  • SemVer: patch para correções; minor para funcionalidades compatíveis (novos plugins, regras, endpoints); major para mudanças incompatíveis na API pública, no contrato do coletor (/api/v1/collector/*, formato das mensagens ver: 1) ou no schema sem migração.
  • As mensagens do barramento carregam ver para permitir evolução compatível.
  • Registre as mudanças em Changelog.

Documentação

  • Páginas de referência geradas do código (docs/gen_reference.py, docs/gen_api.py), nunca editadas à mão.
  • mkdocs build --strict precisa passar sem avisos.
  • O site não pode depender de recursos externos (fontes, CDN, scripts inline), porque é servido sob a CSP do nginx.