task-124: @Transactional 方法审计清单（147 方法/30 模块扫描器 + 13 条测试 + 报告快照，不改生产代码）

backend-java/scripts/test_tx_audit.py

@@ -0,0 +1,204 @@
+"""task-124 @Transactional 方法审计清单测试。
+
+对应 plan 07 任务 124 的 8 条用例 + 2 条补强：
+1. test_audit_covers_all_modules  覆盖全部业务模块
+2. test_audit_classification      分类完整（必须/可移出）
+3. test_audit_result_endpoints    /result 相关方法都在清单
+4. test_audit_python_facing       Python 回调相关标记
+5. test_audit_priority_order      按收益排序
+6. test_audit_no_code_change      本任务零代码变更
+7. test_audit_documented          文档产出
+8. test_audit_repeatable          可重复执行
+9. test_audit_detects_tx_method   识别 @Transactional 方法
+10. test_audit_classifies_movable 事务内可移出段分类
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import unittest
+from pathlib import Path
+
+from tx_audit import MODULES_ROOT, scan_modules, scan_text
+
+SCRIPTS_DIR = Path(__file__).resolve().parent
+REPO_ROOT = SCRIPTS_DIR.parent.parent
+DOC_PATH = REPO_ROOT / "backend-java" / "docs" / "transaction-boundary-audit.md"
+
+FIXTURE_TX = """package com.example;
+@Service
+public class DemoService {
+    @Transactional
+    public boolean submitResult(Long taskId, List<RowVo> rows) {
+        List<ItemVo> items = rows.stream()
+                .map(row -> toVo(row))
+                .collect(Collectors.toList());
+        int updated = fileResultMapper.update(null, new LambdaUpdateWrapper<FileResultEntity>()
+                .eq(FileResultEntity::getId, taskId)
+                .set(FileResultEntity::getStatus, "SUCCESS"));
+        log.info("submitted taskId={} count={}", taskId, items.size());
+        Files.deleteIfExists(Path.of("/tmp/task-" + taskId));
+        return updated > 0;
+    }
+
+    public void noTxMethod(Long id) {
+        fileTaskMapper.selectById(id);
+    }
+}
+"""
+
+FIXTURE_WRITE_ONLY = """package com.example;
+@Service
+public class DemoService {
+    @Transactional
+    public int markFailed(Long id) {
+        return fileTaskMapper.update(null, new LambdaUpdateWrapper<FileTaskEntity>()
+                .eq(FileTaskEntity::getId, id)
+                .set(FileTaskEntity::getStatus, "FAILED"));
+    }
+}
+"""
+
+FIXTURE_LOCK = """package com.example;
+@Service
+public class DemoService {
+    @Transactional
+    public void finalizeTask(Long taskId) {
+        TaskDistributedLockService.LockHandle handle = acquireTaskLock("MODULE", taskId);
+        if (handle == null) {
+            return;
+        }
+        try (handle) {
+            taskMapper.update(null, new LambdaUpdateWrapper<TaskFileEntity>()
+                    .eq(TaskFileEntity::getId, taskId));
+        }
+    }
+}
+"""
+
+FIXTURE_PLAIN = """package com.example;
+@Service
+public class DemoService {
+    public int sum(List<Integer> nums) {
+        return nums.stream().mapToInt(Integer::intValue).sum();
+    }
+}
+"""
+
+
+class TxAuditDetectTest(unittest.TestCase):
+    def test_audit_detects_tx_method(self):
+        findings = scan_text(FIXTURE_TX, "DemoService.java")
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0]["method"], "submitResult")
+        self.assertFalse(findings[0]["class_level"])
+
+    def test_audit_classifies_movable(self):
+        findings = scan_text(FIXTURE_TX, "DemoService.java")
+        self.assertEqual(len(findings), 1)
+        movable = findings[0]["movable"]
+        self.assertIn("compute", movable)
+        self.assertIn("assembly", movable)
+        self.assertIn("log", movable)
+        self.assertIn("cleanup", movable)
+        self.assertIn("write", findings[0]["must_stay"])
+        self.assertGreater(findings[0]["priority"], 0)
+
+    def test_audit_no_tx_not_reported(self):
+        self.assertEqual(len(scan_text(FIXTURE_PLAIN, "Plain.java")), 0)
+
+    def test_audit_write_only_no_movable(self):
+        findings = scan_text(FIXTURE_WRITE_ONLY, "DemoService.java")
+        self.assertEqual(len(findings), 1)
+        self.assertIn("write", findings[0]["must_stay"])
+        self.assertEqual(findings[0]["movable"], [])
+
+    def test_audit_lock_flagged_must_stay(self):
+        findings = scan_text(FIXTURE_LOCK, "DemoService.java")
+        self.assertEqual(len(findings), 1)
+        self.assertIn("lock", findings[0]["must_stay"])
+
+
+class TxAuditCoverageTest(unittest.TestCase):
+    def test_audit_covers_all_modules(self):
+        report = scan_modules(MODULES_ROOT)
+        self.assertGreaterEqual(report.scanned_files, 600)
+        self.assertGreater(len(report.findings), 50)
+        modules = {f["module"] for f in report.findings}
+        self.assertGreaterEqual(len(modules), 15)
+
+    def test_audit_classification(self):
+        for finding in scan_modules(MODULES_ROOT).findings:
+            self.assertIn("must_stay", finding)
+            self.assertIn("movable", finding)
+            self.assertIsInstance(finding["must_stay"], list)
+            self.assertIsInstance(finding["movable"], list)
+
+    def test_audit_result_endpoints(self):
+        report = scan_modules(MODULES_ROOT)
+        result_methods = [
+            f
+            for f in report.findings
+            if "result" in f["method"].lower() or "submit" in f["method"].lower()
+        ]
+        self.assertGreater(
+            len(result_methods), 0, "应找到 /result 相关 @Transactional 方法"
+        )
+        modules_with_result = {f["module"] for f in result_methods}
+        self.assertGreaterEqual(len(modules_with_result), 3)
+
+    def test_audit_python_facing(self):
+        report = scan_modules(MODULES_ROOT)
+        flagged = [f for f in report.findings if f["python_facing"]]
+        self.assertGreater(len(flagged), 0, "应标记 Python 回调相关方法")
+        for f in flagged:
+            name = f["method"].lower()
+            self.assertTrue(
+                any(
+                    k in name
+                    for k in (
+                        "result",
+                        "submit",
+                        "upload",
+                        "chunk",
+                        "done",
+                        "ack",
+                        "report",
+                    )
+                ),
+                f"python_facing 标记与命名不符: {f['method']}",
+            )
+
+    def test_audit_priority_order(self):
+        findings = scan_modules(MODULES_ROOT).findings
+        priorities = [f["priority"] for f in findings]
+        self.assertEqual(priorities, sorted(priorities, reverse=True))
+
+    def test_audit_repeatable(self):
+        first = scan_modules(MODULES_ROOT).to_dict()
+        second = scan_modules(MODULES_ROOT).to_dict()
+        self.assertEqual(
+            json.dumps(first, sort_keys=True), json.dumps(second, sort_keys=True)
+        )
+
+    def test_audit_documented(self):
+        self.assertTrue(DOC_PATH.is_file(), f"audit doc missing: {DOC_PATH}")
+        text = DOC_PATH.read_text(encoding="utf-8")
+        self.assertIn("事务", text)
+        self.assertIn("必须", text)
+        self.assertIn("可移出", text)
+
+    def test_audit_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}")
+
+
+if __name__ == "__main__":
+    unittest.main()

backend-java/scripts/tx_audit.py

@@ -0,0 +1,220 @@
+"""task-124 @Transactional 方法审计清单工具。
+
+对 backend-java modules 下的 Java 源码做机械化扫描：定位全部方法级
+@Transactional 注解，按方法体内容分类事务内代码段——必须事务内（落库写/状态/锁）
+与可移出（纯计算/DTO 组装/日志/临时文件清理），标记 Python 回调相关方法，
+按可移出收益排序，产出审计清单供 plan 07 的任务 125-131 事务收缩参考。
+本工具只读，不改任何代码。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from n1_scan import _match_span, _strip_comments
+
+MODULES_ROOT = (
+    Path(__file__).resolve().parent.parent / "src/main/java/com/nanri/aiimage/modules"
+)
+
+TX_RE = re.compile(r"@Transactional\b")
+METHOD_RE = re.compile(
+    r"\s*(?:(?:public|protected|private)\s+)?"
+    r"(?:[\w<>,.?\[\] ]+[\s])?(\w+)\s*\("
+)
+PYTHON_FACING_RE = re.compile(r"(?i)(result|submit|upload|chunk|done|ack|report)")
+
+WRITE_RE = re.compile(
+    r"\.(insert|update|deleteById|deleteBatchIds|removeById|removeByIds|remove\b|"
+    r"save|saveBatch|saveOrUpdate|updateById|insertOrUpdate|updateBatchById)\s*\("
+)
+LOCK_RE = re.compile(r"acquireTaskLock|\.tryLock\(|LockHandle|taskLockHandle")
+CLEANUP_RE = re.compile(
+    r"Files\.(delete|deleteIfExists|move)|deleteIfExists\(|"
+    r"tempDir|tempFile|temp-dir|cleanupTemp|deleteTemp|临时文件"
+)
+COMPUTE_RE = re.compile(
+    r"\.stream\(\)|\.map\(|\.collect\(|\.filter\(|\.reduce\(|\.sorted\(|"
+    r"Collectors\.|computeIfAbsent|\.distinct\(|\.flatMap\(|\.peek\("
+)
+ASSEMBLY_RE = re.compile(
+    r"build\w*(Vo|VO|Dto|DTO)|toVo\(|toEntity\(|convert\w*\(|assemble\w*\(|"
+    r"new \w+(Vo|VO|Dto|DTO)\b"
+)
+LOG_RE = re.compile(r"log\.(info|warn|debug|error|trace)\s*\(")
+
+
+def _match_body_span(text: str, open_pos: int) -> int | None:
+    """从 { 出发，返回匹配的 } 偏移（含）。
+
+    圆括号深度同步跟踪：lambda/方法调用内的 { } 不计入方法体层级，
+    方法体的闭合 } 总是在圆括号外层（paren == 0）首次归零时命中。
+    """
+    depth = 0
+    paren = 0
+    for i in range(open_pos, len(text)):
+        c = text[i]
+        if c == "(":
+            paren += 1
+        elif c == ")":
+            paren -= 1
+        elif c == "{" and paren == 0:
+            depth += 1
+        elif c == "}" and paren == 0:
+            depth -= 1
+            if depth == 0:
+                return i
+    return None
+
+
+def _count_hits(pattern: re.Pattern[str], text: str) -> int:
+    return len(pattern.findall(text))
+
+
+def scan_text(text: str, filename: str = "fixture.java") -> list[dict]:
+    """扫描单份 Java 源码，返回 @Transactional 方法审计条目（按收益降序）。"""
+    stripped = _strip_comments(text)
+    findings: list[dict] = []
+    pos = 0
+    while True:
+        tx_match = TX_RE.search(stripped, pos)
+        if not tx_match:
+            break
+        anno_end = tx_match.end()
+        if stripped[anno_end : anno_end + 1] == "(":
+            close = _match_span(stripped, anno_end)
+            if close is None:
+                pos = tx_match.end()
+                continue
+            anno_end = close + 1
+        method_match = METHOD_RE.search(stripped, anno_end)
+        if not method_match:
+            pos = tx_match.end()
+            continue
+        method_name = method_match.group(1)
+        paren_pos = method_match.end() - 1
+        close_paren = _match_span(stripped, paren_pos)
+        if close_paren is None:
+            pos = method_match.end()
+            continue
+        body_start = close_paren + 1
+        while body_start < len(stripped) and stripped[body_start].isspace():
+            body_start += 1
+        if body_start >= len(stripped) or stripped[body_start] != "{":
+            # 抽象方法/接口声明无方法体，跳过
+            pos = method_match.end()
+            continue
+        body_end = _match_body_span(stripped, body_start)
+        if body_end is None:
+            pos = method_match.end()
+            continue
+        body = stripped[body_start + 1 : body_end]
+
+        must_stay: list[str] = []
+        counts: dict[str, int] = {}
+        if _count_hits(WRITE_RE, body) > 0:
+            must_stay.append("write")
+            counts["write"] = _count_hits(WRITE_RE, body)
+        if _count_hits(LOCK_RE, body) > 0:
+            must_stay.append("lock")
+            counts["lock"] = _count_hits(LOCK_RE, body)
+
+        movable: list[str] = []
+        for key, pattern in (
+            ("compute", COMPUTE_RE),
+            ("assembly", ASSEMBLY_RE),
+            ("cleanup", CLEANUP_RE),
+            ("log", LOG_RE),
+        ):
+            hits = _count_hits(pattern, body)
+            counts[key] = hits
+            if hits > 0:
+                movable.append(key)
+
+        priority = sum(
+            counts.get(key, 0) for key in ("compute", "assembly", "cleanup", "log")
+        )
+        findings.append(
+            {
+                "file": filename,
+                "line": _line_of(text, tx_match.start()),
+                "method": method_name,
+                "signature": " ".join(
+                    stripped[method_match.start() : close_paren].split()
+                )[:100],
+                "class_level": False,
+                "python_facing": bool(PYTHON_FACING_RE.search(method_name)),
+                "must_stay": must_stay,
+                "movable": movable,
+                "counts": counts,
+                "priority": priority,
+            }
+        )
+        pos = body_end + 1
+
+    findings.sort(key=lambda f: (-f["priority"], f["line"]))
+    return findings
+
+
+def _line_of(text: str, offset: int) -> int:
+    return text.count("\n", 0, offset) + 1
+
+
+@dataclass
+class Report:
+    scanned_files: int = 0
+    modules: list[str] = field(default_factory=list)
+    findings: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "scanned_files": self.scanned_files,
+            "modules": self.modules,
+            "findings": self.findings,
+        }
+
+
+def scan_modules(root: Path) -> Report:
+    """扫描 modules 根目录下全部 Java 文件，产出 @Transactional 审计报告。"""
+    report = Report()
+    module_set: set[str] = set()
+    for java_file in sorted(root.rglob("*.java")):
+        report.scanned_files += 1
+        rel = java_file.relative_to(root)
+        module_set.add(rel.parts[0])
+        for finding in scan_text(java_file.read_text(encoding="utf-8"), str(rel)):
+            finding["module"] = rel.parts[0]
+            report.findings.append(finding)
+    report.findings.sort(key=lambda f: (-f["priority"], f["file"], f["line"]))
+    report.modules = sorted(module_set)
+    return report
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="@Transactional 方法审计")
+    parser.add_argument("--json", help="输出 JSON 报告路径（默认 stdout）")
+    args = parser.parse_args()
+
+    report = scan_modules(MODULES_ROOT)
+    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"scanned {report.scanned_files} files, "
+        f"{len(report.findings)} @Transactional methods "
+        f"across {len(report.modules)} modules",
+        file=sys.stderr,
+    )
+
+
+if __name__ == "__main__":
+    main()