# DocuConvert

**Repository Path**: Liyingpu/docu-convert

## Basic Information

- **Project Name**: DocuConvert
- **Description**: word2pdf
pdf2word
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DocuConvert — 文档转换后端服务

基于 Spring Boot 的文件格式转换后端服务，支持 Word/PDF/Excel/PPT 多种格式互转，包含用户认证、异步任务、WebSocket 进度推送等完整功能。

## 功能特性

| 功能 | 说明 |
|------|------|
| Word → PDF | 支持 .doc 和 .docx 格式，无水印 |
| PDF → Word | 输出 .docx 格式，无水印 |
| Excel → PDF | 支持 .xlsx 和 .xls 格式 |
| PPT → PDF | 支持 .pptx 格式 |
| 批量转换 | 多文件上传，结果打包为 ZIP 下载 |
| 异步任务 | 大文件异步转换，WebSocket 实时进度推送 |
| PDF 文本提取 | 提取 PDF 中的名称、金额等字段（发票解析） |
| 用户认证 | JWT 认证，支持 Web 登录和微信小程序登录 |
| 历史记录 | 转换历史自动保存，用户隔离 |
| 文件校验 | 文件大小限制、类型白名单、魔数校验 |
| 转换统计 | 全局/用户维度的转换统计数据 |
| 流式下载 | 大文件流式输出，不会 OOM |
| 自动清理 | 定时清理过期临时文件 |

## 技术栈

- Java 17 + Spring Boot 3.2.5
- Aspose.Words 24.1（Word → PDF）
- Aspose.PDF 22.7.1（PDF → Word）
- Apache POI 5.2.5（Excel/PPT 处理）
- Apache PDFBox 2.0.24（PDF 文本提取）
- Spring Security + JWT（用户认证）
- Spring Data JPA + SQLite（数据持久化）
- WebSocket（实时进度推送）

## 项目结构

```
src/main/java/org/example/word2pdf/
├── Word2pdfApplication.java          # 启动类
├── config/
│   ├── AuthInterceptor.java          # JWT 认证拦截器
│   ├── CorsConfig.java               # CORS 跨域配置
│   ├── RateLimitInterceptor.java     # 限流配置
│   ├── SecurityConfig.java           # Spring Security 配置
│   ├── WebMvcConfig.java             # MVC 配置
│   ├── WebSocketConfig.java          # WebSocket 配置
│   ├── FileStreamingResponse.java    # 流式下载封装
│   ├── Result.java                   # 统一响应格式
│   └── TempFileCleanupTask.java      # 临时文件定时清理
├── controller/
│   ├── AuthController.java           # 认证接口（登录/注册/修改密码）
│   ├── Word2PdfController.java       # Word/PDF 转换接口
│   ├── Office2PdfController.java     # Office 文件转换接口
│   ├── TaskController.java           # 异步任务接口
│   ├── HistoryController.java        # 历史记录接口
│   └── StatisticsController.java     # 转换统计接口
├── service/
│   ├── Word2pdfService.java          # Word→PDF 接口
│   ├── Pdf2WordService.java          # PDF→Word 接口
│   ├── Office2PdfService.java        # Office 转换接口
│   ├── AsyncTaskService.java         # 异步任务接口
│   ├── ConversionHistoryService.java # 历史记录接口
│   ├── StatisticsService.java        # 统计接口
│   ├── FileValidationService.java    # 文件校验接口
│   └── UserService.java              # 用户服务接口
├── impl/
│   ├── Word2pdfServiceImpl.java      # Word→PDF 实现
│   ├── Pdf2WordServiceImpl.java      # PDF→Word 实现
│   ├── Office2PdfServiceImpl.java    # Office 转换实现
│   ├── AsyncTaskServiceImpl.java     # 异步任务实现
│   ├── ConversionHistoryServiceImpl.java # 历史记录实现
│   ├── StatisticsServiceImpl.java    # 统计实现
│   ├── FileValidationServiceImpl.java # 文件校验实现
│   └── UserServiceImpl.java          # 用户服务实现
├── entity/
│   ├── User.java                     # 用户实体
│   ├── ConversionHistory.java        # 转换历史实体
│   └── AsyncTask.java                # 异步任务实体
├── repository/
│   ├── UserRepository.java           # 用户仓库
│   ├── ConversionHistoryRepository.java # 历史记录仓库
│   └── AsyncTaskRepository.java      # 异步任务仓库
├── websocket/
│   └── WebSocketProgressHandler.java # WebSocket 进度推送处理器
├── util/
│   └── JwtUtil.java                  # JWT 工具类
└── exception/
    ├── BusinessException.java        # 业务异常
    └── GlobalExceptionHandler.java   # 全局异常处理
```

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.6+

### 启动

```bash
# 克隆项目
git clone https://gitee.com/Liyingpu/docu-convert.git

# 进入后端目录
cd word2pdf

# 编译运行
mvn spring-boot:run
```

服务默认启动在 `http://localhost:8090`。

### 运行测试

```bash
mvn test
```

测试覆盖：150 个测试用例，包括用户认证、文件转换、异步任务、历史记录等模块。

## API 接口

### 认证接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /auth/login | 用户登录 |
| POST | /auth/register | 用户注册 |
| POST | /auth/change-password | 修改密码 |

### 文件转换接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /word2pdf/word2PdfFileMultipart | 单文件 Word → PDF |
| POST | /word2pdf/word2PdfFilesMultipartBatch | 批量 Word → PDF |
| POST | /word2pdf/pdf2WordFileMultipart | 单文件 PDF → Word |
| POST | /word2pdf/pdf2WordFilesMultipartBatch | 批量 PDF → Word |
| POST | /word2pdf/extract | PDF 文本提取 |
| POST | /office/convert | Office 文件转换（Excel/PPT → PDF） |

### 异步任务接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /task/submit | 提交异步转换任务 |
| GET | /task/status/{taskId} | 获取任务状态 |
| GET | /task/download/{taskId} | 下载转换结果 |
| GET | /task/list | 获取任务列表 |
| POST | /task/retry/{taskId} | 重试失败任务 |

### 历史记录接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /history/list | 获取转换历史 |
| DELETE | /history/{id} | 删除历史记录 |
| DELETE | /history/clear | 清空历史记录 |

### 统计接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /statistics/overview | 全局统计概览 |
| GET | /statistics/user/overview | 用户统计概览 |
| GET | /statistics/daily?days=7 | 每日转换趋势 |
| GET | /statistics/direction | 转换格式分布 |

### curl 示例

```bash
# 用户登录
curl -X POST http://localhost:8090/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'

# Word 转 PDF
curl -X POST http://localhost:8090/word2pdf/word2PdfFileMultipart \
  -F "file=@test.docx" \
  -o output.pdf

# 提交异步任务
curl -X POST http://localhost:8090/task/submit \
  -F "file=@large-file.docx" \
  -F "direction=word2pdf"

# 获取任务状态
curl http://localhost:8090/task/status/{taskId}
```

## 配置说明

配置文件 `src/main/resources/application.yml`：

```yaml
server:
  port: 8090

spring:
  servlet:
    multipart:
      max-file-size: 100MB       # 单文件大小限制
      max-request-size: 500MB    # 批量请求大小限制

word2pdf:
  temp-dir: ${java.io.tmpdir}/word2pdf   # 临时文件目录
  allowed-dir: D:/pdf2word               # 文件夹接口允许访问的目录
  temp-expire-hours: 24                  # 临时文件过期时间（小时）
  cors:
    allowed-origins: "*"                 # CORS 允许的来源
  validation:
    max-file-size: 10MB                  # 文件大小限制
    allowed-types: docx,doc,xlsx,xls,pptx,ppt,pdf  # 允许的文件类型
```

## 前端配套

- **Web 前端**: `../word-web`，基于 Vue 3 + Vite，详见 [前端 README](../word-web/README.md)
- **小程序端**: 微信小程序，详见 [小程序 README](../../weichat/docuConvertWeichat/README.md)

## 部署

### 后端

```bash
mvn clean package -DskipTests
java -jar target/word2pdf-0.0.1-SNAPSHOT.jar
```

### Nginx 配置示例

```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 前端静态资源
    location / {
        root /path/to/word-web/dist;
        try_files $uri $uri/ /index.html;
    }

    # 后端 API 代理
    location /word2pdf/ {
        proxy_pass http://localhost:8090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        client_max_body_size 500M;
    }

    # WebSocket 代理
    location /ws/ {
        proxy_pass http://localhost:8090;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

## 相关仓库

- **小程序端**: https://gitee.com/Liyingpu/docu-convert-weichat.git