CHECKLIST_IMPLEMENTACAO.py

"""
═══════════════════════════════════════════════════════════════════════
CHECKLIST DE IMPLEMENTAÇÃO — PASSO A PASSO
═══════════════════════════════════════════════════════════════════════
Guia prático para aplicar a solução no seu ambiente
"""

# ═══════════════════════════════════════════════════════════════════════
# FASE 1: PREPARAÇÃO (30 minutos)
# ═══════════════════════════════════════════════════════════════════════

FASE1 = """

✓ PASSO 1.1: BACKUP DO CÓDIGO EXISTENTE
───────────────────────────────────────────────────────────────
Local: i:\\Isaac Quarenta\\Programação\\AKIRA-SOFTEDGE\\

□ Fazer backup de api.py
  cp modules/api.py modules/api.py.backup.$(date +%Y%m%d_%H%M%S)
  
□ Fazer backup de database.py
  cp modules/database.py modules/database.py.backup.$(date +%Y%m%d_%H%M%S)

□ Fazer backup de todo o diretório modules/
  ls -la modules/ > modules_backup_list.txt


✓ PASSO 1.2: VERIFICAR NOVOS ARQUIVOS
───────────────────────────────────────────────────────────────
□ context_manager_v2.py ✅ EXISTS (já criado)
□ listen_stream_processor.py ✅ EXISTS (já criado)
□ INTEGRATION_GUIDE.md ✅ EXISTS (já criado)
□ API_PATCH_DETAILED.md ✅ EXISTS (já criado)
□ test_context_isolation.py ✅ EXISTS (já criado)
□ SOLUCAO_ESCALAVEL_CONTEXT_ISOLATION.md ✅ EXISTS (já criado)
□ ARQUITETURA_VISUAL.txt ✅ EXISTS (já criado)


✓ PASSO 1.3: VERIFICAR DEPENDÊNCIAS PYTHON
───────────────────────────────────────────────────────────────
Necessários (já devem existir):
□ hashlib (built-in)
□ threading (built-in)
□ dataclasses (built-in)
□ typing (built-in)
□ datetime (built-in)
□ enum (built-in)
□ json (built-in)
□ logging (built-in)
□ re (built-in)
□ time (built-in)

Comandos para verificar:
$ python -c "import hashlib, threading, dataclasses, enum; print('✅ Tudo OK')"


✓ PASSO 1.4: REVISAR DOCUMENTAÇÃO
───────────────────────────────────────────────────────────────
□ Ler ARQUITETURA_VISUAL.txt (compreender fluxo)
□ Ler SOLUCAO_ESCALAVEL_CONTEXT_ISOLATION.md (entender problema/solução)
□ Ler INTEGRATION_GUIDE.md (entender integração)
□ Ler API_PATCH_DETAILED.md (ver modificações específicas)

"""

# ═══════════════════════════════════════════════════════════════════════
# FASE 2: TESTES (20 minutos)
# ═══════════════════════════════════════════════════════════════════════

FASE2 = """

✓ PASSO 2.1: EXECUTAR TESTES ISOLADOS
───────────────────────────────────────────────────────────────
Locação: i:\\Isaac Quarenta\\Programação\\AKIRA-SOFTEDGE\\

□ Execute os testes:
  cd AKIRA-SOFTEDGE
  python test_context_isolation.py

Esperado:
  ✅ TEST 1 PASSED
  ✅ TEST 2 PASSED
  ✅ TEST 3 PASSED
  ✅ TEST 4 PASSED
  ✅ TEST 5 PASSED
  
  🎉 TODOS OS TESTES PASSARAM!

Se falhar:
  - Verificar que context_manager_v2.py existe
  - Verificar que listen_stream_processor.py existe
  - Verificar que ambos estão em modules/
  - Verificar mensagens de erro específicas


✓ PASSO 2.2: TESTAR ISOLADAMENTE CADA MÓDULO
───────────────────────────────────────────────────────────────
□ Testar context_manager_v2:
  python -c "
from modules.context_manager_v2 import get_context_manager
cm = get_context_manager()
print('✅ ContextManagerV2 carregado')
print(f'Stats: {cm.obter_stats()}')
"

□ Testar listen_stream_processor:
  python -c "
from modules.listen_stream_processor import get_listen_processor
lp = get_listen_processor()
print('✅ ListenStreamProcessor carregado')
resultado = lp.processar_mensagem_chegando({
    'usuario': 'teste',
    'numero': '1234567890',
    'texto': '@AKIRA teste',
    'tipo_conversa': 'pv'
})
print(f'Resultado: {resultado}')
"

Se tudo OK → continuar para Fase 3


✓ PASSO 2.3: VALIDAR ISOLAÇÃO
───────────────────────────────────────────────────────────────
□ Executar test_context_isolation.py novamente
□ Verificar que TEST 4 passa (isolação Isaac vs Stefânio)
□ Se TEST 4 falhar, revisar logic em listen_stream_processor.py

"""

# ═══════════════════════════════════════════════════════════════════════
# FASE 3: INTEGRAÇÃO (45 minutos)
# ═══════════════════════════════════════════════════════════════════════

FASE3 = """

✓ PASSO 3.1: ADICIONAR IMPORTS NO api.py
───────────────────────────────────────────────────────────────
Localização: modules/api.py (linha ~10-30)

ANTES:
```python
import json
import hashlib
import logging
from skills_registry import SkillsRegistry
...
```

DEPOIS (ADICIONAR):
```python
import json
import hashlib
import logging
from skills_registry import SkillsRegistry

# ✅ NOVOS IMPORTS PARA CONTEXT V2
from modules.context_manager_v2 import (
    ContextManagerV2,
    get_context_manager,
    MessageType,
    ContextType
)
from modules.listen_stream_processor import (
    ListenStreamProcessor,
    get_listen_processor
)

# Inicializa singletons
ctx_manager = get_context_manager()
listen_processor = get_listen_processor()
...
```

Ação:
□ Abrir modules/api.py
□ Localizar seção de imports
□ Adicionar imports acima
□ SALVAR arquivo


✓ PASSO 3.2: MODIFICAR _get_user_context
───────────────────────────────────────────────────────────────
Localização: modules/api.py::_get_user_context (line ~2311)

AÇÃO: Seguir API_PATCH_DETAILED.md seção "MODIFICATION 2"

□ Abrir api.py
□ Procurar função "_get_user_context"
□ Modificar assinatura (adicionar numero, tipo_conversa, grupo_id)
□ Adicionar lógica de ContextManagerV2
□ SALVAR e TESTAR


✓ PASSO 3.3: INTEGRAR LISTEN STREAM EM akira_endpoint
───────────────────────────────────────────────────────────────
Localização: modules/api.py::akira_endpoint (line ~1224)

AÇÃO: Seguir API_PATCH_DETAILED.md seção "MODIFICATION 3"

Este é o PRINCIPAL passo:

□ Localizar onde se extrai dados (usuario, numero, texto, tipo_conversa)
□ Adicionar extração de novos campos (referenced_message_author, etc)
□ ANTES de processar LLM:
   ├─ Chamar listen_processor.processar_mensagem_chegando(evento)
   ├─ Verificar resultado_processamento['deve_processar']
   ├─ Se False: retornar jsonify com status 'contextual'
   └─ Se True: continuar normalmente
□ Usar listen_processor.obter_contexto_para_resposta() para histórico
□ SALVAR e TESTAR


✓ PASSO 3.4: ACEITAR NOVOS CAMPOS NO PAYLOAD
───────────────────────────────────────────────────────────────
Localização: modules/api.py::akira_endpoint (data extraction)

AÇÃO: Adicionar suporte aos novos campos

```python
# ✅ NOVOS CAMPOS PARA LISTEN STREAM
referenced_message_author = data.get('referenced_message_author', 
                                    data.get('quoted_author_name', ''))
referenced_message_texto = data.get('referenced_message_texto',
                                   data.get('mensagem_citada', ''))
referenced_message_id = data.get('referenced_message_id',
                                data.get('message_id_citada', ''))
```

□ Adicionar após extração de tipo_conversa/grupo_id
□ SALVAR


✓ PASSO 3.5: ATUALIZAR RESPOSTA JSON
───────────────────────────────────────────────────────────────
Localização: modules/api.py::akira_endpoint (return jsonify)

AÇÃO: Adicionar campos de debug

```python
return jsonify({
    'resposta': resposta,
    'modelo_usado': modelo,
    'confidence': confidence,
    'conversation_id': conversation_id,  # ✅ NOVO
    'tipo_message': resultado_processamento['tipo_message'],  # ✅ NOVO
    'participants': participants if tipo_conversa == 'grupo' else [],  # ✅ NOVO
    ...
})
```

□ Localizar primeiro return jsonify em akira_endpoint
□ Adicionar campos acima
□ SALVAR

"""

# ═══════════════════════════════════════════════════════════════════════
# FASE 4: ATUALIZAR discord-ts (15 minutos)
# ═══════════════════════════════════════════════════════════════════════

FASE4 = """

✓ PASSO 4.1: ATUALIZAR APIClient.ts
───────────────────────────────────────────────────────────────
Localização: discord-ts/index/modules/APIClient.ts

Adicionar ao payload enviado:

□ tipo_conversa: "pv" | "grupo"
  └─ Se é conversa privada ou grupo

□ grupo_id: string | null
  └─ ID do grupo (se aplicável)

□ referenced_message_author: string | null
  └─ Nome de quem foi mencionado/citado

□ referenced_message_texto: string | null
  └─ Texto da mensagem citada

Exemplo de novo payload:
```typescript
const payload = {
    usuario: msg.author.username,
    numero: msg.author.id,
    texto: msg.content,
    tipo_conversa: msg.channel.isDMBased() ? 'pv' : 'grupo',
    grupo_id: !msg.channel.isDMBased() ? msg.channelId : null,
    referenced_message_author: msg.reference?.author?.username || null,
    referenced_message_texto: msg.reference?.content || null,
    // ... resto dos campos
};
```

□ Modificar APIClient.ts
□ TESTAR com Discord


✓ PASSO 4.2: VERIFICAR BAILEYS (WhatsApp)
───────────────────────────────────────────────────────────────
Localização: discord-ts/index/modules/BotCore.ts ou similar

Verificar se:
□ tipo_conversa é capturado corretamente
□ grupo_id é enviado quando em grupo
□ quoted messages são extraídas

Se não estão:
□ Adicionar lógica similar ao Discord
□ TESTAR com WhatsApp

"""

# ═══════════════════════════════════════════════════════════════════════
# FASE 5: TESTES DE INTEGRAÇÃO (30 minutos)
# ═══════════════════════════════════════════════════════════════════════

FASE5 = """

✓ PASSO 5.1: TESTE BÁSICO - CONVERSA PRIVADA
───────────────────────────────────────────────────────────────
□ Enviar via POST /akira em conversa privada
  
Payload:
{
    "usuario": "IsaacTest",
    "numero": "test_123",
    "texto": "Oi AKIRA",
    "tipo_conversa": "pv"
}

Esperado:
✅ deve_processar: true
✅ tipo_message: "direct"
✅ resposta: [alguma resposta]
✅ conversation_id: [hash único]


✓ PASSO 5.2: TESTE COM MENÇÃO EM GRUPO
───────────────────────────────────────────────────────────────
□ Enviar em grupo COM @AKIRA

Payload:
{
    "usuario": "IsaacTest",
    "numero": "test_123",
    "texto": "@AKIRA qual é a capital?",
    "tipo_conversa": "grupo",
    "grupo_id": "test_group_123"
}

Esperado:
✅ deve_processar: true
✅ tipo_message: "direct"
✅ resposta: [resposta da pergunta]


✓ PASSO 5.3: TESTE SEM MENÇÃO EM GRUPO
───────────────────────────────────────────────────────────────
□ Enviar em grupo SEM @AKIRA

Payload:
{
    "usuario": "StefanioTest",
    "numero": "test_456",
    "texto": "Bacano",
    "tipo_conversa": "grupo",
    "grupo_id": "test_group_123"
}

Esperado:
✅ deve_processar: false
✅ tipo_message: "contextual"
✅ resposta: "" (vazia)
✅ status: "context_registered"


✓ PASSO 5.4: TESTE DE ISOLAÇÃO
───────────────────────────────────────────────────────────────
□ Executar sequência em grupo:

1. Isaac: "@AKIRA qual é capital de PT?" (responde)
2. Stefânio: "Bacano" (contextual, não responde)
3. Isaac: "@AKIRA e da FR?" (responde)

Validação:
□ AKIRA respondeu em 1 e 3 (ambas Isaac)
□ AKIRA não respondeu em 2
□ Logs mostram "🔍 Classificação Listen: direct/contextual"
□ conversation_id de Isaac mantém isolado


✓ PASSO 5.5: MONITORAR LOGS
───────────────────────────────────────────────────────────────
Observar no logs:
□ "📨 Mensagem chegando: ..."
□ "🔍 Classificação Listen: ..."
□ "✓ Mensagem contextual (escuta). Não respondendo." (quando aplicável)
□ "📖 Contexto obtido: X mensagens diretas"

Se tudo OK → Fase 6

"""

# ═══════════════════════════════════════════════════════════════════════
# FASE 6: VALIDAÇÃO FINAL (15 minutos)
# ═══════════════════════════════════════════════════════════════════════

FASE6 = """

✓ PASSO 6.1: VERIFICAR STATS
───────────────────────────────────────────────────────────────
□ Chamar ctx_manager.obter_stats()

Esperado:
{
    'total_contexts': N,
    'total_messages': M,
    'average_msgs_per_context': M/N,
    'cache_size': X,
    'memory_estimate_mb': Y
}

Validar:
□ memory_estimate_mb < 100MB (escalável)
□ total_contexts growing mas não explosivo


✓ PASSO 6.2: VERIFICAR ISOLAÇÃO REAL
───────────────────────────────────────────────────────────────
□ Fazer teste completo com 2+ usuários em grupo real
□ Verificar que mensagens de um não contamina outro
□ Verificar que AKIRA responde apenas quando mencionada

Exemplo:
- Isaac: "@AKIRA Python é melhor que Java?"
- Você em outro grupo: "@AKIRA Qual é o melhor framework?"
- Isaac: "@AKIRA Ok valeu"
✓ Confirm: Cada um tem seu próprio contexto isolado


✓ PASSO 6.3: PERFORMANCE
───────────────────────────────────────────────────────────────
□ Medir tempo de resposta com novo sistema
□ Comparar com antes (deve ser ~5-10% mais rápido)
□ Verificar que não há memory leaks após 1 hora de uso


✓ PASSO 6.4: ROLLBACK PLAN
───────────────────────────────────────────────────────────────
Se algo der errado:

□ Restaurar api.py do backup:
  cp modules/api.py.backup.* modules/api.py
  
□ Remover imports dos novos módulos

□ Reiniciar servidor

□ Verificar que volta ao estado anterior

□ Documentar problema encontrado para debug

"""

# ═══════════════════════════════════════════════════════════════════════
# FASE 7: DEPLOY (5 minutos)
# ═══════════════════════════════════════════════════════════════════════

FASE7 = """

✓ PASSO 7.1: DEPLOY EM STAGING
───────────────────────────────────────────────────────────────
□ Deploy do novo código em staging
□ Rodar Fase 5 (testes de integração) em staging
□ Monitorar por 2-4 horas
□ Verificar que não há errors no log


✓ PASSO 7.2: DEPLOY EM PRODUÇÃO
───────────────────────────────────────────────────────────────
□ Fazer último backup do api.py em produção
□ Deploy da solução
□ Monitorar logs continuamente
□ Se problema: executar rollback plan


✓ PASSO 7.3: MONITORAMENTO PÓS-DEPLOY
───────────────────────────────────────────────────────────────
□ Primeira hora: Verificar a cada 5 minutos
□ Primeiras 24h: Verificar a cada 30 minutos
□ Após 24h: Verificar diariamente

Métricas a monitorar:
├─ Taxa de erro (deve ser < 0.1%)
├─ Tempo médio de resposta (deve ser < 2s)
├─ Memory usage (deve ser estável)
├─ Context isolation (validar com teste manual diário)
└─ User complaints (deve ser zero sobre context mix)

"""

# ═══════════════════════════════════════════════════════════════════════
# RESUMO DE TEMPO ESTIMADO
# ═══════════════════════════════════════════════════════════════════════

RESUMO_TEMPO = """

FASE 1 (Preparação): 30 minutos
├─ Backup
├─ Verificar novos arquivos
├─ Verificar dependências
└─ Revisar documentação

FASE 2 (Testes Isolados): 20 minutos
├─ Executar test_context_isolation.py
├─ Testar cada módulo
└─ Validar isolação

FASE 3 (Integração): 45 minutos
├─ Adicionar imports
├─ Modificar _get_user_context
├─ Integrar listen stream
├─ Aceitar novos campos
└─ Atualizar resposta JSON

FASE 4 (Atualizar discord-ts): 15 minutos
├─ Atualizar APIClient.ts
└─ Verificar Baileys

FASE 5 (Testes de Integração): 30 minutos
├─ Teste PV
├─ Teste menção em grupo
├─ Teste sem menção
├─ Teste isolação
└─ Monitorar logs

FASE 6 (Validação): 15 minutos
├─ Verificar stats
├─ Verificar isolação real
├─ Performance check
└─ Rollback plan

FASE 7 (Deploy): 5 minutos
├─ Deploy staging
├─ Deploy produção
└─ Monitoramento inicial

────────────────────────────────────────────────────────────────
TOTAL: ~2 horas 50 minutos (primeira vez)
PRÓXIMAS IMPLEMENTAÇÕES: ~30 minutos (depois de entender)
────────────────────────────────────────────────────────────────

"""

# ═══════════════════════════════════════════════════════════════════════
# TROUBLESHOOTING RÁPIDO
# ═══════════════════════════════════════════════════════════════════════

TROUBLESHOOTING = """

PROBLEMA: "ModuleNotFoundError: No module named 'context_manager_v2'"
SOLUÇÃO:
  □ Verificar que context_manager_v2.py está em modules/
  □ Verificar que __init__.py existe em modules/
  □ Adicionar modules/ ao PYTHONPATH se necessário


PROBLEMA: "NameError: name 'ctx_manager' is not defined"
SOLUÇÃO:
  □ Verificar que imports estão no top do api.py
  □ Verificar que get_context_manager() foi chamado
  □ Verificar que listen_processor também foi inicializado


PROBLEMA: "AKIRA ainda está respondendo mensagens contextuais"
SOLUÇÃO:
  □ Verificar que listen_processor.processar_mensagem_chegando() é chamado
  □ Verificar que if not resultado_processamento['deve_processar']: é respeitado
  □ Verificar logs: ver se 🔍 Classificação está correto
  □ Se classifica como CONTEXTUAL mas processa, debugar lógica


PROBLEMA: "Contextos ainda estão misturando"
SOLUÇÃO:
  □ Verificar que conversation_id é único por usuário/grupo
  □ Rodar test_context_isolation.py especialmente TEST 4
  □ Debugar _gerar_conversation_id() em ContextManagerV2
  □ Verificar que ctx_manager.obter_historico_direto() está sendo usado


PROBLEMA: "Performance degradada após integração"
SOLUÇÃO:
  □ Verificar ctx_manager.obter_stats() para memory estimate
  □ Se > 100MB: implementar cleanup mais agressivo
  □ Verificar número de contextos: se > 10k, há problema
  □ Revisar TTL do cache (atualmente 300s, pode reduzir)


PROBLEMA: "Mensagens antigas não aparecem"
SOLUÇÃO:
  □ Verificar TTL: contextos com last_access > 7 dias são deletados
  □ Se precisa histórico mais longo: modificar max_age_days em cleanup
  □ Ou implementar persistência em DB (fora do escopo atual)

"""

print(FASE1)
print("\n" + "="*70 + "\n")
print(FASE2)
print("\n" + "="*70 + "\n")
print(FASE3)
print("\n" + "="*70 + "\n")
print(FASE4)
print("\n" + "="*70 + "\n")
print(FASE5)
print("\n" + "="*70 + "\n")
print(FASE6)
print("\n" + "="*70 + "\n")
print(FASE7)
print("\n" + "="*70 + "\n")
print(RESUMO_TEMPO)
print("\n" + "="*70 + "\n")
print(TROUBLESHOOTING)

__all__ = ['FASE1', 'FASE2', 'FASE3', 'FASE4', 'FASE5', 'FASE6', 'FASE7', 'RESUMO_TEMPO', 'TROUBLESHOOTING']