49c3fc1491
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
159 lines
7.1 KiB
Markdown
159 lines
7.1 KiB
Markdown
# 08-plan — 结果文件阶段字段契约固化
|
||
|
||
> 对应 `docs/specs/08-result-file-phase-and-download.md`。**审计结论:Java 13 模块字段已实现、前端已消费,无代码改动需求。**
|
||
> 本 plan 将现状固化为契约测试,防止未来回归;不新增业务字段。
|
||
> 技术栈:Java 21 + JUnit5 + Vitest(前端)。
|
||
|
||
## 任务 140:13 模块 file 字段契约快照测试
|
||
|
||
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
对 13 个业务模块(similarasin/appearancepatent/shopdatacrawl/queryasin/withdraw/patroldelete/shopmatch/productrisk/pricetrack/deletebrand/publish/collectdata/brand)的响应 VO 断言 file 阶段字段存在且类型正确(collectdata 除外:断言其自洽语义);旧字段(taskId/resultId/downloadUrl/status)仍在。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_similar_has_file_fields — similarasin 字段齐全
|
||
2. test_appearance_has_file_fields
|
||
3. test_shopdatacrawl_has_file_fields
|
||
4. test_publish_has_file_fields — publish 文件级
|
||
5. test_collectdata_self_consistent — collectdata 无 file 字段(现状)
|
||
6. test_old_fields_present — 旧字段全在
|
||
7. test_file_field_types — 类型正确(boolean/string/integer)
|
||
8. test_contract_frozen_snapshot — JSON 快照冻结
|
||
|
||
### TDD 流程
|
||
1. 测试断言 VO 字段(反射/样例对象)→ 对现状应 GREEN(基线固化)
|
||
2. 若未来删除字段即 RED(回归保护)
|
||
3. `mvn test -Dtest=ResultFilePhaseContractTest` 通过
|
||
|
||
## 任务 141:similarasin file 进度合成逻辑单测
|
||
|
||
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
attachFileProgress 三路径:Coze 阶段(cozeCompleted/pending>0)、Python 上传阶段(未完成)、snapshot 百分比(上传完成无 coze);fileReady=true 时 100%。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_coze_progress_path — Coze 路径
|
||
2. test_python_upload_path — Python 上传路径
|
||
3. test_snapshot_percent_path — snapshot 路径
|
||
4. test_file_ready_100 — ready=100%
|
||
5. test_upload_not_complete_no_snapshot — 未完成且无快照
|
||
6. test_can_treat_completed — 可视为完成
|
||
7. test_task_not_running_skip — 非运行中跳过
|
||
8. test_percent_cap_99 — 未 ready 时 ≤99
|
||
|
||
### TDD 流程 / 验证方法
|
||
构造 FileResultEntity/TaskFileJobEntity/TaskProgressSnapshotEntity 组合断言输出(调用包可见/测试可见的 attachFileProgress 或经 toHistoryItem)。
|
||
|
||
## 任务 142:fileReady/fileStatus 语义测试
|
||
|
||
**所属模块**:08 结果阶段 **依赖**:140 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
fileReady = resultFileUrl 非空;无 job 时 fileStatus = ready?SUCCESS:null;有 job 时 fileStatus = job.status;fileError = job.errorMessage。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_ready_url_present — 有 URL ready=true
|
||
2. test_ready_url_blank — 空 URL ready=false
|
||
3. test_no_job_success_status — 无 job ready 时 SUCCESS
|
||
4. test_no_job_null_status — 无 job 未 ready null
|
||
5. test_job_status_mapped — job 状态映射
|
||
6. test_job_error_mapped — job 错误映射
|
||
7. test_ready_blank_whitespace — 空白字符串
|
||
8. test_semantics_frozen — 语义快照
|
||
|
||
## 任务 143:publish 文件级 file 状态测试
|
||
|
||
**所属模块**:08 结果阶段 **依赖**:140 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
publish 的 file 状态是文件级(PublishResultVo.setFileReady(ready)/setFileStatus(file.status)),与其余模块 job 级不同;语义固化。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_publish_file_ready — ready 设置
|
||
2. test_publish_file_status — 文件状态
|
||
3. test_publish_per_file — 按文件独立
|
||
4. test_publish_mixed_files — 多文件混合状态
|
||
5. test_publish_ready_all — 全 ready
|
||
6. test_publish_no_files — 无文件
|
||
7. test_publish_failed_file — 失败文件
|
||
8. test_publish_semantics_frozen — 语义快照
|
||
|
||
## 任务 144:前端 live progress 合并测试补强
|
||
|
||
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
mergeHistoryItemPreservingLiveProgress:history 缺失 file 进度时保留 live progress;incoming 有进度时用 incoming;可下载时不保留。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_merge_keeps_live_when_history_missing — 保留 live
|
||
2. test_merge_incoming_wins — incoming 优先
|
||
3. test_merge_no_keep_when_downloadable — 可下载不保留
|
||
4. test_merge_no_previous — 无 previous 返回 incoming
|
||
5. test_merge_partial_fields — 部分字段保留
|
||
6. test_merge_meaningful_progress — 有效进度值判断
|
||
7. test_merge_file_ready_flag — ready 标志保留
|
||
8. test_merge_idempotent — 幂等
|
||
|
||
### TDD 流程 / 验证方法
|
||
`npx vitest run`(扩展既有测试文件或新增)。
|
||
|
||
## 任务 145:前端可下载判定测试
|
||
|
||
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
canDownload/fileReady/fileStatus 终态判定:fileReady=true 可下载;fileStatus=SUCCESS/FAILED 可下载(FAILED 可下载错误文件或展示错误);其余不可下载。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_can_download_ready — ready 可下载
|
||
2. test_can_download_status_success — SUCCESS 可下载
|
||
3. test_can_download_status_failed — FAILED 展示错误
|
||
4. test_can_not_download_pending — PENDING 不可
|
||
5. test_can_not_download_null — null 不可
|
||
6. test_file_status_lowercase — 小写归一
|
||
7. test_ready_false_status_success — 组合判断
|
||
8. test_download_flow_no_result_resubmit — 下载失败不重提交
|
||
|
||
## 任务 146:collectdata 自洽行为测试
|
||
|
||
**所属模块**:08 结果阶段 **依赖**:140 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
collectdata 前端用 success + downloadUrl 判定下载;后端不返回 file 字段;行为自洽(任务 SUCCESS 且有 URL 才可下载)。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_collect_success_downloadable — SUCCESS+URL 可下载
|
||
2. test_collect_success_no_url — 无 URL 不可
|
||
3. test_collect_failed_no_download — 失败不可
|
||
4. test_collect_ready_download_url — URL 有效
|
||
5. test_collect_progress_display — 进度显示
|
||
6. test_collect_self_consistent_backend — 后端无 file 字段
|
||
7. test_collect_status_flow — 状态流
|
||
8. test_collect_contract_frozen — 快照
|
||
|
||
## 任务 147:downloadUrl 永不过期验证
|
||
|
||
**所属模块**:08 结果阶段 **依赖**:无 **预估**:8-15 分钟
|
||
|
||
### 功能点要求
|
||
generateFreshDownloadUrl 行为:result/ 前缀走 download-endpoint;非 result/ 走公开端点;无签名(URL 无过期参数);bucket 前缀正确。
|
||
|
||
### 测试用例(≥8)
|
||
1. test_result_prefix_download_endpoint — result/ 走下载域名
|
||
2. test_other_prefix_public — 其他走公开
|
||
3. test_no_signed_params — 无签名参数
|
||
4. test_bucket_in_url — bucket 包含
|
||
5. test_blank_input_fallback — 空值回退
|
||
6. test_uri_encoding — 路径编码
|
||
7. test_scheme_https — https
|
||
8. test_url_stable_over_time — 时间无关(无过期)
|
||
|
||
### TDD 流程 / 验证方法
|
||
OssStorageService 单测(配置注入 mock endpoint)。
|
||
|
||
### 收尾验证(本模块)
|
||
`mvn test` 相关类 + `cd frontend-vue && npx vitest run` 全绿;08 spec §2/§3 清单与实际一致。
|