mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-02 13:22:11 +03:00
492afc4ff1
T-15 — Decompose usageDb.js (969→40 lines): - Extract src/lib/usage/migrations.js (legacy + JSON→SQLite migration) - Extract src/lib/usage/usageHistory.js (tracking, pending, log.txt) - Extract src/lib/usage/costCalculator.js (pure cost calculation) - Extract src/lib/usage/usageStats.js (dashboard aggregation) - Extract src/lib/usage/callLogs.js (structured logs, CRUD, rotation) - usageDb.js is now a thin facade re-exporting all functions T-28 — Decompose handleSingleModelChat (183→80 lines): - Extract handleNoCredentials() — credential error responses - Extract safeResolveProxy() — proxy resolution with error handling - Extract safeLogEvents() — fire-and-forget proxy + translation logging - Also created chatHelpers.js with standalone helper exports T-29 — Extract shared UI primitives (3230 total lines): - FilterBar.js — search input + filter chips dropdown - ColumnToggle.js — table column visibility toggle - DataTable.js — generic data table with sticky header, loading/empty Tests: 88/88 pass (no regressions)
5.4 KiB
5.4 KiB
FASE 06 — Documentação e Governança
Prioridade: 🟡 Moderado
Estimativa de Complexidade: Baixa-Média (2–4 dias)
Dimensões do Relatório: D4 (Documentação)
Dependências: FASE-03 (decisões arquiteturais para ADRs), FASE-05 (padrões de código para CONTRIBUTING)
Objetivo
Completar a documentação do projeto com ADRs, guia de contribuição, política de segurança expandida, e padronização de comentários inline, garantindo que novos contribuidores tenham contexto suficiente para entender e contribuir com o projeto.
Escopo Detalhado
6.1 — Architecture Decision Records (ADRs)
Origem no relatório: D4 — Ausência de ADRs (🟡 Moderado)
Especificação Técnica
- Criar diretório
docs/adr/com templatedocs/adr/000-template.md. - Criar ADRs iniciais:
| ADR # | Título | Decisão |
|---|---|---|
| 001 | Escolha de SQLite como Database | Justificar SQLite vs PostgreSQL para single-tenant |
| 002 | Padrão de Fallback entre Providers | Documentar estratégias fill-first, round-robin, p2c |
| 003 | Estratégia de OAuth Multi-Provider | Documentar escolha de Strategy pattern (FASE-03) |
| 004 | JavaScript + JSDoc vs TypeScript | Documentar decisão de tipagem (FASE-05) |
| 005 | Sistema Single-Tenant | Documentar escopo sem multi-tenancy |
| 006 | Tradução de Formatos LLM | Documentar pattern Registry do Translator |
- Formato ADR: Status, Contexto, Decisão, Consequências (formato Nygard).
Critérios de Aceite
- Template ADR criado e documentado.
- ≥ 6 ADRs cobrindo decisões-chave do projeto.
- ADRs referenciados no README e ARCHITECTURE.md.
6.2 — CONTRIBUTING.md
Origem no relatório: D4 — CONTRIBUTING.md Ausente (🟡 Moderado)
Especificação Técnica
- Criar
CONTRIBUTING.mdna raiz com seções:- Getting Started — Setup do ambiente,
npm install, env vars obrigatórias. - Development Workflow — Branch naming, commit convention (Conventional Commits).
- Coding Standards — JSDoc obrigatório, ESLint, Prettier.
- Testing — Como rodar testes unitários, e2e, e coverage.
- PR Process — Template de PR, reviewers, CI checks obrigatórios.
- Architecture — Link para ARCHITECTURE.md e ADRs.
- Getting Started — Setup do ambiente,
- Criar
.github/PULL_REQUEST_TEMPLATE.mdcom checklist padrão.
Critérios de Aceite
CONTRIBUTING.mdcriado com todas as 6 seções.- PR template criado e ativo no GitHub.
- README referencia CONTRIBUTING.md.
6.3 — Expansão do SECURITY.md
Origem no relatório: D4 — SECURITY.md Insuficiente (🟡 Moderado)
Especificação Técnica
- Expandir
SECURITY.mdde 619 bytes para ≥ 2KB com:- Responsible Disclosure Policy — Como reportar vulnerabilidades.
- Vulnerability Scope — Tipos aceitos (RCE, XSS, SSRF, auth bypass, etc.).
- Response SLA — Prazo de resposta (48h ack, 7 dias para fix P0).
- Security Contact — Email ou canal dedicado.
- Security Best Practices — Instruções para configurar segredos fortes.
- Known Limitations — Documentar limitações de segurança do single-tenant.
Critérios de Aceite
- SECURITY.md ≥ 2KB com todas as 6 seções.
- Formato segue GitHub Security Advisories best practices.
- Link no README para SECURITY.md.
6.4 — Padronização de JSDoc em Funções Exportadas
Origem no relatório: D4 — Inline Comments inconsistentes (🟢 Menor)
Especificação Técnica
- Definir padrão: toda função exportada DEVE ter JSDoc com
@param,@returns,@throws. - Priorizar módulos públicos:
src/lib/db/*.js— Funções de DB.src/shared/utils/*.js— Utilitários.src/domain/*.js— Domain services (módulos novos da FASE-03).src/sse/services/*.js— Services de streaming.
- ESLint: Ativar
jsdoc/require-jsdoccomowarnparaexportfunctions.
Critérios de Aceite
- ≥ 80% das funções exportadas em módulos priorizados têm JSDoc.
- ESLint rule
jsdoc/require-jsdocativa. - CONTRIBUTING.md documenta o padrão de JSDoc.
Pré-Requisitos
- FASE-03 (decisões de refatoração para ADRs) e FASE-05 (padrões de código para CONTRIBUTING).
Entregáveis
- Diretório
docs/adr/com ≥ 6 ADRs. CONTRIBUTING.mdcompleto.SECURITY.mdexpandido.- JSDoc em funções exportadas.
- PR template.
Critérios de Conclusão da Fase
- Todos os documentos criados e revisados.
- README atualizado com links para novos docs.
- ESLint rule de JSDoc ativa.
Riscos Identificados
| Risco | Probabilidade | Impacto | Mitigação |
|---|---|---|---|
| ADRs ficam desatualizados rapidamente | Média | Baixo | Revisão trimestral agendada |
| JSDoc obrigatório reduz velocidade de contribuição | Baixa | Baixo | Começar com warn, não error |
| SECURITY.md cria expectativas de SLA não cumpridas | Baixa | Médio | SLA realista e comunicado |