real-e-party-iOS/QUICK_START_GUIDE.md

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

🎯 核心组件

EPSDKManager - 统一 SDK 管理入口

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

使用方式:

// 在任何 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 - 进度显示组件

使用方式:

// 显示进度
[EPProgressHUD showProgress:3 total:9];  // 上传中 3/9

// 关闭
[EPProgressHUD dismiss];

EPMomentAPISwiftHelper - 动态 API 封装

使用方式:

EPMomentAPISwiftHelper *api = [[EPMomentAPISwiftHelper alloc] init];

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

📦 完整发布流程示例

- (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：

progress:^(NSInteger uploaded, NSInteger total) {
    [EPProgressHUD showProgress:uploaded total:total];
}

Q5: 上传失败如何处理？

A: 在 failure 回调中处理：

failure:^(NSString *error) {
    [EPProgressHUD dismiss];
    // 显示错误 Toast 或 Alert
    NSLog(@"上传失败: %@", error);
}

Q6: 新旧代码会冲突吗？

A: 不会。新旧代码完全隔离：

• 新代码（EP 前缀）使用 EPSDKManager
• 旧代码继续使用 UploadFile
• 两者共享 QCloudCOSXML SDK 底层，互不干扰

📝 代码规范

导入头文件

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

错误处理

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

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

内存管理

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

🚀 未来扩展

计划中的功能

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

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

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

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

扩展方式

在 EPSDKManager.swift 中添加新方法：

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

📚 相关文档

• 完整实施报告
• SDK 管理器说明
• 检查清单

---

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