┌──────────────────────────────────────────────────────────────┐
│                     Web UI (index.html)                       │
│     SSE 流式渲染 · Markdown 解析 · 会话管理 · 知识库面板       │
│     深色/亮色主题 · 移动端适配 · 消息复制 · 自定义提示框       │
│     统一 Results JSON 解析 · SSE error 事件处理                │
└───────────────────────┬──────────────────────────────────────┘
                        │ POST /api/chat {sessionId, question}
                        ▼
┌──────────────────────────────────────────────────────────────┐
│                    RateLimitAspect (@RateLimit)               │
│        Redisson 令牌桶（IP 30次/分 + 每日 10,000 次）         │
│        429 → 统一 Results 格式返回                            │
└───────────────────────┬──────────────────────────────────────┘
                        ▼
┌──────────────────────────────────────────────────────────────┐
│                      ChatController                           │
│            SseEmitter (120s timeout) · Jackson 序列化          │
└───────────────────────┬──────────────────────────────────────┘
                        ▼
┌──────────────────────────────────────────────────────────────┐
│                       RAG Pipeline                            │
│                                                               │
│  ┌──────────────┐   ┌───────────────┐   ┌─────────────────┐  │
│  │  会话历史      │──▶│  Query        │──▶│  Embedding      │  │
│  │  Redis        │   │  Rewriting    │   │  BGE-large-zh   │  │
│  └──────────────┘   └───────────────┘   └───────┬─────────┘  │
│                                                  ▼            │
│                                           ┌────────────┐     │
│                                           │ Vector      │     │
│                                           │ Store       │     │
│                                           │ top 20      │     │
│                                           └─────┬──────┘     │
│                                                  ▼            │
│  ┌──────────────┐   ┌───────────────┐   ┌─────────────────┐  │
│  │ LLM 回答      │◀──│ Prompt 组装    │◀──│ Rerank          │  │
│  │ DeepSeek /    │   │ 引用 + 约束   │   │ BGE-reranker   │  │
│  │ OpenAI 兼容   │   │              │   │ top 5          │  │
│  └──────────────┘   └───────────────┘   └─────────────────┘  │
│                                                               │
│  ┌───────────────────────────────────────────────────────┐    │
│  │ 文档来源                                               │   │
│  │  ├─ Web 上传（Multipart 文件上传，SHA256 去重）         │   │
│  │  ├─ 目录扫描（data/docs/ 自动扫描）                     │   │
│  │  └─ 飞书知识库同步（Feishu Wiki Sync）                  │   │
│  └───────────────┬───────────────────────────────────────┘    │
│                  │ 元数据                                     │
│                  ▼                                            │
│  ┌──────────────────────────────────────────────────────┐    │
│  │              MySQL + MyBatis-Plus                     │    │
│  │  documents（文档元数据） · document_chunks（分块映射） │   │
│  └──────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────┘

                         ┌────────────┐
                         │   Redis    │ ← 多实例共享会话 + 分布式限流计数器
                         └────────────┘

接收文档 → 去重检查（查询 documents 表）
  ├─ 已存在 → 跳过，返回已有记录
  └─ 不存在 → 解析 → 分块（300 字符/块，60 字符重叠）
              → 批量 Embedding（10 条/批）
              → 写入向量库 → 捕获 vectorId
              → INSERT documents + INSERT document_chunks

---

## API 参考

所有接口统一返回 `Results<T>` 格式，前端通过 `resCode` 判断状态、`msg` 显示提示、`obj` 获取数据。

```json
{
  "resCode": "200",
  "msg": "成功",
  "obj": { ... }
}

event: message
data: {"token":"逐","token":"步","token":"输","token":"出"}

event: message
data: {"token":"完"}

data: [DONE]

event: error
data: {"resCode":"500","msg":"流式处理失败: Redis 连接异常"}

data: [DONE]

src/main/java/com/rag/studyhelper/
├── controller/
│   ├── ChatController.java              # SSE 流式问答接口
│   └── DocumentController.java          # 文档管理接口
├── service/
│   ├── RagQueryService.java             # RAG 核心流程编排
│   ├── DocumentIngestionService.java    # 文档解析、去重、向量化与 MySQL 持久化
│   ├── RedisConversationStore.java      # Redis 会话存储（多实例共享）
│   ├── ConversationStore.java           # 会话存储接口
│   ├── RateLimitService.java            # 分布式限流（Redisson 令牌桶 + 每日计数）
│   ├── RerankService.java               # SiliconFlow Rerank 调用
│   └── QueryRewriteService.java         # 多轮查询改写
├── config/
│   ├── LangChain4jConfig.java           # LLM / Embedding / VectorStore 配置
│   ├── MyBatisPlusConfig.java           # MyBatis-Plus 分页插件
│   ├── MyMetaObjectHandler.java         # 自动填充创建/更新时间
│   ├── GlobalExceptionHandler.java      # @RestControllerAdvice 统一异常处理
│   ├── RedissonConfig.java              # Redisson 客户端（复用 spring.redis.*）
│   ├── RateLimit.java                   # @RateLimit 限流注解
│   └── RateLimitAspect.java             # 限流切面（AOP 环绕通知）
├── utils/
│   └── Results.java                     # 统一 API 响应体（resCode / msg / obj）
├── mapper/
│   ├── DocumentsMapper.java             # 文档元数据 Mapper
│   └── DocumentChunksMapper.java        # 文档分块映射 Mapper
├── model/
│   ├── ChatRequest.java
│   ├── ChatMessage.java
│   ├── DocumentInfo.java
│   ├── Documents.java                   # documents 表实体
│   └── DocumentChunks.java             # document_chunks 表实体
├── feishu/
│   ├── client/
│   │   ├── FeishuClient.java            # 飞书 API 封装（文档/表格/多维表格）
│   │   └── WikiNode.java                # 知识库节点模型
│   ├── service/
│   │   └── FeishuSyncService.java       # 同步编排 + @Scheduled 定时任务
│   └── config/
│       ├── FeishuProperties.java        # 配置绑定
│       └── FeishuConfig.java            # Spring Bean 装配
└── RagStudyHelperApplication.java

src/main/resources/
├── application.yml                      # 主配置
└── static/index.html                    # 前端页面

项目根目录/
├── init.sql                             # MySQL DDL（首次启动自动执行）

src/test/java/com/rag/studyhelper/
├── config/
│   ├── GlobalExceptionHandlerTest.java   # 异常处理单元测试
│   └── ExceptionTestController.java      # 测试辅助 Controller
├── controller/
│   └── ChatControllerIntegrationTest.java
├── service/
│   ├── DocumentSplitterTest.java
│   ├── RagQueryServiceTest.java
│   └── RerankServiceTest.java
├── feishu/
│   ├── client/FeishuClientTest.java
│   └── service/FeishuSyncServiceTest.java
└── RagStudyHelperApplicationTests.java