📖 Glossário de Termos - C-Suite
Este documento define termos técnicos e de negócio usados no ecossistema C-Suite.
📋 Índice
- Conceitos de Negócio
- Conceitos Técnicos
- Métricas e Modelos
- Arquitetura e Componentes
- Bancos de Dados
💼 Conceitos de Negócio
4 Certos (4 Certos Dinâmico)
Sistema de decisão baseado em IA que determina os 4 aspectos críticos de uma ação comercial:
- Cliente Certo - Quem deve ser abordado
- Decisão baseada em modelo de intenção de compra
- Considera recency, frequency, monetary value (RFM)
-
Filtra clientes com maior probabilidade de conversão
-
Oferta Certa - O que deve ser oferecido
- Seleção de SKU/produto otimizada
- Considera histórico de compras, estoque, margem
-
Maximiza conversão e rentabilidade
-
Jeito Certo - Como comunicar a oferta
- Escolha do canal (WhatsApp, Email, SMS, etc.)
- Tom da mensagem (técnico, emocional, direto)
-
Personalização baseada em histórico de interações
-
Hora Certa - Quando agir
- Otimização do timing de envio
- Baseado em probabilidade de resposta
- Considera padrões de comportamento do cliente
Uso: Motor principal do app 4c para decisões 1:1 com clientes.
RFR (Recency, Frequency, Revenue)
Modelo de análise de comportamento de revendas (B2B) similar ao RFM, mas adaptado para canal de revenda:
- Recency (Recência) - Quantos dias desde o último pedido
- Medido em
recency_days -
Quanto menor, mais recente a relação comercial
-
Frequency (Frequência) - Quantidade de pedidos em um período
- Medido em
freq_90d(frequência nos últimos 90 dias) -
Indica regularidade da relação comercial
-
Revenue (Receita) - Valor total de pedidos em um período
- Medido em
revenue_90d(receita nos últimos 90 dias) - Indica valor comercial da revenda
Score RFR: Score combinado que classifica revendas em:
- class_risco: Baixo, Médio, Alto
- class_valor: Baixo, Médio, Alto
Uso: App csuite-sales-manager para priorização de revendas.
RFM (Recency, Frequency, Monetary)
Modelo clássico de análise de comportamento de clientes:
- Recency - Quanto tempo desde a última compra
- Frequency - Frequência de compras
- Monetary - Valor monetário das compras
Uso: App 4c para análise de clientes (nível B2C).
Context Shift (Mudança Estrutural)
Mudança significativa e sustentada em uma métrica ou padrão de comportamento, indicando uma alteração estrutural no negócio.
Características:
- Mudança persistente (não apenas flutuação temporária)
- Magnitude significativa (ex: aumento de 25% em receita)
- Direção clara (up ou down)
Exemplos:
- Receita aumentou 25% de forma sustentada
- Taxa de churn diminuiu 15% e se manteve
- Nova tendência de produto emergindo
Uso: App csuite-context detecta e reporta context shifts para tomada de decisão estratégica.
Tendência (Trend)
Padrão de comportamento detectado em um período médio (semanas/meses), diferente de eventos pontuais.
Tipos:
- Tendência de crescimento - Métrica aumentando consistentemente
- Tendência de declínio - Métrica diminuindo consistentemente
- Tendência estável - Métrica mantendo-se constante
Uso: App csuite-context detecta tendências para análise de médio prazo.
Evento (Event)
Ocorrência pontual de curto prazo que merece atenção imediata.
Características:
- Curto prazo (horas/dias)
- Nível de importância (low, medium, high)
- Contexto específico
Exemplos:
- "Receita aumentou 25% nos últimos 7 dias"
- "Novo cliente de alto valor adquirido"
- "Alerta de estoque baixo"
Uso: App csuite-context registra e expõe eventos para monitoramento.
Organismo Digital
Conceito que descreve o ecossistema C-Suite como um sistema integrado com três capacidades:
- Percepção (Sensing) - Coleta de sinais e dados
- Consciência (Thinking) - Interpretação usando IA e regras
- Ação (Acting) - Decisão e execução
Uso: Termo usado para descrever a integração entre 4c e csuite-executive via 4c-suite.
🔧 Conceitos Técnicos
Feature Service
Serviço que agrega e entrega dados como vetores de features para modelos de ML.
Função:
- Agrega dados de múltiplas fontes (MySQL, Redis, Kafka)
- Calcula features derivadas
- Cache de features para performance
Uso: App 4c - Feature Service (/features/customer)
Scoring Service
Serviço que aplica modelos de ML para calcular scores (intenção, oferta, canal, timing).
Modelos:
- Intent Model - Probabilidade de compra
- Offer Model - Ranking de ofertas
- Channel Model - Melhor canal de contato
- Timing Model - Melhor horário de envio
Uso: App 4c - Scoring Service (/score/*)
Decision Orchestrator
Componente que orquestra a decisão completa dos 4 Certos, combinando:
- Scores dos modelos ML
- Políticas e regras de negócio
- Contexto e constraints
Uso: App 4c - Decision API (/decide)
Policy Engine
Sistema que aplica políticas e regras de negócio definidas no nível executivo (C-Suite) nas decisões do nível cliente (4C).
Políticas comuns:
- Margem mínima
- Limites de contato
- SKUs prioritários
- Regras de desconto
Uso: Integração csuite-executive → 4c via csuite.policy_rules
Outbox Pattern
Padrão arquitetural para garantir entrega de eventos em sistemas distribuídos.
Como funciona:
1. Transação escreve evento em outbox_events
2. Processo assíncrono lê e publica eventos
3. Garante consistência transacional
Uso: App 4c - core.outbox_events para sincronização com C-Suite
CDC (Change Data Capture)
Técnica para capturar mudanças em banco de dados em tempo real.
Implementação:
- Debezium conectado ao MySQL
- Captura INSERT, UPDATE, DELETE
- Publica eventos no Kafka
Uso: App 4c - Para invalidar cache e sincronizar dados
Agent Run
Execução de um agente executivo (CFO, CEO, COO, etc.) que:
1. Analisa métricas e dados
2. Gera insights e recomendações
3. Cria alerts e action items
Uso: App csuite-executive - csuite.agent_runs
Action Item
Tarefa concreta gerada por um agente executivo que requer ação humana ou automática.
Tipos:
- Aprovar orçamento
- Revisar estoque
- Contatar cliente estratégico
- Ajustar política
Uso: App csuite-executive - csuite.action_items
Alert
Alerta gerado por um agente ou regra que indica problema ou oportunidade.
Níveis:
- Low - Informativo
- Medium - Requer atenção
- High - Crítico, ação imediata necessária
Uso: App csuite-executive - csuite.alerts
📊 Métricas e Modelos
Intent Score
Score de 0 a 1 que indica probabilidade de compra do cliente.
- 0.0 - 0.3: Baixa intenção
- 0.3 - 0.7: Média intenção
- 0.7 - 1.0: Alta intenção
Uso: Modelo IntentModel no app 4c
Offer Score
Score que ranqueia ofertas/produtos por potencial de conversão e rentabilidade.
Fatores:
- Histórico de compras do cliente
- Margem do produto
- Disponibilidade em estoque
- Regras de negócio
Uso: Modelo OfferModel no app 4c
Channel Score
Score que indica o melhor canal de contato para um cliente.
Canais:
- WhatsApp
- Email
- SMS
- Telefone
- Presencial
Uso: Modelo ChannelModel no app 4c
Timing Score
Score que indica o melhor horário para enviar uma mensagem/contato.
Fatores:
- Histórico de respostas do cliente
- Padrões de comportamento
- Horário do dia
- Dia da semana
Uso: Modelo TimingModel no app 4c
Score RFR
Score combinado de Recency, Frequency e Revenue para classificar revendas.
Classificações:
- class_risco: Baixo, Médio, Alto (risco de perder a revenda)
- class_valor: Baixo, Médio, Alto (valor comercial da revenda)
Uso: App csuite-sales-manager para priorização
🏗️ Arquitetura e Componentes
Córtex Comercial
Sistema de decisão no nível cliente (micro), focado em decisões 1:1.
Componentes:
- Feature Service
- Scoring Service
- Decision Orchestrator
- Executor
Uso: App 4c
Córtex Executivo
Sistema de decisão no nível organização (macro), focado em estratégia e gestão.
Componentes:
- Agentes Executivos (CFO, CEO, COO, CMO, CAIO)
- Scheduler
- Dashboard
Uso: App csuite-executive
Orquestrador
Camada que integra e consolida visão dos níveis micro (4c) e macro (csuite-executive).
Função:
- Consolida métricas de ambos os níveis
- Fornece visão única do organismo
- Coordena ações entre níveis
Uso: App 4c-suite
Executor
Componente que executa ações decididas pelos modelos.
Ações:
- Envio de mensagens (WhatsApp, Email, SMS)
- Criação de tarefas no CRM
- Atualização de sistemas externos
Uso: App 4c - Executor
Feedback Worker
Processo que coleta e processa feedback de ações executadas.
Feedback coletado:
- Mensagem entregue
- Mensagem lida
- Cliente respondeu
- Cliente comprou
- Cliente cancelou
Uso: App 4c - Feedback Worker
💾 Bancos de Dados
Schema staging
Schema do MySQL usado para ingestão bruta de dados do 4C.
Função:
- Recebe dados de sistemas operacionais (ERP, CRM)
- Views e staging tables
- Dados ainda não processados
Uso: App 4c
Schema core
Schema do MySQL com modelo unificado de dados do 4C.
Tabelas principais:
- core_customers - Clientes
- core_orders - Pedidos
- core_inventory - Estoque
- core_interactions - Interações
- core_feedback - Feedback
- core_signals - Sinais
- core_outbox_events - Eventos para sincronização
Uso: App 4c
Schema csuite_staging
Schema do MySQL para ingestão bruta de dados executivos.
Tabelas:
- companies_raw - Dados brutos de empresas
- companies_ready - Dados processados
Uso: App csuite-executive
Schema csuite
Schema do MySQL com modelo executivo.
Tabelas principais:
- organizations - Organizações
- agents - Agentes executivos
- agent_runs - Execuções de agentes
- alerts - Alertas
- action_items - Tarefas
- metric_samples - Amostras de métricas
- financial_transactions - Transações financeiras
- policy_rules - Regras de política
- core_sellers - Vendedores
- core_revendas - Revendas
- core_orders - Pedidos (B2B)
- core_interactions - Interações (B2B)
Uso: Apps csuite-executive, csuite-context, csuite-sales-manager
Schema context_radar
Schema do MySQL para features e tasks do sales manager.
Tabelas:
- features_revenda_rfr - Features RFR calculadas
- tasks_seller_day - Tasks diárias por vendedor
Procedures:
- sp_refresh_revenda_radar(IN p_ref_date DATE) - Recalcula features e tasks
Uso: App csuite-sales-manager
ClickHouse telemetry
Banco ClickHouse para eventos e telemetria.
Tabelas:
- telemetry.events - Eventos de telemetria
Uso: App 4c - Feedback Worker, métricas e analytics
Redis
Cache em memória para features e dados frequentes.
Uso:
- Cache de features por customer_id
- Sessões de usuário
- Dados temporários
Uso: App 4c - Feature Service
Kafka/Debezium
Sistema de mensageria para eventos CDC (Change Data Capture).
Uso:
- Eventos de mudança no banco
- Invalidação de cache
- Sincronização entre serviços
Uso: App 4c - Eventos CDC
🔄 Fluxos e Processos
Sincronização 4C → C-Suite
Processo que sincroniza dados do nível cliente (4C) para o nível organização (C-Suite).
Dados sincronizados:
- core.outbox_events → csuite.metric_samples
- core.core_orders → csuite.financial_transactions
- core.core_feedback → Métricas agregadas
Implementação: Script sync_4c_to_csuite.py (planejado)
Aplicação de Políticas C-Suite → 4C
Processo que aplica políticas definidas no C-Suite nas decisões do 4C.
Políticas aplicadas:
- Margem mínima
- Limites de contato
- SKUs prioritários
- Regras de desconto
Implementação: Policy Engine no Decision API do 4C
Refresh do Radar
Processo que recalcula features RFR e gera tasks diárias para vendedores.
Steps:
1. Calcula features RFR para todas as revendas
2. Classifica por risco e valor
3. Gera tasks priorizadas por vendedor
4. Atualiza context_radar.tasks_seller_day
Implementação: Procedure context_radar.sp_refresh_revenda_radar()
Uso: App csuite-sales-manager - Job refresh-radar
🎯 Termos de Negócio Específicos
Revenda
Cliente B2B no canal de revenda (não venda direta).
Características:
- Compra produtos para revender
- Tem histórico de pedidos
- Atribuída a um vendedor
- Tem segmento (jeans, malharia, lingerie, etc.)
Uso: App csuite-sales-manager
Vendedor (Seller)
Representante de vendas interno (inside sales / telemarketing B2B).
Características:
- Gerencia carteira de ~250 revendas
- Recebe tasks diárias priorizadas
- Executa contatos e follow-ups
Uso: App csuite-sales-manager
Task (Tarefa)
Ação recomendada para um vendedor em relação a uma revenda.
Campos:
- prioridade: alta, média, baixa
- tipo_acao: contato, follow-up, visita, etc.
- motivo: Razão da task (ex: "Sem pedido há 30 dias")
- status: pendente, concluida
- decision_payload: Decisão 4C Lite (opcional)
Uso: App csuite-sales-manager - context_radar.tasks_seller_day
Organização (Organization)
Entidade empresarial que usa o sistema C-Suite.
Características:
- Tem múltiplos agentes executivos
- Tem métricas e KPIs
- Tem políticas e regras de negócio
- Tem clientes e revendas
Uso: Apps csuite-executive, 4c-suite - csuite.organizations
Agente Executivo
Sistema de IA que atua como um executivo (CFO, CEO, COO, CMO, CAIO).
Funções:
- Analisa métricas e dados
- Gera insights e recomendações
- Cria alerts e action items
- Executa rotinas periódicas
Tipos:
- CFO - Análise financeira
- CEO - Visão estratégica geral
- COO - Operações e estoque
- CMO - Marketing e vendas
- CAIO - Inteligência artificial e dados
Uso: App csuite-executive
📚 Referências
- RELACAO_ENTRE_APPS.md - Visão geral dos apps
- ARQUITETURA.md - Diagramas de arquitetura
- API_DOCUMENTATION.md - Documentação de APIs
- 4c/docs/4C_ROADMAP.md - Roadmap do 4C
Última atualização: 2025-12-01