lingyue-zhibao/backend

灵越智报 v2.0 后端服务

项目概述

灵越智报是一个智能文档处理平台，通过 OCR 识别、版面理解、要素抽取和 AI 处理，提升文档处理效率。

技术栈

• 框架: Spring Boot 3.2.x, Spring Cloud 2022.0.x
• 服务注册与配置: Nacos 2.3.x
• API 网关: Spring Cloud Gateway
• 数据库: PostgreSQL 15+
• 数据访问: MyBatis Plus 3.5.11
• 连接池: Druid 1.2.23
• 缓存: Redis 7+
• 消息队列: RabbitMQ
• 认证: JWT (jjwt 0.11.5)
• 工具类: Hutool 5.8.35, FastJSON2 2.0.53
• Java版本: 17+

项目结构

backend/
├── pom.xml                          # 父 POM
├── common/                           # 公共模块
│   ├── pom.xml
│   └── src/main/java/com/lingyue/common/
│       ├── config/                  # 公共配置
│       ├── dto/                     # 数据传输对象
│       ├── exception/               # 异常处理
│       ├── response/                # 统一响应
│       └── util/                    # 工具类
├── gateway-service/                  # API 网关服务
├── auth-service/                     # 用户认证服务
├── document-service/                # 文档管理服务
├── parse-service/                    # 解析服务
├── ai-service/                       # AI 处理服务
├── graph-service/                    # 关系网络服务
├── notification-service/             # 通知服务
└── sql/                              # 数据库脚本
    └── init.sql

服务说明

1. gateway-service (端口: 8080)

API 网关服务，负责路由转发、JWT 认证、CORS 配置等。

2. auth-service (端口: 8001)

用户认证服务，提供注册、登录、Token 管理等功能。

3. document-service (端口: 8002)

文档管理服务，负责文档上传、存储、管理等功能。

4. parse-service (端口: 8003)

解析服务，负责 OCR 识别、文本提取、版面分析等功能。

5. ai-service (端口: 8004)

AI 处理服务，负责要素提取、文本处理、Prompt 生成等功能。

6. graph-service (端口: 8005)

关系网络服务，负责关系网络构建、逻辑计算等功能。

7. notification-service (端口: 8006)

通知服务，提供 WebSocket 实时通信功能。

环境要求

• JDK 17+
• Maven 3.6+
• PostgreSQL 15+
• Redis 7+
• RabbitMQ 3.12+
• Nacos 2.3+

快速开始

1. 数据库初始化

# 创建数据库
createdb lingyue_zhibao

# 执行初始化脚本
psql -U postgres -d lingyue_zhibao -f sql/init.sql

2. 启动基础设施

# 启动 Nacos（需要单独安装）
# 启动 Redis
redis-server

# 启动 RabbitMQ（需要单独安装）
rabbitmq-server

3. 配置环境变量

各服务的配置文件位于 {service}/src/main/resources/application.yml，可根据实际情况修改：

• 数据库连接信息
• Redis 连接信息
• RabbitMQ 连接信息
• Nacos 服务地址
• JWT 密钥（生产环境必须修改）

4. 编译项目

cd backend
mvn clean install

5. 启动服务

按以下顺序启动服务：

# 1. 启动认证服务
cd auth-service
mvn spring-boot:run

# 2. 启动其他微服务（可并行启动）
cd document-service && mvn spring-boot:run
cd parse-service && mvn spring-boot:run
cd ai-service && mvn spring-boot:run
cd graph-service && mvn spring-boot:run
cd notification-service && mvn spring-boot:run

# 3. 最后启动网关服务
cd gateway-service
mvn spring-boot:run

API 接口

认证接口

• POST /api/v1/auth/register - 用户注册
• POST /api/v1/auth/login - 用户登录
• POST /api/v1/auth/logout - 用户登出
• POST /api/v1/auth/refresh - 刷新 Token

文档接口

• GET /api/v1/documents - 获取文档列表
• GET /api/v1/documents/{id} - 获取文档详情
• POST /api/v1/documents - 上传文档
• DELETE /api/v1/documents/{id} - 删除文档

解析接口

• POST /api/v1/parse/start - 启动解析
• GET /api/v1/parse/status/{documentId} - 查询解析状态

AI 接口

• POST /api/v1/ai/extract-elements - 提取要素
• POST /api/v1/ai/polish-text - 文本润色
• POST /api/v1/ai/generate-prompt - 生成 Prompt

关系网络接口

• POST /api/v1/graphs - 创建关系网络
• GET /api/v1/graphs/{id} - 获取关系网络
• POST /api/v1/graphs/{id}/calculate - 计算关系网络

WebSocket

• ws://localhost:8080/ws - WebSocket 连接端点

开发说明

统一响应格式

所有接口返回统一的响应格式（AjaxResult）：

{
  "code": 200,
  "msg": "操作成功",
  "data": { ... }
}

响应码说明：

• 200: 操作成功
• 400: 参数列表错误
• 401: 未授权
• 403: 访问受限
• 404: 资源未找到
• 500: 系统内部错误
• 601: 系统警告消息

JWT 认证

• 请求头格式: Authorization: Bearer {token}
• Token 有效期: 7 天
• 刷新 Token 有效期: 30 天

异常处理

使用 ServiceException 抛出业务异常，全局异常处理器会自动转换为统一响应格式。

数据库实体

所有实体类使用 MyBatis Plus 注解，继承 SimpleModel 基类，支持自动创建和更新 create_time、update_time 字段。

实体基类：

• AssignUuidModel: UUID主键模型基类
• CreationModel: 创建信息模型基类（包含创建者、创建时间）
• SimpleModel: 简单模型基类（包含创建和更新信息）

配置说明

开发环境

使用 application-dev.yml 配置文件，包含本地开发环境的配置。

生产环境

使用 application-prod.yml 配置文件，通过环境变量配置敏感信息：

export DB_USERNAME=postgres
export DB_PASSWORD=your_password
export JWT_SECRET=your_jwt_secret
export NACOS_SERVER_ADDR=nacos-server:8848

MyBatis Plus 配置

每个服务都包含 MyBatisPlusConfig 配置类，配置了：

• Mapper扫描路径
• 分页插件（PostgreSQL）
• ID生成策略（ASSIGN_UUID）

Druid 连接池配置

所有服务使用 Druid 连接池，配置了：

• 连接池大小（初始5，最小5，最大20）
• 连接验证
• SQL监控（stat, wall, slf4j）

待实现功能

当前版本为基础框架，以下功能待实现：

1. 文档服务: 文件上传、OSS 集成、文档预览
2. 解析服务: PaddleOCR 集成、文本提取、版面分析
3. AI 服务: DeepSeek API 集成、要素提取、文本处理
4. 关系网络服务: 关系网络计算、逻辑运算
5. 通知服务: WebSocket 消息推送、解析进度通知

注意事项

1. JWT 密钥: 生产环境必须修改默认的 JWT 密钥
2. 数据库密码: 生产环境必须使用强密码
3. CORS 配置: 生产环境应配置具体的允许域名
4. 日志级别: 生产环境建议使用 WARN 级别

参考文档

• 设计文档
• Spring Cloud 文档
• Nacos 文档
• PostgreSQL 文档

许可证

详见 LICENSE 文件。