# ref-manager

**Repository Path**: oxtop/ref-manager

## Basic Information

- **Project Name**: ref-manager
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-28
- **Last Updated**: 2025-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文献助手系统 (Literature Assistant)

基于SpringBoot3.5的智能文献管理系统，支持多格式文档解析、AI智能分析和阅读指南生成。

## 项目特性

### 核心功能
- 📄 **多格式文档支持**: PDF、Word、Markdown、TXT四种格式解析
- 🤖 **AI智能分析**: 集成Kimi AI进行文献深度智能分析
- 📚 **实时阅读指南**: SSE流式响应生成个性化阅读指南
- 🏷️ **智能分类标签**: 自动提取和分类文献标签
- 📊 **完整文献管理**: 文献信息存储、查询、更新、删除
- 🔍 **智能搜索**: 支持按关键词、类型、标签搜索

### 技术特性
- ✅ SpringBoot 3.5.5 企业级框架
- ✅ MyBatis-Plus 3.5.5 ORM框架
- ✅ H2嵌入式数据库 (持久化存储)
- ✅ 多格式文档处理 (Apache POI, PDFBox, CommonMark)
- ✅ AI接口集成 (Kimi AI + OkHttp)
- ✅ SSE流式响应支持
- ✅ Knife4j 4.5.0 API文档
- ✅ Hutool 5.8.29 工具类库
- ✅ Lombok 代码简化
- ✅ 统一异常处理体系
- ✅ 分页查询支持
- ✅ 文件工具类库

## 技术栈

### 后端框架
- **框架**: SpringBoot 3.5.5
- **Java版本**: 21
- **构建工具**: Maven
- **数据库**: H2 (嵌入式，持久化存储)
- **ORM框架**: MyBatis-Plus 3.5.5

### 文档处理
- **PDF处理**: Apache PDFBox 2.0.29
- **Word处理**: Apache POI 5.2.5
- **Markdown处理**: CommonMark 0.21.0
- **纯文本处理**: Java NIO
- **文件操作**: Apache Commons IO 2.15.1

### AI集成
- **AI服务**: Kimi AI (Moonshot)
- **HTTP客户端**: OkHttp 4.12.0
- **流式响应**: OkHttp SSE 4.12.0
- **JSON处理**: Jackson

### 开发工具
- **API文档**: Knife4j 4.5.0
- **工具库**: Hutool 5.8.29
- **代码简化**: Lombok
- **连接池**: HikariCP
- **参数验证**: SpringBoot Validation

## 项目结构

```
src/main/java/com/oxtop/refmanager/
├── RefManagerApplication.java          # SpringBoot启动类
├── common/                            # 通用基础类
│   ├── constant/                      # 常量定义
│   │   └── CommonConstants.java       # 通用常量类
│   ├── dto/                          # 基础数据传输对象
│   │   └── BaseDTO.java              # 基础DTO类
│   ├── entity/                       # 基础实体类
│   │   └── BaseEntity.java           # 基础实体类
│   ├── exception/                    # 异常处理体系
│   │   ├── BaseException.java        # 基础异常类
│   │   ├── BusinessException.java    # 业务异常类
│   │   └── ValidationException.java  # 参数验证异常类
│   ├── handler/                      # 全局处理器
│   │   └── GlobalExceptionHandler.java # 全局异常处理器
│   ├── request/                      # 请求响应类
│   │   ├── BaseRequest.java         # 基础请求类
│   │   ├── PageRequest.java         # 分页请求类
│   │   └── PageResult.java          # 分页响应类
│   ├── result/                       # 响应结果类
│   │   ├── Result.java              # 统一响应类
│   │   └── ResultCode.java          # 响应码枚举
│   └── utils/                        # 工具类
│       ├── ResponseUtils.java       # 响应工具类
│       └── FileUtils.java           # 文件处理工具类
├── config/                           # 配置类
│   ├── CorsConfig.java              # 跨域配置
│   ├── Knife4jConfig.java           # API文档配置
│   └── MyBatisPlusConfig.java       # MyBatis-Plus配置
├── controller/                       # 控制器层
│   ├── LiteratureController.java    # 文献管理控制器
│   ├── LiteratureGuideController.java # 文献指南控制器
│   └── TestController.java          # 测试控制器
├── service/                          # 服务层
│   ├── LiteratureService.java       # 文献服务接口
│   ├── DocumentParseService.java    # 文档解析服务
│   ├── KimiAIService.java           # AI服务
│   └── impl/                        # 服务实现
│       └── LiteratureServiceImpl.java # 文献服务实现
├── entity/                           # 实体类
│   └── Literature.java              # 文献实体类
├── mapper/                           # 数据访问层
│   └── LiteratureMapper.java        # 文献数据访问接口
├── dto/                              # 数据传输对象
│   ├── LiteratureUploadRequest.java # 文献上传请求
│   ├── LiteratureQueryRequest.java   # 文献查询请求
│   ├── LiteratureUpdateRequest.java  # 文献更新请求
│   └── LiteratureGuideRequest.java  # 文献指南请求
└── vo/                               # 视图对象
    ├── LiteratureResponse.java      # 文献响应对象
    ├── LiteratureListResponse.java   # 文献列表响应
    ├── LiteratureGuideResponse.java # 文献指南响应
    └── LiteratureClassificationResponse.java # 分类响应对象
```

## 快速开始

### 1. 环境要求

- JDK 21+
- Maven 3.6+
- 无需额外数据库安装 (使用H2嵌入式数据库，数据自动持久化)

### 2. 配置说明

#### 数据库配置
项目使用H2嵌入式数据库，数据文件自动保存在 `./data/ref-manager.mv.db`

#### AI配置
在 `application.yml` 中配置Kimi AI接口：

```yaml
literature:
  ai:
    base-url: https://api.moonshot.cn/v1
    model: kimi-k2-turbo-preview
    max-tokens: 20480
    temperature: 0.7
    timeout: 60000
    system-prompt-file: classpath:prompts/literature-guide-system-prompt.txt
    classification-prompt-file: classpath:prompts/literature-classification-system-prompt.txt
```

#### 文件上传配置
```yaml
literature:
  file:
    upload-path: ./uploads/documents
    max-file-size: 10MB
    allowed-extensions: pdf,doc,docx,md,markdown,txt
```

### 3. 启动应用

```bash
# 编译项目
mvn clean compile

# 运行应用
mvn spring-boot:run

# 或者使用启动脚本
./start.sh
```

### 4. 访问接口文档

启动成功后，访问以下地址：

- **Knife4j文档**: http://localhost:8086/api/doc.html
- **Swagger JSON**: http://localhost:8086/api/v3/api-docs
- **H2数据库控制台**: http://localhost:8086/api/h2-console
- **健康检查**: http://localhost:8086/api/test/hello

## 核心功能

### 1. 多格式文档处理
- 支持PDF、Word、Markdown、TXT四种格式
- 自动提取文档内容和元数据
- 智能识别文档类型和结构
- 实时内容长度统计

### 2. AI智能分析集成
- 集成Kimi AI进行深度文献分析
- 自动生成个性化阅读指南
- 智能分类和标签提取
- 支持自定义系统提示词
- 实时SSE流式响应

### 3. 完整文献管理系统
- 文献信息持久化存储 (H2数据库)
- 支持按关键词、类型、标签搜索
- 分页查询和统计信息
- 完整的CRUD操作 (增删改查)
- 文件管理和版本控制

## API接口说明

### 测试接口
| 接口 | 方法 | 描述 |
|------|------|------|
| `/test/hello` | GET | 系统健康检查 |

### 文献管理接口

| 接口 | 方法 | 描述 |
|------|------|------|
| `/literature/file-types` | GET | 获取支持的文件类型 |
| `/literature/tags` | GET | 获取所有标签 |
| `/literature/statistics` | GET | 获取统计信息 |
| `/literature/list` | GET | 分页查询文献列表 |
| `/literature/{id}` | GET | 获取文献详情 |
| `/literature/upload` | POST | 上传文献文件 |
| `/literature/generate-guide` | POST | 生成阅读指南（SSE流式） |
| `/literature/update` | PUT | 更新文献信息 |
| `/literature/{id}` | DELETE | 删除文献 |
| `/literature/batch` | DELETE | 批量删除文献 |
| `/literature/test-ai-connection` | POST | 测试AI连接 |

### 响应格式

#### 成功响应
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": 1703123456789
}
```

#### 分页响应
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [],
    "total": 100,
    "current": 1,
    "size": 10,
    "pages": 10,
    "hasNext": true,
    "hasPrevious": false
  },
  "timestamp": 1703123456789
}
```

#### 错误响应
```json
{
  "code": 500,
  "message": "系统内部错误",
  "data": null,
  "timestamp": 1703123456789
}
```

## 开发指南

### 1. 创建新的Controller

```java
@RestController
@RequestMapping("/api/example")
@Tag(name = "示例接口", description = "示例功能接口")
public class ExampleController extends BaseController {
    
    @GetMapping("/list")
    @Operation(summary = "获取列表", description = "获取示例数据列表")
    public PageResult<ExampleVO> getList(PageRequest pageRequest) {
        // 业务逻辑
        return PageResult.success(records, total, current, size);
    }
}
```

### 2. 异常处理

```java
// 抛出业务异常
throw new BusinessException(ErrorCode.DATA_NOT_FOUND.getCode(), "数据不存在");

// 抛出系统异常
throw new SystemException(ErrorCode.DATABASE_ERROR.getCode(), "数据库操作失败");
```

### 3. 参数验证

```java
@PostMapping("/create")
public Result<String> create(@Valid @RequestBody CreateRequest request) {
    // 业务逻辑
    return Result.success("创建成功");
}
```

## 配置说明

### 应用配置

- **端口**: 8080
- **上下文路径**: /api
- **字符编码**: UTF-8

### 跨域配置

- **允许源**: 所有源 (*)
- **允许方法**: GET, POST, PUT, DELETE, OPTIONS
- **允许头**: 所有头 (*)
- **允许凭证**: 是

### 文件上传配置

- **上传路径**: ./uploads/documents/
- **最大文件大小**: 10MB
- **允许文件类型**: pdf, doc, docx, md, markdown

### AI配置

- **AI服务**: Kimi AI (Moonshot)
- **模型**: kimi-k2-turbo-preview
- **最大Token**: 20480
- **温度参数**: 0.7
- **超时时间**: 60秒

### 数据库配置

- **数据库类型**: H2嵌入式数据库
- **数据文件**: ./data/ref_manager.mv.db
- **连接池**: HikariCP
- **最大连接数**: 20

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 操作成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
| 1000-1999 | 业务错误 |
| 2000-2999 | 文件相关错误 |
| 3000-3999 | 用户相关错误 |
| 4000-4999 | 数据库相关错误 |

## 使用示例

### 上传文献文件

```bash
curl -X POST "http://localhost:8086/api/literature/upload" \
  -F "file=@document.pdf" \
  -F "apiKey=your-api-key" \
  -F "customSystemPrompt=请为这篇文献生成详细的阅读指南"
```

### 生成阅读指南（SSE流式响应）

```bash
curl -X POST "http://localhost:8086/api/literature/generate-guide" \
  -F "file=@document.pdf" \
  -F "apiKey=your-api-key" \
  -F "customSystemPrompt=请为这篇文献生成详细的阅读指南"
```

### 获取文献列表

```bash
curl -X GET "http://localhost:8086/api/literature/list?pageNum=1&pageSize=10&keyword=搜索关键词"
```

### 测试AI连接

```bash
curl -X POST "http://localhost:8086/api/literature/test-ai-connection" \
  -H "Content-Type: application/json" \
  -d '{"apiKey":"your-api-key"}'
```

## 开发计划

### ✅ 已完成功能
- ✅ 现代化SpringBoot 3.5架构搭建
- ✅ H2嵌入式数据库设计和初始化
- ✅ 多格式文档解析 (PDF、Word、Markdown、TXT)
- ✅ Kimi AI智能分析集成
- ✅ SSE流式响应支持
- ✅ 完整API接口体系
- ✅ 统一异常处理和响应封装
- ✅ 文件管理和工具类库
- ✅ API文档自动生成

### 🚀 下一步开发计划
- 🔄 前端管理界面开发
- 🔄 用户权限管理集成
- 🔄 高级搜索和推荐系统
- 🔄 批量处理功能
- 🔄 文献版本管理和协作
- 🔄 缓存优化和监控
- 🔄 Docker容器化部署
- 🔄 单元测试完善

## 许可证

Apache 2.0

## 作者

oxtop

## 贡献指南

欢迎提交Issue和Pull Request来帮助改进项目！

## 更新日志

### v2.0.0 (2025-01-29)
- 🎉 企业级架构重构
- 🎉 支持四种文档格式 (PDF、Word、Markdown、TXT)
- 🎉 完整的AI智能分析集成
- 🎉 SSE实时流式响应
- 🎉 优化数据库设计和索引
- 🎉 完善异常处理体系
- 🎉 新增文件工具类库
- 🎉 改进API接口文档

### v1.0.0 (2024-12-19)
- 🎉 项目初始化
- 🎉 基础框架搭建
- 🎉 多格式文档支持
- 🎉 AI智能分析集成