# 灵越智报 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/                              # 数据库重建脚本（实际初始化脚本在项目根 database/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. 数据库初始化

```bash
# 创建数据库
createdb lingyue_zhibao

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

### 2. 启动基础设施

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

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

### 3. 配置环境变量

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

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

### 4. 编译项目

```bash
cd backend
mvn clean install
```

### 5. 启动服务

按以下顺序启动服务：

```bash
# 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）：

```json
{
  "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` 配置文件，通过环境变量配置敏感信息：

```bash
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 级别

## 参考文档

- [设计文档](../DESIGN_DOCUMENT.md)
- [Spring Cloud 文档](https://spring.io/projects/spring-cloud)
- [Nacos 文档](https://nacos.io/docs/latest/what-is-nacos/)
- [PostgreSQL 文档](https://www.postgresql.org/docs/)

## 许可证

详见 [LICENSE](../LICENSE) 文件。