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);mypyopcional. - I/O assíncrono. Bibliotecas bloqueantes em
asyncio.to_thread. except Exceptionsó em fronteiras (job da engine, ciclo de um dispositivo, envio de alerta, ferramenta da IA), sempre com# noqa: BLE001e log. Um item com falha não derruba os demais.- Erros para o usuário:
HTTPException(status, "mensagem em português")na API;PluginError/AuthErrornos plugins (a mensagem aparece emlast_errore 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_strpara 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_VERSIONe 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 mensagensver: 1) ou no schema sem migração. - As mensagens do barramento carregam
verpara 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 --strictprecisa passar sem avisos.- O site não pode depender de recursos externos (fontes, CDN, scripts inline), porque é servido sob a CSP do nginx.