docs(service): SLA 跟踪一节按实测行为改写(#903)

[yinlianghui]

Fixes #903

三语同步改写 content/docs/service/sla-and-escalation{,.zh-Hans,.zh-Hant}.mdx 的 SLA 计算 / 跟踪一节。四族里三族属实并已写实,第四族(B,违约标记只读)复核后前提证伪 —— 按实情保留原判断并补上真实机制,而不是照单把它改成一句新的失实说法。未动任何字段定义、流程、视图或平台版本。

逐条前提复核(基线 7df29789,平台 17.0.0-rc.3)

行号为 issue 基线 90686a4f 的原始值。PR #907(#886+#890)与 #906(#844)确实动过同页,但其增删都落在 :57 一节及其后,本单四族的四处行号在 fresh main 上未位移,逐一原址命中。

A :12「每个工单创建即获 SLA 截止日期」—— 成立 ✅

src/objects/case.hook.ts:60-64 只在 priority === 'critical' 且字段为空时填 now + 4h,其余三档一律不写。改动:

• :12 改为「只有 Critical 工单会自动获得 SLA 截止日期」,点名 case_sla_defaults 钩子与文件路径。
• 连带 :8 导语一次改齐(裁定 1)。导语原文「gives every case a deadline … surfaces breaches in real time」是 A 的同一句话换个位置,只改 :12 会把矛盾留在更显眼的地方;「in real time」同时是 C 的回声,一并按每小时扫描写实。
• :21「SLA 目标可按优先级配置」随之收窄为「Critical 的 4 小时是系统唯一会盯的目标,写在钩子里」—— 不与 service/sla-and-escalation 三语还剩两处行为性失实：升级触发条件多出一个不存在的 High+Customer 分支，Critical 违约行承诺「红色横幅 + 通知支持经理」 #886 已落地的 :136 冲突,只是把它的范围说准。
• service/sla-and-escalation 三语还剩两处行为性失实：升级触发条件多出一个不存在的 High+Customer 分支，Critical 违约行承诺「红色横幅 + 通知支持经理」 #886 / service 三页仍写「建议一个解决方案」会检索知识库并起草回复 / Copilot 用知识库对相似历史工单做模式匹配——两个技能都做不到 #890 的 :16 / :57 族 / :105 / :134 原文逐字未动,:16 的 Critical 单元格只在第二列加了「会被写入 sla_due_date」,判断部分照抄。

D :17-19 High/Medium/Low 的「违约长什么样」—— 成立 ✅

src/views/case.view.ts:39-42 的 rowColor 键在 priority 而非违约,三重不符全部复现:行底色不是徽章、按优先级恒常渲染、High 是橙 #f97316 不是红 / Medium 是黄 #eab308。三行现写明「什么都不会发生」并交代真实归属(case_sla_monitor 只捞 sla_due_date 已过的工单,而它们没有截止日期),目标值如实降格为服务承诺(裁定 5);另加一句点明列表里真正报告违约的是 is_sla_violated 这一列(case.view.ts:28)。

C :34-38 实时倒计时 —— 成立 ✅

grep -rniE "countdown|remaining" src/ 仅两处无关注释(opportunity.dataset.ts:76、executive.dashboard.ts:149)。另有一处比 issue 更强的证据:src/pages/case_detail.page.ts:44-51 的 page:header 只带 {case_number} · {subject} 与副标题 {crm_account},页眉里根本没有 SLA 字段;两个 SLA 字段渲染在 :56-73 的 record:highlights(label Key Information)里。三条 emoji 阈值行替换为真实呈现,并补上两个确实能帮上忙的视图(sla_calendar / sla_at_risk),按各自的过滤条件如实描述 —— sla_at_risk 筛的是 priority in [high, critical],不是「离截止有多近」。

同族回声 :124「关注你的 SLA 倒计时——当你看到琥珀色区域时」指的是同一个不存在的部件,一并改写;只改 :34-38 会让页面继续在提示区承诺倒计时。

B :32「违约标记对客服只读」—— 前提证伪 ❌

Issue 的依据是 case.object.ts:205-210 不是 readonly,推论「那道门不存在」。字段确实不是 readonly(注释写明原因:case_sla_monitor 要写它,16.x 会丢弃对 readonly 字段的写入,#2948)—— 但这道门存在,只是实现在另一层:

src/profiles/service-agent.profile.ts:52
  fields: { 'crm_case.is_sla_violated': { readable: true, editable: false }, … }

fields 是 PermissionSetSchema 的一等键(PERMISSION_SET_KEYS 含 fields,FieldPermissionSchema = { readable, editable },.strict()),不是会被静默丢弃的未识别键。本仓自己的文档也已列过这条遮罩:content/docs/administration/profiles.mdx:82 —— 「crm_case.is_sla_violated / resolution_time_hours | Service agent | Nobody — they are computed」,sharing-and-security.mdx:194 写明 FLS「enforced everywhere」。其余 profile 里 sales_manager / sales_rep 对 crm_case 本就 allowEdit: false,marketing_user 无授权,guest_portal 只能 insert —— 也就是说页面说的「对客服只读」是对的。

照 issue 原样改写会把一句正确的话改成失实。故:保留该判断,补写真实机制(字段级安全,不是字段属性),并链到 Profiles 的 FLS 表让读者能自己核。

B 这一族真正失实的是相邻的 :30 —— 字段定义行。它写「SLA Breached? — true when the resolution time exceeds the target」,两处都不对:字段标签是 SLA Violated(case.object.ts:206 / translations/en.ts:659),不存在叫 SLA Breached? 的字段;置真条件也不是「解决时间超过目标」,而是每小时扫描命中「status 不在 resolved/closed + sla_due_date 已过」(case-sla-monitor.flow.ts:40-47)。由此两个后果值得写出来,且直接与 A 咬合:没有截止日期的工单永远不入选;在下一轮扫描前就被解决掉的超时工单也不会被标记。这条已改写。

裁定 4(只改页面承诺,不动字段定义)全程遵守 —— src/ 零改动。

反向验证的方向

本单是纯文档改写,没有可以「删掉再看诊断变红」的代码分支,pnpm test 也不含针对该页散文的断言(docs-drift.test.ts 的规则面是磁贴引用与对象覆盖,不是本页这几句)。按裁定如实报告:守卫盲区(散文列),predicted GREEN —— 各门在改前改后都应绿,绿本身不构成对文案正确性的证据。文案正确性的证据是上面每条的 file:line,而不是 CI。

裁定对齐

• 裁定 1(A 与 service/sla-and-escalation 三语还剩两处行为性失实：升级触发条件多出一个不存在的 High+Customer 分支，Critical 违约行承诺「红色横幅 + 通知支持经理」 #886 一次改齐、不回退):见 A 条。
• 裁定 2(口径沿 docs(automation): 按 flow 源码写实内置流程表两行，并修 opportunity_won_alert 的 description (#851) #870/docs(flows): name what the flow nodes do, not what they were once meant to do #877/docs(service): 按 flow 与 hook 写实 SLA 页的升级说明(#876) #885/docs: 清扫 automation 页之外的「工作流规则」并写实 cases 两条虚构通知 (#850, #887) #894,点名说清不做什么 + 真实归属,不静默删名):SLA Breached? / 红色徽章 / 琥珀区 / 倒计时四个名字都保留在文中并说清「不存在 / 是别的东西」,没有一个是悄悄删掉的。
• 裁定 3(SLA policy matrix: per-priority × tier clocks, first-response stamping, escalation that reassigns #595 不预判):全文只写当前行为。High/Medium/Low 该不该有时钟、违约标记该不该换种锁法,一句未评,末尾在 changeset 里显式指回 SLA policy matrix: per-priority × tier clocks, first-response stamping, escalation that reassigns #595。
• 裁定 4 / 5:见上。
• zh 页内链沿 docs(guides): email-and-calendar 按实测改写——Log a Call 的三写路径、活动指标所在仪表盘、连接器段落标注未落地 (#738) #755/docs(guides): 按实际落地能力重述 integrations 页，并校正指南索引描述行 (#756) #762 惯例不带锚(/zh-Hans/docs/administration/profiles、/zh-Hant/docs/administration/profiles);英文页用 #field-level-security,该锚点由 sharing-and-security.mdx:193 现存链接实证可达。

验证

全部在 flock -w 7200 /tmp/os-heavy-verify.lock 内串行执行,NODE_OPTIONS=--max-old-space-size=4096:

门	退出码	关键行
pnpm validate	0	✓ Validation passed (1297ms)
pnpm typecheck	0	无输出
pnpm lint	0	13 warning(s), 14 suggestion(s) —— 全部为 main 既有(approval 审批人可能解析为空、campaign_member 字段组)
pnpm hygiene	0	✓ no raw control bytes in first-party files
pnpm build	0	✓ Build complete (1580ms),dist/objectstack.json (1921.4 KB)
pnpm test -- --maxWorkers=2	0	Test Files 66 passed (66) / Tests 1587 passed | 1 skipped (1588)

push 前自扫控制字节:grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' 覆盖三个 mdx 与 changeset,退出码 1(无命中)。未起 dev server。

附带

• changeset:.changeset/sla-tracking-fidelity.md(patch),站内路径一律反引号包裹。
• 施工中发现同页另一族失实(视图 / 报表 / 配置项是否存在,6 处),行集与本单互斥,已先搜重复后立单 service/sla-and-escalation 剩余六处失实(#903 四族之外):营业时间可配置、SLA 表现报表的四个维度、Breached SLA 视图、Service Board 看板、My Open Cases 排序、Waiting on Customer 暂停 SLA 时钟 #917,未在本 PR 顺手改。

---

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 8:06am