feat(opportunity): the 立项 (qualification) approval gate, off by default (REQ-0006 step 11)

.changeset/1995-qualification-approval-gate.md

@@ -0,0 +1,29 @@
+---
+'hotcrm': minor
+---
+
+An opportunity can now require **qualification approval (立项)** before it is committed:
+until the deal is approved, its stage cannot move, *Will Bid* cannot be recorded, and it
+can be neither closed won/lost nor asked to be. Everything else stays open, so a new deal
+can still be worked while it waits. **The gate ships off** (REQ-0006 step 11:
+「销售立项需走审批流程；新增商机可跟进，立项通过后方可更新阶段、投标、赢丢单操作。」).
+
+**How it works, once armed.** The rep ticks *Request Qualification Approval* in the deal's
+**Qualification** section, and one request appears in the approval inbox HotCRM already
+mounts, routed to the `sales_manager` position. Approved, the deal is qualified for good.
+Rejected, the box is unticked and the deal stays held; ticking it again asks again. The
+verdict lands on a new read-only field, *Qualification Approval*, and a refused move is
+answered `409 RECORD_LOCKED` with a sentence naming what was held and the way forward.
+Unlike the status-change gate, the deal is **not** locked while the request waits — that
+is the customer's own 「新增商机可跟进」.
+
+**Off by default, bit for bit.** The switch is the field default on *Qualification
+Approval*, shipped as *Not Required*: no deal is ever born pending, the new flow
+(*Opportunity Qualification Approval*) opens nothing, and moving the stage, *Will Bid* and
+closing behave exactly as before. An install arms the gate by changing that one default
+to *Pending*; deals that already exist keep *Not Required*.
+
+**With the status-change gate armed too, qualification comes first.** A deal that is not
+yet qualified cannot raise a won/lost request either; once it is qualified, the
+status-change gate behaves exactly as it does alone. Each gate keeps its own verdict
+field, and the amount-based *Large Deal Approval* is unchanged.

README.md

@@ -5,7 +5,7 @@
 # HotCRM
 
 > **The reference app for AI-written enterprise software.** A complete CRM —
-> 18 objects, 31 flows, 5 dashboards, 6 AI skills, 4 languages — built as four
+> 18 objects, 32 flows, 5 dashboards, 6 AI skills, 4 languages — built as four
 > packages (sales, service, revenue, marketing) that compile to one artifact.
 > The **sales package**, the one a customer installs, carries its whole
 > business semantics (objects, flows, actions, hooks) in **~54k tokens**
@@ -69,7 +69,7 @@ HotCRM is a complete, opinionated CRM built as the **first official application*
 | `crm_event` | | | |
 | `crm_event_attendee` | | | |
 
-Plus **6 AI skills** (a skills-only surface — HotCRM defines no agents of its own; the skills attach to the platform `ask` assistant), **5 dashboards**, **31 flows**, **31 actions**, **9 datasets**, **4 language bundles** (en, zh-CN, es-ES, ja-JP), **6 permission profiles**, **12 positions**, and **9 sharing rules**.
+Plus **6 AI skills** (a skills-only surface — HotCRM defines no agents of its own; the skills attach to the platform `ask` assistant), **5 dashboards**, **32 flows**, **31 actions**, **9 datasets**, **4 language bundles** (en, zh-CN, es-ES, ja-JP), **6 permission profiles**, **12 positions**, and **9 sharing rules**.
 
 > **Business reader?** The ObjectStack docs tour every one of these capabilities in plain business language — [What Can It Do?](https://objectstack.ai/docs/capabilities) — with HotCRM as the running example on every page.
 

content/docs/administration/automation.mdx

@@ -50,7 +50,7 @@ A flow fires one of three ways, set by its start node:
 
 > **Auto-launch needs the `triggers` capability.** Record-change and scheduled flows only fire when the stack's `requires` list includes `triggers` — it installs the record-change + schedule trigger providers (schedule triggers also use the job service). Screen flows are always launched manually.
 
-**Built-in flows in HotCRM** (31). Each row carries the flow's own label — the name listed in **Studio → Automation → Flows**, and the name you pick from in **Studio → Developer → Flow Runs**, so a run you are chasing can be looked up here verbatim:
+**Built-in flows in HotCRM** (32). Each row carries the flow's own label — the name listed in **Studio → Automation → Flows**, and the name you pick from in **Studio → Developer → Flow Runs**, so a run you are chasing can be looked up here verbatim:
 
 | Flow | Trigger | What it does |
 | --- | --- | --- |
@@ -70,6 +70,7 @@ A flow fires one of three ways, set by its start node:
 | **Large Deal Approval** | Record change (update) | Tiered sign-off via approval nodes — Sales Manager ≥ $100K, Sales Director > $500K |
 | **Large Deal Approval (on create)** | Record change (insert) | The same intake for opportunities *created* at or above the threshold |
 | **Opportunity Status Change Approval** | Record change (update) | Sign-off a deal needs before it is declared won or lost. Ships switched OFF — it opens nothing until an install arms the gate on the opportunity's **Status Change Approval** field; armed, the rep sets **Requested Status** and the stage moves only when the request is approved |
+| **Opportunity Qualification Approval** | Record change (update) | The qualification (立项) sign-off a new deal needs before its stage, its bid decision or its won/lost call may change. Ships switched OFF — it opens nothing until an install arms the gate on the opportunity's **Qualification Approval** field; armed, the rep ticks **Request Qualification Approval**, and everything else on the deal stays editable while it waits |
 | **Lead Conversion Approval** | Record change (insert) | Sign-off a lead needs before it can be converted. Ships switched OFF — it opens nothing until an install arms the gate on the lead's **Conversion Approval** field |
 | **Account Approval** | Record change (insert) | Sign-off a newly created account needs before it counts as established data. Ships switched **ON** — a new account starts *Pending* and is decided in the approval inbox; an install that wants no account sign-off changes the default on the account's **Approval Status** field |
 | **Large Deal Won Alert** | Record change (update) | When an opportunity of $100K or more turns *Closed Won*, notify the owner — the owner alone, not their manager |
@@ -110,7 +111,7 @@ Since ObjectStack 7.4, approvals are modeled as **`approval` nodes inside a flow
 
 HotCRM's built-in **Opportunity Approval** flow chains two approval nodes for tiered sign-off (manager → director). See [Revenue › Approvals](/docs/revenue/approvals) for thresholds, what approvers see, and the audit trail.
 
-A second, independent gate — **Opportunity Status Change Approval** — asks for sign-off before a deal is declared won or lost. It ships switched off and keeps its verdict in its own field, so arming it never changes the amount-based sign-off; see [Sales › Opportunity Qualification](/docs/sales/opportunity-qualification).
+A second, independent gate — **Opportunity Status Change Approval** — asks for sign-off before a deal is declared won or lost. It ships switched off and keeps its verdict in its own field, so arming it never changes the amount-based sign-off. A third, **Opportunity Qualification Approval**, is the qualification (立项) sign-off a new deal needs before its stage, bid decision or won/lost call may change; it too ships off, and with both armed it comes first. See [Sales › Opportunity Qualification](/docs/sales/opportunity-qualification).
 
 ## Order of operations
 

content/docs/administration/automation.zh-Hans.mdx

@@ -50,7 +50,7 @@ description: 验证规则、流程、计划作业与审批 —— 无需你动
 
 > **自动触发需要 `triggers` 能力。** 记录变更与计划类流程，只有当 stack 的 `requires` 列表包含 `triggers` 时才会触发 —— 它会安装记录变更与计划触发器提供方（计划触发器还依赖 job 服务）。屏幕类流程始终为手动启动。
 
-**HotCRM 中的内置流程**（31 个）。每一行用的都是流程自身的标签 —— 也就是 **Studio → 自动化 → 流程** 里列出、并在 **Studio → 开发者 → 流程运行记录** 里供你挑选的那个名字，因此一次运行可以逐字回到这张表里查：
+**HotCRM 中的内置流程**（32 个）。每一行用的都是流程自身的标签 —— 也就是 **Studio → 自动化 → 流程** 里列出、并在 **Studio → 开发者 → 流程运行记录** 里供你挑选的那个名字，因此一次运行可以逐字回到这张表里查：
 
 | 流程 | 触发 | 它做什么 |
 | --- | --- | --- |
@@ -70,6 +70,7 @@ description: 验证规则、流程、计划作业与审批 —— 无需你动
 | **大额商机审批** | 记录变更（更新） | 通过 approval 节点分级签核 —— 销售经理 ≥ $100K，销售总监 > $500K |
 | **大额商机审批（新建时）** | 记录变更（插入） | 同一套受理逻辑，用于*创建时*金额已达到阈值的商机 |
 | **商机状态变更审批** | 记录变更（更新） | 商机宣布赢单或丢单之前需要的签核。出厂默认是**关闭**的：在商机的**状态变更审批**字段上打开闸门之前，它不会发起任何审批；打开之后，销售填写**申请变更状态**，请求获批后阶段才会变更 |
+| **商机立项审批** | 记录变更（更新） | 新建商机在更新阶段、决定是否投标或赢丢单之前需要的立项签核。出厂默认是**关闭**的：在商机的**立项审批**字段上打开闸门之前，它不会发起任何审批；打开之后，销售勾选**申请立项审批**，等待审批期间商机的其他内容照常可以编辑 |
 | **线索转化审批** | 记录变更（插入） | 线索转化前需要的签核。出厂默认是**关闭**的：在线索的**转化审批**字段上打开闸门之前，它不会发起任何审批 |
 | **客户审批** | 记录变更（插入） | 新建客户在成为正式数据之前需要的签核。出厂默认是**打开**的：新客户以**待审批**状态创建，并在审批收件箱中裁定；不需要客户签核的安装，改掉客户**审批状态**字段的默认值即可 |
 | **大额商机赢单提醒** | 记录变更（更新） | 金额 $100K 及以上的商机转为 *Closed Won* 时，通知负责人 —— 只通知负责人本人，不通知其经理 |
@@ -110,7 +111,7 @@ description: 验证规则、流程、计划作业与审批 —— 无需你动
 
 HotCRM 内置的 **商机审批** 流程串联两个 approval 节点实现分级签核（经理 → 总监）。关于阈值、审批人所见以及审计轨迹，参见 [营收云 › 审批](/zh-Hans/docs/revenue/approvals)。
 
-另有一道独立的闸门 —— **商机状态变更审批** —— 在商机宣布赢单或丢单之前要求签核。它出厂默认关闭，并把结论记在自己的字段里，因此打开它不会改变按金额分级的签核；参见[销售云 › 商机资格评估](/zh-Hans/docs/sales/opportunity-qualification)。
+另有一道独立的闸门 —— **商机状态变更审批** —— 在商机宣布赢单或丢单之前要求签核。它出厂默认关闭，并把结论记在自己的字段里，因此打开它不会改变按金额分级的签核。第三道 —— **商机立项审批** —— 是新建商机在更新阶段、决定是否投标或赢丢单之前需要的立项签核；它同样出厂关闭，两道都打开时它排在前面。参见[销售云 › 商机资格评估](/zh-Hans/docs/sales/opportunity-qualification)。
 
 ## 操作顺序
 

content/docs/administration/automation.zh-Hant.mdx

@@ -52,7 +52,7 @@ description: 驗證規則、流程、排程作業與審批 —— 無需你動
 
 > **自動觸發需要 `triggers` 能力。** 記錄變更與排程類流程，只有當 stack 的 `requires` 列表包含 `triggers` 時才會觸發 —— 它會安裝記錄變更與排程觸發器提供方（排程觸發器還依賴 job 服務）。螢幕類流程始終為手動啟動。
 
-**HotCRM 中的內建流程**（31 個）。每一行用的都是流程自身的標籤 —— 也就是 **Studio → Automation → Flows** 裡列出、並在 **Studio → Developer → Flow Runs** 裡供你挑選的那個名字，因此一次執行可以逐字回到這張表裡查：
+**HotCRM 中的內建流程**（32 個）。每一行用的都是流程自身的標籤 —— 也就是 **Studio → Automation → Flows** 裡列出、並在 **Studio → Developer → Flow Runs** 裡供你挑選的那個名字，因此一次執行可以逐字回到這張表裡查：
 
 | 流程 | 觸發 | 它做什麼 |
 | --- | --- | --- |
@@ -72,6 +72,7 @@ description: 驗證規則、流程、排程作業與審批 —— 無需你動
 | **大額商機審批** | 記錄變更（更新） | 透過 approval 節點分級簽核 —— 銷售經理 ≥ $100K，銷售總監 > $500K |
 | **大額商機審批（新建時）** | 記錄變更（插入） | 同一套受理邏輯，用於*建立時*金額已達到閾值的商機 |
 | **商機狀態變更審批** | 記錄變更（更新） | 商機宣布贏單或丟單之前需要的簽核。出廠預設是**關閉**的：在商機的**狀態變更審批**欄位上打開閘門之前，它不會發起任何審批；打開之後，銷售填寫**申請變更狀態**，請求獲批後階段才會變更 |
+| **商機立項審批** | 記錄變更（更新） | 新建商機在更新階段、決定是否投標或贏丟單之前需要的立項簽核。出廠預設是**關閉**的：在商機的**立項審批**欄位上打開閘門之前，它不會發起任何審批；打開之後，銷售勾選**申請立項審批**，等待審批期間商機的其他內容照常可以編輯 |
 | **線索轉化審批** | 記錄變更（插入） | 線索轉化前需要的簽核。出廠預設是**關閉**的：在線索的**轉化審批**欄位上打開閘門之前，它不會發起任何審批 |
 | **客戶審批** | 記錄變更（插入） | 新建客戶在成為正式資料之前需要的簽核。出廠預設是**打開**的：新客戶以**待審批**狀態建立，並在審批收件匣中裁定；不需要客戶簽核的安裝，改掉客戶**審批狀態**欄位的預設值即可 |
 | **大額商機贏單提醒** | 記錄變更（更新） | 金額 $100K 及以上的商機轉為 *Closed Won* 時，通知負責人 —— 只通知負責人本人，不通知其經理 |
@@ -112,7 +113,7 @@ description: 驗證規則、流程、排程作業與審批 —— 無需你動
 
 HotCRM 內建的 **商機審批** 流程串聯兩個 approval 節點實作分級簽核（經理 → 總監）。關於閾值、審批人所見以及稽核軌跡，參見 [營收雲 › 審批](/zh-Hant/docs/revenue/approvals)。
 
-另有一道獨立的閘門 —— **商機狀態變更審批** —— 在商機宣布贏單或丟單之前要求簽核。它出廠預設關閉，並把結論記在自己的欄位裡，因此打開它不會改變按金額分級的簽核；參見[銷售雲 › 商機資格評估](/zh-Hant/docs/sales/opportunity-qualification)。
+另有一道獨立的閘門 —— **商機狀態變更審批** —— 在商機宣布贏單或丟單之前要求簽核。它出廠預設關閉，並把結論記在自己的欄位裡，因此打開它不會改變按金額分級的簽核。第三道 —— **商機立項審批** —— 是新建商機在更新階段、決定是否投標或贏丟單之前需要的立項簽核；它同樣出廠關閉，兩道都打開時它排在前面。參見[銷售雲 › 商機資格評估](/zh-Hant/docs/sales/opportunity-qualification)。
 
 ## 操作順序
 

content/docs/sales/opportunities.mdx

@@ -56,7 +56,7 @@ The nine names below are `crm_opportunity`'s **field groups** (`fieldGroups` in
 | **Basic Information** | Opportunity Owner, Opportunity Name, Account, Primary Contact |
 | **Financials** | Amount, Expected Revenue |
 | **Sales Process** | Stage, Probability (%), Close Date, Stage Entry Date, Customer Initiation Date, Expected Tender Date, Expected Signing Date, Expected Tender Amount, Expected Signing Amount, Approval Status, Approved Date, Requested Status, Status Change Approval |
-| **Qualification** | Will Bid, Controllability, Priority, Deal Level, Involves Subcontracting, Subcontracting Note |
+| **Qualification** | Will Bid, Controllability, Priority, Deal Level, Involves Subcontracting, Subcontracting Note, Request Qualification Approval, Qualification Approval |
 | **Deal Narrative** | Customer Background, Project Background, Risk Analysis, Payment Terms |
 | **Classification** | Opportunity Type, Business Line, Lead Source, Win Reason, Loss Reason, Loss/Win Details |
 | **Campaigns** *(collapsed by default)* | Campaign |

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

@@ -56,7 +56,7 @@ description: 活跃的销售交易——销售管道的核心，包含 7 个阶
 | **基本信息** | 商机负责人、商机名称、所属客户、主要联系人 |
 | **财务** | 金额、预期收入 |
 | **销售流程** | 阶段、成交概率 (%)、预计成交日期、进入当前阶段日期、客户立项日期、预计招标日期、预计签约日期、预计招标金额、预计签约金额、审批状态、批准时间、申请变更状态、状态变更审批 |
-| **资格评估** | 是否投标、可控性、优先级、商机级别、涉及分包、分包说明 |
+| **资格评估** | 是否投标、可控性、优先级、商机级别、涉及分包、分包说明、申请立项审批、立项审批 |
 | **商机叙述** | 客户简介、项目背景、风险分析、付款条款 |
 | **分类** | 类型、业务线、线索来源、赢单原因、丢单原因、赢/丢单详情 |
 | **营销活动** *(默认折叠)* | 营销活动 |

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

@@ -58,7 +58,7 @@ description: 活躍的銷售交易——銷售管道的核心，包含 7 個階
 | **基本資訊** | 商機負責人、商機名稱、所屬客戶、主要聯絡人 |
 | **財務** | 金額、預期收入 |
 | **銷售流程** | 階段、成交機率 (%)、預計成交日期、進入當前階段日期、客戶立項日期、預計招標日期、預計簽約日期、預計招標金額、預計簽約金額、審批狀態、批准時間、申請變更狀態、狀態變更審批 |
-| **資格評估** | 是否投標、可控性、優先級、商機級別、涉及分包、分包說明 |
+| **資格評估** | 是否投標、可控性、優先級、商機級別、涉及分包、分包說明、申請立項審批、立項審批 |
 | **商機敘述** | 客戶簡介、專案背景、風險分析、付款條款 |
 | **分類** | 類型、業務線、潛在客戶來源、贏單原因、丟單原因、贏/丟單詳情 |
 | **行銷活動** *(預設摺疊)* | 行銷活動 |