Propostas (CPQ)

Objetivo

A Proposta é o documento comercial que o Consultor fecha com o lead. Desde a F1 ela funciona como CPQ: uma proposta por lead, com versões (cada envio congela uma) e itens precificados pelo código a partir do Catálogo. A Pré-proposta do chat e da etapa 2 entra como versão inicial; o Consultor ajusta itens, preço e condições, envia por link único /pp/<código> e o lead pode aceitar na própria página. A proposta aceita é o que permite converter o lead em Cliente e gerar o Contrato.

Fluxo

1. Versão inicial. Cada Pré-proposta (chat ou etapa 2) vira uma nova versão da proposta do lead, com origem agente ou etapa2. Se o Consultor abre o editor e não há versão nenhuma, a última Pré-proposta é espelhada naquele momento.
2. Versão de trabalho. Ao abrir o editor (/radar/lead/:id/proposta), a Radhr AI usa a última versão se ela for do Consultor e ainda não foi enviada; senão, cria uma cópia nova (origem consultor) com os mesmos itens.
3. Montagem. O Consultor adiciona itens do catálogo (preço de lista pelo porte), itens livres (nome e preço), aplica sugestões da IA, edita quantidade, preço unitário, fase e o porquê de cada item, e escreve resumo, observações e condições. Os totais são recalculados a cada mudança.
4. Apoio da IA. Ao lado ficam as sugestões por sinais, o alerta da política de desconto e margem, a Estratégia da proposta (gerada na aba Propostas do Lead Workspace) e as propostas de leads parecidos que fecharam como ganho.
5. Envio. "Enviar ao lead" congela a versão, gera o código (o mesmo para todas as versões da proposta), manda o e-mail com o link /pp/<código> e leva o lead a proposta_enviada.
6. Leitura pelo lead. Cada abertura de /pp/<código> soma em aberturas, registra proposta_aberta, leva a proposta de enviada a visualizada e pede a Próxima ação.
7. Aceite. O lead aceita na página (nome, e-mail, confirmação de leitura) ou o Consultor muda o status para aceita no editor. O consultor dono recebe e-mail com o atalho para converter.
8. Depois do aceite. A Home mostra "Converter em cliente"; a conversão gera o Contrato em rascunho (ver funcional/clientes e funcional/contratos).
9. Upsell e renovação (25/09, migração 0028). Uma Oportunidade de cliente (upsell/renovacao) tem a sua própria proposta em /radar/oportunidade/:id/proposta, com o mesmo editor: o destinatário é o contato decisor da empresa (porte da empresa, consultor = dono), sem os blocos que dependem de lead. A renovação nasce com os itens da última proposta aceita do cliente. Enviar leva a oportunidade a proposta; o aceite — pelo cliente na página pública ou registrado pelo Consultor no editor — gera o Contrato em rascunho ligado à oportunidade ("Contrato de expansão" ou "Renovação") e a leva a contrato; assinado, ela fica ganha, o total da versão aceita soma ao contratado do cliente e ele vai a expandido/ativo. Os eventos ficam no Cliente (alvo), não num lead.

Regras de negócio

• Preço de lista pelo porte. Item do catálogo: preco_padrao do catálogo em banco, se houver; senão mínimo + (máximo − mínimo) × posição do porte (0,3 / 0,5 / 0,7), arredondado a R$ 500. Agente do AI Layer entra como ai.agente:<id> com a faixa de "agente individual". Item livre do banco usa o preço padrão (ou a faixa). O mesmo item não entra duas vezes na versão. — src/propostas.ts (precoDeCatalogo, adicionarItem)
• Totais. Itens recorrentes (mensais) ficam fora do total; o desconto de cada item é a diferença entre preço de lista e preço unitário; a margem estimada usa o custo interno do catálogo e só aparece quando há custo cadastrado. — src/propostas.ts (totais)
• Política de desconto da organização: sem perfil de IA com regras de preço, vale a do código (POLITICA): desconto sobre a lista a partir de 10% gera aviso; a partir de 20% exige admin para enviar. Com regras de preço no perfil, o aviso começa no desconto máximo definido ali e a aprovação de admin 10 pontos acima; as regras escritas no perfil aparecem junto do alerta no editor. Margem abaixo da referência gera aviso e mais de 10 pontos abaixo exige admin. A referência é a média das margem_alvo do catálogo dos itens, ponderada pelo valor; sem elas, a margem mínima do perfil (padrão 35%). Consultor que tenta enviar nesse caso recebe "Peça a um admin para enviar". — src/propostas.ts (politicaDesconto, margemAlvo, enviarVersao), src/perfil/condicoes.ts (politicaDoPerfil)
• Condições limitadas ao publicado. Parcelas entre 1 e o máximo da organização; desconto à vista até o da organização; validade entre 1 e 90 dias. Sem perfil, o máximo é 10x e 5%; com regras de preço e de proposta no perfil, valem as dela. Uma versão nova sem condições copiadas nasce com as condições da organização (padrão 10x, 5%, 15 dias). — src/propostas.ts (atualizarTextos, condicoesPadraoDaOrganizacao), src/perfil/condicoes.ts
• Envio exige e-mail e itens. Sem e-mail do lead ou sem itens, o envio é recusado. O e-mail ("Proposta <organização> — <empresa>") sai em nome do Consultor pelo remetente da organização (o próprio, se verificado e com o recurso ligado; senão, contato@witbiz.com.br), com resposta para o e-mail dele. — src/propostas.ts, src/remetente.ts (enderecoDe)
• Versão enviada não muda. O envio grava enviada_em e a data de validade na versão; qualquer edição posterior acontece numa nova versão. O primeiro envio muda o status de rascunho para enviada (evento proposta_status); os seguintes registram proposta_reenviada. — src/propostas.ts
• Link público mostra a última versão enviada. A versão atual (versao_atual) acompanha o rascunho mais novo só até o primeiro envio. Depois dele, ela passa a ser a versão que o cliente vê, e só um novo envio a avança. Abrir o editor, criar uma versão de trabalho ou espelhar uma etapa 2 depois do envio não tira /pp/<código> do ar. Também não muda o que a conversão, o contrato e a expansão leem. — src/propostas.ts (apontarVersaoAtual), src/proposta-formal.ts
• Estados da proposta (máquina proposta): rascunho → enviada → visualizada → em_negociacao → aceita | recusada | expirada. De enviada, visualizada ou em_negociacao dá para voltar a rascunho; recusada e expirada só voltam a rascunho; aceita é final. Toda mudança passa por transicao(). — src/estados.ts, src/propostas.ts (mudarStatus)
• Expiração não é automática. Nenhuma rotina move a proposta para expirada. Depois da validade, a página pública mostra o selo "expirada", esconde o formulário de aceite e recusa o aceite. — src/proposta-versao.ts, src/proposta-formal.ts
• Aceite pelo lead. Exige nome, e-mail válido e confirmação de leitura; recusa proposta expirada ou já aceita; registra aceita_em na versão e proposta_aceita com origem lead, IP e navegador; avisa o dono e pede a Próxima ação. O e-mail informado não precisa ser o do lead. — src/proposta-formal.ts
• Aceite pelo Consultor. Mudar o status para aceita no editor marca aceita_em na última versão enviada e registra proposta_aceita. Na conversão, o Consultor também pode registrar o aceite no mesmo ato. — src/radar/proposta.ts, src/clientes.ts
• Sugestões por sinais (sem modelo): itens cujo gatilho aparece na dor, nas ferramentas ou nas respostas da etapa 2 e que ainda não estão na versão; até 5. — src/propostas.ts (sugerirPorSinais)
• Estratégia da proposta (Proposal Strategist, Opus): lê triagem, Pré-propostas, resumo, site, reunião, notas e leads parecidos; devolve posicionamento, abertura, objeções com resposta, argumentos, riscos, alternativa de escopo e condições dentro das publicadas pela organização (parcelas e desconto à vista do perfil, senão 10x e 5%). Fala como estrategista da organização e recebe o perfil de IA dela (posicionamento, proposta de valor, diferenciais, cliente ideal, playbook, objeções, negociação, regras de preço, tom, instruções); a versão do perfil entra no hash. Termo do vocabulário proibido do perfil é removido da saída, com o evento vocabulario_proibido_removido. Gerada pelo botão na aba Propostas, que sempre chama o modelo de novo (a reutilização por hash vale só para chamadas automáticas). Registra estrategia_gerada e entra no rascunho legado. Não altera preço. — src/estrategia.ts, src/radar/lead.ts
• Rascunho em markdown (legado). Continua disponível: a IA escreve o texto a partir do Valor de referência, das notas, do site e da estratégia; o Consultor edita, define valor e validade (padrão 15 dias) e envia por /pp/<código>. Não passa pela política de desconto nem pela máquina de estados. O e-mail do rascunho legado usa a identidade da organização: assunto "Proposta {nome curto} — <empresa>", remetente por enderecoDe (domínio próprio verificado, senão o da Witbiz) e o rodapé da organização; o corpo diz "segue a proposta de {nome curto}". — src/radar/lead.ts, src/identidade.ts, src/proposta-formal.ts
• Só lead da organização. Gerar estratégia ou rascunho e enviar o rascunho (POST /radar/lead/:id) exigem que o lead exista na organização da sessão; senão, 404 sem gravar nada. — src/radar/lead.ts

Casos de uso

• Proposta a partir da Pré-proposta. O lead fechou o escopo na etapa 2; o Consultor abre o editor, encontra os itens já precificados, ajusta o porquê de cada um e envia.
• Desconto para fechar. O Consultor baixa o preço unitário do Sprint e o desconto passa de 20%: o editor avisa "Exige aprovação de admin para enviar"; um admin revisa e envia.
• Nova versão depois de uma objeção. O lead pediu escopo menor; o Consultor abre o editor (nasce a v2), remove um item, coloca a alternativa de escopo da estratégia e envia a nova versão. Até o envio, o link continua mostrando a v1.
• Aceite pela página. O decisor aceita em /pp/<código>; o consultor recebe o e-mail "Proposta aceita" e a Home traz "Converter em cliente".
• Aceite por e-mail. O lead respondeu "de acordo" por e-mail; o Consultor muda o status para aceita no editor ou marca o aceite no cartão de conversão.

Telas

• **/radar/lead/:id/proposta — Editor de proposta.** Cabeçalho com versão e status, barra de total fixa com o botão de envio, itens por fase (editar, remover), adicionar do catálogo ou item livre, textos e condições, status e histórico de versões; coluna da IA com sugestões, estratégia e comparáveis.
• **/radar/lead/:id/proposta/ver — Prévia.** A versão de trabalho como o lead verá, para imprimir em PDF. Para financeiro e leitura, mostra a versão mais nova, sem criar nada.
• **/radar/lead/:id, aba Propostas.** Atalho para o editor, rascunho em markdown (legado) e o cartão Estratégia da proposta.
• **/radar/proposta/:id — Prévia do rascunho legado**, com a barra da Radhr AI e o botão de PDF.
• **/pp/<código> — Proposta pública.** Versão enviada com itens, investimento, validade, próximos passos e o formulário de aceite; mostra "Proposta aceita" depois do aceite.

Permissões

• Lead anônimo por link: lê a proposta enviada e aceita pelo formulário; cada abertura é registrada.
• Consultor: edita e envia propostas de qualquer lead da organização, dentro da política de desconto; muda status; gera a estratégia e o rascunho legado.
• Admin: tudo do consultor e o envio das versões que exigem aprovação (desconto no limite de aprovação da política, 20% no padrão, ou margem mais de 10 pontos abaixo da referência). A verificação usa o papel vigente da sessão (vínculo de membro); sem ele, o papel do cadastro de usuário (usuarios.papel).
• Financeiro e leitura: só consultam. O editor redireciona para a prévia da versão mais nova e não cria versão de trabalho. Qualquer alteração (itens, textos, status, envio) é recusada com 403 pelo middleware (src/radar/permissoes.ts).
• Plano: "Propostas CPQ com versões, link público e aceite pelo lead" estão em todos os planos (src/planos.ts). A estratégia e o rascunho respeitam o Limite de IA.

Perguntas frequentes

Abri o editor depois de enviar. O link do lead continua funcionando? Sim. Depois do primeiro envio, /pp/<código> mostra a última versão enviada; a versão de trabalho só aparece para o lead quando for enviada (o código do link é o mesmo).

Posso mudar o preço de um item do catálogo? Sim, no campo "Unit.". O preço de lista fica guardado; a diferença vira desconto e entra na política.

Por que a margem não aparece? Margem depende do custo interno do item no catálogo em banco. Sem custo cadastrado, aparece "margem não calculada".

A proposta venceu. Ela expira sozinha? Não. A página pública passa a mostrar "expirada" e bloqueia o aceite, mas o status só muda se o Consultor marcar expirada. Para renovar, envie uma nova versão.

Qual a diferença entre a proposta do editor e o "rascunho em markdown"? O editor é o fluxo atual, com itens, versões, política de desconto e aceite. O rascunho em markdown é o formato anterior, mantido como legado; não tem aceite nem política.

Por que o limite de desconto da minha organização não é 10%/20%? Porque o perfil de IA da organização tem regras de preço: o aviso começa no desconto máximo definido ali e a aprovação de admin, 10 pontos acima. Sem regras de preço no perfil, valem 10% e 20%.

A Estratégia da proposta muda o preço? Não. Ela sugere posicionamento, argumentos e condições dentro das publicadas; preço vem do catálogo e do Consultor.