file-starter/docs/word-merge-feature.md

Word文档合并功能说明

功能概述

本功能实现了Word文档的合并处理，支持以下流程：

1. 将上传的Word文档转换为PDF（保持格式一致）
2. 将多个PDF合并为一个PDF
3. 将合并后的PDF转换为Word或PDF输出

技术架构

后端处理流程

• Word转PDF: 使用mammoth库将Word文档转换为HTML，然后使用html-pdf-node将HTML转换为PDF
• PDF合并: 使用pdf-merger-js库合并多个PDF文档
• PDF转Word: 使用libreoffice-convert库进行格式转换（需要系统安装LibreOffice）

前端界面

• 基于React和TypeScript的现代化界面
• 支持拖拽上传和文件选择
• 实时显示处理进度和状态
• 支持PDF和Word两种输出格式选择

安装依赖

项目需要安装以下Node.js依赖：

npm install pdf-lib pdf-merger-js html-pdf-node libreoffice-convert

系统依赖

对于PDF转Word功能，需要安装LibreOffice：

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install libreoffice

CentOS/RHEL:

sudo yum install libreoffice

macOS:

brew install libreoffice

API接口

文档合并接口

• 路径: POST /api/v1/documents/merge
• 认证: 需要Bearer token认证
• 参数:
  • files: Word文档文件数组（multipart/form-data）
  • outputFormat: 输出格式（pdf/docx），默认docx
  • preserveFormatting: 是否保持格式，默认true

响应格式

{
  "success": true,
  "message": "成功合并 3 个文档",
  "fileName": "merged_document_2025-09-10T05-23-42Z.docx",
  "fileSize": 10240,
  "downloadUrl": "data:application/docx;base64,..."
}

使用流程

1. 上传文档: 选择多个Word文档（.doc或.docx格式）
2. 选择输出格式: 选择合并后的文件格式（PDF或Word）
3. 开始合并: 点击合并按钮，系统会自动处理
4. 下载结果: 处理完成后下载合并后的文档

处理流程说明

Word转PDF流程

1. 使用mammoth解析Word文档内容
2. 提取文本、图片和格式信息
3. 生成HTML格式的中间文件
4. 使用html-pdf-node将HTML转换为PDF

PDF合并流程

1. 使用pdf-merger-js加载所有PDF文档
2. 按顺序合并文档页面
3. 保持原有的页面格式和布局

PDF转Word流程

1. 使用libreoffice-convert调用系统LibreOffice
2. 进行格式转换处理
3. 生成Word文档

性能考虑

• 大文件处理建议使用分块上传
• 并发处理时注意内存使用
• 建议设置文件大小限制（默认10MB）
• 处理完成后自动清理临时文件

错误处理

• 文件格式验证失败返回400错误
• 处理过程中错误返回500错误
• 详细的错误日志记录在服务器端

安全考虑

• 文件类型严格验证（只允许.doc/.docx）
• 文件大小限制防止DoS攻击
• 临时文件及时清理
• 输入内容安全过滤

扩展功能

未来可以扩展的功能：

• 支持更多文档格式（如Excel、PowerPoint）
• 批量处理队列管理
• 异步处理支持
• 处理进度实时推送
• 云存储集成（如MinIO、AWS S3）