06-UI交互规范

一、整体布局

1.1 页面框架

采用 Ant Design 5.x 的 Layout 组件构建整体骨架，分三段：

• Header（顶部导航）：左侧 Logo + 系统名（"小羚羊 ERP"），右侧用户头像下拉（个人信息 / 修改密码 / 退出登录）。
• Sider（侧边菜单）：固定左侧，使用 Menu 组件以树形展示由 MOD 模块管理维护的功能菜单，支持折叠。
• Content（主区域）：路由出口，渲染各业务页面，外包 Breadcrumb + PageHeader 上下文容器。

整体使用 ConfigProvider 注入主题与中文 zh_CN locale。

1.2 布局参数

项	默认值	说明
Header 高度	56 px	紧凑信息密度，留出更多内容区
Sidebar 展开宽度	220 px	菜单文案完整可见
Sidebar 折叠宽度	56 px	仅图标
Content 内边距	16 px	与 Card / Table 的内边距对齐
最小分辨率	1366 × 768	ERP 桌面端为主，不做移动端适配

二、标准页面类型

基于 USR / MOD 模块均为典型主数据维护场景，列表 / 表单 / 详情 三类页面足以覆盖；用户与模块均为扁平或浅层树结构，再补一个树形管理页用于 MOD。

2.1 列表页

自上而下三段：

• 顶部操作区：左侧批量动作（启用 / 停用 / 删除），右侧主操作（"新增 X"）。
• 搜索栏：Form 行内布局，含关键字 + 1~2 个枚举筛选；提交触发请求，"重置"清空。
• 表格 + 分页：Table + 服务端分页（Pagination），列尾固定 操作 列（编辑 / 详情 / 删除）。
• 删除等危险操作需 Modal.confirm 二次确认。

2.2 表单页

新建 / 编辑统一使用右侧 Drawer（宽度 600 px），不跳页：

• 字段使用 Ant Design Form + Form.Item，校验时机 onBlur，提交前再 validateFields 全量校验。
• 提交按钮固定在 Drawer 右下角，主按钮"保存"在右、"取消"在左。
• 提交期间按钮 loading=true，避免重复提交。

2.3 详情页

使用 Descriptions（bordered + column={2}）展示主数据，必要时 Tabs 切分"基本信息 / 关联资源 / 操作日志"等子页签；详情页只读，编辑动作回到 Drawer 表单。

2.4 树形管理页

仅 MOD 模块管理使用：左侧 Tree 展示模块层级，右侧 Descriptions + Form 展示选中节点详情；新增子模块使用节点上的"+"按钮直接打开 Drawer。

三、通用交互规则

3.1 操作反馈

• 成功：message.success，文案 "<动作>成功"，自动消失 2 秒。
• 失败：message.error 或 Modal.error，文案优先取后端返回的 message，缺省"操作失败，请稍后重试"。
• 危险操作：删除 / 停用使用 Modal.confirm 二次确认，确认按钮使用 danger 色。
• 长耗时按钮：超过 300 ms 的请求按钮 loading=true，禁用重复点击。

3.2 数据展示

• 空状态：Empty 组件，文案统一 "暂无数据"。
• 加载：列表整体 Spin；局部加载使用 Skeleton。
• 异常：请求失败统一 Result 组件 + "重试"按钮，错误码 / 错误信息以小字置于副标题。

3.3 权限控制（前端）

• 菜单级：登录返回的菜单树驱动 Sider Menu，未授权模块不渲染。
• 按钮级：自定义 <Authorized code="XXX"> 包装组件，按权限码控制按钮可见 / 禁用。
• 路由级：<RequireAuth> 高阶组件，未授权路由重定向到 403 页。
• 所有权限码与后端 RBAC 对齐，前端不做信任决策，仅做展示控制。

四、Design Tokens

4.1 全局调色板

与 Ant Design 5.x 主题 token 对齐，统一以 CSS 变量定义于 src/styles/tokens.css，并通过 ConfigProvider.theme.token 映射。

语义	变量名	默认值	用途
主色	--color-primary	#1677ff	主按钮 / 链接 / 高亮
成功	--color-success	#52c41a	成功消息 / 正向状态标签
警告	--color-warning	#faad14	提醒类反馈
错误	--color-error	#ff4d4f	错误消息 / 危险按钮
主文字	--color-text	rgba(0,0,0,0.88)	正文文字
次文字	--color-text-secondary	rgba(0,0,0,0.65)	辅助说明
边框	--color-border	#d9d9d9	表单边框 / 分割线
背景	--color-bg	#ffffff	主体背景
容器背景	--color-bg-container	#fafafa	Card / Sider 等容器

4.2 组件级状态色

序号	组件	编辑 bg	只读 bg	悬浮 bg	编辑 fg	只读 fg	悬浮 fg	备注
1	Form Input	var(--color-bg)	var(--color-bg-container)	var(--color-bg)	var(--color-text)	var(--color-text-secondary)	var(--color-text)	只读使用 disabled 样式
2	Table Row	var(--color-bg)	var(--color-bg)	var(--color-row-hover)	var(--color-text)	var(--color-text)	var(--color-text)	选中行另用 --color-row-selected
3	Button Primary	var(--color-primary)	—	var(--color-primary-hover)	#fff	—	#fff	危险按钮用 --color-error 系

Token 默认值：

Token	默认值
--color-row-hover	#f5f5f5
--color-row-selected	#e6f4ff
--color-primary-hover	#4096ff

4.3 引用约定

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

五、页面清单

module_mod 模块管理

• 模块列表 / 树形管理 (/mod/list)
  • 类型: 树形管理页（左 Tree 右 Form/Descriptions）
  • 对应 REQ: REQ-MOD-001 / REQ-MOD-002 / REQ-MOD-003 / REQ-MOD-004
  • 入口菜单: 系统配置 → 模块管理
  • 主要交互: 关键字搜索 sModuleNameZh 模糊匹配；左侧 Tree 选中节点 → 右侧 Descriptions 展示详情；节点上 "+" 打开 Drawer 新增子模块；"编辑" 按钮打开 Drawer 修改；"删除" 按钮触发 Modal.confirm 二次确认软删除（存在子节点时禁用并提示）

module_usr 用户管理

• 用户列表 (/usr/list)

  • 类型: 列表页
  • 对应 REQ: REQ-USR-003（查询）/ REQ-USR-001（新增入口）/ REQ-USR-002（编辑入口）
  • 入口菜单: 系统配置 → 用户管理
  • 主要交互: 顶部搜索栏（查询字段下拉 + 匹配方式下拉 + 查询值文本框）；右上 "新增用户" 主按钮；表格列尾 "编辑 / 详情" 操作；分页器（20/页 默认）

• 用户表单（新增 / 编辑） (/usr/list?drawer=user)

  • 类型: 表单页（Drawer 形式，与列表页同路由用 query 控制开合）
  • 对应 REQ: REQ-USR-001 / REQ-USR-002
  • 入口菜单: 列表页"新增用户"按钮 / 列表行"编辑"按钮
  • 主要交互: 基本字段表单（用户号 / 用户名 / 员工 / 类型 / 语言 / 单据修改权限）+ 权限组多选 Table；保存触发后端校验，唯一性冲突在字段下方红字提示；初始密码不在表单展示，由后端默认 666666

• 登录页 (/login)

  • 类型: 表单页（独立全屏布局，不走 Layout 框架）
  • 对应 REQ: REQ-USR-004
  • 入口菜单: 未登录时所有路由重定向到此
  • 主要交互: 用户名 + 密码（星号显示）+ 版本下拉；提交登录返回 token 写入内存 / Cookie；连续失败锁定后展示剩余冷却时间并禁用按钮