数据同步（TSDataSync）
TSDataSync 提供健康数据的每日聚合和原始数据同步。同步结果按数据类型逐项回调，也通过最终 completion 汇总返回。
前提条件
- 设备已连接并完成鉴权。
- 已完成 SDK 初始化。
- 配置中的
startTime早于endTime，且endTime不得晚于当前时间。 - 调用同步前检查
isSyncing，避免并发同步。
数据模型
TSDataSyncConfig
| 属性 | 类型 | 说明 |
|---|---|---|
options | TSDataSyncOption | 要同步的数据类型，可按位或组合 |
granularity | TSDataGranularity | 原始数据或按天聚合数据 |
startTime | NSTimeInterval | Unix 秒时间戳；为 0 时读取数据库中的上次同步时间 |
endTime | NSTimeInterval | Unix 秒时间戳；为 0 时使用当前时间 |
includeUserInitiated | BOOL | 是否包含主动测量，默认 YES |
初始化方式：init、initWithOptions:granularity:、initWithOptions:granularity:startTime:endTime:；便捷方法：configForRawDataWithOptions:startTime:endTime:、configForDailyDataWithOptions:startTime:endTime:、configWithOptions:granularity:startTime:。
TSHealthData
| 属性 | 类型 | 说明 |
|---|---|---|
option | TSDataSyncOption | 当前结果对应的数据类型 |
healthValues | NSArray<TSHealthValueModel *> * | 按时间升序排列的数据；无数据时为空数组 |
fetchError | NSError * | 该类型获取失败时的错误；成功（包括无数据）时为 nil |
TSHealthData 可使用 initWithOption:healthValues:fetchError: 及对应类方法创建，也可使用 findHealthDataWithOption:fromArray: 从最终结果中查找某一类型。
TSHealthValueType
健康数据项的数值类型：TSHealthValueTypeNormal（0，普通值）、TSHealthValueTypeMax（1，最大值）、TSHealthValueTypeMin（2，最小值）和 TSHealthValueTypeResting（3，静息值，仅用于心率）。
枚举与选项
TSDataGranularity
| 值 | 说明 |
|---|---|
TSDataGranularityRaw (0) | 单次测量的原始数据 |
TSDataGranularityDay (1) | 按天聚合的数据 |
TSDataSyncOption
TSDataSyncOptionNone 为 0；其余选项为按位标志：HeartRate、BloodOxygen、BloodPressure、Stress、Sleep、Temperature、ECG、Sport、DailyActivity、HeartRateVar。TSDataSyncOptionAll 为全部选项的组合。
回调类型
TSDataSyncHealthDataBlock：void (^)(TSHealthData *typeData)。每种通过能力过滤的数据类型完成时在主线程回调一次；单类型失败通过 typeData.fetchError 返回。心率静息值合并在心率结果中，通过数据项的 valueType == TSHealthValueTypeResting 区分。
最终 completion 的签名为：
void (^)(NSArray<TSHealthData *> *_Nullable results, NSError *_Nullable error)
error 只表示阻止同步继续的致命错误；单类型错误在 TSHealthData.fetchError 中返回。
接口方法
从上次同步时间同步每日数据
- (void)syncDailyDataFromLastTime:(nullable TSDataSyncHealthDataBlock)onHealthData
completion:(void (^)(NSArray<TSHealthData *> *_Nullable results,
NSError *_Nullable error))completion;
从上次同步时间同步原始数据
- (void)syncRawDataFromLastTime:(nullable TSDataSyncHealthDataBlock)onHealthData
completion:(void (^)(NSArray<TSHealthData *> *_Nullable results,
NSError *_Nullable error))completion;
使用配置同步
- (void)syncDataWithConfig:(TSDataSyncConfig *)config
onHealthData:(nullable TSDataSyncHealthDataBlock)onHealthData
completion:(void (^)(NSArray<TSHealthData *> *_Nullable results,
NSError *_Nullable error))completion;
同步示例
id<TSDataSyncInterface> syncManager = [TopStepComKit sharedInstance].dataSync;
if ([syncManager isSyncing]) {
TSLog(@"[DataSync] 已有同步任务正在执行");
return;
}
TSDataSyncConfig *config = [TSDataSyncConfig configForDailyDataWithOptions:
(TSDataSyncOptionHeartRate | TSDataSyncOptionBloodOxygen)
startTime:[[NSDate dateWithTimeIntervalSinceNow:-7 * 24 * 60 * 60] timeIntervalSince1970]
endTime:[[NSDate date] timeIntervalSince1970]];
[syncManager syncDataWithConfig:config
onHealthData:^(TSHealthData *typeData) {
if (typeData.fetchError) {
TSLog(@"[DataSync] 类型 %ld 失败: %@", (long)typeData.option,
typeData.fetchError.localizedDescription);
return;
}
TSLog(@"[DataSync] 类型 %ld 完成，共 %lu 条",
(long)typeData.option, (unsigned long)typeData.healthValues.count);
} completion:^(NSArray<TSHealthData *> *results, NSError *error) {
if (error) {
TSLog(@"[DataSync] 致命错误: %@", error.localizedDescription);
return;
}
TSHealthData *heartRate = [TSHealthData findHealthDataWithOption:
TSDataSyncOptionHeartRate fromArray:results];
TSLog(@"[DataSync] 最终结果包含心率: %@", heartRate ? @"是" : @"否");
}];
取消和状态
- (void)cancelSync;
- (BOOL)isSyncing;
cancelSync 立即受理并返回；真正结束通过原同步 completion 返回 eTSErrorSyncCancelled。没有正在同步时调用会被忽略。取消完成前不要启动下一次同步或释放连接。
注意事项
- 所有回调在主线程执行。
healthValues为空表示该类型在时间范围内没有数据，不等于失败。- 原始数据量通常大于每日数据，建议按时间段分批同步。
includeUserInitiated为 NO 时只返回自动/被动监测数据。startTime == 0使用数据库中的上次同步时间；endTime == 0使用调用时的当前时间。- 配置无效、设备繁忙、鉴权或网络致命错误通过最终 completion 的
error返回。