# 06-UI交互规范

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

## 一、通用交互规则

### 1.1 操作反馈

- **成功提示**：使用 Ant Design `message.success`，3 秒自动消失；不阻塞操作。
- **失败提示**：使用 `message.error` 显示后端 `Result.message`；4.5 秒消失；保留可复制。
- **危险操作**（删除 / 停用 / 重置密码）：必须 `Modal.confirm` 二次确认，标题写明动作，正文写明影响对象 + 不可逆性。
- **长耗时按钮**（>300ms）：按钮 `loading` 态 + 禁用，避免重复提交；提交完成后恢复。
- **表单校验失败**：字段下方红字提示；首个错误字段自动聚焦并滚入视口。

### 1.2 数据展示

- **空状态**：使用 `Empty` 组件，图标 + 一句话说明（如 `暂无用户`）+ 主操作按钮（如 `新增用户`）。
- **加载中**：列表用 `Skeleton`；单组件用 `Spin`；全屏首次加载允许使用 `Spin` 覆盖。
- **异常态**：网络 / 5xx 错误使用 `Result status="error"` 显示，附 `重试` 按钮。
- **分页**：默认 20 条 / 页，可选 10 / 20 / 50 / 100；显示总数 + 当前页 / 总页数。
- **表格列**：必显列固定在左侧；操作列固定在右侧；时间列统一格式 `YYYY-MM-DD HH:mm`。

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

- **菜单级**：Redux `auth.user.permissions` 驱动；菜单项无权限直接不渲染。
- **路由级**：`router/index.tsx` 用 `RequireAuth` + `RequireRole` 高阶守卫；未授权重定向到登录或 403 页。
- **按钮级**：`<Permission code="...">` 包裹按钮，无权限时不渲染（不显示 disabled 灰按钮）。
- **后端 RBAC 同源**：前端权限码与后端 `Permission` 表严格对齐（codename 一致）；前端只做展示控制，最终鉴权由后端兜底。

## 二、Design Tokens

> 所有色值统一以 CSS 变量定义于 `frontend/src/styles/tokens.css`；命名规范见 docs/04 § 2.5。组件样式只引用 `var(--color-xxx)`，禁止硬编码 hex / rgba。

### 2.1 全局调色板

与 Ant Design 5 默认主题对齐，按语义分组。

| 语义 | 变量名 | 默认值 | 用途 |
|---|---|---|---|
| 主色 | `--color-primary` | `#1677ff` | 主按钮、链接、激活态边框 |
| 主色-悬浮 | `--color-primary-hover` | `#4096ff` | 主色控件 hover |
| 主色-激活 | `--color-primary-active` | `#0958d9` | 主色控件 active / pressed |
| 成功 | `--color-success` | `#52c41a` | 成功提示、积极状态标签 |
| 警告 | `--color-warning` | `#faad14` | 警告提示、需注意状态 |
| 错误 | `--color-error` | `#ff4d4f` | 错误提示、危险按钮 |
| 信息 | `--color-info` | `#1677ff` | 普通信息提示 |
| 主文字 | `--color-text` | `rgba(0,0,0,0.88)` | 标题、正文 |
| 次文字 | `--color-text-secondary` | `rgba(0,0,0,0.65)` | 辅助说明 |
| 禁用文字 | `--color-text-disabled` | `rgba(0,0,0,0.25)` | 禁用态 |
| 边框 | `--color-border` | `#d9d9d9` | 输入框 / 卡片边框 |
| 分割线 | `--color-split` | `#f0f0f0` | 列表分割线 |
| 背景-页面 | `--color-bg-page` | `#f5f5f5` | 页面底色 |
| 背景-容器 | `--color-bg-container` | `#ffffff` | 卡片 / 表单 / Modal |
| 背景-禁用 | `--color-bg-disabled` | `#f5f5f5` | 禁用控件 |

### 2.2 组件级状态色

按场景 × 状态映射，单元格写 token 引用形式（`var(--color-xxx)`）。`—` 表示该状态不适用。

| # | 组件 | 编辑bg | 只读bg | 悬浮bg | 编辑fg | 只读fg | 悬浮fg | 备注 |
|---|---|---|---|---|---|---|---|---|
| 1 | Input | `var(--color-bg-container)` | `var(--color-bg-disabled)` | `var(--color-bg-container)` | `var(--color-text)` | `var(--color-text-secondary)` | `var(--color-text)` | 只读用 `readOnly`，禁用用 `disabled` |
| 2 | Select | `var(--color-bg-container)` | `var(--color-bg-disabled)` | `var(--color-bg-container)` | `var(--color-text)` | `var(--color-text-secondary)` | `var(--color-text)` | 同 Input |
| 3 | Button-Primary | `var(--color-primary)` | — | `var(--color-primary-hover)` | `#fff` | — | `#fff` | 主操作 |
| 4 | Button-Default | `var(--color-bg-container)` | — | `var(--color-bg-container)` | `var(--color-text)` | — | `var(--color-primary)` | 次操作 |
| 5 | Button-Danger | `var(--color-error)` | — | `#ff7875` | `#fff` | — | `#fff` | 删除 / 停用 |
| 6 | Table-Row | `var(--color-bg-container)` | — | `#fafafa` | `var(--color-text)` | — | `var(--color-text)` | 斑马纹关闭 |
| 7 | Tag-Success | `#f6ffed` | — | — | `var(--color-success)` | — | — | 正常 / 启用状态 |
| 8 | Tag-Error | `#fff2f0` | — | — | `var(--color-error)` | — | — | 停用 / 失败状态 |

**Token 默认值**（与 § 2.1 完整一致；新增 token 时此表与 tokens.css 同步更新）。

### 2.3 引用约定

- 组件样式只用 `var(--color-xxx)`，**禁止**直接写 hex / rgb / rgba。
- 新增 token 必须先登记到 § 2.1 / 2.2，再写入 `tokens.css`。
- 修改色值只改 `tokens.css` 一处；组件层不允许覆盖（如 `.ant-btn-primary { background: ... }` 之类禁止）。

## 三、页面清单
（由 `downstream-gen` 按模块追加段落）

### module_usr 用户管理

- **登录页** (`/login`)
  - 类型: 表单页
  - 对应 REQ: REQ-USR-001
  - 入口菜单: 未登录访问任何路径均重定向至此
  - 主要交互: 公司/版本下拉（页面加载时拉取 `GET /api/v1/companies`）→ 输入用户名 / 密码（密码星号显示）→ 提交按钮带 loading 态防重复提交；连续 5 次失败显示锁定剩余时间；成功后写 access token 到内存并跳转默认主页

- **用户列表** (`/users`)
  - 类型: 列表页
  - 对应 REQ: REQ-USR-002（"新增"入口）、REQ-USR-003（"编辑"行内按钮）、REQ-USR-004（列表分页 + 筛选）
  - 入口菜单: 系统管理 → 用户管理
  - 主要交互: 顶部筛选区（查询字段下拉 / 匹配方式下拉 / 查询值输入框 / 查询按钮）+ 右上"新增用户"按钮 + Ant Design Table（含序号 / 用户名 / 员工名 / 用户号 / 部门 / 用户类型 / 语言 / 作废标签 / 登录日期 / 制单人 / 制单日期 / 操作列）+ 分页器（10/20/50/100）；编辑按钮打开 Modal 复用新增表单组件（按 REQ-USR-003 字段差异置只读 / 禁用）；不允许停用当前登录账号自己（按钮 disabled + tooltip 解释）

- **用户表单**（嵌入式 Modal，无独立路由）
  - 类型: 表单页（Modal）
  - 对应 REQ: REQ-USR-002 / REQ-USR-003
  - 入口菜单: 由用户列表的"新增" / "编辑"按钮触发
  - 主要交互: 左侧基础信息区（员工名下拉 / 用户号 / 用户名 / 类型下拉 / 语言下拉 / 单据修改权限复选框 / 作废复选框（仅编辑））+ 右侧权限组区（按 `sys_permission_category` 渲染勾选列表）+ 底部"保存"/"取消"；保存调 `POST /api/v1/users`（新增）或 `PUT /api/v1/users/{userId}`（编辑），成功后关闭 Modal 并刷新列表