Files
crawler-plugin/backend-java/docs/plans/08-plan-result-file-phase-contract.md
T
huangzd1997 49c3fc1491 docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」,
代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红),
跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
2026-10-04 13:51:16 +08:00

159 lines
7.1 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.
# 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 清单与实际一致。