docs(sales): 把 pipeline-management 剩余的仪表盘/报表指称写实 (#989)

[yinlianghui]

Fixes #989

同一页上的三族指称漂移，读者按现文在产品里都找不到东西。三语同址同步（en 行号，zh-Hans / zh-Hant 同行），src/ 零改动，不触 content/docs/releases/，不动 @objectstack/* 版本。

与 PR #990（刚合并，改本页 :94 / :95）和 #987（:93）行集互斥，两者落地的写法在本 PR 中零回退 —— coverage 报表的轴、sales_dashboard 的真名与标识符都按 #990 刚落地的措辞抄平。

一、:34 —— 幻名 + 一条源码里给不出的能力

原文：Sales Dashboard sums Expected Revenue across the open pipeline …

两半都不成立：

• 幻名：没有叫 Sales Dashboard 的仪表盘。真身 sales_dashboard，label 与 Sales 组导航项都是 Sales Performance（src/dashboards/sales.dashboard.ts:22、src/apps/crm.app.ts:61）。这正是 sales/pipeline-management 的「预测汇总」另两条：仪表盘真名是 Sales Performance，Pipeline Coverage 报表是「预测类别 × 结束季度」而非「季度 × 阶段」 #985 / PR docs(sales): 按真名写「预测汇总」的仪表盘与报表两条 (#985) #990 从同页 :94 修掉的那个幻名，:34 还留着一份 —— 现按「一名到底」归位。
• 假能力：opportunity_metrics 没有任何 measure 读 expected_revenue（grep expected_revenue src/datasets/ 零命中）。它暴露的金额类度量 total_amount / avg_amount / won_amount / lost_amount 一律绑 amount 字段（src/datasets/opportunity.dataset.ts:44-91），所以 Total Pipeline 磁贴给的是未加权的管道总额，任何仪表盘 widget 都求不出加权预测 —— 语义层没暴露它。

加权预测这件事在产品里是存在的，落点是表格视图的列合计：open_opportunities（label Open Deals）与 all_opportunities（label All Opportunities）各声明了对 expected_revenue 的 summary: sum（src/views/opportunity.view.ts:37、:138）。content/docs/sales/opportunities.mdx:120 已经这样写了（Amount and Expected Revenue carry column totals），本 PR 与它对齐，并写明仪表盘为什么给不出同一个数。

⚠️ 裁定与实况有一处出入，未按裁定执行

issue 正文与派发裁定都把本页 :51（看板列顶的「加权合计」）当作「已写对」的参照系，要求 :34 与之对齐。复核不成立：kanban 的列顶合计由 summarizeField 一个单数可选字符串决定 —— @objectstack/spec 的 src/ui/view.zod.ts 里 KanbanConfigSchema 写的是 summarizeField: z.string().optional()，describe 为 Field to sum at top of column —— 而 pipeline_kanban 设的是 summarizeField: amount（src/views/opportunity.view.ts:147-157）。看板每列只有一个数字，且求的是 amount，:48-:51 的「两个数字」本身就是同一类假能力。

本 PR 因此没有引用 :51，改为按上述源码证据把落点写成两张表格视图；:48-:51 属本单面外，已另立 #992，本 PR 不动它。

二、:68 + :72-:76 报表表格（含 :86 / :87 / :107 / :108 截断名）

:68「You will find these in the Reports section of the sidebar」：侧边栏没有 Reports 分组。分组叫 Insights（src/apps/crm.app.ts:143-156），且只钉了三张报表 —— Pipeline Coverage、Lead Inflow、SLA Performance —— 外加 CRM Overview 与 Forecasts。本表五行里只有第一行在导航上，其余四张从报表界面进。改写后与 content/docs/analytics/index.mdx:54 的口径（#987 落地）一致，两页不再矛盾。

四行报表名逐字对 src/reports/opportunity.report.ts：

原文	真实 label	出处
Pipeline Coverage (Quarter)，轴写作 quarter × stage	Pipeline Coverage by Forecast × Quarter；轴为 forecast_category（行）× close_quarter（列）	:36-:39
Funnel by Owner → Stage	Opportunity Funnel by Owner → Stage	:50-:51
Opportunities by Stage	逐字正确，未动	:6-:7
Won by Owner	Won Opportunities by Owner	:19-:20
Customer Churn Signals	逐字正确，未动	churn.report.ts:28-:29

coverage 行的轴按 PR #990 刚在 :95 落地的措辞抄平（未结管道的矩阵：行是预测类别，列是预计成交季度），不再写反的 quarter × stage；同时点明导航项上的短名是 Pipeline Coverage。:72 的「3x the quota」是描述业务问题的修辞（没有任何 coverage-ratio 度量），按原样保留，未当事实句处理。

截断名逐处补全：:86 与 :107 → Opportunity Funnel by Owner → Stage，:87 → Won Opportunities by Owner，:108 原来的 Pipeline Coverage by Quarter 两边都不是，归到导航名 Pipeline Coverage，与已写对的 :85 一致。

zh 两页里这些报表名原本被意译成中文（销售管道覆盖率 / 按负责人的赢单 …），没有任何翻译文件为它们背书（src/translations/zh-CN.ts 不含报表 label），一并归位为真 label —— 与 content/docs/analytics/reports.zh-Hans.mdx:23 的既有写法一致，不另造名。这一条也覆盖 zh 的 :85：en 的 Pipeline Coverage 本就正确无需动，zh 同址的意译名则需要归位，三语才真正同步。

三、:94 括号里的 top deals

• pipeline by stage → 真磁贴 Pipeline by Stage（src/dashboards/shared-widgets.ts:32-36）✓ 逐字未动
• win rate → 真磁贴 Win Rate (12M)（src/dashboards/sales.dashboard.ts:143）✓ 逐字未动
• top deals → 不存在，且结构性不可能

仪表盘 table 绑定的是分析 dataset，只能聚合、列不出原始记录（ADR-0021）。src/dashboards/sales.dashboard.ts 第 5 行区（:243-:249）的注释记着这次替换：

// A dashboard `table` binds to an analytics cube and aggregates; it cannot
// list raw deals (ADR-0021). The previous "Top Open Opportunities" table
// selected only `opp_count` with no dimension — one summary row, not a deal
// ranking. Grouping open pipeline by owner yields a rep leaderboard (one
// row per rep). For a per-deal list, surface an object-bound ListView
// through app navigation (ADR-0017).

所以不是「改个名就行」。列表项改为真磁贴 Open Pipeline by Owner，并在列表后新增一段点名说清「为什么不可能有 top deals 磁贴」，把逐笔排行指向商机列表视图 —— 出处（Row 5 注释 + ADR-0021）一并写进正文。

验证

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

门	结果
pnpm validate	✓ Validation passed (1177ms)，exit 0
pnpm typecheck	exit 0，无输出
pnpm lint	13 warning(s), 14 suggestion(s)，均为既有项，exit 0
pnpm hygiene	✓ source hygiene clean，exit 0
pnpm build	✓ Build complete (1155ms)，exit 0
pnpm test -- --maxWorkers=2	Test Files 75 passed (75)／Tests 1757 passed, 1 skipped (1758)，exit 0

控制字节自扫：对三个 mdx 跑 grep -naP 扫 0x00-0x08 / 0x0b / 0x0c / 0x0e-0x1f 零命中；pnpm hygiene 的扫描面本身覆盖 content 与 .changeset（"255 files under src, test, e2e, scripts; the control-byte scan adds 448 under content, .changeset" → "✓ no raw control bytes in first-party files"）。

守卫盲区，如实报 predicted GREEN 并已实测：本页没有任何 guard 覆盖这两族词汇 —— test/docs-drift.test.ts 的磁贴/仪表盘规则只扫 content/docs/analytics/dashboards*.mdx（DOC_PAGES），test/docs-analytics-vocabulary.test.ts 虽 walk(DOCS_ROOT) 全树，但对全树只查 cubes/ 字样一条。两个套件单跑：

• 带缺陷（git stash 回到 origin/main 的三页）：Test Files 2 passed (2)｜Tests 73 passed (73)
• 已修：Test Files 2 passed (2)｜Tests 73 passed (73)

即两种状态同为绿。这不是「修好了所以绿」，而是这两族词汇根本不在任何门的扫描面上；同理，本次修好之后再漂回去也没有门会红。没有为本页新增 guard —— 那是独立的能力扩张，不在本单面内。

与刚合并的 #991 的兼容：#991 给 docs-drift 加了「产品文档里 src/<dir>/ 必须存在」的新规则，而本 PR 新增了三处这类引用（src/views/、src/apps/、src/dashboards/）。把 #991 版本的 docs-drift.test.ts 取到本分支上单跑：本页相关断言全过，6 条失败全部落在 for-developers.mdx 上 —— 那是本分支还没有 #991 同 PR 的页面修正所致，合并后即消失。

未起任何 dev server；worktree 已 git worktree remove。

面外发现（Prime Directive #10，均已另立且未指派）

• sales/pipeline-management :48-:51：看板列顶「两个数字（未加权 + 加权）」是假能力——kanban 只有一个 summarizeField，且绑的是 amount #992 —— 本页 :48-:51「看板列顶两个数字（未加权 + 加权）」是假能力：kanban 的 summarizeField 是单数可选字符串且绑 amount，看板每列只有一个数、且未加权。该条同时否证了 sales/pipeline-management 剩余的仪表盘/报表指称漂移：:34 的 Sales Dashboard「求和 Expected Revenue」是假能力，:68/:72 的报表表格四行名字对不上，:94 括号里的 top deals 磁贴不存在 #989 正文里「:51 已写对」这一支撑判断（见上文第一族的说明），本 PR 据此调整了 :34 的写法，但按面限未动 :48-:51。
• Sales 组两个非对象导航项被按侧边栏上没有的名字指称：sales/index :64/:65 的 *Sales Pipeline* / *Sales Dashboard*，sales/pipeline-management :38 的「sidebar shortcut Sales Pipeline」 #993 —— Sales 组两个非对象导航项被按侧边栏上没有的名字指称：content/docs/sales/index.mdx:64 / :65 的 Sales Pipeline / Sales Dashboard（后者是同一幻名的第三处），以及本页 :38 的「sidebar shortcut Sales Pipeline」—— 导航项真名分别是 Pipeline 与 Sales Performance；content/docs/sales/opportunities.mdx:122 已有正确口径可抄。

两条在开单前均已按关键词 + 文件路径检索过 open issues，无重复。

[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 3:21pm