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

Checklist Qualification Agent

✅ Checklist: Qualification Agent

Status: 🟢 Implementado
Prioridade: 4 (Pode ser implementado em paralelo)
Estimativa: 1-2 semanas
Implementado em: 2026-01-25

📋 Resumo

Item Valor
Código qualification
Porta 8023
Database csuite_context
Prefixo API /v1/qualification
Traefik Path /qualification/
Depende de Credit Agent (para score de crédito)

🎯 Objetivo

Gate de entrada do canal. Decide se uma nova revenda vale o investimento de cultivar, qual tier atribuir e quais limites iniciais definir.

Frase-guia: Não é um agente para dizer "sim". É um agente para dizer "vale a pena".

📊 Decisões Possíveis

Decisão Significado Próximo Passo
APPROVE_STRATEGIC Alta prioridade Onboarding prioritário
APPROVE_LIMITED Aprovado com restrições Onboarding com limites
HOLD Precisa mais análise Aguardar/observar
DO_NOT_CULTIVATE Não vale investir Sem onboarding

📊 Tiers de Revenda

Tier Descrição Tratamento
STRATEGIC Alto potencial, alinhado Prioridade máxima
OPPORTUNISTIC Bom potencial, não core Atenção moderada
TRANSACTIONAL Volume, baixa margem Autoatendimento
LIMITED Alto risco ou baixo fit Limites restritivos

📊 Scores Calculados

Score O que Mede Peso
strategic_fit_score Alinhamento com estratégia 40%
potential_value_score Valor potencial de receita 35%
operational_readiness_score Capacidade operacional 25%

✅ 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 com Fluxo de Cadastro

Fase 12: Integração Admin (Opcional)

Fase 13: Documentação

Fase 14: Testes

📁 Estrutura de Arquivos

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

🔌 API Endpoints

Método Endpoint Descrição
GET / Info do serviço
GET /health Health check
POST /v1/qualification/evaluate Avaliar nova revenda
GET /v1/qualification/{account_id} Consultar qualificação
POST /v1/qualification/{account_id}/override Override manual
GET /v1/qualification/pending-review Precisam revisão
GET /v1/qualification/by-tier/{tier} Listar por tier
GET /v1/qualification/by-decision/{decision} Listar por decisão
GET /v1/qualification/metrics Métricas

📊 Schema SQL Principal

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

    -- Input Data
    cnpj VARCHAR(20),
    company_name VARCHAR(255),
    region VARCHAR(50),
    city VARCHAR(100),
    state VARCHAR(2),
    segment VARCHAR(100),

    -- Analysis Inputs
    estimated_potential DECIMAL(15,2),
    credit_score INT,
    credit_limit_suggested DECIMAL(15,2),
    operational_capacity ENUM('LOW', 'MEDIUM', 'HIGH'),
    years_in_business INT,
    employee_count INT,
    existing_relationship BOOLEAN DEFAULT FALSE,

    -- Calculated Scores (0-100)
    strategic_fit_score INT,
    potential_value_score INT,
    operational_readiness_score INT,
    overall_score INT,

    -- Decision
    decision ENUM('APPROVE_STRATEGIC', 'APPROVE_LIMITED', 'HOLD', 'DO_NOT_CULTIVATE') NOT NULL,
    tier_assigned ENUM('STRATEGIC', 'OPPORTUNISTIC', 'TRANSACTIONAL', 'LIMITED'),
    decision_reasons JSON,
    risk_factors JSON,

    -- Initial Limits
    initial_credit_limit DECIMAL(15,2),
    initial_discount_limit DECIMAL(5,2),
    initial_payment_terms INT,  -- dias

    -- Metadata
    evaluated_by VARCHAR(50) DEFAULT 'system',
    evaluated_at DATETIME NOT NULL,
    expires_at DATETIME,  -- qualificação expira após X meses

    -- Override
    overridden BOOLEAN DEFAULT FALSE,
    overridden_by VARCHAR(50),
    overridden_at DATETIME,
    override_reason TEXT,
    original_decision ENUM('APPROVE_STRATEGIC', 'APPROVE_LIMITED', 'HOLD', 'DO_NOT_CULTIVATE'),

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

    UNIQUE KEY uk_account (org_id, account_id),
    INDEX idx_decision (decision),
    INDEX idx_tier (tier_assigned),
    INDEX idx_score (overall_score)
);

📊 Critérios de Score

Strategic Fit Score (0-100)

def calculate_strategic_fit(data):
    score = 50  # base

    # Região prioritária (+20)
    if data.region in PRIORITY_REGIONS:
        score += 20

    # Segmento alvo (+15)
    if data.segment in TARGET_SEGMENTS:
        score += 15

    # Relacionamento existente (+10)
    if data.existing_relationship:
        score += 10

    # Anos no mercado (+5 por ano, max 15)
    score += min(data.years_in_business, 3) * 5

    return min(score, 100)

Potential Value Score (0-100)

def calculate_potential_value(data):
    # Baseado no potencial estimado
    if data.estimated_potential >= 500000:
        return 100
    elif data.estimated_potential >= 200000:
        return 80
    elif data.estimated_potential >= 100000:
        return 60
    elif data.estimated_potential >= 50000:
        return 40
    else:
        return 20

Decision Matrix

overall_score >= 80 AND fit >= 70 → APPROVE_STRATEGIC + STRATEGIC
overall_score >= 60 AND fit >= 50 → APPROVE_LIMITED + OPPORTUNISTIC
overall_score >= 40 → APPROVE_LIMITED + TRANSACTIONAL
overall_score >= 20 AND no_risk_factors → HOLD
else → DO_NOT_CULTIVATE

✅ Critérios de Conclusão

🔗 Próximos Passos

  1. ~~Executar SQL~~ ✅ Concluído
  2. ~~Build e Deploy~~ ✅ Concluído
  3. ~~Testar Endpoints~~ ✅ Funcionando via curl
  4. Integrar - Conectar com fluxo de cadastro de revendas

📊 Teste de Validação (25/01/2026)

Endpoint testado: POST /v1/qualification/evaluate

Input:

{
    "account_id": "TEST-001",
    "company_name": "Distribuidora Teste LTDA",
    "state": "SP",
    "estimated_potential": 250000,
    "years_in_business": 5
}

Output:
- ✅ Decision: APPROVE_STRATEGIC
- ✅ Tier: STRATEGIC
- ✅ Overall Score: 85
- ✅ Initial Credit Limit: R$ 100.000
- ✅ Initial Discount Limit: 15%

Atualizado: 2026-01-25 18:39

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir