feat: add Super Alpha research, management and MCP workflows

backend/app/mcp_api/server.py

@@ -18,9 +18,18 @@ from ..models import MCPAudit, now
 from ..research.serialization import encode_snapshot
 from ..research_access import contracts as c
 from ..research_access.service import ResearchAccess, ResearchError
+from ..superalpha import contracts as sc
 
 # Name, schema, business method, required scope, description. No generic arbitrary HTTP tool.
 TOOLS = {
+    "search_superalpha_plans": (sc.PlanSearch, "super_plans", "research:read", "分页查找 Super Alpha 研究方案。"),
+    "get_superalpha_plan": (sc.PlanReference, "super_plan", "research:read", "读取指定方案版本或固定构造记录；不发起回测。"),
+    "save_superalpha_plan": (sc.PlanSave, "save_super_plan", "research:write", "保存调用方构造的 Selection/Combo 参数方案；更新须携带版本，支持幂等。不调用模型或回测。"),
+    "preview_superalpha_selection": (sc.SelectionPreview, "preview_super_selection", "research:refresh", "主动预览展开后的 Selection；异步返回 job_id，用 get_refresh_job 查进度、get_superalpha_selection 查组件。预览不是实际回测组件。"),
+    "get_superalpha_selection": (sc.SelectionReference, "super_selection", "research:read", "分页读取组件预览及完整性、时间、警告；缺失不自动刷新。"),
+    "build_superalpha_candidates": (sc.BuildCandidates, "build_super_candidates", "research:write", "按方案版本或内联方案进行全量展开/固定种子采样；保存固定候选及来源，不执行回测。将 candidates 与 submit_source 交给 submit_backtests；超过100项按分页读取固定记录。"),
+    "search_superalphas": (sc.SuperAlphaSearch, "super_alphas", "research:read", "分页查询本地已导入的 SUPER 成果，固定 SUPER 范围；不自动同步。"),
+    "get_superalpha": (sc.AlphaReference, "super_alpha", "research:read", "读取已导入 SUPER 的 Selection/Combo、指标、组件证据、Description 和研究来源。"),
     "get_pyramid_distribution": (c.PyramidQuery, "pyramid_distribution", "research:read", "实时读取指定 region（如 USA、GLB）和 delay（0/1）的个人 Pyramid Alpha 分布；必传 current_date（YYYY-MM-DD），自动按自然年四季度取完整起止日（如2026-09-13对应2026-07-01至2026-09-30），传给平台 startDate/endDate，不使用默认周期。按用户约定 alphaCount>=3 为 lit（已点亮），1–2 为 in_progress，0 为 unlit；每项含 category、alpha_count、距3条的 remaining。复用平台认证，未连接时先调用 authenticate_worldquant；缺失数据不当作0。不回测、不提交。"),
     "search_data_preparations": (c.PreparationSearch, "preparations", "research:read", "分页查询数据准备集合，返回固定范围、字段数及版本。研究可使用多个集合，各集合范围独立。"),
     "get_data_preparation": (c.PreparationRead, "preparation", "research:read", "按集合 ID 与版本分页预览字段、类型、描述和数据集归属。提交回测时携带 preparation_refs，由服务端核对版本并固定独立输入快照；空集合不能用于研究。"),
@@ -37,7 +46,7 @@ TOOLS = {
     "check_self_correlation": (c.SelfCorrelationCheck, "check_self_correlation", "research:refresh", "对 1–100 个已导入 Alpha 发起本地自相关检查，返回 job_id。与本地同地区已提交 Alpha 比较，排除自身；优先用缓存，缺失 PnL 自动补取。需先同步已提交 Alpha；不调用平台提交检查。用 get_refresh_job 查进度、get_self_correlation 读结果。"),
     "get_self_correlation": (c.SelfCorrelationReference, "self_correlation", "research:read", "读取指定 Alpha 最新的本地自相关缓存，包括最大相关系数、样本覆盖与 stale 状态；无缓存不自动检查，结果不等同于平台提交资格。"),
     "search_backtests": (c.History, "history", "research:read", "分页查历史候选与固定设置；candidates 按完整输入精确匹配，不推断数学等价。"),
-    "submit_backtests": (c.Submit, "submit", "backtests:execute", "执行用户已授权的固定批次，自动留痕并立即返回运行 ID。可携带 preparation_refs 选择集合，版本变化须重新读取；每项必须完整设置；重复默认拒绝，rerun 明确重跑。不需要研究资产。"),
+    "submit_backtests": (c.Submit, "submit", "backtests:execute", "执行用户已授权的 REGULAR/SUPER 固定批次，自动留痕并立即返回运行 ID；SUPER 使用 selection/combo 和专属设置，逐条模拟。可携带 preparation_refs 选择集合，版本变化须重新读取；每项必须完整设置；重复默认拒绝，rerun 明确重跑。不需要研究资产。"),
     "get_backtest": (c.RunReference, "run", "research:read", "读取真实运行进度、提交数量和可选增量事件；受理不等于成功。"),
     "get_backtest_results": (c.Results, "results", "research:read", "分页读取固定快照指标、Alpha 非通过检查及三层状态；REGULAR_SUBMISSION 单列 submission_limits，不计入 Alpha 失败统计。缺失指标不补零。"),
     "get_backtest_artifact": (c.Artifact, "artifact", "research:read", "分页读取候选脱敏快照的顶层键值或独立采集的 PnL；缺缓存不自动刷新。"),
@@ -73,8 +82,8 @@ class MCPResearchServer:
         return types.ListToolsResult(tools=[types.Tool(name=name, description=description,
             inputSchema=schema.model_json_schema(), annotations=types.ToolAnnotations(
                 readOnlyHint=scope == "research:read", destructiveHint=method == "control",
-                idempotentHint=method in {"submit", "control", "create_template"} or scope == "research:read",
-                openWorldHint=method in {"refresh", "submit", "metadata", "check_self_correlation", "check_submission", "authenticate", "pyramid_distribution"}))
+                idempotentHint=method in {"submit", "control", "create_template", "save_super_plan", "build_super_candidates"} or scope == "research:read",
+                openWorldHint=method in {"refresh", "submit", "metadata", "check_self_correlation", "check_submission", "authenticate", "pyramid_distribution", "preview_super_selection"}))
             for name, (schema, method, scope, description) in TOOLS.items()
             if scope in principal.scopes and "research:read" in principal.scopes])
 
@@ -127,7 +136,7 @@ class MCPResearchServer:
                         data = {"error": ResearchError(code, "研究操作失败；可使用原幂等键重试或查询历史", retryable=True).data}
                     db.add(MCPAudit(id=str(uuid4()), token_id=principal.token_id, tool=name,
                         request_id=fingerprint({"request_id": request_id}), input_digest=digest,
-                        business_id=data.get("backtest_run_id", data.get("job_id", data.get("template_id"))),
+                        business_id=data.get("backtest_run_id", data.get("job_id", data.get("template_id", data.get("id")))),
                         result_code=code, elapsed_ms=int((time.monotonic()-started)*1000)))
                 if not error:
                     if access.wake == "backtests":