跳转至

Admin Shell 结构约束

注意：本文档仅保留为 Classic Admin 的历史设计记录。Classic 源码已从活跃代码树移除；当前活跃控制台是 admin-frontend/studio/src/shadcn-admin/，新工作不应再依赖本文描述的旧组件路径。

Classic Admin 曾经通过共享布局契约解决 shell 抖动和页面流失控问题。这里保留的不是可直接复用的文件路径，而是仍然值得继承的结构原则。

历史原则

  • shell 层应拥有视口高度和主内容区滚动控制权。
  • 页面应优先通过共享布局原语构建，而不是自由拼装顶层块。
  • create/edit/test 这类高密度交互应优先进入 overlay surface，而不是把大表单插回主页面流。

历史原语

Classic Admin 曾使用以下布局原语：

  • AdminPageFrame
  • AdminPageHeader
  • AdminDrawer
  • AdminSurfaceCard

这些名称仅作为历史概念保留，不再代表当前可导入的实现文件。

仍然有效的经验

  • 避免在主页面流顶部条件渲染大块 create/edit 表单。
  • 避免让页面顶层布局直接影响 shell 高度或滚动归属。
  • 避免为单个页面再造一套临时 overlay 样式体系。

当前建议

如果你在 Studio 中处理类似问题，应在 admin-frontend/studio/src/shadcn-admin/ 范围内延续同类布局思想，而不是尝试恢复 Classic 组件或路径。

Studio 运行时 Provider 护栏

Studio 里有一类问题看起来像“单页白屏”，实际上是共享 provider 作用域丢失。Knowledge Sources 和 Audit Logs 都出现过同类故障：页面把 tooltip label 作为 ReactNode 传入共享布局后，实际渲染位置已经跑到了原页面局部 TooltipProvider 外面，最终触发 Tooltip must be used within TooltipProvider。

当前防线是保留 admin-frontend/studio/src/app.tsx 里的根级 TooltipProvider。这条约束不要轻易移除。

  • 页面局部 TooltipProvider 只能用于局部行为微调，例如单页覆盖 delayDuration。
  • 不要把页面局部 provider 当成唯一安全保障，尤其是 tooltip 被塞进 StudioMasthead.meta、StudioInsightList.items、dialog label 或 rail summary 这类共享槽位时。
  • 如果你调整 App 根节点、shell/provider 层级，先审计所有 tooltip 使用点，再手动打开相关页面验证，避免再次引入首屏白屏。