docs(database): add comprehensive Supabase integration guide

Complete technical documentation covering:
- Architecture overview and data flow
- Step-by-step setup instructions
- Environment configuration for backend and frontend
- Database schema documentation
- Code examples for Python and TypeScript
- Security and RLS configuration
- Performance optimization guidelines
- Troubleshooting common issues
- Deployment instructions for HuggingFace Spaces

docs/SUPABASE_INTEGRATION.md

@@ -0,0 +1,413 @@
+# Integração com Supabase
+
+Este documento descreve como configurar e usar a integração com Supabase para armazenamento centralizado de investigações.
+
+## 📋 Visão Geral
+
+O **Cidadão.AI Backend** agora suporta Supabase como banco de dados central, permitindo que:
+
+1. **Backend** armazene resultados de investigações diretamente no Supabase
+2. **Frontend** consuma os dados em tempo real via Supabase Client
+3. **Row Level Security (RLS)** garanta que usuários só vejam suas próprias investigações
+4. **Realtime Subscriptions** permitam atualizações em tempo real no frontend
+
+## 🔧 Configuração
+
+### 1. Setup no Supabase Dashboard
+
+#### 1.1 Criar Projeto
+1. Acesse [Supabase Dashboard](https://app.supabase.com)
+2. Crie um novo projeto ou use um existente
+3. Aguarde a criação do banco PostgreSQL
+
+#### 1.2 Executar Migration
+1. Vá para **SQL Editor** no dashboard
+2. Copie o conteúdo de `migrations/supabase/001_create_investigations_table.sql`
+3. Execute a migration
+4. Verifique se a tabela `investigations` foi criada
+
+#### 1.3 Obter Credenciais
+1. Vá para **Settings > API**
+2. Copie as seguintes informações:
+   - **Project URL**: `https://[project-id].supabase.co`
+   - **Anon Key**: Para acesso público (com RLS)
+   - **Service Role Key**: Para backend (bypass RLS)
+
+3. Vá para **Settings > Database > Connection string**
+4. Copie a **URI** de conexão PostgreSQL
+
+### 2. Configuração do Backend
+
+#### 2.1 Variáveis de Ambiente
+
+Adicione ao `.env`:
+
+```bash
+# Supabase PostgreSQL Connection
+SUPABASE_DB_URL=postgresql://postgres:[PASSWORD]@db.[PROJECT-ID].supabase.co:5432/postgres
+
+# Supabase API Keys (opcional - para Row Level Security)
+SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+
+# Connection Pool Settings (opcional)
+SUPABASE_MIN_CONNECTIONS=5
+SUPABASE_MAX_CONNECTIONS=20
+```
+
+**Importante**: Use `SUPABASE_SERVICE_ROLE_KEY` para que o backend possa escrever dados sem RLS.
+
+#### 2.2 HuggingFace Spaces
+
+No HuggingFace Spaces, adicione as variáveis em **Settings > Variables**:
+
+```
+SUPABASE_DB_URL: postgresql://postgres:...
+SUPABASE_SERVICE_ROLE_KEY: eyJhbGci...
+```
+
+### 3. Instalação de Dependências
+
+```bash
+# Já incluído em requirements.txt
+pip install asyncpg>=0.29.0
+```
+
+## 🚀 Uso no Backend
+
+### Exemplo 1: Criar Investigação
+
+```python
+from src.services.investigation_service_supabase import investigation_service_supabase
+
+# Criar investigação
+investigation = await investigation_service_supabase.create(
+    user_id="user-uuid-from-auth",
+    query="Contratos com valores acima de R$ 1 milhão",
+    data_source="contracts",
+    filters={"min_value": 1000000},
+    anomaly_types=["price", "vendor"],
+)
+
+print(f"Investigation ID: {investigation['id']}")
+```
+
+### Exemplo 2: Executar Investigação
+
+```python
+# Executar em background
+await investigation_service_supabase.start_investigation(
+    investigation_id=investigation['id']
+)
+
+# A investigação roda em background e atualiza o Supabase
+# O frontend pode monitorar via realtime subscription
+```
+
+### Exemplo 3: Consultar Investigações
+
+```python
+# Listar investigações do usuário
+investigations = await investigation_service_supabase.search(
+    user_id="user-uuid",
+    status="completed",
+    limit=10
+)
+
+for inv in investigations:
+    print(f"{inv['id']}: {inv['query']} - {inv['status']}")
+```
+
+## 🌐 Uso no Frontend (Next.js)
+
+### 1. Setup do Supabase Client
+
+```typescript
+// lib/supabase.ts
+import { createClient } from '@supabase/supabase-js'
+
+const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!
+const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+
+export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+```
+
+### 2. Listar Investigações do Usuário
+
+```typescript
+// pages/investigations.tsx
+import { supabase } from '@/lib/supabase'
+
+export async function getInvestigations() {
+  const { data, error } = await supabase
+    .from('investigations')
+    .select('*')
+    .order('created_at', { ascending: false })
+    .limit(10)
+
+  if (error) {
+    console.error('Error fetching investigations:', error)
+    return []
+  }
+
+  return data
+}
+```
+
+### 3. Monitorar Investigação em Tempo Real
+
+```typescript
+// components/InvestigationMonitor.tsx
+import { useEffect, useState } from 'react'
+import { supabase } from '@/lib/supabase'
+
+export function InvestigationMonitor({ investigationId }: { investigationId: string }) {
+  const [investigation, setInvestigation] = useState<any>(null)
+  const [progress, setProgress] = useState(0)
+
+  useEffect(() => {
+    // Fetch initial state
+    const fetchInvestigation = async () => {
+      const { data } = await supabase
+        .from('investigations')
+        .select('*')
+        .eq('id', investigationId)
+        .single()
+
+      setInvestigation(data)
+      setProgress(data?.progress || 0)
+    }
+
+    fetchInvestigation()
+
+    // Subscribe to real-time updates
+    const channel = supabase
+      .channel(`investigation:${investigationId}`)
+      .on(
+        'postgres_changes',
+        {
+          event: 'UPDATE',
+          schema: 'public',
+          table: 'investigations',
+          filter: `id=eq.${investigationId}`,
+        },
+        (payload) => {
+          console.log('Investigation updated:', payload.new)
+          setInvestigation(payload.new)
+          setProgress(payload.new.progress || 0)
+        }
+      )
+      .subscribe()
+
+    // Cleanup
+    return () => {
+      supabase.removeChannel(channel)
+    }
+  }, [investigationId])
+
+  return (
+    <div>
+      <h3>Investigation Status: {investigation?.status}</h3>
+      <div>Progress: {Math.round(progress * 100)}%</div>
+      <div>Phase: {investigation?.current_phase}</div>
+      <div>Anomalies Found: {investigation?.anomalies_found || 0}</div>
+
+      {investigation?.status === 'completed' && (
+        <div>
+          <h4>Results</h4>
+          <pre>{JSON.stringify(investigation.results, null, 2)}</pre>
+        </div>
+      )}
+    </div>
+  )
+}
+```
+
+### 4. Criar Nova Investigação via API
+
+```typescript
+// services/investigationService.ts
+const API_URL = process.env.NEXT_PUBLIC_API_URL
+
+export async function createInvestigation(params: {
+  query: string
+  data_source: string
+  filters?: Record<string, any>
+  anomaly_types?: string[]
+}) {
+  // Obter token JWT do usuário
+  const { data: { session } } = await supabase.auth.getSession()
+
+  const response = await fetch(`${API_URL}/api/v1/investigations/start`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${session?.access_token}`,
+    },
+    body: JSON.stringify(params),
+  })
+
+  if (!response.ok) {
+    throw new Error('Failed to create investigation')
+  }
+
+  return await response.json()
+}
+```
+
+## 📊 Schema da Tabela
+
+### Campos Principais
+
+| Campo | Tipo | Descrição |
+|-------|------|-----------|
+| `id` | UUID | ID único da investigação |
+| `user_id` | UUID | ID do usuário (auth.users) |
+| `query` | TEXT | Query da investigação |
+| `data_source` | VARCHAR | Fonte de dados (contracts, expenses, etc) |
+| `status` | VARCHAR | Status: pending, processing, completed, failed, cancelled |
+| `progress` | FLOAT | Progresso de 0.0 a 1.0 |
+| `current_phase` | VARCHAR | Fase atual (data_retrieval, analysis, etc) |
+| `results` | JSONB | Array de anomalias detectadas |
+| `summary` | TEXT | Resumo da investigação |
+| `confidence_score` | FLOAT | Confiança geral (0.0 a 1.0) |
+| `anomalies_found` | INTEGER | Total de anomalias |
+| `total_records_analyzed` | INTEGER | Total de registros analisados |
+
+### Exemplo de Result (JSONB)
+
+```json
+{
+  "anomaly_id": "uuid",
+  "type": "price",
+  "severity": "high",
+  "confidence": 0.92,
+  "description": "Preço 45% acima da média",
+  "explanation": "Análise de 1.234 contratos similares...",
+  "affected_records": [
+    {
+      "contract_id": "123",
+      "value": 1500000,
+      "expected_value": 1034000
+    }
+  ],
+  "suggested_actions": [
+    "Solicitar justificativa do preço",
+    "Comparar com licitações similares"
+  ],
+  "metadata": {
+    "analysis_method": "fft_spectral",
+    "comparison_count": 1234
+  }
+}
+```
+
+## 🔒 Segurança (Row Level Security)
+
+### Políticas Ativas
+
+1. **SELECT**: Usuários só veem suas próprias investigações
+2. **INSERT**: Usuários só criam investigações para si mesmos
+3. **UPDATE**: Usuários só atualizam suas próprias investigações
+4. **DELETE**: Usuários só deletam suas próprias investigações
+5. **Service Role**: Backend com `service_role_key` pode gerenciar tudo
+
+### Testando RLS
+
+```sql
+-- Como usuário autenticado
+SELECT * FROM investigations; -- Vê apenas suas investigações
+
+-- Como service_role (backend)
+-- Vê todas as investigações
+```
+
+## 🐛 Troubleshooting
+
+### Erro: "Connection refused"
+
+Verifique se `SUPABASE_DB_URL` está correto:
+```bash
+psql "postgresql://postgres:[PASSWORD]@db.[PROJECT-ID].supabase.co:5432/postgres"
+```
+
+### Erro: "Permission denied"
+
+- Verifique se RLS está habilitado
+- Use `SUPABASE_SERVICE_ROLE_KEY` no backend
+- Verifique se `user_id` corresponde ao `auth.uid()`
+
+### Investigação não atualiza no frontend
+
+- Verifique se Realtime está habilitado no Supabase
+- Vá para **Database > Replication** e habilite `investigations`
+- Verifique se o frontend tem a subscription correta
+
+## 📈 Monitoramento
+
+### Ver estatísticas do usuário
+
+```sql
+SELECT * FROM get_investigation_stats('user-uuid');
+```
+
+### Ver investigações ativas
+
+```sql
+SELECT id, query, status, progress, current_phase
+FROM investigations
+WHERE status IN ('pending', 'processing')
+ORDER BY created_at DESC;
+```
+
+### Performance indexes
+
+A migration cria 7 indexes otimizados:
+- `user_id` (B-tree)
+- `status` (B-tree)
+- `created_at` (B-tree desc)
+- `user_id, status` (composite)
+- `filters` (GIN - JSONB)
+- `results` (GIN - JSONB)
+
+## 🚢 Deploy
+
+### HuggingFace Spaces
+
+```bash
+# Adicione as variáveis no dashboard
+SUPABASE_DB_URL=postgresql://...
+SUPABASE_SERVICE_ROLE_KEY=eyJhbGci...
+
+# O app.py vai usar automaticamente
+```
+
+### Docker
+
+```yaml
+# docker-compose.yml
+services:
+  backend:
+    environment:
+      - SUPABASE_DB_URL=${SUPABASE_DB_URL}
+      - SUPABASE_SERVICE_ROLE_KEY=${SUPABASE_SERVICE_ROLE_KEY}
+```
+
+## 📚 Recursos
+
+- [Supabase Documentation](https://supabase.com/docs)
+- [Supabase Realtime](https://supabase.com/docs/guides/realtime)
+- [Row Level Security](https://supabase.com/docs/guides/auth/row-level-security)
+- [asyncpg Documentation](https://magicstack.github.io/asyncpg/)
+
+## ✅ Checklist de Implementação
+
+- [x] Criar serviço `SupabaseService`
+- [x] Criar `InvestigationServiceSupabase`
+- [x] Criar migration SQL
+- [x] Documentar configuração
+- [ ] Executar migration no Supabase
+- [ ] Configurar variáveis de ambiente
+- [ ] Testar criação de investigação
+- [ ] Testar realtime no frontend
+- [ ] Deploy no HuggingFace Spaces