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