Analise Apis Novo App Operacional

🔍 Análise de APIs e Proposta de Novo App Operacional

Data: 2025-12-06
Versão: 1.0


📋 Índice

  1. Análise das APIs Existentes
  2. Proposta: C-Suite Operations
  3. Arquitetura do Novo App
  4. Casos de Uso Práticos
  5. Exemplos de Integração
  6. Roadmap de Implementação

🔍 Análise das APIs Existentes

1. 4C - Córtex Comercial (Nível Cliente)

Decision API

Capacidades:
- ✅ Decisões 1:1 com clientes
- ✅ Scoring de intenção, oferta, canal e timing
- ✅ Explicações e justificativas
- ✅ Constraints e políticas

Feature Service

Capacidades:
- ✅ Agregação de dados históricos
- ✅ Cache Redis para performance
- ✅ Features contextuais

Scoring Service

Capacidades:
- ✅ Modelos ML para cada dimensão
- ✅ Explicações (SHAP values)
- ✅ Versionamento de modelos


2. C-Suite Executive (Nível Organização)

CSuite API

Capacidades:
- ✅ Agentes executivos automatizados
- ✅ Alertas e action items
- ✅ Políticas organizacionais
- ✅ Métricas e KPIs


3. C-Suite Context (Análise Temporal)

Context API

Capacidades:
- ✅ Detecção de padrões temporais
- ✅ Identificação de tendências
- ✅ Alertas de mudanças estruturais


4. C-Suite Cashflow (Gestão Financeira)

Cashflow API

Capacidades:
- ✅ Previsão de fluxo de caixa
- ✅ Simulação de cenários
- ✅ Alertas de risco financeiro


5. C-Suite Sales Manager (Vendas B2B)

Manager API

Decision API (4C Lite)

Capacidades:
- ✅ Priorização de tasks
- ✅ Decisões simplificadas para B2B


🎯 Proposta: C-Suite Operations

Visão Geral

C-Suite Operations é um app operacional que conecta as decisões do 4C (nível cliente) com as ações executivas do C-Suite Executive (nível organização), criando uma ponte entre o operacional e o estratégico.

Problema que Resolve

Atualmente, há uma lacuna operacional:
- ✅ 4C toma decisões inteligentes (cliente certo, oferta certa, jeito certo, hora certa)
- ✅ C-Suite Executive gera alertas e action items estratégicos
- ❌ Falta: Um app que permita que operadores executem essas decisões e respondam aos alertas de forma integrada

Objetivos

  1. Execução Operacional: Permitir que operadores executem decisões do 4C
  2. Resposta a Alertas: Facilitar resposta rápida a alertas do Executive
  3. Visão Unificada: Consolidar visão operacional + estratégica
  4. Automação de Workflows: Orquestrar workflows entre sistemas
  5. Feedback Loop: Coletar feedback operacional para melhorar decisões

🏗️ Arquitetura do Novo App

Componentes Principais

┌─────────────────────────────────────────────────┐
│      C-Suite Operations                         │
│      (App Operacional)                          │
└─────────────────────────────────────────────────┘
                            ┌───────────┼───────────┐
                                  ┌───▼───┐  ┌───▼───┐  ┌───▼───┐
     4C      Exec.    Context     APIs     APIs     APIs      └───────┘  └───────┘  └───────┘

Módulos do App

1. Operations Dashboard

2. Decision Executor

3. Alert Responder

4. Workflow Orchestrator

5. Feedback Collector


💡 Casos de Uso Práticos

Caso de Uso 1: Executar Decisão do 4C com Aprovação

Cenário: O 4C gerou uma decisão para contatar cliente com oferta especial. O operador precisa revisar e aprovar antes de executar.

Fluxo:
1. Operations Dashboard mostra decisão pendente
2. Operador visualiza detalhes (cliente, oferta, canal, timing)
3. Operador pode modificar (ex: mudar canal de WhatsApp para Email)
4. Operador aprova e executa
5. Sistema chama POST /4c/decision/send para executar
6. Feedback é coletado após execução

APIs Utilizadas:

# 1. Obter decisão pendente
GET /4c/decision/decisions?status=pending&limit=50

# 2. Obter detalhes da decisão
GET /4c/decision/decisions/{decision_id}

# 3. Modificar decisão (se necessário)
PATCH /4c/decision/decisions/{decision_id}
{
  "channel": "email",  # Mudança de WhatsApp para Email
  "message": "Mensagem customizada pelo operador"
}

# 4. Executar decisão
POST /4c/decision/send
{
  "decision_id": "uuid-123",
  "approved_by": "operator-456",
  "executed_at": "2025-12-06T14:30:00Z"
}

# 5. Coletar feedback
POST /operations/feedback
{
  "decision_id": "uuid-123",
  "outcome": "success",
  "customer_response": "positive",
  "notes": "Cliente respondeu positivamente"
}

Caso de Uso 2: Responder a Alerta do CFO

Cenário: O CFO detectou que o fluxo de caixa está abaixo do esperado. O operador precisa criar um plano de ação.

Fluxo:
1. Alert Responder mostra alerta do CFO
2. Operador visualiza detalhes (métrica, valor atual, valor esperado)
3. Operador cria plano de ação (ex: acelerar cobrança, reduzir despesas)
4. Sistema integra com Cashflow API para simular impacto
5. Operador executa ações
6. Sistema monitora resultado e fecha alerta quando resolvido

APIs Utilizadas:

# 1. Obter alertas prioritários
GET /executive/alerts?priority=high&status=open

# 2. Obter detalhes do alerta
GET /executive/alerts/{alert_id}

# 3. Obter contexto financeiro
GET /cashflow/api/cashflow/timeline?days=30

# 4. Simular impacto de ação
POST /cashflow/api/cashflow/simulator/run
{
  "scenario": "accelerate_collection",
  "parameters": {
    "collection_days_reduction": 5
  }
}

# 5. Criar action item
POST /executive/action-items
{
  "alert_id": "alert-789",
  "title": "Acelerar cobrança de clientes",
  "description": "Contatar clientes com pagamento em atraso",
  "priority": "high",
  "due_date": "2025-12-10"
}

# 6. Executar ações do 4C para clientes com atraso
POST /4c/decision/decide/auto
{
  "customer_ids": [123, 456, 789],  # Clientes com atraso
  "context": {
    "goal": "collection",
    "urgency": "high"
  }
}

# 7. Fechar alerta quando resolvido
PATCH /executive/alerts/{alert_id}
{
  "status": "resolved",
  "resolution_notes": "Ações executadas com sucesso"
}

Caso de Uso 3: Workflow Automatizado de Reativação

Cenário: Cliente inativo há 90 dias. Sistema detecta oportunidade de reativação e cria workflow automático.

Fluxo:
1. Context API detecta cliente inativo (via /events ou /signals)
2. Operations cria workflow de reativação
3. Sistema chama 4C para gerar decisão de reativação
4. Operador revisa e aprova
5. Sistema executa sequência de ações:
- Envia email de reativação
- Agenda follow-up
- Monitora resposta
6. Se cliente não responder, escala para vendedor

APIs Utilizadas:

# 1. Detectar cliente inativo (via Context API)
GET /context/api/csuite/signals?type=customer_inactive&days=90

# 2. Obter features do cliente
POST /4c/feature-service/features/customer
{
  "customer_id": 123,
  "context": {"goal": "reactivation"}
}

# 3. Gerar decisão de reativação
POST /4c/decision/decide/auto
{
  "customer_id": 123,
  "context": {
    "goal": "reactivation",
    "urgency": "medium"
  }
}

# 4. Criar workflow
POST /operations/workflows
{
  "name": "Customer Reactivation",
  "customer_id": 123,
  "steps": [
    {
      "action": "send_email",
      "decision_id": "decision-123",
      "delay_hours": 0
    },
    {
      "action": "schedule_followup",
      "delay_hours": 48
    },
    {
      "action": "escalate_to_seller",
      "condition": "no_response",
      "delay_hours": 120
    }
  ]
}

# 5. Executar workflow
POST /operations/workflows/{workflow_id}/execute

# 6. Monitorar progresso
GET /operations/workflows/{workflow_id}/status

Caso de Uso 4: Priorização Inteligente de Tasks

Cenário: Operador tem 100 decisões pendentes. Sistema prioriza automaticamente baseado em impacto e urgência.

Fluxo:
1. Operations Dashboard consolida todas as decisões pendentes
2. Sistema calcula prioridade usando:
- Score de intenção do 4C
- Urgência do contexto
- Impacto financeiro (via Cashflow)
- Alertas relacionados (via Executive)
3. Operador vê lista priorizada
4. Sistema sugere ações em lote para decisões similares

APIs Utilizadas:

# 1. Obter todas as decisões pendentes
GET /4c/decision/decisions?status=pending

# 2. Para cada decisão, obter contexto
for decision in decisions:
    # Obter features do cliente
    POST /4c/feature-service/features/customer
    {
      "customer_id": decision["customer_id"]
    }

    # Obter alertas relacionados
    GET /executive/alerts?customer_id={customer_id}

    # Calcular impacto financeiro
    GET /cashflow/api/cashflow/timeline?customer_id={customer_id}

# 3. Priorizar usando algoritmo próprio
POST /operations/prioritize
{
  "decisions": [...],
  "criteria": {
    "intent_weight": 0.3,
    "urgency_weight": 0.2,
    "financial_impact_weight": 0.3,
    "alert_priority_weight": 0.2
  }
}

# 4. Retornar lista priorizada
GET /operations/dashboard/pending?sort=priority&limit=50

Caso de Uso 5: Integração com Sistema Externo (CRM)

Cenário: Decisão do 4C precisa criar oportunidade no CRM externo.

Fluxo:
1. 4C gera decisão
2. Operations recebe decisão
3. Sistema cria oportunidade no CRM via webhook/API
4. Sistema sincroniza status entre CRM e Operations
5. Feedback do CRM é usado para melhorar decisões

APIs Utilizadas:

# 1. Obter decisão aprovada
GET /4c/decision/decisions/{decision_id}

# 2. Criar oportunidade no CRM (webhook)
POST /operations/integrations/crm/create-opportunity
{
  "decision_id": "uuid-123",
  "customer_id": 123,
  "offer": {
    "sku": "BK4-2516",
    "price": 1500.00
  },
  "channel": "whatsapp",
  "timing": "2025-12-06T14:30:00Z"
}

# 3. Sincronizar status
GET /operations/integrations/crm/opportunities/{crm_opportunity_id}

# 4. Atualizar decisão com feedback do CRM
PATCH /4c/decision/decisions/{decision_id}
{
  "crm_status": "won",
  "crm_notes": "Cliente aceitou oferta"
}

# 5. Coletar feedback para melhorar modelos
POST /operations/feedback
{
  "decision_id": "uuid-123",
  "source": "crm",
  "outcome": "won",
  "revenue": 1500.00
}

🔌 Exemplos de Integração

Exemplo 1: Endpoint de Dashboard Operacional

# GET /operations/dashboard
@app.get("/operations/dashboard")
async def get_operations_dashboard(
    org_id: int,
    operator_id: Optional[int] = None
):
    """
    Dashboard consolidado com:
    - Decisões pendentes (4C)
    - Alertas prioritários (Executive)
    - Métricas operacionais
    - Tasks do dia
    """

    # 1. Obter decisões pendentes do 4C
    async with httpx.AsyncClient() as client:
        decisions_resp = await client.get(
            f"{FOURC_DECISION_API_URL}/decisions",
            params={"status": "pending", "limit": 50}
        )
        decisions = decisions_resp.json()

    # 2. Obter alertas do Executive
    alerts_resp = await client.get(
        f"{CSUITE_EXECUTIVE_API_URL}/alerts",
        params={"priority": "high", "status": "open"}
    )
    alerts = alerts_resp.json()

    # 3. Obter action items
    action_items_resp = await client.get(
        f"{CSUITE_EXECUTIVE_API_URL}/action-items",
        params={"status": "pending"}
    )
    action_items = action_items_resp.json()

    # 4. Priorizar decisões
    prioritized = prioritize_decisions(decisions, alerts, action_items)

    return {
        "pending_decisions": prioritized["decisions"],
        "high_priority_alerts": alerts,
        "action_items": action_items,
        "metrics": {
            "decisions_today": len(decisions),
            "alerts_open": len(alerts),
            "completion_rate": calculate_completion_rate()
        }
    }

Exemplo 2: Executar Decisão com Modificações

# POST /operations/decisions/{decision_id}/execute
@app.post("/operations/decisions/{decision_id}/execute")
async def execute_decision(
    decision_id: str,
    modifications: Optional[DecisionModifications] = None,
    operator_id: int
):
    """
    Executa decisão do 4C, permitindo modificações do operador
    """

    # 1. Obter decisão original
    async with httpx.AsyncClient() as client:
        decision_resp = await client.get(
            f"{FOURC_DECISION_API_URL}/decisions/{decision_id}"
        )
        decision = decision_resp.json()

    # 2. Aplicar modificações (se houver)
    if modifications:
        decision.update(modifications.dict(exclude_none=True))
        decision["modified_by"] = operator_id
        decision["modified_at"] = datetime.utcnow().isoformat()

    # 3. Executar via 4C Executor
    execute_resp = await client.post(
        f"{FOURC_DECISION_API_URL}/send",
        json={
            "decision_id": decision_id,
            "customer_id": decision["customer_id"],
            "offer": decision["offer"],
            "channel": decision["channel"],
            "message": decision.get("message"),
            "send_at": decision.get("timing", {}).get("send_at")
        }
    )

    # 4. Registrar execução
    await db.execute(
        """
        INSERT INTO operations.executions 
        (decision_id, operator_id, executed_at, status)
        VALUES (:decision_id, :operator_id, NOW(), 'executed')
        """,
        {"decision_id": decision_id, "operator_id": operator_id}
    )

    return {
        "decision_id": decision_id,
        "status": "executed",
        "execution_id": execute_resp.json().get("execution_id")
    }

Exemplo 3: Workflow de Resposta a Alerta

# POST /operations/alerts/{alert_id}/respond
@app.post("/operations/alerts/{alert_id}/respond")
async def respond_to_alert(
    alert_id: str,
    response: AlertResponse,
    operator_id: int
):
    """
    Responde a alerta do Executive criando plano de ação
    """

    # 1. Obter alerta
    async with httpx.AsyncClient() as client:
        alert_resp = await client.get(
            f"{CSUITE_EXECUTIVE_API_URL}/alerts/{alert_id}"
        )
        alert = alert_resp.json()

    # 2. Criar action items baseados na resposta
    action_items = []
    for action in response.actions:
        action_item_resp = await client.post(
            f"{CSUITE_EXECUTIVE_API_URL}/action-items",
            json={
                "alert_id": alert_id,
                "title": action["title"],
                "description": action["description"],
                "priority": action.get("priority", "medium"),
                "due_date": action.get("due_date"),
                "assigned_to": operator_id
            }
        )
        action_items.append(action_item_resp.json())

    # 3. Se alerta é financeiro, simular impacto
    if alert["type"] == "financial":
        cashflow_resp = await client.post(
            f"{CASHFLOW_API_URL}/simulator/run",
            json={
                "scenario": response.scenario_name,
                "parameters": response.parameters
            }
        )
        impact = cashflow_resp.json()

    # 4. Se necessário, gerar decisões do 4C
    if response.generate_decisions:
        for customer_id in response.customer_ids:
            decision_resp = await client.post(
                f"{FOURC_DECISION_API_URL}/decide/auto",
                json={
                    "customer_id": customer_id,
                    "context": {
                        "alert_id": alert_id,
                        "goal": response.goal
                    }
                }
            )
            # Adicionar decisão ao workflow
            await create_workflow_step(alert_id, decision_resp.json())

    # 5. Atualizar status do alerta
    await client.patch(
        f"{CSUITE_EXECUTIVE_API_URL}/alerts/{alert_id}",
        json={
            "status": "in_progress",
            "responded_by": operator_id,
            "response_notes": response.notes
        }
    )

    return {
        "alert_id": alert_id,
        "action_items_created": len(action_items),
        "decisions_generated": len(response.customer_ids) if response.generate_decisions else 0,
        "impact_simulation": impact if alert["type"] == "financial" else None
    }

🗺️ Roadmap de Implementação

Fase 1: MVP (4 semanas)

Objetivo: Dashboard básico + Execução de decisões

APIs a Implementar:
- GET /operations/dashboard - Dashboard consolidado
- GET /operations/decisions/pending - Lista de decisões pendentes
- POST /operations/decisions/{id}/execute - Executar decisão
- POST /operations/feedback - Coletar feedback


Fase 2: Alertas e Action Items (3 semanas)

Objetivo: Integração com Executive + Resposta a alertas

APIs a Implementar:
- GET /operations/alerts - Lista de alertas
- POST /operations/alerts/{id}/respond - Responder a alerta
- GET /operations/action-items - Lista de action items
- POST /operations/action-items/{id}/complete - Completar action item


Fase 3: Workflows e Automação (4 semanas)

Objetivo: Workflows personalizados + Automação

APIs a Implementar:
- POST /operations/workflows - Criar workflow
- GET /operations/workflows - Lista de workflows
- POST /operations/workflows/{id}/execute - Executar workflow
- GET /operations/workflows/{id}/status - Status do workflow


Fase 4: Integrações e Priorização (3 semanas)

Objetivo: Integrações externas + Priorização inteligente

APIs a Implementar:
- POST /operations/integrations/crm/* - Integração CRM
- POST /operations/prioritize - Priorizar decisões
- POST /operations/batch/execute - Executar em lote
- GET /operations/metrics - Métricas operacionais


📊 Estrutura de Dados

Tabelas Principais

-- Execuções de decisões
CREATE TABLE operations.executions (
    id UUID PRIMARY KEY,
    decision_id UUID NOT NULL,
    operator_id INT NOT NULL,
    executed_at TIMESTAMP NOT NULL,
    status VARCHAR(50) NOT NULL,
    modifications JSONB,
    feedback JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Workflows
CREATE TABLE operations.workflows (
    id UUID PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    steps JSONB NOT NULL,
    status VARCHAR(50) NOT NULL,
    created_by INT NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Execuções de workflows
CREATE TABLE operations.workflow_executions (
    id UUID PRIMARY KEY,
    workflow_id UUID NOT NULL,
    status VARCHAR(50) NOT NULL,
    current_step INT,
    started_at TIMESTAMP NOT NULL,
    completed_at TIMESTAMP,
    result JSONB
);

-- Feedback de operadores
CREATE TABLE operations.feedback (
    id UUID PRIMARY KEY,
    decision_id UUID,
    execution_id UUID,
    operator_id INT NOT NULL,
    rating INT,  -- 1-5
    notes TEXT,
    outcome VARCHAR(50),  -- success, failure, partial
    created_at TIMESTAMP DEFAULT NOW()
);

🎯 Benefícios Esperados

Para Operadores

Para Gestores

Para o Ecossistema


🔗 Próximos Passos

  1. Validar proposta com stakeholders
  2. Definir prioridades de implementação
  3. Criar protótipo do dashboard
  4. Testar integrações com APIs existentes
  5. Implementar MVP (Fase 1)

Última atualização: 2025-12-06

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir