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/（问题分析和重构计划）
2026-06-23 14:14:51 +08:00
parent caef477cec
commit 60be51f4a5
25 changed files with 339 additions and 606 deletions
@@ -0,0 +1,275 @@
+# 日志配置完成总结
+
+## ✅ 已完成的工作
+
+### 1. 配置文件添加
+
+| 文件 | 说明 |
+|------|------|
+| `src/main/resources/application.yml` | 添加 logging 配置（简单模式） |
+| `src/main/resources/logback-spring.xml` | Logback 完整配置（推荐使用） |
+
+### 2. 日志输出位置
+
+项目启动后，日志会自动输出到：
+
+```
+logs/
+├── application.log              # 所有日志（滚动）
+├── application-error.log        # 仅 ERROR 日志
+├── aiops.log                    # AI Ops 专用
+├── chat.log                     # Chat 对话专用
+└── application-2026-05-30.0.log # 历史日志（按日期滚动）
+```
+
+### 3. 日志特性
+
+- ✅ **控制台输出** + **文件输出**（双通道）
+- ✅ **彩色高亮**（控制台）
+- ✅ **按模块分文件**（aiops.log、chat.log）
+- ✅ **异步写入**（提升性能）
+- ✅ **自动滚动**（按日期 + 大小）
+- ✅ **保留 30 天**（可配置）
+- ✅ **总大小限制 1GB**（防止磁盘爆满）
+
+### 4. 日志级别
+
+| 包 | 级别 | 说明 |
+|---|------|------|
+| `org.example` | DEBUG | 本项目所有类（详细日志） |
+| `org.springframework.ai` | DEBUG | Spring AI 框架 |
+| `org.springframework` | INFO | Spring 框架 |
+| `com.alibaba.cloud` | WARN | 第三方库降噪 |
+| `ROOT` | INFO | 其他所有 |
+
+---
+
+## 🚀 使用方式
+
+### 方式 1：启动项目后手动查看
+
+```bash
+# 启动项目
+mvn spring-boot:run
+
+# 另一个终端查看日志
+tail -f logs/application.log
+
+# 只看错误
+tail -f logs/application-error.log
+
+# 只看 AI Ops
+tail -f logs/aiops.log
+```
+
+### 方式 2：在 Claude Code 中分析（推荐）
+
+**实时日志**：
+```
+! tail -n 100 logs/application.log
+```
+输出会直接进入对话，Claude 可以分析。
+
+**搜索日志**：
+```
+使用 Grep 工具：
+- pattern: "ERROR.*OOM"
+- path: logs/application.log
+- output_mode: content
+```
+
+**读取日志片段**：
+```
+Read logs/application.log (limit: 100)
+Read logs/aiops.log (offset: 500, limit: 50)
+```
+
+---
+
+## 📊 典型分析场景
+
+### 场景 1：AI Ops 分析耗时诊断
+
+```
+1. 用户报告："AI Ops 分析太慢"
+2. Claude 执行：Read logs/aiops.log (limit: 100)
+3. Claude 分析：
+   - Prometheus 查询 15s（异常，正常 <1s）
+   - CLS 日志查询 4s（正常）
+   - LLM 推理 35s（正常）
+4. 结论：Prometheus 服务端慢查询，建议优化 PromQL
+```
+
+### 场景 2：模型调用失败排查
+
+```
+1. 用户报告："对话没有响应"
+2. Claude 执行：Grep pattern="ERROR.*DeepSeek" path=logs/application-error.log
+3. Claude 分析：
+   java.net.SocketTimeoutException: Read timed out
+   at DeepSeekChatModel.call(...)
+4. 结论：DeepSeek API 超时，建议增加 timeout 或检查网络
+```
+
+### 场景 3：完整链路追踪
+
+```
+1. 用户报告："某次对话返回了错误结果"
+2. Claude 执行：
+   - Read logs/chat.log → 找到请求时间 13:05:23
+   - Grep pattern="13:05:2[0-9]" path=logs/application.log → 完整链路
+3. Claude 分析：
+   - ChatController 收到请求 13:05:23.123
+   - ChatService 调用 DeepSeek 13:05:23.456
+   - DeepSeek 返回 200 OK 13:05:24.789
+   - 发现：返回内容被截断（content.length() > 4096）
+4. 结论：响应长度超过限制，需要调整配置
+```
+
+---
+
+## 🛠️ 故障排查清单
+
+### 问题：logs/ 目录没有生成
+
+**检查**：
+1. 项目是否启动成功？
+2. 查看控制台是否有 Logback 错误
+3. 检查 `logback-spring.xml` 语法
+
+**解决**：
+```bash
+# 验证配置
+bash scripts/verify-logging.sh
+```
+
+### 问题：日志文件为空
+
+**检查**：
+1. 日志级别是否太高（改为 DEBUG）
+2. 是否触发了对应的功能（如 aiops.log 需要点击 AI Ops）
+
+**解决**：
+```yaml
+# application.yml
+logging:
+  level:
+    org.example: DEBUG  # 确保是 DEBUG
+```
+
+### 问题：控制台看不到彩色日志
+
+**原因**：Windows CMD 不支持 ANSI 颜色
+
+**解决**：
+- 使用 Git Bash
+- 使用 PowerShell 7+
+- 使用 Windows Terminal
+- 或只看文件日志（无影响）
+
+---
+
+## 📝 配置调整
+
+### 调整日志级别
+
+编辑 `src/main/resources/logback-spring.xml`：
+
+```xml
+<!-- 只看 ERROR 和 WARN -->
+<logger name="org.example" level="WARN" additivity="false">
+    <appender-ref ref="CONSOLE"/>
+    <appender-ref ref="ASYNC_FILE_ALL"/>
+</logger>
+
+<!-- 增加某个类的详细日志 -->
+<logger name="org.example.service.RagService" level="TRACE" additivity="false">
+    <appender-ref ref="CONSOLE"/>
+    <appender-ref ref="FILE_ALL"/>
+</logger>
+```
+
+### 调整滚动策略
+
+```xml
+<!-- 保留 90 天 -->
+<maxHistory>90</maxHistory>
+
+<!-- 单文件最大 50MB -->
+<maxFileSize>50MB</maxFileSize>
+
+<!-- 总大小 5GB -->
+<totalSizeCap>5GB</totalSizeCap>
+```
+
+### 添加新的专用日志文件
+
+```xml
+<!-- 新增 RAG 专用日志 -->
+<appender name="FILE_RAG" class="ch.qos.logback.core.rolling.RollingFileAppender">
+    <file>${LOG_PATH}/rag.log</file>
+    <!-- ... -->
+</appender>
+
+<logger name="org.example.service.RagService" level="DEBUG" additivity="false">
+    <appender-ref ref="FILE_RAG"/>
+</logger>
+```
+
+---
+
+## 🎯 下一步
+
+### 立即验证
+
+1. **启动项目**：
+   ```bash
+   mvn spring-boot:run
+   ```
+
+2. **检查日志文件生成**：
+   ```bash
+   ls -lh logs/
+   ```
+   应该看到 `application.log` 立即生成。
+
+3. **触发功能并查看专用日志**：
+   - 发送一条对话 → `logs/chat.log` 出现
+   - 点击 AI Ops → `logs/aiops.log` 出现
+
+4. **在 Claude Code 中分析**：
+   ```
+   ! tail -n 50 logs/application.log
+   ```
+
+### 集成到开发流程
+
+1. **每次调试新功能**：
+   ```
+   ! tail -f logs/application.log
+   ```
+   在另一个终端实时查看日志。
+
+2. **提交代码前**：
+   ```
+   Read logs/application-error.log
+   ```
+   确保没有遗漏的错误。
+
+3. **性能优化时**：
+   ```
+   Grep pattern="耗时.*ms" path=logs/aiops.log
+   ```
+   提取所有耗时日志分析瓶颈。
+
+---
+
+## 📚 相关文档
+
+- **详细指南**：[docs/日志配置与分析指南.md](./日志配置与分析指南.md)
+- **配置文件**：`src/main/resources/logback-spring.xml`
+- **验证脚本**：`scripts/verify-logging.sh` / `scripts/verify-logging.bat`
+
+---
+
+> 🎉 **配置完成！** 现在 Claude 可以通过读取日志文件来分析你的项目运行情况了。