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

Checklist Account State Agent

✅ Checklist: Account State Agent

Status: � Implementado e Deployado em DEV
Prioridade: 1 (FUNDAÇÃO - outros agentes dependem deste)
Estimativa: 1-2 semanas
Progresso: ✅ Completo - Deploy funcionando em DEV
Implementado em: 2026-01-25

📋 Resumo

Item Valor
Código account-state
Porta 8020
Database csuite_context
Prefixo API /v1/state
Traefik Path /account-state/

🎯 Objetivo

Declarar o estado atual de cada conta/revenda baseado em dados objetivos. É o "batimento cardíaco" do canal - todos os outros agentes consomem esse estado.

📊 Estados

NEW → ACTIVATING → ACTIVE → STALLED → AT_RISK → CHURN
Estado Trigger Ação Padrão
NEW Cadastro Iniciar Onboarding
ACTIVATING 1ª compra Acompanhar
ACTIVE 2ª compra Crescimento
STALLED Inativo > ciclo × 1.5 Reativação
AT_RISK Stalled + contatos falharam Urgente
CHURN Sem resposta prolongada Arquivar

✅ 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: Routes/API ✅

Fase 7: Policies ✅

Fase 8: Docker ✅

Fase 9: Deploy DEV ✅

Fase 10: Integração Seller Cockpit (Backend) ✅

Fase 11: Integração Seller Cockpit (Frontend) ✅

Fase 12: Documentação ✅

Fase 13: Testes

📁 Estrutura de Arquivos

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

🔌 API Endpoints

Método Endpoint Descrição
GET / Info do serviço
GET /health Health check
POST /v1/state/evaluate Avaliar e atualizar estado
GET /v1/state/account/{id} Consultar estado de uma conta
GET /v1/state/by-state/{state} Listar contas por estado
GET /v1/state/history/{id} Histórico de transições
GET /v1/state/summary Resumo (contagem por estado)
GET /v1/state/candidates/reactivation Candidatos à reativação

📊 Schema SQL Principal

CREATE TABLE IF NOT EXISTS channel_account_states (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    org_id INT NOT NULL DEFAULT 1,
    account_id VARCHAR(100) NOT NULL,
    account_type ENUM('customer', 'reseller', 'lead') NOT NULL DEFAULT 'customer',

    -- State
    current_state ENUM('NEW','ACTIVATING','ACTIVE','STALLED','AT_RISK','CHURN') NOT NULL,
    previous_state ENUM('NEW','ACTIVATING','ACTIVE','STALLED','AT_RISK','CHURN'),
    health_score INT DEFAULT 100 CHECK (health_score >= 0 AND health_score <= 100),

    -- Metrics
    last_order_at DATETIME,
    last_contact_at DATETIME,
    expected_cycle_days INT DEFAULT 30,
    days_since_order INT,
    failed_contact_attempts INT DEFAULT 0,
    total_orders INT DEFAULT 0,
    total_value DECIMAL(15,2) DEFAULT 0,

    -- Timestamps
    state_changed_at DATETIME NOT NULL,
    evaluated_at DATETIME NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

    UNIQUE KEY uk_account (org_id, account_id, account_type),
    INDEX idx_state (current_state),
    INDEX idx_health (health_score),
    INDEX idx_stalled (current_state, days_since_order)
);

🎨 Cores dos Estados (Frontend)

.state-new { background: #3498db; } /* Azul */
.state-activating { background: #f39c12; } /* Amarelo */
.state-active { background: #27ae60; } /* Verde */
.state-stalled { background: #e67e22; } /* Laranja */
.state-at-risk { background: #e74c3c; } /* Vermelho */
.state-churn { background: #95a5a6; } /* Cinza */

✅ Critérios de Conclusão

Atualizado: 2026-01-24

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir