SuperBizAgent-java/mvp/architecture/data-model.md

数据模型总览

更新日期：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. 总体关系

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 证据链路的关键字段：

{
  "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 主要包括：

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 容器：

{
  "rule_evaluation": {},
  "verifier_evaluation": {},
  "aiops_rule_evaluation": {}
}

边界：

• rule_evaluation 评估证据收集充分度。
• verifier_evaluation 评估 Chat 结构化 claims 是否能由已验真证据推出，并保存 Gatekeeper、Verifier、Composer 的审计数据。
• aiops_rule_evaluation 评估 AIOps 报告是否聚焦告警并使用证据。

当前 verifier_evaluation 关键结构：

{
  "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	引用真实性校验结果，包括 rule set version、checked bindings、failed rules、warnings、errors
composer_output	Composer 最终表达及解析状态
tool_trace_summary	Verifier 调用时使用的工具调用导航索引，不是唯一证据源

7. 数据写入时序

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 中结构化抽取。