docs(sales): 看板小节按实况重写 + sales/index 补 Account Workbench(#996 #997)

[yinlianghui]

Fixes #996
Fixes #997

/pm-dispatch R36 并单实施(主单 #996)。行号已在 fresh main(748002f0)重定位;PR #990 / #994 / #999 的落地行零回退——三份 diff 先读后改,#999 刚落地的 :40 首句、:50/:52 两段、index :63/:64 两条原样保留。

三语同步(en / zh-Hans / zh-Hant),src/ 零改动,content/docs/releases/ 未触碰。

---

#996 sales/pipeline-management 看板小节

① :40「7 columns — one per stage」——按证据边界重写

pipeline_kanban 自带过滤器(src/views/opportunity.view.ts),把两个已结束阶段整个排除在外:stage not_in ['closed_won', 'closed_lost']。

OPPORTUNITY_STAGE_OPTIONS 确有 7 项,但被过滤掉的两个阶段在这块板上永远拿不到一张卡;同处源码注释自述 "keeps all five active stages visible"。

证据边界:列究竟由 groupBy 字段的 picklist 选项生成(7 列、其中 2 列恒空)还是由数据生成(5 列),取决于 console 的 kanban 渲染器,不在本仓内。按裁定不断言具体渲染列数,改写为元数据可证的部分:

• 每个阶段一列、只放在飞交易;
• 只有五个活跃阶段可能有卡(逐个点名);
• 已结束的生意在 All Opportunities 与 Sales Performance 仪表盘;
• 明写「那两个已结束阶段是被画成空列还是不出现,是 console 的算绘选择,本应用的元数据并没有声明」。

沿用 content/docs/sales/opportunities.mdx 已有的保守口径(「one column per stage, open deals only」,不给数字)。

补充线索(未写入文档,仅供后续判断):翻读 node_modules/@objectstack/console 的 plugin-kanban-*.js,板列的取值链在 columns 缺省时落到 groupBy 字段的 options,指向「选项派生 = 7 列、2 列恒空」。但这是压缩过的第三方产物、且本次没有浏览器实测条件,不足以当作文档断言的依据,所以只作为 PR 记录留在这里,页面仍按上面的边界写。

② :42-:46 卡片字段——Owner avatar 是幻影

卡面字段由 kanban.columns 决定,只有四个(name / crm_account / amount / close_date);owner_id 只在视图顶层 columns 里。上面那份 console 产物同样印证:cardFields 在 kanban.columns 非空时就取它。

清单改为四条,并按 #927 / PR #932 的「说清真名在哪,不要默默删掉」惯例把 Owner 指回真正带它的两处:All Opportunities 的 Owner 列、Deal Cards 图库(gallery.visibleFields 含 owner_id)。注意 Open Deals 并没有 Owner 列,故未列入。

③ :85(原单写 :86,fresh main 位移一行)Pipeline Kanban 指称

Pipeline Kanban 是标识符 pipeline_kanban 的驼峰读法,产品里没有这个名字。「每日」行改为打开侧边栏条目 Pipeline(zh 作 销售管道 / 銷售管道),与同小节开头 #993 已归位的口径一致。en 页全页已无 Pipeline Kanban。

④ :48 强制力措辞(原单标「低置信,待核」)——核后改

核实结论:原单的怀疑成立。opportunity_stage_progression 的 severity 是 'warning'(src/objects/opportunity.object.ts),且 prospecting 的允许集不含 closed_won。

关键佐证不需要新探针——本仓已有页面把这件事写死过:

• content/docs/administration/state-machines.mdx:100 明写 "an opportunity can go from Prospecting straight to Closed Won",并说每次这样的写入「writes one warning to the server log and is then saved」;
• 同页 :22 的口径就是 "A declared route is advice, not a gate";
• test/status-state-machines.test.ts:68 已把五条状态机的 severity 钉为 'warning'。

也就是说这一处是两页互相矛盾,而错的是本页。措辞按既有口径统一改为「建议,不是闸门 / advice, not a gate」+「保存照样通过 / the save still goes through」,并链到 State Machines 页(zh 内链不带锚)。

---

#997 sales/index 的《Where to find things》

crm.app.ts 的 group_sales 有九个 children,本节只覆盖八个,漏掉第 3 项 Account Workbench(nav_account_workbench,ADR-0047 interface page,zh-CN label 客户工作台,es-ES / ja-JP 语言包同样有真 label)。同一问题 getting-started/quick-tour.mdx:53 已列全九项、且被 #960 守卫逐项钉死——两页对新读者答案不一致。

补法沿本节自身的结构:六个对象入口留在 · 那条,三个「打开的不是对象列表」的条目各占一行(Account Workbench 按源码顺序排在 Pipeline 之前),并说明它是什么——复用 All Accounts 视图的列/过滤/排序,加三个快捷筛选(行业、类型、负责人),刻意不提供视图管理与高级过滤,记录与 Accounts 相同。前导句补上分组规模「九个条目」。

沿 #932 / #942 / #938 / #927 的导航清单先例。

---

新增两道守卫(原单 #997 的建议项)

os validate 与 pnpm lint 都不打开 content/docs,所以检查必须落在断言所在处(#948 / #960 已写下的理由)。

test/docs-sales-index-navigation.test.ts(#997)

• exists ⇒ listed:三语逐项比对本节与 group_sales;
• 六个对象入口在 zh 页是译名,无法按英文 label 比,改钉数量(任何语言下多一个对象入口都会红),en 页额外逐个 label 校验;
• 三个非对象条目每种语言都写了英文 label(en 裸写、zh 在括号里),故三语都按 label 校验;
• 前导句的分组规模必须与 group_sales 一致;
• 源码侧钉住:九个 children 的顺序、六/三 的切分、nav_account_workbench 紧跟 nav_account 且绑 account_workbench、该页 interfaceConfig 复用 all_accounts、三份语言包都给了 label。

切分口径注意:nav_pipeline 的 type 也是 'object',但它钉了 viewName(落在某个具体看板视图而非商机列表),所以判据是「type 为 object 且无 viewName」而不是单看 type——第一版按 type 切分被测试当场判红,已修正并把理由写进注释。

test/docs-pipeline-kanban-section.test.ts(#996)

• 卡片 bullet 数与 kanban.columns 长度严格相等;
• 本节必须点名被过滤掉的两个 stage 值与「五个活跃阶段」;
• 必须带 advisory 措辞与规则名 opportunity_stage_progression;
• 节奏表「每日」行必须点名侧边栏条目;
• 四条 retired 断言不得复活(en 页 Pipeline Kanban 为全页禁);
• 源码侧反向钉住:把 owner_id 绑上卡面、拿掉板上的过滤器、把规则提到 error,或给 Sales 组加条目,文档都会跟着元数据一起红。

---

反向验证(方向为先判后跑:预测 RED,实测 RED)

git stash push -- content/docs/ 把六份正文退回 main、只留新守卫:

Test Files  2 failed (2)
     Tests  24 failed | 15 passed (39)

24 条红全部落在读文档的用例上;仍绿的 15 条正是不读文档的 "source facts" 块——方向与预测一致,没有出现空断言式的假绿。恢复正文后 39/39 全绿。

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

门	退出码	关键行
pnpm validate	0	Data: 17 Objects 344 Fields,仅既有 5 条 author-time 警告
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(扫描面含 content / .changeset)
pnpm build	0	✓ Build complete,dist/objectstack.json (1921.3 KB)
pnpm test -- --maxWorkers=2	0	Test Files 77 passed (77) / Tests 1811 passed | 1 skipped (1812)

pnpm test 输出里那几行 ✗ source hygiene failed: … 是 test/source-hygiene-scan-surface.test.ts 故意走失败路径的 stdout,不是失败断言——该文件计入 77 passed。

守卫盲区如实报:#960(docs-quick-tour-navigation)与 #987 的守卫都不读这两页本面行,单跑确认本次改动不触发它们,predicted GREEN 且实测 GREEN(随全量 77 文件一起绿)。

其他

• changeset:.changeset/sales-pipeline-kanban-section-and-account-workbench.md(站内路径用反引号)。
• push 前用 grep -naP 对六份 mdx、两份测试与 changeset 做控制字节自扫,结果干净;pnpm hygiene 的控制字节门同样绿(扫描面已含 content 与 .changeset)。
• 未起 dev server,无遗留进程。
• ⚠️ 面内行中未出现需要改动的 Copilot 称谓;Sales Copilot 在健康信号与节奏表里原样保留,留给 R37 的 Docs drift (round 2 leftovers): ~39 product pages still name "Sales/Service Copilot" as a persona; config comment and RELEASE_STRATEGY.md still stale #612 全站扫。
• SLA policy matrix: per-priority × tier clocks, first-response stamping, escalation that reassigns #595 未预判,未越界。

[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 5:33pm