fix(quote_generation): refuse Generate Quote before qualification approval instead of leaving an orphan quote

.changeset/2032-quote-before-qualification.md

@@ -0,0 +1,5 @@
+---
+'hotcrm': patch
+---
+
+Where qualification approval (立项) is turned on, Generate Quote on a deal that is not yet approved now tells you qualification approval comes first and creates nothing, instead of reporting a failure and leaving a draft quote behind.

content/docs/administration/state-machines.mdx

@@ -80,7 +80,7 @@ There are **two** closed stages, not three: *Closed Won* and *Closed Lost*. Ther
 | Closed Won | — | Terminal |
 | Closed Lost | — | Terminal |
 
-Two of those edges exist for the CPQ path rather than for a rep clicking through stages: *→ Proposal* is legal from every pre-proposal stage because the `quote_generation` flow fast-forwards the deal to *Proposal* the moment a quote is generated, which can happen at any open stage; and *Proposal → Closed Won* is legal because the `quote_on_accepted` hook wins the linked deal straight from an accepted quote, with no separate negotiation step.
+Two of those edges exist for the CPQ path rather than for a rep clicking through stages: *→ Proposal* is legal from every pre-proposal stage because the `quote_generation` flow fast-forwards the deal to *Proposal* the moment a quote is generated, which can happen at any open stage — though where your organisation requires qualification approval (立项), not before the deal is approved ([Opportunity Qualification](/docs/sales/opportunity-qualification#qualification-approval)); and *Proposal → Closed Won* is legal because the `quote_on_accepted` hook wins the linked deal straight from an accepted quote, with no separate negotiation step.
 
 **Not in the table**: moving **backwards**. No open stage declares an edge to an earlier one, so *Negotiation* back to *Proposal* — a deal slipping — is outside the route and logs a warning like any other departure (it still saves, per the note above). Neither closed stage declares an edge either, so there is no reopen transition and no admin path back to an open stage.
 

content/docs/administration/state-machines.zh-Hans.mdx

@@ -80,7 +80,7 @@ Prospecting / Qualification / Needs Analysis / Proposal / Negotiation ──▶
 | Closed Won | — | 终态 |
 | Closed Lost | — | 终态 |
 
-其中两条边是为 CPQ 路径存在的，不是给销售一个阶段一个阶段点出来的：*→ Proposal* 从每一个 Proposal 之前的阶段都合法，因为 `quote_generation` 流程一旦生成报价就把交易快进到 *Proposal*，而生成报价在任何开放阶段都可能发生；*Proposal → Closed Won* 合法，则是因为 `quote_on_accepted` 钩子会从一份被接受的报价上直接赢下关联交易，中间不再经过一次谈判。
+其中两条边是为 CPQ 路径存在的，不是给销售一个阶段一个阶段点出来的：*→ Proposal* 从每一个 Proposal 之前的阶段都合法，因为 `quote_generation` 流程一旦生成报价就把交易快进到 *Proposal*，而生成报价在任何开放阶段都可能发生——不过如果你们的组织要求立项，交易在立项通过之前不能生成报价（[商机资格评估](/zh-Hans/docs/sales/opportunity-qualification#qualification-approval)）；*Proposal → Closed Won* 合法，则是因为 `quote_on_accepted` 钩子会从一份被接受的报价上直接赢下关联交易，中间不再经过一次谈判。
 
 **表里没有的**：**向后** 移动。没有任何一个开放阶段声明了通往更早阶段的边，所以从 *Negotiation* 退回 *Proposal* —— 交易滑落 —— 是走出了这条路线，和其他任何一次出格一样只记一条警告（照样保存，见上文）。两个已关闭阶段也都没有出边，所以既不存在「重新打开」这条转换，也不存在管理员绕回开放阶段的通道。
 

content/docs/administration/state-machines.zh-Hant.mdx

@@ -82,7 +82,7 @@ Prospecting / Qualification / Needs Analysis / Proposal / Negotiation ──▶
 | Closed Won | — | 終態 |
 | Closed Lost | — | 終態 |
 
-其中兩條邊是為 CPQ 路徑存在的，不是給業務一個階段一個階段點出來的：*→ Proposal* 從每一個 Proposal 之前的階段都合法，因為 `quote_generation` 流程一旦產生報價就把交易快進到 *Proposal*，而產生報價在任何開放階段都可能發生；*Proposal → Closed Won* 合法，則是因為 `quote_on_accepted` 鉤子會從一份被接受的報價上直接贏下關聯交易，中間不再經過一次談判。
+其中兩條邊是為 CPQ 路徑存在的，不是給業務一個階段一個階段點出來的：*→ Proposal* 從每一個 Proposal 之前的階段都合法，因為 `quote_generation` 流程一旦產生報價就把交易快進到 *Proposal*，而產生報價在任何開放階段都可能發生——不過如果你們的組織要求立項，交易在立項通過之前不能產生報價（[商機資格評估](/zh-Hant/docs/sales/opportunity-qualification#qualification-approval)）；*Proposal → Closed Won* 合法，則是因為 `quote_on_accepted` 鉤子會從一份被接受的報價上直接贏下關聯交易，中間不再經過一次談判。
 
 **表裡沒有的**：**向後** 移動。沒有任何一個開放階段宣告了通往更早階段的邊，所以從 *Negotiation* 退回 *Proposal* —— 交易滑落 —— 是走出了這條路線，和其他任何一次出格一樣只記一條警告（照樣儲存，見上文）。兩個已關閉階段也都沒有出邊，所以既不存在「重新開啟」這條轉換，也不存在管理員繞回開放階段的通道。
 

content/docs/sales/opportunity-qualification.mdx

@@ -53,13 +53,13 @@ Attachments still go on the record's files, as they always have.
 
 ## Qualification approval
 
-Some organisations approve a deal as a project — 立项 — before anyone commits to it. Until that approval, a new deal can be **worked**: log calls and meetings, write the narrative, record the customer's calendar, the amount and **Will Bid**. What waits is **committing** it: moving its stage and the won/lost call — whether that is closing it directly or asking for it with **Requested Status**. **Will Bid** stays open on purpose: whether you intend to bid is part of what the approver decides on, so record it before you ask. The **Qualification Approval** field records where that stands:
+Some organisations approve a deal as a project — 立项 — before anyone commits to it. Until that approval, a new deal can be **worked**: log calls and meetings, write the narrative, record the customer's calendar, the amount and **Will Bid**. What waits is **committing** it: moving its stage and the won/lost call — whether that is closing it directly or asking for it with **Requested Status**. Quoting waits too: while the deal is *Pending* or *Rejected*, **Generate Quote** creates nothing (see [Quotes](/docs/sales/quotes#generating-a-quote)). **Will Bid** stays open on purpose: whether you intend to bid is part of what the approver decides on, so record it before you ask. The **Qualification Approval** field records where that stands:
 
 | Qualification Approval | What it means |
 | --- | --- |
 | **Not Required** | No qualification approval is asked for. This is how HotCRM ships, and it is what every deal shows unless your admin has turned the gate on. |
 | **Pending** | The gate is on for this deal and it has not been approved yet. |
-| **Approved** | The deal is qualified. Its stage and won/lost call are open from now on. |
+| **Approved** | The deal is qualified. Its stage, its won/lost call and **Generate Quote** are open from now on. |
 | **Rejected** | The approver said no to the last request. The deal stays held. |
 
 You never set this field yourself — it is filled in by the approval, and it is read-only.

content/docs/sales/opportunity-qualification.zh-Hans.mdx

@@ -53,13 +53,13 @@ description: 这笔交易值不值得跟、客户自己的采购日程、写下
 
 ## 立项审批 [#qualification-approval]
 
-有些组织要先对一笔交易立项、批准之后，才愿意为它投入。立项通过之前，新商机照样可以**跟进**：记录电话和拜访、撰写商机叙述、登记客户的日程、金额和**是否投标**。要等审批的是**推进**它的那两步：变更阶段，以及赢单或丢单——不论是直接关单，还是通过**申请变更状态**去申请。**是否投标**有意不被挡住：你打不打算投标，本身就是审批人据以决定的内容之一，所以要在申请之前填好。商机上的**立项审批**字段记录这件事走到哪一步：
+有些组织要先对一笔交易立项、批准之后，才愿意为它投入。立项通过之前，新商机照样可以**跟进**：记录电话和拜访、撰写商机叙述、登记客户的日程、金额和**是否投标**。要等审批的是**推进**它的那两步：变更阶段，以及赢单或丢单——不论是直接关单，还是通过**申请变更状态**去申请。报价也要等：交易处在*审批中*或*已驳回*时，**生成报价单**什么都不会创建（见[报价](/zh-Hans/docs/sales/quotes#generating-a-quote)）。**是否投标**有意不被挡住：你打不打算投标，本身就是审批人据以决定的内容之一，所以要在申请之前填好。商机上的**立项审批**字段记录这件事走到哪一步：
 
 | 立项审批 | 含义 |
 | --- | --- |
 | **无需审批** | 不要求立项审批。这是 HotCRM 的出厂状态，除非管理员打开了闸门，否则每笔交易都是这个值。 |
 | **审批中** | 这笔交易的闸门是开着的，还没有通过立项。 |
-| **已批准** | 立项已通过。从此可以变更阶段、赢单或丢单。 |
+| **已批准** | 立项已通过。从此可以变更阶段、赢单或丢单，也可以用**生成报价单**报价。 |
 | **已驳回** | 审批人否决了上一次申请。交易仍然被挡着。 |
 
 这个字段不由你填写——它由审批流程写入，是只读的。

content/docs/sales/opportunity-qualification.zh-Hant.mdx

@@ -55,13 +55,13 @@ description: 這筆交易值不值得跟、客戶自己的採購日程、寫下
 
 ## 立項審批 [#qualification-approval]
 
-有些組織要先對一筆交易立項、批准之後，才願意為它投入。立項通過之前，新商機照樣可以**跟進**：記錄電話和拜訪、撰寫商機敘述、登記客戶的日程、金額和**是否投標**。要等審批的是**推進**它的那兩步：變更階段，以及贏單或丟單——不論是直接關單，還是透過**申請變更狀態**去申請。**是否投標**有意不被擋住：你打不打算投標，本身就是審批人據以決定的內容之一，所以要在申請之前填好。商機上的**立項審批**欄位記錄這件事走到哪一步：
+有些組織要先對一筆交易立項、批准之後，才願意為它投入。立項通過之前，新商機照樣可以**跟進**：記錄電話和拜訪、撰寫商機敘述、登記客戶的日程、金額和**是否投標**。要等審批的是**推進**它的那兩步：變更階段，以及贏單或丟單——不論是直接關單，還是透過**申請變更狀態**去申請。報價也要等：交易處在*審批中*或*已駁回*時，**生成報價單**什麼都不會建立（見[報價](/zh-Hant/docs/sales/quotes#generating-a-quote)）。**是否投標**有意不被擋住：你打不打算投標，本身就是審批人據以決定的內容之一，所以要在申請之前填好。商機上的**立項審批**欄位記錄這件事走到哪一步：
 
 | 立項審批 | 含義 |
 | --- | --- |
 | **無需審批** | 不要求立項審批。這是 HotCRM 的出廠狀態，除非管理員打開了閘門，否則每筆交易都是這個值。 |
 | **審批中** | 這筆交易的閘門是開著的，還沒有通過立項。 |
-| **已批准** | 立項已通過。從此可以變更階段、贏單或丟單。 |
+| **已批准** | 立項已通過。從此可以變更階段、贏單或丟單，也可以用**生成報價單**報價。 |
 | **已駁回** | 審批人否決了上一次申請。交易仍然被擋著。 |
 
 這個欄位不由你填寫——它由審批流程寫入，是唯讀的。

content/docs/sales/quotes.mdx

@@ -93,6 +93,8 @@ You don't manually create quotes — instead, open an opportunity that is still
 - Valid for (days) — default 30
 - Discount % — default 0; the label shows the 60% ceiling
 
+**If your organisation requires qualification approval (立项) for new deals, a deal is quoted only once it is approved.** While the deal's **Qualification Approval** is *Pending* or *Rejected*, **Generate Quote** opens no form: you are told that qualification approval comes first, and nothing is created. Tick **Request Qualification Approval** on the deal; once it is approved, the button works as described here. Out of the box this gate is off — every deal reads *Not Required* — and none of this applies (see [Opportunity Qualification](/docs/sales/opportunity-qualification#qualification-approval)).
+
 When you submit it, the system:
 
 1. Creates the quote in **Draft** status with the opportunity's amount as the subtotal. The quote takes the opportunity's account and primary contact, makes you its owner, is dated today, expires the number of days you entered from today, and has payment terms of Net 30. The opportunity's products are not copied: the quote starts with no line items.

content/docs/sales/quotes.zh-Hans.mdx

@@ -90,6 +90,8 @@ Total Price    = Subtotal − Discount + Tax + Shipping & Handling
 - 有效期（天）——默认 30
 - 折扣 %——默认 0；标签上标明了 60% 的上限
 
+**如果你们的组织要求新商机先立项，一笔交易要等立项通过之后才能报价。** 只要交易的**立项审批**是*审批中*或*已驳回*，点击**生成报价单**就不会弹出表单：系统会告诉你需要先通过立项审批，并且什么都不会创建。在交易上勾选**申请立项审批**；获批之后，这个按钮就按本节描述的方式工作。出厂状态下这道闸门是关着的——每笔交易都显示*无需审批*——以上都不适用（见[商机资格评估](/zh-Hans/docs/sales/opportunity-qualification#qualification-approval)）。
+
 提交表单后，系统会：
 
 1. 以**草稿**状态创建报价，并将商机的金额作为小计。报价沿用商机的客户和主要联系人，负责人是你，报价日期为今天，到期日期为今天起算你填写的天数，付款条款为 Net 30。商机上的产品不会被复制过来：报价创建时没有任何行项目。

content/docs/sales/quotes.zh-Hant.mdx

@@ -92,6 +92,8 @@ Total Price    = Subtotal − Discount + Tax + Shipping & Handling
 - 有效期（天）——預設 30
 - 折扣 %——預設 0；標籤上標明了 60% 的上限
 
+**如果你們的組織要求新商機先立項，一筆交易要等立項通過之後才能報價。** 只要交易的**立項審批**是*審批中*或*已駁回*，點擊**生成報價單**就不會彈出表單：系統會告訴你需要先通過立項審批，並且什麼都不會建立。在交易上勾選**申請立項審批**；獲批之後，這個按鈕就按本節描述的方式運作。出廠狀態下這道閘門是關著的——每筆交易都顯示*無需審批*——以上都不適用（見[商機資格評估](/zh-Hant/docs/sales/opportunity-qualification#qualification-approval)）。
+
 提交表單後，系統會：
 
 1. 以**草稿**狀態建立報價，並將商機的金額作為小計。報價沿用商機的客戶和主要聯絡人，負責人是你，報價日期為今天，到期日期為今天起算你填寫的天數，付款條款為 Net 30。商機上的產品不會被複製過來：報價建立時沒有任何行項目。