refactor(trace): enforce run-only diagnosis model

2026-07-20 14:11:34 +08:00
parent 190013c901
commit 4b9cf7c5cc
63 changed files with 583 additions and 909 deletions
@@ -12,7 +12,7 @@
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---|---|
 | `id` | BIGINT | 是 | 自增主键 |
-| `session_id` | VARCHAR(64) | 是 | 所属会话目录 ID，保留用于粗粒度过滤和兼容 |
+| `session_id` | VARCHAR(64) | 是 | 所属会话目录 ID，作为粗粒度冗余筛选字段 |
 | `run_id` | VARCHAR(64) | 否 | 所属 `diagnosis_run.run_id`；新执行应写入 |
 | `step_index` | INT | 是 | 步骤序号，从 0 开始 |
 | `agent_name` | VARCHAR(32) | 是 | Agent 名称，例如 planner、executor、verifier、composer |
@@ -28,14 +28,14 @@

 | 索引 | 字段 | 用途 |
 |---|---|---|
-| `idx_session_step` | `session_id, step_index` | 历史兼容和粗粒度排查 |
+| `idx_session_step` | `session_id, step_index` | 粗粒度排查 |
 | `idx_agent_step_run_step` | `run_id, step_index` | 按运行筛选步骤并辅助顺序查询 |
 | `idx_agent_name` | `agent_name` | 按 Agent 类型筛选 |

 ## 关系

 - `agent_step.run_id` 逻辑关联 `diagnosis_run.run_id`。
- `agent_step.session_id` 保留为 `chat_session.session_id` 的冗余关联，便于粗粒度过滤和兼容查询。
+- `agent_step.session_id` 是 `chat_session.session_id` 的冗余关联，只用于粗粒度过滤。
 - `tool_invocation.step_id` 可关联 `agent_step.id`，但当前允许为空且不强制外键。

 ## 注意点
@@ -1,6 +1,6 @@
 # MVP 数据表索引

-**更新日期**：2026-07-10
+**更新日期**：2026-07-20
 **状态**：当前表文档入口

 本目录保存当前 MVP 使用的数据表说明。详细结构以 Flyway migration 和实体类为准；本目录用于面试讲解、排查索引和快速理解数据流。
@@ -16,13 +16,13 @@
 | `api_document` | 知识库文档元数据，和向量库 chunk 通过 `doc_id` 关联 | [文档元数据表-api_document.md](文档元数据表-api_document.md) |
 | `knowledge_domain` | 知识域元数据，支撑 RAG domain hint 和检索策略 | [知识域表-knowledge_domain.md](知识域表-knowledge_domain.md) |
 | `case_library` | 用户反馈沉淀出的高质量诊断案例 | [案例库表-case_library.md](案例库表-case_library.md) |
-| `diagnosis_session` | 历史兼容和回滚表，新执行写入不再依赖它 | [诊断会话表-diagnosis_session.md](诊断会话表-diagnosis_session.md) |

 ## 已归档表

 | 表 | 归档原因 | 文档 |
 |---|---|---|
 | `diagnosis_record` | 已由 `V007` 删除，历史上被 `diagnosis_session + agent_step + tool_invocation` 替代；当前新模型是 `chat_session + diagnosis_run + trace detail` | [archive/2026-07-09-doc-cleanup/旧诊断记录表-diagnosis_record.md](archive/2026-07-09-doc-cleanup/旧诊断记录表-diagnosis_record.md) |
+| `diagnosis_session` | 旧会话级诊断模型，当前 Java 运行时不再映射、读取或写入 | [../archive/2026-07-20-doc-cleanup/tables/诊断会话表-diagnosis_session.md](../archive/2026-07-20-doc-cleanup/tables/诊断会话表-diagnosis_session.md) |

 ## 核心关系

@@ -33,9 +33,6 @@ chat_session.session_id
      -> tool_invocation.run_id
      -> case_library.diagnosis_id (new AUTO cases use run_id)

-diagnosis_session.session_id
-  -> historical compatibility / rollback only
-
 api_document.doc_id
  -> vector chunk metadata.docId / doc_id

@@ -1,6 +1,6 @@
 # diagnosis_record - 旧诊断记录表

-> 归档说明：`diagnosis_record` 已在 `V007__drop_diagnosis_record.sql` 中删除，当前主模型是 `diagnosis_session + agent_step + tool_invocation`。本文只用于追溯早期设计。
+> 归档说明：`diagnosis_record` 已在 `V007__drop_diagnosis_record.sql` 中删除，该阶段由 `diagnosis_session + agent_step + tool_invocation` 替代。本文只用于追溯早期设计，不代表当前 Run-only v2 模型。

 ## 表定位

@@ -12,7 +12,7 @@
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---|---|
 | `id` | BIGINT | 是 | 自增主键 |
-| `session_id` | VARCHAR(64) | 是 | 所属会话目录 ID，保留用于粗粒度过滤和兼容 |
+| `session_id` | VARCHAR(64) | 是 | 所属会话目录 ID，作为粗粒度冗余筛选字段 |
 | `run_id` | VARCHAR(64) | 否 | 所属 `diagnosis_run.run_id`；新执行应写入 |
 | `step_id` | BIGINT | 否 | 可关联 `agent_step.id` |
 | `tool_name` | VARCHAR(64) | 是 | 工具名称，例如 `lookup_knowledge`、日志查询、指标查询 |
@@ -35,7 +35,7 @@

 | 索引 | 字段 | 用途 |
 |---|---|---|
-| `idx_session_id` | `session_id` | 历史兼容和粗粒度排查 |
+| `idx_session_id` | `session_id` | 粗粒度排查 |
 | `idx_tool_invocation_run_id` | `run_id, id` | Trace、Verifier、评测按运行查询工具调用 |
 | `idx_tool_name` | `tool_name` | 按工具类型排查 |
 | `idx_retrieval_layer` | `retrieval_layer` | 观察 RAG L0/L1 行为 |
@@ -43,7 +43,7 @@
 ## 关系

 - `tool_invocation.run_id` 逻辑关联 `diagnosis_run.run_id`。
- `tool_invocation.session_id` 保留为 `chat_session.session_id` 的冗余关联，便于粗粒度过滤和兼容查询。
+- `tool_invocation.session_id` 是 `chat_session.session_id` 的冗余关联，只用于粗粒度过滤。
 - `tool_invocation.step_id` 可关联 `agent_step.id`，但当前不强制。

 ## 关键 JSON
@@ -13,7 +13,7 @@
 |---|---|---|---|
 | `id` | BIGINT | 是 | 自增主键 |
 | `case_id` | VARCHAR(64) | 是 | 案例唯一 ID |
-| `diagnosis_id` | VARCHAR(64) | 否 | 关联诊断来源；新自动生成时存 `diagnosis_run.run_id`，历史数据可能是 `diagnosis_session.session_id` |
+| `diagnosis_id` | VARCHAR(64) | 否 | 关联诊断来源；自动生成时存 `diagnosis_run.run_id` |
 | `source_type` | VARCHAR(16) | 否 | 来源类型：`AUTO` 或 `MANUAL` |
 | `fault_category` | VARCHAR(32) | 否 | 故障类别，实体侧使用 `FaultCategory` |
 | `fault_source` | VARCHAR(128) | 否 | 故障源，例如服务、系统或省份 |
@@ -35,17 +35,17 @@
 | `idx_error_code` | `error_code` | 按错误码精确匹配 |
 | `idx_fault_source` | `fault_source` | 按故障源筛选 |
 | `idx_fault_target` | `fault_target(100)` | 按故障目标筛选 |
-| `idx_diagnosis_id` | `diagnosis_id` | 追溯来源运行或历史会话 |
+| `idx_diagnosis_id` | `diagnosis_id` | 追溯来源运行 |
 | `idx_reference_count` | `reference_count` | 推荐排序 |
 | `idx_created_at` | `created_at` | 时间排序 |

 ## 关系

- `case_library.diagnosis_id` 是过渡字段：新自动案例逻辑关联 `diagnosis_run.run_id`，历史自动案例可能仍是 `diagnosis_session.session_id`。
+- `case_library.diagnosis_id` 逻辑关联 `diagnosis_run.run_id`。
 - 人工录入案例可以不填写 `diagnosis_id`。

 ## 注意点

 - 旧文档里提到的 `diagnosis_record` 已被 `V007` 删除，不再是当前主模型。
- 查询新自动案例时优先按 `run_id` 追溯；遇到旧值时再按历史 `session_id` 解释。
+- 自动案例只按 `run_id` 追溯，不执行会话级兼容查询。
 - 当前自动沉淀仍比较粗：`root_cause` 和 `solution` 都可能来自完整 answer。后续可从结构化结论中拆分根因、证据和修复建议。
@@ -1,48 +0,0 @@
-# 诊断会话表：diagnosis_session
-
-**状态**：历史兼容和回滚表
-**来源**：`V005__create_session_storage.sql`、`V008__add_answer_to_diagnosis_session.sql`、`DiagnosisSession`
-
-## 定位
-
-`diagnosis_session` 是旧版 session 级诊断主记录。`V011` 之后，新 Chat/AIOps 执行的运行态写入已经切到 `chat_session + diagnosis_run`；本表保留用于历史兼容、迁移回填和回滚比较。
-
-## 字段
-
-| 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
-| `id` | BIGINT | 是 | 自增主键 |
-| `session_id` | VARCHAR(64) | 是 | 旧版会话唯一 ID，也是兼容 run 回填来源 |
-| `query` | TEXT | 是 | 用户原始问题或 AIOps 输入摘要 |
-| `status` | VARCHAR(16) | 否 | `PENDING`、`RUNNING`、`SUCCESS`、`FAILED` |
-| `agent_flow` | VARCHAR(32) | 否 | `CHAT` 或 `AI_OPS` |
-| `total_duration_ms` | INT | 否 | 总耗时，单位毫秒 |
-| `total_token_count` | INT | 否 | 总 Token 消耗 |
-| `step_count` | INT | 否 | Agent 步骤数 |
-| `tool_call_count` | INT | 否 | 工具调用次数 |
-| `answer` | LONGTEXT | 否 | 返回给用户的最终答案 |
-| `self_evaluation` | JSON | 否 | rule、verifier、aiops 等自评估结果容器 |
-| `feedback` | VARCHAR(16) | 否 | 用户反馈：`useful`、`not_useful` 或空 |
-| `created_at` | DATETIME | 是 | 创建时间 |
-| `updated_at` | DATETIME | 是 | 更新时间 |
-
-## 索引
-
-| 索引 | 字段 | 用途 |
-|---|---|---|
-| `session_id` unique | `session_id` | 会话唯一约束 |
-| `idx_created_at` | `created_at` | 按时间查询 |
-| `idx_status` | `status` | 按状态筛选 |
-| `idx_agent_flow` | `agent_flow` | 区分 Chat / AIOps |
-
-## 关系
-
- 迁移时每条 `diagnosis_session` 会生成一条兼容 `diagnosis_run`。
- 历史 `agent_step.run_id` 和 `tool_invocation.run_id` 会尽量从兼容 `diagnosis_run` 回填。
- 历史自动案例可能仍使用 `case_library.diagnosis_id = diagnosis_session.session_id`。
-
-## 注意点
-
- 新执行不应再把 query、answer、self_evaluation、feedback、统计计数写入本表。
- 新 Trace 聚合优先读取 `diagnosis_run + agent_step.run_id + tool_invocation.run_id`。
- 历史 fallback 仅在没有 run-backed 数据时读取本表。
@@ -5,7 +5,7 @@

 ## 定位

-`diagnosis_run` 表示一次可回放的 Chat 或 AIOps 诊断执行。`run_id` 是运行级边界，Trace、反馈、自评估、案例沉淀和统计都应优先按 `run_id` 绑定。
+`diagnosis_run` 表示一次可回放的 Chat 或 AIOps 诊断执行。`run_id` 是运行级边界，Trace、反馈、自评估、案例沉淀和统计都必须按 `run_id` 绑定。

 ## 字段

@@ -32,7 +32,7 @@
 | 索引 | 字段 | 用途 |
 |---|---|---|
 | `run_id` unique | `run_id` | 运行唯一约束 |
-| `idx_diagnosis_run_session_created` | `session_id, created_at, id` | session 下最新运行解析和运行列表 |
+| `idx_diagnosis_run_session_created` | `session_id, created_at, id` | session 下运行列表和排序 |
 | `idx_diagnosis_run_session_run` | `session_id, run_id` | exact trace / feedback ownership 校验 |
 | `idx_diagnosis_run_status` | `status` | 状态筛选 |
 | `idx_diagnosis_run_agent_flow` | `agent_flow` | 区分 Chat / AIOps |
@@ -46,6 +46,6 @@

 ## 注意点

- `GET /api/diagnosis/{sessionId}/trace` 未带 `runId` 时只为兼容解析 latest run；新 demo 和新客户端应传 `runId`。
- latest run 排序使用 `created_at DESC, id DESC`，避免 feedback 或自评估更新 `updated_at` 后改变回放目标。
- 历史 `diagnosis_session` 会被迁移成兼容 run，但旧混合数据不能被还原成真实多轮边界。
+- Trace 查询必须同时提供 `sessionId + runId`，并验证 Run 归属；缺少 `runId` 时直接拒绝。
+- Run 列表按 `created_at DESC, id DESC` 排序，feedback 或自评估更新 `updated_at` 不改变运行顺序。
+- 当前 Java 运行时只使用 `chat_session + diagnosis_run`，不读取或写入旧会话级诊断表。