docs(guide): 把 building-crud-app 的两条死链改指真实存在的文档页

[yinlianghui]

Fixes #3507

背景

content/docs/guide/building-crud-app.md 的 "Next Steps" 有两条指向 examples/todo、examples/crm 的 GitHub 绝对 URL。这两个目录在 12b287d8b(2026-05-02,"refactor: remove example Todo application and related files",一次删掉 80 个 examples/todo/、examples/crm/ 下的文件)里已随 Todo/CRM 示例一起移除,链接自那时起就是 GitHub 404,至今约三个月无人发现 —— 因为两个门禁按设计都看不见它:

• scripts/check-doc-links.mjs 跳过一切带 scheme 的 href(EXTERNAL_HREF_RE),外链归 lychee;
• lychee 是周 cron + 手动、且 continue-on-error,从不 gate PR(pnpm docs:check-links 在 main 上就退出 1,但没有任何工作流跑它(两个链接检查器都不拦 PR) #3213 的有意取舍)。

这是 #3486/#3495 修 examples/hello-world/README.md 里 ../crm/、../todo/ 两条死链的同源问题在文档站这一侧的残留:同一次示例删除,README 那侧已修,docs 这侧漏了。

改动

只动两行 link,标签按真实目标如实改写,不假装存在一个等价的示例 app(沿用 #3506 把 Example: CRM Application 改成 Example: ObjectStack Console Starter、以及 #3495 "描述取自各自 README,未臆造" 的口径):

行	原目标(404)	新目标	为什么是它
328	examples/todo	/docs/plugins/plugin-kanban	该 bullet 承诺的是 "Add a Kanban board view using @object-ui/plugin-kanban"。Kanban 插件文档页正是这件事的正面回答,页内还挂着两个真实可跑的 board schema(plugin-kanban/basic-kanban-board、plugin-kanban/advanced-kanban-with-badges-and-limits),比原来指向一个"待办示例 app"更直接。
330	examples/crm	/docs/fields/lookup	该 bullet 承诺的是 "Build multi-object apps with relationships"。Lookup Field 文档页开篇即 "reference field for creating relationships between objects and records",且 schema 是 type: 'lookup' | 'master_detail' —— 单对象 CRUD 教程读完后想把对象 B 接到对象 A 上,要看的就是这一页。

关于 330 为什么没跟着 #3506 指向 console-starter

#3506 把另一处 Example: CRM Application 改指了 examples/console-starter,看起来"同名同解"更一致。但两处的上下文不同:#3506 那条在 objectos-integration 的 Resources 清单里,承诺仅仅是"一个示例 app";本文这条承诺的是关系(relationships)怎么建。console-starter/src/App.tsx 通读下来是 routing + auth 脚手架(ConsoleShell/AuthenticatedRoute/Default* 页面),对象与关系全部来自 ObjectStack 后端,它并不演示关系建模。指过去会是第二次"标签夸大目标"。这里跟随 #3506 的是原则(如实改写标签),不是那个具体目标。

顺带的一个真实收益(不是本单的目标)

两条链接从"带 scheme、门禁一律跳过"的那一类,落进了 /docs/... 路由这一类 —— 而 /docs/... 恰恰是 check-doc-links.mjs 今天在 main 上就已经严格校验的一类。也就是说这两条链接以后再烂掉,PR 会直接红,不需要等 #3507 里 hold 住的方向 2(给"指向本仓库自身的 GitHub 绝对 URL"补离线校验)。方向 2 仍然有价值 —— 它覆盖 #3506 新引入的 8 条同形态链接 —— 本 PR 未触碰 scripts/check-doc-links.mjs,把那块完整留给 #3506 合并后的那张 gate 扩展单。

验证

正反两个方向都先预测、后执行:

1. 目标真实存在(离线判定) —— content/docs/plugins/plugin-kanban.mdx、content/docs/fields/lookup.mdx 均在盘上;examples/todo、examples/crm 均 No such file or directory。
2. node scripts/check-doc-links.mjs → Docs links are valid.(exit 0)。
3. 探针 A(预测:红) —— 把新 href 改成 /docs/plugins/plugin-kanban-nope,门禁 exit 1 并精确点名 building-crud-app.md:328。证明新链接确实被校验,而不是换了个门禁同样看不见的写法。
4. 探针 B(预测:绿) —— 把第 328 行原样还原成 https://github.com/objectstack-ai/objectui/tree/main/examples/todo,门禁仍然 Docs links are valid.(exit 0)。这条 404 就在文件里,门禁绿着 —— 这正是本 issue 描述的盲区,也是探针 A 的对照组。
5. pnpm exec vitest run scripts/ → Test Files 14 passed (14) / Tests 204 passed (204)。符合预测:纯文案改动,verdict 不动;唯一变的是覆盖面——the repo it guards / has no broken internal docs links 这条用例现在多校验了这两条链接(此前它们作为外链被整条跳过)。
6. node scripts/check-control-bytes.mjs → OK(3686 个文本文件);另对改动文件单独 grep -naP 自查控制字节,无命中。

已知的先存红:type-check:scripts

pnpm run type-check:scripts 在本分支报

scripts/__tests__/check-doc-links.test.ts(7,1): error TS2578: Unused '@ts-expect-error' directive.

这是 origin/main(f995a45)自带的,不是本 PR 引入:本 PR 的 diff 只有 content/docs/guide/building-crud-app.md 一个文件(2 增 2 删),git show origin/main:scripts/__tests__/check-doc-links.test.ts 第 7 行的 @ts-expect-error 原样还在。即 #3504,热修 PR #3505 尚未落到 main。按分诊要求不在本 PR 里顺手改,#3505 合并后 update branch 即可转绿。

范围

• 无 changeset:纯文档站内容,沿用既往 docs-only PR 的惯例。
• 未触碰 content/docs/releases/。
• 未触碰 scripts/check-doc-links.mjs(方向 2 由 content/docs/guide/building-crud-app.md 有 2 条 GitHub 绝对 URL 指向不存在的 examples/ 目录(examples/todo、examples/crm),两个门禁按设计都看不见 #3507 显式 hold,避免与正在重写同一脚本的 fix(docs): 非 /docs 绝对链接按站点路由校验,并修掉 18 条真实 404 (#3490) #3506 相撞)。

---

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)
objectui	Ignored		Aug 7, 2026 1:48am

[yinlianghui]

更正正文里「已知的先存红」一节的口径 —— 那段写于本地跑完 type-check:scripts 之后、CI 报回之前,说法偏重了。

CI 实际结果:本 PR 一共 5 个 check,没有 Type Check 这一项。

check	结论
Internal Docs Link Check	success
Control Byte Scan	success
Vercel Preview Comments	success
dependabot	skipped
label	(housekeeping)

scripts 的 Type Check 作业带 path filter,本 PR 的 diff 只有 content/docs/guide/building-crud-app.md,所以它根本没触发。也就是说 #3504 的 TS2578 在本 PR 上既不红也不绿,是「不适用」。

正文那段仍然成立的部分:该错误确实存在于 origin/main(f995a45)自身,我在本地 pnpm run type-check:scripts 复现了它,且它与本 PR 无关(diff 未触碰 scripts/)。不成立的部分:「#3505 合并后 update branch 即可转绿」—— 本 PR 没有等它转绿的东西,无需为此 update branch。留档以免 reviewer 误以为本 PR 挂着一个待修的红。

---

Generated by Claude Code