Repository navigation
administration/state-machines 说 case / contract / quote「没有完整状态机」，但三者都有具名的 state_machine 校验规则；页首清单也只列了 lead / opportunity 两个 #896
Description
来源：#850 / PR #894 清扫「工作流规则」字样时的顺带发现。基线 origin/main = 92b94e71。
与 #850 / PR #894 的边界：PR #894 在本页只动了「工作流规则」这个字样（派单的硬性切割就是「只动字样」），:17 的后半截行为性主张原样留着 —— 本条就是那半截。PR #894 已把 simpler workflow rules 换成不指涉任何类型的中性表述 simpler status handling，没有新增也没有加强下面这个错误，但也没有修它。
事实
content/docs/administration/state-machines.mdx:12-17 及其 zh-Hans / zh-Hant 孪生页（同行号）：
:12-15—— "HotCRM uses state machines on:" 之后只列 Leads 与 Opportunities 两个对象。:17—— "Other objects (case, contract, campaign, quote) have status fields but use simpler status handling rather than full state machines, because their transitions are less strict."
逐条对源码核（grep -rn "type: 'state_machine'" src/objects/，5 处命中）：
| 对象 | 页面的说法 | 实况 |
|---|---|---|
crm_lead |
有状态机 | ✅ lead_status_progression（src/objects/lead.object.ts:511） |
crm_opportunity |
有状态机 | ✅ opportunity_stage_progression（src/objects/opportunity.object.ts:412） |
crm_case |
❌ 「没有完整状态机」 | 有：case_status_progression（src/objects/case.object.ts:345），field: 'status'，带完整 transitions 映射 |
crm_contract |
❌ 同上 | 有：contract_status_progression（src/objects/contract.object.ts:258） |
crm_quote |
❌ 同上 | 有：quote_status_progression（src/objects/quote.object.ts:262） |
crm_campaign |
❌ 同上 | ✅ 确实没有 —— 四个里只有这一个说对了 |
也就是说：:17 点名的四个对象里，三个的状态转换恰恰是由具名 state_machine 校验规则强制的，而 :12-15 那份「用状态机的对象」清单漏掉了这三个。
顺带一提，service/cases.mdx:78 自己写着 "Status progression is enforced — you can't jump from New straight to Resolved without going through In Progress" —— 那正是 case_status_progression 干的事。同一套文档，两页互相矛盾。
影响
一个管理员按 :17 的说法去理解「案例/合同/报价的状态转换比较松、没有强制」，会在改这三个对象的状态流转时以为不需要同步维护转换映射；实际上写一个不在 transitions 里的目标状态会被校验规则拦下（severity warning，见各对象定义）。这是「文档说没有约束，实际有约束」的方向，不是观察类。
修复面（未做）
三语同步：:12-15 的清单补上 case / contract / quote 三个（并说明它们与 lead / opportunity 一样都是对象上的 state_machine 校验规则，7.7 移除顶层 stateMachines 键后统一迁到这里）；:17 改写为只讲 campaign —— 或按语境判断这一句是否还有存在必要。修 :17 会连带重写 :12-17 这一小节，所以不适合塞进 PR #894 的字样清扫里。
Activity
yinlianghui commentedon Aug 6, 2026
🔒 认领(/pm-dispatch R27)— session
session_01VHrPAGEgFDoHjphqYG4BMa,分支claude/issue-896-state-machines-list。文件面:
content/docs/administration/state-machines{,.zh-Hans,.zh-Hant}.mdx,仅 :12-17 节 ×3——PR #906(#844)已动本页 zh-Hant 用字,fresh main 上重定位,convert 词汇沿 #906 已落口径不得回退。裁定:
state_machine命中逐条重验)。error抛异常、warning不阻断保存(core.mjs:2434-2441 族),contract_status_progression实测为 warning。本单三个新列对象的 state_machine 规则须逐条实测 severity 与真实拦截行为,不照抄 issue「会被校验规则拦下」的说法——若为 warning,写「声明了完整 transitions 映射(warning 级校验)」而非「强制/拦下」,并与 lead/opportunity 两条的实况对齐措辞。:17改写为只讲 campaign 还是删句,由 dev 依语境定,PR 里说明取舍。service/cases.mdx:78的互证句只引用,不动那一页。Generated by Claude Code
yinlianghui commentedon Aug 6, 2026
✅ 验收通过 —— PR #919 已转 ready 并挂 auto-merge(CI 9/9 全绿实核)。
验收要点:
state_machine命中行号各 +1 重定位),清单补齐 case/contract/quote,路线按各自 transitions 逐边核对书写(如 resolved 只能从 in_progress/escalated 进入)。severity: 'warning',五条非法跳转全部 SAVED 落库,引擎只记一条 WARN;lead/opportunity 与其余三个没有分档;五条均无 initialStates,insert 路径完全不检查。裁定「不照抄 issue『拦下』说法」被证完全必要——措辞落为「advice, not a gate / 保存照样通过」,沿 contracts.mdx 还剩四处与实现不符：五条幽灵列表视图、三个幽灵选项、无实现的「已激活不能删除」、教销售代表做他无权做的事 #832/PR docs(contracts): 按视图、选项集、hook 与 profile 写实合同页其余四处 (#832) #874 已落地口径。test/status-state-machines.test.ts从 GOVERNED/UNGOVERNED ledger 推导期望,只读列表项防散文误伤,UNGOVERNED 条有非空 precondition 防空转变绿;反向验证预告 RED 实测 RED(还原 mdx 后三 locale 全红,点名恰为 case/quote/contract 三语译名)。越界发现处置(两单已复核成立,均标 pm:queue):
administration/state-machines通篇声称状态机会「拦下」非法转换，实测五条规则全是warning：保存照样通过；连「只显示合法下一状态」「bypass state machine 权限」都无实现 #920(同页「拦下」通篇失实 + :110 下拉零实现 + :134 bypass 零命中 + cases:78 跨页互证冲突)——已注明不得顺手把 severity 提到 error(Follow-up to #514: remaining behaviour fixes, conventions, and the action-sandbox test gap #575 B4 产品决定);与 bareworkflows残留族在 #899 枚举之外还有 4 处：whats-new 把真实的contract_renewal流程叫成 workflow，state-machines:133 在 PR #894 扫过该文件后仍留着 #912 的 state-machines:133 同页,R28 可考虑并单。administration/state-machines用的一整套状态词在src/里查无此值：lead 的 Working / Disqualified 是导入别名不是状态，opportunity 的 Closed Without Decision 根本不存在，Needs Analysis 被漏掉；:60的「Disallowed」举例反了 #921(状态词全套查无此值:Working/Disqualified 是导入别名、Closed Without Decision 零命中、:60 Disallowed 方向反了、setup 三页同批)——面大跨页,R28 候选或拆分。crm_case在中文文档里有三种叫法：语言包「服务案例」、25 个页面「工单」、14 个页面「案例」（两页同页混用） #837 覆盖,未重复立单,处置正确。Generated by Claude Code
docs(administration): list all five objects that have a state machine (…