🏠 Início / 📚 Documentação / Guias de Uso / Checklist Reactivation Agent

Checklist Reactivation Agent

✅ Checklist: Reactivation Agent

Status: 🟢 Completo
Prioridade: 3 (Depende do Account State Agent)
Estimativa: 1-2 semanas
Progresso: 100% - ✅ Todas as fases concluídas!

📋 Resumo

Item Valor
Código reactivation
Porta 8022
Database csuite_context
Prefixo API /v1/reactivation
Traefik Path /reactivation/
Depende de Account State Agent, Pricing Agent, NBA Agent

🎯 Objetivo

Estratégias controladas para recuperar contas em estado STALLED ou AT_RISK. Decide se vale tentar, qual estratégia usar, e mede resultados.

Frase-guia: Onboarding cria raiz. Gestão faz crescer. Reactivation decide se vale salvar ou deixar morrer.

⚠️ Regra de Elegibilidade (CRÍTICA)

Reactivation NÃO se aplica a contas que nunca atingiram ACTIVE.

  • ✅ Elegível: Conta que foi ACTIVE e agora está STALLED ou AT_RISK
  • ❌ Não elegível: Conta que falhou no onboarding (nunca foi ACTIVE)

Razão: Failed onboarding ≠ stalled account. São problemas diferentes com soluções diferentes.
- Onboarding falho → revisar qualificação ou tentar novo onboarding
- Conta stalled → reativação com estratégia controlada

Isso mantém o ROI de reativação alto e evita gastar recursos em contas que nunca provaram valor.

📊 Estratégias de Reativação

Estratégia Quando Usar Custo
INCENTIVE_DISCOUNT Cliente sensível a preço Alto
PRODUCT_MIX Cliente quer novidades Médio
PERSONAL_CONTACT Relacionamento forte Baixo
SPECIAL_CONDITION Cliente VIP Alto
WAIT Melhor não agir agora Zero

📊 Fluxo de Estados

STALLED/AT_RISK → [Create Attempt] → IN_PROGRESS → WON/LOST
                                           ↓
                                    Se WON: ACTIVE
                                    Se LOST: CHURN ou nova tentativa

✅ Fases de Implementação

Fase 1: Estrutura Base

Fase 2: Schema SQL

Fase 3: Modelos Python

Fase 4: Repository (Queries)

Fase 5: Heuristics (Lógica de Decisão)

Fase 6: Integrações Externas

Fase 7: Routes/API

Fase 8: Policies

Fase 9: Docker

Fase 10: Deploy DEV

Fase 11: Integração Seller Cockpit (Backend)

Fase 12: Integração Seller Cockpit (Frontend)

Fase 13: Documentação

Fase 14: Testes

📁 Estrutura de Arquivos

reactivation/
├── .env.example
├── Dockerfile
├── README.md
├── deploy.sh
├── docker-stack.yml
├── main.py
├── requirements.txt
├── app/
│   ├── __init__.py
│   ├── database.py
│   ├── heuristics.py
│   ├── models.py
│   ├── nba_client.py
│   ├── pricing_client.py
│   ├── repository.py
│   ├── settings.py
│   └── state_client.py
├── policies/
│   ├── __init__.py
│   └── reactivation.py
├── routes/
│   ├── __init__.py
│   ├── core.py
│   └── reactivation.py
└── sql/
    ├── schema.sql
    └── views.sql

🔌 API Endpoints

Método Endpoint Descrição
GET / Info do serviço
GET /health Health check
GET /v1/reactivation/candidates Candidatos à reativação
POST /v1/reactivation/create Criar tentativa
GET /v1/reactivation/attempt/{id} Consultar tentativa
POST /v1/reactivation/attempt/{id}/start Iniciar execução
POST /v1/reactivation/attempt/{id}/outcome Registrar resultado
GET /v1/reactivation/active Tentativas em andamento
GET /v1/reactivation/history/{account_id} Histórico de tentativas
GET /v1/reactivation/metrics KPIs de reativação
GET /v1/reactivation/strategy-effectiveness Eficácia por estratégia

📊 Schema SQL Principal

CREATE TABLE IF NOT EXISTS channel_reactivation_attempts (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    org_id INT NOT NULL DEFAULT 1,
    account_id VARCHAR(100) NOT NULL,
    attempt_number INT NOT NULL DEFAULT 1,

    -- Trigger Info
    trigger_state ENUM('STALLED', 'AT_RISK') NOT NULL,
    trigger_reason VARCHAR(255),
    days_inactive INT,
    risk_value DECIMAL(15,2),  -- Valor em risco (receita anual)

    -- Strategy
    strategy ENUM('INCENTIVE_DISCOUNT', 'PRODUCT_MIX', 'PERSONAL_CONTACT', 'SPECIAL_CONDITION', 'WAIT') NOT NULL,
    strategy_params JSON,
    max_discount_allowed DECIMAL(5,2),
    suggested_products JSON,
    suggested_message TEXT,

    -- Execution
    status ENUM('PLANNED', 'IN_PROGRESS', 'WON', 'LOST', 'CANCELLED') NOT NULL DEFAULT 'PLANNED',
    assigned_to VARCHAR(50),  -- seller_id
    started_at DATETIME,
    completed_at DATETIME,

    -- Contacts
    contact_attempts INT DEFAULT 0,
    last_contact_at DATETIME,
    last_contact_channel VARCHAR(20),

    -- Outcome
    outcome_type ENUM('REACTIVATED', 'PARTIAL', 'NO_RESPONSE', 'DECLINED', 'CHURNED'),
    outcome_notes TEXT,
    next_order_at DATE,
    next_order_value DECIMAL(15,2),
    actual_discount_given DECIMAL(5,2),

    -- Cost
    attempt_cost DECIMAL(10,2) DEFAULT 0,

    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

    INDEX idx_account (account_id),
    INDEX idx_status (status),
    INDEX idx_strategy (strategy),
    INDEX idx_outcome (outcome_type)
);

🎨 UI no Seller Cockpit

Inbox - Card de Reativação

┌─────────────────────────────────────────────────────┐
│ 🔴 REATIVAÇÃO                           Urgente     │
├─────────────────────────────────────────────────────┤
│ Atacadão Norte                                      │
│ 🟠 AT_RISK • Inativo há 45 dias                     │
│ R$ 320.000/ano em risco                             │
│                                                     │
│ 📋 Estratégia sugerida: INCENTIVE_DISCOUNT          │
│ ┌─────────────────────────────────────────────────┐ │
│ │ • Desconto máximo: 5%                           │ │
│ │ • Produtos: Linha Premium                       │ │
│ │ • Canal: WhatsApp + Ligação                     │ │
│ └─────────────────────────────────────────────────┘ │
│                                                     │
│ Tentativa: 1 de 3                                   │
│                                                     │
│ [🚀 Iniciar] [💬 WhatsApp] [📞 Ligar] [❌ Descartar] │
└─────────────────────────────────────────────────────┘

📊 KPIs a Monitorar

KPI Descrição Meta
Taxa de Reativação % de contas reativadas > 40%
Margem Pós-Reativação Margem após retorno > 15%
Tempo até Nova Compra Dias até pedido < 15 dias
Custo por Tentativa Custo médio < R$ 50
Reincidência % que volta a ficar inativo < 20%

✅ Critérios de Conclusão

Atualizado: 2026-01-24

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir