real-e-party-iOS/QUICK_START_GUIDE.md

# EP 模块 Swift 组件快速使用指南

## 🎯 核心组件

### EPSDKManager - 统一 SDK 管理入口

**功能**: QCloud 等第三方 SDK 的统一管理器

**使用方式**:
```objc
// 在任何 ViewController 中
#import "YuMi-Swift.h"

// 上传图片（自动初始化 QCloud）
[[EPSDKManager shared] uploadImages:imageArray 
    progress:^(NSInteger uploaded, NSInteger total) {
        // 进度回调
        [EPProgressHUD showProgress:uploaded total:total];
    }
    success:^(NSArray<NSDictionary *> *resList) {
        // 上传成功
        // resList: [{resUrl, width, height, format}, ...]
    }
    failure:^(NSString *error) {
        // 上传失败
        NSLog(@"上传失败: %@", error);
    }];
```

### EPProgressHUD - 进度显示组件

**使用方式**:
```objc
// 显示进度
[EPProgressHUD showProgress:3 total:9];  // 上传中 3/9

// 关闭
[EPProgressHUD dismiss];
```

### EPMomentAPISwiftHelper - 动态 API 封装

**使用方式**:
```objc
EPMomentAPISwiftHelper *api = [[EPMomentAPISwiftHelper alloc] init];

// 发布动态
[api publishMomentWithType:@"2"  // "0"=文本, "2"=图片
                   content:@"动态内容"
                   resList:uploadedImages
                completion:^{
    NSLog(@"发布成功");
}
failure:^(NSInteger code, NSString *msg) {
    NSLog(@"发布失败: %@", msg);
}];
```

## 📦 完整发布流程示例

```objc
- (void)publishMomentWithText:(NSString *)text images:(NSArray<UIImage *> *)images {
    EPMomentAPISwiftHelper *api = [[EPMomentAPISwiftHelper alloc] init];
    
    if (images.count > 0) {
        // 有图片：先上传图片，后发布
        [[EPSDKManager shared] uploadImages:images 
            progress:^(NSInteger uploaded, NSInteger total) {
                [EPProgressHUD showProgress:uploaded total:total];
            }
            success:^(NSArray<NSDictionary *> *resList) {
                [EPProgressHUD dismiss];
                
                // 图片上传成功，发布动态
                [api publishMomentWithType:@"2" 
                                   content:text ?: @"" 
                                   resList:resList 
                                completion:^{
                    NSLog(@"发布成功");
                    // 关闭页面或刷新列表
                }
                failure:^(NSInteger code, NSString *msg) {
                    NSLog(@"发布失败: %@", msg);
                }];
            }
            failure:^(NSString *error) {
                [EPProgressHUD dismiss];
                NSLog(@"图片上传失败: %@", error);
            }];
    } else {
        // 纯文本：直接发布
        [api publishMomentWithType:@"0" 
                           content:text 
                           resList:@[]
                        completion:^{
            NSLog(@"发布成功");
        }
        failure:^(NSInteger code, NSString *msg) {
            NSLog(@"发布失败: %@", msg);
        }];
    }
}
```

## 🏗️ 架构说明

### 组件关系

```
EPSDKManager (统一入口)
  ├── uploadImages()         ← 对外接口
  ├── QCloud 初始化管理
  └── 内部持有 EPImageUploader

EPImageUploader (内部类)
  └── 批量上传实现（直接使用 QCloud SDK）

EPProgressHUD (工具类)
  └── 进度显示

EPMomentAPISwiftHelper (API 封装)
  └── 发布动态 API
```

### 调用者只需要知道

- ✅ `EPSDKManager.shared` - SDK 管理
- ✅ `EPProgressHUD` - 进度显示
- ✅ `EPMomentAPISwiftHelper` - API 调用

### 调用者不需要知道

- ❌ EPImageUploader（内部实现）
- ❌ EPQCloudConfig（内部模型）
- ❌ QCloud SDK 的细节
- ❌ Token 的管理
- ❌ 初始化的时机

## 🔧 常见问题

### Q1: 首次上传会比较慢吗？

**A**: 首次上传需要初始化 QCloud（获取 Token），大约增加 0.5-1 秒。后续上传会复用配置，无等待。

### Q2: Token 过期了怎么办？

**A**: 自动处理。`EPSDKManager` 会检测 Token 是否过期，过期时自动重新获取，用户无感知。

### Q3: 并发上传如何控制？

**A**: 内部使用 `DispatchSemaphore(value: 3)` 控制，最多同时上传 3 张图片，避免占用过多网络资源。

### Q4: 如何显示上传进度？

**A**: 使用 `EPProgressHUD`：
```objc
progress:^(NSInteger uploaded, NSInteger total) {
    [EPProgressHUD showProgress:uploaded total:total];
}
```

### Q5: 上传失败如何处理？

**A**: 在 failure 回调中处理：
```objc
failure:^(NSString *error) {
    [EPProgressHUD dismiss];
    // 显示错误 Toast 或 Alert
    NSLog(@"上传失败: %@", error);
}
```

### Q6: 新旧代码会冲突吗？

**A**: 不会。新旧代码完全隔离：
- 新代码（EP 前缀）使用 `EPSDKManager`
- 旧代码继续使用 `UploadFile`
- 两者共享 QCloudCOSXML SDK 底层，互不干扰

## 📝 代码规范

### 导入头文件

```objc
#import "YuMi-Swift.h"  // 必须导入，才能使用 Swift 类
```

### 错误处理

```objc
// ✅ 推荐：提供友好的错误提示
failure:^(NSString *error) {
    [EPProgressHUD dismiss];
    [self showErrorToast:error];  // 显示 Toast
}

// ❌ 不推荐：只打印日志
failure:^(NSString *error) {
    NSLog(@"%@", error);  // 用户看不到
}
```

### 内存管理

```objc
// ✅ 推荐：使用 weak self
[[EPSDKManager shared] uploadImages:images 
    success:^(NSArray *resList) {
        __weak typeof(self) weakSelf = self;
        [weakSelf doSomething];
    }
    ...
];
```

## 🚀 未来扩展

### 计划中的功能

```swift
// 视频上传
EPSDKManager.shared.uploadVideo(video, ...)

// 音频上传
EPSDKManager.shared.uploadAudio(audio, ...)

// IM SDK 初始化
EPSDKManager.shared.initializeIM()

// 推送 SDK 初始化
EPSDKManager.shared.initializePush()
```

### 扩展方式

在 `EPSDKManager.swift` 中添加新方法：

```swift
@objc func uploadVideo(
    _ video: URL,
    progress: @escaping (Double) -> Void,
    success: @escaping ([String: Any]) -> Void,
    failure: @escaping (String) -> Void
) {
    // 实现视频上传逻辑
}
```

## 📚 相关文档

- [完整实施报告](SWIFT_QCLOUD_REWRITE_FINAL.md)
- [SDK 管理器说明](SDK_MANAGER_IMPLEMENTATION.md)
- [检查清单](IMPLEMENTATION_CHECKLIST.md)

---

**文档版本**: 1.0  
**最后更新**: 2025-10-11  
**维护者**: AI Assistant