Merge branch 'emdash/lemon-shrimps-bake-7q6xl' into refactor/rag-chunking-strategy
# Conflicts: # AGENTS.md # CLAUDE.md # src/main/resources/application.yml
This commit is contained in:
zhuyongxin
@@ -54,3 +54,4 @@ uploads/
|
||||
### docker
|
||||
/volumes
|
||||
/server.pid
|
||||
.claude/settings.local.json
|
||||
|
||||
@@ -1,7 +1,121 @@
|
||||
# CLAUDE.md
|
||||
|
||||
## Defaults
|
||||
|
||||
- Reply in **Chinese** unless I explicitly ask for English.
|
||||
- No emojis.
|
||||
- Do not truncate important outputs (logs, diffs, stack traces, commands, or critical reasoning that affects
|
||||
safety/correctness).
|
||||
|
||||
## Refactor policy (legacy code)
|
||||
|
||||
- When existing code is a "big ball of mud" (hard to maintain, clearly bad design,
|
||||
full of hacks), prefer a **clean, full refactor** over stacking more patches
|
||||
on top of it.
|
||||
- A refactor may completely replace internal structure
|
||||
(functions, modules, classes, data flow).
|
||||
- By default, try to preserve externally observable behaviour.
|
||||
If you intentionally change behaviour or protocols, you MUST:
|
||||
- Call out clearly that this is a **behaviour/protocol change**.
|
||||
- Explain why the change is necessary and which code paths/consumers are affected.
|
||||
- Update or add tests to cover the new behaviour.
|
||||
|
||||
## Before touching code (mandatory)
|
||||
|
||||
Find reuse opportunities + Trace the call/dependency chain and impact radius:
|
||||
|
||||
- Use semantic code search first via `codebase-retrieval` tool.
|
||||
- Confirm understanding with LSP: `goToDefinition`, `findReferences`.
|
||||
- Use Grep/Glob for verifying and understanding additional code snippets.
|
||||
|
||||
## Red lines
|
||||
|
||||
- No copy-paste duplication.
|
||||
- Do not break existing externally observable behaviour **unless**:
|
||||
- It is part of a deliberate refactor as described in the refactor policy, and
|
||||
- You clearly document the behavioural change and its impact.
|
||||
- Do not proceed with a known-wrong approach.
|
||||
- Critical paths must have explicit error handling.
|
||||
- Never implement "blindly": always confirm understanding via code reading + references.
|
||||
|
||||
## Task sizing
|
||||
|
||||
- **Simple**
|
||||
- Criteria — single file, clear requirement, < 20 lines changed,
|
||||
clearly local impact.
|
||||
- Handling — after doing the "Before touching code" steps
|
||||
(research + impact analysis + internal three-question checklist),
|
||||
you may execute directly with minimal explanation.
|
||||
- A very short context line is enough;
|
||||
a full breakdown of the checklist is not required.
|
||||
|
||||
- **Medium**
|
||||
- Criteria — 2–5 files, or requires some research, or impact is not obviously local.
|
||||
- Handling — write a short plan (bullet points) → then implement.
|
||||
- Briefly surface the checklist result in the reply
|
||||
(1–3 short lines describing real issue, key reuse, and main impact).
|
||||
|
||||
- **Complex**
|
||||
- Criteria — architecture changes, multiple modules, high uncertainty or risk.
|
||||
- Handling — follow this workflow:
|
||||
1. **RESEARCH**: inspect code and facts only (no proposals yet).
|
||||
2. **PLAN**: present options + tradeoffs + recommendation;
|
||||
use `AskUserQuestion` actively to align with the user;
|
||||
wait for user's confirmation.
|
||||
3. **EXECUTE**: implement exactly the approved plan.
|
||||
4. **REVIEW**: self-check (tests, edge cases, cleanup).
|
||||
|
||||
## Git
|
||||
|
||||
- Do not commit unless I explicitly ask.
|
||||
- Do not push unless I explicitly ask.
|
||||
- Before writing a commit message, glance at a few recent commits and match the repo's style:
|
||||
- `git log -n 5 --oneline`
|
||||
- If there is no obvious existing style, use this default format:
|
||||
- `<type>(<scope>): <description>`
|
||||
- Before any commit: run `git diff` and confirm the exact scope of changes.
|
||||
- Never force-push to `main` / `master` unless the user approves.
|
||||
- Do not add attribution lines in commit messages.
|
||||
|
||||
## Security
|
||||
|
||||
- Never hardcode secrets (keys/passwords/tokens).
|
||||
- Never commit `.env` files or any credentials.
|
||||
- Validate user input at trust boundaries (APIs, CLIs, external data sources).
|
||||
|
||||
## Quality & cleanup
|
||||
|
||||
- Prefer clarity and simplicity first (KISS); apply DRY to remove obvious
|
||||
copy-paste duplication when it does not hurt readability.
|
||||
- If you change a function signature, update **all** call sites.
|
||||
- After changes:
|
||||
- Remove temporary files.
|
||||
- Remove dead/commented-out code.
|
||||
- Remove unused imports.
|
||||
- Remove debug logging that is no longer needed.
|
||||
- Run the smallest meaningful verification (lint/test/build) for the parts you touched.
|
||||
|
||||
## Windows / PowerShell (if used)
|
||||
|
||||
- PowerShell does not support `&&`; use `;` to chain commands.
|
||||
- Quote paths that contain spaces or non-ASCII characters.
|
||||
|
||||
## Baisc Infos
|
||||
|
||||
Unless directly relevant to the user's current question, you should avoid proactively mentioning, illustrating, or
|
||||
trailing off into the following information in 99% of cases:
|
||||
|
||||
## Documentation
|
||||
|
||||
- 所有产生的文档（需求文档、计划文档、分析文档等）统一放到项目内的 `.docs` 文件夹中
|
||||
- 文档目录结构：
|
||||
- 不要将文档放到用户目录（如 `C:\Users\EDY\.claude\`）中
|
||||
|
||||
|
||||
<!-- gitnexus:start -->
|
||||
# GitNexus — Code Intelligence
|
||||
|
||||
This project is indexed by GitNexus as **SuperBizAgent-java** (1528 symbols, 2828 relationships, 87 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
|
||||
This project is indexed by GitNexus as **SuperBizAgent-java** (1001 symbols, 2043 relationships, 78 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
|
||||
|
||||
> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
|
||||
|
||||
|
||||
@@ -0,0 +1,81 @@
|
||||
# 数据库设计文档索引
|
||||
|
||||
## 📂 文档结构
|
||||
|
||||
```
|
||||
docs/
|
||||
├── README.md # 总览（推荐从这里开始）
|
||||
├── database-design.md # 总览（同 README.md）
|
||||
│
|
||||
├── tables/ # 表设计详细文档
|
||||
│ ├── diagnosis_record.md # 诊断记录表（核心）
|
||||
│ ├── case_library.md # 案例库表
|
||||
│ └── api_document.md # 文档元数据表
|
||||
│
|
||||
└── architecture/ # 架构设计文档
|
||||
├── agent-architecture-mvp.md # ⭐ Agent 架构 MVP 精简版
|
||||
├── agent-architecture.md # Agent 架构完整版（含生产级扩展）
|
||||
├── session-management.md # 会话管理设计
|
||||
└── implementation-plan.md # 实施规划
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速导航
|
||||
|
||||
### 我是开发者
|
||||
1. [总览](README.md) - 了解整体设计
|
||||
2. [diagnosis_record](tables/diagnosis_record.md) - 核心业务表
|
||||
3. [实施规划](architecture/implementation-plan.md) - 开发计划
|
||||
|
||||
### 我是运维
|
||||
1. [总览](README.md) - 了解表结构
|
||||
2. [实施规划](architecture/implementation-plan.md) - 部署检查清单
|
||||
|
||||
### 我是产品
|
||||
1. [总览](README.md) - 了解系统定位
|
||||
2. [会话管理](architecture/session-management.md) - 了解用户交互流程
|
||||
|
||||
---
|
||||
|
||||
## 📋 表清单
|
||||
|
||||
| 表名 | 优先级 | 文档 | 说明 |
|
||||
|------|--------|------|------|
|
||||
| diagnosis_record | P0 | [查看](tables/diagnosis_record.md) | 诊断记录（核心） |
|
||||
| case_library | P0 | [查看](tables/case_library.md) | 案例库 |
|
||||
| api_document | P0 | [查看](tables/api_document.md) | 文档元数据 |
|
||||
|
||||
---
|
||||
|
||||
## 📖 阅读建议
|
||||
|
||||
### 第一次阅读
|
||||
```
|
||||
1. README.md（10分钟）
|
||||
- 了解设计原则
|
||||
- 了解表关系
|
||||
|
||||
2. diagnosis_record.md（15分钟）
|
||||
- 核心表设计
|
||||
- 字段泛化设计
|
||||
|
||||
3. implementation-plan.md（5分钟）
|
||||
- 分阶段实施计划
|
||||
```
|
||||
|
||||
### 深入理解
|
||||
```
|
||||
- case_library.md - 案例推荐机制
|
||||
- api_document.md - 文档管理设计
|
||||
- session-management.md - 会话管理机制
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 文档维护
|
||||
|
||||
- 原完整文档已备份：`database-design-backup-20240622.md`
|
||||
- 每个表的详细设计在 `tables/` 目录
|
||||
- 架构设计在 `architecture/` 目录
|
||||
- 修改表结构时，同步更新对应 Markdown
|
||||
+155
@@ -0,0 +1,155 @@
|
||||
# 数据库设计文档
|
||||
|
||||
## 📚 文档导航
|
||||
|
||||
### 核心表设计
|
||||
- [diagnosis_record](tables/diagnosis_record.md) - 诊断记录表（核心）
|
||||
- [case_library](tables/case_library.md) - 案例库表
|
||||
- [api_document](tables/api_document.md) - 文档元数据表
|
||||
|
||||
### 架构设计
|
||||
- [Agent 架构设计](architecture/agent-architecture.md) - Agent 协作 + Skill + Harness
|
||||
- [会话管理](architecture/session-management.md) - Redis + MySQL 会话管理
|
||||
- [实施规划](architecture/implementation-plan.md) - 分阶段实施计划
|
||||
|
||||
---
|
||||
|
||||
## 一、设计原则
|
||||
|
||||
### 1.1 核心原则
|
||||
- ✅ **简单优先**：满足诊断流程需要，避免过度设计
|
||||
- ✅ **渐进增强**：先实现核心功能，再逐步扩展
|
||||
- ✅ **数据分离**：诊断结果持久化（MySQL），会话上下文临时化（Redis）
|
||||
- ✅ **适度冗余**：避免过度范式化，适当冗余提升查询性能
|
||||
|
||||
### 1.2 系统定位
|
||||
**自动化诊断系统**
|
||||
- 核心：一键诊断 → 返回完整报告
|
||||
- 辅助：支持追问，但不是主要场景
|
||||
- 特点：大部分用户单次诊断即结束，少数用户会追问细节
|
||||
|
||||
---
|
||||
|
||||
## 二、表结构总览
|
||||
|
||||
### 2.1 核心表关系
|
||||
|
||||
```
|
||||
┌─────────────────────┐
|
||||
│ diagnosis_record │ 诊断记录（核心）
|
||||
│ - 每次诊断一条 │
|
||||
└──────────┬──────────┘
|
||||
│ 1:1
|
||||
↓
|
||||
┌─────────────────────┐
|
||||
│ case_library │ 案例库（知识沉淀）
|
||||
│ - 诊断成功→案例 │
|
||||
└─────────────────────┘
|
||||
|
||||
┌─────────────────────┐
|
||||
│ api_document │ 文档元数据（管理层）
|
||||
│ - 状态追踪/去重 │
|
||||
└──────────┬──────────┘
|
||||
│ doc_id
|
||||
↓
|
||||
┌─────────────────────┐
|
||||
│ Milvus │ 文档内容（检索层）
|
||||
│ - 向量检索 │
|
||||
└─────────────────────┘
|
||||
|
||||
┌─────────────────────┐
|
||||
│ Redis Session │ 会话管理（临时）
|
||||
│ - 30分钟过期 │
|
||||
│ - 支持追问 │
|
||||
└─────────────────────┘
|
||||
```
|
||||
|
||||
### 2.2 表统计
|
||||
|
||||
| 表名 | 类型 | 预估数据量 | 用途 |
|
||||
|------|------|-----------|------|
|
||||
| diagnosis_record | 核心 | 3.6万/年 | 诊断记录 |
|
||||
| case_library | 核心 | 500-1000 | 案例库 |
|
||||
| api_document | 核心 | 100-200 | 文档管理 |
|
||||
|
||||
---
|
||||
|
||||
## 三、技术栈
|
||||
|
||||
### 3.1 数据存储
|
||||
```
|
||||
MySQL 8.0+
|
||||
├─ 元数据管理
|
||||
├─ 事务支持
|
||||
└─ JSON 字段支持
|
||||
|
||||
Redis 6.0+
|
||||
├─ 会话存储
|
||||
├─ 缓存
|
||||
└─ TTL 自动过期
|
||||
|
||||
Milvus 2.6+
|
||||
├─ 向量存储
|
||||
├─ 语义检索
|
||||
└─ 混合检索
|
||||
```
|
||||
|
||||
### 3.2 开发框架
|
||||
```
|
||||
Spring Boot 3.2
|
||||
Spring AI Alibaba 1.1.0
|
||||
Milvus SDK Java 2.6.10
|
||||
DashScope SDK
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、快速开始
|
||||
|
||||
### 4.1 创建数据库
|
||||
|
||||
```sql
|
||||
-- 1. 创建数据库
|
||||
CREATE DATABASE diagnosis_system CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
|
||||
-- 2. 执行建表脚本（按顺序）
|
||||
SOURCE tables/diagnosis_record.sql;
|
||||
SOURCE tables/case_library.sql;
|
||||
SOURCE tables/api_document.sql;
|
||||
```
|
||||
|
||||
### 4.2 初始化 Milvus
|
||||
|
||||
```java
|
||||
// 创建 Collection
|
||||
MilvusClientFactory.createCollection();
|
||||
```
|
||||
|
||||
### 4.3 配置 Redis
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
redis:
|
||||
host: localhost
|
||||
port: 6379
|
||||
database: 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、版本历史
|
||||
|
||||
| 版本 | 日期 | 变更内容 |
|
||||
|------|------|---------|
|
||||
| v1.0 | 2024-06-15 | 初版，定义核心表结构 |
|
||||
| v2.0 | 2024-06-15 | diagnosis_record 字段泛化，支持多种故障类型 |
|
||||
| v2.1 | 2024-06-22 | 文档拆分，增加 api_document 表 |
|
||||
|
||||
---
|
||||
|
||||
## 六、维护说明
|
||||
|
||||
- 每个表的详细设计在 `tables/` 目录下
|
||||
- 架构设计文档在 `architecture/` 目录下
|
||||
- 修改表结构时，同步更新对应的 Markdown 文档
|
||||
- 重大变更需记录在版本历史中
|
||||
@@ -0,0 +1,529 @@
|
||||
# Agent 架构设计（MVP 版）
|
||||
|
||||
## 一、MVP 全景
|
||||
|
||||
```
|
||||
用户输入
|
||||
↓
|
||||
┌──────────────────────────────────────────┐
|
||||
│ 意图识别（Intent Recognition） 🆕 │
|
||||
│ "用户想干什么？" │
|
||||
│ │
|
||||
│ 诊断意图 → 路由到诊断 Skill │
|
||||
│ 文档意图 → 路由到文档问答 │
|
||||
│ 案例意图 → 路由到案例查询 │
|
||||
│ 闲聊 → 快速响应（不启动 Agent） │
|
||||
│ 模糊/无关 → 提示用户，直接中断 │
|
||||
└──────────────┬───────────────────────────┘
|
||||
│ 诊断意图
|
||||
↓
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Supervisor Agent（调度者） │
|
||||
│ "谁来干？什么时候停？" │
|
||||
└──────────────┬───────────────────────────┘
|
||||
↓
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Planner Agent（规划者） │
|
||||
│ 分析问题 → 制定策略 → 生成报告 │
|
||||
└──────────────┬───────────────────────────┘
|
||||
↓
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Executor Agent（执行者） │
|
||||
│ 调用工具收集证据 │
|
||||
└──────────────┬───────────────────────────┘
|
||||
↓
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Verifier Agent（验证者） │
|
||||
│ 事实核查 → 判定通过/修正/驳回 │
|
||||
└──────────────┬───────────────────────────┘
|
||||
↓
|
||||
诊断报告输出
|
||||
↓
|
||||
用户反馈（有用/无用）
|
||||
↓
|
||||
案例沉淀 + BadCase 优化
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、意图识别（入口层）🆕
|
||||
|
||||
### 2.1 设计理念
|
||||
|
||||
```
|
||||
定位：独立模块，不嵌入任何单一 Agent
|
||||
|
||||
分层策略（不是二选一，而是组合）：
|
||||
|
||||
L0: 正则规则 —— 0 成本，毫秒级 ✅ MVP
|
||||
├─ 处理 80%+ 的结构化查询
|
||||
├─ 正则匹配订单号/traceId/错误码格式
|
||||
└─ 关键词匹配（"报错"/"异常"/"失败"）
|
||||
|
||||
L1: 小模型 Agent —— 低成本，百毫秒级 ✅ MVP
|
||||
├─ L0 未命中时触发
|
||||
├─ 处理灵活的模糊表达（"系统有点慢"、"怎么查不到了"）
|
||||
├─ 不启动全链路 Agent，只做意图分类
|
||||
└─ 判断为诊断意图 → 路由到诊断 Skill
|
||||
|
||||
L2: 兜底策略 —— 极少使用
|
||||
├─ L0+L1 都无法判断 → 意图不明 → 中断
|
||||
└─ Phase 2 增强
|
||||
```
|
||||
|
||||
### 2.2 意图分类与路由
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────┐
|
||||
│ 意图 │ 说明 │ 路由 │
|
||||
├────────────────────────────────────────────────────┤
|
||||
│ 诊断意图 │ 包含结构化标识或错误描述 │ → 诊断Skill│
|
||||
│ 文档问答 │ "XX接口的参数有哪些" │ → 直接RAG │
|
||||
│ 案例查询 │ "之前有类似的问题吗" │ → 案例检索 │
|
||||
│ 闲聊 │ "你好"/"谢谢" │ → 快速响应 │
|
||||
│ 意图不明 │ 无法识别 │ → 中断+提示 │
|
||||
└────────────────────────────────────────────────────┘
|
||||
|
||||
关键原则：
|
||||
- 只有诊断意图才启动 Agent 全链路
|
||||
- 非诊断意图走轻量路径或直接中断
|
||||
```
|
||||
|
||||
### 2.3 L0：正则规则（MVP，处理 80%）
|
||||
|
||||
```
|
||||
为什么先做 L0？
|
||||
→ 0 成本（不调 LLM），毫秒级响应
|
||||
→ 结构化查询占比最大（订单号、traceId、错误码、关键词）
|
||||
→ L0 命中直接路由，不需要走后续逻辑
|
||||
|
||||
规则配置（可扩展）：
|
||||
┌────────────────────────────────────────────────┐
|
||||
│ 规则 │ 意图 │ 方式 │
|
||||
├────────────────────────────────────────────────┤
|
||||
│ 匹配 \d{12,} │ 诊断 │ 正则 │
|
||||
│ 匹配 trace[-_]?\w{8,} │ 诊断 │ 正则 │
|
||||
│ 包含"报错‖失败‖异常‖挂了‖超时" │ 诊断 │ 关键词│
|
||||
│ 包含"文档‖接口‖参数‖字段‖API" │ 文档 │ 关键词│
|
||||
│ 包含"案例‖之前‖类似‖历史" │ 案例 │ 关键词│
|
||||
│ 长度 <= 5 字符 │ 闲聊 │ 规则 │
|
||||
└────────────────────────────────────────────────┘
|
||||
|
||||
命中 → 直接路由，不调 L1
|
||||
未命中 → 进入 L1
|
||||
```
|
||||
|
||||
### 2.4 L1：小模型 Agent（MVP，处理剩余 20%）
|
||||
|
||||
```
|
||||
为什么用小模型 Agent 而非嵌入到 Supervisor？
|
||||
→ 意图识别是独立职责，不应耦合到任何业务 Agent
|
||||
→ 轻量 Agent：单一职责，只分类不执行
|
||||
→ 成本低（~50 token），延迟低（~200ms）
|
||||
|
||||
何时触发：L0 规则未命中
|
||||
|
||||
System Prompt:
|
||||
"你是意图分类器，判断用户想做什么。
|
||||
只返回一个词：[诊断 / 文档查询 / 案例查询 / 闲聊 / 意图不明]
|
||||
|
||||
诊断：用户描述了故障、报错、异常
|
||||
文档查询：用户询问接口文档、字段含义
|
||||
案例查询：用户询问历史案例、类似问题
|
||||
闲聊：简单的问候、感谢
|
||||
意图不明：无法判断用户意图"
|
||||
|
||||
输入：用户原始输入
|
||||
输出：意图类型 + 置信度
|
||||
```
|
||||
|
||||
### 2.5 L2：兜底策略
|
||||
|
||||
```
|
||||
L0+L1 都无法判断 → L2 兜底
|
||||
|
||||
中断规则：
|
||||
├─ 意图不明 → 提示用户 + 中断
|
||||
│ "无法判断您的意图，请提供订单号或错误码"
|
||||
├─ 闲聊 → 快速响应 + 中断
|
||||
│ "我是故障诊断助手，请描述您遇到的问题"
|
||||
└─ 不启动 Agent，直接返回
|
||||
|
||||
路由规则：
|
||||
├─ 诊断意图 → 启动 Supervisor + 4 Agent 全链路
|
||||
├─ 文档意图 → 不启动 Agent，直接 RAG 检索
|
||||
└─ 案例意图 → 不启动 Agent，直接查询 case_library
|
||||
```
|
||||
|
||||
### 2.5 架构位置
|
||||
|
||||
```
|
||||
用户输入
|
||||
↓
|
||||
┌──────────────────────────────────────────┐
|
||||
│ 意图识别模块（独立） │
|
||||
│ │
|
||||
│ L1: 小模型 Agent ─→ 诊断意图？ │
|
||||
│ │ 文档意图？ │
|
||||
│ │ 案例意图？ │
|
||||
│ │ 闲聊？ │
|
||||
│ ↓ │
|
||||
│ L2: 兜底 ─────────→ 意图不明 → 中断 │
|
||||
│ 闲聊 → 快速响应 │
|
||||
└───────────────┬──────────────────────────┘
|
||||
│ 诊断意图
|
||||
↓
|
||||
Supervisor → Planner → Executor → Verifier
|
||||
```
|
||||
|
||||
### 2.6 MVP vs Phase 2
|
||||
|
||||
```
|
||||
MVP L0（正则）+ L1（小模型Agent） 覆盖 95%+ 场景
|
||||
Phase 2 L2（兜底增强） 细化中断提示，支持多轮澄清
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、4 个 Agent 设计
|
||||
|
||||
### 2.1 Supervisor Agent（调度者）
|
||||
|
||||
**职责**：总指挥，协调工作流
|
||||
|
||||
```
|
||||
调度规则：
|
||||
├─ 接收任务 → 发给 Planner 分析
|
||||
├─ Planner 完成 → 发给 Executor 执行
|
||||
├─ Executor 完成 → 发给 Verifier 校验
|
||||
└─ Verifier PASS → 输出报告 / REJECT → 返回 Planner 重新规划
|
||||
|
||||
不做：
|
||||
- 不直接调用工具
|
||||
- 不直接生成报告
|
||||
```
|
||||
|
||||
### 2.2 Planner Agent（规划者 + 分诊）
|
||||
|
||||
**职责**：分析问题、制定策略、生成报告草稿
|
||||
|
||||
```
|
||||
分析规则：
|
||||
├─ 有 errorCode + 接口 URL → EXTERNAL_API（外部接口故障）
|
||||
├─ 有堆栈信息 → INTERNAL_ERROR（系统内部错误）
|
||||
├─ 有数据库错误码（如 1213）→ DATABASE（数据库问题）
|
||||
└─ 其他 → 通用排查
|
||||
|
||||
规划流程：
|
||||
1. 确定 fault_category
|
||||
2. 制定排查步骤（每步：工具名 + 参数 + 预期）
|
||||
3. 生成决策：EXECUTE（继续执行）| FINISH（生成报告）
|
||||
|
||||
Replanner 职责：
|
||||
├─ Executor 每次返回结果后 → 评估证据是否充分
|
||||
├─ 需要补充？→ 调整步骤，继续执行
|
||||
├─ 证据齐全？→ FINISH，生成报告草稿
|
||||
└─ 连续 3 次失败？→ 降级
|
||||
|
||||
禁止：
|
||||
- 编造数据
|
||||
- 引用未经工具返回的内容
|
||||
```
|
||||
|
||||
### 2.3 Executor Agent（执行者）
|
||||
|
||||
**职责**：调用工具收集证据
|
||||
|
||||
```
|
||||
工具清单：
|
||||
├─ queryOrder：查询订单/业务数据（MySQL 只读）
|
||||
├─ searchDoc：检索接口文档（混合检索 Milvus + MySQL）
|
||||
├─ recommendCase：推荐相似案例（精确匹配 + 语义检索）
|
||||
└─ getCurrentTime：获取当前时间
|
||||
|
||||
执行规则：
|
||||
├─ 每次只执行 Planner 指定的一个步骤
|
||||
├─ 返回结构化的执行结果
|
||||
├─ 失败时返回错误详情（便于 Planner 调整）
|
||||
└─ 禁止编造结果
|
||||
|
||||
扩展预留：
|
||||
// 代码中 Executor 是接口，后续可扩展为 SubAgent
|
||||
public interface Executor {
|
||||
ExecutionResult execute(Step step);
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 Verifier Agent（验证者）
|
||||
|
||||
**职责**：验证诊断报告，防止编造
|
||||
|
||||
```
|
||||
验证流程：
|
||||
|
||||
1️⃣ 事实核查（最重要）
|
||||
├─ 报告中的错误码 → 在 tool_calls 中存在？
|
||||
├─ 根因结论 → 有日志/文档证据支撑？
|
||||
├─ 修复方案 → 引用了文档或案例？
|
||||
└─ 发现编造数据 → 直接 REJECT
|
||||
|
||||
2️⃣ 完整性检查
|
||||
├─ 根因分析章节不能为空
|
||||
├─ 证据链章节不能为空
|
||||
└─ 修复方案章节不能为空
|
||||
|
||||
判决结果：
|
||||
├─ PASS：报告成立，直接输出
|
||||
├─ REVISE：小问题可修正，返回 Planner 微调
|
||||
└─ REJECT：编造数据或严重错误，返回 Planner 重新分析
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、RAG 两层加载策略
|
||||
|
||||
### 4.1 设计理念
|
||||
|
||||
```
|
||||
问题：
|
||||
❌ 全前置：启动时把所有文档塞给 Agent → 信息过载，推理变慢
|
||||
❌ 纯被动：等到需要才查 → Planner 没有全局视野，可能跑偏
|
||||
❌ 固定步骤：每次都调 → 内部错误查接口文档浪费
|
||||
|
||||
正确做法：两层互补
|
||||
|
||||
L1 预加载（Planner 启动时）
|
||||
→ 通用领域知识：系统架构、通用错误码、业务流程
|
||||
→ 给 Planner 全局视野，避免方向性错误
|
||||
|
||||
L2 按需加载（Executor 执行中）
|
||||
→ 具体接口文档：字段定义、错误码含义、调用规范
|
||||
→ 给 Executor 精准证据，定位具体问题
|
||||
```
|
||||
|
||||
### 4.2 两层对比
|
||||
|
||||
| | L1 预加载 | L2 按需加载 |
|
||||
|------|---------|-----------|
|
||||
| 触发时机 | 意图识别后，Planner 启动前 | Executor 拿到具体信息后 |
|
||||
| 内容 | 通用知识（架构、流程、高频错误码） | 具体接口文档（字段、错误码含义） |
|
||||
| 目的 | 让 Planner 有全局视野 | 让 Executor 有精准证据 |
|
||||
| 成本 | 固定，每次诊断 1 次 | 按需，最多 2-3 次 |
|
||||
| 谁负责 | Supervisor 注入 | Executor 自主调用 |
|
||||
|
||||
### 4.3 实现方式
|
||||
|
||||
```
|
||||
L1 预加载：
|
||||
Supervisor 在启动 Planner 前：
|
||||
searchDoc(keyword="系统架构 通用错误码 业务流程")
|
||||
→ 注入到 Planner 的 System Prompt 中
|
||||
→ Planner 拥有"领域背景知识"
|
||||
|
||||
L2 按需加载：
|
||||
Executor 执行 Step 2 时：
|
||||
拿到 errorCode=40003, faultSource="广东"
|
||||
→ 自主调用 searchDoc(errorCode="40003", faultSource="广东")
|
||||
→ 获取该接口的具体字段定义和错误码说明
|
||||
→ 作为证据写入诊断报告
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、Skill 设计（1 个）
|
||||
|
||||
### /diagnose-by-orderid（按订单号诊断）
|
||||
|
||||
```
|
||||
输入：orderId
|
||||
|
||||
工作流（6 步）：
|
||||
|
||||
Step 1: 查询订单信息
|
||||
工具：queryOrder
|
||||
失败：ABORT（订单不存在则终止）
|
||||
|
||||
Step 2: 检索接口文档
|
||||
工具：searchDoc
|
||||
参数：errorCode + faultSource
|
||||
失败：SKIP（标注"文档缺失"）
|
||||
|
||||
Step 3: 查询日志
|
||||
工具：queryLogs（Mock）
|
||||
参数：traceId
|
||||
失败：SKIP（标注"日志缺失"）
|
||||
|
||||
Step 4: 检索相似案例
|
||||
工具：recommendCase
|
||||
参数：errorCode + faultCategory
|
||||
失败：SKIP（标注"无相似案例"）
|
||||
|
||||
Step 5: 生成诊断报告
|
||||
汇总所有证据，按模板生成报告
|
||||
|
||||
Step 6: Verifier 验证
|
||||
事实核查 → 判决
|
||||
|
||||
门禁规则：
|
||||
├─ Step 1 失败 → 终止，返回"订单不存在"
|
||||
├─ Step 2-4 失败 → 跳过，标注缺失信息
|
||||
├─ 任意步骤超时 30s → 终止
|
||||
└─ Verifier REJECT → 返回 Planner 重新规划
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、Harness 控制层（精简版）
|
||||
|
||||
### 4.1 5 个 Quality Gates
|
||||
|
||||
```
|
||||
输入门禁（2 个）：
|
||||
├─ Gate 1: 输入参数非空校验
|
||||
└─ Gate 2: 5 分钟内同一订单 → 返回缓存
|
||||
|
||||
执行门禁（1 个）：
|
||||
└─ Gate 3: 工具调用超时（10 秒）
|
||||
|
||||
输出门禁（2 个）：
|
||||
├─ Gate 4: 报告章节完整性（3 章节不全 → 不通过）
|
||||
└─ Gate 5: 置信度阈值（< 60 → 标记"低置信度"）
|
||||
```
|
||||
|
||||
### 4.2 中断规则
|
||||
|
||||
```
|
||||
自动中断：
|
||||
├─ 工具连续失败 3 次 → 终止，降级输出
|
||||
└─ 全局超时 30 秒 → 终止
|
||||
|
||||
条件降级：
|
||||
├─ 文档检索为空 → 跳过继续
|
||||
├─ 案例推荐为空 → 跳过继续
|
||||
└─ 日志查询失败 → 跳过继续
|
||||
|
||||
降级输出：
|
||||
"无法自动诊断，请人工介入"
|
||||
+ 已收集的证据（订单信息 + 部分日志 + 已知错误码）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、技术实现
|
||||
|
||||
### 5.1 基于 Spring AI Alibaba
|
||||
|
||||
```java
|
||||
// Supervisor - 框架提供
|
||||
SupervisorAgent supervisor = SupervisorAgent.builder()
|
||||
.name("diagnosis_supervisor")
|
||||
.model(chatModel)
|
||||
.subAgents(List.of(planner, executor, verifier))
|
||||
.build();
|
||||
|
||||
// Planner
|
||||
ReactAgent planner = ReactAgent.builder()
|
||||
.name("planner_agent")
|
||||
.model(chatModel)
|
||||
.systemPrompt(plannerPrompt)
|
||||
.outputKey("planner_plan")
|
||||
.build();
|
||||
|
||||
// Executor（代码中预留 SubAgent 扩展接口）
|
||||
ReactAgent executor = ReactAgent.builder()
|
||||
.name("executor_agent")
|
||||
.model(chatModel)
|
||||
.systemPrompt(executorPrompt)
|
||||
.methodTools(diagnosisTools)
|
||||
.tools(new ToolCallback[]{queryOrder, searchDoc, recommendCase, getCurrentTime})
|
||||
.build();
|
||||
|
||||
// Verifier
|
||||
ReactAgent verifier = ReactAgent.builder()
|
||||
.name("verifier_agent")
|
||||
.model(chatModel)
|
||||
.systemPrompt(verifierPrompt)
|
||||
.outputKey("verifier_result")
|
||||
.build();
|
||||
```
|
||||
|
||||
### 5.2 工具注册
|
||||
|
||||
```java
|
||||
@Component
|
||||
public class DiagnosisTools {
|
||||
|
||||
@Tool(description = "查询订单/业务数据（只读）")
|
||||
public OrderInfo queryOrder(@ToolParam(description = "订单号") String orderId) {
|
||||
// MySQL 只读 + SQL 注入防护
|
||||
}
|
||||
|
||||
@Tool(description = "检索接口文档")
|
||||
public List<DocChunk> searchDoc(
|
||||
@ToolParam(description = "错误码") String errorCode,
|
||||
@ToolParam(description = "省份/服务名") String faultSource
|
||||
) {
|
||||
// 混合检索：精确匹配 + 向量检索
|
||||
}
|
||||
|
||||
@Tool(description = "推荐相似历史案例")
|
||||
public List<CaseResult> recommendCase(
|
||||
@ToolParam(description = "错误码") String errorCode,
|
||||
@ToolParam(description = "故障类别") String faultCategory
|
||||
) {
|
||||
// 精确匹配 MySQL + 语义检索 Milvus
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、闭环机制
|
||||
|
||||
```
|
||||
诊断报告输出
|
||||
↓
|
||||
用户反馈（useful / not_useful）
|
||||
↓
|
||||
├─ useful → 自动生成 case_library
|
||||
└─ not_useful → 记录 BadCase
|
||||
↓
|
||||
每周 BadCase 分析
|
||||
↓
|
||||
Prompt / Skill 优化
|
||||
↓
|
||||
准确率验证（测试集重跑）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 九、MVP vs 扩展方向
|
||||
|
||||
| 维度 | MVP | 扩展方向 |
|
||||
|------|-----|---------|
|
||||
| Agent | 4 个 Agent | SubAgent 模式（专科医生） |
|
||||
| Skill | 1 个 | 渐进式披露（3 层知识） |
|
||||
| 工具 | @Tool 注解 | MCP 独立 Server |
|
||||
| 回退 | 2 级（失败→降级） | 4 级路由 |
|
||||
| Gates | 5 个 | 15 个全流程门禁 |
|
||||
| 隔离 | 单 JVM | K8s Pod 进程隔离 |
|
||||
| 进化 | 案例自动生成 | 模式识别 + Prompt 自优化 |
|
||||
|
||||
---
|
||||
|
||||
## 十、面试话术（精简版）
|
||||
|
||||
> "我用 Spring AI Alibaba 实现了一个故障诊断 Agent 系统。
|
||||
>
|
||||
> 入口层是**意图识别**：先判断用户想干什么——诊断故障、查文档、查案例还是闲聊。
|
||||
> 非诊断意图直接走轻量路径，只有诊断意图才启动 Agent 全链路，节省资源。
|
||||
>
|
||||
> 4 Agent 协作：Supervisor 调度、Planner 制定策略、
|
||||
> Executor 调用工具收集证据、Verifier 验证报告防止编造。
|
||||
>
|
||||
> 诊断流程封装成了 Skill，标准化 6 个步骤和异常处理。
|
||||
> Harness 层 5 个门禁保证质量——最关键的是输出门禁，
|
||||
> Verifier 会对比报告数据和工具返回数据，发现编造就驳回。
|
||||
>
|
||||
> 闭环机制：用户反馈 → BadCase 分析 → Prompt 优化。
|
||||
> 案例自动沉淀，系统越用越智能。"
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,715 @@
|
||||
# SuperBizAgent MVP 完整实施计划（AI 执行）
|
||||
|
||||
## 协作分工
|
||||
|
||||
```
|
||||
用户角色：规划者 + 验证者 + 架构师
|
||||
AI 角色： 执行者 + 编码者 + 记录者
|
||||
|
||||
用户负责：
|
||||
├─ 确认架构设计
|
||||
├─ 验收每个阶段产出
|
||||
├─ 调整优先级和方向
|
||||
└─ 最终验收和部署决策
|
||||
|
||||
AI 负责：
|
||||
├─ 编写全部代码
|
||||
├─ 编写全部测试
|
||||
├─ 执行测试验证
|
||||
├─ 记录实施过程
|
||||
├─ 遇到问题提出方案供用户决策
|
||||
└─ 自动化构建和本地验证
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 总览：3 个 Phase，13 天
|
||||
|
||||
```
|
||||
Phase 1: 基础设施（5天）
|
||||
├─ Day 1-2: 数据库 + 实体 + 会话管理
|
||||
├─ Day 3: 代码结构重构
|
||||
└─ Day 4-5: 文档管理（CRUD + Milvus）
|
||||
|
||||
Phase 2: 核心功能（5天）
|
||||
├─ Day 6-7: 意图识别 + RAG 两层加载
|
||||
├─ Day 8-9: 4 Agent 协作 + Skill
|
||||
└─ Day 10: 工具层开发
|
||||
|
||||
Phase 3: 闭环优化（3天）
|
||||
├─ Day 11: Verifier + Harness
|
||||
├─ Day 12: 反馈机制 + 案例沉淀
|
||||
└─ Day 13: 端到端测试 + 验收
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1：基础设施（5天）
|
||||
|
||||
### Day 1-2：数据库 + 实体 + 会话
|
||||
|
||||
#### 任务 1.1：MySQL 表结构（Flyway 迁移）
|
||||
|
||||
```sql
|
||||
产出文件：
|
||||
src/main/resources/db/migration/
|
||||
├── V001__create_diagnosis_record.sql
|
||||
├── V002__create_case_library.sql
|
||||
└── V003__create_api_document.sql
|
||||
|
||||
依据文档：
|
||||
- docs/tables/diagnosis_record.md
|
||||
- docs/tables/case_library.md
|
||||
- docs/tables/api_document.md
|
||||
|
||||
关键点：
|
||||
- 使用 Flyway 版本管理
|
||||
- 索引：trace_id, error_code, fault_category
|
||||
- JSON 字段：steps_executed, evidence_chain
|
||||
- 时间字段：created_at, updated_at 自动维护
|
||||
|
||||
验收标准：
|
||||
✓ 执行 mvn flyway:migrate 成功
|
||||
✓ 3 张表创建成功
|
||||
✓ 索引完整
|
||||
✓ 约束正确
|
||||
```
|
||||
|
||||
#### 任务 1.2：JPA 实体类
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
src/main/java/com/superbiz/agent/domain/entity/
|
||||
├── DiagnosisRecord.java
|
||||
├── CaseLibrary.java
|
||||
└── ApiDocument.java
|
||||
|
||||
技术栈：
|
||||
- Spring Data JPA
|
||||
- Lombok (@Data, @Builder)
|
||||
- Hibernate @JdbcTypeCode(SqlTypes.JSON)
|
||||
|
||||
验收标准：
|
||||
✓ 字段与 DDL 一致
|
||||
✓ 枚举映射正确
|
||||
✓ JSON 字段序列化正常
|
||||
✓ 编译通过
|
||||
```
|
||||
|
||||
#### 任务 1.3：Repository 层
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
src/main/java/com/superbiz/agent/repository/
|
||||
├── DiagnosisRecordRepository.java
|
||||
├── CaseLibraryRepository.java
|
||||
└── ApiDocumentRepository.java
|
||||
|
||||
常用查询：
|
||||
- findByOrderId
|
||||
- findByTraceId
|
||||
- findByErrorCodeAndFaultCategory
|
||||
- findTopByOrderByCreatedAtDesc
|
||||
|
||||
验收标准：
|
||||
✓ 继承 JpaRepository
|
||||
✓ 单元测试覆盖（@DataJpaTest + H2）
|
||||
✓ 分页查询正确
|
||||
```
|
||||
|
||||
#### 任务 1.4：Redis 会话管理
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
src/main/java/com/superbiz/agent/session/
|
||||
├── SessionManager.java # 接口
|
||||
├── RedisSessionManager.java # Redis 实现
|
||||
├── SessionContext.java # 会话上下文
|
||||
└── SessionConfiguration.java # 配置类
|
||||
|
||||
功能：
|
||||
- 替换内存 HashMap
|
||||
- TTL：30 分钟
|
||||
- JSON 序列化（Jackson）
|
||||
- 按 sessionId 存取删
|
||||
|
||||
验收标准：
|
||||
✓ 单元测试通过
|
||||
✓ Redis 连接成功
|
||||
✓ 序列化/反序列化正确
|
||||
✓ TTL 生效
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Day 3：代码结构重构
|
||||
|
||||
#### 任务 3.1：包名重构
|
||||
|
||||
```
|
||||
重构前：org.example
|
||||
重构后：com.superbiz.agent
|
||||
|
||||
操作：
|
||||
1. IDEA Refactor → Rename Package
|
||||
2. 全局搜索替换 import
|
||||
3. pom.xml 更新 mainClass
|
||||
|
||||
验收标准：
|
||||
✓ 编译通过
|
||||
✓ 无遗漏的 org.example
|
||||
✓ 启动成功
|
||||
```
|
||||
|
||||
#### 任务 3.2：分层结构优化
|
||||
|
||||
```
|
||||
目标结构：
|
||||
src/main/java/com/superbiz/agent/
|
||||
├── controller/ # REST 接口
|
||||
├── service/ # 业务逻辑
|
||||
├── repository/ # 数据访问
|
||||
├── domain/
|
||||
│ ├── entity/ # JPA 实体
|
||||
│ ├── dto/ # 数据传输对象
|
||||
│ ├── vo/ # 视图对象
|
||||
│ └── enums/ # 枚举
|
||||
├── agent/ # Agent 层
|
||||
│ ├── supervisor/
|
||||
│ ├── planner/
|
||||
│ ├── executor/
|
||||
│ └── verifier/
|
||||
├── tool/ # 工具层
|
||||
├── harness/ # Harness 控制
|
||||
│ ├── gate/
|
||||
│ └── interrupt/
|
||||
├── skill/ # Skill 定义
|
||||
├── session/ # 会话管理
|
||||
├── intent/ # 意图识别
|
||||
├── rag/ # RAG 加载
|
||||
└── config/ # 配置
|
||||
|
||||
验收标准：
|
||||
✓ 目录结构清晰
|
||||
✓ 职责单一
|
||||
✓ 编译通过
|
||||
```
|
||||
|
||||
#### 任务 3.3：DTO 抽离
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
src/main/java/com/superbiz/agent/domain/dto/
|
||||
├── DiagnosisRequest.java
|
||||
├── DiagnosisResponse.java
|
||||
├── DocumentUploadRequest.java
|
||||
├── CaseQueryRequest.java
|
||||
└── ...
|
||||
|
||||
要求：
|
||||
- Controller 不直接依赖 Entity
|
||||
- MapStruct 做对象转换
|
||||
- 校验注解 @Valid + @NotNull
|
||||
- 统一响应包装类 Result<T>
|
||||
|
||||
验收标准：
|
||||
✓ Controller 不 import Entity
|
||||
✓ 原有接口兼容
|
||||
✓ 编译通过
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Day 4-5：文档管理
|
||||
|
||||
#### 任务 4.1：文档上传
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
controller/DocumentController.java
|
||||
service/DocumentService.java
|
||||
service/TextExtractor.java
|
||||
service/VectorService.java
|
||||
|
||||
接口：POST /api/documents/upload
|
||||
功能：
|
||||
1. 接收文件（Word/PDF/Markdown）
|
||||
2. 提取纯文本
|
||||
3. 分块（chunk_size=500, overlap=50）
|
||||
4. 向量化（DashScopeEmbedding）
|
||||
5. 写 MySQL + Milvus
|
||||
|
||||
验收标准：
|
||||
✓ 上传成功返回 document_id
|
||||
✓ MySQL 记录正确
|
||||
✓ Milvus 向量正确
|
||||
✓ 单元测试覆盖
|
||||
```
|
||||
|
||||
#### 任务 4.2：文档查询
|
||||
|
||||
```java
|
||||
接口：
|
||||
- GET /api/documents/{id}
|
||||
- GET /api/documents?province=XX&category=YY
|
||||
|
||||
验收标准：
|
||||
✓ 分页查询
|
||||
✓ 过滤生效
|
||||
✓ 性能可接受（< 100ms）
|
||||
```
|
||||
|
||||
#### 任务 4.3：文档删除同步
|
||||
|
||||
```java
|
||||
接口：DELETE /api/documents/{id}
|
||||
|
||||
功能：
|
||||
- 删除 MySQL 记录
|
||||
- 同步删除 Milvus 向量
|
||||
- 事务一致性
|
||||
|
||||
验收标准：
|
||||
✓ MySQL + Milvus 同步删除
|
||||
✓ 事务回滚正确
|
||||
```
|
||||
|
||||
#### 任务 4.4：混合检索实现
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
tool/DocumentSearchTool.java
|
||||
|
||||
策略：
|
||||
1. 精确匹配（MySQL）
|
||||
2. 语义检索（Milvus）
|
||||
3. RRF 融合排序
|
||||
|
||||
验收标准：
|
||||
✓ 精确匹配优先
|
||||
✓ 语义检索补漏
|
||||
✓ 返回 Top 3
|
||||
✓ 单元测试覆盖
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2：核心功能（5天）
|
||||
|
||||
### Day 6-7：意图识别 + RAG
|
||||
|
||||
#### 任务 6.1：意图识别模块
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
intent/IntentClassifier.java
|
||||
intent/L0RulesMatcher.java
|
||||
intent/L1AgentClassifier.java
|
||||
intent/IntentResult.java
|
||||
|
||||
L0 规则匹配：
|
||||
- 正则：订单号、traceId、错误码
|
||||
- 关键词：报错、异常、失败
|
||||
- 返回：诊断/文档/案例/闲聊
|
||||
|
||||
L1 小模型 Agent：
|
||||
- 输入：用户原始输入
|
||||
- Prompt：分类意图
|
||||
- 输出：意图 + 置信度
|
||||
|
||||
验收标准：
|
||||
✓ L0 命中率 80%+
|
||||
✓ L1 准确率 90%+
|
||||
✓ 延迟 < 200ms
|
||||
✓ 单元测试覆盖
|
||||
```
|
||||
|
||||
#### 任务 6.2：RAG 两层加载
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
rag/RagLoader.java
|
||||
rag/L1PreloadService.java
|
||||
rag/L2OnDemandService.java
|
||||
|
||||
L1 预加载：
|
||||
- 触发时机：意图识别后，Planner 启动前
|
||||
- 内容：通用领域知识（架构、流程、高频错误码）
|
||||
- 注入：Planner System Prompt
|
||||
|
||||
L2 按需加载：
|
||||
- 触发时机：Executor 拿到 errorCode 后
|
||||
- 内容：具体接口文档
|
||||
- 调用：searchDoc
|
||||
|
||||
验收标准：
|
||||
✓ L1 预加载成功
|
||||
✓ L2 按需调用成功
|
||||
✓ 单元测试覆盖
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Day 8-9：4 Agent 协作 + Skill
|
||||
|
||||
#### 任务 8.1：4 Agent 定义
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
agent/supervisor/SupervisorAgent.java
|
||||
agent/planner/PlannerAgent.java
|
||||
agent/executor/ExecutorAgent.java
|
||||
agent/verifier/VerifierAgent.java
|
||||
|
||||
配置文件：
|
||||
src/main/resources/prompts/
|
||||
├── supervisor-system.md
|
||||
├── planner-system.md
|
||||
├── executor-system.md
|
||||
└── verifier-system.md
|
||||
|
||||
技术栈：
|
||||
- Spring AI Alibaba
|
||||
- SupervisorAgent + ReactAgent
|
||||
- @Tool 注解
|
||||
|
||||
验收标准：
|
||||
✓ 4 Agent 注册成功
|
||||
✓ 协作流程跑通
|
||||
✓ Supervisor 调度正确
|
||||
```
|
||||
|
||||
#### 任务 8.2：Skill 实现
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
skill/SkillDefinition.java
|
||||
skill/DiagnoseByOrderIdSkill.java
|
||||
skill/SkillRegistry.java
|
||||
|
||||
工作流（6 步）：
|
||||
1. queryOrder
|
||||
2. searchDoc (L2 按需)
|
||||
3. queryLogs (Mock)
|
||||
4. recommendCase
|
||||
5. 生成报告
|
||||
6. Verifier 验证
|
||||
|
||||
验收标准：
|
||||
✓ 6 步流程正确
|
||||
✓ 失败处理正确（ABORT/SKIP）
|
||||
✓ 单元测试覆盖
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Day 10：工具层开发
|
||||
|
||||
#### 任务 10.1：queryOrder 工具
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
tool/QueryOrderTool.java
|
||||
|
||||
功能：
|
||||
- 只读查询 MySQL
|
||||
- 返回订单信息 + 错误信息
|
||||
- SQL 注入防护
|
||||
|
||||
验收标准：
|
||||
✓ 查询正确
|
||||
✓ 超时控制（10s）
|
||||
✓ 单元测试覆盖
|
||||
```
|
||||
|
||||
#### 任务 10.2：searchDoc 工具
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
tool/SearchDocTool.java
|
||||
|
||||
功能：
|
||||
- 调用混合检索
|
||||
- 返回 Top 3 文档片段
|
||||
|
||||
验收标准：
|
||||
✓ 调用成功
|
||||
✓ 结果格式正确
|
||||
✓ 单元测试覆盖
|
||||
```
|
||||
|
||||
#### 任务 10.3：recommendCase 工具
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
tool/RecommendCaseTool.java
|
||||
|
||||
功能：
|
||||
- 精确匹配：error_code + fault_category
|
||||
- 语义检索：description 向量相似度
|
||||
- RRF 融合
|
||||
|
||||
验收标准：
|
||||
✓ 推荐准确
|
||||
✓ 返回 Top 3
|
||||
✓ 单元测试覆盖
|
||||
```
|
||||
|
||||
#### 任务 10.4：getCurrentTime 工具
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
tool/GetCurrentTimeTool.java
|
||||
|
||||
功能：
|
||||
- 返回当前时间戳
|
||||
- 格式化输出
|
||||
|
||||
验收标准：
|
||||
✓ 返回正确
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3：闭环优化（3天）
|
||||
|
||||
### Day 11：Verifier + Harness
|
||||
|
||||
#### 任务 11.1：Verifier Agent
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
agent/verifier/VerifierAgent.java
|
||||
|
||||
验证逻辑：
|
||||
1. 事实核查（报告数据 vs 工具返回数据）
|
||||
2. 完整性检查（3 章节不能为空）
|
||||
|
||||
判决：
|
||||
- PASS：通过
|
||||
- REVISE：需修正
|
||||
- REJECT：驳回
|
||||
|
||||
验收标准：
|
||||
✓ 事实核查正确
|
||||
✓ 编造检测生效
|
||||
✓ 单元测试覆盖
|
||||
```
|
||||
|
||||
#### 任务 11.2：Harness 5 Gates
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
harness/gate/InputGates.java
|
||||
harness/gate/ExecutionGates.java
|
||||
harness/gate/OutputGates.java
|
||||
|
||||
门禁清单：
|
||||
- Gate 1: 输入参数非空
|
||||
- Gate 2: 5 分钟内重复 → 缓存
|
||||
- Gate 3: 工具超时（10s）
|
||||
- Gate 4: 报告完整性
|
||||
- Gate 5: 置信度阈值（60）
|
||||
|
||||
验收标准：
|
||||
✓ 5 Gates 生效
|
||||
✓ 中断机制正确
|
||||
✓ 单元测试覆盖
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Day 12：反馈机制 + 案例沉淀
|
||||
|
||||
#### 任务 12.1：反馈接口
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
controller/FeedbackController.java
|
||||
service/FeedbackService.java
|
||||
|
||||
接口：POST /api/diagnosis/{id}/feedback
|
||||
参数：useful / not_useful
|
||||
|
||||
功能：
|
||||
- 更新 diagnosis_record.feedback
|
||||
- useful → 自动生成 case_library
|
||||
|
||||
验收标准：
|
||||
✓ 反馈记录成功
|
||||
✓ 案例生成正确
|
||||
✓ 单元测试覆盖
|
||||
```
|
||||
|
||||
#### 任务 12.2：案例自动生成
|
||||
|
||||
```java
|
||||
产出文件：
|
||||
service/CaseGenerationService.java
|
||||
|
||||
触发条件：
|
||||
- feedback = useful
|
||||
- confidence >= 80
|
||||
|
||||
生成逻辑：
|
||||
- 提取关键信息
|
||||
- 生成 case_library 记录
|
||||
- 向量化 solution_steps
|
||||
|
||||
验收标准：
|
||||
✓ 案例生成正确
|
||||
✓ 向量化成功
|
||||
✓ 单元测试覆盖
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Day 13：端到端测试 + 验收
|
||||
|
||||
#### 任务 13.1：Mock 5 个场景
|
||||
|
||||
```
|
||||
场景 1：外部接口故障（广东社保 40003）
|
||||
场景 2：内部空指针异常
|
||||
场景 3：数据库连接超时
|
||||
场景 4：意图不明（闲聊）
|
||||
场景 5：缓存命中（重复诊断）
|
||||
|
||||
验收标准：
|
||||
✓ 5 个场景全部跑通
|
||||
✓ 诊断报告正确
|
||||
✓ 反馈闭环完整
|
||||
```
|
||||
|
||||
#### 任务 13.2：性能测试
|
||||
|
||||
```
|
||||
指标：
|
||||
- 诊断延迟 < 10s（P95）
|
||||
- 意图识别 < 200ms
|
||||
- 文档检索 < 500ms
|
||||
- 并发 10 QPS 稳定
|
||||
|
||||
验收标准：
|
||||
✓ 性能达标
|
||||
✓ 无内存泄漏
|
||||
✓ 无明显瓶颈
|
||||
```
|
||||
|
||||
#### 任务 13.3：文档更新
|
||||
|
||||
```
|
||||
产出文件：
|
||||
docs/
|
||||
├── API.md # 接口文档
|
||||
├── DEPLOYMENT.md # 部署指南
|
||||
└── TEST_REPORT.md # 测试报告
|
||||
|
||||
验收标准：
|
||||
✓ 文档完整
|
||||
✓ 部署可复现
|
||||
✓ 测试报告详实
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试要求
|
||||
|
||||
### 单元测试
|
||||
|
||||
```
|
||||
框架：JUnit 5 + Mockito
|
||||
覆盖率：
|
||||
- Repository: 100%
|
||||
- Service: 80%+
|
||||
- Tool: 80%+
|
||||
- Agent: 70%+
|
||||
- Controller: 70%+
|
||||
```
|
||||
|
||||
### 集成测试
|
||||
|
||||
```
|
||||
框架：@SpringBootTest
|
||||
覆盖：
|
||||
- Redis 集成
|
||||
- MySQL 集成
|
||||
- Milvus 集成
|
||||
- Agent 协作
|
||||
```
|
||||
|
||||
### E2E 测试
|
||||
|
||||
```
|
||||
工具：RestAssured
|
||||
场景：5 个 Mock 场景
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 实施记录格式
|
||||
|
||||
每完成一个任务，AI 在此文档追加：
|
||||
|
||||
```markdown
|
||||
---
|
||||
|
||||
## [完成] 任务 X.X：任务名称
|
||||
|
||||
**执行时间**：2026-XX-XX HH:mm
|
||||
|
||||
**产出文件**：
|
||||
- path/to/file1.java (126 行)
|
||||
- path/to/file2.java (89 行)
|
||||
|
||||
**关键决策**：
|
||||
- 决策点：选择方案 A，因为...
|
||||
- 权衡点：备选方案 B 的劣势是...
|
||||
|
||||
**遇到的问题**：
|
||||
- 问题：XXX
|
||||
- 解决方案：YYY
|
||||
- 影响范围：ZZZ
|
||||
|
||||
**测试结果**：
|
||||
✓ 单元测试：8/8 通过
|
||||
✓ 集成测试：3/3 通过
|
||||
✓ 代码覆盖率：85%
|
||||
|
||||
**验收状态**：⏳ 等待用户确认 / ✅ 已通过
|
||||
|
||||
**用户反馈**：（用户确认后填写）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 当前进度
|
||||
|
||||
```
|
||||
Phase 1: 基础设施（5天） [ ] 0%
|
||||
├─ Day 1-2: 数据库 + 实体 [ ] 未开始
|
||||
├─ Day 3: 代码结构重构 [ ] 未开始
|
||||
└─ Day 4-5: 文档管理 [ ] 未开始
|
||||
|
||||
Phase 2: 核心功能（5天） [ ] 0%
|
||||
├─ Day 6-7: 意图识别 + RAG [ ] 未开始
|
||||
├─ Day 8-9: Agent + Skill [ ] 未开始
|
||||
└─ Day 10: 工具层 [ ] 未开始
|
||||
|
||||
Phase 3: 闭环优化（3天） [ ] 0%
|
||||
├─ Day 11: Verifier + Harness [ ] 未开始
|
||||
├─ Day 12: 反馈 + 案例 [ ] 未开始
|
||||
└─ Day 13: E2E 测试 [ ] 未开始
|
||||
|
||||
总体进度：0/13 天
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
等待用户确认：
|
||||
1. ✅ 这个完整计划是否符合预期？
|
||||
2. 有没有需要调整的优先级？
|
||||
3. 有没有需要增删的任务？
|
||||
4. 确认后开始执行 Phase 1 Day 1-2。
|
||||
@@ -0,0 +1,211 @@
|
||||
# 实施规划
|
||||
|
||||
## Phase 1：核心功能（第1周）
|
||||
|
||||
### 实现内容
|
||||
```
|
||||
✅ diagnosis_record 表
|
||||
✅ case_library 表
|
||||
✅ api_document 表
|
||||
✅ Redis 会话管理
|
||||
✅ 单次诊断流程
|
||||
```
|
||||
|
||||
### 不实现
|
||||
```
|
||||
❌ conversation_history 表（先不加）
|
||||
❌ 会话同步（先不做）
|
||||
❌ 追问功能（先不支持）
|
||||
```
|
||||
|
||||
### 验收标准
|
||||
```
|
||||
- 用户输入订单号 → 返回诊断报告
|
||||
- 诊断记录持久化到 MySQL
|
||||
- 可以查询历史诊断
|
||||
- 可以统计诊断成功率
|
||||
- 文档可以导入、查询、删除
|
||||
- 案例可以推荐
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 2：追问功能（第2周）
|
||||
|
||||
### 实现内容
|
||||
```
|
||||
✅ 支持多轮对话（基于 Redis 上下文）
|
||||
✅ conversation_history 表（可选）
|
||||
✅ 会话上下文管理
|
||||
```
|
||||
|
||||
### 验收标准
|
||||
```
|
||||
- 用户可以追问细节
|
||||
- Agent 能基于上下文回答
|
||||
- 追问不创建新的诊断记录
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3：优化分析（第3周）
|
||||
|
||||
### 实现内容
|
||||
```
|
||||
✅ 会话同步（Redis → MySQL）
|
||||
✅ BadCase 分析
|
||||
✅ 追问频率统计
|
||||
✅ 案例质量评分
|
||||
```
|
||||
|
||||
### 验收标准
|
||||
```
|
||||
- 重要会话自动同步到 MySQL
|
||||
- 可以分析用户追问模式
|
||||
- 可以优化 Prompt 和功能
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 技术债务清单
|
||||
|
||||
### 待优化项（Phase 4+）
|
||||
|
||||
```
|
||||
1. api_document 增强
|
||||
- 软删除（archived_at）
|
||||
- 启用开关（enabled）
|
||||
- 批次管理（batch_id）
|
||||
- 状态细化（PARSING/SPLITTING/INDEXING...）
|
||||
|
||||
2. case_library 增强
|
||||
- 复杂评分（useful_count + score）
|
||||
- 标签分类（tags）
|
||||
- 版本管理
|
||||
- 案例合并
|
||||
|
||||
3. 性能优化
|
||||
- Redis 缓存有效文档列表
|
||||
- 分页查询优化
|
||||
- 索引优化
|
||||
|
||||
4. 监控告警
|
||||
- 诊断成功率监控
|
||||
- 诊断耗时监控
|
||||
- 文档索引状态监控
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数据迁移计划
|
||||
|
||||
### 如果已有旧数据
|
||||
|
||||
```
|
||||
1. diagnosis_record 迁移
|
||||
- 旧字段 → 新字段映射
|
||||
- order_id → business_id
|
||||
- province → fault_source
|
||||
- api_url → fault_target
|
||||
|
||||
2. 执行迁移脚本
|
||||
UPDATE diagnosis_record SET
|
||||
business_id = order_id,
|
||||
fault_category = 'EXTERNAL_API',
|
||||
fault_source = province,
|
||||
fault_target = api_url
|
||||
WHERE fault_category IS NULL;
|
||||
|
||||
3. 验证数据一致性
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 部署检查清单
|
||||
|
||||
### Phase 1 部署前
|
||||
|
||||
```
|
||||
□ MySQL 数据库已创建
|
||||
□ 三张核心表已创建（diagnosis_record/case_library/api_document）
|
||||
□ Redis 已配置并可连接
|
||||
□ Milvus Collection 已创建
|
||||
□ 向量化服务（DashScope）配置正确
|
||||
□ 文件上传目录已创建并有写权限
|
||||
□ 应用配置文件检查完成
|
||||
```
|
||||
|
||||
### 配置文件示例
|
||||
|
||||
```yaml
|
||||
# application.yml
|
||||
spring:
|
||||
datasource:
|
||||
url: jdbc:mysql://localhost:3306/diagnosis_system
|
||||
username: root
|
||||
password: xxx
|
||||
|
||||
redis:
|
||||
host: localhost
|
||||
port: 6379
|
||||
database: 0
|
||||
|
||||
milvus:
|
||||
host: localhost
|
||||
port: 19530
|
||||
collection-name: api_doc_collection
|
||||
|
||||
dashscope:
|
||||
api-key: sk-xxx
|
||||
|
||||
file:
|
||||
upload:
|
||||
path: /data/uploads
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 回滚方案
|
||||
|
||||
### 数据库回滚
|
||||
|
||||
```sql
|
||||
-- 保留旧表备份
|
||||
CREATE TABLE diagnosis_record_backup_20240622 AS SELECT * FROM diagnosis_record;
|
||||
|
||||
-- 回滚时恢复
|
||||
DROP TABLE diagnosis_record;
|
||||
RENAME TABLE diagnosis_record_backup_20240622 TO diagnosis_record;
|
||||
```
|
||||
|
||||
### Milvus 回滚
|
||||
|
||||
```
|
||||
- Milvus 数据无法回滚
|
||||
- 建议：重要操作前先备份 Collection
|
||||
- 或者：保留原始文件，可重新索引
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 监控指标
|
||||
|
||||
### 核心指标
|
||||
|
||||
```
|
||||
1. 诊断成功率
|
||||
- 目标：> 85%
|
||||
- 告警：< 80%
|
||||
|
||||
2. 诊断耗时
|
||||
- 目标：P95 < 10s
|
||||
- 告警：P95 > 15s
|
||||
|
||||
3. 文档索引成功率
|
||||
- 目标：> 95%
|
||||
- 告警：< 90%
|
||||
|
||||
4. 案例推荐准确率
|
||||
- 目标：> 70%
|
||||
- 评估：用户反馈
|
||||
```
|
||||
@@ -0,0 +1,210 @@
|
||||
# 会话管理设计
|
||||
|
||||
## 会话存储策略
|
||||
|
||||
### Redis（主）
|
||||
|
||||
**数据结构**：
|
||||
```
|
||||
key: session:{session_id}
|
||||
value: {
|
||||
"sessionId": "sess-abc",
|
||||
"userId": "user-123",
|
||||
"currentDiagnosisId": "diag-001",
|
||||
"messages": [
|
||||
{"role": "user", "content": "诊断订单 A"},
|
||||
{"role": "assistant", "content": "完整报告..."}
|
||||
],
|
||||
"context": {
|
||||
"province": "广东",
|
||||
"apiName": "社保查询",
|
||||
"errorCode": "40003"
|
||||
},
|
||||
"createdAt": "2024-06-15T14:30:00Z",
|
||||
"lastActiveAt": "2024-06-15T14:35:00Z"
|
||||
}
|
||||
ttl: 1800秒（30分钟）
|
||||
```
|
||||
|
||||
**优势**：
|
||||
- ✅ 快速读写
|
||||
- ✅ 自动过期
|
||||
- ✅ 支持追问（保存上下文）
|
||||
|
||||
---
|
||||
|
||||
### MySQL（辅助，可选）
|
||||
|
||||
**同步策略**：
|
||||
1. 重要会话同步
|
||||
- 有用户反馈的会话
|
||||
- 诊断失败的会话（BadCase）
|
||||
- 多轮对话 > 3 轮的会话
|
||||
|
||||
2. 同步时机
|
||||
- 会话结束时（30分钟过期）
|
||||
- 用户反馈时（实时）
|
||||
- 定时任务（每小时，可选）
|
||||
|
||||
3. 同步目标
|
||||
- conversation_history 表
|
||||
- 用于长期分析和审计
|
||||
|
||||
---
|
||||
|
||||
## 数据流设计
|
||||
|
||||
### 场景1：单次诊断（主流 80%）
|
||||
|
||||
```
|
||||
1. 用户发起诊断
|
||||
POST /api/diagnosis/start
|
||||
{
|
||||
"orderId": "202406150001"
|
||||
}
|
||||
|
||||
2. 创建会话（Redis）
|
||||
key: session:sess-abc
|
||||
ttl: 1800秒
|
||||
|
||||
3. 创建诊断记录（MySQL）
|
||||
INSERT INTO diagnosis_record
|
||||
- diagnosis_id: diag-001
|
||||
- session_id: sess-abc
|
||||
- status: RUNNING
|
||||
|
||||
4. Agent 执行诊断
|
||||
- 调用工具（queryOrder, queryLogs, searchDoc...）
|
||||
- 生成报告
|
||||
|
||||
5. 更新诊断记录（MySQL）
|
||||
UPDATE diagnosis_record
|
||||
- status: SUCCESS
|
||||
- root_cause: "idCard字段缺失"
|
||||
- report_markdown: "完整报告..."
|
||||
|
||||
6. 返回报告
|
||||
→ 大部分用户到此结束
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 场景2：追问（少数 20%）
|
||||
|
||||
```
|
||||
1. 用户追问
|
||||
POST /api/chat
|
||||
{
|
||||
"sessionId": "sess-abc",
|
||||
"message": "为什么会缺失字段？"
|
||||
}
|
||||
|
||||
2. 从 Redis 获取上下文
|
||||
GET session:sess-abc
|
||||
- 有之前的诊断结果
|
||||
- 有对话历史
|
||||
|
||||
3. Agent 基于上下文回答
|
||||
- 不创建新的 diagnosis_record
|
||||
- 只是普通对话
|
||||
|
||||
4. 更新 Redis 会话
|
||||
- 追加对话历史
|
||||
- 刷新 TTL（重新计时30分钟）
|
||||
|
||||
5. 可选：保存到 conversation_history（MySQL）
|
||||
- 如果需要长期分析
|
||||
- 异步存储
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 场景3：同一会话多次诊断
|
||||
|
||||
```
|
||||
1. 用户第一次诊断
|
||||
"诊断订单 A"
|
||||
→ diagnosis_record（diag-001, session_id=sess-abc）
|
||||
|
||||
2. 用户第二次诊断
|
||||
"再诊断订单 B"
|
||||
→ diagnosis_record（diag-002, session_id=sess-abc）
|
||||
|
||||
3. 会话关联
|
||||
- 同一个 session_id
|
||||
- 两条 diagnosis_record
|
||||
- Redis 中保存完整对话历史
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 会话生命周期
|
||||
|
||||
```
|
||||
创建
|
||||
↓
|
||||
活跃（每次交互刷新TTL）
|
||||
↓
|
||||
30分钟无活动
|
||||
↓
|
||||
自动过期
|
||||
↓
|
||||
可选：同步到 MySQL（重要会话）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 实现示例
|
||||
|
||||
### Java 代码
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class SessionService {
|
||||
|
||||
@Autowired
|
||||
private RedisTemplate<String, String> redisTemplate;
|
||||
|
||||
private static final String SESSION_PREFIX = "session:";
|
||||
private static final Duration SESSION_TTL = Duration.ofMinutes(30);
|
||||
|
||||
// 创建会话
|
||||
public String createSession(String userId) {
|
||||
String sessionId = UUID.randomUUID().toString();
|
||||
|
||||
SessionData session = SessionData.builder()
|
||||
.sessionId(sessionId)
|
||||
.userId(userId)
|
||||
.messages(new ArrayList<>())
|
||||
.context(new HashMap<>())
|
||||
.createdAt(LocalDateTime.now())
|
||||
.lastActiveAt(LocalDateTime.now())
|
||||
.build();
|
||||
|
||||
String key = SESSION_PREFIX + sessionId;
|
||||
redisTemplate.opsForValue().set(key, toJson(session), SESSION_TTL);
|
||||
|
||||
return sessionId;
|
||||
}
|
||||
|
||||
// 获取会话
|
||||
public SessionData getSession(String sessionId) {
|
||||
String key = SESSION_PREFIX + sessionId;
|
||||
String json = redisTemplate.opsForValue().get(key);
|
||||
return json != null ? fromJson(json) : null;
|
||||
}
|
||||
|
||||
// 更新会话（刷新TTL）
|
||||
public void updateSession(SessionData session) {
|
||||
session.setLastActiveAt(LocalDateTime.now());
|
||||
String key = SESSION_PREFIX + session.getSessionId();
|
||||
redisTemplate.opsForValue().set(key, toJson(session), SESSION_TTL);
|
||||
}
|
||||
|
||||
// 删除会话
|
||||
public void deleteSession(String sessionId) {
|
||||
String key = SESSION_PREFIX + sessionId;
|
||||
redisTemplate.delete(key);
|
||||
}
|
||||
}
|
||||
```
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,155 @@
|
||||
# 数据库设计文档
|
||||
|
||||
## 📚 文档导航
|
||||
|
||||
### 核心表设计
|
||||
- [diagnosis_record](tables/diagnosis_record.md) - 诊断记录表（核心）
|
||||
- [case_library](tables/case_library.md) - 案例库表
|
||||
- [api_document](tables/api_document.md) - 文档元数据表
|
||||
|
||||
### 架构设计
|
||||
- [Agent 架构设计](architecture/agent-architecture.md) - Agent 协作 + Skill + Harness
|
||||
- [会话管理](architecture/session-management.md) - Redis + MySQL 会话管理
|
||||
- [实施规划](architecture/implementation-plan.md) - 分阶段实施计划
|
||||
|
||||
---
|
||||
|
||||
## 一、设计原则
|
||||
|
||||
### 1.1 核心原则
|
||||
- ✅ **简单优先**：满足诊断流程需要，避免过度设计
|
||||
- ✅ **渐进增强**：先实现核心功能，再逐步扩展
|
||||
- ✅ **数据分离**：诊断结果持久化（MySQL），会话上下文临时化（Redis）
|
||||
- ✅ **适度冗余**：避免过度范式化，适当冗余提升查询性能
|
||||
|
||||
### 1.2 系统定位
|
||||
**自动化诊断系统**
|
||||
- 核心：一键诊断 → 返回完整报告
|
||||
- 辅助：支持追问，但不是主要场景
|
||||
- 特点：大部分用户单次诊断即结束，少数用户会追问细节
|
||||
|
||||
---
|
||||
|
||||
## 二、表结构总览
|
||||
|
||||
### 2.1 核心表关系
|
||||
|
||||
```
|
||||
┌─────────────────────┐
|
||||
│ diagnosis_record │ 诊断记录（核心）
|
||||
│ - 每次诊断一条 │
|
||||
└──────────┬──────────┘
|
||||
│ 1:1
|
||||
↓
|
||||
┌─────────────────────┐
|
||||
│ case_library │ 案例库（知识沉淀）
|
||||
│ - 诊断成功→案例 │
|
||||
└─────────────────────┘
|
||||
|
||||
┌─────────────────────┐
|
||||
│ api_document │ 文档元数据（管理层）
|
||||
│ - 状态追踪/去重 │
|
||||
└──────────┬──────────┘
|
||||
│ doc_id
|
||||
↓
|
||||
┌─────────────────────┐
|
||||
│ Milvus │ 文档内容（检索层）
|
||||
│ - 向量检索 │
|
||||
└─────────────────────┘
|
||||
|
||||
┌─────────────────────┐
|
||||
│ Redis Session │ 会话管理（临时）
|
||||
│ - 30分钟过期 │
|
||||
│ - 支持追问 │
|
||||
└─────────────────────┘
|
||||
```
|
||||
|
||||
### 2.2 表统计
|
||||
|
||||
| 表名 | 类型 | 预估数据量 | 用途 |
|
||||
|------|------|-----------|------|
|
||||
| diagnosis_record | 核心 | 3.6万/年 | 诊断记录 |
|
||||
| case_library | 核心 | 500-1000 | 案例库 |
|
||||
| api_document | 核心 | 100-200 | 文档管理 |
|
||||
|
||||
---
|
||||
|
||||
## 三、技术栈
|
||||
|
||||
### 3.1 数据存储
|
||||
```
|
||||
MySQL 8.0+
|
||||
├─ 元数据管理
|
||||
├─ 事务支持
|
||||
└─ JSON 字段支持
|
||||
|
||||
Redis 6.0+
|
||||
├─ 会话存储
|
||||
├─ 缓存
|
||||
└─ TTL 自动过期
|
||||
|
||||
Milvus 2.6+
|
||||
├─ 向量存储
|
||||
├─ 语义检索
|
||||
└─ 混合检索
|
||||
```
|
||||
|
||||
### 3.2 开发框架
|
||||
```
|
||||
Spring Boot 3.2
|
||||
Spring AI Alibaba 1.1.0
|
||||
Milvus SDK Java 2.6.10
|
||||
DashScope SDK
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、快速开始
|
||||
|
||||
### 4.1 创建数据库
|
||||
|
||||
```sql
|
||||
-- 1. 创建数据库
|
||||
CREATE DATABASE diagnosis_system CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
|
||||
-- 2. 执行建表脚本（按顺序）
|
||||
SOURCE tables/diagnosis_record.sql;
|
||||
SOURCE tables/case_library.sql;
|
||||
SOURCE tables/api_document.sql;
|
||||
```
|
||||
|
||||
### 4.2 初始化 Milvus
|
||||
|
||||
```java
|
||||
// 创建 Collection
|
||||
MilvusClientFactory.createCollection();
|
||||
```
|
||||
|
||||
### 4.3 配置 Redis
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
redis:
|
||||
host: localhost
|
||||
port: 6379
|
||||
database: 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、版本历史
|
||||
|
||||
| 版本 | 日期 | 变更内容 |
|
||||
|------|------|---------|
|
||||
| v1.0 | 2024-06-15 | 初版，定义核心表结构 |
|
||||
| v2.0 | 2024-06-15 | diagnosis_record 字段泛化，支持多种故障类型 |
|
||||
| v2.1 | 2024-06-22 | 文档拆分，增加 api_document 表 |
|
||||
|
||||
---
|
||||
|
||||
## 六、维护说明
|
||||
|
||||
- 每个表的详细设计在 `tables/` 目录下
|
||||
- 架构设计文档在 `architecture/` 目录下
|
||||
- 修改表结构时，同步更新对应的 Markdown 文档
|
||||
- 重大变更需记录在版本历史中
|
||||
@@ -0,0 +1,332 @@
|
||||
# api_document - 文档元数据表
|
||||
|
||||
## 表定位
|
||||
|
||||
**文档管理表**：管理接口文档的元信息，不负责文档检索（检索由 Milvus 负责）
|
||||
|
||||
## 设计理念
|
||||
|
||||
### 文档管理，不是文档检索
|
||||
|
||||
**核心定位**：
|
||||
- MySQL 负责文档元数据管理（状态、版本、去重）
|
||||
- Milvus 负责文档内容存储和检索
|
||||
- 通过 doc_id 关联两者
|
||||
|
||||
**MVP版本原则**：
|
||||
- ✅ 最简字段，满足基本管理需求
|
||||
- ✅ 文件去重（基于 file_hash）
|
||||
- ✅ 状态追踪（索引进度）
|
||||
- ✅ 硬删除（同步删除 Milvus 数据）
|
||||
- ❌ 暂不支持：软删除、启用开关、版本管理（Phase 2）
|
||||
|
||||
---
|
||||
|
||||
## 表结构（MVP版）
|
||||
|
||||
```sql
|
||||
CREATE TABLE api_document (
|
||||
-- 主键
|
||||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||||
doc_id VARCHAR(64) UNIQUE NOT NULL COMMENT '文档唯一ID（UUID），关联Milvus',
|
||||
|
||||
-- 文档分类
|
||||
fault_category VARCHAR(32) DEFAULT 'EXTERNAL_API' COMMENT '文档类别',
|
||||
fault_source VARCHAR(128) COMMENT '文档归属（省份/服务名）',
|
||||
api_name VARCHAR(128) COMMENT '接口名称',
|
||||
version VARCHAR(32) DEFAULT 'v1.0' COMMENT '文档版本',
|
||||
|
||||
-- 文件信息
|
||||
file_name VARCHAR(256) NOT NULL COMMENT '原始文件名',
|
||||
file_path VARCHAR(512) COMMENT '文件存储路径',
|
||||
file_hash VARCHAR(64) COMMENT '文件MD5 hash（用于去重）',
|
||||
file_size BIGINT COMMENT '文件大小（字节）',
|
||||
|
||||
-- 索引状态
|
||||
status VARCHAR(16) DEFAULT 'PENDING' COMMENT '索引状态（PENDING/PROCESSING/INDEXED/FAILED）',
|
||||
chunk_count INT DEFAULT 0 COMMENT '分块数量',
|
||||
error_message TEXT COMMENT '失败原因',
|
||||
|
||||
-- 时间字段
|
||||
indexed_at DATETIME COMMENT '索引完成时间',
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||||
|
||||
-- 索引
|
||||
UNIQUE INDEX uk_file_hash (file_hash),
|
||||
INDEX idx_doc_id (doc_id),
|
||||
INDEX idx_fault_source (fault_source),
|
||||
INDEX idx_status (status),
|
||||
INDEX idx_created_at (created_at)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文档元数据表（MVP版）';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 字段说明
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| doc_id | VARCHAR(64) | 是 | **核心**：文档唯一ID，关联 Milvus |
|
||||
| fault_category | VARCHAR(32) | 否 | 文档类别 |
|
||||
| fault_source | VARCHAR(128) | 否 | 文档归属（省份/服务名）|
|
||||
| api_name | VARCHAR(128) | 否 | 接口名称 |
|
||||
| version | VARCHAR(32) | 否 | 文档版本 |
|
||||
| file_name | VARCHAR(256) | 是 | 原始文件名 |
|
||||
| file_path | VARCHAR(512) | 否 | 文件存储路径 |
|
||||
| file_hash | VARCHAR(64) | 否 | **去重关键**：文件MD5 |
|
||||
| file_size | BIGINT | 否 | 文件大小 |
|
||||
| status | VARCHAR(16) | 是 | **状态追踪**：PENDING/PROCESSING/INDEXED/FAILED |
|
||||
| chunk_count | INT | 否 | 分块数量 |
|
||||
| error_message | TEXT | 否 | 失败原因 |
|
||||
| indexed_at | DATETIME | 否 | 索引完成时间 |
|
||||
|
||||
---
|
||||
|
||||
## 核心设计决策
|
||||
|
||||
### 1. doc_id：MySQL 与 Milvus 的桥梁
|
||||
|
||||
```
|
||||
作用：
|
||||
- MySQL：通过 doc_id 管理文档元数据
|
||||
- Milvus：每个 chunk 的 metadata 中携带 doc_id
|
||||
|
||||
关联关系：
|
||||
api_document (MySQL)
|
||||
doc_id: doc-001
|
||||
↓ 1:N
|
||||
Milvus chunks
|
||||
chunk_1: {doc_id: 'doc-001', text: '...', vector: [...]}
|
||||
chunk_2: {doc_id: 'doc-001', text: '...', vector: [...]}
|
||||
|
||||
管理操作：
|
||||
- 删除文档：
|
||||
DELETE FROM milvus_collection WHERE metadata["doc_id"] == 'doc-001';
|
||||
DELETE FROM api_document WHERE doc_id = 'doc-001';
|
||||
```
|
||||
|
||||
### 2. file_hash：文件去重
|
||||
|
||||
```
|
||||
去重流程：
|
||||
1. 用户上传文件
|
||||
↓
|
||||
2. 计算文件 MD5
|
||||
file_hash = md5(file_content)
|
||||
↓
|
||||
3. 检查是否已存在
|
||||
SELECT * FROM api_document WHERE file_hash = 'abc123...';
|
||||
↓
|
||||
4a. 如果存在 → 提示"文档已存在"
|
||||
4b. 如果不存在 → 继续导入
|
||||
|
||||
唯一约束：UNIQUE INDEX uk_file_hash (file_hash)
|
||||
```
|
||||
|
||||
### 3. status：状态追踪
|
||||
|
||||
```
|
||||
状态流转：
|
||||
PENDING (待处理)
|
||||
↓
|
||||
PROCESSING (处理中)
|
||||
↓ 成功
|
||||
INDEXED (已索引)
|
||||
↓ 失败
|
||||
FAILED (失败)
|
||||
|
||||
用途：
|
||||
- 批量导入时监控进度
|
||||
- 失败重试
|
||||
- 统计索引成功率
|
||||
```
|
||||
|
||||
### 4. 硬删除策略（MVP）
|
||||
|
||||
```
|
||||
删除文档时：
|
||||
1. 删除 Milvus 中的所有分块
|
||||
2. 删除 MySQL 元数据
|
||||
3. 可选：删除原始文件
|
||||
|
||||
特点：
|
||||
- 简单直接
|
||||
- 数据彻底删除
|
||||
- 不可恢复（需谨慎）
|
||||
|
||||
Phase 2 可增强：
|
||||
- 软删除（archived_at）
|
||||
- 启用开关（enabled）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数据流
|
||||
|
||||
### 场景1：导入新文档
|
||||
|
||||
```
|
||||
1. 用户上传文件
|
||||
↓
|
||||
2. 计算 hash
|
||||
↓
|
||||
3. 检查去重（MySQL）
|
||||
↓
|
||||
4. 插入元数据（status=PROCESSING）
|
||||
↓
|
||||
5. 后台处理：解析 → 分块 → 向量化 → 存入 Milvus
|
||||
↓
|
||||
6. 更新状态（status=INDEXED, chunk_count=15）
|
||||
```
|
||||
|
||||
### 场景2：删除文档
|
||||
|
||||
```
|
||||
1. 用户删除文档
|
||||
↓
|
||||
2. 删除 Milvus 数据（WHERE metadata["doc_id"] == 'xxx'）
|
||||
↓
|
||||
3. 删除 MySQL 元数据
|
||||
↓
|
||||
4. 可选：删除原始文件
|
||||
```
|
||||
|
||||
### 场景3：重新索引
|
||||
|
||||
```
|
||||
1. 删除旧数据（Milvus + MySQL）
|
||||
↓
|
||||
2. 重新导入（同场景1）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 典型查询
|
||||
|
||||
```sql
|
||||
-- 查看文档列表
|
||||
SELECT doc_id, file_name, version, status, chunk_count, indexed_at
|
||||
FROM api_document
|
||||
WHERE fault_source = '广东'
|
||||
AND status = 'INDEXED'
|
||||
ORDER BY indexed_at DESC;
|
||||
|
||||
-- 查询失败的文档
|
||||
SELECT doc_id, file_name, error_message
|
||||
FROM api_document
|
||||
WHERE status = 'FAILED';
|
||||
|
||||
-- 统计各状态文档数量
|
||||
SELECT status, COUNT(*) as count
|
||||
FROM api_document
|
||||
GROUP BY status;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 与 Milvus 的协作
|
||||
|
||||
### Milvus Collection Schema
|
||||
|
||||
```python
|
||||
{
|
||||
"collection_name": "api_doc_collection",
|
||||
"fields": [
|
||||
{"name": "id", "type": "VARCHAR", "is_primary": true},
|
||||
{"name": "content", "type": "VARCHAR"},
|
||||
{"name": "vector", "type": "FLOAT_VECTOR", "dim": 1536},
|
||||
{"name": "metadata", "type": "JSON"}
|
||||
]
|
||||
}
|
||||
|
||||
# metadata 结构
|
||||
{
|
||||
"doc_id": "doc-001", # 关联 MySQL
|
||||
"_source": "/path/to/file",
|
||||
"_file_name": "xxx.docx",
|
||||
"chunkIndex": 0,
|
||||
"totalChunks": 15
|
||||
}
|
||||
```
|
||||
|
||||
### Java 代码示例
|
||||
|
||||
```java
|
||||
// 插入时携带 doc_id
|
||||
Map<String, Object> metadata = new HashMap<>();
|
||||
metadata.put("doc_id", docId); // 关联 MySQL
|
||||
metadata.put("_source", filePath);
|
||||
metadata.put("chunkIndex", chunkIndex);
|
||||
|
||||
// 删除文档的所有分块
|
||||
String expr = String.format("metadata[\"doc_id\"] == \"%s\"", docId);
|
||||
milvusClient.delete(DeleteParam.newBuilder()
|
||||
.withCollectionName(COLLECTION_NAME)
|
||||
.withExpr(expr)
|
||||
.build());
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数据示例
|
||||
|
||||
```sql
|
||||
-- 外部接口文档
|
||||
INSERT INTO api_document VALUES
|
||||
(1, 'doc-001', 'EXTERNAL_API', '广东', '社保查询', 'v2.1',
|
||||
'广东社保查询v2.1.docx', '/docs/guangdong/social-v2.1.docx',
|
||||
'abc123...', 1048576,
|
||||
'INDEXED', 15, NULL, '2024-06-15 10:30:00', NOW(), NOW());
|
||||
|
||||
-- 内部服务文档
|
||||
INSERT INTO api_document VALUES
|
||||
(2, 'doc-002', 'INTERNAL_ERROR', 'order-service', '订单服务API', 'v1.0',
|
||||
'订单服务API文档.pdf', '/docs/internal/order-service-api.pdf',
|
||||
'def456...', 2097152,
|
||||
'INDEXED', 20, NULL, '2024-06-14 15:20:00', NOW(), NOW());
|
||||
|
||||
-- 处理失败的文档
|
||||
INSERT INTO api_document VALUES
|
||||
(3, 'doc-003', 'EXTERNAL_API', '江苏', '公积金查询', 'v1.5',
|
||||
'江苏公积金查询.html', '/docs/jiangsu/fund-v1.5.html',
|
||||
'ghi789...', 512000,
|
||||
'FAILED', 0, '不支持HTML格式', NULL, NOW(), NOW());
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数据量预估
|
||||
|
||||
```
|
||||
预估：100-200 条
|
||||
- 外部接口文档：50-100 条
|
||||
- 内部服务文档：20-50 条
|
||||
- 其他文档：30-50 条
|
||||
|
||||
存储：
|
||||
- 单条记录：约 1KB
|
||||
- 200 条：约 200KB
|
||||
|
||||
结论：数据量很小
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MVP 版本的简化
|
||||
|
||||
```
|
||||
Phase 1（当前）：
|
||||
✅ 基础字段和表结构
|
||||
✅ 文件去重（file_hash）
|
||||
✅ 状态追踪（status）
|
||||
✅ 硬删除
|
||||
✅ 通过 doc_id 关联 Milvus
|
||||
|
||||
Phase 2（未来增强）：
|
||||
❌ enabled（启用开关）
|
||||
❌ archived_at（软删除）
|
||||
❌ batch_id（批次管理）
|
||||
❌ status 细化
|
||||
❌ tags（标签分类）
|
||||
```
|
||||
@@ -0,0 +1,265 @@
|
||||
# case_library - 案例库表
|
||||
|
||||
## 表定位
|
||||
|
||||
**知识沉淀表**：存储高质量诊断案例，支持相似案例推荐
|
||||
|
||||
## 设计理念
|
||||
|
||||
### 知识沉淀，系统越用越智能
|
||||
|
||||
**核心价值**：
|
||||
- 质量过滤：只存储高质量案例（成功诊断 + 用户反馈有用）
|
||||
- 知识沉淀：历史诊断经验可复用
|
||||
- 提升准确率：相似问题提供历史参考
|
||||
- 加速诊断：快速推荐相似案例
|
||||
|
||||
**MVP版本设计原则**：
|
||||
- ✅ 能用：满足基本案例推荐功能
|
||||
- ✅ 简单：字段不多，逻辑清晰
|
||||
- ✅ 可扩展：后续可增加字段
|
||||
|
||||
---
|
||||
|
||||
## 表结构（MVP版）
|
||||
|
||||
```sql
|
||||
CREATE TABLE case_library (
|
||||
-- 主键
|
||||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||||
case_id VARCHAR(64) UNIQUE NOT NULL COMMENT '案例唯一ID（UUID）',
|
||||
|
||||
-- 来源关联
|
||||
diagnosis_id VARCHAR(64) COMMENT '关联诊断记录（可选，人工录入时为空）',
|
||||
source_type VARCHAR(16) DEFAULT 'AUTO' COMMENT '来源类型（AUTO:自动生成/MANUAL:人工录入）',
|
||||
|
||||
-- 案例分类
|
||||
fault_category VARCHAR(32) COMMENT '故障类别（EXTERNAL_API/INTERNAL_ERROR/DATABASE...）',
|
||||
fault_source VARCHAR(128) COMMENT '故障源（省份/服务名/类名...）',
|
||||
fault_target VARCHAR(256) COMMENT '故障目标（接口URL/方法名/SQL...）',
|
||||
error_code VARCHAR(64) COMMENT '错误码',
|
||||
|
||||
-- 案例内容
|
||||
title VARCHAR(256) NOT NULL COMMENT '案例标题（简短描述）',
|
||||
root_cause TEXT NOT NULL COMMENT '根因分析',
|
||||
solution TEXT NOT NULL COMMENT '解决方案',
|
||||
|
||||
-- 简单统计
|
||||
reference_count INT DEFAULT 0 COMMENT '引用次数（被推荐的次数）',
|
||||
|
||||
-- 元数据
|
||||
created_by VARCHAR(64) COMMENT '创建人',
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||||
|
||||
-- 索引
|
||||
INDEX idx_fault_category (fault_category),
|
||||
INDEX idx_error_code (error_code),
|
||||
INDEX idx_fault_source (fault_source),
|
||||
INDEX idx_fault_target (fault_target(100)),
|
||||
INDEX idx_diagnosis_id (diagnosis_id),
|
||||
INDEX idx_reference_count (reference_count),
|
||||
INDEX idx_created_at (created_at)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='案例库表（MVP版）';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 字段说明
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| case_id | VARCHAR(64) | 是 | 案例唯一标识（UUID）|
|
||||
| diagnosis_id | VARCHAR(64) | 否 | 关联诊断记录（人工录入时为空）|
|
||||
| source_type | VARCHAR(16) | 是 | 来源：AUTO（自动）/MANUAL（人工）|
|
||||
| fault_category | VARCHAR(32) | 否 | 故障类别 |
|
||||
| fault_source | VARCHAR(128) | 否 | 故障源 |
|
||||
| fault_target | VARCHAR(256) | 否 | 故障目标（与 diagnosis_record 一致）|
|
||||
| error_code | VARCHAR(64) | 否 | 错误码 |
|
||||
| title | VARCHAR(256) | 是 | 案例标题 |
|
||||
| root_cause | TEXT | 是 | 根因分析（核心内容）|
|
||||
| solution | TEXT | 是 | 解决方案（核心内容）|
|
||||
| reference_count | INT | 是 | 引用次数（用于排序）|
|
||||
|
||||
---
|
||||
|
||||
## 核心设计决策
|
||||
|
||||
### 1. 案例来源
|
||||
|
||||
```
|
||||
来源1：自动生成（source_type=AUTO）
|
||||
├─ 触发条件：诊断成功 + 用户反馈"有用"
|
||||
├─ 关联诊断：diagnosis_id 不为空
|
||||
└─ 质量保证：用户验证过
|
||||
|
||||
来源2：人工录入（source_type=MANUAL）
|
||||
├─ 运维团队总结的经典案例
|
||||
├─ diagnosis_id 为空
|
||||
└─ 质量最高
|
||||
|
||||
注意：诊断失败或用户反馈"无用"的不自动生成案例
|
||||
```
|
||||
|
||||
### 2. 简化的评分机制（MVP）
|
||||
|
||||
```
|
||||
MVP版本：只按 reference_count 排序
|
||||
- 引用次数多的排前面
|
||||
- 简单有效
|
||||
|
||||
Phase 2 可增强：
|
||||
- 增加 useful_count（用户反馈有用次数）
|
||||
- 增加 score（综合评分）
|
||||
- 增加 is_featured（人工标记的经典案例）
|
||||
```
|
||||
|
||||
### 3. 与 diagnosis_record 的关系
|
||||
|
||||
```
|
||||
关系：一对一（可选）
|
||||
- 一次诊断 → 可以生成一个案例
|
||||
- 通过 diagnosis_id 关联
|
||||
- diagnosis_id 可为空（人工录入案例）
|
||||
|
||||
流程：
|
||||
diagnosis_record（成功）
|
||||
↓
|
||||
用户反馈"有用"
|
||||
↓
|
||||
自动生成 case_library
|
||||
↓
|
||||
后续可人工修正、合并相似案例
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数据示例
|
||||
|
||||
### 示例1：外部接口故障案例
|
||||
```sql
|
||||
INSERT INTO case_library VALUES
|
||||
(1, 'case-001', 'diag-001', 'AUTO', 'EXTERNAL_API', '广东', '/api/v1/guangdong/social-security', '40003',
|
||||
'广东社保查询idCard字段缺失',
|
||||
'请求报文中未传入idCard字段，导致参数校验失败',
|
||||
'前端表单增加idCard必填校验；后端增加参数校验提示',
|
||||
15, 'system', NOW(), NOW());
|
||||
```
|
||||
|
||||
### 示例2：内部错误案例
|
||||
```sql
|
||||
INSERT INTO case_library VALUES
|
||||
(2, 'case-002', 'diag-045', 'AUTO', 'INTERNAL_ERROR', 'order-service', 'OrderController.createOrder()', 'NullPointerException',
|
||||
'订单服务创建订单空指针异常',
|
||||
'OrderController.createOrder()方法中user对象为null，未做空判断',
|
||||
'在第45行添加空判断：if (user == null) throw new BizException("用户信息不存在")',
|
||||
8, 'system', NOW(), NOW());
|
||||
```
|
||||
|
||||
### 示例3：人工录入案例
|
||||
```sql
|
||||
INSERT INTO case_library VALUES
|
||||
(3, 'case-003', NULL, 'MANUAL', 'DATABASE', 'mysql-master-01', 'UPDATE orders SET status=? WHERE order_id=?', '1213',
|
||||
'订单库存更新死锁通用处理',
|
||||
'两个事务互相等待对方释放锁',
|
||||
'调整事务加锁顺序：统一先锁订单，再锁库存；或使用乐观锁',
|
||||
3, 'admin', NOW(), NOW());
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 典型查询
|
||||
|
||||
### 精确匹配查询
|
||||
```sql
|
||||
-- 按错误码查询
|
||||
SELECT * FROM case_library
|
||||
WHERE error_code = '40003'
|
||||
ORDER BY reference_count DESC
|
||||
LIMIT 5;
|
||||
|
||||
-- 按故障类别 + 错误码 + 故障目标查询
|
||||
SELECT * FROM case_library
|
||||
WHERE fault_category = 'INTERNAL_ERROR'
|
||||
AND error_code = 'NullPointerException'
|
||||
AND fault_target = 'OrderController.createOrder()'
|
||||
ORDER BY reference_count DESC
|
||||
LIMIT 5;
|
||||
```
|
||||
|
||||
### 统计分析
|
||||
```sql
|
||||
-- 统计案例分布
|
||||
SELECT
|
||||
fault_category,
|
||||
COUNT(*) as count,
|
||||
AVG(reference_count) as avg_reference
|
||||
FROM case_library
|
||||
GROUP BY fault_category
|
||||
ORDER BY count DESC;
|
||||
|
||||
-- Top 引用案例
|
||||
SELECT title, reference_count, created_at
|
||||
FROM case_library
|
||||
ORDER BY reference_count DESC
|
||||
LIMIT 10;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 与 Milvus 的配合
|
||||
|
||||
### 混合检索策略
|
||||
|
||||
```
|
||||
1. 精确匹配（MySQL）
|
||||
- 按 error_code 查询
|
||||
- 按 fault_category + fault_source 查询
|
||||
- 优点：快速、准确
|
||||
|
||||
2. 语义检索（Milvus）
|
||||
- 将案例内容向量化
|
||||
- 按语义相似度查询
|
||||
- 优点：能找到相似但不同错误码的案例
|
||||
|
||||
3. 混合策略（推荐）
|
||||
Step 1: 先精确匹配（MySQL）
|
||||
Step 2: 如果结果 < 3 个，补充语义检索（Milvus）
|
||||
Step 3: 合并去重，按 reference_count 排序
|
||||
Step 4: 返回 Top 5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数据量预估
|
||||
|
||||
```
|
||||
预估：500-1000 条
|
||||
- 初期：每月新增 10-20 条
|
||||
- 稳定期：每月新增 5-10 条
|
||||
- 总量：1-2 年达到稳定
|
||||
|
||||
存储：
|
||||
- 单条记录：约 2KB
|
||||
- 1000 条：约 2MB
|
||||
|
||||
结论：数据量很小
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MVP 版本的简化
|
||||
|
||||
```
|
||||
Phase 1（当前）：
|
||||
✅ 基础字段和表结构
|
||||
✅ 自动生成案例
|
||||
✅ 人工录入案例
|
||||
✅ 按 reference_count 简单排序
|
||||
|
||||
Phase 2（未来增强）：
|
||||
❌ useful_count + score（复杂评分）
|
||||
❌ 版本管理
|
||||
❌ 标签分类（tags）
|
||||
❌ 案例合并功能
|
||||
```
|
||||
@@ -0,0 +1,240 @@
|
||||
# diagnosis_record - 诊断记录表
|
||||
|
||||
## 表定位
|
||||
|
||||
**核心业务表**：存储每次诊断任务的完整记录
|
||||
|
||||
## 设计理念
|
||||
|
||||
### 兼容多种故障类型
|
||||
|
||||
**问题背景**：
|
||||
- 初始设计过于聚焦"外部接口故障"
|
||||
- 实际故障类型更丰富：空指针异常、数据库死锁、缓存穿透、线程池耗尽等
|
||||
|
||||
**解决方案**：
|
||||
- 字段泛化：business_id 替代 order_id，fault_source 替代 province
|
||||
- 增加分类：fault_category 显式区分故障类别
|
||||
- 增强错误信息：error_message、stack_trace 支持内部错误
|
||||
|
||||
---
|
||||
|
||||
## 表结构（v2.0）
|
||||
|
||||
```sql
|
||||
CREATE TABLE diagnosis_record (
|
||||
-- 主键
|
||||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||||
diagnosis_id VARCHAR(64) UNIQUE NOT NULL COMMENT '诊断唯一ID（UUID）',
|
||||
|
||||
-- 关联信息
|
||||
session_id VARCHAR(64) COMMENT '会话ID（关联Redis）',
|
||||
business_id VARCHAR(128) COMMENT '业务标识（订单号/请求ID/线程ID/任务ID...）',
|
||||
trace_id VARCHAR(64) COMMENT '链路追踪ID',
|
||||
|
||||
-- 故障分类（泛化设计）
|
||||
fault_category VARCHAR(32) COMMENT '故障类别（EXTERNAL_API/INTERNAL_ERROR/DATABASE/CACHE/NETWORK/THREAD/MEMORY/CONFIG）',
|
||||
fault_source VARCHAR(128) COMMENT '故障源（省份/服务名/类名/数据库实例...）',
|
||||
fault_target VARCHAR(256) COMMENT '故障目标（接口URL/方法名/SQL语句/缓存键...）',
|
||||
|
||||
-- 错误信息（通用）
|
||||
error_code VARCHAR(64) COMMENT '错误码（业务错误码/HTTP状态码/异常类名）',
|
||||
error_message TEXT COMMENT '错误消息',
|
||||
stack_trace TEXT COMMENT '堆栈信息（内部错误时记录）',
|
||||
|
||||
-- 诊断结果
|
||||
problem_type VARCHAR(32) COMMENT '问题类型（参数/网络/权限/逻辑/空指针/死锁...）',
|
||||
root_cause TEXT COMMENT '根因分析',
|
||||
solution TEXT COMMENT '修复方案',
|
||||
report_markdown TEXT COMMENT '完整诊断报告（Markdown格式）',
|
||||
|
||||
-- 评估指标
|
||||
status VARCHAR(16) DEFAULT 'PENDING' COMMENT '诊断状态（PENDING/RUNNING/SUCCESS/FAILED）',
|
||||
confidence INT COMMENT '诊断置信度（0-100）',
|
||||
duration INT COMMENT '诊断耗时（毫秒）',
|
||||
|
||||
-- 用户反馈
|
||||
feedback VARCHAR(16) COMMENT '用户反馈（useful/not_useful/null）TODO: 后续可拆分为独立反馈表',
|
||||
|
||||
-- 调试字段
|
||||
tool_calls JSON COMMENT '工具调用记录',
|
||||
|
||||
-- 元数据
|
||||
created_by VARCHAR(64) COMMENT '创建人',
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||||
|
||||
-- 索引
|
||||
INDEX idx_business_id (business_id),
|
||||
INDEX idx_trace_id (trace_id),
|
||||
INDEX idx_session_id (session_id),
|
||||
INDEX idx_fault_category (fault_category),
|
||||
INDEX idx_fault_source_target (fault_source, fault_target(100)),
|
||||
INDEX idx_error_code (error_code),
|
||||
INDEX idx_created_at (created_at),
|
||||
INDEX idx_status (status)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='诊断记录表（v2.0 泛化版）';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 字段说明
|
||||
|
||||
### 核心字段
|
||||
|
||||
| 字段 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| diagnosis_id | 诊断唯一标识 | diag-001 |
|
||||
| session_id | 会话ID（支持追问） | sess-abc |
|
||||
| business_id | **泛化**：业务标识 | 订单号/请求ID/线程ID |
|
||||
| trace_id | 链路追踪ID | trace-xyz |
|
||||
|
||||
### 故障分类字段（泛化设计）
|
||||
|
||||
| 字段 | 说明 | 外部接口示例 | 内部错误示例 |
|
||||
|------|------|-------------|-------------|
|
||||
| fault_category | 故障类别 | EXTERNAL_API | INTERNAL_ERROR |
|
||||
| fault_source | 故障源 | 广东 | order-service |
|
||||
| fault_target | 故障目标 | /api/v1/social | OrderController.create() |
|
||||
| error_code | 错误码 | 40003 | NullPointerException |
|
||||
|
||||
### fault_category 枚举值
|
||||
|
||||
```
|
||||
EXTERNAL_API - 外部接口调用失败
|
||||
INTERNAL_ERROR - 系统内部错误（空指针、NPE）
|
||||
DATABASE - 数据库问题（死锁、慢查询）
|
||||
CACHE - 缓存问题（穿透、雪崩）
|
||||
NETWORK - 网络问题（超时、连接失败）
|
||||
THREAD - 线程问题（线程池满、死锁）
|
||||
MEMORY - 内存问题（OOM、内存泄漏）
|
||||
CONFIG - 配置问题（配置错误、缺失）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数据示例
|
||||
|
||||
### 示例1：外部接口故障
|
||||
```sql
|
||||
INSERT INTO diagnosis_record VALUES (
|
||||
NULL, 'diag-001', 'sess-abc', '202406150001', 'trace-001',
|
||||
'EXTERNAL_API', '广东', '/api/v1/guangdong/social-security', '40003',
|
||||
'参数缺失：idCard', NULL,
|
||||
'参数问题', 'idCard字段缺失', '补充前端校验', '完整报告...',
|
||||
'SUCCESS', 85, 5234, NULL,
|
||||
NULL, NOW(), NOW()
|
||||
);
|
||||
```
|
||||
|
||||
### 示例2：空指针异常
|
||||
```sql
|
||||
INSERT INTO diagnosis_record VALUES (
|
||||
NULL, 'diag-002', 'sess-def', 'req-xyz789', NULL,
|
||||
'INTERNAL_ERROR', 'order-service', 'OrderController.createOrder()', 'NullPointerException',
|
||||
'Cannot invoke "User.getName()" because "user" is null',
|
||||
'java.lang.NullPointerException: ...\n at OrderController.java:45\n ...',
|
||||
'空指针异常', 'createOrder方法中user对象为null', '添加空判断', '完整报告...',
|
||||
'SUCCESS', 90, 3456, NULL,
|
||||
NULL, NOW(), NOW()
|
||||
);
|
||||
```
|
||||
|
||||
### 示例3：数据库死锁
|
||||
```sql
|
||||
INSERT INTO diagnosis_record VALUES (
|
||||
NULL, 'diag-003', 'sess-ghi', 'txn-20240615-001', NULL,
|
||||
'DATABASE', 'mysql-master-01', 'UPDATE orders SET status=? WHERE order_id=?', '1213',
|
||||
'Deadlock found when trying to get lock', NULL,
|
||||
'数据库死锁', '两个事务互相等待对方释放锁', '调整事务加锁顺序', '完整报告...',
|
||||
'SUCCESS', 88, 4567, NULL,
|
||||
NULL, NOW(), NOW()
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 典型查询
|
||||
|
||||
### 按故障类别统计
|
||||
```sql
|
||||
SELECT
|
||||
fault_category,
|
||||
COUNT(*) as count,
|
||||
ROUND(AVG(duration), 2) as avg_duration_ms,
|
||||
ROUND(AVG(confidence), 2) as avg_confidence
|
||||
FROM diagnosis_record
|
||||
WHERE created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY)
|
||||
GROUP BY fault_category
|
||||
ORDER BY count DESC;
|
||||
```
|
||||
|
||||
### 内部错误Top异常
|
||||
```sql
|
||||
SELECT
|
||||
error_code,
|
||||
fault_target,
|
||||
COUNT(*) as count
|
||||
FROM diagnosis_record
|
||||
WHERE fault_category = 'INTERNAL_ERROR'
|
||||
AND created_at >= DATE_SUB(NOW(), INTERVAL 30 DAY)
|
||||
GROUP BY error_code, fault_target
|
||||
ORDER BY count DESC
|
||||
LIMIT 10;
|
||||
```
|
||||
|
||||
### 诊断成功率
|
||||
```sql
|
||||
SELECT
|
||||
COUNT(*) as total,
|
||||
SUM(CASE WHEN status = 'SUCCESS' THEN 1 ELSE 0 END) as success,
|
||||
ROUND(SUM(CASE WHEN status = 'SUCCESS' THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2) as success_rate
|
||||
FROM diagnosis_record
|
||||
WHERE created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 核心设计决策
|
||||
|
||||
### 1. 一次诊断 = 一条记录
|
||||
- 用户发起一次诊断任务，创建一条记录
|
||||
- 不是聊天记录（不存多轮对话）
|
||||
- 追问对话上下文暂存 Redis（30分钟过期）
|
||||
|
||||
### 2. report_markdown 字段的必要性
|
||||
- 固化结果：Prompt变化不影响历史报告
|
||||
- 快速展示：不需要重新生成
|
||||
- 历史审计：可以看到当时的诊断结果
|
||||
|
||||
### 3. 字段泛化的好处
|
||||
- 支持多种故障类型（不限于外部接口）
|
||||
- 灵活填写（根据故障类型选择字段值）
|
||||
- 易于扩展（新增故障类型只需增加枚举值）
|
||||
|
||||
---
|
||||
|
||||
## 数据量预估
|
||||
|
||||
```
|
||||
场景：中型企业运维团队
|
||||
- 日均诊断：100 次
|
||||
- 月均诊断：3000 次
|
||||
- 年均诊断：36000 次
|
||||
|
||||
存储预估：
|
||||
- 单条记录：约 5KB（含报告）
|
||||
- 年存储量：36000 × 5KB = 180MB
|
||||
- 三年存储：540MB
|
||||
|
||||
结论：数据量不大，可以全量保留
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 版本历史
|
||||
|
||||
| 版本 | 日期 | 变更内容 |
|
||||
|------|------|---------|
|
||||
| v1.0 | 2024-06-15 | 初版，基础字段 |
|
||||
| v2.0 | 2024-06-22 | 字段泛化，支持多种故障类型 |
|
||||
@@ -0,0 +1 @@
|
||||
COMMITTED
|
||||
@@ -0,0 +1,112 @@
|
||||
# Phase 1 Infrastructure - Decisions Log
|
||||
|
||||
## Grill 阶段澄清记录
|
||||
|
||||
### 2026-06-23
|
||||
|
||||
#### Q1: SessionContext 字段设计
|
||||
**问题**: Redis 会话需要存储哪些字段？
|
||||
|
||||
**决策**:
|
||||
```java
|
||||
class SessionContext {
|
||||
String sessionId;
|
||||
String diagnosisId;
|
||||
String currentStep;
|
||||
Map<String, Object> collectedEvidence;
|
||||
List<ToolCall> toolCallHistory;
|
||||
String intentType; // 预留 Phase 2 意图识别
|
||||
LocalDateTime createdAt;
|
||||
LocalDateTime lastAccessAt;
|
||||
}
|
||||
```
|
||||
|
||||
**理由**:
|
||||
- 支持多轮对话恢复上下文
|
||||
- intentType 预留 Phase 2，避免后续修改结构
|
||||
- tool_calls 同时存 Redis（临时）和 MySQL（持久）
|
||||
|
||||
**用户确认**: 已确认
|
||||
|
||||
---
|
||||
|
||||
#### Q2: 包名重构策略
|
||||
**问题**: org.example → com.superbiz.agent 是否需要兼容层？
|
||||
|
||||
**决策**: 直接全量替换，不保留兼容层
|
||||
|
||||
**理由**:
|
||||
- 内部项目，无外部依赖者
|
||||
- 兼容层增加复杂度
|
||||
- MVP 阶段保持简单
|
||||
|
||||
**用户确认**: 已确认
|
||||
|
||||
---
|
||||
|
||||
#### Q3: Redis 降级策略
|
||||
**问题**: Redis 故障时如何处理？
|
||||
|
||||
**决策**: Phase 1 不做降级，Redis 故障直接失败
|
||||
|
||||
**理由**:
|
||||
- MVP 优先跑通核心流程
|
||||
- 降级策略增加复杂度
|
||||
- 单元测试可用内存 Mock
|
||||
|
||||
**备选方案** (Phase 2/3):
|
||||
- 自动降级到内存实现
|
||||
- 返回友好错误提示
|
||||
|
||||
**用户确认**: 已确认（先跑通 MVP）
|
||||
|
||||
---
|
||||
|
||||
## Evidence-Driven 查证结果
|
||||
|
||||
### 诊断记录 vs 案例的边界
|
||||
**查证文件**: docs/tables/diagnosis_record.md, docs/tables/case_library.md
|
||||
|
||||
**结论**:
|
||||
- 诊断记录：每次诊断都记录
|
||||
- 案例：从诊断记录中筛选（成功诊断 + 用户反馈 useful）
|
||||
- 转换触发：diagnosis_record.feedback = 'useful' + confidence >= 80
|
||||
|
||||
**状态**: 已查证，边界清晰
|
||||
|
||||
---
|
||||
|
||||
### 文档范围
|
||||
**查证文件**: docs/tables/api_document.md
|
||||
|
||||
**结论**:
|
||||
- Phase 1: 只处理接口文档（API 文档、错误码说明）
|
||||
- Phase 2/3: 可扩展为其他类型（运维手册、FAQ）
|
||||
|
||||
**状态**: 已查证，范围明确
|
||||
|
||||
---
|
||||
|
||||
### 单元测试覆盖率标准
|
||||
**查证文件**: docs/architecture/implementation-detail.md
|
||||
|
||||
**结论**:
|
||||
- 目标：行覆盖率 70%+
|
||||
- Repository: 100%
|
||||
- Service: 80%+
|
||||
- Tool: 80%+
|
||||
- Controller: 70%+
|
||||
|
||||
**状态**: 已查证，标准明确
|
||||
|
||||
---
|
||||
|
||||
## 待写入 CONTEXT.md 的术语
|
||||
|
||||
无新增术语。现有术语已在 docs/ 中定义清楚。
|
||||
|
||||
---
|
||||
|
||||
## 待创建 ADR
|
||||
|
||||
无。Phase 1 都是标准技术选型，无需 ADR。
|
||||
@@ -0,0 +1,267 @@
|
||||
# Phase 1 Infrastructure - Design
|
||||
|
||||
## 架构设计
|
||||
|
||||
### 1. 数据持久化层
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Application Layer │
|
||||
│ (Service / Controller / Agent) │
|
||||
└──────────────┬──────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Repository Layer (JPA) │
|
||||
│ - DiagnosisRecordRepository │
|
||||
│ - CaseLibraryRepository │
|
||||
│ - ApiDocumentRepository │
|
||||
└──────────────┬──────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────┐
|
||||
│ MySQL 8.0+ │
|
||||
│ - diagnosis_record (诊断记录) │
|
||||
│ - case_library (案例库) │
|
||||
│ - api_document (文档元数据) │
|
||||
│ - flyway_schema_history (版本管理) │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Flyway 迁移流程**：
|
||||
1. 启动时自动扫描 `db/migration/V*.sql`
|
||||
2. 检查 `flyway_schema_history` 表
|
||||
3. 执行未运行的脚本
|
||||
4. 记录版本号
|
||||
|
||||
### 2. 会话管理层
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Diagnosis Flow │
|
||||
└──────────────┬──────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────┐
|
||||
│ SessionManager (Interface) │
|
||||
└──────────────┬──────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────┐
|
||||
│ RedisSessionManager (Impl) │
|
||||
│ - get(sessionId): SessionContext │
|
||||
│ - save(context): void │
|
||||
│ - delete(sessionId): void │
|
||||
└──────────────┬──────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Redis 6.0+ │
|
||||
│ Key: session:{sessionId} │
|
||||
│ Value: SessionContext (JSON) │
|
||||
│ TTL: 30 minutes │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**SessionContext 结构**：
|
||||
```java
|
||||
{
|
||||
"sessionId": "uuid",
|
||||
"diagnosisId": "uuid",
|
||||
"currentStep": "queryOrder",
|
||||
"collectedEvidence": {
|
||||
"orderInfo": {...},
|
||||
"logs": [...]
|
||||
},
|
||||
"toolCallHistory": [
|
||||
{
|
||||
"toolName": "queryOrder",
|
||||
"params": {...},
|
||||
"result": {...},
|
||||
"timestamp": "2026-06-23T10:00:00"
|
||||
}
|
||||
],
|
||||
"intentType": "诊断",
|
||||
"createdAt": "2026-06-23T09:55:00",
|
||||
"lastAccessAt": "2026-06-23T10:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 包结构设计
|
||||
|
||||
```
|
||||
com.superbiz.agent/
|
||||
├── SuperBizAgentApplication.java # 启动类
|
||||
│
|
||||
├── controller/ # REST 控制器
|
||||
│ ├── DiagnosisController.java
|
||||
│ ├── DocumentController.java
|
||||
│ └── CaseController.java
|
||||
│
|
||||
├── service/ # 业务服务
|
||||
│ ├── DiagnosisService.java
|
||||
│ ├── DocumentService.java
|
||||
│ ├── CaseService.java
|
||||
│ ├── TextExtractor.java # 文本提取
|
||||
│ └── VectorService.java # 向量化服务
|
||||
│
|
||||
├── repository/ # 数据访问
|
||||
│ ├── DiagnosisRecordRepository.java
|
||||
│ ├── CaseLibraryRepository.java
|
||||
│ └── ApiDocumentRepository.java
|
||||
│
|
||||
├── domain/ # 领域模型
|
||||
│ ├── entity/ # JPA 实体
|
||||
│ │ ├── DiagnosisRecord.java
|
||||
│ │ ├── CaseLibrary.java
|
||||
│ │ └── ApiDocument.java
|
||||
│ ├── dto/ # 数据传输对象
|
||||
│ │ ├── DiagnosisRequest.java
|
||||
│ │ ├── DiagnosisResponse.java
|
||||
│ │ ├── DocumentUploadRequest.java
|
||||
│ │ └── DocumentQueryResponse.java
|
||||
│ └── enums/ # 枚举
|
||||
│ ├── FaultCategory.java
|
||||
│ ├── DiagnosisStatus.java
|
||||
│ └── SourceType.java
|
||||
│
|
||||
├── session/ # 会话管理
|
||||
│ ├── SessionManager.java # 接口
|
||||
│ ├── RedisSessionManager.java # Redis 实现
|
||||
│ ├── SessionContext.java # 会话上下文
|
||||
│ └── ToolCall.java # 工具调用记录
|
||||
│
|
||||
├── tool/ # 工具层
|
||||
│ ├── DocumentSearchTool.java # 混合检索
|
||||
│ └── (其他 tool 保留 Phase 2)
|
||||
│
|
||||
├── config/ # 配置
|
||||
│ ├── JpaConfig.java
|
||||
│ ├── RedisConfig.java
|
||||
│ ├── MilvusConfig.java # 保留现有
|
||||
│ └── DashScopeConfig.java # 保留现有
|
||||
│
|
||||
└── exception/ # 异常处理
|
||||
├── GlobalExceptionHandler.java
|
||||
├── SessionNotFoundException.java
|
||||
└── DocumentProcessException.java
|
||||
```
|
||||
|
||||
### 4. 文档管理流程
|
||||
|
||||
```
|
||||
文档上传流程：
|
||||
User → POST /api/documents/upload
|
||||
↓
|
||||
DocumentController.upload()
|
||||
↓
|
||||
DocumentService.uploadDocument()
|
||||
↓ (并行)
|
||||
├─→ TextExtractor.extract() # 提取文本
|
||||
├─→ chunkText() # 分块
|
||||
├─→ VectorService.embed() # 向量化
|
||||
├─→ ApiDocumentRepository.save() # 存 MySQL
|
||||
└─→ MilvusClient.insert() # 存 Milvus
|
||||
↓
|
||||
返回 document_id
|
||||
```
|
||||
|
||||
```
|
||||
混合检索流程：
|
||||
Agent → DocumentSearchTool.search(errorCode, province)
|
||||
↓
|
||||
├─→ MySQL 精确匹配
|
||||
│ SELECT * FROM api_document
|
||||
│ WHERE error_code = ? AND province = ?
|
||||
│
|
||||
├─→ Milvus 语义检索
|
||||
│ 向量化查询 → 相似度搜索 → Top 10
|
||||
│
|
||||
└─→ RRF 融合排序
|
||||
(精确匹配优先 + 语义补漏)
|
||||
↓
|
||||
返回 Top 3 文档片段
|
||||
```
|
||||
|
||||
### 5. 数据库配置
|
||||
|
||||
**application.yml 新增**：
|
||||
```yaml
|
||||
spring:
|
||||
datasource:
|
||||
url: jdbc:mysql://localhost:3306/superbiz_agent?useUnicode=true&characterEncoding=utf8mb4&serverTimezone=Asia/Shanghai
|
||||
username: ${DB_USERNAME:root}
|
||||
password: ${DB_PASSWORD:your-password}
|
||||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||||
|
||||
jpa:
|
||||
hibernate:
|
||||
ddl-auto: validate # 生产用 validate，Flyway 管理表结构
|
||||
show-sql: true
|
||||
properties:
|
||||
hibernate:
|
||||
format_sql: true
|
||||
dialect: org.hibernate.dialect.MySQL8Dialect
|
||||
|
||||
flyway:
|
||||
enabled: true
|
||||
baseline-on-migrate: true
|
||||
locations: classpath:db/migration
|
||||
|
||||
data:
|
||||
redis:
|
||||
host: localhost
|
||||
port: 6379
|
||||
password: ${REDIS_PASSWORD:}
|
||||
database: 0
|
||||
timeout: 3000
|
||||
lettuce:
|
||||
pool:
|
||||
max-active: 8
|
||||
max-idle: 8
|
||||
min-idle: 0
|
||||
```
|
||||
|
||||
### 6. 测试策略
|
||||
|
||||
**Repository 测试**：
|
||||
- 使用 @DataJpaTest + H2 内存数据库
|
||||
- 测试 CRUD + 自定义查询
|
||||
|
||||
**Service 测试**：
|
||||
- 使用 @SpringBootTest + Mockito
|
||||
- Mock Repository 和外部依赖
|
||||
|
||||
**Controller 测试**：
|
||||
- 使用 @WebMvcTest + MockMvc
|
||||
- Mock Service 层
|
||||
|
||||
**集成测试**：
|
||||
- 使用 @SpringBootTest + Testcontainers（可选）
|
||||
- 测试完整流程
|
||||
|
||||
## 技术决策
|
||||
|
||||
### Flyway vs Liquibase
|
||||
**选择**：Flyway
|
||||
|
||||
**理由**：
|
||||
- 更简单，SQL-first
|
||||
- Spring Boot 官方推荐
|
||||
- 社区活跃
|
||||
|
||||
### Jackson vs Gson
|
||||
**选择**：Jackson（Spring Boot 默认）
|
||||
|
||||
**理由**：
|
||||
- Spring Boot 内置
|
||||
- 性能更好
|
||||
- 与 Spring MVC 集成好
|
||||
|
||||
### Lettuce vs Jedis
|
||||
**选择**：Lettuce（Spring Data Redis 默认）
|
||||
|
||||
**理由**：
|
||||
- 异步支持
|
||||
- 线程安全
|
||||
- Spring Boot 默认
|
||||
@@ -0,0 +1,171 @@
|
||||
# Proposal: Phase 1 基础设施搭建
|
||||
|
||||
## 问题
|
||||
|
||||
当前项目是一个 Demo，需要改造为 MVP 诊断 Agent 系统。Phase 1 需要搭建基础设施：
|
||||
- 缺少持久化层（MySQL + JPA）
|
||||
- 缺少分布式会话管理（Redis）
|
||||
- 代码结构需要重构（包名、分层）
|
||||
- 缺少文档管理基础功能
|
||||
|
||||
## 建议方案
|
||||
|
||||
### 1. 数据持久化
|
||||
|
||||
**方案**：Spring Data JPA + MySQL + Flyway
|
||||
|
||||
**理由**：
|
||||
- JPA 是 Spring Boot 标准持久化方案
|
||||
- Flyway 管理数据库版本，团队协作友好
|
||||
- 3 张表设计已完成（docs/tables/）
|
||||
|
||||
**实现**：
|
||||
1. 添加依赖（spring-boot-starter-data-jpa, mysql-connector-j, flyway-core）
|
||||
2. 创建 3 个 Flyway 迁移脚本（V001/V002/V003）
|
||||
3. 创建 JPA 实体类（DiagnosisRecord, CaseLibrary, ApiDocument）
|
||||
4. 创建 Repository 接口（继承 JpaRepository）
|
||||
|
||||
### 2. 会话管理
|
||||
|
||||
**方案**：Redis 替代内存 HashMap
|
||||
|
||||
**理由**：
|
||||
- 支持分布式部署
|
||||
- 自动 TTL（30 分钟）
|
||||
- Spring Data Redis 集成简单
|
||||
|
||||
**实现**：
|
||||
1. 添加 spring-boot-starter-data-redis 依赖
|
||||
2. 创建 SessionManager 接口 + RedisSessionManager 实现
|
||||
3. SessionContext 使用 JSON 序列化
|
||||
|
||||
### 3. 代码结构重构
|
||||
|
||||
**方案**：包名重构 + 分层优化 + DTO 抽离
|
||||
|
||||
**包名重构**：
|
||||
- `org.example` → `com.superbiz.agent`
|
||||
- 工具：IDEA Refactor → Rename Package
|
||||
|
||||
**分层结构**：
|
||||
```
|
||||
com.superbiz.agent/
|
||||
├── controller/ # REST API
|
||||
├── service/ # 业务逻辑
|
||||
├── repository/ # 数据访问
|
||||
├── domain/
|
||||
│ ├── entity/ # JPA 实体
|
||||
│ ├── dto/ # DTO
|
||||
│ └── enums/ # 枚举
|
||||
├── agent/ # Agent 层（Phase 2）
|
||||
├── tool/ # 工具层
|
||||
├── session/ # 会话管理
|
||||
└── config/ # 配置
|
||||
```
|
||||
|
||||
**DTO 抽离**：
|
||||
- Controller 不直接依赖 Entity
|
||||
- 使用 MapStruct 做对象转换
|
||||
|
||||
### 4. 文档管理
|
||||
|
||||
**方案**：CRUD + Milvus 向量同步
|
||||
|
||||
**功能**：
|
||||
1. 上传接口：文件 → 文本提取 → 分块 → 向量化 → MySQL + Milvus
|
||||
2. 查询接口：分页、过滤
|
||||
3. 删除接口：MySQL + Milvus 同步删除
|
||||
4. 检索工具：精确匹配（MySQL）+ 语义检索（Milvus）+ RRF 融合
|
||||
|
||||
## 范围
|
||||
|
||||
**包含**：
|
||||
- Day 1-2: MySQL 表 + JPA + Repository + Redis 会话
|
||||
- Day 3: 包名重构 + 分层优化 + DTO 抽离
|
||||
- Day 4-5: 文档管理 4 个接口 + 混合检索工具
|
||||
|
||||
**不包含**：
|
||||
- Agent 功能（Phase 2）
|
||||
- 意图识别和 RAG（Phase 2）
|
||||
- Verifier 和 Harness（Phase 3）
|
||||
|
||||
## 非目标
|
||||
|
||||
- 性能优化（后续优化）
|
||||
- 完整的权限控制（MVP 不需要）
|
||||
- 前端界面（只做后端 API）
|
||||
|
||||
## 来自 devflow 的上下文约束
|
||||
|
||||
无（这是首个 OpenSpec，devflow 目录为空）
|
||||
|
||||
## 风险
|
||||
|
||||
1. **包名重构影响范围大**
|
||||
- 缓解：先提交当前代码，独立分支重构
|
||||
- 验证：重构后编译通过 + 启动成功
|
||||
|
||||
2. **Flyway 首次运行可能失败**
|
||||
- 缓解：本地 MySQL 先手动测试
|
||||
- 回退：Flyway 支持 repair 修复
|
||||
|
||||
3. **Redis 本地环境依赖**
|
||||
- 缓解：提供 Docker Compose 配置
|
||||
- 回退：可降级为内存实现（测试用）
|
||||
|
||||
## 关键假设
|
||||
|
||||
1. MySQL 8.0+ 和 Redis 6.0+ 可用（本地或 Docker）
|
||||
2. 现有 Milvus 集成不需要改动
|
||||
3. 单元测试覆盖率目标：70%+
|
||||
|
||||
## 成功标准
|
||||
|
||||
1. ✅ 3 张表创建成功，索引完整
|
||||
2. ✅ Repository 层单元测试通过
|
||||
3. ✅ Redis 会话存取正常，TTL 生效
|
||||
4. ✅ 包名重构完成，编译通过
|
||||
5. ✅ 文档上传/查询/删除接口可用
|
||||
6. ✅ 混合检索工具返回正确结果
|
||||
7. ✅ 整体测试覆盖率 ≥ 70%
|
||||
|
||||
## 产出文件（预期）
|
||||
|
||||
**数据库迁移**：
|
||||
- `src/main/resources/db/migration/V001__create_diagnosis_record.sql`
|
||||
- `src/main/resources/db/migration/V002__create_case_library.sql`
|
||||
- `src/main/resources/db/migration/V003__create_api_document.sql`
|
||||
|
||||
**实体类**：
|
||||
- `com.superbiz.agent.domain.entity.DiagnosisRecord`
|
||||
- `com.superbiz.agent.domain.entity.CaseLibrary`
|
||||
- `com.superbiz.agent.domain.entity.ApiDocument`
|
||||
|
||||
**Repository**：
|
||||
- `com.superbiz.agent.repository.DiagnosisRecordRepository`
|
||||
- `com.superbiz.agent.repository.CaseLibraryRepository`
|
||||
- `com.superbiz.agent.repository.ApiDocumentRepository`
|
||||
|
||||
**会话管理**：
|
||||
- `com.superbiz.agent.session.SessionManager`
|
||||
- `com.superbiz.agent.session.RedisSessionManager`
|
||||
- `com.superbiz.agent.session.SessionContext`
|
||||
|
||||
**文档管理**：
|
||||
- `com.superbiz.agent.controller.DocumentController`
|
||||
- `com.superbiz.agent.service.DocumentService`
|
||||
- `com.superbiz.agent.service.TextExtractor`
|
||||
- `com.superbiz.agent.tool.DocumentSearchTool`
|
||||
|
||||
**配置**：
|
||||
- `pom.xml`（增加依赖）
|
||||
- `application.yml`（增加 MySQL + Redis 配置）
|
||||
|
||||
**测试**：
|
||||
- `*RepositoryTest.java`
|
||||
- `*ServiceTest.java`
|
||||
- `*ControllerTest.java`
|
||||
|
||||
## 工期估算
|
||||
|
||||
5 天（按实施计划）
|
||||
@@ -0,0 +1,312 @@
|
||||
# Phase 1 Infrastructure - Specifications
|
||||
|
||||
## 功能规格
|
||||
|
||||
### 1. 数据库表创建
|
||||
|
||||
#### 1.1 diagnosis_record 表
|
||||
**输入**：Flyway 迁移脚本 V001
|
||||
**输出**：MySQL 表创建成功
|
||||
**验收标准**：
|
||||
- ✅ 表结构与 docs/tables/diagnosis_record.md 一致
|
||||
- ✅ 所有索引创建成功
|
||||
- ✅ JSON 字段类型正确
|
||||
- ✅ 默认值和注释完整
|
||||
|
||||
#### 1.2 case_library 表
|
||||
**输入**：Flyway 迁移脚本 V002
|
||||
**输出**：MySQL 表创建成功
|
||||
**验收标准**：
|
||||
- ✅ 表结构与 docs/tables/case_library.md 一致
|
||||
- ✅ 外键约束正确
|
||||
- ✅ 索引覆盖查询场景
|
||||
|
||||
#### 1.3 api_document 表
|
||||
**输入**：Flyway 迁移脚本 V003
|
||||
**输出**：MySQL 表创建成功
|
||||
**验收标准**：
|
||||
- ✅ 表结构与 docs/tables/api_document.md 一致
|
||||
- ✅ province 和 category 索引就绪
|
||||
|
||||
---
|
||||
|
||||
### 2. JPA 实体与 Repository
|
||||
|
||||
#### 2.1 DiagnosisRecord 实体
|
||||
**字段映射**：
|
||||
- `@Id @GeneratedValue` - id
|
||||
- `@Column(unique=true)` - diagnosis_id
|
||||
- `@JdbcTypeCode(SqlTypes.JSON)` - tool_calls
|
||||
- `@Enumerated(EnumType.STRING)` - fault_category, status
|
||||
- `LocalDateTime` - created_at, updated_at
|
||||
|
||||
**验收标准**：
|
||||
- ✅ 所有字段与数据库一致
|
||||
- ✅ JSON 字段序列化正确
|
||||
- ✅ 枚举映射正确
|
||||
- ✅ Lombok 注解完整
|
||||
|
||||
#### 2.2 Repository 查询方法
|
||||
**DiagnosisRecordRepository**：
|
||||
```java
|
||||
Optional<DiagnosisRecord> findByDiagnosisId(String diagnosisId);
|
||||
Optional<DiagnosisRecord> findByBusinessId(String businessId);
|
||||
Optional<DiagnosisRecord> findByTraceId(String traceId);
|
||||
List<DiagnosisRecord> findByFaultCategoryAndErrorCode(
|
||||
FaultCategory category, String errorCode);
|
||||
Page<DiagnosisRecord> findByCreatedAtBetween(
|
||||
LocalDateTime start, LocalDateTime end, Pageable pageable);
|
||||
```
|
||||
|
||||
**验收标准**：
|
||||
- ✅ 单元测试通过（@DataJpaTest + H2）
|
||||
- ✅ 分页查询正确
|
||||
- ✅ 复杂查询性能可接受（< 100ms）
|
||||
|
||||
---
|
||||
|
||||
### 3. Redis 会话管理
|
||||
|
||||
#### 3.1 SessionManager 接口
|
||||
```java
|
||||
public interface SessionManager {
|
||||
SessionContext get(String sessionId);
|
||||
void save(SessionContext context);
|
||||
void delete(String sessionId);
|
||||
boolean exists(String sessionId);
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.2 RedisSessionManager 实现
|
||||
**存储格式**：
|
||||
- Key: `session:{sessionId}`
|
||||
- Value: SessionContext 的 JSON 字符串
|
||||
- TTL: 1800 秒（30 分钟）
|
||||
|
||||
**异常处理**：
|
||||
- Redis 连接失败 → 抛出 RedisConnectionException
|
||||
- 序列化失败 → 抛出 SessionSerializationException
|
||||
- Session 不存在 → 返回 null（get 方法）
|
||||
|
||||
**验收标准**：
|
||||
- ✅ 存取删操作成功
|
||||
- ✅ TTL 自动刷新（每次 get/save）
|
||||
- ✅ JSON 序列化/反序列化正确
|
||||
- ✅ 单元测试覆盖（Mock RedisTemplate）
|
||||
|
||||
---
|
||||
|
||||
### 4. 文档管理
|
||||
|
||||
#### 4.1 文档上传接口
|
||||
**接口**：`POST /api/documents/upload`
|
||||
|
||||
**请求**：
|
||||
```json
|
||||
{
|
||||
"file": "multipart/form-data",
|
||||
"province": "广东",
|
||||
"category": "社保接口"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "上传成功",
|
||||
"data": {
|
||||
"documentId": "uuid",
|
||||
"fileName": "社保接口文档.docx",
|
||||
"chunkCount": 12
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**处理流程**：
|
||||
1. 文件类型校验（.txt, .md, .docx, .pdf）
|
||||
2. 文本提取
|
||||
3. 分块（chunk_size=500, overlap=50）
|
||||
4. DashScope 向量化
|
||||
5. MySQL 存元数据
|
||||
6. Milvus 存向量
|
||||
|
||||
**错误处理**：
|
||||
- 文件类型不支持 → 400 Bad Request
|
||||
- 文件大小超限（10MB） → 413 Payload Too Large
|
||||
- 向量化失败 → 500 Internal Server Error（回滚 MySQL）
|
||||
|
||||
**验收标准**：
|
||||
- ✅ 支持 .txt, .md, .docx, .pdf
|
||||
- ✅ MySQL + Milvus 事务一致
|
||||
- ✅ 单元测试覆盖
|
||||
|
||||
#### 4.2 文档查询接口
|
||||
**接口**：`GET /api/documents?province=广东&category=社保接口&page=0&size=10`
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"content": [
|
||||
{
|
||||
"documentId": "uuid",
|
||||
"fileName": "社保接口文档.docx",
|
||||
"province": "广东",
|
||||
"category": "社保接口",
|
||||
"createdAt": "2026-06-23T10:00:00"
|
||||
}
|
||||
],
|
||||
"totalElements": 1,
|
||||
"totalPages": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**验收标准**：
|
||||
- ✅ 分页正确
|
||||
- ✅ 过滤生效
|
||||
- ✅ 性能可接受（< 100ms）
|
||||
|
||||
#### 4.3 文档删除接口
|
||||
**接口**：`DELETE /api/documents/{documentId}`
|
||||
|
||||
**响应**：
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "删除成功"
|
||||
}
|
||||
```
|
||||
|
||||
**处理流程**：
|
||||
1. 删除 MySQL 记录
|
||||
2. 根据 document_id 删除 Milvus 向量
|
||||
|
||||
**事务性**：
|
||||
- MySQL 删除失败 → 不删除 Milvus
|
||||
- Milvus 删除失败 → 记录日志（容忍）
|
||||
|
||||
**验收标准**：
|
||||
- ✅ MySQL 记录删除
|
||||
- ✅ Milvus 向量删除
|
||||
- ✅ 幂等性（重复删除不报错）
|
||||
|
||||
#### 4.4 混合检索工具
|
||||
**接口**：`DocumentSearchTool.search(errorCode, province)`
|
||||
|
||||
**输入**：
|
||||
```java
|
||||
{
|
||||
"errorCode": "40003",
|
||||
"province": "广东"
|
||||
}
|
||||
```
|
||||
|
||||
**输出**：
|
||||
```java
|
||||
List<DocumentChunk> {
|
||||
"documentId": "uuid",
|
||||
"chunkId": "uuid",
|
||||
"content": "错误码 40003 表示...",
|
||||
"score": 0.95
|
||||
}
|
||||
```
|
||||
|
||||
**检索策略**：
|
||||
1. **精确匹配**（MySQL）：
|
||||
```sql
|
||||
SELECT * FROM api_document
|
||||
WHERE error_code = '40003' AND province = '广东'
|
||||
```
|
||||
2. **语义检索**（Milvus）：
|
||||
- 向量化查询文本
|
||||
- 相似度搜索 Top 10
|
||||
3. **RRF 融合**：
|
||||
- 精确匹配分数 = 1.0
|
||||
- 语义检索分数 = Milvus 相似度
|
||||
- 合并排序，返回 Top 3
|
||||
|
||||
**验收标准**：
|
||||
- ✅ 精确匹配优先
|
||||
- ✅ 语义检索补漏
|
||||
- ✅ 返回 Top 3
|
||||
- ✅ 单元测试覆盖
|
||||
|
||||
---
|
||||
|
||||
## 接口规格
|
||||
|
||||
### API 设计原则
|
||||
- RESTful 风格
|
||||
- 统一响应格式 `Result<T>`
|
||||
- HTTP 状态码语义化
|
||||
- 异常统一处理
|
||||
|
||||
### 统一响应格式
|
||||
```java
|
||||
class Result<T> {
|
||||
int code; // 业务状态码
|
||||
String message; // 提示信息
|
||||
T data; // 数据
|
||||
long timestamp; // 时间戳
|
||||
}
|
||||
```
|
||||
|
||||
### 错误码约定
|
||||
- 200: 成功
|
||||
- 400: 参数错误
|
||||
- 404: 资源不存在
|
||||
- 500: 服务器错误
|
||||
|
||||
---
|
||||
|
||||
## 性能规格
|
||||
|
||||
### 响应时间要求
|
||||
- 文档上传：< 5s（单文件 < 5MB）
|
||||
- 文档查询：< 100ms
|
||||
- 文档删除：< 200ms
|
||||
- 混合检索：< 500ms
|
||||
- Repository 查询：< 50ms
|
||||
|
||||
### 并发要求
|
||||
- 支持 10 QPS（Phase 1 目标）
|
||||
- 后续扩展至 100 QPS（Phase 2/3）
|
||||
|
||||
---
|
||||
|
||||
## 安全规格
|
||||
|
||||
### 输入校验
|
||||
- 文件类型白名单
|
||||
- 文件大小限制（10MB）
|
||||
- SQL 注入防护（JPA Prepared Statement）
|
||||
- XSS 防护（输入转义）
|
||||
|
||||
### 数据安全
|
||||
- Redis 密码保护
|
||||
- MySQL 用户权限最小化
|
||||
- 敏感日志脱敏
|
||||
|
||||
---
|
||||
|
||||
## 测试规格
|
||||
|
||||
### 单元测试覆盖率
|
||||
- Repository: 100%
|
||||
- Service: 80%+
|
||||
- Tool: 80%+
|
||||
- Controller: 70%+
|
||||
|
||||
### 测试类型
|
||||
- 单元测试（JUnit 5 + Mockito）
|
||||
- 集成测试（@SpringBootTest）
|
||||
- 接口测试（MockMvc）
|
||||
|
||||
### 必须覆盖的场景
|
||||
- 正常流程
|
||||
- 边界条件
|
||||
- 异常处理
|
||||
- 并发安全
|
||||
@@ -0,0 +1,400 @@
|
||||
# Phase 1 Infrastructure - Tasks
|
||||
|
||||
## 任务清单
|
||||
|
||||
### Day 1-2: 数据库 + 实体 + 会话（8 个任务）
|
||||
|
||||
#### Task 1.1: 添加依赖到 pom.xml
|
||||
**优先级**: P0（阻塞后续任务）
|
||||
**预估时间**: 15 分钟
|
||||
**产出**:
|
||||
- 修改 `pom.xml`
|
||||
- 添加：spring-boot-starter-data-jpa, mysql-connector-j, flyway-core, flyway-mysql, spring-boot-starter-data-redis, spring-boot-starter-test, h2
|
||||
**验收**: `mvn clean compile` 成功
|
||||
|
||||
---
|
||||
|
||||
#### Task 1.2: 创建 Flyway 迁移脚本 - diagnosis_record
|
||||
**优先级**: P0
|
||||
**预估时间**: 30 分钟
|
||||
**产出**:
|
||||
- `src/main/resources/db/migration/V001__create_diagnosis_record.sql`
|
||||
**依据**: `docs/tables/diagnosis_record.md`
|
||||
**验收**:
|
||||
- 表结构与文档一致
|
||||
- 索引完整
|
||||
- 注释完整
|
||||
- 本地 MySQL 执行成功
|
||||
|
||||
---
|
||||
|
||||
#### Task 1.3: 创建 Flyway 迁移脚本 - case_library
|
||||
**优先级**: P0
|
||||
**预估时间**: 20 分钟
|
||||
**产出**:
|
||||
- `src/main/resources/db/migration/V002__create_case_library.sql`
|
||||
**依据**: `docs/tables/case_library.md`
|
||||
**验收**: 同 Task 1.2
|
||||
|
||||
---
|
||||
|
||||
#### Task 1.4: 创建 Flyway 迁移脚本 - api_document
|
||||
**优先级**: P0
|
||||
**预估时间**: 20 分钟
|
||||
**产出**:
|
||||
- `src/main/resources/db/migration/V003__create_api_document.sql`
|
||||
**依据**: `docs/tables/api_document.md`
|
||||
**验收**: 同 Task 1.2
|
||||
|
||||
---
|
||||
|
||||
#### Task 1.5: 配置 MySQL + Redis + Flyway
|
||||
**优先级**: P0
|
||||
**预估时间**: 20 分钟
|
||||
**产出**:
|
||||
- 修改 `src/main/resources/application.yml`
|
||||
- 添加 spring.datasource, spring.jpa, spring.flyway, spring.data.redis 配置
|
||||
**验收**:
|
||||
- 应用启动成功
|
||||
- Flyway 自动执行迁移
|
||||
- 3 张表创建成功
|
||||
|
||||
---
|
||||
|
||||
#### Task 1.6: 创建 JPA 实体类
|
||||
**优先级**: P0
|
||||
**预估时间**: 45 分钟
|
||||
**产出**:
|
||||
- `com.superbiz.agent.domain.entity.DiagnosisRecord`
|
||||
- `com.superbiz.agent.domain.entity.CaseLibrary`
|
||||
- `com.superbiz.agent.domain.entity.ApiDocument`
|
||||
**依赖**: Task 1.2, 1.3, 1.4
|
||||
**验收**:
|
||||
- 字段与数据库一致
|
||||
- Lombok 注解完整
|
||||
- JSON 字段序列化正确
|
||||
- 编译通过
|
||||
|
||||
---
|
||||
|
||||
#### Task 1.7: 创建 Repository 接口
|
||||
**优先级**: P0
|
||||
**预估时间**: 30 分钟
|
||||
**产出**:
|
||||
- `com.superbiz.agent.repository.DiagnosisRecordRepository`
|
||||
- `com.superbiz.agent.repository.CaseLibraryRepository`
|
||||
- `com.superbiz.agent.repository.ApiDocumentRepository`
|
||||
**依赖**: Task 1.6
|
||||
**验收**:
|
||||
- 继承 JpaRepository
|
||||
- 常用查询方法定义
|
||||
- 编译通过
|
||||
|
||||
---
|
||||
|
||||
#### Task 1.8: Repository 单元测试
|
||||
**优先级**: P1
|
||||
**预估时间**: 60 分钟
|
||||
**产出**:
|
||||
- `DiagnosisRecordRepositoryTest`
|
||||
- `CaseLibraryRepositoryTest`
|
||||
- `ApiDocumentRepositoryTest`
|
||||
**依赖**: Task 1.7
|
||||
**测试框架**: @DataJpaTest + H2
|
||||
**验收**:
|
||||
- 测试覆盖率 100%
|
||||
- CRUD 测试通过
|
||||
- 自定义查询测试通过
|
||||
|
||||
---
|
||||
|
||||
#### Task 1.9: 创建会话管理接口
|
||||
**优先级**: P0
|
||||
**预估时间**: 30 分钟
|
||||
**产出**:
|
||||
- `com.superbiz.agent.session.SessionManager` (接口)
|
||||
- `com.superbiz.agent.session.SessionContext` (数据类)
|
||||
- `com.superbiz.agent.session.ToolCall` (数据类)
|
||||
**验收**:
|
||||
- 接口定义清晰
|
||||
- SessionContext 字段完整（含 intentType）
|
||||
- 编译通过
|
||||
|
||||
---
|
||||
|
||||
#### Task 1.10: Redis 会话管理实现
|
||||
**优先级**: P0
|
||||
**预估时间**: 45 分钟
|
||||
**产出**:
|
||||
- `com.superbiz.agent.session.RedisSessionManager`
|
||||
- `com.superbiz.agent.session.SessionConfiguration`
|
||||
**依赖**: Task 1.9
|
||||
**验收**:
|
||||
- 实现 SessionManager 接口
|
||||
- TTL 设置为 30 分钟
|
||||
- JSON 序列化配置正确
|
||||
- 编译通过
|
||||
|
||||
---
|
||||
|
||||
#### Task 1.11: Redis 会话管理单元测试
|
||||
**优先级**: P1
|
||||
**预估时间**: 45 分钟
|
||||
**产出**:
|
||||
- `RedisSessionManagerTest`
|
||||
**依赖**: Task 1.10
|
||||
**测试框架**: @SpringBootTest + Mock RedisTemplate
|
||||
**验收**:
|
||||
- 存取删测试通过
|
||||
- TTL 测试通过
|
||||
- 序列化测试通过
|
||||
|
||||
---
|
||||
|
||||
### Day 3: 代码结构重构（3 个任务）
|
||||
|
||||
#### Task 3.1: 包名重构
|
||||
**优先级**: P0
|
||||
**预估时间**: 30 分钟
|
||||
**操作**:
|
||||
1. IDEA Refactor → Rename Package
|
||||
2. `org.example` → `com.superbiz.agent`
|
||||
3. 更新 `pom.xml` 中的 mainClass
|
||||
4. 全局搜索确认无遗漏
|
||||
**验收**:
|
||||
- 编译通过
|
||||
- 启动成功
|
||||
- 无遗漏的 org.example
|
||||
|
||||
---
|
||||
|
||||
#### Task 3.2: 分层结构优化
|
||||
**优先级**: P1
|
||||
**预估时间**: 45 分钟
|
||||
**产出**:
|
||||
- 创建目录结构（controller/service/repository/domain/tool/config/exception）
|
||||
- 移动现有类到对应目录
|
||||
**验收**:
|
||||
- 目录结构符合 design.md
|
||||
- 编译通过
|
||||
- 启动成功
|
||||
|
||||
---
|
||||
|
||||
#### Task 3.3: DTO 抽离
|
||||
**优先级**: P1
|
||||
**预估时间**: 60 分钟
|
||||
**产出**:
|
||||
- `com.superbiz.agent.domain.dto.DiagnosisRequest`
|
||||
- `com.superbiz.agent.domain.dto.DiagnosisResponse`
|
||||
- `com.superbiz.agent.domain.dto.DocumentUploadRequest`
|
||||
- `com.superbiz.agent.domain.dto.DocumentQueryResponse`
|
||||
- `com.superbiz.agent.domain.dto.Result<T>` (统一响应)
|
||||
**验收**:
|
||||
- Controller 不 import Entity
|
||||
- 编译通过
|
||||
|
||||
---
|
||||
|
||||
### Day 4-5: 文档管理（7 个任务）
|
||||
|
||||
#### Task 4.1: 创建 TextExtractor 服务
|
||||
**优先级**: P0
|
||||
**预估时间**: 60 分钟
|
||||
**产出**:
|
||||
- `com.superbiz.agent.service.TextExtractor`
|
||||
**功能**:
|
||||
- 支持 .txt, .md, .docx, .pdf
|
||||
- 提取纯文本
|
||||
**依赖**: 可能需要添加 Apache POI / PDFBox 依赖
|
||||
**验收**:
|
||||
- 4 种格式提取成功
|
||||
- 单元测试覆盖
|
||||
|
||||
---
|
||||
|
||||
#### Task 4.2: 文档分块服务
|
||||
**优先级**: P0
|
||||
**预估时间**: 30 分钟
|
||||
**产出**:
|
||||
- `com.superbiz.agent.service.DocumentChunkService` (可能已存在，重构)
|
||||
**功能**:
|
||||
- chunk_size=500
|
||||
- overlap=50
|
||||
**验收**:
|
||||
- 分块逻辑正确
|
||||
- 单元测试通过
|
||||
|
||||
---
|
||||
|
||||
#### Task 4.3: 文档上传接口
|
||||
**优先级**: P0
|
||||
**预估时间**: 90 分钟
|
||||
**产出**:
|
||||
- `com.superbiz.agent.controller.DocumentController#upload`
|
||||
- `com.superbiz.agent.service.DocumentService#uploadDocument`
|
||||
**依赖**: Task 4.1, 4.2
|
||||
**验收**:
|
||||
- 上传成功返回 documentId
|
||||
- MySQL + Milvus 数据一致
|
||||
- 异常处理完整
|
||||
- 单元测试覆盖
|
||||
|
||||
---
|
||||
|
||||
#### Task 4.4: 文档查询接口
|
||||
**优先级**: P1
|
||||
**预估时间**: 30 分钟
|
||||
**产出**:
|
||||
- `DocumentController#query`
|
||||
- `DocumentService#queryDocuments`
|
||||
**验收**:
|
||||
- 分页查询正确
|
||||
- 过滤条件生效
|
||||
- 单元测试覆盖
|
||||
|
||||
---
|
||||
|
||||
#### Task 4.5: 文档删除接口
|
||||
**优先级**: P1
|
||||
**预估时间**: 45 分钟
|
||||
**产出**:
|
||||
- `DocumentController#delete`
|
||||
- `DocumentService#deleteDocument`
|
||||
**验收**:
|
||||
- MySQL 删除成功
|
||||
- Milvus 删除成功
|
||||
- 幂等性保证
|
||||
- 单元测试覆盖
|
||||
|
||||
---
|
||||
|
||||
#### Task 4.6: 混合检索工具
|
||||
**优先级**: P0
|
||||
**预估时间**: 90 分钟
|
||||
**产出**:
|
||||
- `com.superbiz.agent.tool.DocumentSearchTool`
|
||||
**功能**:
|
||||
- 精确匹配（MySQL）
|
||||
- 语义检索（Milvus）
|
||||
- RRF 融合
|
||||
**验收**:
|
||||
- 精确匹配优先
|
||||
- 语义检索补漏
|
||||
- 返回 Top 3
|
||||
- 单元测试覆盖
|
||||
|
||||
---
|
||||
|
||||
#### Task 4.7: 集成测试
|
||||
**优先级**: P1
|
||||
**预估时间**: 60 分钟
|
||||
**产出**:
|
||||
- `DocumentIntegrationTest`
|
||||
**测试场景**:
|
||||
- 上传 → 查询 → 检索 → 删除 完整流程
|
||||
**验收**:
|
||||
- 端到端测试通过
|
||||
|
||||
---
|
||||
|
||||
### 全局任务
|
||||
|
||||
#### Task G.1: 统一异常处理
|
||||
**优先级**: P1
|
||||
**预估时间**: 30 分钟
|
||||
**产出**:
|
||||
- `com.superbiz.agent.exception.GlobalExceptionHandler`
|
||||
- `com.superbiz.agent.exception.SessionNotFoundException`
|
||||
- `com.superbiz.agent.exception.DocumentProcessException`
|
||||
**验收**:
|
||||
- 异常统一捕获
|
||||
- 返回格式统一
|
||||
|
||||
---
|
||||
|
||||
#### Task G.2: Docker Compose 配置
|
||||
**优先级**: P2
|
||||
**预估时间**: 20 分钟
|
||||
**产出**:
|
||||
- `docker-compose.yml` (MySQL + Redis + Milvus)
|
||||
**验收**:
|
||||
- `docker-compose up -d` 启动成功
|
||||
- 应用连接成功
|
||||
|
||||
---
|
||||
|
||||
#### Task G.3: README 更新
|
||||
**优先级**: P2
|
||||
**预估时间**: 15 分钟
|
||||
**产出**:
|
||||
- 更新 `README.md`
|
||||
- 添加 Phase 1 安装说明
|
||||
- 添加本地开发指南
|
||||
|
||||
---
|
||||
|
||||
## 任务依赖关系图
|
||||
|
||||
```
|
||||
Day 1-2:
|
||||
Task 1.1 → Task 1.5
|
||||
↓
|
||||
Task 1.2, 1.3, 1.4 → Task 1.6 → Task 1.7 → Task 1.8
|
||||
↓
|
||||
Task 1.5 → Task 1.9 → Task 1.10 → Task 1.11
|
||||
|
||||
Day 3:
|
||||
Task 3.1 (阻塞) → Task 3.2 → Task 3.3
|
||||
|
||||
Day 4-5:
|
||||
Task 4.1, 4.2 → Task 4.3 → Task 4.7
|
||||
↓
|
||||
Task 4.4
|
||||
↓
|
||||
Task 4.5
|
||||
↓
|
||||
Task 4.6 → Task 4.7
|
||||
|
||||
全局:
|
||||
Task G.1 (并行)
|
||||
Task G.2 (并行)
|
||||
Task G.3 (最后)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关键路径
|
||||
|
||||
```
|
||||
Task 1.1 → 1.5 → 1.6 → 1.7 → 3.1 → 3.2 → 4.1 → 4.3 → 4.6 → 4.7
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 预估总工时
|
||||
|
||||
- Day 1-2: 5.5 小时（11 个任务）
|
||||
- Day 3: 2 小时（3 个任务）
|
||||
- Day 4-5: 6 小时（7 个任务）
|
||||
- 全局: 1 小时（3 个任务）
|
||||
|
||||
**总计**: 14.5 小时（约 2 个完整工作日）
|
||||
|
||||
---
|
||||
|
||||
## 里程碑
|
||||
|
||||
**Milestone 1**: Day 2 结束
|
||||
- ✅ 数据库表就绪
|
||||
- ✅ JPA + Repository 可用
|
||||
- ✅ Redis 会话管理可用
|
||||
|
||||
**Milestone 2**: Day 3 结束
|
||||
- ✅ 包名重构完成
|
||||
- ✅ 代码结构清晰
|
||||
|
||||
**Milestone 3**: Day 5 结束
|
||||
- ✅ 文档管理 CRUD 完整
|
||||
- ✅ 混合检索工具可用
|
||||
- ✅ 单元测试覆盖率达标（70%+）
|
||||
@@ -144,6 +144,45 @@
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-starter-mcp-client-webflux</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- MySQL + JPA -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-data-jpa</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>com.mysql</groupId>
|
||||
<artifactId>mysql-connector-j</artifactId>
|
||||
<scope>runtime</scope>
|
||||
</dependency>
|
||||
|
||||
<!-- Flyway 数据库迁移 -->
|
||||
<dependency>
|
||||
<groupId>org.flywaydb</groupId>
|
||||
<artifactId>flyway-core</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.flywaydb</groupId>
|
||||
<artifactId>flyway-mysql</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- Redis -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-data-redis</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- 测试依赖 -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-test</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>com.h2database</groupId>
|
||||
<artifactId>h2</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
package com.superbiz.agent.domain.enums;
|
||||
|
||||
/**
|
||||
* 诊断状态枚举
|
||||
*/
|
||||
public enum DiagnosisStatus {
|
||||
PENDING("待处理"),
|
||||
RUNNING("诊断中"),
|
||||
SUCCESS("成功"),
|
||||
FAILED("失败");
|
||||
|
||||
private final String description;
|
||||
|
||||
DiagnosisStatus(String description) {
|
||||
this.description = description;
|
||||
}
|
||||
|
||||
public String getDescription() {
|
||||
return description;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,25 @@
|
||||
package com.superbiz.agent.domain.enums;
|
||||
|
||||
/**
|
||||
* 故障类别枚举
|
||||
*/
|
||||
public enum FaultCategory {
|
||||
EXTERNAL_API("外部接口调用失败"),
|
||||
INTERNAL_ERROR("系统内部错误"),
|
||||
DATABASE("数据库问题"),
|
||||
CACHE("缓存问题"),
|
||||
NETWORK("网络问题"),
|
||||
THREAD("线程问题"),
|
||||
MEMORY("内存问题"),
|
||||
CONFIG("配置问题");
|
||||
|
||||
private final String description;
|
||||
|
||||
FaultCategory(String description) {
|
||||
this.description = description;
|
||||
}
|
||||
|
||||
public String getDescription() {
|
||||
return description;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
package com.superbiz.agent.domain.enums;
|
||||
|
||||
/**
|
||||
* 案例来源类型枚举
|
||||
*/
|
||||
public enum SourceType {
|
||||
AUTO("自动生成"),
|
||||
MANUAL("人工录入");
|
||||
|
||||
private final String description;
|
||||
|
||||
SourceType(String description) {
|
||||
this.description = description;
|
||||
}
|
||||
|
||||
public String getDescription() {
|
||||
return description;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
-- V001: 创建诊断记录表
|
||||
-- 核心业务表，存储每次诊断任务的完整记录
|
||||
-- 设计理念：兼容多种故障类型（外部接口、内部错误、数据库、缓存等）
|
||||
|
||||
CREATE TABLE diagnosis_record (
|
||||
-- 主键
|
||||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||||
diagnosis_id VARCHAR(64) UNIQUE NOT NULL COMMENT '诊断唯一ID（UUID）',
|
||||
|
||||
-- 关联信息
|
||||
session_id VARCHAR(64) COMMENT '会话ID（关联Redis）',
|
||||
business_id VARCHAR(128) COMMENT '业务标识（订单号/请求ID/线程ID/任务ID...）',
|
||||
trace_id VARCHAR(64) COMMENT '链路追踪ID',
|
||||
|
||||
-- 故障分类（泛化设计）
|
||||
fault_category VARCHAR(32) COMMENT '故障类别（EXTERNAL_API/INTERNAL_ERROR/DATABASE/CACHE/NETWORK/THREAD/MEMORY/CONFIG）',
|
||||
fault_source VARCHAR(128) COMMENT '故障源（省份/服务名/类名/数据库实例...）',
|
||||
fault_target VARCHAR(256) COMMENT '故障目标（接口URL/方法名/SQL语句/缓存键...）',
|
||||
|
||||
-- 错误信息（通用）
|
||||
error_code VARCHAR(64) COMMENT '错误码（业务错误码/HTTP状态码/异常类名）',
|
||||
error_message TEXT COMMENT '错误消息',
|
||||
stack_trace TEXT COMMENT '堆栈信息（内部错误时记录）',
|
||||
|
||||
-- 诊断结果
|
||||
problem_type VARCHAR(32) COMMENT '问题类型（参数/网络/权限/逻辑/空指针/死锁...）',
|
||||
root_cause TEXT COMMENT '根因分析',
|
||||
solution TEXT COMMENT '修复方案',
|
||||
report_markdown TEXT COMMENT '完整诊断报告（Markdown格式）',
|
||||
|
||||
-- 评估指标
|
||||
status VARCHAR(16) DEFAULT 'PENDING' COMMENT '诊断状态（PENDING/RUNNING/SUCCESS/FAILED）',
|
||||
confidence INT COMMENT '诊断置信度（0-100）',
|
||||
duration INT COMMENT '诊断耗时（毫秒）',
|
||||
|
||||
-- 用户反馈
|
||||
feedback VARCHAR(16) COMMENT '用户反馈（useful/not_useful/null）',
|
||||
|
||||
-- 调试字段
|
||||
tool_calls JSON COMMENT '工具调用记录',
|
||||
|
||||
-- 元数据
|
||||
created_by VARCHAR(64) COMMENT '创建人',
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||||
|
||||
-- 索引
|
||||
INDEX idx_business_id (business_id),
|
||||
INDEX idx_trace_id (trace_id),
|
||||
INDEX idx_session_id (session_id),
|
||||
INDEX idx_fault_category (fault_category),
|
||||
INDEX idx_fault_source_target (fault_source, fault_target(100)),
|
||||
INDEX idx_error_code (error_code),
|
||||
INDEX idx_created_at (created_at),
|
||||
INDEX idx_status (status)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='诊断记录表（v2.0 泛化版）';
|
||||
@@ -0,0 +1,41 @@
|
||||
-- V002: 创建案例库表
|
||||
-- 知识沉淀表，存储高质量诊断案例，支持相似案例推荐
|
||||
-- 设计理念：质量过滤，只存储成功诊断 + 用户反馈有用的案例
|
||||
|
||||
CREATE TABLE case_library (
|
||||
-- 主键
|
||||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||||
case_id VARCHAR(64) UNIQUE NOT NULL COMMENT '案例唯一ID（UUID）',
|
||||
|
||||
-- 来源关联
|
||||
diagnosis_id VARCHAR(64) COMMENT '关联诊断记录（可选，人工录入时为空）',
|
||||
source_type VARCHAR(16) DEFAULT 'AUTO' COMMENT '来源类型（AUTO:自动生成/MANUAL:人工录入）',
|
||||
|
||||
-- 案例分类
|
||||
fault_category VARCHAR(32) COMMENT '故障类别（EXTERNAL_API/INTERNAL_ERROR/DATABASE...）',
|
||||
fault_source VARCHAR(128) COMMENT '故障源（省份/服务名/类名...）',
|
||||
fault_target VARCHAR(256) COMMENT '故障目标（接口URL/方法名/SQL...）',
|
||||
error_code VARCHAR(64) COMMENT '错误码',
|
||||
|
||||
-- 案例内容
|
||||
title VARCHAR(256) NOT NULL COMMENT '案例标题（简短描述）',
|
||||
root_cause TEXT NOT NULL COMMENT '根因分析',
|
||||
solution TEXT NOT NULL COMMENT '解决方案',
|
||||
|
||||
-- 简单统计
|
||||
reference_count INT DEFAULT 0 COMMENT '引用次数（被推荐的次数）',
|
||||
|
||||
-- 元数据
|
||||
created_by VARCHAR(64) COMMENT '创建人',
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||||
|
||||
-- 索引
|
||||
INDEX idx_fault_category (fault_category),
|
||||
INDEX idx_error_code (error_code),
|
||||
INDEX idx_fault_source (fault_source),
|
||||
INDEX idx_fault_target (fault_target(100)),
|
||||
INDEX idx_diagnosis_id (diagnosis_id),
|
||||
INDEX idx_reference_count (reference_count),
|
||||
INDEX idx_created_at (created_at)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='案例库表（MVP版）';
|
||||
@@ -0,0 +1,38 @@
|
||||
-- V003: 创建文档元数据表
|
||||
-- 文档管理表，管理接口文档的元信息
|
||||
-- 设计理念：MySQL 负责元数据管理，Milvus 负责内容检索，通过 doc_id 关联
|
||||
|
||||
CREATE TABLE api_document (
|
||||
-- 主键
|
||||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||||
doc_id VARCHAR(64) UNIQUE NOT NULL COMMENT '文档唯一ID（UUID），关联Milvus',
|
||||
|
||||
-- 文档分类
|
||||
fault_category VARCHAR(32) DEFAULT 'EXTERNAL_API' COMMENT '文档类别',
|
||||
fault_source VARCHAR(128) COMMENT '文档归属（省份/服务名）',
|
||||
api_name VARCHAR(128) COMMENT '接口名称',
|
||||
version VARCHAR(32) DEFAULT 'v1.0' COMMENT '文档版本',
|
||||
|
||||
-- 文件信息
|
||||
file_name VARCHAR(256) NOT NULL COMMENT '原始文件名',
|
||||
file_path VARCHAR(512) COMMENT '文件存储路径',
|
||||
file_hash VARCHAR(64) COMMENT '文件MD5 hash（用于去重）',
|
||||
file_size BIGINT COMMENT '文件大小（字节）',
|
||||
|
||||
-- 索引状态
|
||||
status VARCHAR(16) DEFAULT 'PENDING' COMMENT '索引状态（PENDING/PROCESSING/INDEXED/FAILED）',
|
||||
chunk_count INT DEFAULT 0 COMMENT '分块数量',
|
||||
error_message TEXT COMMENT '失败原因',
|
||||
|
||||
-- 时间字段
|
||||
indexed_at DATETIME COMMENT '索引完成时间',
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||||
|
||||
-- 索引
|
||||
UNIQUE INDEX uk_file_hash (file_hash),
|
||||
INDEX idx_doc_id (doc_id),
|
||||
INDEX idx_fault_source (fault_source),
|
||||
INDEX idx_status (status),
|
||||
INDEX idx_created_at (created_at)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文档元数据表（MVP版）';
|
||||
Reference in New Issue
Block a user