Avanço do negócio (pipe Comercial)¶
O que é¶
As três ações que empurram um negocio para a frente dentro do pipe Comercial: Aceitar proposta, Docs OK e Marcar assinado. São os "botões de avançar" que o operador comercial usa no dia a dia do kanban-comercial — cada uma dispara um evento de domínio (ver board-read-only-orientado-a-eventos), nunca um arrasto de card.
Os dois passos seguintes do ciclo — cadastro de CCB e envio de documentos/efetivação — acontecem na Mesa F2 e têm página própria: ver cadastrar-ccb e aguardando-documentacao.
Como funciona¶
Aceitar proposta (✓ Aceito)¶
No dialog de propostas do card (etapa Em Negociação), o operador marca qual proposta o
cliente fechou. É escolha única exclusiva: PATCH
/v2/mesa-analise/propostas/:propostaId/aceitar?exclusivo=true aceita a escolhida e limpa o
aceite das irmãs do mesmo negócio (não dá pra ter duas propostas aceitas ao mesmo tempo). É
forward-only — regra de domínio válida em qualquer pipe (ver pipe-e-etapa): uma vez
aceita, não volta a "não aceita" por essa ação. Emite proposta.aceita, que avança o card para
Coleta de Documentos.
Docs OK¶
Botão da etapa Coleta de Documentos: POST .../coletar-documentos. Confirma que a
documentação do cliente está completa e emite proposta.docs-coletados, que cruza de pipe
— o card sai do Comercial e aparece na Mesa F2 (coluna Cadastrar CCB). É a única ação de avanço
deste grupo que muda de pipe (as outras duas ficam dentro do Comercial).
Marcar assinado¶
Botão da etapa Aguardando Assinatura: POST .../marcar-assinado. Confirma que o contrato foi
assinado e emite proposta.contrato-assinado, avançando para Aguardando Pagamento — o último
passo antes do webhook de pagamento (PropostaPaga) concluir o negócio.
Regras de negócio¶
⚠️ A documentar. Esta tela ainda não tem as regras de negócio levantadas do código.
O que entra aqui: invariante (o que nunca pode acontecer), permissão (quem pode fazer o quê), bloqueio (o que impede a ação e a mensagem que o usuário vê), cálculo (fórmula e arredondamento) e efeito colateral (o que mais muda quando isso acontece).
Regra só entra aqui com origem no código — arquivo e linha. Regra que alguém "acha que é assim" é pior que seção vazia, porque vira decisão de produto baseada em memória.
Onde vive no código¶
- Front:
apps/crm-menos-juros/client/src/domains/comercial/negocios/hooks/use-acoes-card.ts(aceitar,docsOk,marcarAssinado),api/negocios-api.ts(aceitarProposta,coletarDocumentos,marcarAssinado),pages/comercial/kanban/components/AceitarPropostaDialog.tsx. - API: rotas em
/v2/comercial/propostas/contatos/:contatoId/*e/v2/mesa-analise/propostas/:propostaId/aceitar.
Relacionado¶
kanban-comercial · proposta · negocio · pipe-e-etapa · board-read-only-orientado-a-eventos · cadastrar-ccb · aguardando-documentacao · comercial
Histórico¶
- 2026-07-10: primeira ingestão, a partir do código atual (hooks + dialog).