`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
12 KiB
09-plan — 临时文件生命周期治理
对应
docs/specs/09-temp-file-lifecycle.md。第一阶段只巡检不自动删;路径安全是硬门槛。 技术栈:Java 21 + Spring Scheduling + JUnit5。
任务 148:临时目录配置盘点
所属模块:09 临时文件 依赖:无 预估:8-15 分钟
功能点要求
盘点 TransientStorageProperties/StorageProperties/TransientPayloadStorageService 的临时目录配置(路径、前缀、保留期、现有清理逻辑);产出配置清单文档;不改代码。
测试用例(≥8)
- test_config_listed — 配置项清单齐全
- test_temp_root_defined — 临时根目录定义
- test_retention_period — 保留期定义
- test_payload_prefixes — payload 前缀
- test_upload_dir — 上传目录
- test_existing_cleanup_noted — 现有清理逻辑记录
- test_doc_committed — 文档存在
- test_no_code_change — 零代码变更
TDD 流程
- 断言清单文档存在且字段齐全 → RED
- 产出文档 → GREEN
任务 149:创建/访问时间记录审计与补缺
所属模块:09 临时文件 依赖:148 预估:8-15 分钟
功能点要求
临时文件创建时间/大小/最后访问时间记录:现有实现缺最后访问时间则补(文件 mtime 或记录表);不改变文件语义。
测试用例(≥8)
- test_creation_time_recorded — 创建时间
- test_size_recorded — 大小
- test_access_time_readable — 访问时间可读
- test_access_time_fallback — mtime 回退
- test_record_update — 访问更新
- test_record_missing_grace — 缺记录容忍
- test_record_no_io_error — IO 错误不阻断
- test_record_consistency — 一致
任务 150:引用检查(清理前)
所属模块:09 临时文件 依赖:148 预估:8-15 分钟
功能点要求
清理前确认无任务引用:fileKey 被 task_file_job/file_result 引用则不清理;引用判定逻辑可测试。
测试用例(≥8)
- test_referenced_kept — 被引用不清理
- test_unreferenced_candidate — 无引用可清理
- test_reference_by_job — job 引用
- test_reference_by_result — result 引用
- test_reference_unknown — 未知引用安全
- test_check_no_side_effect — 检查无副作用
- test_check_failure_keeps — 检查失败保守保留
- test_check_batch — 批量检查
任务 151:路径安全校验
所属模块:09 临时文件 依赖:148 预估:8-15 分钟
功能点要求
删除前校验:路径规范化后 startsWith(临时根目录);穿越(../、绝对路径逃逸、符号链接)拒绝;非法路径不删除并记录。
测试用例(≥8)
- test_inside_root_ok — 根内允许
- test_traversal_rejected — ../ 拒绝
- test_absolute_escape — 绝对路径逃逸拒绝
- test_symlink_escape — 符号链接逃逸拒绝
- test_normalize_before_check — 规范化后校验
- test_relative_subdir — 子目录允许
- test_sibling_rejected — 兄弟目录拒绝
- test_illegal_logged — 非法路径记录
TDD 流程
- 测试(构造各种路径)→ RED
- 实现校验 → GREEN
mvn test -Dtest=TransientPathGuardTest通过
任务 152:清理失败吞异常记指标
所属模块:09 临时文件 依赖:150,151 预估:8-15 分钟
功能点要求
清理失败:记录日志+指标(清理失败计数),不抛异常、不阻断主流程;不自动重试成循环。
测试用例(≥8)
- test_failure_logged — 日志
- test_failure_metric — 指标
- test_failure_no_throw — 不抛出
- test_failure_flow_continues — 主流程继续
- test_failure_no_retry_loop — 不循环
- test_failure_next_round — 下轮可再试
- test_failure_partial — 部分失败处理
- test_failure_isolation — 隔离其他文件
任务 153:fileKey 兜底查找
所属模块:09 临时文件 依赖:148 预估:8-15 分钟
功能点要求
进程重启后 fileKey 兜底:上传记录持久化或重启后按 fileKey 重建索引;找不到时明确失败而非静默。
测试用例(≥8)
- test_file_key_found — 找到
- test_file_key_after_restart — 重启后找到
- test_file_key_missing — 缺失明确失败
- test_file_key_null — null 安全
- test_file_key_cleanup — 清理后不可找
- test_file_key_record_persist — 记录持久化
- test_file_key_rebuild — 索引重建
- test_file_key_semantics_frozen — 语义不变
任务 154:磁盘容量告警
所属模块:09 临时文件 依赖:152 预估:8-15 分钟
功能点要求
临时目录容量超阈值:记录告警日志(当前容量/阈值);无监控栈时仅日志输出;不阻塞业务。
测试用例(≥8)
- test_warning_threshold — 阈值判断
- test_warning_logged — 告警日志
- test_under_threshold_silent — 未超不告警
- test_warning_repeat_limited — 告警频率限制
- test_usage_measured — 容量测量
- test_usage_zero — 空目录
- test_measure_error_grace — 测量失败容忍
- test_warning_no_block — 不阻塞
任务 155:孤立文件巡检报表
所属模块:09 临时文件 依赖:150 预估:8-15 分钟
功能点要求
只读巡检:临时目录中无任何引用/超过保留期的文件清单输出到报表(日志或报表文件);不删除。
测试用例(≥8)
- test_orphan_detected — 孤立文件检出
- test_referenced_not_reported — 被引用不报
- test_report_output — 报表输出
- test_read_only_no_delete — 只读不删
- test_report_batch — 批量
- test_report_empty — 无孤立空报表
- test_report_rerun_safe — 可重复
- test_report_details — 详情(路径/大小/时间)
任务 156:孤立 Job 巡检报表
所属模块:09 临时文件 依赖:无 预估:8-15 分钟
功能点要求
只读巡检:task_file_job 无对应 task/result 的孤儿 Job 清单;输出报表;不修改状态。
测试用例(≥8)
- test_orphan_job_detected — 检出
- test_valid_job_not_reported — 正常不报
- test_report_output — 输出
- test_read_only — 不修改
- test_job_retry_orphan — 重试耗尽孤儿
- test_report_empty — 空
- test_report_details — 详情
- test_rerun_safe — 可重复
任务 157:任务存在结果缺失巡检
所属模块:09 临时文件 依赖:无 预估:8-15 分钟
功能点要求
只读巡检:任务存在但结果缺失(SUCCESS 任务无 file_result)清单。
测试用例(≥8)
- test_missing_result_detected — 检出
- test_with_result_not_reported — 有结果不报
- test_success_no_result — SUCCESS 无结果
- test_running_ignored — 运行中忽略
- test_report_empty
- test_read_only
- test_details
- test_rerun_safe
任务 158:结果存在文件缺失巡检
所属模块:09 临时文件 依赖:无 预估:8-15 分钟
功能点要求
只读巡检:file_result 的 resultFileUrl 对应文件在 OSS/本地不存在清单。
测试用例(≥8)
- test_file_missing_detected
- test_file_exists_ok
- test_blank_url_handled — 空 URL
- test_oss_check — OSS 校验(mock)
- test_report_empty
- test_read_only
- test_details
- test_rerun_safe
任务 159:已完成任务活跃 Job 巡检
所属模块:09 临时文件 依赖:无 预估:8-15 分钟
功能点要求
只读巡检:任务已终态(SUCCESS/FAILED)但仍有活跃(RUNNING/PENDING)Job 清单。
测试用例(≥8)
- test_active_job_after_terminal — 检出
- test_terminal_no_job_ok
- test_job_active_task_running_ok — 运行中任务正常
- test_stuck_job_reported — 卡死 Job
- test_report_empty
- test_read_only
- test_details
- test_rerun_safe
任务 160:超保留期仍被引用巡检
所属模块:09 临时文件 依赖:150 预估:8-15 分钟
功能点要求
只读巡检:临时文件超保留期但仍有引用清单(供人工处理)。
测试用例(≥8)
- test_over_retention_referenced — 检出
- test_in_retention_ok
- test_over_retention_unreferenced — 无引用(另表)
- test_boundary_retention — 边界时间
- test_report_empty
- test_read_only
- test_details
- test_rerun_safe
任务 161:巡检任务开关(默认 disabled)
所属模块:09 临时文件 依赖:155-160 预估:8-15 分钟
功能点要求
全部巡检任务由配置开关控制(默认 disabled);启用后按调度间隔执行;双实例不重复输出(owner 或随机)。
测试用例(≥8)
- test_disabled_by_default — 默认关
- test_enabled_runs — 启用执行
- test_schedule_interval — 间隔配置
- test_dual_instance_no_dup — 双实例不重复
- test_run_error_grace — 异常不阻断
- test_each_report_independent — 各报表独立
- test_config_override — 覆盖生效
- test_enabled_no_crash — 启用稳定
任务 162:路径穿越测试
所属模块:09 临时文件 依赖:151 预估:8-15 分钟
功能点要求
穿越输入矩阵:../、..\\、绝对路径、URL 编码 %2e%2e、Unicode 全角点、混合分隔符——全部拒绝。
测试用例(≥8)
- test_dotdot_slash — ../
- test_dotdot_backslash — ..\
- test_encoded_dotdot — %2e%2e
- test_fullwidth_dot — 全角点
- test_abs_win_path — C:\ 形式
- test_abs_unix_path — /etc 形式
- test_mixed_separator — 混合分隔符
- test_null_byte — 空字节
任务 163:引用中文件不清测试
所属模块:09 临时文件 依赖:150 预估:8-15 分钟
功能点要求
被 job/result 引用的文件:清理流程跳过;仅未引用文件被清理(清理流程本身在后续批次实现时,本任务先固化引用检查)。
测试用例(≥8)
- test_job_referenced_skip — job 引用跳过
- test_result_referenced_skip — result 引用跳过
- test_unreferenced_passes — 未引用通过
- test_multi_reference — 多引用
- test_check_after_delete_history — 删历史后解除引用
- test_check_batch_mixed — 混合批次
- test_check_null_safe
- test_check_idempotent
任务 164:清理失败不阻断测试
所属模块:09 临时文件 依赖:152 预估:8-15 分钟
功能点要求
清理一个文件失败不影响其他文件清理;主业务不受影响;错误可见(日志/指标)。
测试用例(≥8)
- test_one_fail_others_succeed — 单失败其余成功
- test_failure_visible — 错误可见
- test_no_throw_up — 不上抛
- test_retry_next_round — 下轮重试
- test_partial_result_reported — 部分结果报告
- test_metric_recorded — 指标
- test_flow_continues — 流程继续
- test_no_cascading — 无级联
任务 165:巡检只读测试
所属模块:09 临时文件 依赖:155-161 预估:8-15 分钟
功能点要求
全部巡检运行后:零删除、零状态修改、零写库(只读);可重复执行。
测试用例(≥8)
- test_no_delete — 零删除
- test_no_state_change — 状态不变
- test_no_db_write — 无写库
- test_read_repeatable — 重复一致
- test_isolated_reports — 报表隔离
- test_read_only_assert — 只读断言
- test_no_side_effects — 无副作用
- test_full_suite_run — 全巡检套件
收尾验证(本模块)
mvn test 相关类全绿;09 spec §4 不变要求逐项核对(fileKey 语义、上传协议不变)。