221 lines
No EOL
6.7 KiB
Markdown
221 lines
No EOL
6.7 KiB
Markdown
---
|
||
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) |