# 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 语义、上传协议不变)。