Atualização floresta

.agent/workflows/otimizar-codigos.global.md

@@ -0,0 +1,221 @@
+---
+description: Otimizar código e documentar padrões de qualidade (estrutura, limites, JSDoc e tipagem)
+---
+
+
+
+# Workflow: Qualidade e Documentação de Código
+
+## 🎯 Objetivo
+
+Unificar as regras de **estrutura de arquivos**, **otimização** e **documentação** em um único fluxo de referência para o projeto `eli-vue`.
+
+---
+
+## 1️⃣ Limite de Linhas por Arquivo
+
+Nenhum arquivo `*.vue`, `*.ts` ou `*.tsx` pode ultrapassar **250 linhas**.
+
+Essa regra existe para facilitar a leitura humana, a revisão de código e a manutenção a longo prazo.
+
+> O script `scripts/check-vue-linhas.sh` valida automaticamente os arquivos `.vue` no `prebuild`.
+
+**Estratégias quando o limite se aproxima:**
+
+| Situação | Ação |
+|---|---|
+| Template longo | Extrair seções como subcomponentes |
+| CSS extenso | Mover para `<nome>.css` co-localizado |
+| `setup()` extenso | Extrair subcomponentes, CSS ou Dispatch Table |
+| Modal/Dialog embutido | Sempre em componente separado (`*Modal.vue`) |
+| Handlers e dispatch | Extrair para `handlers.ts` ou `dispatch.ts` |
+
+---
+
+## 2️⃣ Estrutura de Componentes Vue
+
+### `defineComponent` obrigatório
+
+Todo componente Vue deve usar `defineComponent` para garantir inferência de tipos correta e consistência.
+
+```vue
+<script lang="ts">
+import { defineComponent } from 'vue'
+
+export default defineComponent({
+  name: 'MeuComponente',
+  setup() {
+    // lógica aqui
+  }
+})
+</script>
+```
+
+**Por que é importante:**
+- Inferência de tipos TypeScript correta dentro do componente
+- Reconhecimento por ferramentas de análise estática e IDEs
+- Compatível com Options API e Composition API com `setup()`
+- Padronização entre todos os componentes do projeto
+
+---
+
+### `setup()` não pode ser externo
+
+O `setup()` deve estar sempre dentro do componente `.vue`. Não é permitido extrair ou delegar o `setup` para nenhum arquivo externo.
+
+```ts
+// ❌ Proibido — setup delegado inteiramente para arquivo externo
+// useEliTabela.ts
+export function useEliTabela(props, emit) { ... }
+
+// EliTabela.vue
+export default defineComponent({
+  setup(props, { emit }) {
+    return useEliTabela(props, emit)  // setup é apenas um proxy vazio
+  }
+})
+```
+
+```ts
+// ✅ Correto — setup com lógica própria dentro do componente
+// EliTabela.vue
+export default defineComponent({
+  setup(props, { emit }) {
+    const estado = ref(null)
+    const carregar = async () => { ... }
+    return { estado, carregar }
+  }
+})
+```
+
+> Composables `use*.ts` podem encapsular lógica reutilizável pontual (ex: `useFormatador`, `usePermissao`), mas nunca substituir ou esvaziar o `setup()` do componente. Se o componente ultrapassar 250 linhas, a solução é extrair subcomponentes, mover CSS ou usar Dispatch Table — não esvaziar o `setup`.
+
+---
+
+### Desassociação de CSS
+
+A separação de estilos em arquivo externo é permitida e recomendada quando o CSS contribui significativamente para o total de linhas.
+
+**Padrão de nomenclatura:**
+
+```
+MeuComponente.vue
+MeuComponente.css
+```
+
+O `.vue` importa o arquivo CSS no script:
+
+```ts
+import './MeuComponente.css'
+```
+
+Ou via tag `<style>`:
+
+```vue
+<style src="./MeuComponente.css" />
+```
+
+---
+
+### Dispatch Table em Arquivo Separado
+
+O uso de Dispatch Table (mapa de funções) em arquivos separados é bem-vindo para eliminar blocos longos de `if/else` ou `switch`.
+
+```ts
+// handlers.ts
+export const acaoHandlers: Record<string, () => void> = {
+  salvar: () => { ... },
+  cancelar: () => { ... },
+  excluir: () => { ... },
+}
+```
+
+```ts
+// MeuComponente.vue
+import { acaoHandlers } from './handlers'
+
+function executar(acao: string) {
+  acaoHandlers[acao]?.()
+}
+```
+
+---
+
+## 3️⃣ Documentação em Código (JSDoc)
+
+### Princípios básicos
+
+- **Por que, não o Quê**: Documente o raciocínio por trás da decisão arquitetural, não o mecanismo óbvio que o TypeScript já expressa.
+- **Nomenclatura limpa**: Confie na auto-documentação de nomes expressivos antes de escrever comentários de texto livre.
+
+### Funções compartilhadas — JSDoc obrigatório
+
+Toda função central ou de uso compartilhado (frontend, backend, mobile ou bibliotecas comuns) deve ter cabeçalho em `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.
+ *
+ * @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) => { ... }
+```
+
+---
+
+## 4️⃣ Casts Temporários e Exceções de Tipagem
+
+Devido à política **TypeScript sem any**, coerções agressivas requerem justificativa obrigatória em comentá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
+```
+
+---
+
+## 5️⃣ TODOs Estruturados
+
+Toda dívida técnica ou dúvida de negócio deixada em código deve seguir o formato `// TODO`:
+
+- **Tipagem**: `// TODO de tipagem: Criar interface estrita para o retorno da API de listagem`
+- **Negócio**: `// TODO de regra: Validar com Produto se a taxa adicional se aplica a clientes antigos`
+
+---
+
+## 6️⃣ Resumo das Regras
+
+| Regra | Permitido | Proibido |
+|---|---|---|
+| Tamanho de arquivo | Até 250 linhas | Acima de 250 linhas |
+| `defineComponent` | Obrigatório em todo `.vue` | Componentes sem `defineComponent` |
+| `setup()` externo | — | Proibido em qualquer forma |
+| CSS externo | `<nome>.css` vinculado ao `.vue` | CSS inline quando ultrapassa o limite |
+| Dispatch Table | Em arquivo separado | — |
+| JSDoc | Obrigatório em funções compartilhadas | Omitir em funções de uso amplo |
+| Casts `as any` | Com `biome-ignore` justificado | Sem comentário explicativo |
+
+---
+
+## 7️⃣ Checklist de Validação
+
+Antes de concluir qualquer refatoração ou adição de código:
+
+- [ ] O arquivo resultante tem menos de 250 linhas?
+- [ ] Funções compartilhadas têm `JSDoc` com `@param` e `@returns`?
+- [ ] Casts temporários têm comentário justificando?
+- [ ] TODOs estão no formato padronizado?
+- [ ] A documentação explica o **porquê**, não apenas o **o quê**?
+- [ ] `defineComponent` está presente em todo componente `.vue`?
+
+---
+
+## Referências
+
+- Script: `scripts/check-vue-linhas.sh` (validação automática de tamanho)
+- Rule: `.agent/rules/vue-limite-linhas.global.md` (política de limite de linhas)
+- Rule: `.agent/rules/typescript-sem-any.global.md` (política de tipagem)
+- Skill: `.agent/skills/documentar-decisao-tecnica/SKILL.md` (ADRs para decisões arquiteturais)