188 lines
4.8 KiB
Markdown
188 lines
4.8 KiB
Markdown
# PDF上传功能技术规范
|
||
|
||
## 1. 需求分析
|
||
|
||
### 1.1 功能需求
|
||
- 允许用户上传PDF文件到服务器
|
||
- 服务器通过FTP协议将文件存储到指定位置
|
||
- 提供上传状态反馈和错误处理
|
||
- 支持文件验证和安全性检查
|
||
|
||
### 1.2 技术要求
|
||
- 安全性：FTP账号密码不暴露在前端
|
||
- 可靠性：支持大文件上传和断点续传
|
||
- 可扩展性：易于集成到现有系统
|
||
- 兼容性：支持主流浏览器
|
||
|
||
## 2. 技术方案
|
||
|
||
### 2.1 实现方式选择
|
||
|
||
| 方案 | 优点 | 缺点 | 推荐度 |
|
||
|------|------|------|--------|
|
||
| 前端直接FTP上传 | 操作直观，无需修改后端 | 安全性差，浏览器兼容性问题 | ❌ |
|
||
| 后端API上传 | 安全性高，支持服务器端处理 | 需要修改后端代码 | ✅ |
|
||
|
||
**推荐方案**：后端API上传
|
||
- 理由：安全性更高，FTP账号密码保存在服务器端，支持服务器端验证和处理
|
||
- 架构：前端 → 后端API → FTP服务器
|
||
|
||
### 2.2 技术栈
|
||
- 前端：HTML5, JavaScript, jQuery, Bootstrap
|
||
- 后端：ASP.NET Core, C#
|
||
- FTP客户端：FluentFTP（推荐）或System.Net.FtpWebRequest
|
||
|
||
## 3. 架构设计
|
||
|
||
### 3.1 后端架构
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[前端上传请求] --> B[UploadController.PdfUpload]
|
||
B --> C[文件验证]
|
||
C --> D[FTP上传服务]
|
||
D --> E[FTP服务器]
|
||
D --> F[返回上传结果]
|
||
F --> A
|
||
```
|
||
|
||
### 3.2 前端架构
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[用户选择PDF文件] --> B[文件验证]
|
||
B --> C[AJAX上传请求]
|
||
C --> D[UploadController.PdfUpload]
|
||
D --> E[显示上传进度]
|
||
E --> F[显示上传结果]
|
||
```
|
||
|
||
## 4. 详细设计
|
||
|
||
### 4.1 后端API设计
|
||
|
||
#### 4.1.1 接口定义
|
||
|
||
| API路径 | 方法 | 功能 | 参数 | 返回值 |
|
||
|---------|------|------|------|--------|
|
||
| /api/upload/pdf | POST | 上传PDF文件 | files: List<IFormFile><br>type: string<br>folder: string | {code: int, message: string, data: List<string>} |
|
||
|
||
#### 4.1.2 实现细节
|
||
- 扩展现有UploadController，添加PdfUpload方法
|
||
- 集成FTP客户端库，实现FTP上传功能
|
||
- 添加文件验证逻辑（大小、类型、安全性）
|
||
- 实现错误处理和日志记录
|
||
|
||
### 4.2 前端界面设计
|
||
|
||
#### 4.2.1 界面元素
|
||
- 文件选择器：支持多文件选择
|
||
- 上传按钮：触发上传操作
|
||
- 进度显示：实时显示上传进度
|
||
- 结果反馈：显示上传成功/失败信息
|
||
- 历史记录：显示已上传的文件列表
|
||
|
||
#### 4.2.2 实现细节
|
||
- 在batch_query.html中添加PDF上传标签页
|
||
- 使用FormData和XMLHttpRequest实现文件上传
|
||
- 添加文件验证逻辑（大小、类型）
|
||
- 实现上传进度监听
|
||
|
||
## 5. 安全性考虑
|
||
|
||
### 5.1 后端安全
|
||
- FTP账号密码存储在配置文件中，不硬编码
|
||
- 实现文件类型验证，只允许PDF文件
|
||
- 实现文件大小限制
|
||
- 添加文件内容安全检查
|
||
- 记录上传日志，便于审计
|
||
|
||
### 5.2 前端安全
|
||
- 实现客户端文件类型验证
|
||
- 实现客户端文件大小限制
|
||
- 防止XSS攻击
|
||
- 保护用户隐私
|
||
|
||
## 6. 性能优化
|
||
|
||
### 6.1 后端优化
|
||
- 使用异步上传，避免阻塞主线程
|
||
- 实现断点续传功能
|
||
- 优化FTP连接管理
|
||
- 使用缓存机制减少重复上传
|
||
|
||
### 6.2 前端优化
|
||
- 实现分块上传，支持大文件
|
||
- 添加上传进度显示
|
||
- 优化UI响应速度
|
||
- 实现上传队列管理
|
||
|
||
## 7. 测试计划
|
||
|
||
### 7.1 功能测试
|
||
- 单文件上传测试
|
||
- 多文件上传测试
|
||
- 大文件上传测试
|
||
- 错误处理测试
|
||
- 边界情况测试
|
||
|
||
### 7.2 性能测试
|
||
- 上传速度测试
|
||
- 并发上传测试
|
||
- 系统负载测试
|
||
|
||
### 7.3 安全性测试
|
||
- 文件类型验证测试
|
||
- 文件大小限制测试
|
||
- 安全性检查测试
|
||
|
||
## 8. 实施计划
|
||
|
||
### 8.1 后端开发
|
||
1. 添加FTP客户端库依赖
|
||
2. 扩展UploadController，添加PdfUpload方法
|
||
3. 实现FTP上传服务
|
||
4. 添加文件验证逻辑
|
||
5. 编写单元测试
|
||
|
||
### 8.2 前端开发
|
||
1. 在batch_query.html中添加PDF上传标签页
|
||
2. 实现文件选择和上传功能
|
||
3. 添加进度显示和结果反馈
|
||
4. 实现错误处理
|
||
|
||
### 8.3 测试和部署
|
||
1. 功能测试
|
||
2. 性能测试
|
||
3. 安全性测试
|
||
4. 部署到测试环境
|
||
5. 部署到生产环境
|
||
|
||
## 9. 预期效果
|
||
|
||
### 9.1 功能效果
|
||
- 用户可以通过前端界面上传PDF文件
|
||
- 系统将文件通过FTP上传到指定服务器
|
||
- 用户可以看到上传进度和结果
|
||
- 系统提供错误处理和反馈
|
||
|
||
### 9.2 技术效果
|
||
- 安全性高，FTP账号密码不暴露
|
||
- 可靠性强，支持大文件上传
|
||
- 扩展性好，易于集成到现有系统
|
||
- 兼容性好，支持主流浏览器
|
||
|
||
## 10. 风险评估
|
||
|
||
### 10.1 潜在风险
|
||
- FTP服务器连接失败
|
||
- 大文件上传超时
|
||
- 网络不稳定导致上传失败
|
||
- 安全性漏洞
|
||
|
||
### 10.2 风险缓解
|
||
- 实现重试机制
|
||
- 设置合理的超时时间
|
||
- 实现断点续传
|
||
- 加强安全性检查
|
||
- 完善错误处理和日志记录 |