# 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 风险缓解
- 实现重试机制
- 设置合理的超时时间
- 实现断点续传
- 加强安全性检查
- 完善错误处理和日志记录