78 lines
3.0 KiB
Markdown
78 lines
3.0 KiB
Markdown
# 07 记录与版本中心
|
||
|
||
## 模块职责
|
||
|
||
覆盖历史生成记录、客户端软件版本和数字人版本。该模块必须区分“后台管理版本页面”和“客户端公开更新接口”，前者可重构，后者必须保持兼容。
|
||
|
||
覆盖页面：
|
||
|
||
- 历史记录：`history`
|
||
- 软件版本：`version`
|
||
- 数字人版本：`digital-human-version`
|
||
|
||
## 依赖关系
|
||
|
||
上游：菜单树、当前用户、分页/下载适配器。
|
||
|
||
后端：
|
||
|
||
- Java `ImageHistoryController`。
|
||
- Java `SoftwareVersionAdminController`、`SoftwareVersionService`。
|
||
- 数字人版本控制器和 `digitalhuman` 模块。
|
||
|
||
公开版本接口的详细契约见 `09-public-version-compatibility.md`。
|
||
|
||
## 核心接口：原实现 → 目标实现
|
||
|
||
| 功能 | 原实现 | 目标实现 |
|
||
|---|---|---|
|
||
| 历史记录 | `admin.js:loadHistory` + `panel-history` | `HistoryPage.vue` + 原 `/api/admin/history` |
|
||
| 软件版本列表 | `admin.js:loadSoftwareVersions` + `/api/admin/versions` | `SoftwareVersionsPage.vue` |
|
||
| 软件版本上传 | `admin.js` 上传 modal + `/api/admin/version` | Element Plus Upload/Dialog + 原接口 |
|
||
| 数字人版本列表 | `admin.js:loadDigitalHumanVersions` | `DigitalHumanVersionsPage.vue` |
|
||
| 数字人版本上传/发布 | 旧版本 modal 和按钮 | 页面局部表单，保持原数字人版本 API |
|
||
| 客户端检查更新 | Flask `/api/version`、`/api/version/latest` | Java `PublicVersionController`，URL/字段完全不变 |
|
||
|
||
## 内部结构
|
||
|
||
```text
|
||
RecordsCenter
|
||
├── HistoryPage
|
||
│ ├── HistoryFilterBar
|
||
│ ├── HistoryTable
|
||
│ └── ResultPreviewDrawer
|
||
├── SoftwareVersionsPage
|
||
│ ├── VersionTable
|
||
│ └── SoftwareVersionUploadDialog
|
||
└── DigitalHumanVersionsPage
|
||
├── VersionTable
|
||
├── UploadDialog
|
||
└── Release/Latest actions
|
||
```
|
||
|
||
## 类型映射
|
||
|
||
| 原字段 | 目标类型 |
|
||
|---|---|
|
||
| `type` | `HistoryRecordType` |
|
||
| `result_preview` | `PreviewDescriptor`，限制长度和字段 |
|
||
| `version` | `VersionString` |
|
||
| `file_url` | `PublicDownloadUrl` |
|
||
| `created_at` | `DisplayDateTime`，后端格式化或前端统一解析 |
|
||
| 数字人状态 | `DigitalHumanVersionStatus` |
|
||
|
||
公开接口映射：
|
||
|
||
- `/api/version`：`version`、`desc`、`url`。
|
||
- `/api/version/latest`：`version`、`file_url`。
|
||
- 不把 `/api/admin/version` 的上传响应当成客户端公开版本响应。
|
||
|
||
## 迁移/实现注意事项
|
||
|
||
1. 软件版本管理页面调用 `/api/admin/versions` 和 `/api/admin/version`，客户端更新调用 `/api/version/latest`；二者不可混用。
|
||
2. 最新版本判断沿用 `web_config.created_at DESC`，若同一时间并列，使用 id 倒序作为稳定次序。
|
||
3. 上传成功后页面刷新列表，但不得改变公开接口的空值语义。
|
||
4. 版本下载链接是公开客户端资源，页面展示时需要处理超长 URL，不把 URL 写入不必要的日志。
|
||
5. 数字人版本与客户端软件版本是不同业务表和 API，不得合并 DTO。
|
||
6. 历史记录预览要限制内容大小，避免大 JSON 直接阻塞页面。
|