task-148: 临时目录配置盘点（16 配置项/322 清理调用点扫描器 + 9 条测试 + 报告快照，不改生产代码）

backend-java/scripts/temp_config_audit.py

@@ -0,0 +1,113 @@
+"""task-148 临时目录配置盘点工具。
+
+盘点 backend-java 的临时文件相关配置（application.yml 中的路径/前缀/保留期）
+与既有清理逻辑调用点，产出机器可读清单供审计文档使用。本工具只读，不改代码。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+YML_PATH = REPO_ROOT / "src/main/resources/application.yml"
+MAIN_ROOT = REPO_ROOT / "src/main/java"
+
+# 临时文件相关配置键（application.yml 键名匹配）
+CONFIG_KEY_RE = re.compile(
+    r"(local-temp-dir|retention-hours|retention-days|temp-dir|transient-payload|"
+    r"payload-|upload-|source-retention|result-retention|tmp|buffer-retention)",
+    re.IGNORECASE,
+)
+# 既有清理逻辑调用点（临时文件清理）
+CLEANUP_RE = re.compile(
+    r"(deleteIfExists|Files\.delete|cleanup|deleteTemp|tempDir|transientPayloadStorageService\.delete|"
+    r"\.del\(|FileUtil\.del|cleanupPrepared|deletePayloadIfPresent)",
+    re.IGNORECASE,
+)
+
+
+def extract_configs() -> list[dict]:
+    """从 application.yml 提取临时文件相关配置项。"""
+    if not YML_PATH.is_file():
+        return []
+    configs: list[dict] = []
+    for line_no, line in enumerate(
+        YML_PATH.read_text(encoding="utf-8").splitlines(), start=1
+    ):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        match = re.match(r"^([\w.-]+):\s*(.*)$", stripped)
+        if not match:
+            continue
+        key, value = match.group(1), match.group(2).strip()
+        if CONFIG_KEY_RE.search(key):
+            configs.append(
+                {
+                    "key": key,
+                    "value": value,
+                    "line": line_no,
+                    "source": "application.yml",
+                }
+            )
+    return configs
+
+
+def extract_cleanup_calls() -> list[dict]:
+    """扫描 main 源码中临时文件清理调用点。"""
+    calls: list[dict] = []
+    for java_file in sorted(MAIN_ROOT.rglob("*.java")):
+        text = java_file.read_text(encoding="utf-8")
+        for line_no, line in enumerate(text.splitlines(), start=1):
+            if CLEANUP_RE.search(line) and "import " not in line:
+                calls.append(
+                    {
+                        "file": str(java_file.relative_to(REPO_ROOT)).replace(
+                            "\\", "/"
+                        ),
+                        "line": line_no,
+                        "snippet": line.strip()[:100],
+                    }
+                )
+    return calls
+
+
+@dataclass
+class Report:
+    configs: list[dict] = field(default_factory=list)
+    cleanup_calls: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {"configs": self.configs, "cleanup_calls": self.cleanup_calls}
+
+
+def scan() -> Report:
+    return Report(configs=extract_configs(), cleanup_calls=extract_cleanup_calls())
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="临时目录配置盘点")
+    parser.add_argument("--json", help="输出 JSON 报告路径（默认 stdout）")
+    args = parser.parse_args()
+
+    report = scan()
+    payload = report.to_dict()
+    if args.json:
+        Path(args.json).write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+    else:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    print(
+        f"configs: {len(payload['configs'])}, cleanup calls: {len(payload['cleanup_calls'])}",
+        file=sys.stderr,
+    )
+
+
+if __name__ == "__main__":
+    main()

backend-java/scripts/test_temp_config_audit.py

@@ -0,0 +1,89 @@
+"""task-148 临时目录配置盘点测试。
+
+对应 plan 09 任务 148 的 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           零代码变更
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import unittest
+
+from temp_config_audit import REPO_ROOT, extract_cleanup_calls, extract_configs, scan
+
+DOC_PATH = REPO_ROOT / "docs" / "temp-file-config-audit.md"
+
+
+class TempConfigAuditTest(unittest.TestCase):
+    def test_config_listed(self):
+        configs = extract_configs()
+        self.assertGreaterEqual(len(configs), 8, "配置项清单必须齐全")
+        for item in configs:
+            for key in ("key", "value", "line", "source"):
+                self.assertIn(key, item)
+
+    def test_temp_root_defined(self):
+        keys = {c["key"] for c in extract_configs()}
+        self.assertTrue(
+            any("local-temp-dir" in k for k in keys),
+            f"临时根目录配置缺失: {sorted(keys)}",
+        )
+
+    def test_retention_period(self):
+        keys = {c["key"] for c in extract_configs()}
+        self.assertTrue(any("retention" in k for k in keys), "保留期配置缺失")
+
+    def test_payload_prefixes(self):
+        keys = {c["key"] for c in extract_configs()}
+        self.assertTrue(
+            any("transient-payload" in k for k in keys), "transient payload 配置缺失"
+        )
+
+    def test_upload_dir(self):
+        configs = extract_configs()
+        self.assertTrue(
+            any(
+                "upload" in c["key"].lower() or "tmp" in c["key"].lower()
+                for c in configs
+            ),
+            "上传/临时目录配置缺失",
+        )
+
+    def test_existing_cleanup_noted(self):
+        calls = extract_cleanup_calls()
+        self.assertGreater(len(calls), 0, "必须记录既有清理调用点")
+        files = {c["file"] for c in calls}
+        self.assertGreaterEqual(len(files), 3, "清理调用应覆盖多个文件")
+
+    def test_doc_committed(self):
+        self.assertTrue(DOC_PATH.is_file(), f"盘点文档缺失: {DOC_PATH}")
+        text = DOC_PATH.read_text(encoding="utf-8")
+        self.assertIn("临时", text)
+        self.assertIn("保留期", text)
+
+    def test_no_code_change(self):
+        changed = subprocess.run(
+            ["git", "diff", "--name-only", "HEAD", "--", "backend-java/src"],
+            cwd=REPO_ROOT,
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.strip()
+        self.assertEqual(changed, "", f"生产代码被改动: {changed}")
+
+    def test_scan_repeatable(self):
+        first = json.dumps(scan().to_dict(), sort_keys=True)
+        second = json.dumps(scan().to_dict(), sort_keys=True)
+        self.assertEqual(first, second, "盘点结果可重复")
+
+
+if __name__ == "__main__":
+    unittest.main()