示例页面边界

区分 apps/admin 当前页面中的真实开发入口、演示页和占位页，避免把 manage/user、manage/menu、manage/role 误当成标准业务实现

这一页说明 apps/admin/src/pages 里哪些页面可以作为二次开发入口，哪些只是演示或占位。当前应用里 manage/user、manage/menu、manage/role 的路由名称很像真实管理模块，但页面内容并不是完整的用户、菜单、角色 CRUD。

写业务页面前先确认这个边界，避免把通知、弹窗或 UnoCSS 主题展示页面直接复制成生产代码。

适用场景

场景	重点位置
判断某个现有页面能不能直接复用	`apps/admin/src/pages/(admin)`
准备把 demo 页面替换成真实业务页	`features/table`、`service/api/system-manage`
给菜单加真实列表、详情或编辑页	`routing/overview`、`routing/route-meta`、`features/table-and-form`
排查菜单标题、权限和页面内容不一致	每个 route 文件的 `staticData` 和组件正文

当前实现位置

文件	当前职责
`apps/admin/src/pages/(admin)/home/index.tsx`	后台首页和 dashboard 示例，包含菜单 badge、卡片、图表和项目动态模块。
`apps/admin/src/pages/(admin)/manage/user/index.tsx`	通知系统演示页，使用 `useNotificationContext()` 和 mock 通知数据。
`apps/admin/src/pages/(admin)/manage/menu/index.tsx`	Ant Design message、notification、modal 的测试页面。
`apps/admin/src/pages/(admin)/manage/role/index.tsx`	UnoCSS Design System 和主题色展示页面。
`apps/admin/src/pages/(admin)/manage/user/$id.tsx`	用户详情动态路由示例，用于展示 `activeMenu` 一类路由元信息。
`apps/admin/src/pages/(admin)/soybean-docs.tsx`	外链路由示例，使用 `href`。
`apps/admin/src/pages/(admin)/soybean-docs-iframe.tsx`	iframe 路由示例，使用 `url`。

页面现状清单

路由	可以学什么	不要误解成
`/home`	后台首页布局、图表模块、菜单 badge、Dashboard 卡片组合	完整的数据看板产品实现
`/manage/user`	通知上下文、通知配置、浏览器通知权限、声音开关	用户管理列表页
`/manage/menu`	Ant Design 全局 message、notification、modal 包装函数	菜单管理 CRUD
`/manage/role`	UnoCSS 主题色、色阶、设计系统展示	角色管理 CRUD
`/manage/user/$id`	动态路由、隐藏详情页、菜单激活关系	完整用户详情业务流
`/soybean-docs`	外链菜单配置	内嵌页面
`/soybean-docs-iframe`	iframe 菜单配置	普通 React 页面

这里的关键点是：路由名称、菜单名称和页面真实内容并不总是同一个阶段的产物。文档和二次开发应以当前页面源码为准，而不是只看菜单名称。

开发真实管理页的路径

如果要把 manage/user、manage/menu 或 manage/role 改成真实业务页，建议按这个顺序做：

先确认路由是否保留在原路径，还是新建一个业务路由。
在 service/api/system-manage 或新的服务模块里补齐接口、类型、query keys 和 hooks。
用表格与表单的 useTable()、TableHeaderOperation、useTableOperate() 组织列表页。
在 route staticData 里配置 title、i18nKey、menu、permissions。
如果保留 demo 能力，把 demo 页面迁到更明确的示例目录，避免生产菜单下混入测试页面。

最小结构可以这样拆：

apps/admin/src/pages/(admin)/manage/user/
  index.tsx       # 用户列表和搜索
  $id.tsx         # 用户详情
  modules/
    UserSearch.tsx
    UserTable.tsx
    UserOperateDrawer.tsx

页面层只组合路由、搜索、表格和抽屉；接口请求和分页状态交给 service/api 与 features/table。不要在页面里重新写一套请求缓存、分页状态和列设置。

外链和 iframe 页面

当前外链与 iframe 是两种不同路由形态：

形态	配置重点	行为
外链	`staticData.href`	守卫识别后打开新窗口，当前页面不承载内容。
iframe	`staticData.url`	菜单进入应用内 iframe 页面，tabs 和菜单仍在后台壳内。

新增这类页面时，优先看路由元信息的 href、url、activeMenu 说明，不要把 iframe 页面写成普通业务组件。

常见误区

误区	正确做法
看到 `/manage/user` 就按用户列表文档写说明	先看源码。当前它是通知 demo。
直接复制 `manage/menu` 的测试按钮作为业务页骨架	只把消息、弹窗 API 的用法迁移出来，业务页重新按表格/表单结构写。
把 `manage/role` 当成角色管理最佳实践	它主要展示 UnoCSS 和主题色，不处理角色接口。
在 demo 页里追加真实业务逻辑	先拆清 demo 和业务页面边界，再迁移或替换。
只改菜单标题，不改权限和 i18n	`staticData.permissions`、`i18nKey`、语言文件和菜单显示要一起对齐。