---
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)