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 使用同一张表和同一次序规则。

内部结构

PublicVersionController
├── currentVersion()
│   └── 应用版本配置
└── latestVersion()
    └── SoftwareVersionService.latestSoftwareVersion()
        └── SoftwareVersionMapper → web_config

类型映射

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

迁移/实现注意事项

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

2.7 KiB Raw Blame History