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

316 lines
11 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.
# 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