refactor(trace): enforce run-only diagnosis model

mvp/architecture/interview-one-pager.md

@@ -1,11 +1,12 @@
 # 面试一页式架构讲解
 
+**更新日期**：2026-07-20
 **用途**：面试现场 2-5 分钟讲清项目  
 **适合场景**：开场介绍、架构追问、Demo 前铺垫
 
 ## 1. 一句话
 
-SuperBizAgent 是一个面向企业故障诊断的可追踪 Agent 系统：它把用户问题或 AIOps 告警转换成 Planner、Executor、Gatekeeper、Verifier、Composer 的诊断链路，`sessionId` 保留多轮上下文，`runId` 精确绑定一次诊断运行；所有工具证据、模型步骤、最终答案、自评估和用户反馈都能按 `sessionId + runId` 回放。
+SuperBizAgent 是一个面向企业故障诊断的可追踪 Agent 系统：复杂 Chat 通过 bounded StateGraph 编排 Planner、Executor、Gatekeeper、Verified Input、Verifier、Composer 和安全 Fallback，`sessionId` 保留多轮上下文，`runId` 精确绑定一次诊断运行；工具证据、模型步骤、Graph 路由、自评估、最终答案和用户反馈都能按 `sessionId + runId` 回放。
 
 ## 2. 一张图
 
@@ -16,7 +17,7 @@ flowchart TB
     API --> Chat["ChatService"]
     API --> AiOps["AiOpsService"]
 
-    Chat --> ChatFlow["Chat: Planner -> Executor -> Gatekeeper -> Verifier -> Composer"]
+    Chat --> ChatFlow["Chat StateGraph: Planner -> Executor -> Gatekeeper -> Verified Input -> Verifier -> Composer/Fallback"]
     AiOps --> AiOpsFlow["AIOps: Supervisor -> Planner / Executor"]
 
     ChatFlow --> Tools["Evidence Tools"]
@@ -39,10 +40,14 @@ flowchart TB
     Trace --> Step["agent_step"]
     Trace --> Invocation["tool_invocation"]
 
-    Invocation --> Verifier["Verifier / Rule Evaluation"]
+    Invocation --> Gate["Gatekeeper / Rule Evaluation"]
+    Gate --> Projection["Verified Input"]
+    Projection --> Verifier["Verifier"]
     Verifier --> SelfEval["self_evaluation"]
 
+    Run --> RouteTrace["orchestration_trace"]
     Run --> TraceAPI["GET /api/diagnosis/{sessionId}/trace?runId=..."]
+    RouteTrace --> TraceAPI
     Step --> TraceAPI
     Invocation --> TraceAPI
     SelfEval --> TraceAPI
@@ -56,21 +61,21 @@ flowchart TB
 ```text
 这个项目不是把问题直接丢给大模型，而是把诊断拆成可审计的执行链路。
 
-Chat 复杂问题走 Planner -> Executor -> Gatekeeper -> Verifier -> Composer：
-Planner 负责拆解，Executor 只负责调用知识库、日志和指标工具并提炼带证据引用的微观事实；Gatekeeper 用代码核对 invocation、raw_path 和 excerpt 是否真实；Verifier 判断这些事实能否由已验真的证据推出；Composer 只把允许表达的结论写成最终答案。
+Chat 复杂问题走 bounded StateGraph：
+Planner 负责拆解，Executor 调用知识库、日志和指标工具并提炼带证据引用的微观事实；Gatekeeper 用代码核对 invocation、raw_path 和 excerpt 是否真实；Verified Input 只投影通过的 binding；Verifier 判断这些事实能否由已验真的证据推出；Composer 只把允许表达的结论写成最终答案，不可恢复分支由 Fallback 生成安全答复。
 
 AIOps 告警入口走 Supervisor 调度 Planner/Executor：
 如果请求里有 alert payload，系统会进入 PAYLOAD_TARGETED 模式，报告必须聚焦这个告警，而不是被当前环境中的其他活跃告警带偏。
 
-会话元数据会落到 chat_session，每次诊断运行会落到 diagnosis_run，步骤和工具明细通过 run_id 关联。
-所以我可以用 sessionId + runId 精确回放：模型怎么规划、调了哪些工具、工具返回什么、Gatekeeper 怎么验真、Verifier 怎么判定、Composer 最后怎么表达、用户最后是否反馈有用。
+会话元数据会落到 chat_session，每次诊断运行会落到 diagnosis_run，步骤和工具明细通过 run_id 关联；证据质量写入 self_evaluation，Graph 路由独立写入 orchestration_trace。
+所以我可以用 sessionId + runId 精确回放：模型怎么规划、调了哪些工具、Gatekeeper 怎么验真、Graph 为什么重试或降级、Verifier 怎么判定、Composer/Fallback 如何结束、用户最后是否反馈有用。
 ```
 
 ## 4. 五个亮点
 
 | 亮点 | 怎么讲 |
 |---|---|
-| 可追踪 Agent | 每次诊断都有 `runId`，Trace API 可以回放 run、step、tool；同一 `sessionId` 可有多次独立 run |
+| 可追踪 StateGraph | 每次诊断都有 `runId`，Trace API 可以回放 run、step、tool 和 `run.orchestrationTrace`；同一 `sessionId` 可有多次独立 run |
 | 显式工具证据链 | `lookup_knowledge`、日志、指标都记录到 `tool_invocation` |
 | RAG 工程化 | L0 降级为 hint，Spring AI VectorStore 做主检索，SDK fallback 保底 |
 | 质量门禁 | Chat Gatekeeper 验引用、Verifier 判可推导、Composer 控表达，AIOps rule evaluation 控制告警聚焦 |