docs(analytics,administration): write the first-response claims, the Lead reports section and two behavioural claims to source (#936, #951, #952)

[yinlianghui]

Fixes #936
Fixes #951
Fixes #952

三单并单（R31），外加 PM 在 #948 验收时判归本单的《Service reports》整表收口。四个页面 × 3 语言，src/ 零改动，content/docs/releases/ 未触碰。基线 origin/main = b7791caf（PR #950 落地后），全部行号 fresh main 重定位；PR #923 / #950 的落地行零回退。

#936 —— 「可度量的首次响应 SLA」三处

先复核前提，三处全部成立：

• first_response_date 有写入方：src/actions/global.actions.ts 的 logActivityAction 在工单第一次记录「已经发生过」的通话/会议时打戳（读回旧值，不覆盖）。这一半是真的。
• 但没有目标、没有度量、没有告警：case_metrics（src/datasets/case.dataset.ts）三个 measure 是 case_count / avg_resolution / avg_sla_violated，无任何首次响应项；grep -rn "first_response_date" src/flows/ src/reports/ src/datasets/ 零命中；content/docs/service/sla-and-escalation 全页 first response 计数为 0 —— 而 setup §11 正是把「SLA matrix」链到那一页。

三处按 #933 / #946 已落地的写法抄平（service/cases.mdx:179 是同族的标准句式）：

1. administration/setup §11：删掉整列 First response（1 小时 → 1 个工作日），保留解决目标表，点名 Critical 那行是 case_sla_defaults 真正盖出来的期限、其余三行是服务承诺；另起一段写实「这里没有首次响应目标可确认」+ 戳的真实写入时机 + 三条否定（无度量、无报表磁贴、无告警）。收尾把「请自行调整」指向 src/objects/case.hook.ts，不再暗示存在某个设置屏。
2. analytics/reports：SLA Performance → 真名 SLA Performance Report，口径按 case.report.ts 写实；表下一段说清它没有首次响应数字，且那个 SLA 数是违约率（is_sla_violated 的平均）而非准时率。
3. analytics/cubes Service Cube：删掉 First-response time (minutes) 与 SLA met % (first response and resolution) 两条，换成 case_metrics 真实声明的 SLA Violation Rate 并注明它是违约率不是达标率；补一段「这里没有首次响应度量」。

一处越出 issue 列举但属同一主张：cubes 的示例问题 "SLA met % by priority by month." 与被删的那条度量是同一个名字 —— 若只删度量、留下示例问题，页面会自相矛盾。改写为 "SLA Violation Rate by priority."（顺带去掉 by month：created_date 粒度是 day，#924 已在 sla 页写明）。

#595「是否应该有首次响应 SLA」不预判，三处都只写现状。

#951 —— Lead reports 整节

src/reports/ 六个文件里 lead 侧只有 lead.report.ts 一份，label 是 Lead Engagement by Month × Source；页面列的三份 grep -rn "Lead Conversion Funnel\|Lead Source ROI\|Aged Leads" src/ 零命中。沿 #939 在 service/cases「Standard list views」的口径重写整节：

• 先列真实那一份，并说清它按什么切（行 = 来源，列 = Last Contacted 的月份，未联系过的线索被 runtimeFilter 排除）。
• 再逐条点名三份不存在的，并纠正 Working：它是 src/mappings/lead_import.mapping.ts 里 'Working': 'contacted' 这一行导入别名，不是 crm_lead.status 的取值；真实状态词按 PR docs(administration): write the state-machine status vocabulary and the last two behavioural claims to source (#921, #940) #950 的词表写成 New → Contacted → Qualified → Unqualified → Converted（Unqualified 从任何开放状态可入）。
• Lead Source ROI 额外说清语义层为什么答不出来：lead_metrics 只有一个度量（线索计数）+ 四个维度，收入根本不在这个数据集里。
• 末尾给真实替代品：Open Leads 磁贴（Executive Overview 仪表盘，同一数据集）。

PM 面扩 —— 《Service reports》整表（#948 卫星命中）

第二个 commit。原计划只改 SLA 那一行，PM 判定整表归本单一次收口。src/reports/case.report.ts 只发布三份，页面列了六份：

真名（逐字对源码）	口径
Cases by Status and Priority	rows: ['status','priority']、values: ['case_count','avg_resolution']，带一张按状态的柱状图
SLA Performance Report	rows: ['priority']、values: ['case_count','avg_sla_violated','avg_resolution']、runtimeFilter: { is_closed: true }
Cases Opened by Priority × Day	matrix，rows: ['priority'] × columns: ['created_date']（day 粒度）

另外五份（Case Volume by Origin / Case Resolution Time / Top Accounts by Case Volume / Reopened Cases / CSAT by Agent）在 src/ 零命中，且多数连自建都建不出来 —— 逐条给出理由：case_metrics 无 owner 维（所以「by agent」两处都够不着，与我在 cubes/setup 消除的同族一致）、无 account 维、工单上没有任何字段标记「曾被重开」、Customer Satisfaction（customer_rating）虽是真字段但数据集没有为它声明度量。唯一建得出来的是 Case Volume by Origin（Origin 是维度），如实写明。

《订阅与定时推送》里两条示例点名了刚被判定为不存在的报表（SLA Performance / Top Accounts by Case Volume）—— 这是我这次改动自己造成的自相矛盾，一并换成真实报表。Sales / Revenue / Marketing 三节未动（见「边界」）。

#952 —— 两条枚举外行为主张

• A（administration/setup :96）：「请在 设置 → 商机 → 阶段 中调整」→ 沿 docs(service): write the cases and state-machine pages' remaining claims to source (#912, #920, #925, #926) #939 对 state-machines:108 的同型处理，点名该配置面不存在；阶段是 stage 字段选项（src/objects/_picklists.ts 的 OPPORTUNITY_STAGE_OPTIONS），概率是 src/objects/opportunity.hook.ts 的 STAGE_PROBABILITY，且该钩子每次保存都按阶段重推 probability / expected_revenue，所以手填概率撑不过下一次保存 —— 这一条比原句多一个读者真会被咬到的事实。
• B（administration/state-machines :140）：「用状态机转换触发自动化 —— 性能要好得多」。比较对象无据，且机制前提不成立：转换表是 severity: 'warning' 的 validations[] 条目，在做出移动的那次保存里被求值、只写一行日志，不产生任何可订阅的事件（本页 :120 在 PR docs(administration): write the state-machine status vocabulary and the last two behavioural claims to source (#921, #940) #950/docs(service): write the cases and state-machine pages' remaining claims to source (#912, #920, #925, #926) #939 后已写明「按转换触发自动化则是 record_change 流程或对象钩子」）。改写为实况：该收窄的自动化是 record_change 流程在自己的起始条件里比对 record.stage 与 previous.stage —— src/flows/opportunity-won-alert.flow.ts 正是这么写的，并给出它这么写的真实理由（避免已赢商机的每次后续编辑都重发祝贺）。删去无据的性能比较。

验证

六道门全部在 flock -w 7200 /tmp/os-heavy-verify.lock 内串行，面扩后重跑一遍，退出码均为 0：

validate_exit=0    typecheck_exit=0    lint_exit=0
hygiene_exit=0     build_exit=0        test_exit=0
Test Files  70 passed (70)
Tests  1602 passed | 1 skipped (1603)

CI（head 9f097de2）8 项全绿，含 link-check 与 Check Changeset。

守卫盲区如实报告：本 PR 改的四个页面里，只有 docs-conversion-rate-spelling（carriers 钉住 analytics/reports 两个中文页必须仍写「转化率 / 轉化率」）与 docs-drift 的 callout 数量平价真正读到我的改动面；setup §11、cubes 度量列表、reports 各表、state-machines 的 Tips 段落没有任何守卫读，改动正确性靠 src/ 逐条回源，不靠测试变红。

docs-conversion-rate-spelling 是本 PR 最接近踩掉的守卫：改前 analytics/reports.zh-Hans 全页仅有的一处「转化率」就在我重写的 Lead Source ROI 那一行。反向验证（预测方向：RED）——把重写后新写法里的「转化率」临时换成别的词，单跑该守卫：

Tests  1 failed | 3 passed (4)
  118|  const file = join(DOCS_ROOT, `${carrier.page}.${locale}.mdx`);
  119|  expect(readFileSync(file, 'utf8')).toContain(carrier[locale]);

与预测一致变红，随后还原（两个中文页各保留一处该词，语义上正是 ROI 报表答不出来的那个「转化率」）。还原后 docs-conversion-rate-spelling / docs-drift / status-state-machines 三个守卫单跑 77 passed。status-state-machines 的 roster 守卫只读 state-machines 页第一个 ## 小节，我的 Tips 改动在其扫描面之外，预测 GREEN 且实测 GREEN。

关于 PR #955 的新守卫 test/docs-service-index-analytics.test.ts：已从其分支取来在本分支单跑，结果 13 failed | 7 passed —— 红的原因与本 PR 无关，该守卫钉的是 #955 自己重写的 content/docs/service/index*.mdx 三页文本，而那三页在我的 base（b7791caf）上还是旧文本。它的输入面是 service/index 三页 + service.dashboard.ts + case.report.ts / case.dataset.ts，与本 PR 的改动面（analytics 两页、administration 两页）零交集，两个 PR 也没有共同文件。顺带一提：该守卫从源码导出的三个报表 label 与我这次写进 reports 页的三个逐字一致。

边界

• src/ 零改动，content/docs/releases/ 未触碰，@objectstack/* 版本未动。
• 本页 Sales（8 个名字）/ Revenue（3）/ Marketing（2）三节与 analytics/cubes 的「四个内置 cube」框架同样与 src/ 对不上（src/datasets/ 是九个 dataset，没有 campaign dataset；Pipeline by Stage 只存在于仪表盘磁贴标题，Stale Opportunities 只存在于列表视图 label）。「首次响应 SLA」被三处文档写成可度量的目标：setup 清单 §11 的 SLA 矩阵整列、analytics/reports 的 SLA Performance 行、analytics/cubes 的 Service Cube 措施 —— 全仓没有任何首次响应目标、达标度量或超时信号 #936 正文明确把它们排除在本单主张之外，已按 Prime Directive chore(deps-dev): bump eslint from 8.57.1 to 9.39.2 #10 另行开单，不在本 PR 修：analytics/reports 剩下的 Sales / Revenue / Marketing 三节共 13 个报表名 src/ 里一个都没有，而真实发布的 6 份报表在整页上一次都没出现 #962（reports 剩余三节）、analytics/cubes 整页建立在「四个内置 cube」之上，而 src/datasets/ 是九个 dataset：四个名字一个都不存在，Marketing Cube 连数据源都没有 #965（cubes 整页）。

[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:35pm