# 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转换工具** - 让文档转换更简单高效 🚀