docs(automation): 按 flow 源码写实内置流程表两行，并修 opportunity_won_alert 的 description (#851)

.changeset/flow-table-write-real.md

@@ -0,0 +1,50 @@
+---
+'hotcrm': patch
+---
+
+Make two rows of the Automation page's built-in flow table describe what those
+flows actually do, in all three languages, and fix the same claim inside the
+flow's own metadata description.
+
+**Large Deal Won Alert** was billed as *"notify the owner and their manager"*. It
+notifies the owner and nobody else: the flow's single `notify` node addresses
+`{record.owner_id}` on inbox + email, and there is no manager recipient anywhere
+in it — not a `manager_id`, not a position or team target. The node header in
+`src/flows/opportunity-won-alert.flow.ts` explains why the manager was dropped:
+`{record.owner_id.manager}` cannot traverse a lookup on the raw trigger snapshot,
+so it interpolates to the literal `undefined` and the message is delivered to a
+phantom user. A sales director who read the old sentence expected an alert on
+every large win and received none. The flow's own `description` carried the same
+claim (*"notify owner + manager"*) — the table had faithfully copied it — so both
+now say the owner alone, not their manager.
+
+**Case Escalation Process** was billed as *"reassign to a senior agent, notify,
+create a follow-up task"*. Measured node by node against
+`src/flows/case-escalation.flow.ts`:
+
+- **No reassignment.** The `update_record` node writes `is_escalated`,
+  `escalation_reason`, `escalated_date` and `status` — it never touches
+  `owner_id`, for the same lookup-traversal reason as above. The case stays with
+  the agent who had it, which the escalation notice already told the reader in so
+  many words: *"It remains assigned to you."* A service manager who believed
+  escalation handed the ticket to a senior agent had no reason to build the
+  manual hand-off that is actually required, and none of the three pages said so.
+- **The follow-up task is real, but it is not the flow's and it is not the
+  senior agent's.** The flow carries no `create_record` node, deliberately — the
+  escalation write flips `status` to `escalated`, which fires the
+  `case_status_side_effects` hook in `src/objects/case.hook.ts`, the single owner
+  of escalation follow-up tasks. That hook opens an **urgent** task for the
+  **account owner**, due the next day. A task node in the flow too had produced
+  duplicate, disagreeing tasks per escalation. So the row keeps the task and
+  corrects who it lands on.
+
+Both rows name the mechanisms readers arrive looking for — *manager*, *senior
+agent*, *follow-up task* — rather than deleting the words and leaving a reader to
+conclude the page simply forgot to mention them. They describe today's behaviour
+only, and take no position on whether escalation should reassign; that is an open
+product question, and a change there is a behaviour change with its own
+documentation update.
+
+Documentation plus one metadata description string. No flow behaviour, node,
+condition or recipient changed: the pages and the description now match the flows
+as they already run. Fixes #851.

content/docs/administration/automation.mdx

@@ -65,8 +65,8 @@ 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* above the threshold |
-| **Large Deal Won Alert** | Record change (update) | When an opportunity over $100K turns *Closed Won*, notify the owner and their manager |
-| **Case Escalation Process** | Record change (update) | When a case turns *Critical*, reassign to a senior agent, notify, create a follow-up task |
+| **Large Deal Won Alert** | Record change (update) | When an opportunity over $100K turns *Closed Won*, notify the owner — the owner alone, not their manager |
+| **Case Escalation Process** | Record change (update) | When a case turns *Critical*, flag it escalated and notify its owner — the case is not reassigned to a senior agent, it stays with its owner; escalating also opens an urgent follow-up task for the account owner |
 | **Case Escalation Process (on create)** | Record change (insert) | The same escalation for cases *created* at *Critical* |
 | **Case CSAT Follow-up** | Record change (update) + wait | When a case closes, wait 1 day, then prompt the owner to capture a satisfaction rating |
 | **Contract Auto-Expiration** | Schedule (daily midnight) | Expire activated contracts past their `end_date` and notify the owner |

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

@@ -65,8 +65,8 @@ description: 验证规则、流程、计划作业与审批 —— 无需你动
 | **紧急任务提醒** | 记录变更（插入） | 任务以 *Urgent* 创建时通知其负责人 |
 | **大额商机审批** | 记录变更（更新） | 通过 approval 节点分级签核 —— 销售经理 > $100K，销售总监 > $500K |
 | **大额商机审批（新建时）** | 记录变更（插入） | 同一套受理逻辑，用于*创建时*金额已超过阈值的商机 |
-| **大额商机赢单提醒** | 记录变更（更新） | 金额超过 $100K 的商机转为 *Closed Won* 时，通知负责人及其经理 |
-| **案例升级流程** | 记录变更（更新） | 当案例变为 *Critical* 时，重新分配给资深客服、通知、创建跟进任务 |
+| **大额商机赢单提醒** | 记录变更（更新） | 金额超过 $100K 的商机转为 *Closed Won* 时，通知负责人 —— 只通知负责人本人，不通知其经理 |
+| **案例升级流程** | 记录变更（更新） | 当案例变为 *Critical* 时，标记为已升级并通知其负责人 —— 不会重新分配给资深客服，案例仍归原负责人；升级同时会给客户负责人创建一条紧急跟进任务 |
 | **案例升级流程（新建时）** | 记录变更（插入） | 同一套升级逻辑，用于*创建时*就是 *Critical* 的案例 |
 | **案例满意度回访** | 记录变更（更新） + 等待 | 案例关闭后等待 1 天，再提醒负责人收集满意度评分 |
 | **合同自动到期** | 计划（每日 0 点） | 将已激活且超过 `end_date` 的合同置为到期，并通知负责人 |

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

@@ -65,8 +65,8 @@ description: 驗證規則、流程、排程作業與審批 —— 無需你動
 | **緊急任務提醒** | 記錄變更（插入） | 任務以 *Urgent* 建立時通知其負責人 |
 | **大額商機審批** | 記錄變更（更新） | 透過 approval 節點分級簽核 —— 銷售經理 > $100K，銷售總監 > $500K |
 | **大額商機審批（新建時）** | 記錄變更（插入） | 同一套受理邏輯，用於*建立時*金額已超過閾值的商機 |
-| **大額商機贏單提醒** | 記錄變更（更新） | 金額超過 $100K 的商機轉為 *Closed Won* 時，通知負責人及其經理 |
-| **案例升級流程** | 記錄變更（更新） | 當案例變為 *Critical* 時，重新指派給資深客服、通知、建立跟進任務 |
+| **大額商機贏單提醒** | 記錄變更（更新） | 金額超過 $100K 的商機轉為 *Closed Won* 時，通知負責人 —— 只通知負責人本人，不通知其經理 |
+| **案例升級流程** | 記錄變更（更新） | 當案例變為 *Critical* 時，標記為已升級並通知其負責人 —— 不會重新指派給資深客服，案例仍歸原負責人；升級同時會給客戶負責人建立一條緊急跟進任務 |
 | **案例升級流程（新建時）** | 記錄變更（插入） | 同一套升級邏輯，用於*建立時*就是 *Critical* 的案例 |
 | **案例滿意度回訪** | 記錄變更（更新） + 等待 | 案例關閉後等待 1 天，再提醒負責人收集滿意度評分 |
 | **合約自動到期** | 排程（每日 0 點） | 將已啟用且超過 `end_date` 的合約置為到期，並通知負責人 |

src/flows/opportunity-won-alert.flow.ts

@@ -18,7 +18,7 @@ type Flow = Automation.Flow;
 export const OpportunityWonAlertFlow: Flow = {
   name: 'opportunity_won_alert',
   label: 'Large Deal Won Alert',
-  description: 'On closed_won opportunities over $100K: notify owner + manager.',
+  description: 'On closed_won opportunities over $100K: notify the owner — the owner alone, not their manager.',
   type: 'record_change',
   status: 'active',
   // A record-change flow fired by a SYSTEM write carries no trigger user