382 lines
8.8 KiB
Markdown
382 lines
8.8 KiB
Markdown
# 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. **克隆项目**
|
||
```bash
|
||
git clone https://github.com/your-username/pdf-tools.git
|
||
cd pdf-tools
|
||
```
|
||
|
||
2. **安装依赖**
|
||
```bash
|
||
npm run install:all
|
||
```
|
||
|
||
3. **环境配置**
|
||
```bash
|
||
# 复制环境变量文件
|
||
cp server/.env.example server/.env
|
||
|
||
# 编辑环境变量
|
||
nano server/.env
|
||
```
|
||
|
||
4. **启动数据库**
|
||
```bash
|
||
# 启动MongoDB
|
||
mongod
|
||
|
||
# 启动Redis (可选)
|
||
redis-server
|
||
```
|
||
|
||
5. **启动应用**
|
||
```bash
|
||
# 开发模式 (同时启动前后端)
|
||
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)
|
||
```bash
|
||
# 服务器设置
|
||
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
|
||
```
|
||
|
||
## 🧪 测试
|
||
|
||
### 运行测试
|
||
```bash
|
||
# 运行所有测试
|
||
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文档
|
||
|
||
### 核心接口
|
||
|
||
#### 文件管理
|
||
```bash
|
||
POST /api/files/upload # 上传文件
|
||
GET /api/files/:id # 获取文件信息
|
||
DELETE /api/files/:id # 删除文件
|
||
```
|
||
|
||
#### 转换服务
|
||
```bash
|
||
POST /api/convert/start # 开始转换
|
||
GET /api/convert/status/:taskId # 查询状态
|
||
GET /api/convert/result/:taskId # 获取结果
|
||
POST /api/convert/batch # 批量转换
|
||
```
|
||
|
||
#### 用户管理
|
||
```bash
|
||
POST /api/users/register # 用户注册
|
||
POST /api/users/login # 用户登录
|
||
GET /api/users/profile # 用户信息
|
||
PUT /api/users/settings # 更新设置
|
||
```
|
||
|
||
#### 系统信息
|
||
```bash
|
||
GET /api/system/health # 健康检查
|
||
GET /api/system/stats # 系统统计
|
||
GET /api/system/formats # 支持格式
|
||
```
|
||
|
||
### 请求示例
|
||
|
||
#### 开始转换
|
||
```bash
|
||
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工作流
|
||
```bash
|
||
# 创建功能分支
|
||
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部署
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t pdf-tools .
|
||
|
||
# 运行容器
|
||
docker run -p 3000:3000 -p 3001:3001 pdf-tools
|
||
```
|
||
|
||
### 生产环境
|
||
```bash
|
||
# 构建前端
|
||
cd client && npm run build
|
||
|
||
# 启动生产服务器
|
||
cd server && npm start
|
||
```
|
||
|
||
### 环境变量 (生产)
|
||
```bash
|
||
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许可证](LICENSE) 开源。
|
||
|
||
## 🆘 支持与帮助
|
||
|
||
### 常见问题
|
||
- **Q: 支持哪些文件格式？**
|
||
A: 目前支持PDF输入，输出格式包括Word、HTML、TXT、PNG、JPG
|
||
|
||
- **Q: 文件大小限制是多少？**
|
||
A: 默认限制50MB，可在配置中调整
|
||
|
||
- **Q: 转换后的文件保存多久？**
|
||
A: 默认24小时后自动删除，保护用户隐私
|
||
|
||
### 获取帮助
|
||
- 📧 邮箱: support@pdf-tools.com
|
||
- 💬 GitHub Issues: [提交问题](https://github.com/your-username/pdf-tools/issues)
|
||
- 📖 文档: [在线文档](https://docs.pdf-tools.com)
|
||
|
||
## 🎉 致谢
|
||
|
||
感谢以下开源项目的支持：
|
||
- React & React生态系统
|
||
- Node.js & Express
|
||
- MongoDB & Redis
|
||
- Ant Design
|
||
- PDF.js & pdf-lib
|
||
- 所有贡献者
|
||
|
||
---
|
||
|
||
**PDF转换工具** - 让文档转换更简单高效 🚀 |