# 06-UI交互规范

## 一、整体布局

### 1.1 页面框架

采用 Ant Design 5.x 的 `Layout` 组件构建整体骨架，分三段：

- **Header（顶部导航）**：左侧 Logo + 系统名（"小羚羊 ERP"），右侧用户头像下拉（个人信息 / 修改密码 / 退出登录）。
- **Sider（侧边菜单）**：固定左侧，使用 `Menu` 组件以树形展示由 MOD 模块管理维护的功能菜单，支持折叠。
- **Content（主区域）**：路由出口，渲染各业务页面，外包 `Breadcrumb` + `PageHeader` 上下文容器。

整体使用 `ConfigProvider` 注入主题与中文 `zh_CN` locale。

### 1.2 布局参数

| 项 | 默认值 | 说明 |
|---|---|---|
| Header 高度 | 56 px | 紧凑信息密度，留出更多内容区 |
| Sidebar 展开宽度 | 220 px | 菜单文案完整可见 |
| Sidebar 折叠宽度 | 56 px | 仅图标 |
| Content 内边距 | 16 px | 与 Card / Table 的内边距对齐 |
| 最小分辨率 | 1366 × 768 | ERP 桌面端为主，不做移动端适配 |

## 二、标准页面类型

基于 USR / MOD 模块均为典型主数据维护场景，列表 / 表单 / 详情 三类页面足以覆盖；用户与模块均为扁平或浅层树结构，再补一个树形管理页用于 MOD。

### 2.1 列表页

自上而下三段：

- **顶部操作区**：左侧批量动作（启用 / 停用 / 删除），右侧主操作（"新增 X"）。
- **搜索栏**：`Form` 行内布局，含关键字 + 1~2 个枚举筛选；提交触发请求，"重置"清空。
- **表格 + 分页**：`Table` + 服务端分页（`Pagination`），列尾固定 `操作` 列（编辑 / 详情 / 删除）。
- 删除等危险操作需 `Modal.confirm` 二次确认。

### 2.2 表单页

新建 / 编辑统一使用右侧 `Drawer`（宽度 600 px），不跳页：

- 字段使用 Ant Design `Form` + `Form.Item`，校验时机 `onBlur`，提交前再 `validateFields` 全量校验。
- 提交按钮固定在 Drawer 右下角，主按钮"保存"在右、"取消"在左。
- 提交期间按钮 `loading=true`，避免重复提交。

### 2.3 详情页

使用 `Descriptions`（`bordered + column={2}`）展示主数据，必要时 `Tabs` 切分"基本信息 / 关联资源 / 操作日志"等子页签；详情页只读，编辑动作回到 Drawer 表单。

### 2.4 树形管理页

仅 MOD 模块管理使用：左侧 `Tree` 展示模块层级，右侧 `Descriptions` + `Form` 展示选中节点详情；新增子模块使用节点上的"+"按钮直接打开 Drawer。

## 三、通用交互规则

### 3.1 操作反馈

- **成功**：`message.success`，文案 "<动作>成功"，自动消失 2 秒。
- **失败**：`message.error` 或 `Modal.error`，文案优先取后端返回的 `message`，缺省"操作失败，请稍后重试"。
- **危险操作**：删除 / 停用使用 `Modal.confirm` 二次确认，确认按钮使用 `danger` 色。
- **长耗时按钮**：超过 300 ms 的请求按钮 `loading=true`，禁用重复点击。

### 3.2 数据展示

- **空状态**：`Empty` 组件，文案统一 "暂无数据"。
- **加载**：列表整体 `Spin`；局部加载使用 Skeleton。
- **异常**：请求失败统一 `Result` 组件 + "重试"按钮，错误码 / 错误信息以小字置于副标题。

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

- **菜单级**：登录返回的菜单树驱动 `Sider Menu`，未授权模块不渲染。
- **按钮级**：自定义 `<Authorized code="XXX">` 包装组件，按权限码控制按钮可见 / 禁用。
- **路由级**：`<RequireAuth>` 高阶组件，未授权路由重定向到 403 页。
- 所有权限码与后端 RBAC 对齐，前端不做信任决策，仅做展示控制。

## 四、Design Tokens

### 4.1 全局调色板

与 Ant Design 5.x 主题 token 对齐，统一以 CSS 变量定义于 `src/styles/tokens.css`，并通过 `ConfigProvider.theme.token` 映射。

| 语义 | 变量名 | 默认值 | 用途 |
|---|---|---|---|
| 主色 | `--color-primary` | `#1677ff` | 主按钮 / 链接 / 高亮 |
| 成功 | `--color-success` | `#52c41a` | 成功消息 / 正向状态标签 |
| 警告 | `--color-warning` | `#faad14` | 提醒类反馈 |
| 错误 | `--color-error` | `#ff4d4f` | 错误消息 / 危险按钮 |
| 主文字 | `--color-text` | `rgba(0,0,0,0.88)` | 正文文字 |
| 次文字 | `--color-text-secondary` | `rgba(0,0,0,0.65)` | 辅助说明 |
| 边框 | `--color-border` | `#d9d9d9` | 表单边框 / 分割线 |
| 背景 | `--color-bg` | `#ffffff` | 主体背景 |
| 容器背景 | `--color-bg-container` | `#fafafa` | Card / Sider 等容器 |

### 4.2 组件级状态色

| 序号 | 组件 | 编辑 bg | 只读 bg | 悬浮 bg | 编辑 fg | 只读 fg | 悬浮 fg | 备注 |
|---|---|---|---|---|---|---|---|---|
| 1 | Form Input | `var(--color-bg)` | `var(--color-bg-container)` | `var(--color-bg)` | `var(--color-text)` | `var(--color-text-secondary)` | `var(--color-text)` | 只读使用 `disabled` 样式 |
| 2 | Table Row | `var(--color-bg)` | `var(--color-bg)` | `var(--color-row-hover)` | `var(--color-text)` | `var(--color-text)` | `var(--color-text)` | 选中行另用 `--color-row-selected` |
| 3 | Button Primary | `var(--color-primary)` | — | `var(--color-primary-hover)` | `#fff` | — | `#fff` | 危险按钮用 `--color-error` 系 |

**Token 默认值**：

| Token | 默认值 |
|---|---|
| `--color-row-hover` | `#f5f5f5` |
| `--color-row-selected` | `#e6f4ff` |
| `--color-primary-hover` | `#4096ff` |

### 4.3 引用约定

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

## 五、页面清单

### module_mod 模块管理

- **模块列表 / 树形管理** (`/mod/list`)
  - 类型: 树形管理页（左 Tree 右 Form/Descriptions）
  - 对应 REQ: REQ-MOD-001 / REQ-MOD-002 / REQ-MOD-003 / REQ-MOD-004
  - 入口菜单: 系统配置 → 模块管理
  - 主要交互: 关键字搜索 `sModuleNameZh` 模糊匹配；左侧 Tree 选中节点 → 右侧 Descriptions 展示详情；节点上 "+" 打开 Drawer 新增子模块；"编辑" 按钮打开 Drawer 修改；"删除" 按钮触发 Modal.confirm 二次确认软删除（存在子节点时禁用并提示）

### module_usr 用户管理

- **用户列表** (`/usr/list`)
  - 类型: 列表页
  - 对应 REQ: REQ-USR-003（查询）/ REQ-USR-001（新增入口）/ REQ-USR-002（编辑入口）
  - 入口菜单: 系统配置 → 用户管理
  - 主要交互: 顶部搜索栏（查询字段下拉 + 匹配方式下拉 + 查询值文本框）；右上 "新增用户" 主按钮；表格列尾 "编辑 / 详情" 操作；分页器（20/页 默认）

- **用户表单（新增 / 编辑）** (`/usr/list?drawer=user`)
  - 类型: 表单页（Drawer 形式，与列表页同路由用 query 控制开合）
  - 对应 REQ: REQ-USR-001 / REQ-USR-002
  - 入口菜单: 列表页"新增用户"按钮 / 列表行"编辑"按钮
  - 主要交互: 基本字段表单（用户号 / 用户名 / 员工 / 类型 / 语言 / 单据修改权限）+ 权限组多选 Table；保存触发后端校验，唯一性冲突在字段下方红字提示；初始密码不在表单展示，由后端默认 `666666`

- **登录页** (`/login`)
  - 类型: 表单页（独立全屏布局，不走 Layout 框架）
  - 对应 REQ: REQ-USR-004
  - 入口菜单: 未登录时所有路由重定向到此
  - 主要交互: 用户名 + 密码（星号显示）+ 版本下拉；提交登录返回 token 写入内存 / Cookie；连续失败锁定后展示剩余冷却时间并禁用按钮