Clientes, carteira e portal

Objetivo

O Cliente é a Empresa que aceitou uma Proposta e foi convertida. A partir da conversão, a Radhr AI acompanha a relação inteira num lugar só, o Cliente 360: contratos, projetos, oportunidades de upsell e renovação, contatos, tarefas e uma linha do tempo única (eventos do cliente e do lead de origem). Duas leituras rodam sobre a carteira: o Motor de risco (atraso e churn) e a Expansão (upsell e renovação). O cliente, por sua vez, acompanha tudo pelo Portal do cliente, sem login. Contratos e Escopos têm documentos próprios: funcional/contratos e funcional/escopos.

Fluxo

1. O lead aceita a Proposta (em /pp/<código>) ou o Consultor registra o aceite. A Home mostra o cartão "Converter em cliente".
2. Na página do lead, o Consultor confirma empresa, CNPJ, contato, dono e data de kickoff e clica em Converter em cliente (pode marcar "registrar o aceite" no mesmo ato).
3. A Radhr AI acha ou cria a Empresa e o Contato (decisor), cria o Cliente em ativo com o total da versão aceita, fecha o lead como ganho, leva a Oportunidade a contrato, cria a Tarefa de kickoff e gera o contrato em rascunho (só para cliente novo).
4. A cadeia convertido roda o Motor de risco no cliente; a cadeia fechado indexa o lead para Leads parecidos.
5. No dia a dia, o Consultor trabalha no Cliente 360: notas, tarefas, contatos, oportunidades, status. Cada nota, oportunidade aberta ou movida e tarefa concluída dispara a cadeia cliente_movimento, que reavalia o risco.
6. Nos dias úteis às 8h (Brasília), antes do Digest, o Motor de risco reavalia todos os clientes que não estão em churn.
7. Toda segunda às 8h30 a Radhr AI abre as renovações devidas e relê a expansão de até 30 clientes; ao encerrar um projeto, a cadeia escopo_concluido relê a expansão daquele cliente na hora.
8. O Consultor envia o portal pelo 360; o cliente passa a ver contratos, andamento e mudanças e a receber avisos por e-mail (conforme o plano).

Regras de negócio

• Identidade da Empresa: CNPJ, depois domínio (do site; senão do e-mail, se não for provedor pessoal como gmail ou hotmail), depois nome normalizado. Encontrada, só completa o que faltava, nunca sobrescreve. Vive em src/clientes.ts (garantirEmpresa, dominioDe).
• Contato é identificado pelo e-mail dentro da Empresa; sem e-mail, sempre cria um novo. Vive em src/clientes.ts (garantirContato).
• Conversão exige proposta aceita (ou o aceite registrado junto, quando a máquina de proposta permite) e e-mail do contato; o que falta vem listado no aviso. Vive em src/clientes.ts (faltaParaConverter).
• Conversão idempotente: se a Empresa já é cliente, o lead só se liga a ela (cliente_vinculado), o total da proposta é somado ao contratado e não nasce tarefa de kickoff nem contrato. Kickoff padrão: 7 dias depois da conversão. Vive em src/clientes.ts (converterLead) e src/radar/clientes.ts.
• Nada se apaga: o lead continua existindo, fechado como ganho, e o Cliente guarda lead_origem_id. Vive em src/clientes.ts.
• Oportunidade "nova" espelha o estágio do lead (novo→nova, handoff/reunião→qualificada, proposta enviada→proposta, ganho→ganha), vai a contrato na conversão e fecha em ganha quando o contrato é assinado. Vive em src/clientes.ts (espelharOportunidade) e src/contratos.ts (marcarAssinado).
• Upsell e renovação nascem em qualificada, no Cliente 360, pelo Copiloto ou pela Expansão. Abrir renovação põe o cliente em renovando. Upsell ou renovação ganhos somam ao contratado o total da versão aceita da proposta deles (sem proposta aceita, o valor estimado); a oportunidade "nova" do lead não soma de novo, porque a conversão já somou o total da proposta. Upsell ganho leva o cliente a expandido; renovação ganha com o cliente em renovando volta a ativo. Vive em src/clientes.ts (abrirOportunidade, mudarEstagioOportunidade).
• Status do cliente só pela máquina cliente (ativo, em_risco, renovando, churn, expandido). Vive em src/estados.ts.
• Motor de risco, regras: etapa do projeto atrasada (alto com 7 dias ou 3 etapas), tarefa vencida (alto com 7 dias), kickoff sem registro depois de 3 dias (alto depois de 10), silêncio de 21 dias (alto com 45; eventos automáticos da Radhr AI não contam), e-mail devolvido nos últimos 14 dias (alto), upsell ou renovação parados há 14 dias (renovação parada 30 dias é alto). Vive em src/risco.ts (riscosDeCliente).
• Motor de risco, IA: o modelo lê a linha do tempo, tarefas e oportunidades e devolve nível, tipo, motivo e ação. O nível final é o pior entre regras e IA: alto leva ativo ou expandido a em_risco; baixo devolve em_risco a ativo; medio não muda o status. A leitura fica em cache por hash dos dados e do dia. Sem resposta válida do modelo, vale a regra. Vive em src/risco.ts (avaliarRiscoCliente).
• Expansão: as relações de expansão cadastradas pela organização (catalogo_relacoes: "depois de X, sugerir Y quando Z"; nascem da etapa 5 do onboarding, da auditoria ou do humano), as regras padrão do código (Foundation sem AI Layer sugere o Agente SDR; Foundation sem Sprint sugere o Sprint Completo; AI Layer sem sustentação sugere a sustentação — só na organização 1 ou enquanto não há relações cadastradas), o que clientes parecidos, do mesmo setor primeiro, compraram depois, mais o modelo com até 3 sugestões. O código aceita só chaves do Catálogo, tira o já comprado e o já aberto, precifica pelo porte (o modelo nunca dá preço) e limita a 4 sugestões. "Já comprado" junta os itens da proposta aceita do lead de origem e das propostas aceitas de upsell e renovação do cliente (também na comparação com clientes parecidos). Vive em src/expansao.ts (sugestoesPorRegra, consolidar, chavesCompradas).
• Renovação automática: com o contrato principal terminando em até 60 dias e nenhuma renovação aberta, o Radar abre a oportunidade de renovação (valor do contrato principal) e põe o cliente em renovando. A data vem sempre do contrato; o modelo só pode subir o risco da renovação. Vive em src/expansao.ts (abrirRenovacaoSeDevida, renovacaoDe).
• Portal: token único de 32 caracteres, gerado uma vez e sem validade; o link vai ao decisor com e-mail (ou ao e-mail digitado), com resposta para o Consultor dono. Cada abertura conta e vira portal_aberto. Vive em src/portal.ts.
• Pedido de mudança pelo portal exige título, descrição de ao menos 10 caracteres e e-mail; entra com origem cliente no projeto mais recente que não está concluído, é analisado pela IA em segundo plano e avisa o Consultor por e-mail. E-mail que não está nos contatos é aceito e marcado. Vive em src/portal.ts.
• Avisos ao cliente saem só quando o cliente já tem portal (token gerado) e a organização tem o recurso avisos_cliente: entregável concluído, projeto concluído e mudança decidida (rejeitada, aplicada ou com aditivo). Vão ao decisor com e-mail e a quem pediu pelo portal, sempre com o link do portal; evento cliente_avisado. Vive em src/notificacoes-cliente.ts.
• Marca no portal: logo ou nome da contratada e cores do tema da organização por cima da casca; sem configuração, Witbiz. Vive em src/portal.ts (marcaDoPortal).

Casos de uso

• Lead aceitou pelo link. A Home mostra "Converter em cliente"; um clique na página do lead cria tudo e leva ao 360 com a tarefa de kickoff e o contrato em rascunho.
• Segundo contato da mesma empresa fecha outra compra. A conversão liga o lead ao cliente existente e soma o valor; o contrato novo não é gerado sozinho.
• Cliente sumiu. Depois de 21 dias sem registro humano, o risco aparece na Home e no 360; com 45 dias, o cliente vai a em_risco. Registre o contato como nota e o motor reavalia.
• Contrato termina em 50 dias. Na segunda, a Radhr AI abre a renovação e a Home pede "Abrir a renovação do contrato" se ainda não houver.
• Projeto entregue. Ao encerrar o Escopo, a Expansão relê o cliente e a Home sugere "Propor <produto>" com motivo e valor.
• Cliente quer acompanhar o projeto. Use "Enviar portal" no 360; ele vê contratos, fases, entregáveis e pode pedir mudanças.

Telas

• /radar/clientes: carteira com filtros por status e "só os meus", dono, desde, contratado e kickoff.
• /radar/cliente/:id (Cliente 360): cabeçalho com saúde, leitura do risco e contratado; abas Visão geral (ações, riscos, atividade recente), Contratos e propostas (o cartão Propostas lista a do lead de origem e as de upsell/renovação, com status, versão, total e links; aparece mesmo sem lead de origem), Oportunidades (upsell, renovação e o bloco Expansão com "reler"), Solicitações (mudanças de escopo), Contatos e Linha do tempo. Ações: nota, status, dono, kickoff, contato, tarefa, abrir e mover oportunidade, avaliar risco, "Enviar portal" e link do portal.
• /radar/cliente/:id/expansao: consulta usada pela tela enquanto a leitura de expansão roda em segundo plano.
• /radar/lead/:id (botão "Converter em cliente"): formulário da conversão.
• /portal/<token> (público): contratos e o que falta assinar, as propostas aceitas (a do lead de origem e as de expansão/renovação, com o link de cada uma), andamento por fase com etapas e entregáveis, histórico e formulário de mudanças, contato do consultor e agenda.
• Home /radar/: cartões "Converter em cliente", riscos de clientes, "Abrir a renovação do contrato", "Propor <produto>" e a carteira no cabeçalho.

Permissões

• admin e consultor: veem e editam todos os clientes da organização; as telas do 360 não checam o dono, salvo o portal (abaixo). O filtro "só os meus" e a Home (por padrão, os seus e os sem dono) organizam a visão.
• financeiro e leitura: consultam o Cliente 360 e a carteira. Conversão, notas, oportunidades, tarefas e releituras da IA são recusadas com 403; o financeiro só gera o contrato pelo bloco de contratos do 360 (src/radar/permissoes.ts).
• Copiloto: lê qualquer cliente; ações (nota, oportunidade, mudança) só no cliente de que o consultor é dono ou sem dono; admin age em todos (src/copiloto.ts). O link do portal (link_portal) só devolve um link que já existe: não gera nem envia.
• Portal (enviar ou pegar o link): o link dá acesso sem login, então o 360 ("Enviar portal") e o Copiloto (link_portal) usam a mesma regra, recusaDoPortal em src/portal.ts: admin em todos; consultor só no Cliente de que é dono ou no sem dono; financeiro e leitura não; com o RBAC v2, portal.enviar no Cliente (escopo próprio e overrides). Recusa no 360 volta como aviso "Portal não enviado", sem gerar token nem e-mail.
• cliente (por link): o portal dá acesso só aos dados daquele Cliente, sem login; quem tem o link vê.
• Gating de plano: conversão, 360, risco, expansão e portal existem em todos os planos. Os avisos por e-mail ao cliente exigem avisos_cliente (Profissional ou superior) (src/planos.ts).

Perguntas frequentes

Por que o botão "Converter" diz que ainda falta algo? A conversão pede proposta aceita (ou o aceite marcado no mesmo ato, se a proposta foi enviada) e e-mail do contato. O aviso lista exatamente o que falta.

O cliente foi para "em risco" sozinho. Quem decidiu? O Motor de risco: o pior nível entre as regras e a leitura da IA. O motivo aparece no 360. Resolva o que foi apontado e registre; a reavaliação devolve a ativo quando o nível cair para baixo.

Posso mudar o status do cliente à mão? Sim, pelo 360, desde que a máquina de estados permita a transição (por exemplo, churn só volta para ativo).

A IA pode abrir uma oportunidade sozinha? Não. A Expansão sugere; a oportunidade só nasce quando alguém clica (Home ou 360) ou confirma no Copiloto. A exceção é a renovação a 60 dias do fim do contrato, que a Radhr AI abre por regra.

O link do portal expira? Não. É pessoal e fixo; quem tiver o link acessa. Se vazar, hoje não há como trocar o token pela tela.

Como pego o link do portal sem reenviar o e-mail? Pergunte ao Copiloto ("link do portal do cliente X"): ele devolve o /portal/<token> com quando foi enviado e aberto, se você pode enviar o portal desse Cliente. Se o portal ainda não foi gerado, ele orienta usar "Enviar portal" no 360.

Por que o cliente não recebeu o aviso de entregável concluído? Confira três coisas: o cliente tem portal gerado, a organização está no Profissional ou superior e há um contato com e-mail (de preferência marcado como decisor).

O pedido de mudança do portal cai em qual projeto? No projeto mais recente do cliente que não está concluído. Sem projeto em andamento, o portal recusa o pedido.