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

.changeset/pipeline-management-dashboard-and-report-names.md

@@ -0,0 +1,57 @@
+---
+'hotcrm': patch
+---
+
+Write the sales pipeline page's remaining dashboard and report references to what
+the app actually ships — one phantom capability, four wrong report names, and a
+tile that cannot exist.
+
+`content/docs/sales/pipeline-management.mdx` (and both zh pages) carried three
+separate drifts, all of which sent a reader looking for something that is not
+there.
+
+**The weighted forecast is a list-view total, not a dashboard number.** The page
+told a sales manager that a *Sales Dashboard* "sums Expected Revenue across the
+open pipeline". Neither half held. There is no dashboard by that name — the real
+one is `sales_dashboard`, labelled **Sales Performance**, the same phantom #985
+removed from the roll-up list one section further down. And no dashboard widget
+can sum expected revenue at all: the `opportunity_metrics` dataset in
+`src/datasets/opportunity.dataset.ts` declares no measure over
+`expected_revenue`, and every amount measure it does expose (**Total Amount**,
+**Avg Deal Size**, **Won Revenue**, **Lost Revenue**) reads the raw `amount`
+field. The **Total Pipeline** tile is therefore the *unweighted* open pipeline,
+and a reader who took the page at its word was reading a number short of a
+probability coefficient while being told it was the weighted forecast. Where the
+weighted sum genuinely lives is the opportunity list views: **Open Deals** and
+**All Opportunities** each declare
+`{ field: 'expected_revenue', summary: 'sum' }` in
+`src/views/opportunity.view.ts`, which is how
+`content/docs/sales/opportunities.mdx` already describes them. The page now says
+that, and says plainly why the dashboard cannot match it.
+
+**The reports table named a sidebar group that does not exist and four reports
+by names nothing carries.** The group is **Insights**
+(`src/apps/crm.app.ts`), not *Reports*, and it pins three reports — Pipeline
+Coverage, Lead Inflow, SLA Performance — beside the CRM Overview dashboard and
+Forecasts, so only the first row of the table is reachable from the nav at all;
+the rest open from the reports screen. The four drifted rows now carry the
+labels `src/reports/opportunity.report.ts` declares — **Pipeline Coverage by
+Forecast × Quarter**, **Opportunity Funnel by Owner → Stage**, **Won
+Opportunities by Owner** — and the coverage row's axes are stated the way #985
+just landed them one section below (forecast category down the rows, close
+quarter across the columns) instead of the transposed *quarter × stage*. The
+same truncated names in the cadence table and the manager tips were completed to
+match, including the zh pages' invented Chinese report names, which no
+translation file backs.
+
+**There is no *top deals* tile, and there cannot be one.** The roll-up list
+named three Sales Performance widgets; two are real (**Pipeline by Stage**,
+**Win Rate (12M)**) and the third was removed on purpose. A dashboard `table`
+binds to an analytics dataset and can only aggregate — it cannot list raw
+records (ADR-0021) — so the old **Top Open Opportunities** table produced one
+summary row rather than a deal ranking and was replaced by **Open Pipeline by
+Owner**. The Row 5 comment in `src/dashboards/sales.dashboard.ts` records the
+swap; the page now states it and points a reader wanting a deal-by-deal ranking
+at an opportunity list view.
+
+Docs only — no `src/` change.

content/docs/sales/pipeline-management.mdx

@@ -31,7 +31,9 @@ You can override the probability manually on an individual deal if you have a sp
 
 This number is the heart of the weighted forecast. It's recalculated automatically every time the amount or probability changes (including the auto-updates from stage changes).
 
-The **Sales Dashboard** sums *Expected Revenue* across the open pipeline to give you the weighted forecast for the quarter.
+The weighted forecast is a **list-view total, not a dashboard number**. The **Open Deals** and **All Opportunities** views on Opportunities each carry an *Expected Revenue* column with a column sum (`src/views/opportunity.view.ts`), and that sum over the open pipeline is the weighted forecast.
+
+No dashboard can give you the same figure. The **Sales Performance** dashboard (`sales_dashboard`) reads the `opportunity_metrics` dataset, and that dataset declares **no measure over `expected_revenue`** — every amount measure it exposes (*Total Amount*, *Avg Deal Size*, *Won Revenue*, *Lost Revenue*) reads the raw `amount` field. So its *Total Pipeline* tile is the **unweighted** open pipeline; the two numbers differ by the probability weighting, which is the whole point of the calculation above.
 
 ## The pipeline kanban view
 
@@ -65,14 +67,14 @@ The Sales Copilot surfaces at-risk deals when you ask *"what's slipping?"* or *"
 
 ## Pipeline reports worth bookmarking
 
-You'll find these in the **Reports** section of the sidebar:
+Only the first of these is on the sidebar. There is no *Reports* group: the reports group is called **Insights** (`src/apps/crm.app.ts`), and it pins three reports — **Pipeline Coverage**, **Lead Inflow** and **SLA Performance** — alongside the **CRM Overview** dashboard and **Forecasts**. The other four below are opened from the reports screen. Names here are the labels the report library lists, which is not always the shorter name on the nav entry.
 
 | Report | What it shows |
 | --- | --- |
-| **Pipeline Coverage (Quarter)** | Are we covering 3x the quota for the upcoming quarter? Matrix of quarter × stage. |
-| **Funnel by Owner → Stage** | Per-rep funnel health — spot leaky stages. |
+| **Pipeline Coverage by Forecast × Quarter** | Are we covering 3x the quota for the upcoming quarter? A matrix of open pipeline: forecast category down the rows, close quarter across the columns. The sidebar entry for it reads **Pipeline Coverage**. |
+| **Opportunity Funnel by Owner → Stage** | Per-rep funnel health — spot leaky stages. |
 | **Opportunities by Stage** | Bar chart of pipeline by stage. |
-| **Won by Owner** | Leaderboard for quarter-end recognition. |
+| **Won Opportunities by Owner** | Leaderboard for quarter-end recognition. |
 | **Customer Churn Signals** | Open cases + low NPS on existing customers = churn risk. |
 
 See [Analytics › Reports](/docs/analytics/reports) for details.
@@ -83,19 +85,21 @@ See [Analytics › Reports](/docs/analytics/reports) for details.
 | --- | --- |
 | **Daily** | Open Pipeline Kanban. Find stalled cards (in-stage > 14 days). Push or close. |
 | **Weekly** | Run *Pipeline Coverage*. Ask the Sales Copilot: *"what's at risk?"* |
-| **Monthly** | Run *Funnel by Owner → Stage*. Coach reps with leaky stages 1:1. |
-| **Quarter-end** | Run *Won by Owner* for commissions. Archive lost deals with a *loss reason*. |
+| **Monthly** | Run *Opportunity Funnel by Owner → Stage*. Coach reps with leaky stages 1:1. |
+| **Quarter-end** | Run *Won Opportunities by Owner* for commissions. Archive lost deals with a *loss reason*. |
 
 ## Forecasting roll-up
 
 The Sales Manager / Director view of the forecast is built from:
 
 - The **Opportunity Metrics** dataset (`opportunity_metrics`) — measure **Total Amount** (sum of amount), dimension **Stage**
-- The **Sales Performance** dashboard (`sales_dashboard`) — widgets for pipeline by stage, win rate, top deals
+- The **Sales Performance** dashboard (`sales_dashboard`) — widgets for pipeline by stage, win rate, and open pipeline by owner
 - The **Pipeline Coverage** report (`pipeline_coverage_by_quarter`, whose own label reads **Pipeline Coverage by Forecast × Quarter**) — a matrix of open pipeline: forecast category down the rows, close quarter across the columns
 
 Together they answer: *"do we have enough pipeline to make the quarter, and where are the risks?"*
 
+What that dashboard will not give you is a *top deals* ranking, and no renaming would fix it: a dashboard table binds to an analytics dataset and can only aggregate — it cannot list raw records (ADR-0021). The **Top Open Opportunities** table that once held that slot was replaced by **Open Pipeline by Owner**, a per-rep ranking, for exactly that reason; the Row 5 comment in `src/dashboards/sales.dashboard.ts` records the swap. For a deal-by-deal ranking, open an opportunity list view.
+
 ## Tips for sales reps
 
 - ✅ Move stage promptly — your forecast is wrong if your stage is wrong.
@@ -104,8 +108,8 @@ Together they answer: *"do we have enough pipeline to make the quarter, and wher
 
 ## Tips for sales managers
 
-- ✅ Run *Funnel by Owner → Stage* monthly to catch reps with leaky funnels.
-- ✅ Use *Pipeline Coverage by Quarter* in QBRs to set the next quarter's targets.
+- ✅ Run *Opportunity Funnel by Owner → Stage* monthly to catch reps with leaky funnels.
+- ✅ Use *Pipeline Coverage* in QBRs to set the next quarter's targets.
 - ✅ Coach reps to fill in *Competitors* — it dramatically improves Copilot quality.
 
 ## Tips for admins

content/docs/sales/pipeline-management.zh-Hans.mdx

@@ -31,7 +31,9 @@ description: 销售管道的日常运作方式——推进交易、自动概率
 
 这个数字是加权预测的核心。每当金额或概率变化时（包括来自阶段变化的自动更新），它都会自动重新计算。
 
-**销售仪表盘**会在开放销售管道上对*预期营收*求和，从而给你本季度的加权预测。
+加权预测是**列表视图上的合计，不是仪表盘上的数字**。商机的**进行中商机**与**全部商机**两个视图各带一列*预期营收*并对该列求和（`src/views/opportunity.view.ts`），这个在开放管道上的合计就是加权预测。
+
+仪表盘给不出同一个数。**Sales Performance** 仪表盘（`sales_dashboard`）读的是 `opportunity_metrics` dataset，而该 dataset **没有任何度量读 `expected_revenue`** —— 它暴露的金额类度量（*Total Amount*、*Avg Deal Size*、*Won Revenue*、*Lost Revenue*）一律读原始的 `amount` 字段。所以它的 *Total Pipeline* 磁贴是**未加权**的在飞管道；两个数字之间差的正是上面这层概率加权。
 
 ## 销售管道看板视图
 
@@ -65,15 +67,15 @@ description: 销售管道的日常运作方式——推进交易、自动概率
 
 ## 值得收藏的销售管道报告
 
-你会在侧边栏的**报告**部分找到这些：
+这五张里只有第一张在侧边栏上。侧边栏没有*报告*分组：报表所在的分组叫 **Insights**（`src/apps/crm.app.ts`），它钉了三张报表 —— **Pipeline Coverage**、**Lead Inflow**、**SLA Performance** —— 外加 **CRM Overview** 仪表盘与 **Forecasts**。下面其余四张要从报表界面进。这里用的是报表库列出的 label，它未必等于导航项上那个更短的名字。
 
 | 报告 | 它显示什么 |
 | --- | --- |
-| **销售管道覆盖率（季度）** | 我们对即将到来的季度是否覆盖了 3 倍配额？季度 × 阶段矩阵。 |
-| **按负责人 → 阶段的漏斗** | 每位销售代表的漏斗健康——发现漏水的阶段。 |
-| **按阶段的商机** | 按阶段的销售管道柱状图。 |
-| **按负责人的赢单** | 用于季末表彰的排行榜。 |
-| **客户流失信号** | 现有客户的开放案例 + 低 NPS = 流失风险。 |
+| **Pipeline Coverage by Forecast × Quarter** | 我们对即将到来的季度是否覆盖了 3 倍配额？未结管道的矩阵：行是预测类别，列是预计成交季度。它在侧边栏上的导航项写作 **Pipeline Coverage**。 |
+| **Opportunity Funnel by Owner → Stage** | 每位销售代表的漏斗健康——发现漏水的阶段。 |
+| **Opportunities by Stage** | 按阶段的销售管道柱状图。 |
+| **Won Opportunities by Owner** | 用于季末表彰的排行榜。 |
+| **Customer Churn Signals** | 现有客户的开放案例 + 低 NPS = 流失风险。 |
 
 详情参见 [Analytics › Reports](/zh-Hans/docs/analytics/reports)。
 
@@ -82,20 +84,22 @@ description: 销售管道的日常运作方式——推进交易、自动概率
 | 节奏 | 该做什么 |
 | --- | --- |
 | **每日** | 打开销售管道看板。找出停滞的卡片（阶段内 > 14 天）。推进或关闭。 |
-| **每周** | 运行*销售管道覆盖率*。向 Sales Copilot 提问：*"what's at risk?"* |
-| **每月** | 运行*按负责人 → 阶段的漏斗*。对漏斗漏水的销售代表进行一对一辅导。 |
-| **季末** | 运行*按负责人的赢单*以计算提成。归档*失败*的交易并附上*丢单原因*。 |
+| **每周** | 运行 *Pipeline Coverage*。向 Sales Copilot 提问：*"what's at risk?"* |
+| **每月** | 运行 *Opportunity Funnel by Owner → Stage*。对漏斗漏水的销售代表进行一对一辅导。 |
+| **季末** | 运行 *Won Opportunities by Owner* 以计算提成。归档*失败*的交易并附上*丢单原因*。 |
 
 ## 预测汇总
 
 销售经理 / 总监的预测视图由以下部分构建：
 
 - **Opportunity Metrics** dataset（`opportunity_metrics`）—— 度量 **Total Amount**（金额之和），维度 **Stage**
-- **Sales Performance** 仪表盘（`sales_dashboard`）—— 小部件包括按阶段的销售管道、赢单率、顶级交易
+- **Sales Performance** 仪表盘（`sales_dashboard`）—— 小部件包括按阶段的销售管道、赢单率、按负责人的在飞管道
 - **Pipeline Coverage** 报告（`pipeline_coverage_by_quarter`，报表自身的 label 写作 **Pipeline Coverage by Forecast × Quarter**）—— 未结管道的矩阵：行是预测类别，列是预计成交季度
 
 它们共同回答：*"我们是否有足够的销售管道来完成本季度，以及风险在哪里？"*
 
+这块仪表盘给不了的是*顶级交易*那种逐笔排行，改个名字也解决不了：仪表盘的 table 绑定的是分析 dataset，只能做聚合，列不出原始记录（ADR-0021）。原先占着这个位置的 **Top Open Opportunities** 表正是因此被换成了按负责人聚合的 **Open Pipeline by Owner** —— `src/dashboards/sales.dashboard.ts` 里 Row 5 的注释记下了这次替换。要逐笔的交易排行，请改用商机列表视图。
+
 ## 给销售代表的提示
 
 - ✅ 及时推进阶段——如果你的阶段错了，你的预测就是错的。
@@ -104,8 +108,8 @@ description: 销售管道的日常运作方式——推进交易、自动概率
 
 ## 给销售经理的提示
 
-- ✅ 每月运行*按负责人 → 阶段的漏斗*，以发现漏斗漏水的销售代表。
-- ✅ 在 QBR 中使用*按季度的销售管道覆盖率*来设定下一季度的目标。
+- ✅ 每月运行 *Opportunity Funnel by Owner → Stage*，以发现漏斗漏水的销售代表。
+- ✅ 在 QBR 中使用 *Pipeline Coverage* 来设定下一季度的目标。
 - ✅ 辅导销售代表填写*竞争对手*——它能显著提升 Copilot 的质量。
 
 ## 给管理员的提示