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

Checklist Onboarding Agent

✅ Checklist: Onboarding Agent

Status: 🟢 Implementado e Deployado em DEV
Prioridade: 2 (Depende do Account State Agent) ✅
Deploy: 2026-01-25 | URL: https://csuite-dev.vallery.com.br/onboarding/

📋 Resumo

Item Valor
Código onboarding
Porta 8021
Database csuite_context
Prefixo API /v1/onboarding
Traefik Path /onboarding/
Depende de Account State Agent

🎯 Objetivo

Gerenciar os primeiros 30-60 dias de uma nova revenda. Criar plano de ativação, acompanhar progresso e garantir que a revenda "crie raiz" no canal.

Frase-guia: Onboarding não é cadastro. Onboarding é engenharia de sobrevivência da revenda.

📊 Tipos de Plano

Tipo Duração Para Quem
STRATEGIC_60 60 dias Revendas estratégicas
STANDARD_30 30 dias Revendas normais
LIMITED_14 14 dias Revendas limitadas

📊 Atividades do Plano

Atividade Dia Típico Responsável
WELCOME D+0 Sistema
TRAINING D+1-3 Vendedor
FIRST_ORDER D+7 Vendedor
FOLLOW_UP D+14 Sistema/Vendedor
CHECK_IN D+21 Vendedor
SECOND_ORDER D+30 Vendedor

✅ 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: Account State Integration ✅

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

onboarding/
├── .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
│   └── state_client.py
├── policies/
│   ├── __init__.py
│   └── onboarding.py
├── routes/
│   ├── __init__.py
│   ├── core.py
│   └── onboarding.py
└── sql/
    ├── schema.sql
    └── views.sql

🔌 API Endpoints

Método Endpoint Descrição
GET / Info do serviço
GET /health Health check
POST /v1/onboarding/create Criar plano de onboarding
GET /v1/onboarding/plan/{account_id} Consultar plano
POST /v1/onboarding/activity/{id}/complete Completar atividade
POST /v1/onboarding/activity/{id}/skip Pular atividade
GET /v1/onboarding/pending Atividades pendentes hoje
GET /v1/onboarding/at-risk Planos em risco
GET /v1/onboarding/metrics Métricas de onboarding
POST /v1/onboarding/{plan_id}/record-order Registrar pedido

📊 Schema SQL Principal

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

    -- Plan Config
    plan_type ENUM('STANDARD_30', 'STRATEGIC_60', 'LIMITED_14') NOT NULL,
    tier ENUM('STRATEGIC', 'OPPORTUNISTIC', 'TRANSACTIONAL', 'LIMITED') NOT NULL,

    -- Dates
    start_date DATE NOT NULL,
    target_end_date DATE NOT NULL,
    actual_end_date DATE,

    -- Status
    status ENUM('ACTIVE', 'COMPLETED_SUCCESS', 'COMPLETED_FAILED', 'CANCELLED') NOT NULL DEFAULT 'ACTIVE',
    onboarding_risk ENUM('LOW', 'MEDIUM', 'HIGH') DEFAULT 'MEDIUM',

    -- Goals
    first_order_target_days INT DEFAULT 7,
    first_order_actual_date DATE,
    second_order_target_days INT DEFAULT 30,
    second_order_actual_date DATE,
    activation_target_value DECIMAL(15,2),
    activation_actual_value DECIMAL(15,2) DEFAULT 0,

    -- Kit
    suggested_kit_json JSON,
    actual_first_order_json JSON,

    -- Tracking
    cadence_pattern VARCHAR(50) DEFAULT 'DAY1,DAY3,DAY7,DAY14,DAY30',
    contacts_scheduled INT DEFAULT 0,
    contacts_made INT DEFAULT 0,
    progress_pct INT DEFAULT 0,

    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_status (status),
    INDEX idx_risk (onboarding_risk),
    INDEX idx_dates (start_date, target_end_date)
);

CREATE TABLE IF NOT EXISTS channel_onboarding_activities (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    plan_id BIGINT NOT NULL,

    activity_type ENUM('WELCOME', 'TRAINING', 'FIRST_ORDER', 'FOLLOW_UP', 'CHECK_IN', 'SECOND_ORDER') NOT NULL,
    activity_order INT NOT NULL,

    scheduled_date DATE,
    completed_date DATE,
    status ENUM('PENDING', 'COMPLETED', 'SKIPPED', 'OVERDUE') DEFAULT 'PENDING',

    notes TEXT,
    completed_by VARCHAR(50),

    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,

    INDEX idx_plan (plan_id),
    INDEX idx_scheduled (scheduled_date, status),
    FOREIGN KEY (plan_id) REFERENCES channel_onboarding_plans(id)
);

🎨 UI no Seller Cockpit

Dashboard - Seção "Novas Revendas"

┌────────────────────────────────────────────────────┐
│ 🌱 Novas Revendas para Ativar (3)                  │
├────────────────────────────────────────────────────┤
│ ┌──────────────────┐  ┌──────────────────┐         │
│ │ Mercado Central  │  │ Auto Peças Norte │         │
│ │ 🔵 NEW • 5 dias  │  │ 🟡 ACTIVATING    │         │
│ │ ━━━━━━░░░░ 40%   │  │ ━━━━━━━━░░ 80%   │         │
│ │ Próximo: 1ª Cota │  │ Próximo: 2ª Compra│        │
│ └──────────────────┘  └──────────────────┘         │
└────────────────────────────────────────────────────┘

✅ Critérios de Conclusão

Atualizado: 2026-01-24

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir