117 lines
3 KiB
Text
117 lines
3 KiB
Text
---
|
|
name: diagnosticar-saude-backend
|
|
description: >
|
|
Diagnóstico sistemático de saúde do backend: rotas, queries, schemas, filas,
|
|
CRONs e integrações antes de qualquer correção.
|
|
scope: local
|
|
---
|
|
|
|
# Skill: Diagnosticar Saúde do Backend
|
|
|
|
## Objetivo
|
|
|
|
Analisar a saúde de um módulo backend para identificar problemas antes de corrigi-los. Produz relatório com causa raiz, severidade e plano de ação.
|
|
|
|
## Pré-condições
|
|
|
|
- Acesso ao pacote `*-back` do módulo
|
|
- Acesso ao pacote `*-comuns` (schemas de contrato)
|
|
|
|
## Etapas
|
|
|
|
### 1. Verificar Integridade de Schemas
|
|
|
|
```sh
|
|
# Listar todos os schemas Zod do módulo
|
|
rg "export const z" --include='*.ts' <modulo>-comuns/src/tabelas/ -l
|
|
|
|
# Verificar se schemas do comuns são usados no back
|
|
rg "from.*comuns" --include='*.ts' <modulo>-back/src/ | head -20
|
|
|
|
# Detectar schemas redefinidos no back (violação de fronteiras)
|
|
rg "z\.object\(\{" --include='*.ts' <modulo>-back/src/ -l
|
|
```
|
|
|
|
### 2. Verificar Consistência de Rotas
|
|
|
|
```sh
|
|
# Listar todas as rotas definidas
|
|
rg "router\.(get|post|put|patch|delete)" --include='*.ts' <modulo>-back/src/ -n
|
|
|
|
# Verificar validação de entrada em cada rota
|
|
rg "zod|parse|safeParse" --include='*.ts' <modulo>-back/src/rotas/ -l
|
|
|
|
# Detectar rotas sem validação Zod
|
|
# (comparar lista de rotas vs lista de validações)
|
|
```
|
|
|
|
### 3. Verificar Saúde de Queries
|
|
|
|
```sh
|
|
# Detectar queries sem tratamento de erro
|
|
rg "\.select\(|\.insert\(|\.update\(|\.delete\(" --include='*.ts' <modulo>-back/src/ -n
|
|
|
|
# Detectar possíveis N+1 (query dentro de loop)
|
|
rg "for.*await|forEach.*await|map.*await" --include='*.ts' <modulo>-back/src/ -n
|
|
|
|
# Verificar transações (queries que deveriam ser atômicas)
|
|
rg "\.transaction\(" --include='*.ts' <modulo>-back/src/ -l
|
|
```
|
|
|
|
### 4. Verificar Filas e CRONs
|
|
|
|
```sh
|
|
# Listar processadores de fila
|
|
rg "process|worker|queue" --include='*.ts' <modulo>-back/src/filas/ -l
|
|
|
|
# Verificar tratamento de falha em filas
|
|
rg "catch|onFailed|failedReason" --include='*.ts' <modulo>-back/src/filas/ -n
|
|
|
|
# Listar CRONs agendados
|
|
rg "cron|schedule|repeat" --include='*.ts' <modulo>-back/src/ -n
|
|
```
|
|
|
|
### 5. Verificar Tipagem e Build
|
|
|
|
```sh
|
|
# Checar tipos sem gerar saída
|
|
npx tsc --noEmit -p <modulo>-back/tsconfig.json 2>&1 | head -30
|
|
|
|
# Detectar uso de any
|
|
rg "as any|: any" --include='*.ts' <modulo>-back/src/ -n
|
|
```
|
|
|
|
### 6. Gerar Relatório
|
|
|
|
```markdown
|
|
# Diagnóstico Backend — [nome do módulo]
|
|
|
|
## Resumo
|
|
- **Rotas analisadas:** N
|
|
- **Schemas verificados:** N
|
|
- **Problemas encontrados:** N
|
|
|
|
## Problemas Detectados
|
|
|
|
### 🔴 Crítico
|
|
| Arquivo | Problema | Causa | Ação |
|
|
|---------|----------|-------|------|
|
|
|
|
### 🟡 Moderado
|
|
| Arquivo | Problema | Causa | Ação |
|
|
|---------|----------|-------|------|
|
|
|
|
### 🟢 Baixo
|
|
| Arquivo | Problema | Causa | Ação |
|
|
|---------|----------|-------|------|
|
|
|
|
## Plano de Correção (priorizado)
|
|
1. ...
|
|
2. ...
|
|
```
|
|
|
|
## Referências
|
|
|
|
- Rule: `global/rules/diagnostico-antes-correcao`
|
|
- Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`
|
|
- Rule: `global/rules/zod-validacao-padrao`
|