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

323 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 语义、上传协议不变)。