# 5.2.XX管理模块设计说明

## 5.2.1.XX设计说明。

### 5.2.1.1.模块描述。

本模块用于“模型转换结果文件管理”，包含两项核心能力：

1. 模型转换输出文件下载（支持下载地址选择）。
2. 批量重命名。

职责边界说明：

1. **模型转换**由对应 CAD 插件在 CAD 内部执行（Creo/Revit/PDMS 插件链路）。
2. **下载与重命名**由文件管理服务执行（前端通过 WebSocket 请求，下载通过 HTTP 拉取文件流）。

### ·5.2.1.2.功能·。

1. 支持单文件下载：
   - 前端发送 `download_file` + `file_path`。
   - 服务端返回 `download_url` 后，前端通过浏览器打开下载地址。
2. 支持批量下载：
   - 前端发送 `download_batch` + `file_paths[]`。
   - 服务端返回批量下载地址，前端以 `POST` 拉取 ZIP 并触发下载。
3. 支持下载地址选择（文件来源路径选择）：
   - 在“文件扫描配置”中设置 `Base Path`（`set_base_path`）。
   - 下载列表基于当前 `base_path` 扫描结果生成，等价于选择下载资源地址范围。
4. 支持批量重命名：
   - 策略获取：`get_rename_strategies`。
   - 重命名预览：`preview_rename`。
   - 执行重命名：`rename_files`。
5. 支持多重命名策略：
   - `add_prefix`、`add_suffix`、`sequence`、`replace_text`、`add_datetime`、`change_case`。

### 5.2.1.3.性能。

1. 下载流程采用“先取 URL 再 HTTP 下载”，避免 WebSocket 直接承载大文件传输。
2. 批量下载统一打包传输（ZIP），降低多文件重复连接成本。
3. 重命名预览采用防抖触发（500ms），减少高频参数变化导致的请求风暴。
4. 列表与配置基于增量消息回推，前端仅更新必要状态字段，界面响应稳定。

### 5.2.1.4.输入输出项·。

#### 1.字段输入输出。

下载输入字段：

1. `file_path`（单文件相对路径）
2. `file_paths[]`（批量文件相对路径数组）
3. `base_path`（扫描根目录）

下载输出字段：

1. `download_url`
2. `method`（单文件 GET / 批量 POST）
3. `file_paths`（批量下载确认路径）

重命名输入字段：

1. `strategy`
2. `params`（按策略变化）
3. `file_paths[]`

重命名输出字段：

1. `preview[]`（预览结果）
2. `success_count`
3. `failed_count`
4. `results[]`（原名/新名/状态）

#### 2.界面交互输入输出。

输入交互：

1. 点击“下载”按钮触发单文件下载。
2. 多选后点击“批量下载”。
3. 打开配置弹窗修改 `Base Path` 进行下载地址范围选择。
4. 打开重命名弹窗，选择策略并配置参数。

输出交互：

1. 浏览器下载行为（新窗口/保存流）。
2. 配置变更后文件列表刷新并更新当前路径展示。
3. 重命名预览列表实时更新。
4. 重命名完成提示（成功/失败数量）并刷新列表。

### 5.2.1.5.算法

下载算法：

1. 用户选择文件（单个或多个）。
2. 通过 WebSocket 发送下载请求消息。
3. 接收 `download_url`。
4. 若 `method=POST`，执行 `fetch(url,{method:'POST',body:file_paths})` 获取 ZIP。
5. 若非 POST，直接拼接 HTTP 地址执行打开下载。

下载地址选择算法：

1. 用户在配置区输入 `base_path`。
2. 前端发送 `set_base_path`。
3. 服务端返回新配置并重新扫描目录。
4. 前端更新列表；后续下载基于该路径下文件。

批量重命名算法：

1. 选择文件集合 `file_paths[]`。
2. 请求策略列表并选择 `strategy`。
3. 参数变化触发防抖预览 `preview_rename`。
4. 用户确认后调用 `rename_files`。
5. 根据返回 `results` 统计并刷新文件列表。

### 5.2.1.6.流程逻辑

1. 转换完成文件进入文件管理域（由服务端扫描）。
2. 用户可先通过 `Base Path` 设定下载资源目录。
3. 执行单文件/批量下载，获取并使用下载地址。
4. 如需规范文件命名，进入批量重命名流程。
5. 预览确认后执行重命名并回写结果。

### ·5.2.1.7.接口。

WebSocket 文件管理接口：

1. `get_file_list`
2. `download_file`
3. `download_batch`
4. `get_rename_strategies`
5. `preview_rename`
6. `rename_files`
7. `set_base_path`
8. `set_file_extensions`
9. `get_file_config`

前端服务封装接口：

1. `websocketService.downloadFile(filePath)`
2. `websocketService.downloadBatch(filePaths)`
3. `websocketService.previewRename(filePaths, strategy, params)`
4. `websocketService.renameFiles(filePaths, strategy, params)`
5. `websocketService.setBasePath(path)`

下载执行接口：

1. 单文件：`GET {HTTP_BASE_URL}{download_url}`
2. 批量文件：`POST {HTTP_BASE_URL}{download_url}`（Body=`file_paths[]`）

### 5.2.1.8.注释设计

建议注释要点：

1. 明确“WebSocket 仅负责控制消息，HTTP 承担文件下载流”。
2. 注明 `Base Path` 是文件来源目录选择，不是浏览器本地保存目录选择。
3. 注明重命名采用“先预览后执行”防误操作机制。
4. 注明批量下载默认归档文件名（如 `cad_files.zip`）可扩展配置化。

### 5.2.1.9.数据结构。

单文件下载请求：

```
{
  "type": "download_file",
  "file_path": "creo/part1.prt.1"
}
```

批量下载请求：

```
{
  "type": "download_batch",
  "file_paths": ["creo/a.prt.1", "revit/b.rvt"]
}
```

重命名预览请求：

```
{
  "type": "preview_rename",
  "file_paths": ["creo/part1.prt.1"],
  "strategy": "add_prefix",
  "params": { "prefix": "NEW_" }
}
```

重命名执行请求：

```
{
  "type": "rename_files",
  "file_paths": ["creo/part1.prt.1", "creo/assembly.asm"],
  "strategy": "sequence",
  "params": { "base_name": "component", "start_number": 1, "digits": 3, "separator": "_" }
}
```

关键状态结构：

1. `selectedFiles: string[]`
2. `currentPath/configBasePath: string`
3. `selectedStrategy: string`
4. `renameParams: object`
5. `previewList: { original, new, success }[]`
