`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
11 KiB
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)
- test_fixture_result_exists — result 夹具
- test_fixture_items_exists — items 夹具
- test_fixture_parsed_payload — parsed-payload 夹具
- test_fixture_heartbeat — heartbeat 夹具
- test_fixture_sanitized — 脱敏(无真实凭据)
- test_fixture_shape_valid — 结构有效
- test_fixture_fields_documented — 字段说明
- test_fixture_reproducible — 可复录
任务 203:/result 幂等契约测试
所属模块:13 契约 依赖:202 预估:8-15 分钟
功能点要求
同 submissionId 重复提交 /result:HTTP 200 + success=true;只落一次;chunkIndex/chunkTotal 语义;done=true 封口。
测试用例(≥8)
- test_result_success_contract — 200+true
- test_result_duplicate_idempotent — 幂等
- test_result_single_persist — 单次落库
- test_result_chunk_fields — 分片字段
- test_result_done_contract — 封口
- test_result_error_contract — 失败语义
- test_result_unknown_task — 未知任务
- test_result_fixture_replay — 夹具回放
任务 204:/items 分页语义契约测试
所属模块:13 契约 依赖:202 预估:8-15 分钟
功能点要求
collectdata/publish 的 items 接口:分页参数(page/pageSize)、排序、字段结构、缺省行为与 Python Worker 拉取约定一致。
测试用例(≥8)
- test_items_pagination — 分页
- test_items_defaults — 默认值
- test_items_field_shape — 字段结构
- test_items_page_bounds — 越界处理
- test_items_order — 排序
- test_items_empty — 空页
- test_items_worker_order — Worker 顺序
- test_items_fixture_replay
任务 205:parsed-payload 契约测试
所属模块:13 契约 依赖:202 预估:8-15 分钟
功能点要求
similarasin/appearancepatent 的 parsed-payload:字段结构、分页语义、submissionId 关联与 Python 读取约定一致。
测试用例(≥8)
- test_parsed_payload_shape
- test_parsed_payload_pagination
- test_parsed_payload_submission
- test_parsed_payload_empty
- test_parsed_payload_unknown_task
- test_parsed_payload_fixture_replay
- test_parsed_payload_status
- test_parsed_payload_frozen
任务 206:heartbeat 旧字段契约测试
所属模块:13 契约 依赖:202 预估:8-15 分钟
功能点要求
heartbeat 接口:路径、请求/响应字段与 Python Worker 约定一致;缺字段/多余字段处理。
测试用例(≥8)
- test_heartbeat_path
- test_heartbeat_fields
- test_heartbeat_unknown_task
- test_heartbeat_missing_optional
- test_heartbeat_extra_field_tolerant — 多余字段容忍
- test_heartbeat_fixture_replay
- test_heartbeat_success
- test_heartbeat_frozen
任务 207:done=true 最后一批契约测试
所属模块:13 契约 依赖:203 预估:8-15 分钟
功能点要求
done=true 最后一批:强制处理剩余数据、生成结果文件、任务终态;协议与 Python 端一致。
测试用例(≥8)
- test_done_force_process
- test_done_finalize_task
- test_done_generate_file
- test_done_after_partial_chunks
- test_done_no_pending — 无剩余
- test_done_repeat
- test_done_fixture_replay
- test_done_frozen
任务 208:JavaApiResponse 包装契约测试(前端)
所属模块:13 契约 依赖:无 预估:8-15 分钟
功能点要求
前端契约:JavaApiResponse 结构(success/message/data);LegacyApiSuccess(msg)兼容;解包行为(复用 01 callJava 测试)固化。
测试用例(≥8)
- test_java_response_success_shape
- test_java_response_failure_shape
- test_legacy_success_shape
- test_unwrap_success
- test_unwrap_failure_throws
- test_null_data_shape
- test_extra_fields_tolerant
- test_snapshot_frozen
任务 209:字段兼容 schema 覆盖
所属模块:13 契约 依赖:208 预估:8-15 分钟
功能点要求
核心字段 schema:user_id/task_ids(请求)、taskId/resultId/fileKey/status/taskStatus/fileStatus(响应);api-field-compat 检查接入。
测试用例(≥8)
- test_request_user_id_schema
- test_request_task_ids_schema
- test_response_task_id_schema
- test_response_result_id_schema
- test_response_file_key_schema
- test_response_status_schema
- test_compat_checker_integrated
- test_schema_frozen
任务 210:ArchUnit 依赖方向规则
所属模块:13 契约 依赖:无 预估:8-15 分钟
功能点要求
ArchUnit 规则:Controller→Service→Mapper 单向;Controller 不依赖外部 Client 细节;task 模块规则见 212;规则测试可运行。
测试用例(≥8)
- test_controller_depends_service — 允许方向
- test_service_depends_mapper — 允许
- test_controller_to_mapper_forbidden — 禁止
- test_no_cycle — 无环
- test_rule_scope_modules — 作用域
- test_rule_verbose — 失败信息
- test_all_controllers_covered — 覆盖
- test_rule_stable — 稳定
任务 211:ArchUnit Controller 不访问 Mapper
所属模块:13 契约 依赖:210 预估:8-15 分钟
功能点要求
强化规则:任何 Controller 不得注入/调用 Mapper;违例失败。
测试用例(≥8)
- test_no_mapper_in_controller
- test_violation_detected — 违例检出
- test_message_clear
- test_controller_service_ok — 允许路径
- test_all_controllers_covered
- test_no_mapper_field
- test_rule_in_ci
- test_snapshot_frozen
任务 212:ArchUnit task 模块不依赖业务模块
所属模块:13 契约 依赖:210 预估:8-15 分钟
功能点要求
公共 task 模块不得 import 业务模块(similarasin/appearancepatent/...);04 的 Handler SPI 已反转依赖;规则检查通过。
测试用例(≥8)
- test_task_no_business_dep — 无业务依赖
- test_spi_interface_allowed — SPI 接口豁免
- test_violation_detected
- test_message_clear
- test_04_registry_ok — 注册表符合
- test_all_task_classes_covered
- test_rule_in_ci
- test_snapshot_frozen
任务 213:前端共享层导出白名单
所属模块:13 契约 依赖:无 预估:8-15 分钟
功能点要求
TS 检查:页面(pages/*)禁止直接 import shared/api/http.ts 或拼 URL;只允许 import java-modules.ts 的 API 函数与 bridges;违例编译失败(lint 规则或类型守卫)。
测试用例(≥8)
- test_page_no_http_direct — 页面不直连 http
- test_page_no_url_concat — 不拼 URL
- test_page_uses_api_module — 用 API 层
- test_shared_internal_allowed — shared 内部允许
- test_bridge_allowed — bridge 允许
- test_violation_detected
- test_check_runs_in_ci
- test_allowlist_frozen
任务 214:progress/batch 轻量响应契约
所属模块:13 契约 依赖:109 预估:8-15 分钟
功能点要求
progress/batch 契约:items/missingTaskIds 结构;task 轻量字段;file 字段(除 collectdata);前端解析一致。
测试用例(≥8)
- test_progress_batch_shape
- test_missing_ids_shape
- test_task_light_fields
- test_file_fields_included
- test_collectdata_exception — 例外模块
- test_frontend_parse_compat
- test_snapshot_frozen
- test_light_vs_batch_consistency
任务 215:下载 URL 格式契约
所属模块:13 契约 依赖:147 预估:8-15 分钟
功能点要求
downloadUrl 契约:公开直链格式(https、bucket 包含、result/ 前缀下载域名);无签名;前端 save_file 流程兼容。
测试用例(≥8)
- test_download_url_https
- test_download_url_bucket
- test_result_prefix_endpoint
- test_no_signature
- test_frontend_save_compat
- test_blank_handling
- test_contract_frozen
- test_download_flow_end2end
任务 216:CI 接入测试阶段
所属模块:13 契约 依赖:210-215 预估:8-15 分钟
功能点要求
.gitea/workflows/build.yml 追加:mvn test(契约+ArchUnit)、前端 vitest、契约快照比对;失败即红。
测试用例(≥8)
- test_ci_has_test_stage — 测试阶段
- test_ci_java_tests — Java 测试命令
- test_ci_frontend_tests — 前端测试
- test_ci_snapshot_check
- test_ci_fail_fast — 失败即红
- test_ci_cache
- test_ci_timeout
- test_ci_documented
任务 217:快照对比工具
所属模块:13 契约 依赖:90 预估:8-15 分钟
功能点要求
Service 拆分前后响应一致工具:录制(输入→输出)golden;对比(输出 diff);供 05 各模块使用。
测试用例(≥8)
- test_tool_records
- test_tool_compares_equal
- test_tool_diff_detected
- test_tool_output_report
- test_tool_reusable
- test_tool_commits_golden
- test_tool_clear_error
- test_tool_documented
任务 218:结果文件格式契约
所属模块:13 契约 依赖:无 预估:8-15 分钟
功能点要求
结果文件格式契约:文件名(*-result.xlsx 模式)、Sheet 名称、列顺序、ZIP 结构;与 Python/前端约定一致;改造(04/05)后不变。
测试用例(≥8)
- test_filename_pattern
- test_sheet_name
- test_column_order
- test_zip_structure
- test_encoding_utf8
- test_empty_result_file
- test_contract_frozen
- 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)
mvn clean package -DskipTests产 JAR,java -jar target/aiimage-backend-0.0.1-SNAPSHOT.jar(本地配置)启动,curl 健康检查端点返回预期- 核心页面(
/newApi/api/...抽样)可访问 - 核心交互路径:上传→解析→进度→下载最小链路真实调用非空
mvn test全绿(≥80% 覆盖抽查)npm run build(vue-tsc + vite)零错误;npx vitest run全绿- check_progress 脚本返回 all tasks done(exit 0)
- git log 验证每个 task 有对应 commit