crawler-plugin/docs/specs/07-records-and-version.md

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/字段完全不变

内部结构

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