docs: 重构文档结构，分离学习笔记和 MVP 架构设计

**变更概述：**
- 将 MVP 架构设计文档独立到项目根目录 `mvp/`
- 整理 `docs/` 为纯学习和分析文档目录
- 按类型分类：learning（学习）、analysis（分析）、reports（报告）、guides（指南）

**目录结构：**
```
mvp/                          # MVP 架构设计（独立）
├── README.md                 # 数据库设计总览
├── architecture/             # 架构文档
│   ├── agent-architecture-mvp.md
│   ├── implementation-plan.md
│   └── ...
└── tables/                   # 数据表设计

docs/                         # 学习和分析文档
├── learning/                 # 学习笔记（00-08 编号）
├── analysis/                 # 分析笔记 + 重构计划
├── reports/                  # 临时报告
└── guides/                   # 指南文档
```

**详细变更：**
- docs/README.md → mvp/README.md（数据库设计入口）
- docs/architecture/ → mvp/architecture/（架构设计）
- docs/tables/ → mvp/tables/（数据表设计）
- docs/学习笔记-*.md → docs/learning/07-*.md, 08-*.md
- docs/项目学习路径.md → docs/learning/00-*.md
- docs/功能分析报告.md → docs/analysis/
- docs/修复报告-*.md → docs/reports/
- docs/日志配置*.md → docs/guides/ 或 docs/reports/
- docs/design/ → docs/analysis/（问题分析和重构计划）

docs/learning/00-项目学习路径.md

@@ -0,0 +1,659 @@
+# SuperBizAgent-java 项目学习路径
+
+> 创建日期：2026-05-30  
+> 项目规模：58 文件，1528 符号，2828 关系，87 执行流  
+> 核心技术：Spring AI + DeepSeek V4 + BGE-M3 + Milvus + Agent 协同
+
+---
+
+## 📋 学习目标
+
+通过本学习路径，你将掌握：
+
+1. ✅ **AI Ops 自动化分析**的完整执行流程（3-Agent 协同架构）
+2. ✅ **Chat 对话系统**的 RAG 知识库检索机制
+3. ✅ **模型抽象与路由**的解耦设计（ChatModel/EmbeddingModel）
+4. ✅ **Tools 工具集**的设计模式（Prometheus/CLS/RAG）
+5. ✅ **向量数据库**的文档分块、向量化、检索全流程
+
+**预计总耗时**：2-3 小时（可分多次完成）
+
+---
+
+## 🎯 学习路径（推荐顺序）
+
+### 📍 阶段 1：核心执行流理解（30-40 分钟）⭐️ **从这里开始**
+
+**目标**：理解系统的 2 条主线执行流程
+
+---
+
+#### 1.1 AI Ops 自动化分析流程 ⭐️⭐️⭐️
+
+**为什么从这里开始？**
+- 这是项目最核心、最有特色的功能
+- 涉及 Agent 协同、工具调用、流式响应等关键技术
+- 理解了它，其他模块会一通百通
+
+**执行流程图**：
+
+```
+用户点击 "AI Ops" 按钮
+    ↓
+HTTP POST /api/ai_ops
+    ↓
+ChatController.aiOps()
+    ↓
+AiOpsService.executeAiOpsAnalysis()
+    ↓
+┌────────────────────────────────────────┐
+│ Phase 1: Planner Agent 制定分析计划    │
+│  - 输入：固定的规划 Prompt             │
+│  - 输出：分析计划（要查哪些告警、日志）│
+└────────────────────────────────────────┘
+    ↓
+┌────────────────────────────────────────┐
+│ Phase 2: Executor Agent 执行工具调用   │
+│  ├─ QueryMetricsTools.queryActiveAlerts()│
+│  │   → Prometheus 告警（Mock 模式）    │
+│  ├─ QueryLogsTools.queryLogs()         │
+│  │   → 腾讯云 CLS 日志（Mock 模式）    │
+│  └─ InternalDocsTools.queryInternalDocs()│
+│      → RAG 知识库检索                   │
+└────────────────────────────────────────┘
+    ↓
+┌────────────────────────────────────────┐
+│ Phase 3: Supervisor Agent 生成报告     │
+│  - 输入：Planner 计划 + Executor 数据  │
+│  - 输出：结构化告警分析报告            │
+│  - 格式：Markdown（表格、列表、代码块）│
+└────────────────────────────────────────┘
+    ↓
+SSE 流式返回前端
+    ↓
+前端渲染 Markdown
+```
+
+**学习步骤**：
+
+**Step 1.1.1：阅读 Controller 入口**
+
+```bash
+Read src/main/java/org/example/controller/ChatController.java
+```
+
+**关注点**：
+- `aiOps()` 方法（第 106-117 行左右）
+- 如何设置 SSE 响应头（`text/event-stream`）
+- 如何调用 `AiOpsService.executeAiOpsAnalysis()`
+
+**预期收获**：理解 HTTP 层如何触发 AI Ops 分析
+
+---
+
+**Step 1.1.2：阅读核心 Service**
+
+```bash
+Read src/main/java/org/example/service/AiOpsService.java
+```
+
+**关注点**：
+- `executeAiOpsAnalysis()` 方法（核心入口）
+- `buildPlannerAgent()` 方法（如何构建规划 Agent）
+- `buildExecutorAgent()` 方法（如何构建执行 Agent）
+- `buildSupervisorSystemPrompt()` 方法（如何构建最终报告生成 Prompt）
+- 3 个 Agent 如何协同工作（chain 调用）
+
+**预期收获**：理解 3-Agent 协同架构
+
+---
+
+**Step 1.1.3：查看依赖图**
+
+```bash
+在 Claude Code 中执行：
+mcp__gitnexus__context({name: "AiOpsService", repo: "SuperBizAgent-java"})
+```
+
+**关注点**：
+- `outgoing.has_property`：依赖了哪些 Tools
+- `incoming.imports`：被谁调用（应该是 ChatController）
+
+**预期收获**：理解 AiOpsService 的依赖关系
+
+---
+
+**Step 1.1.4：如果要修改，先做影响分析**
+
+```bash
+mcp__gitnexus__impact({
+  target: "executeAiOpsAnalysis", 
+  direction: "upstream", 
+  repo: "SuperBizAgent-java"
+})
+```
+
+**预期收获**：理解修改这个方法会影响哪些代码
+
+---
+
+**🎓 阶段 1.1 总结**：
+
+完成后，你应该能回答：
+1. AI Ops 分析为什么用 3 个 Agent 而不是 1 个？
+2. Planner 和 Executor 的输入输出分别是什么？
+3. 为什么要用 SSE 而不是普通的 HTTP 响应？
+4. Mock 模式下，告警和日志数据从哪里来？
+
+---
+
+#### 1.2 Chat 对话流程
+
+**执行流程图**：
+
+```
+用户输入消息 → 点击发送
+    ↓
+HTTP POST /api/chat
+    ↓
+ChatController.chat()
+    ↓
+ChatService.executeChat(userMessage, sessionId)
+    ↓
+createReactAgent(ChatModel, tools)
+    ├─ InternalDocsTools (RAG 检索)
+    ├─ DateTimeTools (时间查询)
+    ├─ QueryMetricsTools (告警查询)
+    └─ QueryLogsTools (日志查询)
+    ↓
+ReactAgent.stream(userMessage)
+    ↓
+根据用户问题，自动选择调用哪些 Tools
+    ↓
+SSE 流式返回
+    ↓
+前端渲染
+```
+
+**学习步骤**：
+
+**Step 1.2.1：阅读 ChatService**
+
+```bash
+Read src/main/java/org/example/service/ChatService.java
+```
+
+**关注点**：
+- `executeChat()` 方法
+- `createReactAgent()` 方法（如何注册 Tools）
+- `buildSystemPrompt()` 方法（系统提示词）
+- `getToolCallbacks()` 方法（MCP 工具回调，可选）
+
+**预期收获**：理解 ReactAgent 如何工作
+
+---
+
+**Step 1.2.2：查看 InternalDocsTools（RAG 核心）**
+
+```bash
+Read src/main/java/org/example/tools/InternalDocsTools.java
+```
+
+```bash
+mcp__gitnexus__context({name: "InternalDocsTools", repo: "SuperBizAgent-java"})
+```
+
+**关注点**：
+- `queryInternalDocs()` 方法
+- 如何调用 `RagService.queryRelevantDocs()`
+- 返回值结构
+
+**预期收获**：理解 RAG 如何嵌入到 Agent 工具链
+
+---
+
+**🎓 阶段 1.2 总结**：
+
+完成后，你应该能回答：
+1. ReactAgent 如何决定调用哪个 Tool？
+2. Chat 和 AI Ops 使用的 Agent 有什么区别？
+3. 为什么 Chat 需要 sessionId 而 AI Ops 不需要？
+
+---
+
+### 📍 阶段 2：RAG 知识库链路（20 分钟）
+
+**目标**：理解文档上传 → 向量化 → 检索的完整链路
+
+---
+
+#### 2.1 文档上传与向量化
+
+**执行流程图**：
+
+```
+用户上传文档 (txt/md)
+    ↓
+HTTP POST /api/upload
+    ↓
+FileUploadController.upload()
+    ↓
+RagService.processAndStoreDocument()
+    ├─ 文档分块
+    │   └─ ChunkingStrategy.splitByParagraphs()
+    │       ├─ 段落识别（\n\n）
+    │       ├─ Token 估算（estimateTokens）
+    │       └─ 重叠策略（overlap=100）
+    ├─ 向量化
+    │   └─ VectorEmbeddingService.generateEmbeddings()
+    │       └─ SiliconFlow BGE-M3 (1024 维)
+    └─ 存储到 Milvus
+        └─ MilvusClientFactory.insert()
+```
+
+**学习步骤**：
+
+**Step 2.1.1：阅读 RagService**
+
+```bash
+Read src/main/java/org/example/service/RagService.java
+```
+
+**关注点**：
+- `processAndStoreDocument()` 方法（完整流程）
+- `queryRelevantDocs()` 方法（检索流程）
+- 分块策略（`ChunkingStrategy`）
+
+---
+
+**Step 2.1.2：阅读 VectorEmbeddingService**
+
+```bash
+Read src/main/java/org/example/service/VectorEmbeddingService.java
+```
+
+**关注点**：
+- `generateEmbedding()` 单条向量化
+- `generateEmbeddings()` 批量向量化
+- 如何调用 `EmbeddingModel.embed()`
+
+---
+
+**Step 2.1.3：阅读 MilvusClientFactory**
+
+```bash
+Read src/main/java/org/example/client/MilvusClientFactory.java
+```
+
+**关注点**：
+- `createClient()` 方法（Zilliz Cloud 连接）
+- Collection 创建逻辑
+- 索引类型（IVF_FLAT）
+- `loadCollection()` 调用（重要！搜索前必须 load）
+
+---
+
+**🎓 阶段 2 总结**：
+
+完成后，你应该能回答：
+1. 文档分块为什么要有 overlap？overlap=100 的意义是什么？
+2. 为什么用 BGE-M3 而不是其他 Embedding 模型？
+3. Milvus 的 IVF_FLAT 索引适合什么场景？什么时候需要换 HNSW？
+4. 为什么 Collection 创建后要手动 `loadCollection()`？
+
+---
+
+### 📍 阶段 3：模型抽象与路由（15 分钟）
+
+**目标**：理解 ChatModel/EmbeddingModel 如何解耦和路由
+
+**背景**：这是 2026-05-29 重构的核心成果（见 `devflow/projects/2026-05-29-chatmodel-abstraction/`）
+
+---
+
+#### 3.1 模型路由机制
+
+**架构图**：
+
+```
+application.yml
+    ├─ model-routing.chat: deepseek
+    └─ model-routing.embedding: siliconflow
+         ↓
+ModelRoutingConfig.java
+    ├─ routeChatModel()
+    │   └─ List<ChatModel> → 匹配 "deepseek" → @Primary
+    └─ routeEmbeddingModel()
+        └─ Map<String, EmbeddingModel> → 匹配 "siliconflow" → @Primary
+             ↓
+Spring 容器注入
+    ├─ ChatService @Autowired ChatModel → DeepSeek V4 Flash
+    └─ VectorEmbeddingService @Autowired EmbeddingModel → SiliconFlow BGE-M3
+```
+
+**学习步骤**：
+
+**Step 3.1.1：阅读 ModelRoutingConfig**
+
+```bash
+Read src/main/java/org/example/config/ModelRoutingConfig.java
+```
+
+**关注点**：
+- `routeChatModel()` 方法的匹配逻辑
+- `routeEmbeddingModel()` 方法的匹配逻辑
+- 为什么用 `List<ChatModel>` 而不是 `@Qualifier`？
+
+---
+
+**Step 3.1.2：阅读 SiliconFlowEmbeddingConfig**
+
+```bash
+Read src/main/java/org/example/config/SiliconFlowEmbeddingConfig.java
+```
+
+**关注点**：
+- 如何创建独立的 `OpenAiApi`
+- 为什么 base-url 不能带 `/v1` 后缀？（参考 decisions.md L3）
+
+---
+
+**Step 3.1.3：阅读 application.yml**
+
+```bash
+Read src/main/resources/application.yml
+```
+
+**关注点**（第 23-62 行）：
+- `model-routing` 配置
+- `spring.ai.deepseek` 配置
+- `siliconflow` 配置
+- 为什么 `spring.ai.openai.api-key: unused`？
+
+---
+
+**🎓 阶段 3 总结**：
+
+完成后，你应该能回答：
+1. 如果要换成 Ollama 本地模型，需要改哪些配置？
+2. 为什么 `@Qualifier` 方案会失败？（参考 decisions.md L2）
+3. Spring AI 1.1.0 为什么不能用 OpenAI 兼容模式调 DeepSeek？（参考 decisions.md L1）
+
+---
+
+### 📍 阶段 4：Tools 工具集（20 分钟）
+
+**目标**：理解 Agent 可调用的所有工具
+
+---
+
+#### 4.1 工具清单
+
+| 工具类 | 功能 | 核心方法 | 文件路径 |
+|--------|------|---------|---------|
+| `InternalDocsTools` | RAG 知识库检索 | `queryInternalDocs()` | `tools/InternalDocsTools.java` |
+| `DateTimeTools` | 获取当前时间 | `getCurrentDateTime()` | `tools/DateTimeTools.java` |
+| `QueryMetricsTools` | Prometheus 告警查询 | `queryActiveAlerts()` | `tools/QueryMetricsTools.java` |
+| `QueryLogsTools` | 腾讯云 CLS 日志查询 | `queryLogs()` | `tools/QueryLogsTools.java` |
+
+---
+
+**学习步骤**：
+
+**Step 4.1.1：查看所有 Tool 类**
+
+```bash
+Glob pattern="**/tools/*.java"
+```
+
+---
+
+**Step 4.1.2：阅读 QueryMetricsTools（Mock 模式）**
+
+```bash
+Read src/main/java/org/example/tools/QueryMetricsTools.java
+```
+
+**关注点**：
+- `@Tool` 注解（Spring AI 的工具注册机制）
+- `mockEnabled` 配置的作用
+- Mock 数据结构（模拟 Prometheus 告警）
+
+---
+
+**Step 4.1.3：阅读 QueryLogsTools（Mock 模式）**
+
+```bash
+Read src/main/java/org/example/tools/QueryLogsTools.java
+```
+
+**关注点**：
+- 如何根据告警名称返回关联的日志
+- Mock 数据如何与 AI Ops 分析报告对应
+
+---
+
+**🎓 阶段 4 总结**：
+
+完成后，你应该能回答：
+1. 如果要新增一个工具（如 K8s 事件查询），需要做什么？
+2. Mock 模式的数据是否可以通过配置文件管理？
+3. 为什么 Tool 方法要返回 String 而不是复杂对象？
+
+---
+
+### 📍 阶段 5：配置与基础设施（10 分钟）
+
+**目标**：理解配置项和基础设施
+
+---
+
+**Step 5.1：阅读 application.yml**
+
+```bash
+Read src/main/resources/application.yml
+```
+
+**关注清单**：
+
+| 配置项 | 作用 | 默认值 | 修改场景 |
+|--------|------|--------|---------|
+| `milvus.host` | Zilliz Cloud 地址 | in03-xxx.cloud.zilliz.com | 换集群 |
+| `milvus.vector-dim` | 向量维度 | 1024 (BGE-M3) | 换模型 |
+| `model-routing.chat` | Chat 模型路由 | deepseek | 换模型 |
+| `model-routing.embedding` | Embedding 路由 | siliconflow | 换模型 |
+| `document.chunk.max-size` | 分块最大 Token | 800 | 优化检索 |
+| `rag.top-k` | 检索返回数 | 3 | 优化检索 |
+| `prometheus.mock-enabled` | Prometheus Mock | true | 接入真实 Prometheus |
+| `cls.mock-enabled` | CLS Mock | true | 接入真实腾讯云 CLS |
+
+---
+
+**Step 5.2：阅读 MilvusProperties**
+
+```bash
+Read src/main/java/org/example/config/MilvusProperties.java
+```
+
+**关注点**：
+- `@ConfigurationProperties(prefix = "milvus")`
+- 为什么 `vectorDim` 要从配置读取？（参考 brief.md）
+
+---
+
+**🎓 阶段 5 总结**：
+
+完成后，你应该能回答：
+1. 如果 Embedding 模型从 BGE-M3 (1024维) 换成 text-embedding-ada-002 (1536维)，需要改哪些配置？
+2. Mock 模式如何切换到真实环境？
+
+---
+
+## 📊 学习检查点
+
+完成每个阶段后，勾选对应的检查点：
+
+### ✅ 阶段 1 检查点
+
+- [ ] 我能画出 AI Ops 的完整执行流程图
+- [ ] 我理解了 Planner、Executor、Supervisor 的职责
+- [ ] 我知道如何修改 Planner 的分析策略
+- [ ] 我能解释 SSE 流式响应的优势
+
+### ✅ 阶段 2 检查点
+
+- [ ] 我能画出文档上传到向量存储的完整流程
+- [ ] 我理解了文档分块策略的 overlap 参数
+- [ ] 我知道如何调整 top-k 影响检索结果
+- [ ] 我能解释为什么 Collection 需要 load
+
+### ✅ 阶段 3 检查点
+
+- [ ] 我理解了 `@Primary` 路由的原理
+- [ ] 我能通过修改 yml 切换模型
+- [ ] 我知道为什么不用 `@Qualifier`
+- [ ] 我能添加新的模型提供商（如 Ollama）
+
+### ✅ 阶段 4 检查点
+
+- [ ] 我理解了 `@Tool` 注解的作用
+- [ ] 我能新增一个自定义工具
+- [ ] 我知道 Mock 模式的数据结构
+- [ ] 我能对接真实的 Prometheus/CLS
+
+### ✅ 阶段 5 检查点
+
+- [ ] 我理解了所有关键配置项
+- [ ] 我能修改配置优化 RAG 检索
+- [ ] 我知道如何切换到生产环境配置
+
+---
+
+## 🎯 进阶学习路径
+
+完成基础学习后，可以尝试：
+
+### 进阶 1：深入 Agent 协同模式
+
+```bash
+# 阅读 Spring AI Agent Framework 源码
+Read pom.xml  # 查看 spring-ai-alibaba-starter-agent 版本
+```
+
+**研究方向**：
+- ReactAgent 的 Tool 选择算法
+- Agent 链式调用的状态传递
+- Agent 的异常处理机制
+
+---
+
+### 进阶 2：性能优化
+
+**优化点**：
+1. **Milvus 索引优化**：IVF_FLAT → HNSW
+2. **分块策略优化**：调整 max-size 和 overlap
+3. **批量向量化**：优化 `generateEmbeddings()` 批量大小
+4. **缓存策略**：热点查询缓存
+
+**推荐操作**：
+```bash
+# 查看向量化服务
+Read src/main/java/org/example/service/VectorEmbeddingService.java
+
+# 查看 Milvus 客户端
+Read src/main/java/org/example/client/MilvusClientFactory.java
+```
+
+---
+
+### 进阶 3：功能扩展
+
+**扩展方向**：
+
+1. **新增工具**：
+   - K8s 事件查询工具
+   - Grafana Dashboard 查询工具
+   - Jira Issue 创建工具
+
+2. **新增 Agent**：
+   - 根因分析专家 Agent
+   - 修复建议生成 Agent
+   - 历史告警对比 Agent
+
+3. **新增模型支持**：
+   - Ollama 本地模型
+   - Azure OpenAI
+   - Anthropic Claude
+
+---
+
+## 📚 参考文档
+
+### 项目文档
+
+| 文档 | 用途 |
+|------|------|
+| `docs/功能分析报告.md` | 项目功能概览、技术栈、分析案例 |
+| `docs/日志配置与分析指南.md` | 日志配置、分析场景、故障排查 |
+| `devflow/projects/2026-05-29-chatmodel-abstraction/` | ChatModel 重构的完整记录 |
+| `CLAUDE.md` | GitNexus 使用规范（影响分析、变更检测） |
+
+### 技术文档
+
+| 技术 | 官方文档 |
+|------|---------|
+| Spring AI | https://docs.spring.io/spring-ai/ |
+| Milvus | https://milvus.io/docs |
+| DeepSeek API | https://platform.deepseek.com/docs |
+| SiliconFlow | https://siliconflow.cn/docs |
+
+---
+
+## 🚀 开始学习
+
+**推荐第一步**：
+
+```bash
+# 1. 阅读 AI Ops 核心 Service
+Read src/main/java/org/example/service/AiOpsService.java
+
+# 2. 查看依赖图
+mcp__gitnexus__context({name: "AiOpsService", repo: "SuperBizAgent-java"})
+
+# 3. 如果打算修改，先做影响分析
+mcp__gitnexus__impact({target: "AiOpsService", direction: "upstream", repo: "SuperBizAgent-java"})
+```
+
+**学习节奏建议**：
+- **快速模式**（1 小时）：只完成阶段 1 + 阶段 3
+- **标准模式**（2 小时）：完成阶段 1-4
+- **深度模式**（3 小时）：完成全部 5 个阶段 + 进阶路径
+
+---
+
+## 🎓 学习产出建议
+
+学习过程中，建议你输出以下文档（保存到 `docs/learning/`）：
+
+| 文档 | 内容 |
+|------|------|
+| `AI-Ops-执行流.md` | 手绘执行流程图 + 关键代码片段 |
+| `RAG-知识库设计.md` | 文档分块策略、向量化、检索全流程 |
+| `模型路由机制.md` | ChatModel/EmbeddingModel 路由源码分析 |
+| `Tools-工具集.md` | 所有工具的作用、参数、返回值、扩展方案 |
+| `学习笔记.md` | 每个阶段的收获、疑问、TODO |
+
+---
+
+> 💡 **提示**：这个学习路径是基于项目当前状态（2026-05-30）设计的。如果项目有重大更新，请重新执行 `npx gitnexus analyze` 更新索引。
+
+---
+
+**立即开始**：
+
+```bash
+# Step 1: 从 AI Ops 开始
+Read src/main/java/org/example/service/AiOpsService.java
+```
+
+祝学习愉快！🎉