docs(getting-started): write the quick tour's landing section to the dashboard Home really opens (#971)

[yinlianghui]

Fixes #971

《快速上手》第 1 节（三语）整节按实况重写。这是新用户读到的第一段话，而它描述的是一块并不存在的"混合盘"——名字取自一块盘，5 条要点取自另外三块。

一、落地页认错了（issue ① — 成立）

src/apps/crm.app.ts:33-39 的 nav_home 是 type: 'dashboard' + dashboardName: 'executive_dashboard'，源码注释写明 "Pinned landing"。executive_dashboard 的 label 是 Executive Overview（src/dashboards/executive.dashboard.ts:26，zh-CN 语言包「高管总览」）。

页面说的 CRM Overview 是 crm_overview_dashboard（src/dashboards/crm.dashboard.ts:28），挂在 group_insights 下的 nav_crm_dashboard（crm.app.ts:151）；group_insights 未声明 expanded，默认收起 —— 新用户既不会"第一眼看到"它，默认也点不到。沿 #968/#975 口径：不静默删名，把 CRM Overview 的真身（Insights 分组下、默认收起、离你两次点击）点名写清楚。

同页第 2 节（PR #968 刚写实的导航表）本就写着 Home 打开 Executive Overview —— 同一页自相矛盾，而错的那半在最前面。#968 落地行零回退，第 2 节一个字未动。

二、5 条要点逐条对照（issue ② — 一条需要修正）

页面原要点	实况	处理
open leads	✅ Open Leads（executive.dashboard.ts:112）	保留，进磁贴表
opportunities in your pipeline	⚠️ 半对，不是全错 —— 本盘有 Pipeline by Stage	改写为"是金额、不是条数"，并指出计数磁贴 Active Deals 在 CRM Overview 上
cases awaiting your response	❌ 两块盘都无工单磁贴	归属 Service 下 Service Overview：Open Cases / Critical Cases / SLA Violations
Top accounts by pipeline value	❌ 全应用无此磁贴	说明 Accounts by Industry 是按行业归组；最接近的排名 Pipeline by Owner 是按销售代表排，不按客户
Recent activity (calls, meetings, emails)	❌ 两块盘都无互动磁贴	归属 Activity 下 Sales Activity：Interactions Logged / Meetings Booked / Customer Minutes

⚠️ issue 前提部分修正：本盘是 9 个磁贴，不是 8 个

issue 正文列了 8 个 widget title 并据此判定"本盘无商机/管道 tile"。这一条不成立。 pipeline_by_stage 来自共享工厂 pipelineByStageFunnelWidget（src/dashboards/shared-widgets.ts:32，#539 引入），在 executive.dashboard.ts:151 以函数调用落位，没有内联的 title: 字面量，所以按标题 grep 只能数到 8 个。运行期 ExecutiveDashboard.widgets 是 9 个，四个语言包也都为它注册了条目（src/translations/{en,zh-CN,es-ES,ja-JP}.ts），本仓已有守卫的 content/docs/analytics/dashboards.mdx:129 同样列着它。

所以"你的管道中有多少商机"是半对而非全错：管道磁贴在，但它画的是各阶段的进行中商机金额（funnel，total_amount），不是商机条数。新文案照此写实。

三、同节第三处失实（issue 未列，但在 issue 划定的 :10-20 面内）

原文末句"如果你是经理，你还会看到团队级汇总"描述的能力本应用没有：

• src/sharing/positions.ts:3-17 —— ADR-0090 D3，岗位扁平，无 parent，"可见性不会向上汇总"；role_and_subordinates 已移除。
• src/profiles/sales-manager.profile.ts:19-28 —— SalesManagerProfile 在销售栈上直接给 viewAllRecords: true，是全组织，不是"团队级"切片。

面在 issue 自己划的第 1 节内，重写整节却留一句已知假话说不过去，故一并写实；新增守卫把这两条源码事实钉住。

四、守卫

扩 PR #968 的 test/docs-quick-tour-navigation.test.ts（它已导入 CrmApp 与 ExecutiveDashboard），新增第 1 节两组断言，模式同 #948 的 docs-service-index-analytics.test.ts：

• exists ⇒ listed：ExecutiveDashboard.widgets 的每个 title 必须出现在本节 —— 断言走运行期对象而非文件文本，这正是能数到第 9 个工厂磁贴的原因（守卫里写明了这一点，并断言内联字面量恰好比运行期少 1 个，把 issue 数错的机制本身钉住）。
• listed ⇒ exists：每个加粗拉丁串必须解析到真实 widget title / dashboard label / nav label / dashboard 筛选器 label / 权限集 label。
• retired 名字不静默删：4 条退役声明必须仍以 斜体 点名、永不加粗；被删掉的旧句子不得回流。
• 负向声明的源码侧同样钉住：两块候选落地盘的 dataset 集合、dimension 集合按精确集合比对（新增维度即红，强制重读"无按管道价值排名的客户榜"这一句）；岗位扁平、sales manager viewAllRecords 一并钉住。

五、验证

六道门全绿，flock -w 7200 /tmp/os-heavy-verify.lock 内串行、NODE_OPTIONS=--max-old-space-size=4096：

validate  exit=0
typecheck exit=0
lint      exit=0   13 warning(s), 14 suggestion(s)  （均为既有 approval 警告）
hygiene   exit=0   ✓ no raw control bytes in first-party files（含 content/ 与 .changeset/ 443 个文件）
build     exit=0   Artifact: dist/objectstack.json (1921.4 KB)
test      exit=0   Test Files 73 passed (73) | Tests 1700 passed | 1 skipped (1701)

单跑本守卫：Tests 39 passed (39) —— #968 原有 21 条全部在列且绿（15 条 page 断言 + 6 条 source-fact），另 18 条为本 PR 新增（12 条 page × 3 语 + 5 条 source-fact + 1 条补入 #968 组的 CRM Overview 归属断言）。

反向验证（方向为事前预测，结果与预测一致）：把英文页第 1 节还原成 origin/main 的旧文案后重跑 —— 预测 #971 新守卫转红、#968 旧守卫保持绿（守卫盲区）。实测 Tests 4 failed | 35 passed (39)：转红的恰是英文页那 4 条 #971 断言；#968 的 21 条一条未动，因为它的 blockOf 只从 Inside Enterprise CRM, 读到下一个 ## ，从来看不到第 1 节 —— 这正是本节失实能一路带着绿 CI 活下来的原因，如实记录。zh-Hans / zh-Hant 的 #971 断言在该轮保持绿（只还原了英文页），侧面确认三语断言彼此独立。

src/ 零改动、@objectstack/* 版本零改动、content/docs/releases/ 未触碰；changeset 见 .changeset/quick-tour-landing-dashboard-real.md。未起 dev server。

---

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 2:36pm