digital-pilates/docs/background-tasks-implementation.md

# 后台任务系统实现文档

## 概述

本项目已成功集成iOS后台任务支持，使用Expo官方的 `expo-task-manager` 和 `expo-background-task` 库。该系统提供了完整的后台任务管理功能，支持任务注册、执行、状态监控等。

## 技术栈

- **expo-task-manager**: Expo官方后台任务管理库
- **expo-background-task**: Expo官方后台任务库
- **React Native**: 跨平台移动应用框架
- **TypeScript**: 类型安全的JavaScript超集

## 文件结构

```
services/
├── backgroundTaskManager.ts    # 后台任务管理器核心逻辑
├── backgroundTasks.ts          # 示例任务定义
hooks/
├── useBackgroundTasks.ts       # 后台任务自定义Hook
components/
├── BackgroundTaskTest.tsx      # 后台任务测试组件
```

## 核心功能

### 1. 后台任务管理器 (services/backgroundTaskManager.ts)

#### 主要特性
- **单例模式**: 确保全局只有一个任务管理器实例
- **任务注册**: 支持注册自定义后台任务
- **状态管理**: 完整的任务状态跟踪和持久化
- **错误处理**: 完善的错误处理和日志记录
- **后台获取**: 自动注册后台获取任务

#### 核心方法

```typescript
// 初始化后台任务管理器
await backgroundTaskManager.initialize();

// 注册自定义任务
await backgroundTaskManager.registerTask({
  id: 'my-task',
  name: '我的任务',
  handler: async (data) => {
    // 您的任务逻辑
    console.log('执行任务:', data);
  },
  options: {
    minimumInterval: 300, // 5分钟最小间隔
    stopOnTerminate: false,
    startOnBoot: true,
  }
});

// 手动执行任务
await backgroundTaskManager.executeTask('my-task', { customData: 'value' });

// 执行所有任务
const results = await backgroundTaskManager.executeAllTasks();

// 获取任务状态
const status = backgroundTaskManager.getTaskStatus('my-task');
```

### 2. 自定义Hook (hooks/useBackgroundTasks.ts)

#### 主要特性
- **状态管理**: 管理任务状态和初始化状态
- **自动初始化**: 组件挂载时自动初始化任务管理器
- **便捷接口**: 提供简化的任务操作方法
- **实时更新**: 任务状态实时更新

#### 使用示例

```typescript
const {
  isInitialized,
  taskStatuses,
  registeredTasks,
  registerTask,
  executeTask,
  executeAllTasks,
} = useBackgroundTasks();

// 注册任务
await registerTask({
  id: 'data-sync',
  name: '数据同步',
  handler: async () => {
    // 数据同步逻辑
  }
});

// 执行任务
await executeTask('data-sync');
```

### 3. 示例任务 (services/backgroundTasks.ts)

#### 预定义任务类型
- **数据同步任务**: 同步用户数据、运动记录等
- **健康数据更新任务**: 更新步数、心率等健康数据
- **通知检查任务**: 检查是否需要发送通知
- **缓存清理任务**: 清理过期缓存文件
- **用户行为分析任务**: 分析用户使用模式

#### 创建自定义任务

```typescript
import { createCustomTask } from '@/services/backgroundTasks';

const myTask = createCustomTask(
  'my-custom-task',
  '我的自定义任务',
  async (data) => {
    // 您的任务逻辑
    console.log('执行自定义任务:', data);
  },
  {
    minimumInterval: 120, // 2分钟
    stopOnTerminate: false,
    startOnBoot: true,
  }
);
```

## 使用指南

### 1. 基本使用

```typescript
import { useBackgroundTasks } from '@/hooks/useBackgroundTasks';
import { createCustomTask } from '@/services/backgroundTasks';

const MyComponent = () => {
  const { registerTask, executeTask } = useBackgroundTasks();

  const handleCreateTask = async () => {
    const task = createCustomTask(
      'my-task',
      '我的任务',
      async (data) => {
        // 实现您的后台任务逻辑
        console.log('后台任务执行中...');
        
        // 例如：数据同步
        await syncUserData();
        
        // 例如：健康数据更新
        await updateHealthData();
        
        // 例如：发送通知
        await checkAndSendNotifications();
      }
    );

    await registerTask(task);
  };

  const handleExecuteTask = async () => {
    await executeTask('my-task', { customData: 'value' });
  };

  return (
    <View>
      <Button title="创建任务" onPress={handleCreateTask} />
      <Button title="执行任务" onPress={handleExecuteTask} />
    </View>
  );
};
```

### 2. 任务状态监控

```typescript
const { taskStatuses, getTaskStatus } = useBackgroundTasks();

// 获取特定任务状态
const taskStatus = getTaskStatus('my-task');
console.log('任务状态:', {
  isRegistered: taskStatus?.isRegistered,
  executionCount: taskStatus?.executionCount,
  lastExecution: taskStatus?.lastExecution,
  lastError: taskStatus?.lastError,
});
```

### 3. 批量操作

```typescript
const { executeAllTasks, cleanupTaskStatuses } = useBackgroundTasks();

// 执行所有任务
const results = await executeAllTasks();
console.log('执行结果:', results);

// 清理过期任务状态
await cleanupTaskStatuses();
```

## 配置说明

### iOS配置

在 `app.json` 中已配置后台模式：

```json
{
  "expo": {
    "ios": {
      "infoPlist": {
        "UIBackgroundModes": ["remote-notification"]
      }
    }
  }
}
```

### 后台获取配置

系统自动配置后台获取任务，支持：
- 最小间隔时间设置
- 应用终止时继续运行
- 设备重启时自动启动

## 最佳实践

### 1. 任务设计原则
- **轻量级**: 后台任务应该快速执行，避免长时间运行
- **幂等性**: 任务应该可以重复执行而不产生副作用
- **错误处理**: 完善的错误处理和重试机制
- **资源管理**: 合理管理内存和网络资源

### 2. 性能优化
- **最小间隔**: 根据任务重要性设置合适的最小间隔
- **批量处理**: 将多个小任务合并为一个大任务
- **缓存策略**: 合理使用缓存减少重复计算

### 3. 用户体验
- **静默执行**: 后台任务应该静默执行，不打扰用户
- **状态反馈**: 通过UI显示任务执行状态
- **错误提示**: 在任务失败时提供友好的错误提示

## 测试

使用 `BackgroundTaskTest` 组件进行功能测试：

```typescript
import { BackgroundTaskTest } from '@/components/BackgroundTaskTest';

// 在您的页面中使用
<BackgroundTaskTest />
```

该组件提供：
- 任务注册和取消注册测试
- 任务执行测试
- 状态监控测试
- 后台获取状态测试

## 注意事项

1. **iOS限制**: iOS对后台任务有严格限制，系统会根据电池状态和用户使用模式调整执行频率
2. **权限要求**: 某些后台任务可能需要特殊权限
3. **调试模式**: 在开发模式下，后台任务行为可能与生产环境不同
4. **网络状态**: 后台任务执行时需要考虑网络状态变化

## 故障排除

### 常见问题

1. **任务不执行**: 检查iOS后台模式配置和任务注册状态
2. **执行频率低**: 系统会根据电池状态自动调整，这是正常行为
3. **任务被终止**: 检查任务执行时间，避免长时间运行

### 调试技巧

1. 使用 `console.log` 记录任务执行状态
2. 检查任务状态和错误信息
3. 使用Xcode查看后台任务日志
4. 测试不同的最小间隔设置