docs: 补充规格文档（specs 01-15）

2026-09-08 13:39:10 +08:00
parent 4ac8f8b472
commit b12acf7793
16 changed files with 1462 additions and 0 deletions
@@ -0,0 +1,77 @@
+# 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 直接阻塞页面。