fix(app-shell): /home 的 Administration 组改由 NavigationRenderer 渲染，9 个系统管理入口恢复可达 (#3609)

[yinlianghui]

Fixes #3609

病灶

UnifiedSidebar 用一个三元挑渲染器：context === 'app' && activeApp ? … : …。

• app 分支（:504，现 :512）渲染 NavigationRenderer —— 那才是会递归进 type: 'group' 子项、把组渲染成 Collapsible 的组件。
• home 分支（:606）是手写的：homeNavigation.map(...)，每项渲染成一条 Link，to={item.url || '/home'}。不递归。

而 home 导航偏偏是全仓唯一用 type: 'group' 结构化的那份。于是 9 项 Administration 簇被压平成一条；组自身没有 url，|| '/home' 把它送回用户已经站着的那一页；9 个子项一个也没进过 DOM。

resolveLandingPath([]) 返回 /home，零应用部署的管理员第一屏就是这里；而 HomePage.tsx:289 的注释写着「（系统入口）已经在 nav 里了」，主动撤掉了自己的 System 卡片。净效果：管理员没有任何通往系统管理的入口。

修法选择：复用 NavigationRenderer（不是补丁化 home 分支）

按 PM 裁决先测量差异面，再决定。测量结果如下：

维度	home 手写分支（修前）	NavigationRenderer（app 分支）
组递归	无 —— item.url || '/home'	有，递归渲染成 Collapsible
叶子 DOM 结构	SidebarGroup / SidebarGroupContent / SidebarMenu / SidebarMenuItem / SidebarMenuButton asChild / Link	完全相同
图标	getIcon（app-shell 自己的）	resolveIcon → getLazyIcon（components 包）—— 同一个 lucide DynamicIcon 实现、同一个 Database 兜底、桌面端同为 h-4 w-4
active 判定	逐项 location.pathname === item.url	全树选举唯一 active（resolveActiveNavItem），basePath 感知
item 级门	无	visible / requiredPermissions / requiresObject / requiresService
badge / separator / action	不支持	支持
context 依赖	useLocation	useLocation 而已 —— basePath 是 prop，对 activeApp 零耦合

最后一行是决定性的：分诊担心的「NavigationRenderer 强依赖 activeApp context」不成立，它只吃 props + useLocation()。所以复用不需要放松任何东西，退到手写递归的条件没有触发。

两处不变量也被测量确认：

1. basePath="" 正是 home 分支 basePath 本来就算出的值（context === 'app' && activeApp ? … : ''）；
2. home 全部条目是 type: 'url'，resolveHref 对它原样返回 item.url，不拼 basePath。

因此两条幸存的顶层链接（Home /home、Documentation /docs）href 逐字节不变，9 个子项拿到各自声明的绝对 URL。

expanded: true：为什么必须显式声明

NavigationRenderer 在作者未声明时对 ≥ 8 个子项的组自动折叠（AUTO_COLLAPSE_THRESHOLD = 8），Radix 的 CollapsibleContent 关闭时会 unmount。这个启发式是为「app 导航里众多分区中的某一条长分区」设计的。

本组正好 9 项，且在 /home 上它不是众多分区之一，它就是管理员的导航本身。若交给启发式，9 项又会退出 DOM —— 那只是同一个 bug 换个拼法。所以在组声明上显式写 spec 字段 expanded: true。测试直接钉住 aria-expanded="true"。

刻意不从 app 分支转发的 props（附理由，非遗漏）

• enablePinning / enableReorder：两者都持久化在 useNavOrder(activeApp?.name || 'home') 下，而 home 上下文里 activeApp 解析成的是第一个 app（activeApps[0]），不是 home —— 打开就等于让 home 导航吃那个 app 存下的根排序。另外 pinned 区会正好落在本分支自己的 "Starred" 组上方。两者都是独立的产品决定，不属于「把组展开」这一单。
• resolveGroupLabel / resolveItemLabel：以 activeApp.name 为键，在 home 上下文里没有意义（会去某个任意 app 的 i18n 命名空间下查 sys-administration）。home 的 label 在构造处已经过 t() 解析。

以上两条都写进了调用点的注释。

MEASUREMENT 钉：翻转前后对照

#3590 在 systemNavSettingsTarget.test.tsx 留下的钉断言的是坏状态，并写明「一旦修好就会转红，届时应换成真实断言」。本 PR 替换它，不是并存 —— 仓库不能同时钉着 bug 和修复。

修前（已删除）

expect(screen.getByRole('link', { name: 'Administration' })).toHaveAttribute('href', '/home');
expect(screen.queryByRole('link', { name: 'System Settings' })).not.toBeInTheDocument();
expect(screen.queryByRole('link', { name: 'Applications' })).not.toBeInTheDocument();

修后（新断言）

expect(screen.queryByRole('link', { name: 'Administration' })).not.toBeInTheDocument();
const trigger = screen.getByRole('button', { name: 'Administration' });
expect(trigger).toHaveAttribute('aria-expanded', 'true');
for (const [label, href] of ADMINISTRATION_ENTRIES) {
  expect(screen.getByRole('link', { name: label })).toHaveAttribute('href', href);
}

两半正好互逆：Administration 由链接变成折叠开关（组无 url，任何把它渲染成链接的写法都只能落回 || '/home' 死链，所以按 role 断言「不再是链接」比断言「href 变了」更严）；子项由缺席变成全部在场。

ADMINISTRATION_ENTRIES 整簇 9 条全断言（不是抽样 3 条）：本 bug 的性质是「子项根本没被访问过」，所以值得钉的性质是「九项俱全、各自 URL 正确」，而非「有些渲染出来了」。另加：System Settings 不得退回裸 /apps/setup（#3608 刚改对的那条）；Home / Documentation 两条扁平项 href 不变。

新增第二条测试反向钉权限门：非管理员在 /home 看不到组、看不到 9 项中任何一项，同时 Home / Documentation 仍在（否则这条测试在「侧栏什么都没渲染」时也会绿）。

逆向验证（先预测后执行）

预测：保留新测试、把 UnifiedSidebar.tsx 单独回退到 origin/main → 新测试转红，且首个失败断言是 queryByRole('link', {name:'Administration'})).not.toBeInTheDocument()（方向：Administration 仍是链接、子项找不到）；非管理员那条保持绿（它从不依赖组渲染）。

实测（git checkout origin/main -- packages/app-shell/src/layout/UnifiedSidebar.tsx）：

 Test Files  1 failed (1)
      Tests  1 failed | 2 passed (3)

 FAIL  systemNavSettingsTarget.test.tsx > UnifiedSidebar: /home renders the Administration cluster as a GROUP …
Error: expect(element).not.toBeInTheDocument()
expected document not to contain element, found  a … data-sidebar="menu-button" href="/home"  span Administration …  instead
 ❯ …/systemNavSettingsTarget.test.tsx:226:72

方向与预测一致（红，且红在预测的那一行）。随后已还原实现。

测试证据

$ pnpm exec vitest run packages/app-shell/src/layout/__tests__/systemNavSettingsTarget.test.tsx
 Test Files  1 passed (1)
      Tests  3 passed (3)

$ pnpm exec vitest run packages/app-shell/src/layout packages/layout/src
 Test Files  19 passed (19)
      Tests  161 passed (161)

$ pnpm --filter @object-ui/app-shell type-check
> tsc --noEmit && tsc -p tsconfig.typetests.json     (无输出 = 通过)

$ pnpm check:control-bytes
✅  check-control-bytes: OK (scanned 3650 tracked text file(s); skipped 85 binary)

$ pnpm changeset:check
✅  All workspace packages are in the changeset fixed group.
✅  No changeset declares a `major` bump.

UnifiedSidebar.derivedAreaVisibility.test.tsx 在上面那 19 个文件里，全绿 —— app 分支（context === 'app'）行为零变化，符合预测。

影响面 sweep（按规则的消费半径，不按改动包）

枚举了 UnifiedSidebar 的全部引用（app-shell/index.ts、layout/index.ts、ConsoleLayout.tsx、FavoritesProvider.tsx、HomePage.tsx、AppSidebar.tsx、apps/console/src/pages/system/SystemHubPage.tsx）与全仓提到 homeNavigation / sys-administration / Administration 的文件。命中的 packages/types/src/__tests__/navigation-model.test.ts:204 只是一个恰好叫 Administration 的 Zod area fixture，与本改动无关。e2e/ 下无相关断言。i18n locale 包未改动。

测试基建的一处必要补充

home 分支现在走 NavigationRenderer，它的图标经 @object-ui/components 的 getLazyIcon（而 AppSidebar 的手写簇经 app-shell 自己的 getIcon）。lucide 的 DynamicIcon 在 useEffect 里发异步 import() 再 setState，所以对 components 包做了局部 mock（importOriginal 展开后只替换 getLazyIcon），Sidebar 原语保持真实。这与该文件原有的 getIcon mock 是同一目的：让每条链接的可访问名等于它的 label 文本，并保持渲染同步。

文件面

• packages/app-shell/src/layout/UnifiedSidebar.tsx
• packages/app-shell/src/layout/__tests__/systemNavSettingsTarget.test.tsx
• .changeset/home-administration-group-3609.md（patch）

未触碰 AppSidebar.tsx / AppContent.tsx / ConsoleShell.tsx（#3610 / #3611 另有单）、locale 包、content/docs/releases/。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt

---

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 4:28pm

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Main entry (gzip)	28.1 KB	350 KB
Entry file	index-B9Z49Vzx.js	—
Status	PASS	—

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (index.js)	8.66KB	3.13KB
app-shell (runtime-config.js)	7.42KB	2.32KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	7.57KB	2.97KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	1.17KB	0.53KB
auth (AuthProvider.js)	22.10KB	4.37KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.21KB	3.45KB
auth (LoginForm.js)	18.13KB	5.39KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.64KB	2.21KB
auth (SocialSignInButtons.js)	9.60KB	3.89KB
auth (UserMenu.js)	3.40KB	1.22KB
auth (auth-gate-events.js)	1.29KB	0.66KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	35.76KB	9.11KB
auth (createAuthenticatedFetch.js)	4.37KB	1.69KB
auth (index.js)	2.35KB	1.07KB
auth (org-roles.js)	6.66KB	2.78KB
auth (phone-identifier.js)	1.11KB	0.66KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	4.91KB	0.87KB
auth (useIsWorkspaceAdmin.js)	1.61KB	0.85KB
collaboration (CommentThread.js)	26.07KB	7.56KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	6.49KB	2.64KB
collaboration (PresenceProvider.js)	2.79KB	1.13KB
collaboration (index.js)	1.65KB	0.73KB
collaboration (useCollaborationTranslation.js)	6.05KB	2.52KB
collaboration (useCommentSearch.js)	1.98KB	0.88KB
collaboration (useConflictResolution.js)	7.75KB	1.86KB
collaboration (useMentionNotifications.js)	1.81KB	0.68KB
collaboration (usePresence.js)	6.33KB	1.84KB
collaboration (useRealtimeSubscription.js)	7.91KB	2.01KB
components (index.js)	480.72KB	105.64KB
core (index.js)	2.96KB	1.13KB
create-plugin (index.js)	9.28KB	2.98KB
data-objectstack (index.js)	137.51KB	35.11KB
fields (index.js)	230.87KB	56.83KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (currency.js)	1.22KB	0.64KB
i18n (i18n.js)	4.32KB	1.77KB
i18n (index.js)	2.65KB	1.06KB
i18n (pickLocalized.js)	1.70KB	0.83KB
i18n (provider.js)	9.48KB	3.27KB
i18n (useObjectLabel.js)	26.14KB	6.07KB
i18n (useSafeTranslation.js)	4.52KB	1.96KB
layout (index.js)	38.53KB	10.71KB
mobile (MobileProvider.js)	0.92KB	0.49KB
mobile (ResponsiveContainer.js)	0.94KB	0.38KB
mobile (breakpoints.js)	1.51KB	0.70KB
mobile (createOfflineDataSource.js)	5.61KB	1.74KB
mobile (index.js)	1.50KB	0.62KB
mobile (offlineQueue.js)	3.91KB	1.35KB
mobile (pwa.js)	0.97KB	0.49KB
mobile (serviceWorker.js)	1.48KB	0.62KB
mobile (serviceWorkerSource.js)	3.41KB	1.48KB
mobile (useBreakpoint.js)	1.54KB	0.65KB
mobile (useGesture.js)	6.96KB	1.98KB
mobile (useOfflineSync.js)	1.99KB	0.72KB
mobile (usePullToRefresh.js)	2.53KB	0.85KB
mobile (useResponsive.js)	0.71KB	0.42KB
mobile (useResponsiveConfig.js)	1.36KB	0.63KB
mobile (useSpecGesture.js)	4.32KB	1.64KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	8.75KB	3.06KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	3.67KB	1.12KB
permissions (evaluator.js)	4.41KB	1.44KB
permissions (index.js)	0.91KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.52KB
permissions (usePermissions.js)	1.55KB	0.71KB
plugin-ai (index.js)	15.71KB	3.79KB
plugin-calendar (index.js)	44.98KB	12.37KB
plugin-charts (index.js)	61.04KB	17.31KB
plugin-chatbot (index.js)	180.09KB	42.72KB
plugin-dashboard (index.js)	115.50KB	29.96KB
plugin-designer (index.js)	210.51KB	42.51KB
plugin-detail (index.js)	232.79KB	57.42KB
plugin-editor (index.js)	2.46KB	1.10KB
plugin-form (index.js)	112.10KB	27.10KB
plugin-gantt (index.js)	162.55KB	39.57KB
plugin-grid (index.js)	186.61KB	49.34KB
plugin-kanban (index.js)	48.30KB	13.28KB
plugin-list (index.js)	105.12KB	25.48KB
plugin-map (index.js)	16.81KB	5.24KB
plugin-markdown (index.js)	13.72KB	4.69KB
plugin-report (index.js)	40.58KB	10.58KB
plugin-timeline (index.js)	25.76KB	7.33KB
plugin-tree (index.js)	8.50KB	2.88KB
plugin-view (index.js)	84.03KB	20.55KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.90KB	0.85KB
providers (UploadProvider.js)	11.71KB	3.53KB
providers (index.js)	0.44KB	0.22KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.67KB	2.37KB
react (LazyPluginLoader.js)	3.77KB	1.33KB
react (SchemaRenderer.js)	19.28KB	6.38KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	1.02KB	0.55KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (codegen.js)	4.09KB	1.74KB
sdui-parser (index.js)	4.47KB	2.03KB
sdui-parser (parse.js)	10.04KB	2.82KB
sdui-parser (types.js)	0.29KB	0.24KB
sdui-parser (validate.js)	4.69KB	1.48KB
types (ai.js)	0.20KB	0.17KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	2.87KB	0.99KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	0.20KB	0.18KB
types (crud.js)	0.20KB	0.18KB
types (data-display.js)	0.20KB	0.18KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	1.87KB	0.85KB
types (disclosure.js)	0.20KB	0.18KB
types (error-code.js)	1.54KB	0.88KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (http-retry.js)	4.32KB	2.02KB
types (index.js)	2.71KB	1.34KB
types (layout.js)	0.20KB	0.18KB
types (managed-by.js)	0.19KB	0.18KB
types (mobile.js)	2.59KB	1.31KB
types (navigation.js)	0.20KB	0.18KB
types (objectql.js)	0.20KB	0.18KB
types (overlay.js)	0.20KB	0.18KB
types (permissions.js)	0.20KB	0.18KB
types (plugin-scope.js)	0.20KB	0.18KB
types (record-components.js)	0.20KB	0.19KB
types (record-semantics.js)	1.28KB	0.67KB
types (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (spec-report.js)	5.05KB	1.93KB
types (system-fields.js)	3.33KB	1.54KB
types (theme.js)	0.20KB	0.18KB
types (ui-action.js)	3.40KB	1.71KB
types (views.js)	0.20KB	0.18KB
types (widget.js)	0.20KB	0.18KB

Size Limits

• ✅ Core packages should be < 50KB gzipped
• ✅ Component packages should be < 100KB gzipped
• ⚠️ Plugin packages should be < 150KB gzipped