huangzd1997
8803e22f39
- 新增公开接口 GET /api/version/list（最近 50 条，字段口径同管理端列表）， 桌面端下拉不再拼 OSS 地址（版本包被删后拼地址会 404） - 更新面板（登录页 + 首页）加「指定版本更新」选择器：默认选中最新版， 可选全部已发布版本（含回退），回退/同版给出明确文案与二次确认 - 客户端无需发版：do_update_app(file_url) 本就接受任意版本包直链
90 lines
3.8 KiB
Markdown
90 lines
3.8 KiB
Markdown
# 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":[]}`。
|
||
- 同一版本的重复上传记录由前端按版本号去重（保留最新一条），后端不做折叠。
|
||
|
||
## 内部结构
|
||
|
||
```text
|
||
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` |
|
||
|
||
## 迁移/实现注意事项
|
||
|
||
1. Flask 停止前必须完成 Java 接口真实 HTTP 验证。
|
||
2. 不要将公开接口放到 `/api/admin/version`；客户端接口和后台上传接口职责不同。
|
||
3. Java 服务启动失败或数据库不可用时，要记录明确错误；不要返回伪造的最新版本。
|
||
4. 版本记录写入仍由后台版本管理 API 完成，公开查询只读。
|
||
5. 上线验收至少使用一个有版本记录和一个空表/无记录夹具对比旧服务响应。
|
||
6. 必须验证旧客户端的请求地址、字段读取和下载 URL 不需要修改。
|