proposals

O submódulo Proposals modela o ciclo de vida completo de uma oferta comercial: criação de rascunho, aprovação interna, entrega ao cliente e conversão em contrato. Uma proposta percorre uma máquina de status fixa — draft, pending_approval, approved, rejected, cancelled, expired, contract_generated — e cada ação que altera o estado é exposta como seu próprio endpoint (submit, send, approve, reject, cancel, convert), em vez de um PATCH genérico de status, o que mantém a trilha de auditoria e os efeitos colaterais (notificações, registros de aprovação) atrelados a uma ação de negócio explícita, e não a uma escrita arbitrária de campo.

Internamente, cada proposta mantém um histórico de revisões. O PATCH /proposal/:id normalmente atualiza a revisão atual no lugar, mas passar create_new_revision: true bifurca uma nova revisão (incrementando current_revision_number) em vez de sobrescrever — isso permite que um representante de vendas itere sobre preços ou escopo depois que uma proposta já foi enviada, sem perder a versão que o cliente viu originalmente. Itens de linha (serviços, produtos, taxas, descontos, notas) e documentos anexados são filhos de uma revisão, não da proposta em si, de modo que cada revisão carrega seu próprio snapshot completo.

A aprovação é configurável, e não codificada de forma fixa: o número de aprovações necessárias antes de uma proposta ser considerada totalmente aprovada é lido da configuração crm-proposal-required-approvals (padrão 1), e cada aprovação é registrada como uma linha com seu próprio approver_user_id e status, de modo que múltiplos aprovadores possam se manifestar de forma independente. De maneira crítica, o POST /proposal/:id/approve é restrito por uma role dedicada proposal-approver, e não pela role geral admin-crm usada pelo restante do submódulo — isso permite que uma organização designe pessoas específicas (por exemplo, um líder financeiro ou chefe de departamento) como autoridades de aprovação sem lhes conceder direitos completos de administração do CRM. Submit e send atualmente passam pelo mesmo fluxo submitForApproval no serviço, de modo que "enviar" uma proposta a um cliente e "submetê-la" para revisão interna são funcionalmente idênticos hoje.

O POST /proposal/:id/generate-pdf renderiza a revisão atual em HTML e então em um buffer PDF, faz upload do arquivo resultante através do serviço File da plataforma (sob contact/proposals/generated) e o vincula de volta à proposta como um documento generated_pdf — o que significa que cada PDF que uma proposta já produziu permanece recuperável através de seu histórico de documentos, não apenas o mais recente. Documentos de proposta também podem se originar de um upload manual, de uma extração assistida por IA ou de uma importação, distinguidos por source_kind, e carregam seu próprio extraction_status para rastrear OCR/parsing de arquivos de origem enviados.

O POST /proposal/:id/convert solicita a conversão de uma proposta aprovada em um contrato; isso dispara um evento de integração ao qual listeners downstream (como os listeners de checkout/contrato conectados no CrmModule) podem reagir, mantendo o handoff de proposta para contrato desacoplado do próprio controller de Proposals.