49c3fc1491
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
316 lines
11 KiB
Markdown
316 lines
11 KiB
Markdown
# 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
|