# 数据模型总览 **更新日期**：2026-07-08 **状态**：当前可运行架构 ## 1. 定位 本文从架构角度说明当前 MVP 的核心数据模型。详细字段仍以 Flyway migration 和 `mvp/tables/` 为准。 核心数据分三组： - 诊断 Trace：`diagnosis_session`、`agent_step`、`tool_invocation` - 知识库：`api_document`、`knowledge_domain`、Milvus/Zilliz metadata - 反馈沉淀：`case_library` ## 2. 总体关系 ```mermaid erDiagram diagnosis_session ||--o{ agent_step : has diagnosis_session ||--o{ tool_invocation : has diagnosis_session ||--o| case_library : creates_when_useful api_document ||--o{ milvus_chunk : indexed_as knowledge_domain ||--o{ api_document : groups diagnosis_session { bigint id varchar session_id text query varchar status varchar agent_flow longtext answer json self_evaluation varchar feedback } agent_step { bigint id varchar session_id int step_index varchar agent_name text model_input text model_output text thought boolean has_tool_call } tool_invocation { bigint id varchar session_id varchar tool_name json input_params text output_preview varchar retrieval_layer json retrieval_details varchar relevance_level varchar dedup_reason } api_document { bigint id varchar doc_id varchar file_name varchar file_path varchar status int chunk_count text metadata } knowledge_domain { bigint id varchar domain_id varchar description text when_to_retrieve int document_count } case_library { bigint id varchar case_id varchar diagnosis_id varchar source_type varchar fault_category text root_cause text solution } milvus_chunk { varchar id text content json metadata vector vector } ``` 说明：Milvus/Zilliz collection 不是 MySQL 表，图中的 `milvus_chunk` 是逻辑模型。 ## 3. 诊断 Trace 模型 ### diagnosis_session 会话级主记录。 关键字段： | 字段 | 说明 | |---|---| | `session_id` | 外部关联键，Trace 和 Feedback 都使用它 | | `query` | 用户原始问题或 AIOps 输入摘要 | | `status` | 执行状态 | | `agent_flow` | `CHAT` / `AI_OPS` | | `answer` | 最终答复或告警报告 | | `self_evaluation` | rule/verifier/aiops 自评估容器 | | `feedback` | 用户反馈 | ### agent_step 记录模型调用步骤。 用途： - 回放 Agent 推理过程。 - 查看 Planner / Executor / Verifier 的输入输出摘要。 - 统计 step count、duration、token count。 ### tool_invocation 记录工具调用事实。 用途： - 给 Trace API 展示证据。 - 给 Gatekeeper 提供 `retrieval_details.evidence_refs` 引用验真源。 - 给 Verifier 构造 `tool_trace_summary` 审计导航。 - 给 `EvaluationService` 计算 evidence score。 - 给 RAG eval 和人工排查提供检索细节。 `retrieval_details.evidence_refs` 是当前 Chat 证据链路的关键字段： ```json { "evidence_status": "supported", "evidence_refs": [ { "raw_path": "$.logs[0]", "text": "2026-07-08 23:05:28 ERROR order-service HikariPool-1 - Connection is not available..." } ] } ``` 字段边界： | 字段 | 说明 | |---|---| | `evidence_status` | 工具证据状态，例如 `supported`、`no_evidence`、`deduped`、`failed` | | `evidence_refs[].raw_path` | Executor 可引用的稳定路径，例如 `$.logs[0]`、`$.alerts[0]`、`$.evidence_blocks[0]`、`$.no_evidence` | | `evidence_refs[].text` | 系统抽取的最小证据文本，Gatekeeper 用它核对 `evidence_excerpt` | `$.no_evidence` 只表示“本次工具查询未检索到匹配证据”，不能被解释为“问题不存在”或“根因已排除”。 ## 4. 知识库模型 ### api_document MySQL 中的文档元数据表。 职责： - 管理上传文件。 - 保存 file hash，用于去重。 - 记录索引状态和 chunk 数量。 - 保存 frontmatter JSON。 ### knowledge_domain 领域级元数据。 职责： - 按 category 聚合文档。 - 存储领域描述。 - 存储 `when_to_retrieve`，辅助 Planner/Executor 判断什么时候检索该领域。 ### Milvus/Zilliz metadata 向量 collection 中每个 chunk 的 metadata 主要包括： ```text docId _source chunkIndex totalChunks title breadcrumb category ``` 这些字段支撑： - category filter。 - source 展示。 - breadcrumb 上下文。 - docId 删除和重建索引。 - evidence block 构造。 ## 5. 反馈沉淀模型 ### case_library `useful` 反馈会触发 `CaseLibraryService.createFromSession`。 当前自动映射： | 字段 | 来源 | |---|---| | `case_id` | UUID | | `diagnosis_id` | `diagnosis_session.session_id` | | `source_type` | `AUTO` | | `fault_category` | 当前默认 `GENERAL` | | `title` | session query 前 100 字符 | | `root_cause` | session answer | | `solution` | session answer | | `created_by` | `system` | ## 6. self_evaluation 结构 `diagnosis_session.self_evaluation` 是 JSON 容器： ```json { "rule_evaluation": {}, "verifier_evaluation": {}, "aiops_rule_evaluation": {} } ``` 边界： - `rule_evaluation` 评估证据收集充分度。 - `verifier_evaluation` 评估 Chat 结构化 claims 是否能由已验真证据推出，并保存 Gatekeeper、Verifier、Composer 的审计数据。 - `aiops_rule_evaluation` 评估 AIOps 报告是否聚焦告警并使用证据。 当前 `verifier_evaluation` 关键结构： ```json { "verdict": "PASS", "groundedness_score": 1.0, "critical_fact_count": 1, "claim_checks": [], "facts_checked": [], "rationale": "...", "round": 1, "traceability_version": "v1", "executor_output_parse_status": {}, "executor_structured_output": {}, "gatekeeper_result": {}, "composer_output": {}, "tool_trace_summary": [] } ``` 必要审计字段： | 字段 | 说明 | |---|---| | `executor_output_parse_status` | Executor 输出是否能解析为 `executor_evidence_v2` | | `executor_structured_output` | Executor 结构化 claims、hypotheses、recommended_actions、missing_info | | `gatekeeper_result` | 引用真实性校验结果，包括 checked bindings、failed rules、warnings、errors | | `composer_output` | Composer 最终表达及解析状态 | | `tool_trace_summary` | Verifier 调用时使用的工具调用导航索引，不是唯一证据源 | ## 7. 数据写入时序 ```mermaid sequenceDiagram autonumber participant API as API participant Svc as ChatService/AiOpsService participant Session as diagnosis_session participant Agent as Agent participant Step as agent_step participant Tool as tool_invocation participant Eval as self_evaluation participant Feedback as case_library API->>Svc: request Svc->>Session: create/update RUNNING Agent->>Step: before/after model Agent->>Tool: tool call record Svc->>Session: SUCCESS/FAILED + answer Svc->>Eval: merge evaluation API->>Svc: feedback useful Svc->>Feedback: create case ``` ## 8. 当前边界和后续 当前边界： - `agent_step.session_id` 和 `tool_invocation.session_id` 通过 sessionId 关联，不强制外键。 - `tool_invocation.step_id` 可为空。 - Milvus chunk 与 `api_document` 通过 metadata.docId 逻辑关联。 - `case_library` 与 session 通过 `diagnosis_id=session_id` 关联。 后续可增强： 1. 增加 run id，支持同 session 多次独立诊断。 2. 强化 `tool_invocation.step_id` 关联。 3. 将 Gatekeeper 规则配置化时的规则元数据保存为可审计版本。 4. 将 `case_library` 的 rootCause/solution 从完整 answer 中结构化抽取。