# 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 不需要修改。