# MOD_029 辅助工具

## 一、功能简介

「辅助工具」是系统的组成部分，供以下角色使用：超级管理员。

**常用场景**：

- 运营上传素材前使用图片处理工具压缩/调整尺寸

**本模块包含的页面**：

| 页面 | 进入方式 |
|------|---------|
| 图片处理 | 业务管理 > 辅助工具 > 图片处理 |

---

## 二、页面详细操作指南

### 2.1 图片处理

**进入方式**：

> 系统左侧菜单：业务管理 > 辅助工具 > 图片处理

**页面说明**：

> 页头标题「图片处理工具」+描述「支持自定义尺寸、比例、格式转换、质量控制和文件大小限制」

**可用的筛选条件**：

| 筛选项 |
|--------|
| 拖拽上传框（将图片拖到此处，或点击上传） |
| 格式提示「支持 JPG / PNG / WebP / GIF 格式，建议图片尺寸不超过 4096 × 4096」 |
| 类型错误提示「请上传 JPG / PNG / WebP / GIF 格式的图片」 |
| 超 20MB 提示「图片大小不能超过 20MB」 |
| 加载失败提示「图片加载失败」 |
| 选图成功后自动应用智能推荐并切换至处理区 |

填写条件后点击【搜索】刷新列表，点击【重置】清空条件。

**可用性提示**：conditional（已选图时显示）

**可用性提示**：conditional（已选图时显示）

**处理参数设置区**（conditional（已选图时显示））：包含 「处理参数」卡片（SettingsPanel：宽/高/格式/质量/最大文件大小KB）；卡片头部[智能推荐]链接（按原图尺寸与大小自动推荐参数）；应用推荐后提示「已应用智能推荐参数」并显示推荐理由 alert；比例变更联动裁剪框

#### 本页面可执行的操作

#### 操作1：选择待处理图片

- **操作入口**：拖拽上传框（将图片拖到此处，或点击上传）
- **操作说明**：支持 JPG/PNG/WebP/GIF，建议尺寸不超过 4096×4096；类型错误提示「请上传 JPG / PNG / WebP / GIF 格式的图片」；超 20MB 提示「图片大小不能超过 20MB」；加载失败提示「图片加载失败」；选图成功后自动应用智能推荐并切换至处理区

**操作步骤**：

1. 前置检查：登录与权限：确保已登录管理端且具备相应权限（管理端登录用户（当前租户范围））（预期结果：若权限不足，页面不显示「选择待处理图片」对应入口）
2. 触发操作：拖拽上传框：在页面 的区域「图片上传区」中，通过拖拽上传框触发「选择待处理图片」（预期结果：界面响应：弹窗打开/进入表单/列表刷新（视功能形态））
3. 录入/选择配置内容：按界面要求填写配置项：支持 JPG/PNG/WebP/GIF，建议尺寸不超过 4096×4096（预期结果：必填项填写完成，格式校验通过）
4. 提交配置：点击保存/确定提交配置（预期结果：请求提交成功）
5. 操作结果反馈：系统提示「请上传 JPG / PNG / WebP / GIF 格式的图片」，列表/界面同步刷新最新数据（预期结果：看到「请上传 JPG / PNG / WebP / GIF 格式的图片」提示且数据已更新）

异常处理：
- 异常路径：请求失败：接口异常或网络中断时，系统提示错误信息；稍后重试或联系管理员
- 异常路径：校验不通过：表单/条件校验失败时，按提示文案修正后重新填写提交

**操作流程图**：

```mermaid
flowchart TD
 A[开始: 进入图片处理页面] --> B[检查登录与权限]
 B -->|权限正常| C[拖拽上传框]
 B -->|无权限| Z0[入口不显示, 结束]
 C -->|请求异常| E1[提示错误, 稍后重试] --> C
 C --> D[填写表单信息]
 D -->|校验失败| E2[按红字提示修正] --> D
 D -->|校验通过| F[点击保存/提交]
 F -->|失败| E1
 F --> G[系统提示操作成功, 列表刷新]
 G --> Z[结束: 选择待处理图片完成]
```

**系统提示语**（与界面实际提示一致）：

- 「请上传 JPG / PNG / WebP / GIF 格式的图片」
- 「图片大小不能超过 20MB」
- 「图片加载失败」

#### 操作2：裁剪图片

- **操作入口**：「图片裁剪」卡片 CropperPanel 裁剪画布
- **操作说明**：支持固定比例/自定义比例裁剪（裁剪在浏览器本地完成）；卡片头部[重新选择]链接可清空图片返回上传区

**操作步骤**：

1. 前置检查：登录与权限：确保已登录管理端且具备相应权限（管理端登录用户（当前租户范围））（预期结果：若权限不足，页面不显示「裁剪图片」对应入口）
2. 触发操作：「图片裁剪」卡片 CropperPanel 裁剪画布：在页面 的区域「图片裁剪区」中，通过「图片裁剪」卡片 CropperPanel 裁剪画布触发「裁剪图片」（预期结果：界面响应：弹窗打开/进入表单/列表刷新（视功能形态））
3. 选定目标数据：在列表中定位目标记录（必要时先通过搜索区筛选）；支持固定比例/自定义比例裁剪（裁剪在浏览器本地完成）（预期结果：目标记录的操作按钮可见可用）
4. 二次确认：系统弹出二次确认弹窗，点击确定继续；取消则终止操作（预期结果：确认后提交请求）
5. 操作结果反馈：系统提示「操作成功」，列表/界面同步刷新最新数据（预期结果：看到「操作成功」提示且数据已更新）

异常处理：
- 异常路径：请求失败：接口异常或网络中断时，系统提示错误信息；稍后重试或联系管理员
- 异常路径：校验不通过：表单/条件校验失败时，按提示文案修正后重新填写提交

**操作流程图**：

```mermaid
flowchart TD
 A[开始: 进入图片处理页面] --> B[检查登录与权限]
 B -->|权限正常| C[「图片裁剪」卡片 CropperPanel 裁剪画布]
 B -->|无权限| Z0[入口不显示, 结束]
 C -->|请求异常| E1[提示错误, 稍后重试] --> C
 C --> D[选定目标记录]
 D -->|状态不符| E2[按钮不显示, 操作不可用] 
 D --> F{二次确认}
 F -->|取消| Z1[终止操作]
 F -->|确定| G[系统提示操作成功]
 G --> Z[结束: 裁剪图片完成]
```

**系统提示语**（与界面实际提示一致）：

- 「图片裁剪」

#### 操作3：设置处理参数

- **操作入口**：「处理参数」卡片 SettingsPanel（宽/高/格式/质量/最大文件大小KB）及卡片头部[智能推荐]链接
- **操作说明**：默认参数 694×400/jpeg/质量80/600KB；[智能推荐]按原图尺寸与大小自动推荐参数，应用后提示「已应用智能推荐参数」并显示推荐理由 alert；比例变更联动裁剪框

**操作步骤**：

1. 前置检查：登录与权限：确保已登录管理端且具备相应权限（管理端登录用户（当前租户范围））（预期结果：若权限不足，页面不显示「设置处理参数」对应入口）
2. 触发操作：「处理参数」卡片 SettingsPanel及卡片头部[智能推荐]链接：在页面 的区域「处理参数设置区」中，通过「处理参数」卡片 SettingsPanel及卡片头部[智能推荐]链接触发「设置处理参数」（预期结果：界面响应：弹窗打开/进入表单/列表刷新（视功能形态））
3. 录入/选择配置内容：按界面要求填写配置项：默认参数 694×400/jpeg/质量80/600KB（预期结果：必填项填写完成，格式校验通过）
4. 提交配置：点击保存/确定提交配置（预期结果：请求提交成功）
5. 操作结果反馈：系统提示「已应用智能推荐参数」，列表/界面同步刷新最新数据（预期结果：看到「已应用智能推荐参数」提示且数据已更新）

异常处理：
- 异常路径：请求失败：接口异常或网络中断时，系统提示错误信息；稍后重试或联系管理员
- 异常路径：校验不通过：表单/条件校验失败时，按提示文案修正后重新填写提交

**操作流程图**：

```mermaid
flowchart TD
 A[开始: 进入图片处理页面] --> B[检查登录与权限]
 B -->|权限正常| C[「处理参数」卡片 SettingsPanel及卡片头部「智能推荐」链接]
 B -->|无权限| Z0[入口不显示, 结束]
 C -->|请求异常| E1[提示错误, 稍后重试] --> C
 C --> D[填写表单信息]
 D -->|校验失败| E2[按红字提示修正] --> D
 D -->|校验通过| F[点击保存/提交]
 F -->|失败| E1
 F --> G[系统提示操作成功, 列表刷新]
 G --> Z[结束: 设置处理参数完成]
```

**系统提示语**（与界面实际提示一致）：

- 「已应用智能推荐参数」
- 「处理参数」

#### 操作4：预览处理结果

- **操作入口**：[预览]按钮
- **操作说明**：本地执行裁剪+参数处理；处理完成提示「图片处理完成」，失败提示「图片处理失败」

**操作步骤**：

1. 前置检查：登录与权限：确保已登录管理端且具备相应权限（管理端登录用户（当前租户范围））（预期结果：若权限不足，页面不显示「预览处理结果」对应入口）
2. 触发操作：[预览]按钮：在页面 的区域「预览和操作区」中，通过[预览]按钮触发「预览处理结果」（预期结果：界面响应：弹窗打开/进入表单/列表刷新（视功能形态））
3. 填写筛选条件：按搜索区条件填写筛选项：本地执行裁剪+参数处理（预期结果：条件录入完成（可随时点击重置清空条件））
4. 点击查询/搜索按钮：提交筛选条件，系统按条件查询当前租户范围数据（预期结果：列表按条件刷新，分页同步更新）
5. 操作结果反馈：系统提示「图片处理完成」，列表/界面同步刷新最新数据（预期结果：看到「图片处理完成」提示且数据已更新）

异常处理：
- 异常路径：请求失败：接口异常或网络中断时，系统提示错误信息；稍后重试或联系管理员
- 异常路径：校验不通过：表单/条件校验失败时，按提示文案修正后重新填写提交

**操作流程图**：

```mermaid
flowchart TD
 A[开始: 进入图片处理页面] --> B[检查登录与权限]
 B -->|权限正常| C[「预览」按钮]
 B -->|无权限| Z0[入口不显示, 结束]
 C -->|请求异常| E1[提示错误, 稍后重试] --> C
 C --> D[填写筛选条件]
 D -->|条件不合法| E2[按提示修正] --> D
 D --> F[点击查询]
 F --> G[列表按条件刷新]
 G --> Z[结束: 预览处理结果完成]
```

**系统提示语**（与界面实际提示一致）：

- 「图片处理完成」
- 「图片处理失败」

#### 操作5：下载处理后图片

- **操作入口**：[下载]按钮
- **操作说明**：下载文件名 processed-image.jpg；成功提示「图片已下载」

**操作步骤**：

1. 前置检查：登录与权限：确保已登录管理端且具备相应权限（管理端登录用户（当前租户范围））（预期结果：若权限不足，页面不显示「下载处理后图片」对应入口）
2. 触发操作：[下载]按钮：在页面 的区域「预览和操作区」中，通过[下载]按钮触发「下载处理后图片」（预期结果：界面响应：弹窗打开/进入表单/列表刷新（视功能形态））
3. 录入/选择配置内容：按界面要求填写配置项：下载文件名 processed-image.jpg（预期结果：必填项填写完成，格式校验通过）
4. 提交配置：点击保存/确定提交配置（预期结果：请求提交成功）
5. 操作结果反馈：系统提示「图片已下载」，列表/界面同步刷新最新数据（预期结果：看到「图片已下载」提示且数据已更新）

异常处理：
- 异常路径：请求失败：接口异常或网络中断时，系统提示错误信息；稍后重试或联系管理员
- 异常路径：校验不通过：表单/条件校验失败时，按提示文案修正后重新填写提交

**操作流程图**：

```mermaid
flowchart TD
 A[开始: 进入图片处理页面] --> B[检查登录与权限]
 B -->|权限正常| C[「下载」按钮]
 B -->|无权限| Z0[入口不显示, 结束]
 C -->|请求异常| E1[提示错误, 稍后重试] --> C
 C --> D[填写表单信息]
 D -->|校验失败| E2[按红字提示修正] --> D
 D -->|校验通过| F[点击保存/提交]
 F -->|失败| E1
 F --> G[系统提示操作成功, 列表刷新]
 G --> Z[结束: 下载处理后图片完成]
```

**系统提示语**（与界面实际提示一致）：

- 「图片已下载」

#### 操作6：上传图片到文件服务

- **操作入口**：[上传]按钮
- **操作说明**：调用后端文件上传接口（bucket=images/tool，唯一后端调用点）；成功提示「图片已上传」并显示 url/fileKey/fileName；失败提示后端返回信息或「上传失败」

**操作步骤**：

1. 前置检查：登录与权限：确保已登录管理端且具备相应权限（管理端登录用户（当前租户范围））（预期结果：若权限不足，页面不显示「上传图片到文件服务」对应入口）
2. 触发操作：[上传]按钮：在页面 的区域「预览和操作区」中，通过[上传]按钮触发「上传图片到文件服务」（预期结果：界面响应：弹窗打开/进入表单/列表刷新（视功能形态））
3. 填写表单信息：按表单要求逐项填写（必填项带红星）：调用后端文件上传接口（bucket=images/tool，唯一后端调用点）（预期结果：字段录入完成，未触发校验红字）
4. 点击保存/提交：点击弹窗或表单页的保存/确定按钮提交数据（预期结果：请求提交成功）
5. 操作结果反馈：系统提示「图片已上传」，列表/界面同步刷新最新数据（预期结果：看到「图片已上传」提示且数据已更新）

异常处理：
- 异常路径：请求失败：接口异常或网络中断时，系统提示错误信息；稍后重试或联系管理员
- 异常路径：校验不通过：表单/条件校验失败时，按提示文案修正后重新填写提交

**操作流程图**：

```mermaid
flowchart TD
 A[开始: 进入图片处理页面] --> B[检查登录与权限]
 B -->|权限正常| C[「上传」按钮]
 B -->|无权限| Z0[入口不显示, 结束]
 C -->|请求异常| E1[提示错误, 稍后重试] --> C
 C --> D[填写表单信息]
 D -->|校验失败| E2[按红字提示修正] --> D
 D -->|校验通过| F[点击保存/提交]
 F -->|失败| E1
 F --> G[系统提示操作成功, 列表刷新]
 G --> Z[结束: 上传图片到文件服务完成]
```

**系统提示语**（与界面实际提示一致）：

- 「图片已上传」
- 「上传失败」

---

## 三、常见问题与系统提示

| 操作 | 界面提示 | 处理建议 |
|------|---------|---------|
| 选择待处理图片 | 「请上传 JPG / PNG / WebP / GIF 格式的图片」 | 属正常反馈，按提示继续操作 |
| 选择待处理图片 | 「图片大小不能超过 20MB」 | 属正常反馈，按提示继续操作 |
| 选择待处理图片 | 「图片加载失败」 | 稍后重试，仍失败请联系管理员 |
| 裁剪图片 | 「图片裁剪」 | 属正常反馈，按提示继续操作 |
| 设置处理参数 | 「已应用智能推荐参数」 | 属正常反馈，按提示继续操作 |
| 设置处理参数 | 「处理参数」 | 属正常反馈，按提示继续操作 |
| 预览处理结果 | 「图片处理完成」 | 属正常反馈，按提示继续操作 |
| 预览处理结果 | 「图片处理失败」 | 稍后重试，仍失败请联系管理员 |

> 本章生成日期：2026-08-24，内容基于系统当前版本界面与提示语整理。
