# 上传功能实现计划

## 1. 需求分析

### 1.1 现有功能
- 当前 `G3File` 组件的上传功能通过 `onUpload` 回调函数处理
- 上传按钮点击时，会获取所有状态为 `pending` 的文件并调用 `onUpload` 回调
- 没有内置的上传实现，完全依赖外部回调

### 1.2 需求目标
- 实现阿里云内部上传方法
- 保留外部方法，允许用户动态获取阿里云key等信息
- 支持外部自定义上传方法
- 只上传未上传（状态为 `pending`）的文件
- 上传成功后，将上传成功的 fileitem 传给外部调用，上传成功一个就触发一次

## 2. 技术方案

### 2.1 核心功能设计
1. **上传配置**：添加上传相关的配置选项，包括阿里云上传配置和自定义上传方法
2. **上传方法**：实现阿里云内部上传方法和外部自定义上传方法的支持
3. **上传流程**：优化上传流程，只上传未上传的文件，上传成功后触发回调
4. **状态管理**：管理文件的上传状态，包括 `pending`、`uploading`、`uploaded`、`failed` 等

### 2.2 配置选项
- `uploadConfig`：上传配置对象，包含阿里云上传配置和自定义上传方法
- `onUploadSuccess`：上传成功回调，上传成功一个文件就触发一次
- `onUploadError`：上传失败回调
- `onUploadComplete`：所有文件上传完成回调

### 2.3 上传流程
1. 用户点击上传按钮
2. 组件获取所有状态为 `pending` 的文件
3. 检查是否配置了自定义上传方法，如果有则使用自定义方法
4. 如果没有自定义上传方法，则使用阿里云内部上传方法
5. 逐个上传文件，更新文件状态为 `uploading`
6. 上传成功后，更新文件状态为 `uploaded`，并触发 `onUploadSuccess` 回调
7. 上传失败后，更新文件状态为 `failed`，并触发 `onUploadError` 回调
8. 所有文件上传完成后，触发 `onUploadComplete` 回调

## 3. 实现步骤

### 3.1 修改 HTML 结构
- 无需修改 HTML 结构，使用现有的上传按钮

### 3.2 扩展 JavaScript 功能
1. **添加上传配置选项**：在 `defaults` 中添加上传相关的配置选项
2. **实现上传方法**：
   - `internalUpload`：内部上传方法，支持阿里云上传
   - `handleUpload`：处理上传逻辑，支持自定义上传方法
3. **更新上传流程**：修改 `$btnUpload` 的点击事件处理，使用新的上传逻辑
4. **添加回调方法**：实现 `onUploadSuccess`、`onUploadError`、`onUploadComplete` 回调

### 3.3 优化 CSS 样式
- 为上传状态添加相应的样式，如上传中、上传失败等

### 3.4 测试和验证
1. 测试阿里云内部上传功能
2. 测试外部自定义上传方法
3. 测试上传状态管理
4. 测试回调函数触发

## 4. 预期效果

### 4.1 上传功能
- 支持阿里云内部上传
- 支持外部自定义上传方法
- 只上传未上传的文件
- 上传成功后触发回调

### 4.2 状态管理
- 清晰的上传状态管理
- 上传中、上传成功、上传失败等状态的视觉反馈

### 4.3 回调机制
- 上传成功一个文件就触发一次 `onUploadSuccess` 回调
- 上传失败触发 `onUploadError` 回调
- 所有文件上传完成触发 `onUploadComplete` 回调

## 5. 风险评估

### 5.1 潜在风险
- 阿里云上传配置复杂，可能出现配置错误
- 自定义上传方法可能与内部上传逻辑冲突
- 上传过程中可能出现网络错误

### 5.2 风险缓解措施
- 提供详细的配置文档
- 确保自定义上传方法与内部上传逻辑的兼容性
- 添加错误处理和重试机制

## 6. 实现细节

### 6.1 上传配置
```javascript
uploadConfig: {
  aliyun: {
    // 阿里云配置是可选的
    // getUploadToken 是必须的，用于动态获取上传凭证
    getUploadToken: null // 动态获取上传凭证的函数，返回 Promise
  },
  customUpload: null // 自定义上传方法
}
```

### 6.2 回调函数
```javascript
onUploadSuccess: function(file) {
  // 上传成功回调
},
onUploadError: function(file, error) {
  // 上传失败回调
},
onUploadComplete: function(successCount, failCount) {
  // 所有文件上传完成回调
}
```

### 6.3 上传方法
- `internalUpload(file, callback)`：内部上传方法
- `handleUpload(files)`：处理上传逻辑

## 7. 代码结构

### 7.1 主要修改文件
- `custom-file/index.js`：扩展上传功能

### 7.2 新增方法
- `internalUpload`：内部上传方法
- `handleUpload`：处理上传逻辑
- `updateFileStatus`：更新文件状态

### 7.3 修改方法
- `init`：初始化上传配置
- `bindEvents`：更新上传按钮的点击事件处理