docs(investigations): add comprehensive 24/7 auto-investigation documentation

Complete guide for deploying and operating the autonomous investigation system.

Includes:
- Architecture overview and data flow
- Activation instructions (local, production, Docker)
- Configuration options and tuning
- Monitoring and troubleshooting
- Security considerations
- KPIs and metrics tracking

Author: Anderson Henrique da Silva
Date: 2025-10-07 18:11:37

docs/24-7-AUTO-INVESTIGATION-SYSTEM.md

@@ -0,0 +1,354 @@
+# 🤖 Sistema de Investigação Autônoma 24/7
+
+**Autor**: Anderson Henrique da Silva
+**Data**: 2025-10-07 18:11:37
+**Status**: ✅ Implementado e Pronto para Produção
+
+## 📋 Visão Geral
+
+Sistema completamente autônomo que monitora contratos governamentais 24 horas por dia, 7 dias por semana, detectando automaticamente padrões suspeitos e criando investigações forenses detalhadas SEM intervenção humana.
+
+## 🎯 O Que o Sistema Faz
+
+### 1. Monitoramento Contínuo de Contratos Novos
+- **Frequência**: A cada 6 horas
+- **Lookback**: Últimas 6 horas de contratos
+- **Fonte**: Portal da Transparência API
+- **Ação**: Cria investigações automáticas para contratos suspeitos
+
+### 2. Monitoramento Prioritário de Órgãos Críticos
+- **Frequência**: A cada 4 horas
+- **Fila**: High Priority
+- **Órgãos**: Lista configurável de órgãos com histórico de irregularidades
+- **Ação**: Análise mais frequente e detalhada
+
+### 3. Reanálise de Contratos Históricos
+- **Frequência**: Semanal (domingos 3h)
+- **Lookback**: 6 meses
+- **Propósito**: Encontrar anomalias previamente perdidas com modelos atualizados
+- **Processamento**: Lotes de 100 contratos por vez
+
+### 4. Health Check do Sistema
+- **Frequência**: A cada hora
+- **Verifica**: API Transparência, Investigation Service, Agent Pool
+- **Alertas**: Logs de componentes com problemas
+
+## 🔍 Critérios de Pré-Triagem (Suspicion Score)
+
+O sistema calcula automaticamente um "suspicion score" baseado em:
+
+| Critério | Pontos | Descrição |
+|----------|--------|-----------|
+| **Valor Alto** | +2 | Contratos acima de R$ 100.000 |
+| **Processo Emergencial** | +3 | Dispensa ou inexigibilidade de licitação |
+| **Licitante Único** | +2 | Apenas 1 proponente no processo |
+| **Fornecedor em Watchlist** | +3 | Fornecedor com histórico de problemas |
+| **Prazo Curto de Licitação** | +1 | Tempo insuficiente para competição |
+
+**Threshold para Investigação**: Score ≥ 3 pontos
+
+## 🏗️ Arquitetura
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   Celery Beat Scheduler                      │
+│         (Agenda e dispara tarefas periodicamente)            │
+└───────────────┬─────────────────────────────────────────────┘
+                │
+    ┌───────────┼───────────┬────────────┬───────────────┐
+    │           │           │            │               │
+    ▼           ▼           ▼            ▼               ▼
+ [6h Task]  [4h Task]  [Weekly]    [Hourly]      [On-Demand]
+New Contracts Priority Historical  Health     User-Triggered
+Monitor      Orgs     Reanalysis   Check      Investigations
+    │           │           │            │               │
+    └───────────┴───────────┴────────────┴───────────────┘
+                            │
+                            ▼
+            ┌───────────────────────────────┐
+            │ Auto Investigation Service     │
+            │ - Fetch contracts from API     │
+            │ - Pre-screen for suspicion     │
+            │ - Trigger full investigation   │
+            └───────────────┬───────────────┘
+                            │
+                            ▼
+            ┌───────────────────────────────┐
+            │ Zumbi (InvestigatorAgent)     │
+            │ - Full anomaly detection       │
+            │ - Forensic enrichment          │
+            │ - Evidence collection          │
+            └───────────────┬───────────────┘
+                            │
+                            ▼
+            ┌───────────────────────────────┐
+            │ Supabase (Database)            │
+            │ - Investigation records        │
+            │ - Forensic results             │
+            │ - ML feedback data             │
+            └───────────────────────────────┘
+```
+
+## 🚀 Como Ativar
+
+### Pré-requisitos
+
+1. **Redis** instalado e rodando:
+```bash
+# Ubuntu/Debian
+sudo apt-get install redis-server
+sudo systemctl start redis
+
+# macOS
+brew install redis
+brew services start redis
+
+# Docker
+docker run -d -p 6379:6379 redis:7-alpine
+```
+
+2. **Variáveis de ambiente configuradas**:
+```bash
+# .env
+REDIS_URL=redis://localhost:6379/0
+TRANSPARENCY_API_KEY=sua-chave-aqui  # Opcional mas recomendado
+SUPABASE_URL=sua-url-supabase
+SUPABASE_SERVICE_ROLE_KEY=sua-chave-supabase
+GROQ_API_KEY=sua-chave-groq  # Para LLM dos agentes
+```
+
+### Iniciar o Sistema
+
+#### Opção 1: Desenvolvimento Local
+
+```bash
+# Terminal 1: Celery Worker
+celery -A src.infrastructure.queue.celery_app worker \
+  --loglevel=info \
+  --queues=critical,high,default,low,background \
+  --concurrency=4
+
+# Terminal 2: Celery Beat (Scheduler)
+celery -A src.infrastructure.queue.celery_app beat \
+  --loglevel=info
+```
+
+#### Opção 2: Produção (Supervisor)
+
+Criar `/etc/supervisor/conf.d/cidadao-ai-celery.conf`:
+
+```ini
+[program:cidadao-ai-worker]
+command=/path/to/venv/bin/celery -A src.infrastructure.queue.celery_app worker --loglevel=info --queues=critical,high,default,low,background --concurrency=8
+directory=/path/to/cidadao.ai-backend
+user=www-data
+autostart=true
+autorestart=true
+stopasgroup=true
+killasgroup=true
+redirect_stderr=true
+stdout_logfile=/var/log/celery/worker.log
+
+[program:cidadao-ai-beat]
+command=/path/to/venv/bin/celery -A src.infrastructure.queue.celery_app beat --loglevel=info
+directory=/path/to/cidadao.ai-backend
+user=www-data
+autostart=true
+autorestart=true
+redirect_stderr=true
+stdout_logfile=/var/log/celery/beat.log
+```
+
+Aplicar configuração:
+```bash
+sudo supervisorctl reread
+sudo supervisorctl update
+sudo supervisorctl start cidadao-ai-worker
+sudo supervisorctl start cidadao-ai-beat
+```
+
+#### Opção 3: Docker Compose
+
+Adicionar ao `docker-compose.yml`:
+
+```yaml
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+
+  celery-worker:
+    build: .
+    command: celery -A src.infrastructure.queue.celery_app worker --loglevel=info --queues=critical,high,default,low,background
+    depends_on:
+      - redis
+    env_file:
+      - .env
+    volumes:
+      - .:/app
+
+  celery-beat:
+    build: .
+    command: celery -A src.infrastructure.queue.celery_app beat --loglevel=info
+    depends_on:
+      - redis
+      - celery-worker
+    env_file:
+      - .env
+    volumes:
+      - .:/app
+
+volumes:
+  redis_data:
+```
+
+Iniciar:
+```bash
+docker-compose up -d redis celery-worker celery-beat
+```
+
+## 📊 Monitoramento
+
+### Ver Tarefas Agendadas
+
+```bash
+celery -A src.infrastructure.queue.celery_app inspect scheduled
+```
+
+### Ver Tarefas Ativas
+
+```bash
+celery -A src.infrastructure.queue.celery_app inspect active
+```
+
+### Ver Estatísticas
+
+```bash
+celery -A src.infrastructure.queue.celery_app inspect stats
+```
+
+### Flower (Web UI)
+
+```bash
+pip install flower
+celery -A src.infrastructure.queue.celery_app flower
+# Acesse: http://localhost:5555
+```
+
+## 🎛️ Configuração Avançada
+
+### Ajustar Frequência de Monitoramento
+
+Edite `src/infrastructure/queue/celery_app.py`:
+
+```python
+celery_app.conf.beat_schedule = {
+    "auto-monitor-new-contracts-6h": {
+        "schedule": timedelta(hours=3),  # Mude de 6h para 3h
+        "args": (3,),  # Lookback de 3h
+    },
+}
+```
+
+### Adicionar Órgãos Prioritários
+
+Edite `src/infrastructure/queue/tasks/auto_investigation_tasks.py`:
+
+```python
+priority_orgs = [
+    "26101",  # Ministério da Saúde
+    "20101",  # Ministério da Educação
+    "53000",  # Prefeitura de São Paulo
+    # Adicione mais códigos aqui
+]
+```
+
+### Ajustar Thresholds de Detecção
+
+Edite `src/services/auto_investigation_service.py`:
+
+```python
+self.value_threshold = 50000.0  # Reduzir para R$ 50k
+self.daily_contract_limit = 1000  # Aumentar limite diário
+```
+
+## 📈 Métricas e KPIs
+
+O sistema automaticamente coleta:
+
+- **Contratos Analisados**: Total de contratos processados
+- **Taxa de Suspeição**: % de contratos que passam pré-triagem
+- **Investigações Criadas**: Quantidade de investigações automáticas
+- **Anomalias Detectadas**: Total de irregularidades encontradas
+- **Tempo de Processamento**: Duração média das investigações
+- **Taxa de Sucesso**: % de investigações completadas com sucesso
+
+Acesse via Flower ou logs estruturados.
+
+## 🛠️ Troubleshooting
+
+### Problema: Tasks não executam
+
+**Causa**: Redis não está rodando ou configuração incorreta
+
+**Solução**:
+```bash
+# Verificar Redis
+redis-cli ping
+# Deve retornar: PONG
+
+# Verificar configuração
+echo $REDIS_URL
+# Deve retornar: redis://localhost:6379/0
+```
+
+### Problema: Muitos erros de API
+
+**Causa**: Rate limit do Portal da Transparência
+
+**Solução**: Ajustar delays no código ou adicionar `TRANSPARENCY_API_KEY`
+
+### Problema: Investigações não aparecem no frontend
+
+**Causa**: Supabase não configurado ou credenciais inválidas
+
+**Solução**:
+```bash
+# Verificar variáveis
+echo $SUPABASE_URL
+echo $SUPABASE_SERVICE_ROLE_KEY
+
+# Testar conexão
+python -c "from src.services.supabase_service_rest import get_supabase_service_rest; import asyncio; print(asyncio.run(get_supabase_service_rest()))"
+```
+
+## 🔐 Segurança
+
+- ✅ Tasks rodando com user `system_auto_monitor`
+- ✅ Rate limiting configurado para APIs externas
+- ✅ Logs estruturados com rastreabilidade completa
+- ✅ Retry automático com backoff exponencial
+- ✅ Timeout configurado para evitar tasks travadas
+
+## 📝 Próximos Passos
+
+1. **Aprendizado Automático**: Treinar modelos ML com dados coletados
+2. **Notificações**: Alertas quando anomalias críticas são encontradas
+3. **Dashboard Analytics**: Visualização de descobertas em tempo real
+4. **Watchlist Dinâmica**: Atualização automática de fornecedores suspeitos
+5. **Cross-referência**: Integração com outros sistemas de fiscalização
+
+## 📚 Referências
+
+- [Documentação Celery](https://docs.celeryq.dev/)
+- [Portal da Transparência API](https://api.portaldatransparencia.gov.br/swagger-ui.html)
+- [Supabase Python Client](https://supabase.com/docs/reference/python)
+
+---
+
+**Status**: ✅ Sistema operacional e pronto para produção
+**Última atualização**: 2025-10-07 18:11:37 (America/Sao_Paulo)
+**Autor**: Anderson Henrique da Silva