# 06-UI交互规范

## 一、整体布局

### 1.1 页面框架

使用 Ant Design `Layout` 组件搭建整体骨架：
- **Header**：顶部导航栏，显示系统名称、用户信息、退出按钮
- **Sider**：左侧菜单栏，使用 `Menu` 组件，支持折叠
- **Content**：右侧主内容区，承载各模块页面

整体结构为 `Header + (Sider + Content)` 的经典 Admin 布局。

### 1.2 布局参数

| 参数 | 默认值 | 说明 |
|---|---|---|
| Header 高度 | 64px | 固定顶部 |
| Sidebar 宽度（展开） | 220px | 左侧菜单展开宽度 |
| Sidebar 宽度（折叠） | 64px | 左侧菜单折叠宽度 |
| Content 内边距 | 24px | 内容区四周间距 |
| 最小支持分辨率 | 1280×720 | 企业内部应用最低屏幕要求 |

## 二、标准页面类型

### 2.1 列表页

- **顶部操作区**：新增、导入、导出按钮靠右对齐
- **搜索栏**：使用 `Form` + `Input` / `Select` / `DatePicker` 组合，搜索按钮在最右侧
- **表格**：使用 `Table` 组件，支持分页、行选择、列排序
- **分页**：位于表格底部右侧，显示总条数，每页默认 20 条

### 2.2 表单页

- 新增/编辑统一使用 `Drawer`（宽度 520px），避免完整页面跳转
- 校验时机：失焦时触发单字段校验，提交时触发全量校验
- 提交按钮位于 Drawer 底部右侧（「确定」+「取消」），固定不随内容滚动

### 2.3 详情页

- 使用 `Descriptions` 展示基本信息（labelWidth 100px，border 模式）
- 多维度信息使用 `Tabs` 切换（如基本信息 / 操作日志 / 关联记录）

### 2.4 树形管理页

用于用户管理中的角色/权限树，使用 Ant Design `Tree` + 右侧 `Drawer` 的左右布局：
- 左侧 Tree 支持搜索、展开/折叠
- 右侧 Drawer 展示选中节点的详细信息或编辑表单

## 三、通用交互规则

### 3.1 操作反馈

- **成功**：`message.success()`，右上角弹出，持续 2s
- **失败**：`message.error()`，持续 3s，错误文案来自接口返回 `message` 字段
- **危险操作**（删除、批量操作）：`Modal.confirm()` 二次确认，标注受影响数量
- **长耗时操作**（导入/导出）：按钮进入 `loading` 态，禁止重复点击

### 3.2 数据展示

| 状态 | 组件 | 文案 |
|---|---|---|
| 空数据 | `Empty` | "暂无数据" |
| 加载中 | `Spin` + `Skeleton` | — |
| 接口异常 | `Result` (status=500) | "数据加载失败，请刷新重试" |

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

- **菜单级**：根据后端返回的权限码动态渲染菜单项，无权限则不显示
- **按钮级**：封装 `<PermButton permission="xxx:yyy">` 组件，无权限时按钮隐藏
- **路由级**：在 React Router 的路由守卫中校验权限，无权限跳转 403 页面
- 权限码格式：`模块代码:操作`（如 `usr:create`、`usr:edit`），与后端 RBAC 保持一致

## 四、Design Tokens

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

### 4.1 全局调色板

| 语义 | 变量名 | 默认值 | 用途 |
|---|---|---|---|
| 主色 | `--color-primary` | `#1677ff` | 按钮/链接/高亮 |
| 成功 | `--color-success` | `#52c41a` | 成功状态/标签 |
| 警告 | `--color-warning` | `#faad14` | 警告提示 |
| 错误 | `--color-error` | `#ff4d4f` | 错误/危险操作 |
| 主文字 | `--color-text-primary` | `#000000e0` | 主要文本 |
| 次文字 | `--color-text-secondary` | `#00000073` | 辅助文本/提示 |
| 边框 | `--color-border` | `#d9d9d9` | 输入框/分割线边框 |
| 背景 | `--color-bg-base` | `#f5f5f5` | 页面底色 |

### 4.2 组件级状态色

| 序号 | 组件 | 编辑bg | 只读bg | 悬浮bg | 编辑fg | 只读fg | 悬浮fg | 备注 |
|---|---|---|---|---|---|---|---|---|
| 1 | 表单输入框 | `var(--color-bg-input-edit)` | `var(--color-bg-input-readonly)` | `var(--color-bg-input-hover)` | `var(--color-text-primary)` | `var(--color-text-secondary)` | `var(--color-text-primary)` | — |
| 2 | 表格行 | — | `var(--color-bg-table-row)` | `var(--color-bg-table-row-hover)` | — | `var(--color-text-primary)` | `var(--color-text-primary)` | 选中行用主色淡色 |
| 3 | 侧边菜单项 | — | `var(--color-bg-menu-item)` | `var(--color-bg-menu-item-hover)` | — | `var(--color-text-primary)` | `var(--color-primary)` | 活动项用主色 |

**Token 默认值**

| 变量名 | 默认值 |
|---|---|
| `--color-bg-input-edit` | `#ffffff` |
| `--color-bg-input-readonly` | `#f5f5f5` |
| `--color-bg-input-hover` | `#ffffff` |
| `--color-bg-table-row` | `#ffffff` |
| `--color-bg-table-row-hover` | `#fafafa` |
| `--color-bg-menu-item` | `transparent` |
| `--color-bg-menu-item-hover` | `rgba(0,0,0,0.06)` |

### 4.3 引用约定

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

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

### module_usr 用户管理

- **登录页** (`/login`)
  - 类型: 表单页
  - 对应 REQ: REQ-USR-004
  - 入口菜单: 不在菜单内，直接路由跳转
  - 主要交互: 填写公司编号/用户名/密码 → 提交登录 → 成功跳转主页；失败显示错误提示；连续失败锁定提示

- **用户列表页** (`/usr/users`)
  - 类型: 列表页
  - 对应 REQ: REQ-USR-001, REQ-USR-002, REQ-USR-003
  - 入口菜单: 系统管理 → 用户管理
  - 主要交互: 顶部搜索栏（字段/匹配方式/值三联筛选）+ 表格分页展示；行内「编辑」按钮弹出 Drawer；顶部「新增」按钮弹出新增 Drawer；Drawer 含权限组复选列表