django-insights

Skill: django-insights

Propósito: Detectar problemas típicos e anti-patterns em projetos Django — diagnóstico preventivo de saúde do código.

Quando usar:

• Mensalmente (manutenção preventiva)
• Ao retomar projeto após pausa longa
• Antes de refatorações grandes
• Quando performance degradou
• Ao herdar projeto Django desconhecido

Comando:

/django-insights [--app=nome] [--focus=performance,security,architecture]

Opções:

• --app: Analisar apenas um app específico
• --focus: Focar em área específica

Método recomendado (script)

Use o script incluído para diagnóstico determinístico:

python3 django_insights.py --project-root .
python3 django_insights.py --project-root . --focus security --format json
python3 django_insights.py --project-root . --app payments --fail-on medium

Exit codes: 0 ok, 1 erro de execução, 2 policy fail (--fail-on).

---

O que a Skill Faz

1. Analisa Models — Detecta models problemáticos (muito grandes, sem índices, etc.)
2. Analisa Views — Encontra N+1 queries, lógica excessiva
3. Analisa Templates — Detecta queries em templates, complexidade
4. Verifica Migrações — Detecta migrações perigosas, conflitos
5. Inspeciona Settings — Alerta sobre configurações inseguras/ineficientes
6. Analisa Signals — Detecta uso excessivo ou problemático
7. Verifica Admin — Detecta configurações inseguras ou ineficientes

---

Problemas Detectados

🔴 Críticos (Devem ser corrigidos)

Problema	Impacto	Como Detecta
N+1 Queries em views	Performance terrível	Analisa loops com acesso a FK
Faltando on_delete em FK	Integridade referencial	AST de models.py
Migração de remoção de campo com dados	Perda de dados	Histórico de migrações
DEBUG=True em produção	Segurança	settings.py
SECRET_KEY hardcoded	Segurança	settings.py
SQL Injection via .raw()	Segurança	Uso de f-strings em raw SQL

🟡 Importantes (Recomendado corrigir)

Problema	Impacto	Como Detecta
Model > 500 linhas	Manutenibilidade	Contagem de linhas
View > 100 linhas	Manutenibilidade	Contagem de linhas
Signal sem dispatch_uid	Comportamento estranho	AST de signals.py
Query em template	Performance	Regex em templates
Índice faltante em campo buscado	Performance	Análise de queries vs índices
Uso excessivo de signals	Acoplamento oculto	Contagem de signals
Método save() sobrescrito sem super()	Bugs sutis	AST de models.py

🟢 Melhorias (Boa prática)

Problema	Impacto	Como Detecta
Faltando __str__ em model	UX no admin/admin	AST de models.py
Faltando get_absolute_url	UX, SEO	AST de models.py
Não usar select_related quando óbvio	Performance	Análise de views
Import circular	Manutenibilidade	Grafo de imports
Código morto (funções não chamadas)	Limpeza	Análise de referências

---

Exemplos de Saída

Exemplo 1: Projeto Herdado (Análise Completa)

$ /django-insights

🔍 Django Insights — Análise de Saúde do Projeto
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Visão Geral
   Django: 4.2
   Apps: 8
   Models: 42
   Views: 127
   Templates: 56
   Migrações: 156

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 PROBLEMAS CRÍTICOS (4)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔴 CRÍTICO: DEBUG=True detectado
   Arquivo: settings.py:12
   Impacto: EXPÕE INFORMAÇÕES SENSÍVEIS EM PRODUÇÃO
   
   Código:
     DEBUG = True
   
   Correção:
     DEBUG = os.getenv('DEBUG', 'False') == 'True'
   
   Ação: Configure variável de ambiente DEBUG antes do deploy

─────────────────────────────────────────────────────

🔴 CRÍTICO: N+1 Query em OrderListView
   Arquivo: orders/views.py:45
   Impacto: 1 query + N queries (uma por order)
   
   Código problemático:
     45 | for order in Order.objects.filter(status='pending'):
     46 |     print(order.customer.name)  # ← Query extra!
   
   Correção:
     Order.objects.filter(status='pending').select_related('customer')
   
   Economia estimada: ~95% de queries (100 orders = 101 → 2 queries)

─────────────────────────────────────────────────────

🔴 CRÍTICO: Migração perigosa detectada
   Arquivo: orders/migrations/0042_remove_order_total.py
   Tipo: Remoção de campo com dados existentes
   
   Análise:
     - Campo 'total' tem 15,432 registros com dados
     - Migração é irreversível sem backup
   
   Recomendação:
     1. Faça backup do banco
     2. Considere marcar como deprecated primeiro
     3. Ou migre dados para outro lugar antes de remover

─────────────────────────────────────────────────────

🔴 CRÍTICO: Signal sem dispatch_uid
   Arquivo: orders/signals.py:23
   Função: send_notification
   
   Problema: Signal pode ser registrado múltiplas vezes
             causando duplicação de notificações
   
   Correção:
     @receiver(order_completed, dispatch_uid="orders.notification")
     def send_notification(sender, **kwargs):
         ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🟡 RECOMENDAÇÕES IMPORTANTES (8)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🟡 Model muito grande: Order (680 linhas)
   Arquivo: orders/models.py
   Sugestão: Dividir em mixin ou mover lógica para services

🟡 View muito complexa: PaymentProcessView (145 linhas)
   Arquivo: payments/views.py:89
   Sugestão: Extrair lógica para PaymentService

🟡 Faltando índice em campo de busca frequente
   Model: Customer.email
   Campo buscado em: 8 lugares
   Sugestão: Adicionar db_index=True ou Index

🟡 Uso excessivo de signals (12 signals)
   App: orders
   Sugestão: Signals dificultam rastreamento. Considere:
             - Explicit calls em vez de signals
             - Ou documentar bem cada signal

🟡 Query em template detectada
   Template: orders/order_detail.html:34
   {{ order.items.filter|length }}
   Sugestão: Prepare no view: items_count = order.items.count()

🟡 Método save() sem super()
   Model: Product (products/models.py:56)
   Risco: Pode quebrar funcionalidades do Django
   
   Correção:
     def save(self, *args, **kwargs):
         # sua lógica
         super().save(*args, **kwargs)

🟡 Import circular detectado
   orders → payments → orders
   Arquivos: orders/services.py, payments/utils.py
   Sugestão: Mover código compartilhado para módulo comum

🟡 Código morto detectado
   Função: calculate_old_tax (never called)
   Arquivo: orders/utils.py:45
   Sugestão: Remover ou verificar se deveria ser usada

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🟢 BOAS PRÁTICAS (5)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🟢 Faltando __str__ em models:
   - payments/models.py: Transaction
   - reports/models.py: ReportConfig
   
   Sugestão: Adicionar para melhor UX no admin/shell

🟢 Faltando get_absolute_url:
   - Order, Customer, Product
   
   Benefício: Melhor navegação, SEO, reuso

🟢 Oportunidade de select_related:
   View: OrderDetailView
   Poderia usar select_related('customer', 'items')
   Economia: ~3 queries por request

🟢 Campo de busca sem índice:
   Order.tracking_code
   Usado em: OrderTrackingView
   Sugestão: Adicionar db_index=True

🟢 Template complexo:
   reports/dashboard.html (350 linhas)
   Sugestão: Dividir em includes

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📈 MÉTRICAS E TENDÊNCIAS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Qualidade do Código:
  🔴 Críticos: 4 (deve ser 0)
  🟡 Importantes: 8 (meta: <5)
  🟢 Melhorias: 5 (opcional)
  
Cobertura de Testes (estimada):
  Models: 60% ⚠️
  Views: 30% 🔴
  Services: 10% 🔴

Débito Técnico Estimado:
  Corrigir críticos: 2-3 dias
  Corrigir importantes: 1 semana
  Todas melhorias: 2 semanas

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 PRÓXIMAS AÇÕES RECOMENDADAS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Imediato (esta semana):
1. Corrigir DEBUG=True ANTES de qualquer deploy
2. Adicionar select_related em OrderListView
3. Revisar migração 0042 antes de aplicar

Curto prazo (próximas 2 semanas):
4. Refatorar Order model (680 → <300 linhas)
5. Quebrar PaymentProcessView em serviços
6. Adicionar índice em Customer.email

Médio prazo (mês):
7. Documentar ou remover signals excessivos
8. Aumentar cobertura de testes em views

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💾 Exportar Relatório
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

/django-insights --export=relatorio-django-2026-03-02.md

Exemplo 2: Foco em Performance

$ /django-insights --focus=performance

🔍 Django Insights — Foco: Performance

🔴 CRÍTICO: N+1 Queries Detectados (5)

1. orders/views.py:45 (OrderListView)
   Loop: for order in orders
   Acesso: order.customer.name
   Correção: .select_related('customer')
   Impacto: ~95% redução de queries

2. products/views.py:89 (ProductCatalog)
   Loop: for product in products
   Acesso: product.category.name
   Correção: .select_related('category')
   Impacto: ~90% redução de queries

3. reports/views.py:34 (SalesReport)
   Loop: for sale in sales
   Acesso: sale.items.all()  ← dentro de loop!
   Correção: .prefetch_related('items')
   Impacto: ~99% redução de queries

🟡 Oportunidades de Otimização (3)

1. Índice faltante: Customer.email
   Busca frequente, sem índice
   Impacto: Busca O(n) → O(log n)

2. Sem select_related óbvio: OrderDetailView
   Usa customer e items, não faz prefetch
   Impacto: 3 queries → 1 query

3. Query COUNT sem necessidade: DashboardView
   products.count() quando só precisa saber se >0
   Correção: Use exists()
   Impacto: Query pesada → Query leve

💡 Impacto Total Estimado:
   - Redução de queries: ~80%
   - Tempo de resposta médio: -60%
   - Capacidade de usuários simultâneos: +200%

Exemplo 3: Análise de App Específico

$ /django-

---

*Content truncated.*