proposals

The Proposals submodule models the full lifecycle of a commercial offer: draft creation, internal approval, client delivery, and conversion into a contract. A proposal moves through a fixed status machine — draft, pending_approval, approved, rejected, cancelled, expired, contract_generated — and every state-changing action is exposed as its own endpoint (submit, send, approve, reject, cancel, convert) rather than a generic status PATCH, which keeps the audit trail and side effects (notifications, approval records) attached to an explicit business action instead of an arbitrary field write.

Internally, every proposal keeps a revision history. PATCH /proposal/:id normally updates the current revision in place, but passing create_new_revision: true forks a new revision (incrementing current_revision_number) instead of overwriting — this lets a sales rep iterate on pricing or scope after a proposal has already been sent without losing the version the client originally saw. Line items (services, products, fees, discounts, notes) and attached documents are children of a revision, not of the proposal itself, so each revision carries its own complete snapshot.

Approval is configurable rather than hardcoded: the number of approvals required before a proposal is considered fully approved is read from the crm-proposal-required-approvals setting (default 1), and each approval is recorded as a row with its own approver_user_id and status so multiple approvers can weigh in independently. Critically, POST /proposal/:id/approve is gated by a dedicated proposal-approver role rather than the general admin-crm role used by the rest of the submodule — this lets an organization designate specific people (e.g. a finance lead or department head) as approval authorities without granting them full CRM administration rights. Submit and send currently route through the same submitForApproval flow on the service, so "sending" a proposal to a client and "submitting" it for internal review are functionally identical today.

POST /proposal/:id/generate-pdf renders the current revision to HTML and then to a PDF buffer, uploads the resulting file through the platform File service (under contact/proposals/generated), and links it back to the proposal as a generated_pdf document — meaning every PDF a proposal ever produced remains retrievable through its document history, not just the latest one. Proposal documents can also originate from a manual upload, an AI-assisted extraction, or an import, distinguished by source_kind, and carry their own extraction_status for tracking OCR/parsing of uploaded source files.

POST /proposal/:id/convert requests conversion of an approved proposal into a contract; this raises an integration event that downstream listeners (such as the checkout/contract listeners wired in CrmModule) can react to, keeping the proposal-to-contract handoff decoupled from the Proposals controller itself.