三处 docblock 在 #3660 落地后变成事实错误:仍写「setup 左导航 Datasources 指向 component/metadata/resource 别名」 #3666

越界发现,记录于 #3660(4 处生产端改发规范拼法)实施期间。这三处不是既有陈旧,而是 #3660 的 PR 一旦合并就会当场制造出来的错误 —— 它们描述的正是该 PR 改掉的两个 sidebar 字面量。按纪律只报不改(#3660 的派发文件面只有两个 sidebar + SystemHubPage + 测试 + changeset,其中 console/AppContent.tsx 另挂 ⛔),未认领,留 PM 分诊。

观察类:纯注释,用户看不到,运行时行为无关。故打 finding、不打 pm:queue。

事实

#3660 把两个 sidebar 的 sys-datasources 由 /apps/setup/component/metadata/resource?type=datasource 改为规范的 /apps/setup/metadata/datasource。以下三段 docblock 以现在时断言该导航项仍指向别名:

1 和 2 是 PR #3658(修 #3639)昨天刚写下的 —— 当时完全正确,#3660 使其失效。3 是 PR #3636(修 #3610)写的,叙述的是 #3610 当时的成因,可辩护为历史陈述,但同样用现在时,读起来是当前事实。

为什么值得单独记一笔,而不是"注释洁癖"

这正是 #3639 立单的原因本身。#3658 的正文写得很清楚:被订正的四段 docblock 把别名说成 "the engine route",而「#3610 的派发单正是顺着这句话推出 component/... 才是规范拼法的,与路由表恰好相反」。同一个坑在同一条链上已经付过一次钱。留下三段新的现在时假陈述,下一个 agent grep component/metadata 找生产端时,会从 1 和 2 得到"sidebar 还在喂别名"的结论,而实际上已经没有任何生产端在喂了。

建议处置(两条路,PM 择一)

• A(推荐,最省):在 导航仍有 4 处生产端在生成已废弃的 component/metadata 别名(SystemHub 两张卡片 + 两个 sidebar),各多绕一跳 #3660 的 PR 合并前直接并入。1 和 2 是两行措辞改动,与 导航仍有 4 处生产端在生成已废弃的 component/metadata 别名(SystemHub 两张卡片 + 两个 sidebar),各多绕一跳 #3660 的 diff 语义上是同一件事(「自家导航不再喂别名」这个事实的文档面)。代价:导航仍有 4 处生产端在生成已废弃的 component/metadata 别名(SystemHub 两张卡片 + 两个 sidebar),各多绕一跳 #3660 的文件面 +2,且这两个文件 fix(console): 宿主重定向直发规范 metadata 路由,不再绕已废弃的 component/metadata 别名 (#3639) #3658 刚碰过(合并冲突风险低,fix(console): 宿主重定向直发规范 metadata 路由,不再绕已废弃的 component/metadata 别名 (#3639) #3658 已落 main)。3 需要单独裁决,因为 console/AppContent.tsx 在 导航仍有 4 处生产端在生成已废弃的 component/metadata 别名(SystemHub 两张卡片 + 两个 sidebar),各多绕一跳 #3660 的派发里挂了 ⛔。
• B:独立小单,导航仍有 4 处生产端在生成已废弃的 component/metadata 别名(SystemHub 两张卡片 + 两个 sidebar),各多绕一跳 #3660 合并后再修。代价:main 上会有一段时间带着三段假陈述,正是上面那个坑的复现窗口。

我(#3660 的执行 agent)倾向 A,但没有自作主张:派发单的文件面写了「越界即停」,而这两个文件不在其中。PM 若裁决 A,我可在 #3660 的分支上直接补一次提交。

别名路由本身不受影响

三段注释描述的别名路由仍然存在且仍然转发 —— #3660 明确不主张删别名(书签/外链)。要改的只是"谁在喂它"这一句。

关联

• 导航仍有 4 处生产端在生成已废弃的 component/metadata 别名(SystemHub 两张卡片 + 两个 sidebar),各多绕一跳 #3660 —— 制造这三处失效的改动本身。
• console(apps/console): MetadataRedirect / ObjectRedirect 改写到已废弃的 component/metadata/resource 别名,多绕一跳且 docblock 已过期 #3639 / PR fix(console): 宿主重定向直发规范 metadata 路由,不再绕已废弃的 component/metadata 别名 (#3639) #3658 —— 写下 1 和 2 的 PR,也是"docblock 说错拼法会误导派发"这一教训的出处。
• console: 零应用下 sys-objects / sys-datasources 落到 /apps/setup/component/... 渲染空白屏——无-activeApp 分支既无 component/* 路由也无 catch-all #3610 / PR fix(app-shell): 零应用分支补 component/metadata 别名路由与 catch-all (#3610) #3636 —— 写下 3 的 PR。
• app-shell 测试里的 MetadataRedirectStub 在 PR #3658 后不再是逐字转录,sys-objects 用例测的是生产中已不存在的链路(绿得没有意义) #3661 —— 同批越界发现(测试 stub 侧),不同文件面。

已就关键词(component/metadata / sys-datasources / docblock / stale comment / DatasourceResourcePage / register.ts)与上述文件路径搜过本仓开放 issue 与 PR,无同源单(命中的 #3655 / #3661 / #3561 均属不同问题)。

Generated by Claude Code