# DocFlow

**Repository Path**: runoob666/doc-flow

## Basic Information

- **Project Name**: DocFlow
- **Description**: DocFlow是一个基于Spring Boot的通用文档处理服务，提供Word模板填充和Word转PDF的功能。
通过简单的API接口，可以实现动态填充任意Word模板并生成PDF文档。
支持完全自定义的模板参数，适用于各种文档生成场景。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-11-12
- **Last Updated**: 2025-11-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DocFlow - 通用文档处理服务

## 项目简介

DocFlow是一个基于Spring Boot的通用文档处理服务，提供Word模板填充和Word转PDF的功能。通过简单的API接口，可以实现动态填充任意Word模板并生成PDF文档。支持完全自定义的模板参数，适用于各种文档生成场景。

## 功能特点

- Word模板填充：支持文本和图片的动态填充
- Word转PDF：支持将填充后的Word文档转换为PDF
- 文件上传：支持上传自定义模板和图片
- 安全性：防止路径遍历和命令注入攻击
- 并发处理：使用线程池处理文档转换任务

## 技术栈

- Spring Boot 2.6.3
- Java 8
- POI-TL (基于Apache POI的Word模板引擎) - 一款强大的Word模板引擎，支持文本、图片、表格等多种元素的动态填充，官网：[https://deepoove.com/poi-tl/](https://deepoove.com/poi-tl/)
- LibreOffice (用于Word转PDF) - 开源办公软件套件，提供文档转换功能，官网：[https://www.libreoffice.org/](https://www.libreoffice.org/)
- Lombok

## 项目结构

```
src/main/java/com/docflow/
├── DocFlowApplication.java        # 应用程序入口
├── common/                        # 通用组件
│   ├── CommonAbnormal.java        # 全局异常处理器
│   ├── CustomException.java       # 自定义异常
│   └── R.java                     # 统一返回对象
├── config/                        # 配置类
│   ├── ThreadPoolConfig.java      # 线程池配置
│   └── WebMvcConfig.java          # Web MVC配置
├── controller/                    # 控制器
│   ├── DocumentController.java    # 文档处理控制器
│   └── FileController.java        # 文件上传控制器
├── model/                         # 数据模型
│   └── dto/
│       └── TemplateInformationDTO.java # 模板信息DTO
├── service/                       # 服务层
│   ├── DocumentService.java       # 文档服务接口
│   └── impl/
│       └── DocumentServiceImpl.java # 文档服务实现
└── util/                          # 工具类
    └── DocumentUtil.java          # 文档处理工具类
```

## 快速开始

### 环境要求

- JDK 8+
- Maven 3.6+
- LibreOffice (用于Word转PDF)

### 构建与运行

1. 克隆项目

```bash
git clone https://github.com/yourusername/doc-flow.git
cd doc-flow
```

2. 编译打包

```bash
mvn clean package
```

3. 运行应用

```bash
java -jar target/doc-flow-0.0.1-SNAPSHOT.jar
```

### 配置说明

在 `application.properties`中可以配置以下参数：

```properties
# 服务端口
server.port=58080

# 文件上传大小限制
spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=10MB

# 默认模板路径
defaultTemplatePath=templates/defaultTemplate.docx
# 模板目录
templatesDir=templates/

# 文件存储路径
file.upload-dir=uploads/
file.export-dir=exports/
```

## API接口说明

### 1. 生成文档

**请求URL：** `/api/document/generate-document`

**请求方式：** POST

**请求参数：**

```json
{
  "documentId" : "DOC-20230520-001",
  "documentName" : "通用文档",
  "templateParams" : {
    "year": 2025,
    "month": 9,
    "day": 12,
    "deadlineYear": 2025,
    "deadlineMonth": 9,
    "deadlineDay": 11,
    "bankAccount" : "69999999999999999",
    "address" : "河南省科技市科技区科技园",
    "accountName" : "李四",
    "partyASeal" : "",
    "idCard" : "41072720020701661x",
    "contactPhone" : "18624714655",
    "alipayAccount" : "18624714655",
    "account" : "18624714655",
    "partyBName" : "李四",
    "openingBank" : "中国银行支行"
  },
  "imageParams" : {
    "partyBSignature" : {
      "path" : "uploads/images/partyBSignature.png",
      "width" : 120,
      "height" : 80
    },
    "partyASeal" : {
      "path" : "uploads/images/logo.png",
      "width" : 120,
      "height" : 110
    }
  },
  "fileType" : 2,
    "templatePath" : "uploads/templates/defaultTemplate.docx",
    "templateCode" : "default"
}
```

**参数说明：**

- `documentId`：文档标识符，必填
- `documentName`：文档名称，必填
- `templateParams`：模板参数映射，键为模板中的占位符名称，值为要填充的内容
- `imageParams`：图片参数映射，键为模板中的占位符名称，值为图片路径
- `fileType`：文件类型，1-Word，2-PDF
- `templatePath`：可选，自定义模板路径，不提供则使用默认模板
- `templateCode`：可选，模板代码，用于指定使用哪个模板

**返回示例：**

```json
{
  "success": true,
  "code": 0,
  "message": "文档生成成功",
  "data": "http://localhost:58080/exports/doc_20230520120000_12345678.pdf"
}
```

**说明：** 返回的 `data`字段是生成文件的完整URL地址，可以直接通过浏览器或任何HTTP客户端访问。

### 2. 上传模板文件

**请求URL：** `/api/file/upload-template`

**请求方式：** POST

**请求参数：** Form-data格式，key为 `file`，value为文件

**返回示例：**

```json
{
  "success": true,
  "code": 0,
  "message": "文件上传成功",
  "data": {
    "fileName": "20230520120000_12345678.docx",
    "fileUrl": "http://localhost:58080/templates/20230520120000_12345678.docx",
    "filePath": "/templates/20230520120000_12345678.docx",
    "originalFileName": "custom_template.docx"
  }
}
```

### 3. 上传图片文件

**请求URL：** `/api/file/upload-image`

**请求方式：** POST

**请求参数：** Form-data格式，key为 `file`，value为文件

**返回示例：**

```json
{
  "success": true,
  "code": 0,
  "message": "文件上传成功",
  "data": {
    "fileName": "20230520120000_12345678.png",
    "fileUrl": "http://localhost:58080/images/20230520120000_12345678.png",
    "filePath": "/images/20230520120000_12345678.png",
    "originalFileName": "seal.png"
  }
}
```

## 注意事项

1. 确保系统已安装LibreOffice，并且可以通过命令行访问
2. 默认模板文件需放置在 `templates/defaultTemplate.docx`
3. 可以在 `templates/`目录下放置多个模板文件，通过templateCode参数指定使用
4. 上传的模板文件将保存在 `templates/`目录下，上传的图片文件将保存在 `images/`目录下
5. 生成的文档将保存在 `exports/`目录下
6. API返回的文件路径均为可直接访问的完整URL

## 许可证

MIT License