Files

T

huangzd1997 8803e22f39 feat(version): 桌面端更新面板支持指定版本安装

- 新增公开接口 GET /api/version/list（最近 50 条，字段口径同管理端列表），
  桌面端下拉不再拼 OSS 地址（版本包被删后拼地址会 404）
- 更新面板（登录页 + 首页）加「指定版本更新」选择器：默认选中最新版，
  可选全部已发布版本（含回退），回退/同版给出明确文案与二次确认
- 客户端无需发版：do_update_app(file_url) 本就接受任意版本包直链

2026-09-14 11:05:30 +08:00

3.8 KiB

Raw Blame History

09 客户端公开版本接口兼容

模块职责

把 Flask 版本蓝图中的公开客户端版本查询能力迁移到 Java，确保已发布客户端无需升级即可继续检查更新和下载新版本。

本模块只覆盖公开版本查询，不覆盖后台软件版本管理页面；后台页面见 07-records-and-version.md。

依赖关系

原实现：

backend/blueprints/version.py:api_version
backend/blueprints/version.py:api_version_latest
backend/utils/db.py 中 web_config 表初始化/访问

目标实现：

backend-java/.../softwareversion/controller/PublicVersionController.java:currentVersion
backend-java/.../softwareversion/controller/PublicVersionController.java:latestVersion
backend-java/.../softwareversion/service/SoftwareVersionService.java:latestSoftwareVersion
SoftwareVersionMapper、SoftwareVersionEntity

核心接口：原实现 → 目标实现

GET `/api/version`

原响应：

version：当前服务版本，默认值与旧服务一致。
desc：当前为空字符串。
url：旧环境配置的更新 URL，当前保持空字符串/配置值语义。

目标：Java 直接提供同路径和同字段，不包装成通用 ApiResponse，避免改变客户端解析。

GET `/api/version/latest`

原逻辑：

从 web_config 读取 version、file_url。
按 created_at DESC 取第一条。
无记录返回 version=null,file_url=null。

目标逻辑：Java SoftwareVersionService.latestSoftwareVersion 使用同一张表和同一次序规则。

GET `/api/version/list`（2026-09-14 新增，非旧接口）

桌面端更新面板「指定版本更新」下拉的数据源：该功能允许用户显式安装某个历史版本（含回退），列表由服务端给全，前端不拼 OSS 地址（拼地址在版本被删除后会 404）。

匿名可达（与 /latest 同族，未登录也能用；登录页更新面板即匿名态）。
按 created_at DESC, id DESC 返回最近 PublicVersionLookup.DEFAULT_LIST_LIMIT（50）条，上限 MAX_LIST_LIMIT（200）；不作为则沿用旧 version/file_url 字段名。
响应 {"items":[{"id","version","file_url","created_at"}]}，字段口径与管理端 /api/admin/versions 一致（同一套前端解析）；空表返回 {"items":[]}。
同一版本的重复上传记录由前端按版本号去重（保留最新一条），后端不做折叠。

内部结构

PublicVersionController
├── currentVersion()
│   └── 应用版本配置
├── latestVersion()
│   └── SoftwareVersionService.latestSoftwareVersion()
│       └── SoftwareVersionMapper → web_config
└── listVersions()
    └── SoftwareVersionService.listPublicSoftwareVersions()
        └── SoftwareVersionMapper → web_config（LIMIT，字段口径同管理端列表）

类型映射

旧字段	目标字段	约束
`version`	`version`	字符串，不自动转数字
`desc`	`desc`	保留字段，即使为空
`url`	`url`	保留字段，即使为空
`file_url`	`file_url`	不改名为 `download_url`
空记录	`null`	不改成空对象或 `success=false`

迁移/实现注意事项

Flask 停止前必须完成 Java 接口真实 HTTP 验证。
不要将公开接口放到 /api/admin/version；客户端接口和后台上传接口职责不同。
Java 服务启动失败或数据库不可用时，要记录明确错误；不要返回伪造的最新版本。
版本记录写入仍由后台版本管理 API 完成，公开查询只读。
上线验收至少使用一个有版本记录和一个空表/无记录夹具对比旧服务响应。
必须验证旧客户端的请求地址、字段读取和下载 URL 不需要修改。

3.8 KiB Raw Blame History Unescape Escape