feat: Phase 4 — Experiment 自动归档 + 异步 Job（状态机 / SSE / 一键复跑）

- 数据表：job / experiment（spec/result JSON 存档、code_version），Alembic 迁移 53113c80257f - Job：queued→running→(success|failed) 状态机，BackgroundTasks 本地执行 + 失败兜底标记；结果与 Experiment 关联 - Experiment：每次研究成功自动归档（含 git commit 与收益摘要），支持一键复跑（同 spec 重建 Job） - API：POST /api/jobs、GET /api/jobs/{id}（内嵌结果）、SSE /api/jobs/{id}/events、/api/experiments 列表/详情/rerun - 前端：新增「实验」页（列表 / 详情 / 复跑 + Job 轮询）；导航更新 - 端到端验证：真实 20 股 job 提交→后台执行→success→EXP 归档（-12.41%）；executor 成功/失败路径单测 - 测试 73 passed（新增 5 项 Job/Experiment）/ ruff clean / 前端 tsc + build 通过
2026-09-06 17:18:46 +08:00
parent 92627f5b6b
commit 0ea229d766
14 changed files with 938 additions and 2 deletions
@@ -0,0 +1,146 @@
+"""Job 执行编排与 Experiment 归档（Phase 4）。
+
+execute_job 在后台运行：状态机 queued→running→(success|failed)，
+成功时自动把 spec/result 存为 Experiment（含代码版本），实现「研究可复现」（AGENT.md §21）。
+独立 Session 生命周期（不依赖请求 scope），可被 FastAPI BackgroundTasks 或测试直接调用。
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import uuid
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+
+from app.domain.entities.research import (
+    BacktestResult,
+    ExperimentRecord,
+    FactorTestReport,
+    JobStatus,
+    ResearchSpec,
+)
+from app.quant.service import ResearchService
+
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+
+
+def new_id(prefix: str) -> str:
+    return f"{prefix}-{uuid.uuid4().hex[:8].upper()}"
+
+
+def _git_short_rev() -> str | None:
+    try:
+        out = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            cwd=PROJECT_ROOT,
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+        return out.stdout.strip() or None
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _summary_text(kind: str, result: BacktestResult | FactorTestReport) -> str | None:
+    if kind == "backtest" and isinstance(result, BacktestResult):
+        s = result.summary
+        return f"总收益 {s.total_return_pct:.2f}% · 年化 {s.annual_return_pct:.2f}% · 回撤 {s.max_drawdown_pct:.2f}%"
+    if isinstance(result, FactorTestReport):
+        return f"IC {result.ic_mean:.4f} · RankIC {result.rank_ic_mean:.4f} · 样本 {result.sample_days} 日"
+    return None
+
+
+def _execute_inner(
+    job_id: str,
+    *,
+    session_factory: Callable,
+    job_repo_factory: Callable,
+    experiment_repo_factory: Callable,
+    stock_repo_factory: Callable,
+    daily_repo_factory: Callable,
+    engine,
+) -> None:
+    with session_factory() as session:
+        job_repo = job_repo_factory(session)
+        experiment_repo = experiment_repo_factory(session)
+        job = job_repo.get(job_id)
+        if job is None:
+            return
+        job.status = JobStatus.RUNNING
+        job.started_at = datetime.now()
+        job_repo.update(job)
+        session.commit()
+        try:
+            spec = ResearchSpec.model_validate_json(job.spec_json)
+            service = ResearchService(
+                stock_repo_factory(session), daily_repo_factory(session), engine
+            )
+            if spec.type == "backtest":
+                result = service.run_backtest(spec)
+            else:
+                result = service.run_factor_test(spec)
+
+            result_json = json.dumps(result.model_dump(mode="json"), ensure_ascii=False)
+            experiment = ExperimentRecord(
+                id=new_id("EXP"),
+                kind=spec.type,
+                spec_json=job.spec_json,
+                result_json=result_json,
+                summary_text=_summary_text(spec.type, result),
+                code_version=_git_short_rev(),
+                job_id=job.id,
+                created_at=datetime.now(),
+            )
+            experiment_repo.save(experiment)
+
+            job.result_json = result_json
+            job.experiment_id = experiment.id
+            job.status = JobStatus.SUCCESS
+            job.error = None
+        except Exception as exc:  # noqa: BLE001 —— 统一记为 failed 供前端展示
+            job.status = JobStatus.FAILED
+            job.error = f"{type(exc).__name__}: {exc}"
+        finally:
+            job.finished_at = datetime.now()
+            job_repo.update(job)
+            session.commit()
+
+
+def execute_job(
+    job_id: str,
+    *,
+    session_factory: Callable,
+    job_repo_factory: Callable,
+    experiment_repo_factory: Callable,
+    stock_repo_factory: Callable,
+    daily_repo_factory: Callable,
+    engine,
+) -> None:
+    """入口包装：任何未预期异常都将 Job 标记 failed（防止卡在 queued/running）。"""
+    try:
+        _execute_inner(
+            job_id,
+            session_factory=session_factory,
+            job_repo_factory=job_repo_factory,
+            experiment_repo_factory=experiment_repo_factory,
+            stock_repo_factory=stock_repo_factory,
+            daily_repo_factory=daily_repo_factory,
+            engine=engine,
+        )
+    except Exception as exc:  # noqa: BLE001
+        try:
+            with session_factory() as session:
+                repo = job_repo_factory(session)
+                job = repo.get(job_id)
+                if job is not None:
+                    job.status = JobStatus.FAILED
+                    job.error = f"内部错误: {type(exc).__name__}: {exc}"
+                    job.finished_at = datetime.now()
+                    repo.update(job)
+                    session.commit()
+        except Exception:  # noqa: BLE001
+            pass