forge_admin/forge-admin-ui/DESIGN.md

Forge Admin 设计与公共组件约束

本文件定义 forge-admin-ui 的界面设计原则、公共页面组件和高频交互约束。它服务于长期维护：新页面、新组件和改版都应先遵循这里的视觉与交互规则，再补充具体业务逻辑。

项目级开发约束以仓库根目录 AGENTS.md 为准；目录、命名、接口、字典和编码细则见 Forge Admin前端开发与组件规范.md。

1. 设计目标

Forge Admin 是供日常反复使用的企业管理控制台，不是营销网站。

• 信息密度保持中高：内容紧凑、可扫读，但不拥挤。
• 页面首先明确“当前管理什么对象、已选择什么对象、操作作用于哪里”。
• 用边框、间距、字重和主题色表达层级；不靠渐变、大阴影或装饰卡片堆砌效果。
• 动效只用于确认操作、悬停和加载状态，不能妨碍阅读或降低列表性能。

2. 颜色、文字与表面

角色	变量或参考色	用途
页面底色	--gray-100 / #f6f8fb	Layout 内容背景
面板底色	--bg-primary / #fff	工作台、表格和表单
主文字	--text-primary	标题、核心值和当前对象
次要文字	--text-tertiary	编码、账号、说明和时间
边框	--border-light	面板分隔、工具栏和控件边界
主题色	--primary-color	主操作、可点击实体、选中态和焦点
危险色	--error-color	删除和不可逆操作

• 正常交互只使用一个主题强调色；不要再引入独立的绿色、紫色或渐变体系。
• 系统页标题通常为 14–17px，表格正文 13px，辅助信息 11–12px。
• 管理页禁止使用营销式大标题、英文装饰标签、虚假指标卡和重阴影。
• 面板圆角通常为 6px，控件间距通常为 6–8px；页面根节点不再额外叠加大留白。

3. 页面边界与工作台

3.1 页面级边界

/system/** 已由 SystemPageLayout 负责满高和页面滚动边界。各 Layout 统一提供 8px 页面外边距。

• 页面和 AiCrudPage 内部不得自行增加页面级 padding、外层白卡或大圆角。
• 业务组件只处理自身内容的留白；页面边界必须由 Layout 统一维护。
• 所有可滚动的 Flex 或 Grid 子区域必须同时设置 min-height: 0，再由真正承载内容的子元素声明 overflow: auto。

3.2 左侧对象区 + 右侧工作区

当树、角色、组织、分类等对象决定右侧内容时，必须使用 MasterDetailWorkspace：

<MasterDetailWorkspace
  :collapsed="collapsed"
  :aside-width="220"
  :collapsed-aside-width="72"
>
  <template #aside>
    <OrgTreePanel />
  </template>

  <AiCrudPage ... />
</MasterDetailWorkspace>

• 默认使用连体工作台：一个外框、内部一条细分隔线，避免左树和右表像两张无关卡片。
• aside 放树、对象列表或筛选导航；默认插槽放表格、详情或页签工作区。
• 仅当两块区域确实无业务关联时，才设置 :attached="false"。
• 窄屏由组件自动上下堆叠；页面不要复制一套响应式列宽逻辑。

3.3 三栏工作台

菜单、资源等“树 + 列表 + 详情”页面遵循以下滚动边界：

工作台（固定高度）
├─ 左侧树：自身滚动
├─ 中间列表：工具栏固定，列表区域自身滚动
└─ 右侧详情：标题与操作固定，详情正文自身滚动

• 禁止将内容放进 overflow: hidden 的面板后却没有内部滚动容器。
• 列表和详情的滚动容器应使用 flex: 1、min-height: 0、overflow: auto 和 scrollbar-gutter: stable。
• 不依赖一次性的 JavaScript max-height 计算维持滚动；布局变化后应仍能正确滚动。

4. 公共组件约束

4.1 SystemPageLayout

• 仅负责系统页面的满高与边界，不承担业务区 padding。
• 已在应用根节点按 /system/** 自动包裹；页面内不要重复套用。

4.2 MasterDetailWorkspace

• Props：asideWidth、collapsedAsideWidth、mainWidth、collapsed、attached。
• 插槽：aside 仅放主对象区域，默认插槽放从属工作区。
• 组件必须同时支持亮色、暗色和窄屏上下布局。
• 左右内容区不得向外撑破工作台；内部滚动由各自内容区负责。

4.3 SystemTableCell

SystemTableCell 是系统 CRUD 列表的统一单元格能力，不是通用装饰容器。

• 实体模式：传入 title、subtitle、interactive；用户、租户、客户端等可传 avatar 显示首字标识。
• 实体主标题是可识别的业务名称；辅助标题只能放账号、编码、键名或稳定标识，必须换行显示。
• 关联模式：传入 values，仅显示主值和可点击的 +N；点击后用浮层查看全部值。
• interactive 必须提供真实的 activate 动作，例如详情、编辑或进入下级管理，禁止制造无动作的蓝色链接。
• 用户优先显示真实姓名或昵称，登录名显示为 @username；当两者相同时不要重复显示。

4.4 AiCrudPage 与 AiTable

• AiCrudPage 只负责搜索、工具栏、表格和表单；不负责页面级外框、间距和背景。
• 默认表格密度为 medium。日志、审计、纯对比列表才可使用 small。
• 列表/卡片切换通过 showRenderModeSwitch 控制；不适合卡片浏览的树表、日志页应显式关闭。
• 详情页必须优先提供完整 editSchema；无 Schema 的只读兜底只用于防止空弹窗，不能替代正式详情。

5. CRUD 列规范

每个单元格只表达一种信息层级，避免用多个小色块抢注意力。

列类型	规则
实体	主标题 + 换行辅助标识；可点击时整块点击
关联关系	主值 + 可展开 +N
状态、类型、布尔枚举	使用 DictTag 或单个语义 Tag
普通属性	纯文字，长文本可省略并提供完整提示
编码、键名、账号	优先作为实体辅助标识，不单独挤占主表列
ID、性别、低频技术字段	放入详情或列设置，不占高频列表首屏
操作	最多两个常用文字操作直显，其余收入“更多”

• 不要在同一个单元格同时叠加图标、多个 Tag、徽章、描边和多种颜色。
• 名称与编码成对出现时优先合并为实体列，例如“字典名称 + 字典类型”“参数名称 + 参数键名”。
• 字典类型的主体列点击进入字典数据；配置、资源、用户等主体列点击进入真实详情或编辑，不要只做视觉链接。
• 多个 Tag 同时出现会破坏扫描节奏；只有状态、类型等确有语义的字段才保留 Tag。

6. 工具栏、操作与对象归属

• 操作必须贴近其作用对象：组织操作在组织树或组织面板，用户操作在用户行，页面级操作才放顶栏。
• 一个区域只保留一个主按钮；低频动作使用三点菜单。
• 图标按钮必须提供中文 title 或 aria-label。
• 不要把单个常用操作藏进“更多”；只有两个以上低频操作才折叠。
• 批量操作只在可批量选择的列表中显示，选中数量必须清晰可见。

7. 树、菜单与性能

• 树节点保持紧凑、稳定；选中态使用轻主题底色和细边框，禁止粗左边条和重阴影。
• 左树首次进入默认展开当前层级，不应无条件全量展开深层树。
• 树 + 列表页面的中间列表默认展示当前节点的直属子项；筛选时才递归检索当前范围。
• 不要将同一批树数据同时全展开渲染到树和扁平渲染到列表。
• 数据量增长后，树应改为按 parentId 懒加载，列表应使用服务端分页；前端假分页不能减少接口传输、构树和 DOM 创建成本。
• Loading 应局部显示在树、列表或详情区域，禁止普通刷新时遮住整张工作台。

8. 加载、空态、错误与动效

• 普通 CRUD 请求使用区域级 Loading；导入、导出、上传和下载等真正阻塞的操作才使用全局 Loading。
• 空态必须贴近对应区域，并区分“暂无数据”和“没有匹配结果”。
• 错误提示要说明失败的具体动作，例如“加载资源树失败”。
• 动效只允许使用 color、background、border、opacity、transform，时长 120–180ms。
• 禁止动画 width、height、top、left；禁止系统 CRUD 页持续动画。

9. 系统页面约束

/system/user、/system/post、/system/tenant

• 使用统一紧凑 CRUD 工作面。
• 用户列采用首字标识、真实姓名/昵称和 @username 两行信息。
• 组织、岗位、租户使用主值 + +N，不能平铺多个标签。

/system/org

• 组织树决定右侧用户、岗位工作区；新增用户放在用户列表工具栏，不额外制造上下文大标题。

/system/role

• 左侧角色对象区优先展示角色名称、键、状态和当前标记；右侧管理当前角色的用户或权限。
• 角色本身的编辑、授权和删除操作属于角色对象，不放到成员列表工具栏。

/system/menu

• 客户端切换保持紧凑，不增加占首屏的大说明或指标卡。
• 左树、中间资源列表、右侧详情必须各自可滚动。
• 首屏只渲染顶级资源和当前层级，避免全树展开与全量扁平列表同时创建。

10. 禁止项与交付检查

禁止：

• 紫蓝霓虹渐变、按钮发光、重阴影和超大圆角。
• 管理页中的营销式 Hero、大段功能文案和假指标卡。
• 没有真实行为的可点击蓝色文本。
• 外层隐藏溢出、内部没有滚动区的工作台。
• 为了“丰富”而给每一列增加图标、Tag 或色块。
• 使用 Emoji 作为系统图标，或使用虚构数据伪造真实业务状态。

完成系统页前确认：

1. 主对象和当前选择是否一眼可见。
2. 操作是否放在正确对象附近。
3. 表格列是否符合实体、关联、状态、普通属性的分层规则。
4. 树、列表、详情是否都有正确的独立滚动边界。
5. 亮色、暗色和窄屏是否不会溢出。
6. 已执行 ESLint、git diff --check 和必要的前端构建。