melhorias em compoenentes de numero

.agent/workflows/documentar-codigo.global.md

@@ -0,0 +1,58 @@
+---
+description: Workflow para criação e padronização de documentação em código (JSDoc, comentários e tipagem)
+---
+
+# Workflow: Documentar Código
+
+## 🎯 Objetivo
+Estabelecer um padrão global e unificado para a redação de documentação em código (comentários, `JSDoc` e explicações arquiteturais) em todas as aplicações, garantindo clareza sem prolixidade e respeitando a política de tipagem explícita.
+
+---
+
+## 1️⃣ Princípios Básicos de Documentação
+- **Por que, não o Quê**: Documente o raciocínio por trás da decisão arquitetural ou a regra de negócio que forçou a estratégia, não o mecanismo óbvio que o TypeScript nativamente expressaria.
+- **Nomenclatura Limpa**: Confie na auto-documentação de nomes de variáveis expressivos baseados no domínio antes de escrever um comentário de texto livre.
+
+## 2️⃣ Funções Compartilhadas e JSDoc (Obrigatória)
+Toda função central ou de uso compartilhado, independente da aplicação (frontend, backend, mobile ou bibliotecas comuns), deve portar cabeçalho em `JSDoc`.
+
+### Padrão para JSDoc
+```typescript
+/**
+ * Busca os detalhes de uma entidade baseando-se no ID fornecido e calcula privilégios aplicáveis.
+ * Não utilizar em fluxos de processamento em lote para evitar sobrecarga de requisições ou banco.
+ *
+ * @param tenantId  - Identificador único do cliente/tenant no sistema
+ * @param entityId  - ID exclusivo identificando o registro na base de dados
+ * @returns Retorna o objeto consolidado com dados ou `null` caso não seja encontrado
+ */
+export const obterDetalhesEntidade = async (tenantId: string, entityId: string) => { ... }
+```
+
+## 3️⃣ Tratamento de Exceções e Casts Temporários
+Devido à política `TypeScript sem any`, não utilizamos conversores obscuros imperativamente.
+Porém, se uma coerção agressiva (`as unknown as X`) demonstrar-se temporariamente necessária por divergência ou limitação de SDK terceiro, **o comentário justificando a anomalia é obrigatório**.
+
+```typescript
+// Necessário cast duplo pois a biblioteca externa não provê tipagem genérica adequada na versão atual
+const dados = payload.raw as unknown as RespostaFormatada
+```
+
+## 4️⃣ Atribuição de TODOs
+Toda refatoração, debito técnico visualizado ou dúvida de negócio deixada aberta em código de longo prazo **não prescreve** e deve ser acompanhada do formato `// TODO`:
+- **Tipagem**: `// TODO de tipagem: Criar interface estrita para o retorno da API de listagem (Removendo Partial)`
+- **Negócio**: `// TODO de regra: Validar com a equipe de Produto se a nova taxa adicional será inserida para clientes antigos.`
+
+## 5️⃣ Validação do Fluxo
+Sempre ao propor documentação de um arquivo novo ou refatorado, valide via checklist:
+* [ ] A documentação está aderente sem estar redundante à tipagem TS?
+* [ ] A formatação de parágrafos/espaçamento quebra alguma regra no formatador?
+* [ ] A sintaxe suporta autocompletion na sua camada dependente (`@params` estão exatos)?
+
+---
+
+## Referências
+
+- Rules: `.agent/rules/typescript-sem-any.global.md` (política de tipagem que influencia a documentação)
+- Skill: `.agent/skills/documentar-decisao-tecnica/SKILL.md` (para decisões arquiteturais que exigem ADR além de JSDoc)
+