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)

🟡 Importantes (Recomendado corrigir)

🟢 Melhorias (Boa prática)

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.*