# 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 直接阻塞页面。