# 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