docs: 补充规格文档（specs 01-15）

2026-09-08 13:39:10 +08:00
parent 4ac8f8b472
commit b12acf7793
16 changed files with 1462 additions and 0 deletions
@@ -0,0 +1,74 @@
+# 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` 使用同一张表和同一次序规则。
+
+## 内部结构
+
+```text
+PublicVersionController
+├── currentVersion()
+│   └── 应用版本配置
+└── latestVersion()
+    └── SoftwareVersionService.latestSoftwareVersion()
+        └── SoftwareVersionMapper → web_config
+```
+
+## 类型映射
+
+| 旧字段 | 目标字段 | 约束 |
+|---|---|---|
+| `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 不需要修改。