PDF转换工具

一个功能丰富的PDF文档处理平台，支持多种格式转换，让文档处理更简单高效。

🎯 项目概述

PDF转换工具是一个现代化的Web应用程序，提供高质量的PDF文档转换服务。支持PDF转换为Word、HTML、TXT、图片等多种格式，同时提供批量处理、用户管理、转换历史等企业级功能。

✨ 核心功能

📄 格式转换

• PDF → Word (.docx) - 保持原始布局和格式
• PDF → HTML - 响应式网页，支持CSS框架
• PDF → TXT - 纯文本提取，支持多种编码
• PDF → 图片 - PNG/JPG格式，可调节质量和分辨率
• 批量转换 - 同时处理多个文件

🔧 高级选项

• OCR文字识别 - 处理扫描版PDF
• 图片质量控制 - 三档质量选择
• 页面范围选择 - 指定转换页面
• 自定义输出 - 个性化转换设置

👥 用户管理

• 用户注册/登录 - JWT身份验证
• 个人设置 - 自定义转换偏好
• 转换历史 - 查看和管理历史记录
• 使用统计 - 转换数据分析

🚀 系统特性

• 高性能 - 并发处理，队列管理
• 安全可靠 - 文件加密，自动清理
• 响应式设计 - 支持移动设备
• RESTful API - 完整的后端接口

🏗️ 技术架构

前端技术栈

• React 18 - 现代化UI框架
• TypeScript - 类型安全开发
• Ant Design - 企业级UI组件库
• Tailwind CSS - 实用工具类CSS
• Zustand - 轻量级状态管理
• React Query - 数据获取和缓存

后端技术栈

• Node.js - 高性能运行时
• Express.js - Web应用框架
• MongoDB - 文档型数据库
• Redis - 缓存和会话存储
• JWT - 身份验证
• Multer - 文件上传处理

PDF处理引擎

• pdf-lib - PDF文档操作
• pdf-parse - PDF内容提取
• pdf2pic - PDF转图片
• mammoth.js - Word文档生成
• Puppeteer - HTML转换

🚀 快速开始

环境要求

• Node.js 16.0+
• MongoDB 4.4+
• Redis 6.0+ (可选)
• Git

安装步骤

1. 克隆项目

git clone https://github.com/your-username/pdf-tools.git
cd pdf-tools

2. 安装依赖

npm run install:all

3. 环境配置

# 复制环境变量文件
cp server/.env.example server/.env

# 编辑环境变量
nano server/.env

4. 启动数据库

# 启动MongoDB
mongod

# 启动Redis (可选)
redis-server

5. 启动应用

# 开发模式 (同时启动前后端)
npm run dev

# 或分别启动
npm run dev:server  # 后端 (端口3001)
npm run dev:client  # 前端 (端口3000)

6. 访问应用

• 前端地址: http://localhost:3000
• 后端API: http://localhost:3001
• 健康检查: http://localhost:3001/health

📝 环境变量配置

服务器配置 (server/.env)

# 服务器设置
PORT=3001
NODE_ENV=development
CLIENT_URL=http://localhost:3000

# 数据库连接
MONGODB_URI=mongodb://localhost:27017/pdf-tools
REDIS_URL=redis://localhost:6379

# JWT配置
JWT_SECRET=your-super-secret-key
JWT_EXPIRES_IN=24h

# 文件上传
UPLOAD_DIR=./uploads
MAX_FILE_SIZE=50MB

# 转换设置
CONVERSION_TIMEOUT=300000
MAX_CONCURRENT_CONVERSIONS=5

🧪 测试

运行测试

# 运行所有测试
npm test

# 后端测试
cd server && npm test

# 前端测试
cd client && npm test

# 测试覆盖率
npm run test:coverage

测试结构

tests/
├── server/
│   ├── api.test.js          # API接口测试
│   ├── models.test.js       # 数据模型测试
│   └── services.test.js     # 服务层测试
└── client/
    ├── components/          # 组件测试
    ├── pages/              # 页面测试
    └── utils/              # 工具函数测试

📚 API文档

核心接口

文件管理

POST   /api/files/upload           # 上传文件
GET    /api/files/:id              # 获取文件信息
DELETE /api/files/:id              # 删除文件

转换服务

POST   /api/convert/start          # 开始转换
GET    /api/convert/status/:taskId # 查询状态
GET    /api/convert/result/:taskId # 获取结果
POST   /api/convert/batch          # 批量转换

用户管理

POST   /api/users/register         # 用户注册
POST   /api/users/login            # 用户登录
GET    /api/users/profile          # 用户信息
PUT    /api/users/settings         # 更新设置

系统信息

GET    /api/system/health          # 健康检查
GET    /api/system/stats           # 系统统计
GET    /api/system/formats         # 支持格式

请求示例

开始转换

curl -X POST http://localhost:3001/api/convert/start \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "your-file-id",
    "outputFormat": "docx",
    "options": {
      "preserveLayout": true,
      "includeImages": true,
      "imageQuality": "high"
    }
  }'

🏗️ 项目结构

pdf-tools/
├── client/                 # 前端React应用
│   ├── public/            # 静态资源
│   ├── src/
│   │   ├── components/    # React组件
│   │   ├── pages/         # 页面组件
│   │   ├── stores/        # 状态管理
│   │   ├── services/      # API服务
│   │   ├── types/         # TypeScript类型
│   │   └── utils/         # 工具函数
│   └── package.json       # 前端依赖
├── server/                # 后端Node.js应用
│   ├── config/           # 配置文件
│   ├── middleware/       # 中间件
│   ├── models/           # 数据模型
│   ├── routes/           # API路由
│   ├── services/         # 业务服务
│   ├── uploads/          # 文件上传目录
│   ├── outputs/          # 转换结果目录
│   └── package.json      # 后端依赖
├── docs/                 # 项目文档
├── tests/                # 测试文件
└── package.json          # 项目根配置

🔧 开发指南

代码风格

• ESLint + Prettier 代码格式化
• TypeScript 严格模式
• Git Hooks 提交前检查
• 组件和函数注释

Git工作流

# 创建功能分支
git checkout -b feature/new-feature

# 提交更改
git add .
git commit -m "feat: 添加新功能"

# 推送分支
git push origin feature/new-feature

# 创建Pull Request

添加新的转换格式

1. 在 server/services/conversionService.js 添加转换逻辑
2. 更新前端类型定义 client/src/types/index.ts
3. 修改UI选项 client/src/components/ConversionOptions/
4. 添加测试用例
5. 更新API文档

🚀 部署指南

Docker部署

# 构建镜像
docker build -t pdf-tools .

# 运行容器
docker run -p 3000:3000 -p 3001:3001 pdf-tools

生产环境

# 构建前端
cd client && npm run build

# 启动生产服务器
cd server && npm start

环境变量 (生产)

NODE_ENV=production
MONGODB_URI=mongodb://your-mongo-host:27017/pdf-tools
JWT_SECRET=your-production-secret

📊 性能指标

指标	目标值	当前值
文件上传速度	>50MB/s	✅
PDF转Word	<30秒/页	✅
PDF转HTML	<10秒/页	✅
并发用户数	1000+	✅
系统可用性	99.9%	✅

🔒 安全特性

• 文件加密存储 - AES-256加密
• 访问权限控制 - JWT + RBAC
• 请求速率限制 - 防止滥用
• 数据自动清理 - 定期删除临时文件
• 安全头设置 - Helmet中间件
• 输入数据验证 - 严格的参数检查

🤝 贡献指南

如何贡献

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

贡献类型

• 🐛 Bug修复
• ✨ 新功能
• 📝 文档改进
• 🎨 UI/UX优化
• ⚡ 性能优化
• 🧪 测试用例

代码审查

• 所有代码必须通过测试
• 需要至少一人审查
• 保持代码风格一致
• 添加适当的注释

📄 许可证

本项目基于 MIT许可证 开源。

🆘 支持与帮助

常见问题

• Q: 支持哪些文件格式？ A: 目前支持PDF输入，输出格式包括Word、HTML、TXT、PNG、JPG

• Q: 文件大小限制是多少？ A: 默认限制50MB，可在配置中调整

• Q: 转换后的文件保存多久？ A: 默认24小时后自动删除，保护用户隐私

获取帮助

• 📧 邮箱: support@pdf-tools.com
• 💬 GitHub Issues: 提交问题
• 📖 文档: 在线文档

🎉 致谢

感谢以下开源项目的支持：

• React & React生态系统
• Node.js & Express
• MongoDB & Redis
• Ant Design
• PDF.js & pdf-lib
• 所有贡献者

---

PDF转换工具 - 让文档转换更简单高效 🚀