otimização do agent para docuemntação

rules/jsdoc-padrao.md

@@ -1,59 +1,115 @@
 ---
 type: rule
 name: jsdoc-padrao
-description: Padrões de documentação em código (JSDoc, casts temporários e TODOs estruturados)
+description: Padrões de documentação em código-fonte (comentários claros e coerentes quanto à aplicação, JSDoc, casts e TODOs).
 scope: global
 trigger: file_match
 globs:
   - "**/*.ts"
   - "**/*.tsx"
   - "**/*.vue"
-updatedAt: "2026-06-01"
+  - "**/*.js"
+updatedAt: "2026-09-01"
 ---
 
-# Regra: Documentação em Código
+# Regra: Documentação e Comentários no Código-Fonte
 
-## 1. JSDoc — Princípios
+## 1. Princípio Fundamental
 
-- **Por que, não o Quê**: documente o raciocínio, não o mecanismo que o TypeScript já expressa.
-- **Nomenclatura limpa**: confie em nomes expressivos antes de comentários.
+> **O código-fonte deve receber comentários claros e coerentes quanto à sua aplicação.**
 
-## 2. JSDoc obrigatório em funções compartilhadas
+Comentários no código-fonte não existem para descrever o óbvio sintático (que a tipagem TypeScript já fornece), mas sim para **explicar o propósito prático, o contexto operacional no sistema e as regras de negócio** que regem aquela função, método, componente ou rota.
 
-Toda função central ou de uso compartilhado deve ter cabeçalho JSDoc:
+---
+
+## 2. JSDoc Obrigatório em Funções, Serviços, Rotas e Composables
+
+Toda função central, serviço de negócio (`servicos/`), endpoint/rota (`rotas/`), query de banco (`banco/`), composable (`composables/`) ou método compartilhado deve possuir cabeçalho JSDoc com:
+
+1. **Descrição da Aplicação Prática**: Para que serve no sistema e em quais cenários operacionais é utilizada.
+2. **Contexto de Negócio / Regras**: Restrições, validações críticas e impactos em outras partes da aplicação.
+3. **Parâmetros (`@param`)**: Significado contextual de cada parâmetro (não apenas repetir o nome).
+4. **Retorno (`@returns`)**: Estrutura e significado do valor retornado em sucesso ou falha/nulo.
+5. **Efeitos Colaterais / Exceções (`@throws`)**: Filas disparadas, transações, logs ou erros esperados.
+
+### Exemplo Correto ✅
 
 ```typescript
 /**
- * Busca detalhes da entidade e calcula privilégios aplicáveis.
- * Não utilizar em processamento em lote para evitar sobrecarga.
+ * Calcula o balanço volumétrico e a carga de efluentes tratados para o período informado.
+ * Aplica as diretrizes da Resolução CONAMA nº 430/2011 e regras de tolerância do ponto de descarte.
  *
- * @param tenantId  - Identificador do tenant no sistema
- * @param entityId  - ID do registro na base de dados
- * @returns Objeto consolidado ou `null` se não encontrado
+ * Aplicação: Utilizado na geração do relatório mensal e no cálculo de conformidade antes do envio de alertas.
+ *
+ * @param tenantId  - Identificador do empreendimento no sistema
+ * @param pontoId   - ID do ponto de monitoramento cadastrado
+ * @param periodo   - Intervalo de datas para consolidação das leituras
+ * @returns Balanço consolidado contendo vazão média, picos e índice de conformidade
+ * @throws {ErroValidacaoParametros} Se o ponto não possuir medições no período
  */
-export const obterDetalhes = async (tenantId: string, entityId: string) => { ... }
+export const calcularBalancoEfluentes = async (
+  tenantId: string,
+  pontoId: string,
+  periodo: IntervaloDatas
+): Promise<BalancoConsolidado> => { ... }
 ```
 
-## 3. Casts temporários — justificativa obrigatória
-
-Coerções agressivas requerem comentário explicando o porquê:
+### Exemplo Incorreto ❌
 
 ```typescript
-// Necessário: biblioteca externa não provê tipagem genérica na versão atual
-const dados = payload.raw as unknown as RespostaFormatada
+/**
+ * Calcula efluentes.
+ * @param tenantId string
+ * @param pontoId string
+ * @param periodo object
+ */
+export const calcularBalancoEfluentes = async (...) => { ... }
 ```
 
-## 4. TODOs estruturados
+---
 
-Dívida técnica ou dúvida de negócio deve seguir formato padronizado:
+## 3. Comentários Inline Contextuais e Expressivos
 
-- **Tipagem**: `// TODO de tipagem: Criar interface para o retorno da API`
-- **Negócio**: `// TODO de regra: Validar com Produto se taxa se aplica a clientes antigos`
+Use comentários inline (`//`) para esclarecer:
+- Decisões de cálculo e fórmulas não-triviais.
+- Tratamento de casos de borda e regras de exceção.
+- Ordem de execução de passos críticos (ex: pipeline de transformação de dados).
+
+```typescript
+// Regra: se o pH estiver fora da faixa 6.0-9.0, o registro é marcado como não-conforme
+const estaConforme = leitura.ph >= 6.0 && leitura.ph <= 9.0
+```
+
+---
+
+## 4. Casts Temporários — Justificativa Obrigatória
+
+Qualquer coerção de tipo (`as unknown as T`, `as T`) exige comentário explicando o motivo técnico:
+
+```typescript
+// Necessário: biblioteca de terceiros não exporta a tipagem dos metadados na v2
+const metadados = resposta.raw as unknown as MetadadosConexao
+```
+
+---
+
+## 5. TODOs Estruturados
+
+Dívidas técnicas ou dúvidas de negócio devem ser registradas de forma padronizada:
+
+- **Tipagem**: `// TODO de tipagem: Migrar retorno bruto para schema Zod zBalancoRetorno`
+- **Negócio**: `// TODO de regra: Confirmar com Operador se tolerância de DBO aplica-se a descarte pluvial`
+
+---
 
 ## Impacto
 
-Sem este padrão, funções compartilhadas ficam sem documentação, casts aparecem sem justificativa, e TODOs são inconsistentes e difíceis de buscar.
+Código autoexplicativo e devidamente contextualizado acelera a manutenção, evita regressões de regras e permite que desenvolvedores e agentes de IA compreendam instantaneamente o impacto de qualquer alteração.
+
+---
 
 ## Referências
 
-- Rule: `global/rules/typescript-sem-any`
+- Rule: `rules/ddd-documentacao-primeiro.md`
+- Rule: `rules/regras-negocio-md.md`
+- Rule: `rules/typescript-sem-any.md`