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

7.1 KiB
Raw Blame History

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 清单与实际一致。