docs(service): write the cases and state-machine pages' remaining claims to source (#912, #920, #925, #926)

[yinlianghui]

Fixes #912
Fixes #920
Fixes #925
Fixes #926

四单并单，收口 service/cases 与 administration/state-machines 两页余下的失实说法，外加 whats-new / guides/integrations 两个卫星点。三语同步，src/ 零改动。

零、stale-premise 复核（先证后改）

四单的行号基线早于 PR #919 / #922 / #924，全部在 fresh origin/main（4855d50b）重定位；每处改动前逐条回源码复核。

#920 的引擎侧机制（一次性探针，跑完即删，未留在仓库里）。探针直接调 evaluateValidationRules，即 @objectstack/objectql/dist/core.mjs:2425-2443 那条路径：violation 只有 severity === 'error' 才进 errors 数组并 throw，其余走 logger.warn。

crm_case.status — rule 'case_status_progression'
  declared severity : warning
  declares initialStates? : no
  transitions[new] : [in_progress, waiting_customer, escalated, closed]
  probe (update): new -> resolved  (outside the table? true)
  ILLEGAL verdict   : NOT BLOCKED (save proceeds)
  engine log lines  :
      Validation rule 'case_status_progression' (warning): Invalid status transition

crm_lead.status — rule 'lead_status_progression'
  probe (update): converted -> contacted  (outside the table? true)
  ILLEGAL verdict   : NOT BLOCKED (save proceeds)
  engine log lines  :
      Validation rule 'lead_status_progression' (warning): Invalid lead status transition

crm_case.status — probe (insert): closed
  ILLEGAL verdict   : NOT BLOCKED (save proceeds)
  engine log lines  : (none)

crm_case.status — probe (update): new -> in_progress  (outside the table? false)   [对照组]
  ILLEGAL verdict   : NOT BLOCKED (save proceeds)
  engine log lines  : (none)

与 PR #919 的实录一致。三点值得单独记下：

1. 第一条探针跑出的正是 cases:78 那句原话的反例（New 直接到 Resolved）。
2. 串扰要隔离：探针第一版里 lead 那条抛了 ValidationError: Email is required、case 的 insert 那条抛了 Resolution is required when closing a case —— 都不是状态机。把邻近规则的必填项补齐后，两条都变成 NOT BLOCKED，只剩一条 WARN。把这类串扰当成「状态机拦下了」是最容易犯的误判。
3. 对照组不是多余的：表内的移动一条日志都不记，说明规则不是空转，它确实在判别 —— 只是判别的结果是记日志而不是拦截。

其余逐条复核：grep -rn "initialStates" src/ 零命中（故 insert 路径直接 return null）；grep -rniE "bypass" src/ 无任何权限项；legalNextStates 在 node_modules/@objectstack/ 里唯一的消费者是 runtime/dist/index.js:5834 的 GET /objects/{name}/state/{field} 端点，本仓零调用；五条规则 severity 全部 warning（lead:513 / opportunity:414 / case:347 / contract:260 / quote:264）。⛔ 按 #575 B4，没有把任何一条提到 error。

一、#920 —— state-machines 页的「护栏」说法（:3 :8 :86-94 :106 :110-112 :133 :134）

沿用 PR #919 已在本页 :22 落地的口径（advice, not a gate / 保存照样通过 / 引擎记 WARN），不新造措辞。

行	原文	改法
:3 frontmatter	「how HotCRM enforces valid status transitions」	declares + 「what the tables do and do not do」。这是搜索结果与导航里第一眼看到的句子
:8	「A state machine enforces these transitions so users can't put records into nonsensical states」	只改第二句：声明路线、不强制，五条全 warning、保存照样通过，并指向本页 :22
:86-94	「Why state machines matter」—— 以「没有状态机就会出现 X」立论	改题为「What a state machine buys you」：X 现在照样出现，各记一条警告后落库；漏斗报表不会因为存在一张表就「反映现实」。随后正面写清转换表真正给的三件事
:106	「Configure at Setup → Object → Status → State Machine」	该配置面不存在（#920 留的待核项）。写实为：每张表是对象上的 validations[] 条目，改它是代码改动加重新部署
:110	下拉「只显示合法的下一个状态」	零实现：写清 legalNextStates 存在于平台、唯一消费者是那个 HTTP 端点、本应用无人调用
:111	「shows an error: Cannot move from Converted back to Working」	不抛错不弹窗；唯一痕迹是一行服务端日志，界面里看不到。顺带：那句假的错误文案里带着 #921 的状态词，改写后整句消失，R30 在 :111 无需再动（#921 与 #920 原文即写明「可以分别改也可以一轮改完」）
:133	「下拉缺选项 = 状态机在拦它」	:110 的孪生句，同一零实现。不改会让同页 :110 与 :133 自相矛盾，故一并收口
:134	「bypass state machine 权限」	grep 零命中，且不需要 —— 没有东西要绕。新建路径根本不查表

:112（新状态的必填字段）保留：那是 requiredWhen 谓词，是真的会拒绝保存的另一套机制（opportunity.object.ts:303 / :327），只补一句点明它不是状态机。

⚠️ 一处刻意的克制（复核中改掉了我自己的初稿）

「What a state machine buys you」的初稿里我写了一条「Copilot 只建议转换表允许的那些转换」。写完去核，grep -rniE "state.?machine|transition|legalNext" src/skills/ src/actions/ 零命中 —— 本仓没有任何技能或动作提到转换表。这句话我证不了，于是删掉重写成不对当前消费面做断言的说法（「流程条件、报表或技能可以按声明出来的路线来写」）。本页 :114-122 那一节本身（「Copilot 理解状态机…这可以防止 Copilot 建议非法的转换」）同属存疑，但它是平台侧 agent 行为、本仓证据不足以断言真伪，故不在本 PR 顺手改，另行归档为越界发现。

二、#925 —— cases 页的三处 SLA 说法（:59 :70 :71 :111）

口径抄平 #886 / PR #885 与 #903 / PR #918 已在 sla-and-escalation 页落地的写法。

• :70 SLA 截止日期：只对 Critical 成立（case.hook.ts:60-63，due.setHours(due.getHours() + 4)），且路径是 beforeInsert 加 beforeUpdate —— 原文的「工单创建时」漏掉了「编辑为 Critical」这条路径，改写后两条都写到。High / Medium / Low 一个字节都不写。
• :71 违约标记：真正写它的是 case-sla-monitor.flow.ts 的每小时扫描，选仍未结（status: { $nin: ['resolved','closed'] }）且 sla_due_date 已过期的工单；从不比较解决时间与目标。两个后果（无截止日期永不是候选、晚解决但赶在下次扫描前解决永不被标记）照写。
• :59 / :111 字段名：真名是 SLA Violated（is_sla_violated，case.object.ts:205-209），breach flag 不存在。:111「对客服只读」经核属实（service-agent.profile.ts:52-53 两条 FLS 掩码 readable: true, editable: false，resolution_time_hours 同），只改字段名并补一句锁的来源。
• :27-32 优先级表：按 service/cases 的《自动发生的事》:70/:71 是同族第三处未清扫的 SLA 说法——「SLA 截止日期按优先级计算」只对 critical 成立、「违约标记按解决时间超目标翻转」是另一套机制,字段名也不存在 #925 授权「一并判断」，在表下补一句「四行里只有 Critical 那行背后真有一只时钟」，与 sla 页 :14 同构。⛔ SLA policy matrix: per-priority × tier clocks, first-response stamping, escalation that reassigns #595 不预判 —— 只写当前行为，不谈 High/Medium/Low 该不该有时钟。

三、#926 —— cases 页的视图清单与经理提示（:114-121 / :171-173，fresh main 上为 :116-124 / :174-176）

• 《标准列表视图》整节重写成 case.view.ts 的七个真实视图（All Cases / Service Workflow / SLA Calendar / Case Timeline / Escalated Cases / ⏰ SLA at Risk / My Open Cases），并按 tabs 数组写出每个视图在工单列表上对应的页签。逐条回源核过：kanban 的 groupByField: 'status' 加 is_closed=false、calendar 的 startDateField: 'sla_due_date'、timeline 的 created_date → closed_date 且 groupByField: 'owner_id'。
• 六个假名按 docs(service): write the sla page's views, report dimensions and business-hours claims to source (#917) #924 先例点名说清 + 给真实去处，不静默删名：Critical Cases / Breached SLA 是 service.dashboard.ts:115 / :144 的磁贴（后者真名 SLA Violations），Service Board 的真身是 Service Workflow，Cases Due Today / Recently Closed / By Account 三个以任何形式都不存在。
• :171 的「红色徽章」：工单列表上唯一的颜色规则是 All Cases 的 rowColor，键在优先级上（case.view.ts:39-42），不是违约 —— 与 service/sla-and-escalation 的 SLA 跟踪一节仍有四处行为性失实：只有 Critical 拿得到 sla_due_date、违约标记并非只读、"实时倒计时"零实现、High/Medium/Low 的"违约长什么样"描述的其实是优先级行色 #903 已在 sla 页写实的同一条。
• :173 客服排行榜：case_metrics（case.dataset.ts:15-21）只有 status / priority / origin / type / created_date 五个维度，无 owner 维度，所以按客服分组在语义层就做不出来。照 docs(service): write the sla page's views, report dimensions and business-hours claims to source (#917) #924 报表条的口径写实，不预判该不该加这个维度。

四、#912 —— bare workflows 残留 4 处

• whats-new:89 ×3：contract_renewal 是流程不是 workflow（src/flows/contract-renewal.flow.ts:25，label: 'Contract Renewal Reminder'）。改成 flow 并与 administration/automation:77 内置流程表的标签逐字一致；中文两页沿用该表已有的「合同续约提醒」/「合約續約提醒」。这一项的实质（按每份合同自己的 renewal_notice_days 触发）复核属实（流程的 check_notice_window 决策节点按记录逐条判窗口），只纠叫法。
• state-machines:133（fresh main 上为 :140）×3：Related 链接的「由转换触发的 workflows」改为「转换可以触发的流程与对象钩子」。
• cases:80 ×3：小节标题 ## Workflow automation 改为 ## Flow and hook automation（中文「流程与对象钩子自动化」/「流程與物件鉤子自動化」），与该节四条正文（流程的 notify 节点、case_status_side_effects 钩子）对齐，且不与同页 ## Case escalation 等相邻标题撞名。
• guides/integrations:130 ×3（bare workflows 残留族在 #899 枚举之外还有 4 处：whats-new 把真实的 contract_renewal 流程叫成 workflow，state-machines:133 在 PR #894 扫过该文件后仍留着 #912 判为最弱一处，交接单人定夺）：改。理由：该段虽是「设计意图（尚未落地）」，但它并列的两个代码面是现在时的事实陈述，而 workflow 命名的是平台 7.7 移除的元数据类型 —— 留着等于暗示除 flow / hook 之外还有第三种代码面。改为 flow / hook，一词之差，不动该段「尚未落地」的定性。

五、PM 验收 #928 时追加的两行（出处：#928 报告的边界节）

以下两行不在四单原始面内，是 PM 在 #928 的 dev 验收中发现、判归本单一次收口的（同页、同口径，且紧邻 :174-176，hunk 自然连续）。照常先复核后改：

• :166「New cases should not sit for more than the first-response SLA」—— 本仓不存在首次响应目标：first_response_date 的唯一写入方是 global.actions.ts:386-401 的 logActivityAction，写完之后没有任何东西读它去比对 —— case_metrics 无首次响应度量（case.dataset.ts:23-27 三个 measure 均与它无关），grep -rn "first_response" src/flows/ 零命中，无报表、无磁贴、无告警。按 docs: write the three business-hours claims outside the SLA page to source (#928) #933 已落地的「服务承诺而非应用跑着的时钟」口径降格。
• :167「it stops the SLA clock in some configurations」—— 与 docs(service): write the sla page's views, report dimensions and business-hours claims to source (#917) #924 已在 sla 页 :138 杀掉的是同一处虚构：sla_due_date 只写一次、从不重算，case_sla_monitor 的 $nin 只排除 resolved / closed，waiting_customer 不在排除名单上。同口径写实。

六、边界（未触碰的东西，逐条自证）

• ⛔ administration/state-machines 用的一整套状态词在 src/ 里查无此值：lead 的 Working / Disqualified 是导入别名不是状态，opportunity 的 Closed Without Decision 根本不存在，Needs Analysis 被漏掉；:60 的「Disallowed」举例反了 #921 的状态词行一字未动（R30 的单）。git diff -U0 content/docs/administration/state-machines.mdx 的 hunk 起点为 :3 :8 :86 :88 :90 :94 :106 :110 :133 :140 —— administration/state-machines 用的一整套状态词在 src/ 里查无此值：lead 的 Working / Disqualified 是导入别名不是状态，opportunity 的 Closed Without Decision 根本不存在，Needs Analysis 被漏掉；:60 的「Disallowed」举例反了 #921 点名的 :14-15（清单两条）、:35-57（ASCII 图加转换表整表）、:60（Disallowed 举例方向）、:69（Closed Without Decision）、:118（Copilot 举例）全部不在任何 hunk 内。:8 与 :111 两行按 PM 裁定归本单的行为面：:8 的第一句（含 New / Working / Qualified 三个词，顺序位置不变）逐字保留，R30 的词表替换仍是干净的一处改动。
• PR docs(administration): list all five objects that have a state machine (#896) #919 / docs(service): cases 升级整节与 index 生命周期第 2 步按 flow / hook 写实(#914、#915) #922 / docs(service): write the sla page's views, report dimensions and business-hours claims to source (#917) #924 已落地的行零回退：state-machines:12-24 整节（含 :22 的 advice-not-a-gate 段）、cases:34 / :82-83 / :89-105 / :181 全部原样，不在 diff 内。
• :79-84（「The system also enforces」四条商机必填/审批）未改 —— 不在 administration/state-machines 通篇声称状态机会「拦下」非法转换，实测五条规则全是 warning：保存照样通过；连「只显示合法下一状态」「bypass state machine 权限」都无实现 #920 的裁定面内，另行归档为越界发现。
• src/** 零改动；@objectstack/* 版本未动；本仓无 content/docs/releases/（whats-new 不是发布说明目录，且 bare workflows 残留族在 #899 枚举之外还有 4 处：whats-new 把真实的 contract_renewal 流程叫成 workflow，state-machines:133 在 PR #894 扫过该文件后仍留着 #912 明确其为「纠叫法不是改历史」）。
• zh 内链一律不带锚（/zh-Hans/docs/... / /zh-Hant/docs/...）。
• 三语结构对齐：两页三语行数各自相等（state-machines 142 / cases 194），引用块计数三语相等（state-machines 0 / cases 1）—— docs-drift.test.ts 的 callout 平价守卫要的就是这个等式。

七、验证

六道门全部在 flock -w 7200 /tmp/os-heavy-verify.lock 内串行，NODE_OPTIONS=--max-old-space-size=4096：

门	退出码	关键行
pnpm validate	0	Data: 17 Objects 344 Fields；5 条 author-time 警告与 main 同（approval / campaign_member group）
pnpm typecheck	0	tsc --noEmit，无输出
pnpm lint	0	13 warning(s), 14 suggestion(s)，与 main 同
pnpm hygiene	0	✓ no raw control bytes in first-party files；扫描面含 content 与 .changeset（425 个文件）
pnpm build	0	✓ Build complete；dist/objectstack.json (1921.4 KB)
pnpm test -- --maxWorkers=2	0	Test Files 70 passed (70)；Tests 1602 passed, 1 skipped (1603)

单跑 #919 新增的守卫（本页唯一读 content/docs 的钉子）：test/status-state-machines.test.ts 得到 Test Files 1 passed (1) / Tests 39 passed (39)。

守卫覆盖面的诚实交代 —— predicted GREEN, stayed GREEN。 该守卫只读本页首个 ## 小节的列表项（:12-18 的对象清单），而本 PR 一个字都没动那一节，所以它预测就应该保持绿，跑出来也确实是绿 —— 这证明我没碰坏清单，不证明新写的散文是真的。本 PR 改的其余全部行都在守卫盲区里：grep -rn "content/docs" test/ 命中的几个文件分别钉 automation 页的流程表、contacts 页的邮箱唯一性、dashboards 页的磁贴名、三语 callout 计数与「转化率」用词，没有一个读 cases / state-machines / whats-new / integrations 的散文。撑住这些散文的是上面第零节的探针实录与逐条源码引用，都写进了正文，下一个读者可以照着复核。

push 前另做控制字节自扫（覆盖 check:nul-bytes 之外的整段范围）：改动的 12 个 mdx 加 changeset 零命中。未起 dev server；探针为一次性文件，跑完已删，git status 干净。

---

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 10:27am