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

[yinlianghui]

Fixes #851

按 PM 裁定的 #840/#841 口径「写实当前行为」修 automation 页 flow 表两行 ×3 语言 + opportunity-won-alert.flow.ts 的 description 串。flow 行为零改动。

前提复核：一半成立，一半被证伪

派单要求逐节点重读两条 flow 源码为据。结果如下 —— issue 的三项指控里两项成立，第三项（「不建任务」）不成立，这直接改变了 Case Escalation 那一行该怎么写。

成立 ①：赢单提醒不发给经理

src/flows/opportunity-won-alert.flow.ts 全流程 start → notify_management → end，唯一 notify 节点：

项	值
recipients	['{record.owner_id}']
channels	['inbox', 'email']

无 manager_id、无 position/team 目标。该节点 73–75 行注释自陈原因：{record.owner_id.manager} 在原始触发快照上无法穿透 lookup，会插值成字面量 undefined，消息发给幽灵用户。

编译产物复核（dist/objectstack.json）：

notify recipients :: ["{record.owner_id}"]

flow 自身 description 原文 'On closed_won opportunities over $100K: notify owner + manager.' 同错 —— 表行不是抄错，是忠实抄了 src 里同样不实的描述，两处一并写实。

成立 ②：案例升级不改派

src/flows/case-escalation.flow.ts 节点链 start → get_record → update_record → notify → end。产物复核：

escalation node types :: start -> get_record -> update_record -> notify -> end
update fields :: ["is_escalated","escalation_reason","escalated_date","status"]

update_record 不含 owner_id。第 93–96 行注释开头即 No owner reassignment:；notify 正文自己就写 "It remains assigned to you."。src/profiles/service-agent.profile.ts:33-35 独立佐证："the agent holds no transfer grant on crm_case … escalation still cannot move a case off its owner (#548; case reassignment remains the deferred half of that decision)"。

⚠️ 不成立 ③：「不建任务」—— 跟进任务是真的会建

issue 的事实节从 dist/objectstack.json 的节点表读出「无 create_record 节点 → 不建任务」。节点表看不见 hook，这一步是误归因。

flow 确实没有 create_record 节点，而且是刻意删掉的 —— src/flows/case-escalation.flow.ts:100-104 写明：

No create_task node here: the escalation write above flips status to escalated, which fires the case_status_side_effects hook — the single owner of escalation follow-up tasks … A second task node here produced duplicate, disagreeing tasks per escalation.

src/objects/case.hook.ts:136-152 的 case_status_side_effects（afterUpdate）在 status 转入 escalated 且案例挂了客户时，插入一条 crm_task：priority: 'urgent'、type: 'follow_up'、due_date = 次日、owner_id = 该客户的负责人。

test/hooks-runtime-service.test.ts:92 有一条现成的通过用例把这条链路钉死了：

✓ case_status_side_effects > creates an urgent task for the account owner on escalation

断言 task.priority === 'urgent'、task.owner_id === 'rep1'（= account.owner_id）、task.related_to_case、task.due_date === daysFromNow(1)。src/profiles/service-agent.profile.ts:26-29 与 content/docs/administration/sharing-and-security.mdx:164（"tasks only (so an escalation can hand work to the account owner)"）再次独立佐证。

结论：若照 issue 与派单细则的字面写「不建任务」，会把一句真话改成假话 —— 反而比原文更不准。所以本行的写法是：保留跟进任务，改正它归谁（客户负责人，不是资深客服），并明说不改派。这是「写实当前行为」的直接结果，不是对裁定的偏离。

另外：case-escalation.flow.ts 的 description 无需改

派单说「其 flow 文件 description 若同错一并写实」—— 逐条核过，没同错：

flow	description	判定
case_escalation	Automatically escalate high-priority cases	准确
case_escalation_on_create	Escalate cases created critical (insert-time twin of case_escalation)	准确

故 src/flows/case-escalation.flow.ts 零改动。本 PR 的 src/** 改动面只有一行 description。

改文

表行（en / zh-Hans / zh-Hant 同步）

Large Deal Won Alert / 大额商机赢单提醒 / 大額商機贏單提醒

• 前：When an opportunity over $100K turns *Closed Won*, notify the owner and their manager
• 后：When an opportunity over $100K turns *Closed Won*, notify the owner — the owner alone, not their manager
• zh-Hans：…时，通知负责人 —— 只通知负责人本人，不通知其经理
• zh-Hant：…時，通知負責人 —— 只通知負責人本人，不通知其經理

Case Escalation Process / 案例升级流程 / 案例升級流程

• 前：When a case turns *Critical*, reassign to a senior agent, notify, create a follow-up task
• 后：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
• zh-Hans：当案例变为 *Critical* 时，标记为已升级并通知其负责人 —— 不会重新分配给资深客服，案例仍归原负责人；升级同时会给客户负责人创建一条紧急跟进任务
• zh-Hant：當案例變為 *Critical* 時，標記為已升級並通知其負責人 —— 不會重新指派給資深客服，案例仍歸原負責人；升級同時會給客戶負責人建立一條緊急跟進任務

术语沿用站内既有译法（客户负责人 / 客戶負責人 = account owner，见 content/docs/administration/sharing-and-security.zh-Hans.mdx:150）；破折号沿用本表既有的 —— 写法。

description 串

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

• 前：'On closed_won opportunities over $100K: notify owner + manager.'
• 后：'On closed_won opportunities over $100K: notify the owner — the owner alone, not their manager.'

产物落位复核（pnpm build 后读 dist/objectstack.json）：

opportunity_won_alert :: "On closed_won opportunities over $100K: notify the owner — the owner alone, not their manager."
case_escalation :: "Automatically escalate high-priority cases"
case_escalation_on_create :: "Escalate cases created critical (insert-time twin of case_escalation)"

不静默删名 & #595 边界

「经理」「改派（资深客服）」「跟进任务」都是读者可能带着找来的词，三个都留在文本里，写成当前不做 / 当前归谁，而不是删掉让读者以为页面漏写了。

文本只描述今天的行为，不预判 #595（SLA policy matrix: … escalation that reassigns，尚开放的产品提案）的结论 —— 既不写「将来会改派」，也不写「永远不会」。让升级真的改派是行为变更，属 #595 的独立实现单，届时文档随之再更新。

守卫盲区（如实报，含反向验证）

test/automation-docs-coverage.test.ts 派生校验的是行集 / 触发面 / 两个数词，「它做什么」这一列是纯散文，不在派生范围内。预期改前改后全绿 —— 但比起断言，直接测了：

方向	预期	实测
改后（新散文）	20/20 绿	Test Files 1 passed (1) / Tests 20 passed (20)
把三个页面 stash 回原状（已知为假的旧散文），同一套规则重跑	仍 20/20 绿 —— 这就是盲区本身	Test Files 1 passed (1) / Tests 20 passed (20)

同一套规则在真值相反的两份散文上都给绿，盲区是测出来的而不是推出来的。本 PR 不加守卫（派单明确禁止）；这条散文列目前无自动化守卫，是已知且被接受的状态（#854 已证同一盲区）。

test/metadata-references.test.ts 未钉 flow description 原文（grep 确认全仓只有两个 flow 文件自身含这些串），故 description 改动未触红任何测试，无需同批同步。

验证

全量套件，共享锁 flock -w 7200 /tmp/os-heavy-verify.lock + NODE_OPTIONS=--max-old-space-size=4096：

步骤	退出码	关键行
pnpm validate	0	仅既有 ⚠（approval 空审批人、campaign_member 字段组），与本改动无关
pnpm typecheck	0	—
pnpm build	0	产物含新 description（见上）
pnpm test --maxWorkers=2	0	Test Files 66 passed (66) / Tests 1587 passed | 1 skipped (1588)
pnpm lint	0	13 warning(s), 14 suggestion(s)，均为既有
pnpm hygiene	0	✓ no raw control bytes in first-party files / ✓ source hygiene clean

控制字节自扫（grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]'）覆盖全部 5 个改动文件：零命中。

边界遵守

• src/** 仅 opportunity-won-alert.flow.ts 一行 description；case-escalation.flow.ts 零改动。
• 未碰同页 Email templates 节（docs(automation): 三语写实「电子邮件模板」节末句 —— 本仓不 ship 邮件模板，通知在 flow 的 notify 里 (#834) #864）、docs(automation): retire the workflow-rules section in all three locales (#833) #854 各节（blockquote / 操作顺序 / 监控列表）、zh 页 Scheduled automation 段（automation 的 zh-Hans / zh-Hant 缺了英文页「计划类自动化」节的第三段（#615 落地的预测分工说明） #836/crm_opportunity.forecast_category 的 best_case 在 zh 文档有三种写法：包里「最佳情况」，opportunities 写「最佳可能」，automation 写「最好情况」 #845）。git diff 显示三个 doc 文件各只有 ±2 行。
• 未加守卫；未动 releases/；未升级 @objectstack/*；changeset 站内路径用反引号。

顺带发现（已另立单，未在本 PR 修）

#869 —— 两条 flow 的节点 label 仍写着未发生的行为：'Notify Management'（opportunity-won-alert.flow.ts:71，实际只发负责人）、'Assign to Senior Agent'（case-escalation.flow.ts:87，实际不写 owner_id）；外加 opportunity-won-alert.flow.ts:10-12 的文件头 JSDoc 仍留着本 PR 刚从 description 改掉的那句「notify the owner and their manager」。三处都在派单边界（「除 description 外 src/** 零改动」）之外，故未动。节点 label 是随产物发布的 authored metadata，与本 PR 修的表行属同族问题；节点 id 承重（edges[] 按 id 引用），不可顺手改 —— 已在 #869 里写明。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 6, 2026 1:05am