Skip to content

docs(marketing): name Products in the index page's "Where to find things" (#938) - #942

Merged
yinlianghui merged 1 commit into
mainfrom
claude/issue-938-marketing-nav
Aug 6, 2026
Merged

docs(marketing): name Products in the index page's "Where to find things" (#938)#942
yinlianghui merged 1 commit into
mainfrom
claude/issue-938-marketing-nav

Conversation

@yinlianghui

@yinlianghui yinlianghui commented Aug 6, 2026

Copy link
Copy Markdown
Collaborator

Fixes #938

《Where to find things》这一节是给新读者指路的，它说 Marketing 分组只有一项。实际是两项。

前提复核（fresh main = 11f62429）

Issue 的基线是 4855d50b，我在 origin/main 上重新定位，行号与断言全部成立：

  • src/apps/crm.app.ts:120-:128 的 group_marketing 恰有两个 children——nav_campaign（label Campaigns）与 nav_product（label Products，:126）。
  • content/docs/marketing/index.mdx:70-:76 的清单只列了 Campaigns；index.zh-Hans.mdx / index.zh-Hant.mdx 同址同形（:74）。

前提成立，未过期。

分组 children 全量核对结果

按裁定「核对该分组全部 children，漏项/假项一并按实况处理」，逐条比对如下：

crm.app.ts 里的 child 文档原状 处置
nav_campaign → crm_campaign，label Campaigns 已列，label 正确 保留，补上对象名
nav_product → crm_product，label Products 漏列 补上

没有第三个 child，也没有假项——本页的问题是纯粹的「少一项」，方向与 #927 / PR #932 相反（那边是列了不存在的东西）。所以本 PR 不需要 #932 那样的「不静默删名」段落：没有名字需要被保留指向。

一并写实的两条源码事实

  1. nav_product 是 crm_product 在整个应用里唯一的侧边栏入口——grep -rn "crm_product" src/apps/ 只返回 crm.app.ts:126 这一行。但 issue 正文里「除此之外只能从报价/商机的明细行反查」这句话我没有照抄：crm_product 声明了 searchableFields: ['name', 'product_code', 'sku']（src/objects/product.object.ts:27），全局搜索是能找到产品记录的。所以文档写成「除了这一项和全局搜索之外，只能从报价或商机的明细行反查」——另两条路径是 crm_quote_line_item:62 与 crm_opportunity_line_item:69 的 crm_product lookup。

  2. group_marketing 默认折叠。 它没有声明 expanded，而 Sales / My Work / Activity / Service 四个分组都写了 expanded: true；GroupNavItemSchema 里 expanded: z.boolean().default(false)（node_modules/@objectstack/spec/dist/index.js）。这正是 issue 描述的失效路径——分组是收起来的，文档又说里面只有 Campaigns，读者就不会点开去看。所以这一节现在明说：先把分组点开，再判断东西在不在。

产品目录自己的文档页在 content/docs/revenue/products，所以新条目链过去，而不是把内容复制进 Marketing。

面与边界

验证

六道门在共享锁 flock -w 7200 /tmp/os-heavy-verify.lock 内串行跑完，全绿：

validate  exit=0
typecheck exit=0
lint      exit=0
hygiene   exit=0   （含 no raw control bytes，扫描 content/ 与 .changeset/ 共 429 个文本文件）
build     exit=0
test      exit=0   （Test Files 70 passed，Tests 1602 passed | 1 skipped）

全绿是事先预测的结果，不是本次改动的功劳。 这是守卫盲区：仓库里没有任何一道门把《Where to find things》的清单与 crm.app.ts 的 navigation 对读——docs-drift.test.ts 只钉 flow 阈值，docs-object-coverage.test.ts 只管对象是否有文档页。证据是 main 本身：11f62429 带着这份错清单合入，六道门当时同样全绿。所以这一类缺陷只能靠人/agent 读源码发现，绿不能当作正确性证据。

push 前另做了控制字节自扫（grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]'，四个改动文件均无命中）。未起 dev server。

Generated by Claude Code

@claude
docs(marketing): name Products in the index page's "Where to find thi…
f3985d9 
…ngs" (#938)

The section that tells a new reader where to click said the **Marketing**
group holds one item. It holds two.

Measured against `src/apps/crm.app.ts:120-128`, `group_marketing` has exactly
two children: `nav_campaign` (Campaigns) and `nav_product`, labelled
**Products** (`:126`). That second item is the product catalog's ONLY sidebar
entry anywhere in the app — `grep -rn "crm_product" src/apps/` returns that one
line — so a reader looking for the catalog under Marketing, told the group held
Campaigns alone, had no reason to expand it. Everything else about the list
survived the read: the Campaigns label is right and no phantom item was named,
so this is purely the missing entry, the direction opposite to #927 / PR #932.

Two further facts from source are recorded with it. `crm_product` carries
`searchableFields` (`src/objects/product.object.ts:27`) and is looked up from
`crm_quote_line_item:62` and `crm_opportunity_line_item:69`, which are the only
other routes to a product record — so the page says that rather than implying
the sidebar item is the sole way in. And `group_marketing` declares no
`expanded` flag while Sales, My Work, Activity and Service all set
`expanded: true`; `GroupNavItemSchema.expanded` defaults to `false`, so this
group is collapsed on load. That is exactly the failure mode the issue
describes, so the page now says to open the group before concluding something
is absent.

The catalog's own pages live under `content/docs/revenue/products`, so the new
bullet links there instead of duplicating the content into Marketing.

All three locales, same lines; zh internal links carry no anchor. `src/`
untouched — no product decision is taken here (#595 / #596 stay open).

Fixes #938

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHrPAGEgFDoHjphqYG4BMa
@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 12:47pm

Request Review

This was referenced Aug 6, 2026
Closed
Closed
@yinlianghui
yinlianghui marked this pull request as ready for review August 6, 2026 12:50
@yinlianghui
yinlianghui added this pull request to the merge queue Aug 6, 2026
@yinlianghui yinlianghui mentioned this pull request Aug 6, 2026
Closed
Merged via the queue into main with commit 2a03ca2 Aug 6, 2026
9 checks passed
This was referenced Aug 6, 2026
Closed
Merged
Closed
Closed
Merged
Closed
Closed
Merged
yinlianghui added a commit to yinlianghui/hotcrm that referenced this pull request Aug 10, 2026
@yinlianghui @claude
docs(revenue): write the index page's "Where to find things" section …
2b750ff 
…to the real navigation (objectstack-ai#943) (objectstack-ai#953)

The section that tells a reader where to click named four things; three of them
do not survive a read of `src/apps/crm.app.ts`, and the one that does was
labelled with a name the app never shows.

Measured against `src/apps/crm.app.ts` on `origin/main` (b7791ca, platform
17.0.0-rc.3), the app has seven groups — Sales, My Work, Activity, Marketing,
Service, Insights, Approvals — and none of them is **Products**. The catalog's
only sidebar entry anywhere is `nav_product`, labelled **Products**, under
`group_marketing` (`:126`); `grep -rn "crm_product" src/apps/` returns that one
line. So the page now sends a reader arriving with the name "Products group" to
Marketing instead of to a place that does not exist, and links the Marketing
overview page that objectstack-ai#938 / PR objectstack-ai#942 just brought in line.

`group_approvals` (`:159-171`) has exactly one child: `nav_approval_requests`,
whose label is **Inbox** (`:165`) — not *Approval Requests*, which no metadata
in this repo carries. The other two listed items are re-judged individually
rather than deleted silently, per the objectstack-ai#870 / objectstack-ai#877 / objectstack-ai#885 / objectstack-ai#894 / objectstack-ai#913 / objectstack-ai#924 /
objectstack-ai#932 / objectstack-ai#942 convention:

- **Action History** — no nav item of that name exists. The data behind it does:
  @objectstack/plugin-approvals registers `sys_approval_action` (enumerated from
  the installed package, alongside `sys_approval`, `sys_approval_approver`,
  `sys_approval_delegation`, `sys_approval_request`, `sys_approval_token`), and
  nothing in this app's navigation opens it. The page says exactly that.
- **Processes** — deleted on purpose, and the source records why at `:166-169`:
  no `sys_approval_process` object exists in any installed plugin, so the old
  item's `requiresObject` guard hid it on every install, forever. The enumeration
  above confirms the absence, so the reason is written into the page.

The one true claim survives unchanged: **Contracts** is under **Sales**
(`nav_contract`, `:60`), and it is the app's only sidebar route to a contract.
Two further facts from source are recorded with it: `group_marketing` and
`group_approvals` declare no `expanded` key while Sales, My Work, Activity and
Service set `expanded: true`, and `GroupNavItemSchema.expanded` defaults to
`false` — so both groups are collapsed on load, which is the failure mode that
sends a reader looking for the catalog away empty-handed. And the zh-Hans page
names the label a simplified-Chinese user actually sees, 待我审批
(`src/translations/zh-CN.ts:1219`), next to the source label.

Product questions stay open on purpose (objectstack-ai#595 / objectstack-ai#596): whether Products deserves
its own group and whether Approvals should gain an audit-trail item are product
decisions, not documentation ones. Only the current shape is recorded.

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

Fixes objectstack-ai#943


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

Co-authored-by: Claude <noreply@anthropic.com>
yinlianghui added a commit to yinlianghui/hotcrm that referenced this pull request Aug 10, 2026
@yinlianghui @claude
docs(getting-started): write the quick tour's navigation table to the…
02fb379 
… real app (objectstack-ai#960) (objectstack-ai#968)

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 objectstack-ai#927 / PR objectstack-ai#932
  and objectstack-ai#937 / PR objectstack-ai#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 objectstack-ai#938 / PR objectstack-ai#942 and
  objectstack-ai#943 / PR objectstack-ai#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;
  objectstack-ai#943 / PR objectstack-ai#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 objectstack-ai#870 / objectstack-ai#877 / objectstack-ai#885 / objectstack-ai#894 / objectstack-ai#913 / objectstack-ai#924 / objectstack-ai#932 / objectstack-ai#942
/ objectstack-ai#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 (objectstack-ai#595 / objectstack-ai#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 objectstack-ai#960

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

Co-authored-by: Claude <noreply@anthropic.com>
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

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

marketing/index 的《Where to find things》(:74) 只列了 Campaigns，漏掉 Marketing 分组里真实存在的 Products（crm.app.ts:126）

2 participants

@yinlianghui @claude