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

58 KiB
Raw Blame History

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 中的接口、类型、迁移注意事项和验收标准均有测试或真实验证记录。
  • 不留下旧后台的无效引用,不改变未授权的客户端版本接口契约。