Decisão Final de Arquitetura — Lead Flow

1. Contexto e Referências

Este documento registra a decisão final de arquitetura adotada para o Lead Flow (codinome: Konecty Black), fundamentada na análise técnica detalhada realizada.

Referências: - Análise completa das alternativas: analise-alternativas-arquitetura.md - Documentação de fluxo e regras de negócio: fluxo-hierarquico.md, etapas-detalhadas.md, sub-situacoes-rastreamento.md, estados-finais.md, cadencia-e-automacoes.md, rastreamento-metricas.md

2. Síntese da Análise Realizada

Foram analisadas três alternativas arquiteturais em profundidade:

  1. Abordagem Customizada Minimalista (Python + PostgreSQL + RabbitMQ + Celery)
  2. Vantagens: simplicidade, controle, integração natural com IA, baixo custo

  3. Desvantagens: processos muito longos requerem workarounds, confiabilidade manual

  4. Temporal.io (Workflow orchestration especializado)

  5. Vantagens: processos longos nativos, confiabilidade automática, escalabilidade

  6. Desvantagens: curva de aprendizado, complexidade operacional, vendor lock-in

  7. Abordagem Híbrida Incremental (Evolução gradual)

  8. Vantagens: validação antes de investimento, YAGNI aplicado
  9. Desvantagens: complexidade dual temporária

Conclusão da análise: Embora Temporal resolva elegantemente problemas de workflows longos, o custo de complexidade e operação não se justifica no contexto atual, dado que: - O CRM Konecty já é uma plataforma robusta e flexível - A essência do Lead Flow é decisão inteligente sobre próximos passos de oportunidade, não orquestração genérica de workflows técnicos - O uso de IA como agente orquestrador reduz a necessidade de um motor de workflow sofisticado

3. Definições Centrais: Oportunidade e Atividade

Para alinhar a arquitetura à linguagem de negócio e ao Konecty, adotamos as seguintes definições como base técnica:

3.1. Oportunidade

Definição: Uma oportunidade é uma possível venda que pode ser gerada a partir de um lead. Ela é criada quando um lead é convertido em uma oportunidade e é responsável por gerenciar o processo de venda.

Em termos arquiteturais: - A oportunidade é o estado de negócio (onde estamos no funil, o que já foi descoberto, quão avançado está) - Toda a jornada de venda – fases, mudanças de situação, transferência entre times, encerramento – acontece no contexto da oportunidade - A oportunidade é o centro de rastreamento e o objeto principal sobre o qual a IA toma decisões

3.2. Atividade

Definição: Uma atividade é uma ação que precisa ser realizada para avançar na venda. Ela é criada quando uma oportunidade é criada e é responsável por gerenciar o processo de acompanhamento da venda. Diversas atividades são criadas e executadas durante o ciclo de vida da oportunidade.

Em termos arquiteturais: - As atividades são os passos concretos que levam a oportunidade adiante - Elas são o "veículo operacional" das decisões da IA e dos corretores - Exemplos: contato inicial, follow-up, envio de material, agendamento de visita, checagem de documentação

3.3. Relação Oportunidade ↔ Atividade ↔ IA

  • A IA decide quais atividades criar/atualizar/cancelar e como evoluir a oportunidade com base no contexto
  • A oportunidade mantém o estado consolidado (fase, situação, resumo, descobertas)
  • As atividades são as ações executáveis que movem a oportunidade através do funil

4. Decisão Final de Arquitetura

4.1. Arquitetura Adotada

Adotar uma arquitetura customizada, centrada no CRM Konecty como fonte da verdade, com um serviço de decisão baseado em IA orquestrando atividades e evolução de oportunidades, acionado por eventos via RabbitMQ, sem uso de motores de workflow como Temporal ou filas de tarefa como Celery.

4.2. Componentes da Arquitetura

Não usaremos: - ❌ Temporal.io - complexidade e custo operacional não justificados - ❌ Celery - não é necessário como orquestrador de workflows de longa duração

Usaremos: - ✅ Konecty - sistema de registro (oportunidade, atividade, estados) - fonte da verdade - ✅ RabbitMQ - canal de eventos (gatilhos de decisão) - apenas eventos, não orquestração - ✅ Serviço de IA (backend em Python) - avalia contexto e decide próximo passo

4.3. Alinhamento com Princípios

Esta escolha está alinhada a:

  • KISS: arquitetura simples, com poucos componentes: Konecty, RabbitMQ e serviço de IA
  • YAGNI: evita-se introduzir um workflow engine completo enquanto não houver dor clara que o justifique
  • DRY: Konecty é a fonte única da verdade; decisões referenciam dados existentes, não duplicam
  • SOLID: responsabilidades bem separadas:
  • Konecty = estado e operações de CRM
  • IA = decisão sobre próximos passos
  • RabbitMQ = eventos/gatilhos

5. Comportamento Arquitetural

5.1. Fluxo: Entrada de Lead e Criação de Oportunidade

Quando: Lead entra no sistema

Processo: 1. Konecty cria ou atualiza a oportunidade correspondente 2. Evento é publicado via RabbitMQ indicando oportunidade nova/atualizada 3. Serviço de IA é notificado, avalia dados do lead e da oportunidade 4. IA decide: - Qual a primeira atividade a ser criada (tipo, canal, prazo de validade) - Qual a fase/situação inicial mais adequada (conforme fluxo-hierarquico.md) 5. Decisão é registrada e aplicada no Konecty: - Criação/atualização de atividades - Atualização da oportunidade (fase, situação, resumo inicial)

5.2. Fluxo: Conclusão de Atividade

Quando: Atividade é concluída pelo corretor (marcada como "feito" ou resultado registrado)

Processo: 1. Konecty gera evento via RabbitMQ: atividade_concluida 2. Serviço de IA lê contexto da oportunidade: - Fase e situação atual - Atividades abertas - Histórico relevante - Resultado da atividade concluída 3. IA decide: - Se deve criar nova atividade de acompanhamento - Se deve encerrar a oportunidade (conforme estados-finais.md) - Se deve mudar situação ou fase da oportunidade - Se não faz nada (ex.: já há conclusão adequada) 4. Decisão é registrada e aplicada no Konecty: - Criar/cancelar atividades conforme decisão - Atualizar fase/situação se decidido progresso - Atualizar resumo da oportunidade com descobertas e próximos focos

5.3. Fluxo: Interações Espontâneas do Cliente

Quando: Corretor registra que cliente ligou, respondeu ou pediu visita

Processo: 1. Corretor cria nova atividade no Konecty (ex.: "Cliente ligou", "Cliente pediu visita") 2. Konecty gera evento via RabbitMQ: nova_interacao_cliente (ou similar) 3. Serviço de IA reavalia o plano: - Analisa atividades futuras já agendadas (nutrição, follow-ups) - Considera o novo evento do cliente - Avalia histórico recente 4. IA decide: - Quais atividades futuras devem ser canceladas (ex.: cadência de nutrição que perdeu sentido) - Que "nova trilha" de atividades iniciar (ex.: fluxo de Visitas, Negociação) - Se deve mudar situação da oportunidade - Se deve transferir para gerente ou equipe de nutrição longa 5. Decisão é registrada e aplicada no Konecty: - Cancelar/fechar atividades que perderam sentido - Criar novas atividades conforme nova trilha - Atualizar situação da oportunidade - Transferir oportunidade se decidido

5.4. Atualização Contínua do Resumo da Oportunidade

Objetivo: Evitar necessidade de ler todo histórico para entender contexto

Processo: - A cada decisão relevante, serviço de IA atualiza resumo consolidado da oportunidade - Resumo contém: - Quem é o cliente (descobertas relevantes) - Quais dores/necessidades foram identificadas - Que compromissos já foram assumidos - Qual o foco da próxima interação - Resumo ajuda corretores e gestores a entender rapidamente "onde estamos e o que importa agora"

6. Registro Sistemático das Decisões da IA

6.1. Objetivo do Registro

Para manter rastreabilidade, aprendizado e governança, cada decisão da IA deve ser registrada de forma enxuta, mas consistente.

6.2. Modelo Conceitual de Registro

Entidades principais: - Oportunidade (no Konecty) - estado de negócio, resumo, fase, situação - Atividade (no Konecty) - ações executáveis, ligadas a decisões de IA - Decisão de IA (novo registro) - rastreamento de cada decisão tomada

6.3. Campos Essenciais da Decisão de IA

Para cada decisão, registrar:

Identificação e Contexto: - ID único da decisão - ID da oportunidade relacionada - Timestamp da decisão - Tipo de evento que disparou (ex.: novo_lead, atividade_concluida, cliente_ligou, cliente_solicitou_visita)

Snapshot do Estado (sem duplicar tudo): - Fase e situação da oportunidade antes da decisão - Atividades abertas relevantes (lista enxuta: id, tipo, prazo) - Resumo do contexto usado (texto curto do que foi considerado) - Versão da regra/prompt de IA usada (para rastreabilidade de melhorias)

Saída da IA (intenção): - Ações recomendadas (lista de alto nível): - "criar atividade: contato WhatsApp" - "cancelar atividades: X, Y" - "mudar situação para: Matching / Visitando" - "transferir para nutricao_longa" - Justificativa da IA (texto curto explicando o porquê) - Nível de confiança (quando aplicável)

O que foi efetivamente aplicado: - Ações aplicadas (pode divergir de recomendadas se houve veto por regra) - IDs das atividades criadas - IDs das atividades canceladas - Mudanças na oportunidade (situação_de, situação_para, transferida_para)

Interação humana (quando houver): - Se houve revisão humana - Comentário do revisor (opcional) - Se foi aprovada parcialmente (quando humano altera antes de aplicar)

6.4. Vínculo Atividade ↔ Decisão

Atividades criadas ou ajustadas pela IA devem saber de qual decisão nasceram: - Campo ligada_a_decisao_id na atividade - Campo origem_atividade (valores: corretor, cliente, sistema, ia)

Isso permite: - Auditoria completa: "por que essa atividade foi criada?" - Análise de eficácia: "decisões da IA estão gerando resultados?" - Melhoria contínua: "quais decisões funcionam melhor?"

6.5. Princípios de Registro (KISS/YAGNI)

Não é necessário, neste momento: - Motor de regras genérico - Modelagem excessivamente sofisticada - DSL para regras de negócio

Basta garantir: - Cada decisão pode ser auditada - Existe vínculo claro: evento → decisão → mudanças na oportunidade/atividades - Informações podem ser consultadas posteriormente para melhoria contínua

7. Alinhamento com Documentação de Fluxo e Métricas

A arquitetura definida deve respeitar e operacionalizar o que já está descrito nos documentos do projeto:

7.1. Fases e Sub-situações

Documentos: fluxo-hierarquico.md, etapas-detalhadas.md, sub-situacoes-rastreamento.md

Como a arquitetura aplica: - As fases e sub-situações mapeadas orientam: - Quais tipos de atividades a IA pode propor em cada momento - Em que condições uma oportunidade pode mudar de fase - Quando uma oportunidade deve ser encaminhada para nutrição longa, gerente ou encerramento

7.2. Regras de Negócio

Documentos: cadencia-e-automacoes.md, premissas.md, estados-finais.md

Como a arquitetura aplica: - SLAs, critérios de passagem, motivos de perda, cadências são insumos para o serviço de decisão de IA - A IA lê essas regras e as aplica, caso a caso, em cada oportunidade

7.3. Métricas e KPIs

Documento: rastreamento-metricas.md

Como a arquitetura aplica: - Métricas desejadas (tempo em cada fase, taxa de conversão, motivos de perda, eficiência das cadências) dependem diretamente de: - Registrar bem as atividades - Registrar as decisões da IA - Manter a oportunidade como fonte de verdade do estado

7.4. Task List de Fechamento

Documento: task-list-fechamento.md

Como a arquitetura aplica: - Quando oportunidade entra em fase de Fechamento, IA pode gerar automaticamente a lista de tarefas conforme documentado - Cada tarefa é uma atividade no Konecty, rastreável e auditável

8. Consideração Final

A escolha arquitetural final é deliberadamente pragmática:

  • Evita a complexidade e o acoplamento de um motor de workflow completo neste momento (YAGNI)
  • Aproveita ao máximo o que o Konecty já oferece como CRM e fonte de verdade
  • Usa RabbitMQ apenas como canal de eventos, mantendo o desenho simples
  • Coloca a IA no centro da orquestração de oportunidades e atividades, que é exatamente onde está o diferencial competitivo do Lead Flow

Qualquer evolução futura (como introduzir um motor de workflow especializado) pode ser avaliada com base em dados de operação e aprendizado obtidos com este desenho. Por ora, a arquitetura escolhida maximiza simplicidade, alinhamento ao negócio e foco na essência do problema: decidir, a cada nova interação, qual é o melhor próximo passo para cada oportunidade.

Versão: 1.0
Status: Decisão de arquitetura consolidada e registrada
Data: Novembro 2025
Relacionado: Ver analise-alternativas-arquitetura.md para análise técnica completa