# 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 灰底）；权限组勾选反映当前授权状态。提交成功提示「保存成功」并返回列表。