feat(opportunity): REQ-0006 qualification, the customer calendar, narrative and approval on status change

.changeset/opportunity-qualification-and-status-approval.md

@@ -0,0 +1,43 @@
+---
+'hotcrm': minor
+---
+
+An opportunity now records **whether it is worth pursuing**, **the customer's own
+procurement calendar**, **the story behind the deal**, and **whether a won/lost call has
+been signed off**. Eighteen new fields on `crm_opportunity`, two new derived sections, a
+new list view, and a status-change approval gate that ships switched off (REQ-0006 — the
+`crm_opportunity` half of REQ-0002's steps 8 through 14).
+
+**Qualification.** *Will Bid*, *Controllability*, *Priority*, *Deal Level* and
+*Involves Subcontracting* (with a note), in their own **Qualification** section. This is
+the triage vocabulary of any seller that cannot pursue every deal, and nothing on the
+object carried it before: *Forecast Category* answers a different question — it is the
+roll-up bucket, derived from the stage — and a judgement about whether to chase a deal is
+not a forecast. The values are generic on purpose; a grading scale of your own is
+configuration on top of them.
+
+**The customer's procurement calendar.** *Customer Initiation Date*, *Expected Tender
+Date* and *Expected Signing Date*, with the amounts expected at tender and at signing.
+*Close Date* is a single date and it is **our** forecast close — it could never carry
+three distinct buyer-side events, which is what an outsourcing seller actually plans
+against. A new **Tender This Quarter** list view windows the tender date alone, so "deals
+whose tender lands this quarter" is one tab and touches the forecast close date nowhere.
+
+**Deal Narrative** — *Customer Background*, *Project Background*, *Risk Analysis* and
+*Payment Terms*, in their own section. Everything a rep wanted to write about a deal used
+to collapse into one *Description* field; split apart, each part is reviewable on its own.
+
+**Business Line**, beside *Opportunity Type* rather than inside it: type's values are a
+relationship taxonomy (new business, renewal, expansion) that reporting already reads, and
+a line-of-business classification is a different axis. Generic delivery-model values only.
+
+**Status Change Approval**, and the flow behind it. With the gate armed, declaring a deal
+*Won* or *Lost* is a **request** — the rep sets *Requested Status* with the win/loss
+reason, the request appears in the approval inbox HotCRM already mounts, and the stage
+moves only when the request is approved. Irreversible transitions are the ones worth
+gating, and the approval this app had could not see them: it keys on amount alone, so a
+$10K deal reached *Closed Won* with no sign-off at all. **The gate ships off.** Its switch
+is the field default on *Status Change Approval*, shipped as *Not Required*, so no deal is
+ever born pending, the flow's start condition is false for every record, and amount-tiered
+approval behaves exactly as it does today. An install arms the gate by changing that one
+default; deals that predate the arming are untouched.

README.md

@@ -5,7 +5,7 @@
 # HotCRM
 
 > **The reference app for AI-written enterprise software.** A complete CRM —
-> 18 objects, 30 flows, 5 dashboards, 6 AI skills, 4 languages — built as four
+> 18 objects, 31 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**, **30 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**, **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**.
 
 > **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** (30). 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** (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:
 
 | Flow | Trigger | What it does |
 | --- | --- | --- |
@@ -69,6 +69,7 @@ A flow fires one of three ways, set by its start node:
 | **Urgent Task Alert** | Record change (insert) | Notify the owner when a task is created at *Urgent* |
 | **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 |
 | **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 |
@@ -109,6 +110,8 @@ 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).
+
 ## Order of operations
 
 When a record is saved, the order is fixed:

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

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

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

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

content/docs/sales/meta.json

@@ -9,6 +9,7 @@
     "contacts",
     "buying-centre",
     "opportunities",
+    "opportunity-qualification",
     "pipeline-management",
     "forecasting",
     "quotes",

content/docs/sales/meta.zh-Hans.json

@@ -9,6 +9,7 @@
     "contacts",
     "buying-centre",
     "opportunities",
+    "opportunity-qualification",
     "pipeline-management",
     "forecasting",
     "quotes",

content/docs/sales/meta.zh-Hant.json

@@ -9,6 +9,7 @@
     "contacts",
     "buying-centre",
     "opportunities",
+    "opportunity-qualification",
     "pipeline-management",
     "forecasting",
     "quotes",