# 知识库模块实施计划

## 技术选型

| 项目 | 选择 |
|------|------|
| 文档解析 | Apache Tika（一个依赖支持 PDF/Word/TXT/MD） |
| 向量化引擎 | Ollama（默认 `nomic-embed-text`）或 DeepSeek（`text-embedding-3-small`），**前端可切换** |
| 向量存储 | PostgreSQL + pgvector（已有） |
| 文件存储 | MinIO（已有） |
| 切片策略 | 500 Token，10% 重叠 |

## 实施步骤

### Step 0：AI 配置管理（前置）

| 端 | 内容 |
|----|------|
| 后端新增 | `AiConfigService` — 读取/写入 AI 配置（provider、模型名、API Key），存入 Redis |
| 后端实现 | `AiConfigController` 的 get/put/test 三个方法 |
| 后端改动 | `EmbeddingService` 每次调用前查配置，根据 provider 路由到 Ollama 或 DeepSeek |
| 前端新增 | 知识库页内加"Embedding 配置"区域：Provider 下拉框（Ollama / DeepSeek）+ 模型名输入框 |

### Step 1：添加依赖

修改 `ims-service/pom.xml`，新增依赖：

| 依赖 | 用途 |
|------|------|
| `org.apache.tika:tika-core` | 文档解析 |
| `org.springframework.ai:spring-ai-ollama-spring-boot-starter` | Ollama Embedding 调用 |

### Step 2：创建 Service 接口 + 实现（8 个新文件）

| 文件 | 包路径 | 说明 |
|------|--------|------|
| `EmbeddingService.java` | `com.ims.service.knowledge` | 接口：`embed(text)` + `search(query, topK)` |
| `AiConfigService.java` | `com.ims.service.knowledge` | AI 配置读写，存入 Redis |
| `OllamaEmbeddingService.java` | `com.ims.service.knowledge` | 调用 Ollama 实现 Embedding |
| `DeepSeekEmbeddingService.java` | `com.ims.service.knowledge` | 调用 DeepSeek API 实现 Embedding |
| `DocumentParserService.java` | `com.ims.service.knowledge` | Tika 解析 + 500 Token 切片 |
| `KnowledgeService.java` | `com.ims.service.knowledge` | 上传→MinIO→DB、列表、删除、重新索引 |
| `SearchService.java` | `com.ims.service.knowledge` | pgvector 余弦相似度检索 |
| `SearchLogService.java` | `com.ims.service.knowledge` | 检索审计日志记录 |

### Step 3：实现 Controller

| Controller | 方法 | 功能 |
|-----------|------|------|
| `AiConfigController` | `GET /api/v1/ai/config` | 读取 AI 配置 |
| | `PUT /api/v1/ai/config` | 更新 AI 配置 |
| | `POST /api/v1/ai/config/test` | 测试连接 |
| `KnowledgeController` | `GET /documents` | 文档列表（分页） |
| | `POST /documents` | 上传文档 → 解析 → 切片 → 向量化 → 入库 |
| | `DELETE /documents/{id}` | 删除文档 + MinIO 文件 + 向量 |
| | `POST /documents/{id}/reindex` | 重新向量化 |
| | `GET /search` | 检索接口 |
| | `GET /logs` | 检索日志列表 |

### Step 4：前端知识库页面

修改 `frontend/src/pages/knowledge-base/index.tsx`：

| 组件 | 参考设计 |
|------|---------|
| Tab 切换 | 文档管理 / 检索审计 |
| Embedding 配置区 | Provider 下拉框（Ollama / DeepSeek）+ 模型名输入框 |
| 上传拖拽区 | Ant Design `Upload.Dragger` |
| 文档表格 | Ant Design `Table`（文件名/上传人/时间/状态/分块数/操作） |
| 搜索框 | Ant Design `Input.Search` |
| 检索日志表格 | Ant Design `Table` |
| 统计卡片 | Ant Design `Card` + `Statistic` |

### Step 5：配置

| 项目 | 操作 |
|------|------|
| Ollama 模型 | `ollama pull nomic-embed-text` |
| MinIO bucket | 管理后台创建 `ims-attachments` |

## 文件清单

```
修改：
  backend/ims-service/pom.xml                              +2 依赖
  backend/ims-api/src/main/java/.../AiConfigController.java    填充 3 个方法
  backend/ims-api/src/main/java/.../KnowledgeController.java   填充 6 个方法
  frontend/src/pages/knowledge-base/index.tsx              重写

新增（后端）：
  backend/ims-service/src/main/java/com/ims/service/knowledge/
    ├── EmbeddingService.java
    ├── AiConfigService.java
    ├── OllamaEmbeddingService.java
    ├── DeepSeekEmbeddingService.java
    ├── DocumentParserService.java
    ├── KnowledgeService.java
    ├── SearchService.java
    └── SearchLogService.java

新增（前端）：
  frontend/src/pages/knowledge-base/services.ts            API 封装
```

## 实施顺序

```
前置条件（你手动执行）
  ① ollama pull nomic-embed-text（如果用 DeepSeek 则跳过）
  ② MinIO 创建 ims-attachments bucket
  ③ 如需 DeepSeek 则准备 API Key
        ↓
代码实施（我写）
  Step 0: AiConfigService + AiConfigController + 前端配置区
  Step 1: pom.xml 加依赖 → mvn install 验证
  Step 2: 8 个 Service 文件
  Step 3: 填充 Controller
  Step 4: 前端页面 + services.ts
        ↓
验证
  ① 启动后端 + 前端
  ② 配置页选择 Ollama + nomic-embed-text → 保存
  ③ 上传一个 PDF → 检查是否解析/切片/向量化成功
  ④ 检索 → 检查返回结果
  ⑤ 查看审计日志
  ⑥ 切到 DeepSeek 重新索引 → 验证 DeepSeek 向量化
```