# 任务系统功能整合说明

## 整合概述

本次整合将原本分离的 `MissionItem.ts` 和 `mission-processor.ts` 功能进行了统一，采用面向对象的设计模式，提供了更清晰的 API 和更好的代码复用性。

## 主要变更

### 1. MissionItem 类增强

**新增功能：**
- ✅ 执行上下文支持 (`MissionExecutionContext`)
- ✅ 高亮标题处理 (`highlightedTitle` getter)
- ✅ 任务状态判断增强（使用 `mission-helpers` 中的函数）
- ✅ 异步任务执行 (`executeTask` 方法)
- ✅ 进度文本格式化 (`progressText` getter)
- ✅ 过期状态检查 (`isExpired` getter)
- ✅ 向后兼容性支持 (`toProcessedMissionInfo` 方法)

**新增方法：**
```typescript
// 设置执行上下文
setExecutionContext(context: MissionExecutionContext): void

// 异步执行任务
async executeTask(customHandler?: Function): Promise<any>

// 获取格式化的进度文本
get progressText(): string

// 获取高亮后的标题
get highlightedTitle(): string

// 转换为旧版本格式（向后兼容）
toProcessedMissionInfo(): any
```

### 2. MissionItemFactory 工厂类增强

**新增工厂方法：**
```typescript
// 创建带执行上下文的任务项
static createProcessedMissionItem(
  mission: MissionInfo,
  activityCode: string,
  missionActivityCode: string
): MissionItem

// 批量创建任务项（支持自动添加执行上下文）
static fromMissionInfoList(
  missionInfoList: MissionInfo[], 
  activityCode?: string, 
  missionActivityCode?: string
): MissionItem[]
```

### 3. MissionProcessor 简化

**简化后的职责：**
- 主要负责数据预处理和格式转换
- 返回 `MissionItem` 实例而不是自定义接口
- 保留 `executeByShowMissionType` 方法（标记为 deprecated）

## 使用方法

### 方法1：使用 MissionProcessor 处理完整活动数据

```typescript
import { MissionProcessor } from '../processors/mission-processor';

// 处理接口返回的活动数据
const processedResult = MissionProcessor.processActivityData(activityData);

// 获取任务列表
const missions = processedResult.missionActivity.tabList[0].missions;

// 执行任务
for (const mission of missions) {
  if (mission.isClaimable) {
    const result = await mission.executeTask();
    console.log('任务执行结果：', result);
  }
}
```

### 方法2：直接使用 MissionItemFactory 创建任务项

```typescript
import { MissionItemFactory } from '../classes/MissionItem';

// 创建单个任务项
const missionItem = MissionItemFactory.createProcessedMissionItem(
  missionInfo,
  'ACTIVITY_001',
  'MISSION_ACTIVITY_001'
);

// 检查任务状态
console.log('任务可领取：', missionItem.isClaimable);
console.log('进度：', missionItem.progressText);
console.log('高亮标题：', missionItem.highlightedTitle);

// 执行任务
if (missionItem.isClaimable) {
  await missionItem.executeTask();
}
```

### 方法3：批量处理任务列表

```typescript
// 批量创建任务项
const missionItems = MissionItemFactory.fromMissionInfoList(
  missionInfoList,
  'ACTIVITY_001',
  'MISSION_ACTIVITY_001'
);

// 过滤和统计
const claimableMissions = missionItems.filter(m => m.isClaimable);
const completedMissions = missionItems.filter(m => m.isCompleted);

console.log(`可领取任务：${claimableMissions.length}个`);
console.log(`已完成任务：${completedMissions.length}个`);
```

## 任务执行方式

### 1. 异步执行（推荐）

```typescript
// 使用默认处理器
const result = await missionItem.executeTask();

// 使用自定义处理器
const result = await missionItem.executeTask(async (context, showMissionType) => {
  // 自定义执行逻辑
  switch (showMissionType) {
    case 1:
      return await customSignIn(context);
    case 2:
      return await customShare(context);
    default:
      return null;
  }
});
```

### 2. 同步执行（向后兼容）

```typescript
// 使用默认逻辑
missionItem.doAction();

// 使用自定义逻辑
missionItem.doAction(() => {
  console.log('自定义执行逻辑');
});
```

### 3. 类型化执行

```typescript
const result = missionItem.executeByShowMissionType({
  1: () => handleSignIn(),
  2: () => handleShare(),
  3: () => handleBrowse()
});
```

## 向后兼容性

为了确保现有代码不受影响，提供了以下兼容性支持：

### 1. ProcessedMissionInfo 接口兼容

```typescript
// 旧版本使用方式
const processedMissionInfo = missionItem.toProcessedMissionInfo();
await processedMissionInfo.executeByType();
```

### 2. MissionProcessor.executeByShowMissionType 保留

```typescript
// 仍然可以使用（但已标记为 deprecated）
const result = await MissionProcessor.executeByShowMissionType(context, showMissionType);
```

## 类型定义

### MissionExecutionContext

```typescript
interface MissionExecutionContext {
  missionCode: string;      // 任务代码
  activityCode: string;     // 活动代码
  missionActivityCode: string;  // 任务活动代码
}
```

### ProcessedTab

```typescript
interface ProcessedTab {
  tabName: string;
  tabDesc: string;
  tabType: MissionTabType;
  missions: MissionItem[];  // 现在返回 MissionItem 实例
  totalCount: number;
  claimableCount: number;
  completedCount: number;
  hasClaimableMissions: boolean;
}
```

## 最佳实践

### 1. 统一使用 MissionItem

```typescript
// ✅ 推荐：统一使用 MissionItem
const missionItem = MissionItemFactory.createProcessedMissionItem(info, activityCode, missionActivityCode);

// ❌ 不推荐：混用旧版本接口
const processedInfo = MissionProcessor.processMission(info, activityCode, missionActivityCode);
```

### 2. 优先使用异步执行

```typescript
// ✅ 推荐：使用异步方法
await missionItem.executeTask();

// ⚠️ 谨慎使用：同步方法（仅用于简单操作）
missionItem.doAction();
```

### 3. 利用类型化执行

```typescript
// ✅ 推荐：根据任务类型执行不同逻辑
const result = missionItem.executeByShowMissionType({
  1: () => handleSignIn(),
  2: () => handleShare(),
  // 其他类型...
});
```

## 示例代码

完整的使用示例请参考：`@lofter-mission/core/src/examples/integration-example.ts`

该文件包含了以下示例：
1. 使用 MissionProcessor 处理完整活动数据
2. 直接使用 MissionItemFactory 创建任务项
3. 批量处理任务列表
4. 向后兼容性演示

## 迁移指南

如果你的项目目前使用的是旧版本的 `ProcessedMissionInfo` 接口，建议按以下步骤迁移：

1. **第一步**：将 `ProcessedMissionInfo` 替换为 `MissionItem`
2. **第二步**：使用 `MissionItemFactory` 创建实例
3. **第三步**：将 `executeByType()` 替换为 `executeTask()`
4. **第四步**：移除对旧版本接口的依赖

完成迁移后，你将获得更好的类型安全性和更清晰的 API 设计。