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

11 KiB
Raw Blame History

13-plan — 契约测试与模块边界治理

对应 docs/specs/13-contract-tests-and-boundaries.md。契约测试与代码同 PR 提交;CI 追加测试阶段。 技术栈:Java 21 + JUnit5 + ArchUnit + Vitest(前端)。

任务 202:Python-contract 夹具准备

所属模块:13 契约 依赖:无 预估:8-15 分钟

功能点要求

录制 app_client/amazon 实际调用(/result、/items、parsed-payload、heartbeat)的真实请求报文,脱敏后入测试资源(JSON 夹具);夹具文件结构明确。

测试用例(≥8)

  1. test_fixture_result_exists — result 夹具
  2. test_fixture_items_exists — items 夹具
  3. test_fixture_parsed_payload — parsed-payload 夹具
  4. test_fixture_heartbeat — heartbeat 夹具
  5. test_fixture_sanitized — 脱敏(无真实凭据)
  6. test_fixture_shape_valid — 结构有效
  7. test_fixture_fields_documented — 字段说明
  8. test_fixture_reproducible — 可复录

任务 203:/result 幂等契约测试

所属模块:13 契约 依赖:202 预估:8-15 分钟

功能点要求

同 submissionId 重复提交 /result:HTTP 200 + success=true;只落一次;chunkIndex/chunkTotal 语义;done=true 封口。

测试用例(≥8)

  1. test_result_success_contract — 200+true
  2. test_result_duplicate_idempotent — 幂等
  3. test_result_single_persist — 单次落库
  4. test_result_chunk_fields — 分片字段
  5. test_result_done_contract — 封口
  6. test_result_error_contract — 失败语义
  7. test_result_unknown_task — 未知任务
  8. test_result_fixture_replay — 夹具回放

任务 204:/items 分页语义契约测试

所属模块:13 契约 依赖:202 预估:8-15 分钟

功能点要求

collectdata/publish 的 items 接口:分页参数(page/pageSize)、排序、字段结构、缺省行为与 Python Worker 拉取约定一致。

测试用例(≥8)

  1. test_items_pagination — 分页
  2. test_items_defaults — 默认值
  3. test_items_field_shape — 字段结构
  4. test_items_page_bounds — 越界处理
  5. test_items_order — 排序
  6. test_items_empty — 空页
  7. test_items_worker_order — Worker 顺序
  8. test_items_fixture_replay

任务 205:parsed-payload 契约测试

所属模块:13 契约 依赖:202 预估:8-15 分钟

功能点要求

similarasin/appearancepatent 的 parsed-payload:字段结构、分页语义、submissionId 关联与 Python 读取约定一致。

测试用例(≥8)

  1. test_parsed_payload_shape
  2. test_parsed_payload_pagination
  3. test_parsed_payload_submission
  4. test_parsed_payload_empty
  5. test_parsed_payload_unknown_task
  6. test_parsed_payload_fixture_replay
  7. test_parsed_payload_status
  8. test_parsed_payload_frozen

任务 206:heartbeat 旧字段契约测试

所属模块:13 契约 依赖:202 预估:8-15 分钟

功能点要求

heartbeat 接口:路径、请求/响应字段与 Python Worker 约定一致;缺字段/多余字段处理。

测试用例(≥8)

  1. test_heartbeat_path
  2. test_heartbeat_fields
  3. test_heartbeat_unknown_task
  4. test_heartbeat_missing_optional
  5. test_heartbeat_extra_field_tolerant — 多余字段容忍
  6. test_heartbeat_fixture_replay
  7. test_heartbeat_success
  8. test_heartbeat_frozen

任务 207:done=true 最后一批契约测试

所属模块:13 契约 依赖:203 预估:8-15 分钟

功能点要求

done=true 最后一批:强制处理剩余数据、生成结果文件、任务终态;协议与 Python 端一致。

测试用例(≥8)

  1. test_done_force_process
  2. test_done_finalize_task
  3. test_done_generate_file
  4. test_done_after_partial_chunks
  5. test_done_no_pending — 无剩余
  6. test_done_repeat
  7. test_done_fixture_replay
  8. test_done_frozen

任务 208:JavaApiResponse 包装契约测试(前端)

所属模块:13 契约 依赖:无 预估:8-15 分钟

功能点要求

前端契约:JavaApiResponse 结构(success/message/data);LegacyApiSuccess(msg)兼容;解包行为(复用 01 callJava 测试)固化。

测试用例(≥8)

  1. test_java_response_success_shape
  2. test_java_response_failure_shape
  3. test_legacy_success_shape
  4. test_unwrap_success
  5. test_unwrap_failure_throws
  6. test_null_data_shape
  7. test_extra_fields_tolerant
  8. test_snapshot_frozen

任务 209:字段兼容 schema 覆盖

所属模块:13 契约 依赖:208 预估:8-15 分钟

功能点要求

核心字段 schema:user_id/task_ids(请求)、taskId/resultId/fileKey/status/taskStatus/fileStatus(响应);api-field-compat 检查接入。

测试用例(≥8)

  1. test_request_user_id_schema
  2. test_request_task_ids_schema
  3. test_response_task_id_schema
  4. test_response_result_id_schema
  5. test_response_file_key_schema
  6. test_response_status_schema
  7. test_compat_checker_integrated
  8. test_schema_frozen

任务 210:ArchUnit 依赖方向规则

所属模块:13 契约 依赖:无 预估:8-15 分钟

功能点要求

ArchUnit 规则:Controller→Service→Mapper 单向;Controller 不依赖外部 Client 细节;task 模块规则见 212;规则测试可运行。

测试用例(≥8)

  1. test_controller_depends_service — 允许方向
  2. test_service_depends_mapper — 允许
  3. test_controller_to_mapper_forbidden — 禁止
  4. test_no_cycle — 无环
  5. test_rule_scope_modules — 作用域
  6. test_rule_verbose — 失败信息
  7. test_all_controllers_covered — 覆盖
  8. test_rule_stable — 稳定

任务 211:ArchUnit Controller 不访问 Mapper

所属模块:13 契约 依赖:210 预估:8-15 分钟

功能点要求

强化规则:任何 Controller 不得注入/调用 Mapper;违例失败。

测试用例(≥8)

  1. test_no_mapper_in_controller
  2. test_violation_detected — 违例检出
  3. test_message_clear
  4. test_controller_service_ok — 允许路径
  5. test_all_controllers_covered
  6. test_no_mapper_field
  7. test_rule_in_ci
  8. test_snapshot_frozen

任务 212:ArchUnit task 模块不依赖业务模块

所属模块:13 契约 依赖:210 预估:8-15 分钟

功能点要求

公共 task 模块不得 import 业务模块(similarasin/appearancepatent/...);04 的 Handler SPI 已反转依赖;规则检查通过。

测试用例(≥8)

  1. test_task_no_business_dep — 无业务依赖
  2. test_spi_interface_allowed — SPI 接口豁免
  3. test_violation_detected
  4. test_message_clear
  5. test_04_registry_ok — 注册表符合
  6. test_all_task_classes_covered
  7. test_rule_in_ci
  8. test_snapshot_frozen

任务 213:前端共享层导出白名单

所属模块:13 契约 依赖:无 预估:8-15 分钟

功能点要求

TS 检查:页面(pages/*)禁止直接 import shared/api/http.ts 或拼 URL;只允许 import java-modules.ts 的 API 函数与 bridges;违例编译失败(lint 规则或类型守卫)。

测试用例(≥8)

  1. test_page_no_http_direct — 页面不直连 http
  2. test_page_no_url_concat — 不拼 URL
  3. test_page_uses_api_module — 用 API 层
  4. test_shared_internal_allowed — shared 内部允许
  5. test_bridge_allowed — bridge 允许
  6. test_violation_detected
  7. test_check_runs_in_ci
  8. test_allowlist_frozen

任务 214:progress/batch 轻量响应契约

所属模块:13 契约 依赖:109 预估:8-15 分钟

功能点要求

progress/batch 契约:items/missingTaskIds 结构;task 轻量字段;file 字段(除 collectdata);前端解析一致。

测试用例(≥8)

  1. test_progress_batch_shape
  2. test_missing_ids_shape
  3. test_task_light_fields
  4. test_file_fields_included
  5. test_collectdata_exception — 例外模块
  6. test_frontend_parse_compat
  7. test_snapshot_frozen
  8. test_light_vs_batch_consistency

任务 215:下载 URL 格式契约

所属模块:13 契约 依赖:147 预估:8-15 分钟

功能点要求

downloadUrl 契约:公开直链格式(https、bucket 包含、result/ 前缀下载域名);无签名;前端 save_file 流程兼容。

测试用例(≥8)

  1. test_download_url_https
  2. test_download_url_bucket
  3. test_result_prefix_endpoint
  4. test_no_signature
  5. test_frontend_save_compat
  6. test_blank_handling
  7. test_contract_frozen
  8. test_download_flow_end2end

任务 216:CI 接入测试阶段

所属模块:13 契约 依赖:210-215 预估:8-15 分钟

功能点要求

.gitea/workflows/build.yml 追加:mvn test(契约+ArchUnit)、前端 vitest、契约快照比对;失败即红。

测试用例(≥8)

  1. test_ci_has_test_stage — 测试阶段
  2. test_ci_java_tests — Java 测试命令
  3. test_ci_frontend_tests — 前端测试
  4. test_ci_snapshot_check
  5. test_ci_fail_fast — 失败即红
  6. test_ci_cache
  7. test_ci_timeout
  8. test_ci_documented

任务 217:快照对比工具

所属模块:13 契约 依赖:90 预估:8-15 分钟

功能点要求

Service 拆分前后响应一致工具:录制(输入→输出)golden;对比(输出 diff);供 05 各模块使用。

测试用例(≥8)

  1. test_tool_records
  2. test_tool_compares_equal
  3. test_tool_diff_detected
  4. test_tool_output_report
  5. test_tool_reusable
  6. test_tool_commits_golden
  7. test_tool_clear_error
  8. test_tool_documented

任务 218:结果文件格式契约

所属模块:13 契约 依赖:无 预估:8-15 分钟

功能点要求

结果文件格式契约:文件名(*-result.xlsx 模式)、Sheet 名称、列顺序、ZIP 结构;与 Python/前端约定一致;改造(04/05)后不变。

测试用例(≥8)

  1. test_filename_pattern
  2. test_sheet_name
  3. test_column_order
  4. test_zip_structure
  5. test_encoding_utf8
  6. test_empty_result_file
  7. test_contract_frozen
  8. test_regression_guard

任务 219:13 全量契约回归

所属模块:13 契约 依赖:202-218 预估:8-15 分钟

功能点要求

全部契约测试(Java + 前端)+ ArchUnit + 白名单检查全绿;契约快照冻结;CI 通过。

测试用例(≥8)

1-8:Java 契约全绿、前端契约全绿、ArchUnit 三规则、白名单、快照比对、CI 模拟、全量单测、package

验证方法

mvn test 全量 + cd frontend-vue && npm run build && npx vitest run + CI 检查。

收尾验证(全部模块——启动性/核心功能/质量 gate)

  1. mvn clean package -DskipTests 产 JAR,java -jar target/aiimage-backend-0.0.1-SNAPSHOT.jar(本地配置)启动,curl 健康检查端点返回预期
  2. 核心页面(/newApi/api/... 抽样)可访问
  3. 核心交互路径:上传→解析→进度→下载最小链路真实调用非空
  4. mvn test 全绿(≥80% 覆盖抽查)
  5. npm run build(vue-tsc + vite)零错误;npx vitest run 全绿
  6. check_progress 脚本返回 all tasks done(exit 0)
  7. git log 验证每个 task 有对应 commit