Skip to content

docs(getting-started): write the quick tour's navigation table to the real app (#960) - #968

Merged
yinlianghui merged 1 commit into
mainfrom
claude/issue-960-quick-tour-nav
Aug 6, 2026
Merged

docs(getting-started): write the quick tour's navigation table to the real app (#960)#968
yinlianghui merged 1 commit into
mainfrom
claude/issue-960-quick-tour-nav

Conversation

@yinlianghui

@yinlianghui yinlianghui commented Aug 6, 2026

Copy link
Copy Markdown
Collaborator

Fixes #960

《快速上手》里那张导航表——新用户读到的第一张表,而它的全部作用就是"告诉你左边有什么"——8 行全部失实。基线复核在 fresh main 4705aed5(平台 17.0.0-rc.3)上重做,issue 正文的每一条都成立,行号按当前 main 重新定位。

逐行复核(对照 src/apps/crm.app.ts)

navigation 的真实形状:1 个顶层固定条目 + 7 个分组——nav_home(Home,:34)、group_sales(:42)、group_work(My Work,:69)、group_activity(Activity,:103)、group_marketing(:120)、group_service(:131)、group_insights(Insights,:144)、group_approvals(:160)。

表中原行 复核结论
Sales 分组真实,但 children 是 9 项不是 6 项——漏 Account Workbench(:52)、Pipeline(:55)、Sales Performance(:61)
Service 分组真实;Knowledge Base 的真实 label 是 Knowledge(:138),且漏 Service Overview(:139)——两个名字 #927 / PR #932 与 #937 / PR #947 已在 service/index 上写实,两页此前互相打架
Marketing 分组真实,children 是 Campaigns(:125) + Products(:126);Campaign Members 根本不是导航条目(grep -rn "crm_campaign_member" src/apps/ 零命中)
Products 分组不存在。真身是 group_marketing 的 child nav_product——#938 / PR #942、#943 / PR #953 已两次写过同一处
Activities 分组不存在,真实的叫 Activity;crm_task 也不在里面,它的两个入口是 My Tasks(:84)与 All Tasks(:93),都在 My Work 下——而 My Work 这个销售代表每天真正用的分组,整表一次都没出现
Analytics 分组不存在,真实的叫 Insights;全仓没有任何条目 label 是 Dashboards 或 Reports
AI 分组不存在;src/apps/ 只有一个文件,里面既无 Copilot 也无 Knowledge Bases
Approvals 分组真实,但只有 1 个 child,label 是 Inbox(:165);Approval Requests 与 Action History 在本仓无任何 metadata——#943 / PR #953 已记录过同样两个名字

改了什么

表格改为 nav_home + 7 个真实分组,children 按源码顺序逐项抄平。消失的名字不静默删除,沿 #870 / #877 / #885 / #894 / #913 / #924 / #932 / #942 / #953 的口径逐个点名去向:产品目录是 Marketing 下的 Products;任务是 My Work 下的 My Tasks / All Tasks;Copilot 是每页右侧聊天面板(本页第 6 节);营销活动成员经营销活动详情页或全局搜索进入;审批操作留痕是真实数据(sys_approval_action),但没有任何导航条目能打开它。

另记录两条源码事实:group_marketing / group_insights / group_approvals 未声明 expanded,而 GroupNavItemSchema.expanded 默认 false,所以这三组加载时是收起的——这正是让读者误以为"东西不在"的失败模式(#942 / #953 已在各自页面写过)。zh 两页补出简中界面实际显示的译名(待我审批 / 知识库 / 我的工作,src/translations/zh-CN.ts:1195-1219),这也解释了英文侧 Knowledge Base 为何长期读起来"像对的"。

#595 / #596 不预判:该不该有 Products 或 AI 分组是产品决定,本 PR 只记录当前形状。三语同步;zh 内链不带锚;src/ 零改动;未动 releases/、未动 @objectstack/* 版本。

新增守卫

test/docs-quick-tour-navigation.test.ts——此前没有任何东西检查这张表:os validate 与 pnpm lint 只走 authored metadata,从不打开 content/docs。新守卫按 docs-service-index-analytics.test.ts(#948 / PR #955)的模式,三语各自:

  • 表格行与 CrmApp.navigation 逐分组、逐 child、按源码顺序全等比对(exists ⇒ listed);
  • 粗体只能是真实 label 或 Home 打开的那块仪表盘的 label(bold ⇒ real),斜体保留给"应用里不存在的名字"(docs(service): write the index page's 《Where to find things》 list to the real navigation (#927) #932 立下的排版约定),每个退役名字必须仍以斜体出现且永不粗体;
  • 默认折叠那句必须点到全部 collapsed 与 expanded 分组;
  • 另有一组 source-facts 断言把 prose 依赖的源码事实钉住(7 个分组的顺序、Home 绑 executive_dashboard、collapsed 集合、crm_task 只经 My Work、crm_campaign_member 无导航条目、四个逐字 label)。

验证

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

门 退出码 关键行
pnpm validate 0 通过(残留 warning 均为既有的 approval-approvers / field-group 提示,与本 PR 无关)
pnpm typecheck 0 tsc --noEmit 无输出
pnpm lint 0 13 warning(s), 14 suggestion(s),与 main 同
pnpm hygiene 0 ✓ no raw control bytes in first-party files(扫 252 + 438 个文件)
pnpm build 0 Artifact: dist/objectstack.json (1921.4 KB)
pnpm test -- --maxWorkers=2 0 Test Files 72 passed (72) / Tests 1652 passed | 1 skipped (1653)(main 为 71 个测试文件)

反向验证(方向预判为 RED,实测吻合):把三语的旧表原样恢复、只留新守卫,21 tests 中 15 failed | 6 passed——三语各 5 条文档侧断言全红,首条即 the table's group column must be every CrmApp group, in source order: expected [ '**Sales**', '**Service**', …(6) ] to deeply equal [ '**Sales**', '**My Work**', …(5) ];6 条 source-facts 断言保持绿,因为它们只读源码、与文档无关——这正是预期,若它们也变红说明守卫钉错了地方。恢复新表后 21 passed。

需要说明的是,这个 PR 之前的六道门对本类改动是盲的:纯 content/docs 文案改动在 main 上跑六道门,改前改后都是绿。新守卫就是把这块盲区补上,所以"守卫盲区"这一栏在本 PR 之后不再成立。

顺带发现(未在本 PR 修)

本页第 1 节首句仍称 "The first thing you see is the CRM Overview dashboard",但 nav_home 绑的是 executive_dashboard,其 label 为 Executive Overview(src/dashboards/executive.dashboard.ts:26);CRM Overview 是 group_insights 下另一条目 nav_crm_dashboard(:151)。不在本单的面(:35-:44 那张表)内,已另开 issue,留给 PM 三分类。

Generated by Claude Code

@claude
docs(getting-started): write the quick tour's navigation table to the…
a5df4ca 
… real app (#960)

The first table a new user reads, whose entire job is "here is what the sidebar
holds", had drifted in every one of its eight rows.

Measured against `src/apps/crm.app.ts` on `origin/main` (4705aed, platform
17.0.0-rc.3), the app's `navigation` is one pinned top-level entry plus seven
groups: `nav_home` (Home, :34), `group_sales` (:42), `group_work` (My Work,
:69), `group_activity` (Activity, :103), `group_marketing` (:120),
`group_service` (:131), `group_insights` (Insights, :144) and `group_approvals`
(:160). Row by row, the old table said:

- **Sales** — the group is real, but it carries nine children, not six. The
  table dropped Account Workbench (:52), Pipeline (:55) and Sales Performance
  (:61).
- **Service** — real; the entry the table called *Knowledge Base* is labelled
  **Knowledge** (:138), and **Service Overview** (:139) was missing. Both
  names were already written to source on `service/index` by #927 / PR #932
  and #937 / PR #947, so the two pages contradicted each other.
- **Marketing** — real, but its children are Campaigns (:125) and Products
  (:126). *Campaign Members* is not a navigation entry at all:
  `grep -rn "crm_campaign_member" src/apps/` returns nothing.
- **Products** — no such group. The catalog's only sidebar entry is
  `nav_product` under `group_marketing`, the same finding #938 / PR #942 and
  #943 / PR #953 already wrote to two other pages.
- **Activities** — no such group; the real one is **Activity**, and `crm_task`
  is not in it. Its two entries are My Tasks (:84) and All Tasks (:93), both
  under **My Work** — which the table never mentioned at all, though it is the
  group a rep uses every day.
- **Analytics** — no such group; the real one is **Insights**, and no entry
  anywhere is labelled *Dashboards* or *Reports*.
- **AI** — no such group anywhere in the repo, and no entry labelled *Copilot*
  or *Knowledge Bases*. `src/apps/` contains one file; neither name appears in
  it.
- **Approvals** — real, with exactly one child, labelled **Inbox** (:165).
  *Approval Requests* and *Action History* carry no metadata in this repo;
  #943 / PR #953 recorded the same two names on the revenue page.

So the table now lists the pinned Home entry and all seven groups with their
real children in source order, and every retired name is re-pointed rather than
deleted silently, per the #870 / #877 / #885 / #894 / #913 / #924 / #932 / #942
/ #953 convention. Two further facts from source ride along: `group_marketing`,
`group_insights` and `group_approvals` declare no `expanded` key while Sales,
My Work, Activity and Service set `expanded: true`, and
`GroupNavItemSchema.expanded` defaults to `false`, so those three are collapsed
on load — the failure mode that makes a reader conclude something is absent.
And the zh pages name the labels a simplified-Chinese user actually sees
(待我审批, 知识库, 我的工作 — `src/translations/zh-CN.ts:1195-1219`), which is
also why the old English *Knowledge Base* read plausibly for so long.

Nothing checked any of it: `os validate` and `pnpm lint` walk authored metadata
and never open `content/docs`. `test/docs-quick-tour-navigation.test.ts` now
compares the table to `CrmApp.navigation` group-for-group and child-for-child in
all three locales, pins the bold-is-real / italic-is-phantom typography the
sibling pages already use, and pins the source facts the prose rests on.
Restoring the old table turns 15 of its 21 assertions red in the predicted
direction.

Product questions stay open on purpose (#595 / #596): whether Products or AI
deserve their own groups is a product decision, not a documentation one. Only
the current shape is recorded.

All three locales, same section; zh internal links carry no anchor. `src/`
untouched.

Fixes #960

Claude-Session: https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa

Co-authored-by: Claude <noreply@anthropic.com>
@vercel

vercel Bot commented Aug 6, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated (UTC)
hotcrm Ignored Ignored Aug 6, 2026 2:01pm

Request Review

@github-actions github-actions Bot added the ci/cd CI plumbing and the verification pipeline label Aug 6, 2026
@yinlianghui yinlianghui mentioned this pull request Aug 6, 2026
Closed
@yinlianghui
yinlianghui marked this pull request as ready for review August 6, 2026 14:04
@yinlianghui
yinlianghui added this pull request to the merge queue Aug 6, 2026
Merged via the queue into main with commit 02fb379 Aug 6, 2026
10 checks passed
This was referenced Aug 6, 2026
Closed
Closed
Merged
Open
Merged
Closed
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

ci/cd CI plumbing and the verification pipeline

Projects

None yet

Milestone

No milestone

2 participants

@yinlianghui @claude