docs(console): name the app-list route the console actually calls, and where per-session filtering really happens - #4937
Merged
Conversation
Six comments in the console app surface named the app LIST endpoint with a
plural-collection spelling that no request in this repo constructs and that no
framework route ledger declares as a row of its own.
Traced first (the issue asked for this before any edit):
- `MetadataProvider` fetches the list as
`client.meta.getItems('app')` (providers/MetadataProvider.tsx:466-468,
type key `apps: 'app'` at :72, eager at :50); the SDK builds
`${baseUrl}${getRoute('metadata')}/${type}` with `metadata` defaulting to
`/api/v1/meta` — so the wire path is `/api/v1/meta/app`.
- The ADR-0037 preview path builds the same address:
`MetadataClient.list()` at metadata-client.ts:586 over the
`/api/v1` + `/meta` base at :405-406.
- Framework ledgers declare `GET /api/v1/meta/:type` -> `meta.getItems`
(rest/src/rest-route-ledger.ts:150, runtime/src/route-ledger.ts:343).
No collection-spelled row exists in either.
- Per-session filtering is real and server-side: `filterAppForUser` /
`filterAppForUserWithReason` (rest/src/rest-server.ts:1814 / :1867) run
inside that `:type` list handler (mounted :3700-3704) at :3838, guarded by
`metaTypeSingular(req.params.type) === 'app'` (:3818) and by
`ctx?.userId` (:3827) — which is what makes it per session.
All six now name the real route and the real filtering locus. Test assertions
are untouched; `appAccessProbe.test.ts:94` already pinned the singular address
in its own expectation, which is what made its header's spelling demonstrably
wrong.
No behaviour change: each touched file transpiles byte-identically with
comments stripped (five of five).
Fixes #4887
Co-authored-by: Claude <noreply@anthropic.com>
Contributor
✅ Console Performance Budget
📦 Bundle Size Report
Size Limits
|
Collaborator
Author
|
PM 验收:ACCEPT(#4887,批次 18,PM 会话 溯源答案(卡面 scope ①,证据链齐):真实端点是通用元数据列表路由 实物核验(已过):6 文件 +50/−16;PM 独立过滤非注释行变更 = 零输出,与 dev 的 正向判据:退役拼写在 packages/+apps/ 归零 + 同管道邻近词正查( 有据偏离(接受):三处 CHANGELOG 的同拼写刻意不动 —— 已发布 release 记录,改它等于重写历史(与 releases 禁令同一精神)。 CI(亲读终态):20 项全 completed,18 success + 2 skipped,零失败。 附带产出:新 finding #4940(同文件 14 个调用点 2 个复数拼写,与本卡同源的拼写漂移观察卡)。 → undraft + auto-merge (SQUASH)。 Generated by Claude Code |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #4887
溯源结论(先做这一步,再动注释)
卡面要求「先确认 console 到底用哪个端点列 apps、per-session 过滤真正发生在哪」。两个问题分开答:
1. 端点:通用元数据列表路由
GET /api/v1/meta/:type,type 段用单数app。packages/app-shell/src/providers/MetadataProvider.tsx:466-468—preview ? preview.list(type) : adapterRef.current.getClient().meta.getItems(type)type的值是单数app:72TYPE_BY_STATE_KEY = { apps: 'app', … };:50EAGER_TYPES = ['app', 'view'](挂载即取)@objectstack/clientmeta.getItems:`${baseUrl}${route}/${type}`,route = getRoute('metadata'),默认表metadata: '/api/v1/meta'→ 线上路径/api/v1/meta/apppackages/data-objectstack/src/metadata-client.ts:586const url = `${this.base}/${encodeURIComponent(type)}${qs}`,base 由:405-406的API_PREFIX='/api/v1'+META_PREFIX='/meta'组成packages/data-objectstack/src/index.tsprobeAppAccess→this.client.meta.getItem('app', appName);appAccessProbe.test.ts:94断言toContain('/api/v1/meta/app/finance')packages/rest/src/rest-route-ledger.ts:150—GET /api/v1/meta/:type→meta.getItems;packages/runtime/src/route-ledger.ts:343同一行台账里没有以集合复数拼写单独立行的 app 列表路由 —— 这正是卡面测量到的「零命中」。
补一条诚实的限定,免得下个读者按「404」去理解:那个被退役的拼写并不会 404。列表路由本身是参数化的
:type,而RestServer.metaTypeSingular(rest-server.ts:1500-1503)用@objectstack/spec/shared的PLURAL_TO_SINGULAR把复数折叠成单数(spec 侧钉死:packages/spec/src/shared/metadata-collection.test.ts:283expect(PLURAL_TO_SINGULAR['apps']).toBe('app'))。所以问题不是「那个 URL 不存在」,而是:本仓没有任何一处 fetch 构造那个拼写,台账也没有它自己的行 —— 六处注释按名字指了一个不是调用地址的东西。2. per-session 过滤:真实存在,且确实在服务端 —— 这半句注释原本就是对的。
@objectstack/rest的RestServer:filterAppForUser(packages/rest/src/rest-server.ts:1814)/filterAppForUserWithReason(:1867)。:3700-3704(path: ${metaPath}/:type);app 分支入口:3818(metaTypeSingular(req.params.type) === 'app');过滤调用:3838;整段包在if (ctx?.userId)(:3827)里 —— 这就是「per session」的机械依据,没有解析出会话用户就不过滤。:4682用filterAppForUserWithReason得出 objectstack#8013 的403 PERMISSION_DENIED判决。所以本卡的两个候选原因里,命中的是前者:路由名错,过滤位置不错。六处注释因此保留「服务端 per-session 过滤」这句声称,并把它从一个泛泛的函数名升级成带文件路径的定位(
filterAppForUser,packages/rest/src/rest-server.ts)。⛔ 卡面边界照办:没做全仓幽灵路由 sweep,没有声称也没有修任何访问控制缺陷。
六处前后对照
每处的新声称都配了上表里的一条可核证据指针。
packages/app-shell/src/console/AppContent.tsx:246filterAppForUser)」GET /api/v1/meta/:type, requested with the SINGULAR type segmentapp(MetadataProvider→client.meta.getItems('app')), and the server filters it per session (filterAppForUser,packages/rest/src/rest-server.ts)」packages/app-shell/src/console/AppContent.tsx:676filterAppForUser)」GET /api/v1/meta/:typewith the SINGULAR type segmentapp, and the server filters that list PER SESSION (filterAppForUser,packages/rest/src/rest-server.ts)」packages/data-objectstack/src/index.ts:3800(probeAppAccessdocblock)filterAppForUser)」GET /api/v1/meta/:type, requested with the singular type segmentapp— the same address this method appends a name to below … applied inside the:typelist handler once the type segment resolves toapp」packages/data-objectstack/src/appAccessProbe.test.ts:13…/console/__tests__/AppContent.deniedVsUnpublished.test.tsx:9GET /api/v1/meta/:typewith the singular type segmentapp, and the server filters that list per session infilterAppForUser(packages/rest/src/rest-server.ts)」;断言未动…/console/__tests__/AppContent.inaccessibleAppStrand.test.tsx:17filterAppForUser,packages/rest/src/rest-server.ts)」GET /api/v1/meta/:typerequested with the singular type segmentapp— the same one thesessionStoragekey above mirrors — and the server already filters it PER SESSION (…)」;断言未动第 6 处原本已经写对了过滤位置(它是六处里唯一带
rest-server.ts路径的),所以那处只订正了路由名。三个测试文件的断言本体一行未改,rationale 修正后也不需要跟着改语义 —— 因为修正的方向是「注释向断言靠拢」,不是反过来:
appAccessProbe.test.ts:94的expect(String(fetchImpl.mock.calls[0][0])).toContain('/api/v1/meta/app/finance')本来就钉着单数地址。文件自己的断言与自己的文件头互相矛盾,这是本卡结论最硬的一条内证。CHANGELOG.md 里还有三处同样的拼写(app-shell / data-objectstack / i18n),故意未动:那是已发布的 release 记录,改它等于重写历史发布说明。
验证
注释-only 改动没有行为门可反向验证,所以用机械等价证明 + 正向判据,不编造一个「改前红/改后绿」的形状。
A. 机械等价(照 PR #4888 六文件
removeComments先例) —— 五个被改文件在removeComments: true下转译,改前(git show HEAD:)与改后逐字节比对:git diff -U0过滤掉注释行后剩零行,与上面互为独立佐证。B. 受影响测试(flock 串行)
单独跑三个被改的测试文件:
Test Files 3 passed (3)/Tests 25 passed (25)。C. 仓根 type-check + 控制字节门
排版微调发生在那次全仓 type-check 之后,所以又对两个受影响包重跑了一遍最终树:
Tasks: 31 successful, 31 total。另按控制字节纪律做了门外自查(grep -naP扫\x00-\x08\x0b\x0c\x0e-\x1f,六个文件 + changeset):零命中。D. 「六处全改、零处遗漏」的正向判据
packages/**/apps/**的.ts/.tsx里命中数:0。meta/:type在两个受影响包里 37 命中;filterAppForUser全仓 8 命中 —— 其中 6 处是本 PR 改过的句子,另 2 处(deniedVsUnpublished.test.tsx:187、inaccessibleAppStrand.test.tsx:127)只提函数名、不带路由名,本来就没有错误声称,不在六处之内。changeset:
.changeset/console-app-list-route-comment-truth.md(注释-only,照combo-drill-doc-truth.md/app-shell-props-block-4808.md先例用空 frontmatter,不推任何包版本)。Generated by Claude Code