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

12 KiB
Raw Blame History

09-plan — 临时文件生命周期治理

对应 docs/specs/09-temp-file-lifecycle.md。第一阶段只巡检不自动删;路径安全是硬门槛。 技术栈:Java 21 + Spring Scheduling + JUnit5。

任务 148:临时目录配置盘点

所属模块:09 临时文件 依赖:无 预估:8-15 分钟

功能点要求

盘点 TransientStorageProperties/StorageProperties/TransientPayloadStorageService 的临时目录配置(路径、前缀、保留期、现有清理逻辑);产出配置清单文档;不改代码。

测试用例(≥8)

  1. test_config_listed — 配置项清单齐全
  2. test_temp_root_defined — 临时根目录定义
  3. test_retention_period — 保留期定义
  4. test_payload_prefixes — payload 前缀
  5. test_upload_dir — 上传目录
  6. test_existing_cleanup_noted — 现有清理逻辑记录
  7. test_doc_committed — 文档存在
  8. test_no_code_change — 零代码变更

TDD 流程

  1. 断言清单文档存在且字段齐全 → RED
  2. 产出文档 → GREEN

任务 149:创建/访问时间记录审计与补缺

所属模块:09 临时文件 依赖:148 预估:8-15 分钟

功能点要求

临时文件创建时间/大小/最后访问时间记录:现有实现缺最后访问时间则补(文件 mtime 或记录表);不改变文件语义。

测试用例(≥8)

  1. test_creation_time_recorded — 创建时间
  2. test_size_recorded — 大小
  3. test_access_time_readable — 访问时间可读
  4. test_access_time_fallback — mtime 回退
  5. test_record_update — 访问更新
  6. test_record_missing_grace — 缺记录容忍
  7. test_record_no_io_error — IO 错误不阻断
  8. test_record_consistency — 一致

任务 150:引用检查(清理前)

所属模块:09 临时文件 依赖:148 预估:8-15 分钟

功能点要求

清理前确认无任务引用:fileKey 被 task_file_job/file_result 引用则不清理;引用判定逻辑可测试。

测试用例(≥8)

  1. test_referenced_kept — 被引用不清理
  2. test_unreferenced_candidate — 无引用可清理
  3. test_reference_by_job — job 引用
  4. test_reference_by_result — result 引用
  5. test_reference_unknown — 未知引用安全
  6. test_check_no_side_effect — 检查无副作用
  7. test_check_failure_keeps — 检查失败保守保留
  8. test_check_batch — 批量检查

任务 151:路径安全校验

所属模块:09 临时文件 依赖:148 预估:8-15 分钟

功能点要求

删除前校验:路径规范化后 startsWith(临时根目录);穿越(../、绝对路径逃逸、符号链接)拒绝;非法路径不删除并记录。

测试用例(≥8)

  1. test_inside_root_ok — 根内允许
  2. test_traversal_rejected — ../ 拒绝
  3. test_absolute_escape — 绝对路径逃逸拒绝
  4. test_symlink_escape — 符号链接逃逸拒绝
  5. test_normalize_before_check — 规范化后校验
  6. test_relative_subdir — 子目录允许
  7. test_sibling_rejected — 兄弟目录拒绝
  8. test_illegal_logged — 非法路径记录

TDD 流程

  1. 测试(构造各种路径)→ RED
  2. 实现校验 → GREEN
  3. mvn test -Dtest=TransientPathGuardTest 通过

任务 152:清理失败吞异常记指标

所属模块:09 临时文件 依赖:150,151 预估:8-15 分钟

功能点要求

清理失败:记录日志+指标(清理失败计数),不抛异常、不阻断主流程;不自动重试成循环。

测试用例(≥8)

  1. test_failure_logged — 日志
  2. test_failure_metric — 指标
  3. test_failure_no_throw — 不抛出
  4. test_failure_flow_continues — 主流程继续
  5. test_failure_no_retry_loop — 不循环
  6. test_failure_next_round — 下轮可再试
  7. test_failure_partial — 部分失败处理
  8. test_failure_isolation — 隔离其他文件

任务 153:fileKey 兜底查找

所属模块:09 临时文件 依赖:148 预估:8-15 分钟

功能点要求

进程重启后 fileKey 兜底:上传记录持久化或重启后按 fileKey 重建索引;找不到时明确失败而非静默。

测试用例(≥8)

  1. test_file_key_found — 找到
  2. test_file_key_after_restart — 重启后找到
  3. test_file_key_missing — 缺失明确失败
  4. test_file_key_null — null 安全
  5. test_file_key_cleanup — 清理后不可找
  6. test_file_key_record_persist — 记录持久化
  7. test_file_key_rebuild — 索引重建
  8. test_file_key_semantics_frozen — 语义不变

任务 154:磁盘容量告警

所属模块:09 临时文件 依赖:152 预估:8-15 分钟

功能点要求

临时目录容量超阈值:记录告警日志(当前容量/阈值);无监控栈时仅日志输出;不阻塞业务。

测试用例(≥8)

  1. test_warning_threshold — 阈值判断
  2. test_warning_logged — 告警日志
  3. test_under_threshold_silent — 未超不告警
  4. test_warning_repeat_limited — 告警频率限制
  5. test_usage_measured — 容量测量
  6. test_usage_zero — 空目录
  7. test_measure_error_grace — 测量失败容忍
  8. test_warning_no_block — 不阻塞

任务 155:孤立文件巡检报表

所属模块:09 临时文件 依赖:150 预估:8-15 分钟

功能点要求

只读巡检:临时目录中无任何引用/超过保留期的文件清单输出到报表(日志或报表文件);不删除。

测试用例(≥8)

  1. test_orphan_detected — 孤立文件检出
  2. test_referenced_not_reported — 被引用不报
  3. test_report_output — 报表输出
  4. test_read_only_no_delete — 只读不删
  5. test_report_batch — 批量
  6. test_report_empty — 无孤立空报表
  7. test_report_rerun_safe — 可重复
  8. test_report_details — 详情(路径/大小/时间)

任务 156:孤立 Job 巡检报表

所属模块:09 临时文件 依赖:无 预估:8-15 分钟

功能点要求

只读巡检:task_file_job 无对应 task/result 的孤儿 Job 清单;输出报表;不修改状态。

测试用例(≥8)

  1. test_orphan_job_detected — 检出
  2. test_valid_job_not_reported — 正常不报
  3. test_report_output — 输出
  4. test_read_only — 不修改
  5. test_job_retry_orphan — 重试耗尽孤儿
  6. test_report_empty — 空
  7. test_report_details — 详情
  8. test_rerun_safe — 可重复

任务 157:任务存在结果缺失巡检

所属模块:09 临时文件 依赖:无 预估:8-15 分钟

功能点要求

只读巡检:任务存在但结果缺失(SUCCESS 任务无 file_result)清单。

测试用例(≥8)

  1. test_missing_result_detected — 检出
  2. test_with_result_not_reported — 有结果不报
  3. test_success_no_result — SUCCESS 无结果
  4. test_running_ignored — 运行中忽略
  5. test_report_empty
  6. test_read_only
  7. test_details
  8. test_rerun_safe

任务 158:结果存在文件缺失巡检

所属模块:09 临时文件 依赖:无 预估:8-15 分钟

功能点要求

只读巡检:file_result 的 resultFileUrl 对应文件在 OSS/本地不存在清单。

测试用例(≥8)

  1. test_file_missing_detected
  2. test_file_exists_ok
  3. test_blank_url_handled — 空 URL
  4. test_oss_check — OSS 校验(mock)
  5. test_report_empty
  6. test_read_only
  7. test_details
  8. test_rerun_safe

任务 159:已完成任务活跃 Job 巡检

所属模块:09 临时文件 依赖:无 预估:8-15 分钟

功能点要求

只读巡检:任务已终态(SUCCESS/FAILED)但仍有活跃(RUNNING/PENDING)Job 清单。

测试用例(≥8)

  1. test_active_job_after_terminal — 检出
  2. test_terminal_no_job_ok
  3. test_job_active_task_running_ok — 运行中任务正常
  4. test_stuck_job_reported — 卡死 Job
  5. test_report_empty
  6. test_read_only
  7. test_details
  8. test_rerun_safe

任务 160:超保留期仍被引用巡检

所属模块:09 临时文件 依赖:150 预估:8-15 分钟

功能点要求

只读巡检:临时文件超保留期但仍有引用清单(供人工处理)。

测试用例(≥8)

  1. test_over_retention_referenced — 检出
  2. test_in_retention_ok
  3. test_over_retention_unreferenced — 无引用(另表)
  4. test_boundary_retention — 边界时间
  5. test_report_empty
  6. test_read_only
  7. test_details
  8. test_rerun_safe

任务 161:巡检任务开关(默认 disabled)

所属模块:09 临时文件 依赖:155-160 预估:8-15 分钟

功能点要求

全部巡检任务由配置开关控制(默认 disabled);启用后按调度间隔执行;双实例不重复输出(owner 或随机)。

测试用例(≥8)

  1. test_disabled_by_default — 默认关
  2. test_enabled_runs — 启用执行
  3. test_schedule_interval — 间隔配置
  4. test_dual_instance_no_dup — 双实例不重复
  5. test_run_error_grace — 异常不阻断
  6. test_each_report_independent — 各报表独立
  7. test_config_override — 覆盖生效
  8. test_enabled_no_crash — 启用稳定

任务 162:路径穿越测试

所属模块:09 临时文件 依赖:151 预估:8-15 分钟

功能点要求

穿越输入矩阵:../、..\\、绝对路径、URL 编码 %2e%2e、Unicode 全角点、混合分隔符——全部拒绝。

测试用例(≥8)

  1. test_dotdot_slash — ../
  2. test_dotdot_backslash — ..\
  3. test_encoded_dotdot — %2e%2e
  4. test_fullwidth_dot — 全角点
  5. test_abs_win_path — C:\ 形式
  6. test_abs_unix_path — /etc 形式
  7. test_mixed_separator — 混合分隔符
  8. test_null_byte — 空字节

任务 163:引用中文件不清测试

所属模块:09 临时文件 依赖:150 预估:8-15 分钟

功能点要求

被 job/result 引用的文件:清理流程跳过;仅未引用文件被清理(清理流程本身在后续批次实现时,本任务先固化引用检查)。

测试用例(≥8)

  1. test_job_referenced_skip — job 引用跳过
  2. test_result_referenced_skip — result 引用跳过
  3. test_unreferenced_passes — 未引用通过
  4. test_multi_reference — 多引用
  5. test_check_after_delete_history — 删历史后解除引用
  6. test_check_batch_mixed — 混合批次
  7. test_check_null_safe
  8. test_check_idempotent

任务 164:清理失败不阻断测试

所属模块:09 临时文件 依赖:152 预估:8-15 分钟

功能点要求

清理一个文件失败不影响其他文件清理;主业务不受影响;错误可见(日志/指标)。

测试用例(≥8)

  1. test_one_fail_others_succeed — 单失败其余成功
  2. test_failure_visible — 错误可见
  3. test_no_throw_up — 不上抛
  4. test_retry_next_round — 下轮重试
  5. test_partial_result_reported — 部分结果报告
  6. test_metric_recorded — 指标
  7. test_flow_continues — 流程继续
  8. test_no_cascading — 无级联

任务 165:巡检只读测试

所属模块:09 临时文件 依赖:155-161 预估:8-15 分钟

功能点要求

全部巡检运行后:零删除、零状态修改、零写库(只读);可重复执行。

测试用例(≥8)

  1. test_no_delete — 零删除
  2. test_no_state_change — 状态不变
  3. test_no_db_write — 无写库
  4. test_read_repeatable — 重复一致
  5. test_isolated_reports — 报表隔离
  6. test_read_only_assert — 只读断言
  7. test_no_side_effects — 无副作用
  8. test_full_suite_run — 全巡检套件

收尾验证(本模块)

mvn test 相关类全绿;09 spec §4 不变要求逐项核对(fileKey 语义、上传协议不变)。