# Verificar se gemini_audit.py existe
[ -f gemini_audit.py ] && echo "✅ gemini_audit.py disponível" || echo "❌ gemini_audit.py NÃO encontrado - usar ferramentas alternativas (Read, Grep)"

# Uso básico (apenas se gemini_audit.py existir)
python gemini_audit.py "Pergunta sobre o código" --dir <pasta> --model gemini-2.5-flash

# Exemplos
python gemini_audit.py "Como funciona o cálculo do saldo financeiro?" \
  --dir ./public/js/fluxo-financeiro

python gemini_audit.py "Explique as regras do Mata-Mata" \
  --dir ./controllers --model gemini-2.5-flash

# Template de pergunta
python gemini_audit.py \
  "Leia estes arquivos e gere uma explicação didática e completa sobre como funciona [TÓPICO], 
   citando valores, fórmulas e regras específicas. 
   Organize em: Resumo, Como Funciona, Regras Principais, Exceções, Exemplo Prático." \
  --dir [PASTA_ALVO] \
  --model gemini-2.5-flash

## [Nome do Módulo/Feature]

### 📋 Resumo
[1-2 frases explicando o propósito]

### 🔧 Como Funciona
[Explicação passo a passo, com código se necessário]

### ⚙️ Regras Principais
- **Regra 1:** [descrição com valor/fórmula]
- **Regra 2:** [descrição com valor/fórmula]
- **Regra 3:** [descrição com valor/fórmula]

### ⚠️ Exceções e Casos Especiais
[Se houver casos especiais ou condições]

### 💡 Exemplo Prático
[Cenário real com números]

### 📂 Arquivos Relacionados
- `arquivo1.js` - Descrição
- `arquivo2.js` - Descrição

### 🔗 Ver Também
- [Link para docs relacionadas]

python gemini_audit.py \
  "Explique a regra do Capitão: como funciona o multiplicador, quando é aplicado, dê exemplos." \
  --dir ./config/rules \
  --model gemini-2.5-flash

## Capitão - Multiplicador de Pontos

### 📋 Resumo
O Capitão é um recurso que permite ao participante escolher um jogador de seu time para ter a pontuação multiplicada por 2x na rodada.

### 🔧 Como Funciona
1. Participante escolhe 1 jogador antes do fechamento da rodada
2. A pontuação desse jogador é multiplicada por 2
3. O multiplicador é aplicado ANTES do cálculo da pontuação total

### ⚙️ Regras Principais
- **Multiplicador:** 2x (dobra os pontos)
- **Limite:** 1 capitão por rodada
- **Deadline:** Deve ser escolhido antes do fechamento do mercado
- **Pontuação negativa:** Se o capitão pontuar negativo, a penalidade também é dobrada

### 💡 Exemplo Prático
**Cenário:**
- Time do João tem Gabigol como atacante
- Gabigol fez 2 gols e teve pontuação de 12.5
- João escolheu Gabigol como Capitão

**Cálculo:**
- Pontuação base: 12.5
- Com multiplicador: 12.5 × 2 = **25.0**
- Ganho extra: +12.5 pontos

### 📂 Arquivos Relacionados
- `config/rules/ranking_rodada.json` - Configuração do multiplicador
- `controllers/rankingRodadaCache.js` - Aplicação do multiplicador

python gemini_audit.py \
  "Explique as zonas financeiras (G-Zones e Z-Zones): valores, faixas de posição." \
  --dir ./config/rules \
  --model gemini-2.5-flash

## Zonas Financeiras - SuperCartola (32 Times)

### 📋 Resumo
Sistema de premiação e punição baseado na posição final da rodada. Divide-se em G-Zones (premiação) e Z-Zones (punição).

### 🔧 Como Funciona
Após cada rodada, os participantes são classificados de 1º a 32º. A posição determina se ganha prêmio ou sofre punição.

### ⚙️ G-Zones (Premiação)
| Zona | Posição | Valor | Descrição |
|------|---------|-------|-----------|
| G1 | 1º | +R$ 100,00 | Campeão/Mito |
| G2 | 2º | +R$ 60,00 | Vice |
| G3 | 3º | +R$ 40,00 | 3º Lugar |
| G4 | 4º-6º | +R$ 20,00 | Top 6 |
| G5 | 7º-9º | +R$ 10,00 | Top 9 |
| G6 | 10º-11º | +R$ 5,00 | Top 11 |

### ⚙️ Zona Neutra
| Zona | Posição | Valor |
|------|---------|-------|
| NEUTRO | 12º-21º | R$ 0,00 |

### ⚙️ Z-Zones (Punição)
| Zona | Posição | Valor | Descrição |
|------|---------|-------|-----------|
| Z1 | 22º | -R$ 5,00 | Z1 |
| Z2 | 23º-24º | -R$ 10,00 | Z2-Z3 |
| Z3 | 25º-27º | -R$ 20,00 | Z4-Z6 |
| Z4 | 28º-30º | -R$ 40,00 | Z7-Z9 |
| Z5 | 31º | -R$ 60,00 | Penúltimo |
| Z6 | 32º | -R$ 100,00 | Lanterna/Mico |

### 💡 Exemplo Prático
**João terminou em 3º lugar na rodada 10:**
- Posição: 3º
- Zona: G3
- Ganho: +R$ 40,00
- Impacto no saldo: Saldo anterior + R$ 40,00

### 📂 Arquivos Relacionados
- `config/rules/zonas_financeiras.json` - Definição das zonas
- `controllers/rankingRodadaCache.js` - Aplicação das premiações

python gemini_audit.py \
  "Explique o cálculo do saldo financeiro: quais módulos contribuem, fórmulas, breakdown." \
  --dir ./public/js/fluxo-financeiro \
  --model gemini-2.5-flash

## Cálculo do Saldo Financeiro

### 📋 Resumo
O saldo financeiro de um participante é a soma de todos os ganhos e perdas da temporada, incluindo rodadas, disputas e acertos financeiros.

### 🔧 Fórmula Completa
```javascript
saldoFinal = saldoRodadas + saldoDisputas + saldoAcertos

onde:
- saldoRodadas = soma de ganhos/perdas de todas as rodadas
- saldoDisputas = premiações de PC, MM, Top10, etc
- saldoAcertos = pagamentos - recebimentos

saldoAcertos = totalPagamentos - totalRecebimentos

// Exemplo:
pagamento: +R$ 200,00  // Participante PAGOU
recebimento: -R$ 50,00 // Participante RECEBEU
saldoAcertos = 200 - 50 = +R$ 150,00

Rodadas:
- Rodada 1: -R$ 20,00 (Mico)
- Rodada 2: +R$ 100,00 (G1)
- ... (rodadas 3-38)
- Total rodadas: +R$ 450,00

Disputas:
- Pontos Corridos: +R$ 300,00 (3º lugar)
- Mata-Mata: +R$ 0,00 (eliminado nas quartas)
- Total disputas: +R$ 300,00

Acertos:
- Pagamento inscrição: +R$ 200,00
- Total acertos: +R$ 200,00

SALDO FINAL = 450 + 300 + 200 = +R$ 950,00

---

## 5. 🎯 Casos de Uso Comuns

### 5.1 Documentar Módulo Completo

```bash
# 1. Identificar arquivos
ls -la public/js/fluxo-financeiro/

# 2. Gerar documentação
python gemini_audit.py \
  "Documente completamente o módulo Fluxo Financeiro: arquitetura, funções, fluxo de dados." \
  --dir ./public/js/fluxo-financeiro \
  --model gemini-2.5-flash > docs/fluxo_financeiro.md

python gemini_audit.py \
  "Como funciona o desempate no Pontos Corridos?" \
  --dir ./controllers \
  --model gemini-2.5-flash

# Quando há bug ou comportamento inesperado
python gemini_audit.py \
  "Por que o saldo financeiro está dando valor diferente do esperado? 
   Analise a lógica de cálculo e possíveis fontes de erro." \
  --dir ./public/js/fluxo-financeiro \
  --model gemini-2.5-flash

docs/
├── README.md                    # Visão geral do sistema
├── architecture/
│   ├── overview.md              # Arquitetura geral
│   ├── multi-tenant.md          # Sistema multi-tenant
│   └── cache-strategy.md        # Estratégia de cache
├── modules/
│   ├── fluxo-financeiro.md      # Fluxo financeiro
│   ├── pontos-corridos.md       # Pontos corridos
│   ├── mata-mata.md             # Mata-mata
│   └── ranking.md               # Sistema de ranking
├── business-rules/
│   ├── zonas-financeiras.md     # G-Zones e Z-Zones
│   ├── acertos-financeiros.md   # Pagamentos/recebimentos
│   └── disputas.md              # Todas as disputas
└── api/
    ├── endpoints.md             # Documentação de APIs
    └── cartola-integration.md   # Integração Cartola FC

#!/bin/bash
# scripts/generate_doc.sh

module=$1
output="docs/modules/${module}.md"

echo "Gerando documentação para $module..."

python gemini_audit.py \
  "Documente o módulo $module completamente: propósito, arquitetura, 
   funções principais, regras de negócio, exemplos de uso." \
  --dir ./controllers ./public/js \
  --model gemini-2.5-flash > "$output"

echo "✅ Documentação salva em $output"

# Verificar se docs estão atualizadas
python gemini_audit.py \
  "Compare o código atual com a documentação em docs/modules/fluxo-financeiro.md. 
   Liste diferenças e o que precisa ser atualizado." \
  --dir ./public/js/fluxo-financeiro \
  --model gemini-2.5-flash

# Documentar mudanças entre versões
python gemini_audit.py \
  "Liste todas as mudanças no módulo desde a última versão, 
   comparando com o backup em backups/v2.0/" \
  --dir ./controllers \
  --model gemini-2.5-flash > CHANGELOG.md

1. Código mudou? 
   ↓
2. Rodar gemini_audit.py
   ↓
3. Atualizar docs/
   ↓
4. Commit: "docs: update [module] documentation"

# === EXPLICAÇÕES RÁPIDAS ===
# Regras de Negócio
python gemini_audit.py "Como funciona [feature]?" --dir ./config/rules

# Módulo Completo
python gemini_audit.py "Explique módulo [nome]" --dir ./controllers

# Troubleshooting
python gemini_audit.py "Por que [bug]?" --dir ./[pasta-relevante]

# === DOCUMENTAÇÃO ===
# Gerar doc completa
python gemini_audit.py "Documente [módulo]" --dir ./[pasta] > docs/[módulo].md

# Atualizar doc existente
python gemini_audit.py "Compare código com docs/[doc].md" --dir ./[pasta]

# === ANÁLISE ===
# Listar mudanças
python gemini_audit.py "Liste mudanças desde [data]" --dir ./[pasta]

# Encontrar dependências
python gemini_audit.py "Quais arquivos usam [função]?" --dir ./

# Criar script de manutenção
#!/bin/bash
# scripts/maintain_docs.sh

echo "🔍 Verificando documentação desatualizada..."

# Listar módulos modificados recentemente
git diff --name-only HEAD~10 | grep -E "controllers|public/js" | \
while read file; do
  module=$(basename $(dirname $file))
  doc="docs/modules/${module}.md"
  
  if [ -f "$doc" ]; then
    echo "⚠️  $module foi modificado, doc pode estar desatualizada"
  fi
done

echo "✅ Verificação concluída"