Files
crawler-plugin/docs/plans/admin-front-vue/09-public-version-compatibility.md
T
huangzd1997 b404fd2572 docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」,
代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红),
跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
2026-10-04 13:51:16 +08:00

767 lines
58 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 09-public-version-compatibility:客户端公开版本接口兼容任务计划
> 对应 Spec:`docs/specs/09-public-version-compatibility.md`。本文件是“客户端公开版本接口兼容”的独立执行计划,任务必须按编号串行完成。
## 模块范围
- 当前实现基线:`backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService`。
- 目标实现边界:Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装。
- 默认验证命令:`cd backend-java; mvn test`;启动 Java 后用 `curl` 对 `/api/version*` 做真实请求。
- 每个任务均需先写测试并确认 RED,再实现到 GREEN;不得用占位实现、纯回显或静态文本替代真实业务。
## 模块依赖
- 本模块任务范围:161-180。
- 前置依赖:任务 160;跨模块依赖必须以总计划中的完成状态为准。
- 页面任务依赖壳层和 Session;Java/数据库任务依赖对应现有模块和真实测试环境;最终验收任务依赖全部前置模块。
## 统一测试与准出规则
每个任务至少包含 8 个测试:3 个正常路径、3 个边界条件、2 个异常/错误处理。涉及 I/O、数据库、文件、Nginx 或外部服务时,除 mock 外至少添加 1 个真实集成/真实请求测试。
## 任务 161:冻结 /api/version 响应契约
**所属模块**:客户端公开版本接口兼容
**依赖**:160
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
把 /api/version 响应契约 固化为可测试契约:定义合法输入、默认值、边界、错误语义和兼容约束;契约必须能被 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 直接消费,并明确禁止的旧行为。
### 测试用例(必须先写,确认 RED)
1. `test_task_161_freeze_public_version_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_161_freeze_public_version_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_161_freeze_public_version_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_161_freeze_public_version_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_161_freeze_public_version_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_161_freeze_public_version_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_161_freeze_public_version_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_161_freeze_public_version_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task161Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 162:冻结 /api/version/latest 响应契约
**所属模块**:客户端公开版本接口兼容
**依赖**:161
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
把 /api/version/latest 响应契约 固化为可测试契约:定义合法输入、默认值、边界、错误语义和兼容约束;契约必须能被 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 直接消费,并明确禁止的旧行为。
### 测试用例(必须先写,确认 RED)
1. `test_task_162_freeze_public_version_latest_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_162_freeze_public_version_latest_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_162_freeze_public_version_latest_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_162_freeze_public_version_latest_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_162_freeze_public_version_latest_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_162_freeze_public_version_latest_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_162_freeze_public_version_latest_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_162_freeze_public_version_latest_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task162Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 163:定义 web_config 最新记录排序规则
**所属模块**:客户端公开版本接口兼容
**依赖**:162
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
为“定义 web_config 最新记录排序规则”建立明确的数据/组件/接口边界,至少写清字段来源、类型、空值、排序、失败语义和调用方;设计必须落在 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 范围内,不能用无类型大对象掩盖边界。
### 测试用例(必须先写,确认 RED)
1. `test_task_163_define_web_config_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_163_define_web_config_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_163_define_web_config_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_163_define_web_config_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_163_define_web_config_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_163_define_web_config_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_163_define_web_config_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_163_define_web_config_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task163Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 164:实现 Java 当前版本配置读取
**所属模块**:客户端公开版本接口兼容
**依赖**:163
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
实现“实现 Java 当前版本配置读取”:以 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 为落点,明确输入、输出、状态转换、边界和错误反馈;保留 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 中仍被批准的业务语义,禁止 stub、纯回显和硬编码结果。
### 测试用例(必须先写,确认 RED)
1. `test_task_164_implement_java_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_164_implement_java_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_164_implement_java_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_164_implement_java_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_164_implement_java_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_164_implement_java_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_164_implement_java_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_164_implement_java_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task164Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 165:实现 Java 最新版本查询服务
**所属模块**:客户端公开版本接口兼容
**依赖**:164
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
实现“实现 Java 最新版本查询服务”:以 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 为落点,明确输入、输出、状态转换、边界和错误反馈;保留 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 中仍被批准的业务语义,禁止 stub、纯回显和硬编码结果。
### 测试用例(必须先写,确认 RED)
1. `test_task_165_implement_java_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_165_implement_java_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_165_implement_java_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_165_implement_java_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_165_implement_java_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_165_implement_java_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_165_implement_java_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_165_implement_java_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task165Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 166:实现空版本表 null 语义
**所属模块**:客户端公开版本接口兼容
**依赖**:165
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
实现“实现空版本表 null 语义”:以 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 为落点,明确输入、输出、状态转换、边界和错误反馈;保留 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 中仍被批准的业务语义,禁止 stub、纯回显和硬编码结果。
### 测试用例(必须先写,确认 RED)
1. `test_task_166_implement_null_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_166_implement_null_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_166_implement_null_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_166_implement_null_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_166_implement_null_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_166_implement_null_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_166_implement_null_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_166_implement_null_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task166Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 167:实现版本字段空字符串语义
**所属模块**:客户端公开版本接口兼容
**依赖**:166
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
实现“实现版本字段空字符串语义”:以 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 为落点,明确输入、输出、状态转换、边界和错误反馈;保留 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 中仍被批准的业务语义,禁止 stub、纯回显和硬编码结果。
### 测试用例(必须先写,确认 RED)
1. `test_task_167_implement_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_167_implement_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_167_implement_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_167_implement_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_167_implement_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_167_implement_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_167_implement_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_167_implement_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task167Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 168:实现公开接口不使用 ApiResponse 包装
**所属模块**:客户端公开版本接口兼容
**依赖**:167
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
实现“实现公开接口不使用 ApiResponse 包装”:以 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 为落点,明确输入、输出、状态转换、边界和错误反馈;保留 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 中仍被批准的业务语义,禁止 stub、纯回显和硬编码结果。
### 测试用例(必须先写,确认 RED)
1. `test_task_168_implement_apiresponse_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_168_implement_apiresponse_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_168_implement_apiresponse_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_168_implement_apiresponse_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_168_implement_apiresponse_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_168_implement_apiresponse_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_168_implement_apiresponse_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_168_implement_apiresponse_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task168Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 169:实现版本接口数据库错误处理
**所属模块**:客户端公开版本接口兼容
**依赖**:168
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
实现“实现版本接口数据库错误处理”:以 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 为落点,明确输入、输出、状态转换、边界和错误反馈;保留 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 中仍被批准的业务语义,禁止 stub、纯回显和硬编码结果。
### 测试用例(必须先写,确认 RED)
1. `test_task_169_implement_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_169_implement_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_169_implement_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_169_implement_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_169_implement_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_169_implement_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_169_implement_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_169_implement_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task169Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 170:验证多版本记录取最新
**所属模块**:客户端公开版本接口兼容
**依赖**:169
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
对“验证多版本记录取最新”做前后端或迁移前后对比验证,覆盖至少两种有效输入、空/边界输入和依赖异常;验收结果必须能够追溯到 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 与 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 的契约。
### 测试用例(必须先写,确认 RED)
1. `test_task_170_verify_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_170_verify_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_170_verify_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_170_verify_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_170_verify_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_170_verify_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_170_verify_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_170_verify_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task170Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 171:验证同时间记录按 id 稳定排序
**所属模块**:客户端公开版本接口兼容
**依赖**:170
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
对“验证同时间记录按 id 稳定排序”做前后端或迁移前后对比验证,覆盖至少两种有效输入、空/边界输入和依赖异常;验收结果必须能够追溯到 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 与 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 的契约。
### 测试用例(必须先写,确认 RED)
1. `test_task_171_verify_id_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_171_verify_id_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_171_verify_id_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_171_verify_id_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_171_verify_id_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_171_verify_id_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_171_verify_id_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_171_verify_id_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task171Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 172:验证 file_url 原样返回
**所属模块**:客户端公开版本接口兼容
**依赖**:171
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
对“验证 file_url 原样返回”做前后端或迁移前后对比验证,覆盖至少两种有效输入、空/边界输入和依赖异常;验收结果必须能够追溯到 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 与 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 的契约。
### 测试用例(必须先写,确认 RED)
1. `test_task_172_verify_file_url_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_172_verify_file_url_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_172_verify_file_url_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_172_verify_file_url_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_172_verify_file_url_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_172_verify_file_url_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_172_verify_file_url_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_172_verify_file_url_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task172Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 173:验证 desc/url 字段保留
**所属模块**:客户端公开版本接口兼容
**依赖**:172
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
对“验证 desc/url 字段保留”做前后端或迁移前后对比验证,覆盖至少两种有效输入、空/边界输入和依赖异常;验收结果必须能够追溯到 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 与 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 的契约。
### 测试用例(必须先写,确认 RED)
1. `test_task_173_verify_desc_url_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_173_verify_desc_url_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_173_verify_desc_url_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_173_verify_desc_url_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_173_verify_desc_url_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_173_verify_desc_url_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_173_verify_desc_url_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_173_verify_desc_url_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task173Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 174:验证旧客户端请求路径不变
**所属模块**:客户端公开版本接口兼容
**依赖**:173
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
对“验证旧客户端请求路径不变”做前后端或迁移前后对比验证,覆盖至少两种有效输入、空/边界输入和依赖异常;验收结果必须能够追溯到 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 与 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 的契约。
### 测试用例(必须先写,确认 RED)
1. `test_task_174_verify_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_174_verify_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_174_verify_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_174_verify_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_174_verify_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_174_verify_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_174_verify_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_174_verify_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task174Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 175:验证公开接口与后台上传解耦
**所属模块**:客户端公开版本接口兼容
**依赖**:174
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
对“验证公开接口与后台上传解耦”做前后端或迁移前后对比验证,覆盖至少两种有效输入、空/边界输入和依赖异常;验收结果必须能够追溯到 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 与 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 的契约。
### 测试用例(必须先写,确认 RED)
1. `test_task_175_verify_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_175_verify_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_175_verify_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_175_verify_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_175_verify_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_175_verify_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_175_verify_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_175_verify_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task175Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 176:验证 Java 接口替代 Flask 后响应一致
**所属模块**:客户端公开版本接口兼容
**依赖**:175
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
对“验证 Java 接口替代 Flask 后响应一致”做前后端或迁移前后对比验证,覆盖至少两种有效输入、空/边界输入和依赖异常;验收结果必须能够追溯到 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 与 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 的契约。
### 测试用例(必须先写,确认 RED)
1. `test_task_176_verify_java__flask_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_176_verify_java__flask_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_176_verify_java__flask_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_176_verify_java__flask_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_176_verify_java__flask_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_176_verify_java__flask_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_176_verify_java__flask_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_176_verify_java__flask_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task176Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 177:补充版本接口控制器测试
**所属模块**:客户端公开版本接口兼容
**依赖**:176
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
实现“补充版本接口控制器测试”:以 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 为落点,明确输入、输出、状态转换、边界和错误反馈;保留 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 中仍被批准的业务语义,禁止 stub、纯回显和硬编码结果。
### 测试用例(必须先写,确认 RED)
1. `test_task_177_feature_point_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_177_feature_point_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_177_feature_point_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_177_feature_point_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_177_feature_point_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_177_feature_point_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_177_feature_point_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_177_feature_point_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task177Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 178:补充版本接口数据库集成测试
**所属模块**:客户端公开版本接口兼容
**依赖**:177
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
实现“补充版本接口数据库集成测试”:以 Java `PublicVersionController` 和 `latestSoftwareVersion`,保持无 ApiResponse 包装 为落点,明确输入、输出、状态转换、边界和错误反馈;保留 `backend/blueprints/version.py:api_version/api_version_latest`、`web_config`、Java `SoftwareVersionService` 中仍被批准的业务语义,禁止 stub、纯回显和硬编码结果。
### 测试用例(必须先写,确认 RED)
1. `test_task_178_feature_point_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_178_feature_point_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_178_feature_point_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_178_feature_point_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_178_feature_point_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_178_feature_point_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_178_feature_point_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_178_feature_point_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task178Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 179:完成真实客户端更新链路 smoke
**所属模块**:客户端公开版本接口兼容
**依赖**:178
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
完成“完成真实客户端更新链路 smoke”的端到端收口:串联本模块真实入口、核心业务调用、错误处理和资源清理,确认输出不是输入纯回显且不产生遗留计时器、请求或敏感日志。
### 测试用例(必须先写,确认 RED)
1. `test_task_179_completereal_smoke_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_179_completereal_smoke_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_179_completereal_smoke_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_179_completereal_smoke_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_179_completereal_smoke_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_179_completereal_smoke_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_179_completereal_smoke_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_179_completereal_smoke_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task179Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 任务 180:完成 Flask 版本蓝图删除前置验收
**所属模块**:客户端公开版本接口兼容
**依赖**:179
**预估耗时**:8-15 分钟(写测试 + 实现 + 自测)
### 功能点要求
完成“完成 Flask 版本蓝图删除前置验收”的端到端收口:串联本模块真实入口、核心业务调用、错误处理和资源清理,确认输出不是输入纯回显且不产生遗留计时器、请求或敏感日志。
### 测试用例(必须先写,确认 RED)
1. `test_task_180_complete_flask_remove_normal_primary_path` — 正常主路径:使用最小有效输入,验证功能输出符合目标契约。
2. `test_task_180_complete_flask_remove_normal_variant_input` — 正常变体:使用第二种有效输入或另一种业务分支,验证不是只支持单一样例。
3. `test_task_180_complete_flask_remove_normal_repeated_operation_is_idempotent` — 正常重复:重复相同操作,验证不会重复提交、重复渲染或污染已有状态。
4. `test_task_180_complete_flask_remove_boundary_empty_input` — 边界空值:空列表、空字符串或缺省请求按模块语义处理,不崩溃。
5. `test_task_180_complete_flask_remove_boundary_single_item` — 边界单元素:单条记录/单节点/单次请求的结果和排序正确。
6. `test_task_180_complete_flask_remove_boundary_limit_or_missing_field` — 边界上限:最大页/长度/超时/缺字段输入得到明确、可控的结果。
7. `test_task_180_complete_flask_remove_invalid_input_rejected` — 异常输入:非法类型、非法状态或越权输入被拒绝,并使用预期错误类型。
8. `test_task_180_complete_flask_remove_dependency_failure_returns_actionable_message` — 依赖失败:HTTP、数据库、文件或浏览器依赖不可用时释放资源并返回可操作错误信息。
### TDD 流程
1. 先写以上全部测试,运行对应命令确认 **RED(目标行为尚未实现时应失败)**;若测试一开始通过,先检查测试是否真正断言了目标行为。
2. 实现本任务功能,重新运行同一测试集确认 **GREEN(全部通过)**。
3. 运行类型检查、lint、format、相关集成测试和真实调用;修复所有失败后才能提交。
### 验证方法
在 `backend-java` 执行 `mvn -q -Dtest=Task180Test test` 或对应测试类,再执行 `mvn -q -DskipTests compile`;必须比较 Flask 基线响应与 Java 响应;数据库空表、多版本和错误路径都要真实验证。
### 准出标准
- 测试、类型检查和格式检查通过;错误路径有明确消息,资源得到释放。
- 真实调用证明结果来自实际业务逻辑,不是硬编码模板或输入原样回显。
- 只修改本任务允许的文件范围,完成后提交包含任务编号的 git commit。
## 模块完成条件
- 任务 161-180 全部按 TDD 流程完成并有对应 commit。
- 关联 Spec 中的接口、类型、迁移注意事项和验收标准均有测试或真实验证记录。
- 不留下旧后台的无效引用,不改变未授权的客户端版本接口契约。