06-UI交互规范

一、整体布局

1.1 页面框架

使用 Ant Design Layout 组件搭建整体骨架：

• Header：顶部导航栏，显示系统名称、用户信息、退出按钮
• Sider：左侧菜单栏，使用 Menu 组件，支持折叠
• Content：右侧主内容区，承载各模块页面

整体结构为 Header + (Sider + Content) 的经典 Admin 布局。

1.2 布局参数

参数	默认值	说明
Header 高度	64px	固定顶部
Sidebar 宽度（展开）	220px	左侧菜单展开宽度
Sidebar 宽度（折叠）	64px	左侧菜单折叠宽度
Content 内边距	24px	内容区四周间距
最小支持分辨率	1280×720	企业内部应用最低屏幕要求

二、标准页面类型

2.1 列表页

• 顶部操作区：新增、导入、导出按钮靠右对齐
• 搜索栏：使用 Form + Input / Select / DatePicker 组合，搜索按钮在最右侧
• 表格：使用 Table 组件，支持分页、行选择、列排序
• 分页：位于表格底部右侧，显示总条数，每页默认 20 条

2.2 表单页

• 新增/编辑统一使用 Drawer（宽度 520px），避免完整页面跳转
• 校验时机：失焦时触发单字段校验，提交时触发全量校验
• 提交按钮位于 Drawer 底部右侧（「确定」+「取消」），固定不随内容滚动

2.3 详情页

• 使用 Descriptions 展示基本信息（labelWidth 100px，border 模式）
• 多维度信息使用 Tabs 切换（如基本信息 / 操作日志 / 关联记录）

2.4 树形管理页

用于用户管理中的角色/权限树，使用 Ant Design Tree + 右侧 Drawer 的左右布局：

• 左侧 Tree 支持搜索、展开/折叠
• 右侧 Drawer 展示选中节点的详细信息或编辑表单

三、通用交互规则

3.1 操作反馈

• 成功：message.success()，右上角弹出，持续 2s
• 失败：message.error()，持续 3s，错误文案来自接口返回 message 字段
• 危险操作（删除、批量操作）：Modal.confirm() 二次确认，标注受影响数量
• 长耗时操作（导入/导出）：按钮进入 loading 态，禁止重复点击

3.2 数据展示

状态	组件	文案
空数据	Empty	"暂无数据"
加载中	Spin + Skeleton	—
接口异常	Result (status=500)	"数据加载失败，请刷新重试"

3.3 权限控制（前端）

• 菜单级：根据后端返回的权限码动态渲染菜单项，无权限则不显示
• 按钮级：封装 <PermButton permission="xxx:yyy"> 组件，无权限时按钮隐藏
• 路由级：在 React Router 的路由守卫中校验权限，无权限跳转 403 页面
• 权限码格式：模块代码:操作（如 usr:create、usr:edit），与后端 RBAC 保持一致

四、Design Tokens

所有色值统一以 CSS 变量定义于 src/styles/tokens.css；命名规范见 docs/04 § 2.5。

4.1 全局调色板

语义	变量名	默认值	用途
主色	--color-primary	#1677ff	按钮/链接/高亮
成功	--color-success	#52c41a	成功状态/标签
警告	--color-warning	#faad14	警告提示
错误	--color-error	#ff4d4f	错误/危险操作
主文字	--color-text-primary	#000000e0	主要文本
次文字	--color-text-secondary	#00000073	辅助文本/提示
边框	--color-border	#d9d9d9	输入框/分割线边框
背景	--color-bg-base	#f5f5f5	页面底色

4.2 组件级状态色

序号	组件	编辑bg	只读bg	悬浮bg	编辑fg	只读fg	悬浮fg	备注
1	表单输入框	var(--color-bg-input-edit)	var(--color-bg-input-readonly)	var(--color-bg-input-hover)	var(--color-text-primary)	var(--color-text-secondary)	var(--color-text-primary)	—
2	表格行	—	var(--color-bg-table-row)	var(--color-bg-table-row-hover)	—	var(--color-text-primary)	var(--color-text-primary)	选中行用主色淡色
3	侧边菜单项	—	var(--color-bg-menu-item)	var(--color-bg-menu-item-hover)	—	var(--color-text-primary)	var(--color-primary)	活动项用主色

Token 默认值

变量名	默认值
--color-bg-input-edit	#ffffff
--color-bg-input-readonly	#f5f5f5
--color-bg-input-hover	#ffffff
--color-bg-table-row	#ffffff
--color-bg-table-row-hover	#fafafa
--color-bg-menu-item	transparent
--color-bg-menu-item-hover	rgba(0,0,0,0.06)

4.3 引用约定

• 组件样式只用 var(--color-xxx)，禁止硬编码 hex / rgba
• 新增 token 须先登记到 § 4.1/4.2 再补 tokens.css
• 修改色值只改 tokens.css 一处，不允许组件级覆盖

五、页面清单

（由 downstream-gen 按模块追加段落）

module_usr 用户管理

• 登录页 (/login)

  • 类型: 表单页
  • 对应 REQ: REQ-USR-004
  • 入口菜单: 不在菜单内，直接路由跳转
  • 主要交互: 填写公司编号/用户名/密码 → 提交登录 → 成功跳转主页；失败显示错误提示；连续失败锁定提示

• 用户列表页 (/usr/users)

  • 类型: 列表页
  • 对应 REQ: REQ-USR-001, REQ-USR-002, REQ-USR-003
  • 入口菜单: 系统管理 → 用户管理
  • 主要交互: 顶部搜索栏（字段/匹配方式/值三联筛选）+ 表格分页展示；行内「编辑」按钮弹出 Drawer；顶部「新增」按钮弹出新增 Drawer；Drawer 含权限组复选列表