06-UI交互规范

本项目所有页面布局以项目根 prototype/ 目录下的静态 HTML mockup 为权威。前端阶段（fe-feature-*）实现时直接以 prototype/ HTML 推导组件树与样式。本文件仅承载跨页面通用规则与 Design Tokens。

一、通用交互规则

1.1 操作反馈

• 成功反馈：表单提交 / 数据操作成功后，统一使用 Ant Design message.success（顶部居中，2 秒自动消失），文案以"操作动词 + 成功"格式，例如"保存成功""删除成功""登录成功"。
• 失败反馈：业务错误使用 message.error（4 秒），文案直接展示后端返回的 msg 字段；网络异常或 5xx 使用 notification.error（右上角，需手动关闭），标题统一"操作失败"，描述给出可复制的 traceId（便于排查）。
• 危险操作二次确认：删除、禁用、批量更新等不可逆或影响范围大的动作，统一使用 Modal.confirm（图标 ExclamationCircleOutlined），确认按钮使用 danger 主题，按钮文案"确认删除/确认禁用"，禁止默认聚焦确认按钮。
• 长耗时按钮 loading 态：所有提交按钮在请求未返回前必须置 loading=true 并禁用其他相关按钮；超过 10 秒未返回，前端在 button 上叠加文案"处理中…"提示用户耐心等待，不主动中断。

1.2 数据展示

• 空状态：列表无数据统一使用 Ant Design Empty 组件，描述文案"暂无数据"；带筛选条件时改为"未找到匹配的记录，请调整筛选条件"。
• 加载态：列表 / 详情页统一使用 Skeleton（结构化骨架屏），不允许使用纯 spinner 遮罩整页；表格内联加载使用 Table 自带 loading 属性。
• 异常态：接口失败导致页面无法渲染时，使用 Result 组件（status="error"），标题"加载失败"，描述展示业务错误码与可复制 traceId，并提供"重试"主按钮。

1.3 权限控制（前端）

• 路由级：在 React Router 外层封装 <RequireAuth>，未登录跳 /login，已登录但权限不足跳 /403；权限定义由后端 RBAC 接口返回当前用户的 permissions 字符串数组（如 usr:user:create）。
• 菜单级：左侧菜单根据 permissions 过滤；用户看不到的模块完全不出现，不做置灰处理。
• 按钮级：封装 <AuthButton perm="usr:user:create"> 组件，无权限时直接不渲染（而非禁用）。后端接口必须独立做权限校验，前端权限隐藏只是用户体验层。

二、Design Tokens

2.1 全局调色板

所有色值统一以 CSS 变量定义于 src/styles/tokens.css，与 Ant Design 5 的 ConfigProvider.theme.token 双向对齐。

语义	变量名	默认值	用途
主色	--color-primary	#1677ff	主按钮、链接、选中态；映射 AntD colorPrimary
成功	--color-success	#52c41a	成功态、有效状态指示
警告	--color-warning	#faad14	警告 tag / message
错误	--color-error	#ff4d4f	错误 message、危险按钮、必填校验失败
主文字	--color-text	rgba(0,0,0,0.88)	标题、正文
次文字	--color-text-secondary	rgba(0,0,0,0.65)	表单 label、辅助说明
三级文字	--color-text-tertiary	rgba(0,0,0,0.45)	placeholder、禁用文字
边框	--color-border	#d9d9d9	输入框、卡片、表格分割线
背景	--color-bg	#ffffff	卡片、模态框背景
页面背景	--color-bg-layout	#f5f5f5	整页底色

2.2 组件级状态色

序号	组件	编辑 bg	只读 bg	悬浮 bg	编辑 fg	只读 fg	悬浮 fg	备注
1	表单输入框	var(--color-bg)	var(--color-bg-layout)	var(--color-bg)	var(--color-text)	var(--color-text-secondary)	var(--color-text)	只读使用 Input 的 readOnly 属性
2	表格行	var(--color-bg)	—	var(--color-row-hover)	var(--color-text)	—	var(--color-text)	表格 hover 高亮
3	选中行	—	—	var(--color-row-selected)	—	—	var(--color-primary)	单选 / 多选
4	主按钮	var(--color-primary)	var(--color-text-tertiary)	var(--color-primary-hover)	#fff	#fff	#fff	禁用态走只读列
5	危险按钮	var(--color-error)	—	var(--color-error-hover)	#fff	—	#fff	删除 / 禁用类操作

Token 默认值（在 src/styles/tokens.css 定义）：

变量名	默认值
--color-row-hover	#fafafa
--color-row-selected	#e6f4ff
--color-primary-hover	#4096ff
--color-error-hover	#ff7875

2.3 引用约定

• 组件样式只用 var(--color-xxx)，禁止硬编码 hex / rgba。
• 新增 token 须先登记到 § 2.1 / 2.2 再补 tokens.css，禁止"先写代码后补登记"。
• 修改色值只改 tokens.css 一处，不允许组件层 style / CSS Module 覆盖；如确实业务需要新色，走"新增 token"流程。

三、页面清单

module_usr 用户管理

• 登录页 (/login)

  • 类型: 表单页
  • 对应 REQ: REQ-USR-004
  • 入口菜单: 系统外（匿名访问入口）
  • 主要交互: 输入用户名 / 密码 / 选择版本（公司）→ 提交 → 成功跳 /；失败统一弹「用户名或密码错误」（不区分），账号锁定时弹锁定截止时间。

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

  • 类型: 列表页
  • 对应 REQ: REQ-USR-003
  • 入口菜单: 系统管理 → 用户管理
  • 主要交互: 顶部筛选区（查询字段下拉 + 匹配方式下拉 + 查询值输入）+ 表格（分页 / 排序）+ 操作列（编辑 / 作废）+ 顶部「新增」按钮跳新增页。

• 用户新增页 (/usr/user/new)

  • 类型: 表单页
  • 对应 REQ: REQ-USR-001
  • 入口菜单: 用户列表页「新增」按钮
  • 主要交互: 用户号 / 用户名手工输入，员工名下拉（来自 tEmployee），类型 / 语言下拉，单据修改权限复选，权限组复选框列表（来自 tPermission）。提交成功提示「保存成功」并返回列表。

• 用户编辑页 (/usr/user/:userId/edit)

  • 类型: 表单页
  • 对应 REQ: REQ-USR-002
  • 入口菜单: 用户列表页「编辑」操作
  • 主要交互: 表单字段同新增，但用户号 / 用户名 / 密码不可编辑（置 readOnly 灰底）；权限组勾选反映当前授权状态。提交成功提示「保存成功」并返回列表。