# 06-UI交互规范

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

## 一、通用交互规则

### 1.1 操作反馈

- **成功提示**：使用 Ant Design `message.success()`，默认 3s 自动消失；新增 / 修改 / 删除等写操作必须给反馈。
- **失败提示**：使用 `message.error()` 显示后端返回的 `message` 字段；表单字段级错误用 Form 的 `validateStatus="error"` + `help` 同步显示。
- **危险操作二次确认**：删除 / 禁用 / 重置密码等不可逆操作必须用 `Modal.confirm({ okType: 'danger' })` 二次确认，按钮文案使用业务动词（如「确认禁用」），不用「确定」。
- **长耗时按钮 loading**：提交类按钮在请求未返回前必须置为 `loading=true` 并禁用，避免重复提交；查询类操作在表格组件上启用 `loading` 属性即可。

### 1.2 数据展示

- **空状态**：列表 / 表格无数据时使用 `<Empty description="暂无数据" />`，明细页无数据时附加「返回列表」按钮。
- **加载状态**：页面级加载用 `<Spin spinning>` 包裹主区域；表格 / 卡片局部加载用组件自带 `loading` 属性。
- **异常状态**：接口 5xx 或网络异常时显示 `<Result status="error" title="加载失败" extra={<Button>重试</Button>} />`；403 时显示「无权限」并提供「返回首页」按钮。

### 1.3 权限控制（前端）

- **菜单级**：登录后由后端返回菜单权限码列表，前端 Layout 按权限码过滤后渲染左侧菜单。
- **按钮级**：包装 `<AuthButton code="USR:ADD">新增</AuthButton>`，权限码不在用户列表时直接不渲染（避免显示再禁用）。
- **路由级**：在 React Router 外层包 `<AuthRoute />`，路由元数据声明 `meta.code`，无权限重定向 403 页面。
- **关联后端 RBAC**：权限码格式 `<模块代码>:<动作>`（如 `USR:ADD` / `USR:EDIT` / `USR:DELETE`），与后端 Spring Security `@PreAuthorize("hasAuthority('USR:ADD')")` 一一对应。

## 二、Design Tokens

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

### 2.1 全局调色板

与 Ant Design 5 主题对齐，统一通过 `<ConfigProvider theme={{ token: {...} }}>` 注入。

| 语义 | 变量名 | 默认值 | 用途 |
|---|---|---|---|
| 主色 | `--color-primary` | `#1677ff` | 主操作按钮 / 链接 / 选中态 |
| 成功 | `--color-success` | `#52c41a` | 成功消息 / 启用状态标签 |
| 警告 | `--color-warning` | `#faad14` | 警告消息 / 待处理状态 |
| 错误 | `--color-error` | `#ff4d4f` | 错误消息 / 危险按钮 / 禁用状态 |
| 主文字 | `--color-text-primary` | `rgba(0, 0, 0, 0.88)` | 正文 / 表格内容 |
| 次文字 | `--color-text-secondary` | `rgba(0, 0, 0, 0.65)` | 辅助说明 / 占位 |
| 边框 | `--color-border` | `#d9d9d9` | 表单输入 / 卡片边界 |
| 背景 | `--color-bg-base` | `#ffffff` | 页面主背景 |
| 弱背景 | `--color-bg-layout` | `#f5f5f5` | 页面 layout 间隙 / 灰底 |

### 2.2 组件级状态色

| 序号 | 组件 | 编辑bg | 只读bg | 悬浮bg | 编辑fg | 只读fg | 悬浮fg | 备注 |
|---|---|---|---|---|---|---|---|---|
| 1 | 表单输入框 | `var(--color-bg-base)` | `var(--color-bg-layout)` | `var(--color-bg-base)` | `var(--color-text-primary)` | `var(--color-text-secondary)` | `var(--color-text-primary)` | 只读态边框使用 `transparent` |
| 2 | 下拉单选 | `var(--color-bg-base)` | `var(--color-bg-layout)` | `var(--color-bg-base)` | `var(--color-text-primary)` | `var(--color-text-secondary)` | `var(--color-text-primary)` | — |
| 3 | 表格行 | — | `var(--color-bg-base)` | `var(--color-bg-row-hover)` | — | `var(--color-text-primary)` | `var(--color-text-primary)` | 编辑态走 Modal，行内不编辑 |
| 4 | 主按钮 | `var(--color-primary)` | `var(--color-bg-layout)` | `var(--color-primary-hover)` | `#ffffff` | `var(--color-text-secondary)` | `#ffffff` | 危险按钮替换 `--color-error` |
| 5 | 链接 | — | — | `var(--color-primary-hover)` | `var(--color-primary)` | — | `var(--color-primary-hover)` | — |

**Token 默认值**：

| Token | 默认值 |
|---|---|
| `--color-primary-hover` | `#4096ff` |
| `--color-bg-row-hover` | `#fafafa` |

### 2.3 引用约定

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

## 三、页面清单

### module_usr USR-用户管理

- **登录页** (`/login`)
  - 类型: 表单页
  - 对应 REQ: REQ-USR-001
  - 入口菜单: 无（未登录态唯一可达页面）
  - 主要交互: 表单输入 用户名 / 密码 / 版本 → 提交 → 成功跳首页 / 失败留页并显示通用错误消息；账号锁定时显示锁定提示
- **用户列表页** (`/usr/users`)
  - 类型: 列表页
  - 对应 REQ: REQ-USR-004
  - 入口菜单: 系统管理 → 用户管理 → 用户列表
  - 主要交互: 查询字段 + 匹配方式 + 查询值 三段筛选 → 表格分页展示 → 行内「编辑」「禁用 / 启用」按钮（权限码 `USR:EDIT`）；顶部「新增用户」按钮（权限码 `USR:ADD`）跳新增表单
- **用户新增页** (`/usr/users/new`)
  - 类型: 表单页
  - 对应 REQ: REQ-USR-002
  - 入口菜单: 系统管理 → 用户管理 → 用户列表 → 新增按钮
  - 主要交互: 员工名（下拉单选）选择后自动回填用户号 / 用户名；类型 / 语言下拉；权限组表格（多选）；提交校验失败显示字段级 `validateStatus="error"`；成功 message.success 后回列表页
- **用户编辑页** (`/usr/users/:id/edit`)
  - 类型: 表单页
  - 对应 REQ: REQ-USR-003
  - 入口菜单: 用户列表 → 行内「编辑」按钮
  - 主要交互: 复用新增表单组件；用户名只读；提供「重置密码」按钮（二次确认）；提供「禁用 / 启用」开关；禁用自己时按钮置灰