ajustes na tabela de consulta
This commit is contained in:
parent
aea3da6585
commit
1446d6225b
78 changed files with 17921 additions and 17580 deletions
|
|
@ -1,221 +1,76 @@
|
|||
---
|
||||
description: Otimizar código e documentar padrões de qualidade (estrutura, limites, JSDoc e tipagem)
|
||||
type: workflow
|
||||
name: otimizar-codigos
|
||||
description: Processo de refatoração e validação de qualidade de código
|
||||
scope: global
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
|
||||
|
||||
# Workflow: Qualidade e Documentação de Código
|
||||
# Workflow: Qualidade e Otimizaçã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`.
|
||||
Aplicar as rules de qualidade do ecossistema Azteca em código existente ou novo, garantindo que todos os padrões sejam cumpridos antes de finalizar uma tarefa.
|
||||
|
||||
---
|
||||
|
||||
## 1️⃣ Limite de Linhas por Arquivo
|
||||
## Passos
|
||||
|
||||
Nenhum arquivo `*.vue`, `*.ts` ou `*.tsx` pode ultrapassar **250 linhas**.
|
||||
### 1. Verificar limite de 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>
|
||||
```bash
|
||||
sh .agent/verificar-linhas.sh
|
||||
```
|
||||
|
||||
**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
|
||||
Se houver violações, aplicar estratégias da rule `limite-linhas.global.md`:
|
||||
- Extrair subcomponentes, mover CSS, usar Dispatch Table
|
||||
- Se necessário, converter em pasta com `index.vue`
|
||||
|
||||
---
|
||||
### 2. Validar estrutura Vue
|
||||
|
||||
### `setup()` não pode ser externo
|
||||
Para cada componente `.vue` modificado, verificar conforme `estrutura-vue.global.md`:
|
||||
- `defineComponent` presente?
|
||||
- `setup()` contém lógica própria (não delegada)?
|
||||
- CSS extenso foi movido para arquivo co-localizado?
|
||||
|
||||
O `setup()` deve estar sempre dentro do componente `.vue`. Não é permitido extrair ou delegar o `setup` para nenhum arquivo externo.
|
||||
### 3. Documentar código
|
||||
|
||||
```ts
|
||||
// ❌ Proibido — setup delegado inteiramente para arquivo externo
|
||||
// useEliTabela.ts
|
||||
export function useEliTabela(props, emit) { ... }
|
||||
Para cada função compartilhada criada/modificada, aplicar `jsdoc-padrao.global.md`:
|
||||
- JSDoc com `@param` e `@returns`?
|
||||
- Casts temporários têm comentário justificando?
|
||||
- TODOs no formato padronizado?
|
||||
|
||||
// EliTabela.vue
|
||||
export default defineComponent({
|
||||
setup(props, { emit }) {
|
||||
return useEliTabela(props, emit) // setup é apenas um proxy vazio
|
||||
}
|
||||
})
|
||||
### 4. Validar tipagem
|
||||
|
||||
```bash
|
||||
npx tsc --noEmit
|
||||
```
|
||||
|
||||
```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 }
|
||||
}
|
||||
})
|
||||
```
|
||||
Zero erros = prosseguir. Se houver erros, aplicar `typescript-sem-any.global.md` — nunca resolver com `any`.
|
||||
|
||||
> 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`.
|
||||
### 5. Formatar
|
||||
|
||||
---
|
||||
|
||||
### 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" />
|
||||
```bash
|
||||
npx biome check --write .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Dispatch Table em Arquivo Separado
|
||||
## Checklist Final
|
||||
|
||||
O uso de Dispatch Table (mapa de funções) em arquivos separados é bem-vindo para eliminar blocos longos de `if/else` ou `switch`.
|
||||
- [ ] `verificar-linhas.sh` passa sem violações?
|
||||
- [ ] Componentes Vue usam `defineComponent`?
|
||||
- [ ] Funções compartilhadas têm JSDoc?
|
||||
- [ ] Casts temporários estão justificados?
|
||||
- [ ] `tsc --noEmit` zero erros?
|
||||
- [ ] `biome check` sem problemas?
|
||||
|
||||
```ts
|
||||
// handlers.ts
|
||||
export const acaoHandlers: Record<string, () => void> = {
|
||||
salvar: () => { ... },
|
||||
cancelar: () => { ... },
|
||||
excluir: () => { ... },
|
||||
}
|
||||
```
|
||||
## Rules Aplicadas
|
||||
|
||||
```ts
|
||||
// MeuComponente.vue
|
||||
import { acaoHandlers } from './handlers'
|
||||
Este workflow orquestra a verificação das seguintes rules:
|
||||
|
||||
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)
|
||||
- `.agent/rules/limite-linhas.global.md` — máximo 250 linhas
|
||||
- `.agent/rules/estrutura-vue.global.md` — defineComponent, setup, CSS, dispatch
|
||||
- `.agent/rules/jsdoc-padrao.global.md` — JSDoc, casts, TODOs
|
||||
- `.agent/rules/typescript-sem-any.global.md` — proibição de any
|
||||
- `.agent/rules/zod-validacao-padrao.global.md` — validação de entradas externas
|
||||
Loading…
Add table
Add a link
Reference in a new issue