# Activity 活动框架

活动管理系统，负责监听事件、判断条件、调用 Sentry 执行开关。

## 架构概览

```
Activity/
├── ActivityManager.cs              # 核心管理器 - 协调整个活动系统
├── ActivityScopeManager.cs          # DI Scope 管理器 - 每个活动独立的依赖注入容器
├── Condition/                       # 条件检查模块
│   ├── IConditionChecker.cs        # 条件检查器接口
│   ├── ConditionCheckerFactory.cs   # 条件检查器工厂
│   ├── TimeConditionChecker.cs       # 时间条件检查器
│   ├── AccountLevelConditionChecker.cs  # 账号等级条件检查器
│   ├── FishCountConditionChecker.cs    # 捕鱼数量条件检查器
│   └── ABTestConditionChecker.cs    # AB测试条件检查器
├── Data/                            # 数据层
│   ├── IEventData.cs                # 活动数据接口
│   ├── AEventData.cs                # 活动数据基类
│   ├── AEventDataManager.cs         # 活动数据管理器基类
│   ├── IEventDataRepository.cs      # 数据仓库接口
│   └── EventDataRepository.cs       # 数据仓库实现
├── Sentry/                          # 活动哨兵模块
│   ├── IActivitySentry.cs           # 哨兵接口
│   ├── AActivitySentry.cs           # 哨兵基类（AActivitySentry<TM, TD>）
│   ├── ActivitySentryManager.cs     # 哨兵管理器
│   └── ActivitySentryAttribute.cs   # 哨兵特性
├── EventSubscriber/                 # 事件订阅模块
│   ├── IActivityEventSubscriber.cs  # 事件订阅器接口
│   ├── ActivitySubscriberManager.cs # 订阅器管理器
│   └── *.cs                         # 具体订阅器实现
├── HomeEntranceBtn/                 # 主页入口按钮
│   ├── IHomeEntranceBtn.cs          # 按钮接口
│   └── AbstractHomeEntranceBtn.cs   # 按钮基类
├── Event/                           # 事件定义
│   └── GMActivityOpenedEvent.cs     # GM开启活动事件
└── Services/                        # 服务层
    ├── IEventTokenService.cs        # 代币服务接口
    └── EventTokenService.cs         # 代币服务实现
```

## 核心概念

### 1. 条件检查器 (IConditionChecker)

负责判断活动是否应该开启。框架支持多种内置条件检查器：

- **TimeConditionChecker** - 时间条件（活动开放时间段）
- **AccountLevelConditionChecker** - 账号等级条件
- **FishCountConditionChecker** - 捕鱼数量条件
- **ABTestConditionChecker** - AB测试分组条件

每个条件检查器实现 `IConditionChecker` 接口：

```csharp
public interface IConditionChecker
{
    bool CanOpen(FishingEvent fishingEvent);           // 判断是否能开启
    int Priority { get; }                              // 优先级
    List<Type> CareDataChangeWithType { get; }        // 关心的数据类型变化
}
```

### 2. 活动哨兵 (IActivitySentry)

活动哨兵负责执行活动的开启和关闭操作。每个活动类型对应一个 Sentry 实例。

```csharp
[ActivitySentry(eventType: 1, eventSubType: 1)]
public class MyActivitySentry : AActivitySentry<MyEventDataManager, MyEventData>
{
    /// <summary>
    /// 主页入口按钮实例
    /// </summary>
    public IHomeEntranceBtn HomeEntranceBtn { get; set; }

    protected override void OnEventActive(FishingEvent fishingEvent)
    {
        // 1. 获取或创建活动数据（自动从 PlayFab 加载）
        var manager = ResolveManager();
        var data = manager.RefreshData<MyEventData>(fishingEvent);

        // 2. 通知按钮活动已开启（自动预加载资源、显示入口）
        HomeEntranceBtn?.OnOpen(fishingEvent, manager);
    }

    protected override void OnEventClosed(FishingEvent fishingEvent)
    {
        // 数据会自动保存（通过 EventDataRepository）

        // 通知按钮活动关闭
        HomeEntranceBtn?.OnClose(fishingEvent);
    }

    protected override void OnEventChanged(FishingEvent previousEventConfig, FishingEvent newEventConfig)
    {
        // 同一 (Type, SubType) 下切换到新的配置时触发
        // 框架不会对 previousEventConfig 额外调用 OnEventClosed，只会：
        // 1. 更新 CurrentEventConfig
        // 2. 调用 OnEventChanged(previous, new)
        // 3. 调用 OnEventActive(new)
    }
}
```

### 3. 活动数据 (IEventData)

活动运行时数据，包含活动ID、膨胀率、活动状态等：

```csharp
public class MyEventData : AEventData
{
    // 自定义数据字段
}
```

### 4. 数据管理器 (AEventDataManager)

管理活动数据的加载、保存、刷新：

```csharp
public class MyEventDataManager : AEventDataManager<MyEventData>
{
    protected override void OnDataInitialized(MyEventData data, FishingEvent eventConfig)
    {
        // 数据初始化逻辑
    }
}
```

### 5. 主页入口按钮 (AbstractHomeEntranceBtn)

活动在主页的入口按钮框架，提供活动入口的通用功能：

```csharp
public class MyActivityEntranceBtn : AbstractHomeEntranceBtn<MyEventData>
{
    #region Abstract Implementation

    /// <summary>
    /// 关联的 Sentry 类型，用于注册按钮到哨兵
    /// </summary>
    protected override Type AssociatedSentryType => typeof(MyActivitySentry);

    /// <summary>
    /// 按钮点击事件处理
    /// </summary>
    protected override void OnClickBtn()
    {
        // 打开活动面板
    }

    /// <summary>
    /// 获取图标资源名称
    /// </summary>
    protected override string GetIconName() => "icon_my_activity";

    /// <summary>
    /// 获取需要预加载的资源列表
    /// </summary>
    protected override List<string> GetResourceNames() => new() { "Prefab_MyActivity" };

    #endregion
}
```

#### 核心功能

| 功能 | 说明 |
|------|------|
| **泛型类型** | `TData` 活动数据类型 |
| **Sentry 集成** | 自动注册/注销按钮到对应的 ActivitySentry |
| **定时器** | 自动每秒更新活动倒计时显示 |
| **资源预加载** | 活动开启前预加载所需资源 |
| **生命周期** | 继承 EventButtonResource，支持完整的创建/销毁流程 |

#### UI 组件绑定

框架会自动查找并绑定以下子物体：

| 字段 | 默认路径 | 说明 |
|------|---------|------|
| `textTimer` | `text_time` | 倒计时文本 |
| `btn` | 自身 | 按钮组件 |
| `icon` | `icon_task` | 图标图片 |

> ⚠️ **注意**: 确保预制体中包含对应名称的子物体，否则需要手动赋值或重写绑定逻辑

### 6. 事件订阅器 (IActivityEventSubscriber)

订阅游戏内事件，触发活动状态检查：

```csharp
public class MyActivitySubscriber : IActivityEventSubscriber
{
    public void Subscribe(ActivityManager manager)
    {
        // 订阅游戏事件
    }

    public void Unsubscribe()
    {
        // 取消订阅
    }
}
```

## 工作流程

### 初始化流程

```
ActivityManager.Init()
  ├── ConditionCheckerFactory.Initialize()     // 初始化条件检查器工厂
  ├── InitAllManage()                           // 注册 EventDataRepository、扫描 Sentry 和 Subscriber
  ├── InitializeAllSentries()                  // 为每个活动类型创建 Sentry 实例
  ├── SubscribeGlobalEvents()                   // 订阅全局事件
  └── CheckAllActivities()                      // 检查所有活动状态
```

### 活动状态检查流程

```
数据变化 或 定时检查
    │
    ▼
ActivityManager.OnDataChanged<T>(data)
    │
    ├── 根据数据类型找到相关活动
    │
    ├── 遍历活动调用 ShouldActivityOpen()
    │       │
    │       └── 遍历所有条件检查器 (IConditionChecker.CanOpen)
    │
    └── 根据结果调用 Sentry.Open() 或 Sentry.Close()
```

### 活动开关执行流程

```
Sentry.Open(fishingEvent)
    │
    ├── 设置 CurrentEventConfig
    │
    ├── 调用 OnEventChanged() (活动切换时)
    │
    ├── 调用 OnEventActive()
    │       │
    │       └── 通知 HomeEntranceBtn.OnOpen()
    │               │
    │               └── 预加载资源 -> OnLoadEventResource()
    │
    └── 创建/刷新活动数据
```

### 按钮注册流程

```
Awake()
    │
    ├── RegisterBtnInSentry()   // 注册到 Sentry
    │       │
    │       └── 获取 TypeKey 从 AssociatedSentryType
    │       │
    │       └── 设置 sentry.HomeEntranceBtn = this
    │
    ├── 查找并绑定 UI 组件
    │
    ├── 设置按钮点击监听
    │
    └── 检查活动状态 -> OnOpen() 或 等待
```

## 使用示例

### 1. 创建新的活动

1. **定义活动数据类**

```csharp
public class MyEventData : AEventData
{
    public int TokenCount;
    public List<int> RewardsClaimed;
}
```

2. **定义数据管理器**

```csharp
public class MyEventDataManager : AEventDataManager<MyEventData>
{
    protected override void OnDataInitialized(MyEventData data, FishingEvent eventConfig)
    {
        data.InflationRate = GContext.container.Resolve<PlayerData>().InflationRate;
    }
}
```

3. **定义活动哨兵**

```csharp
[ActivitySentry(eventType: 1, eventSubType: 1)]
public class MyActivitySentry : AActivitySentry
{
    /// <summary>
    /// 主页入口按钮实例
    /// </summary>
    public AbstractHomeEntranceBtn HomeEntranceBtn { get; set; }

    protected override void OnEventActive(FishingEvent fishingEvent)
    {
        // 创建活动数据
        var manager = ResolveManager<MyEventDataManager>((EventType, EventSubType));
        var data = manager.RefreshData(fishingEvent);

        // 通知按钮活动已开启
        HomeEntranceBtn?.OnOpen();
    }

    protected override void OnEventClosed(FishingEvent fishingEvent)
    {
        // 保存数据
        HomeEntranceBtn?.OnClose();
    }
}
```

4. **定义主页入口按钮**

```csharp
public class MyActivityEntranceBtn : AbstractHomeEntranceBtn<MyEventData, MyEventDataManager>
{
    protected override Type AssociatedSentryType => typeof(MyActivitySentry);

    protected override void OnClickBtn()
    {
        // 打开活动面板
    }

    protected override string GetIconName() => "icon_my_activity";

    protected override List<string> GetResourceNames() => new() { "Prefab_MyActivity" };
}
```

### 2. 添加新的条件检查器

```csharp
public class MyConditionChecker : IConditionChecker
{
    public int Priority => 10;

    public List<Type> CareDataChangeWithType => new()
    {
        typeof(PlayerLevelData)
    };

    public bool CanOpen(FishingEvent fishingEvent)
    {
        var playerLevel = GContext.container.Resolve<PlayerData>().Level;
        return playerLevel >= fishingEvent.ConditionParam;
    }
}
```

然后在 `ConditionCheckerFactory.Initialize()` 中注册。

### 3. 添加事件订阅器

```csharp
public class MyActivityEventSubscriber : IActivityEventSubscriber
{
    private IDisposable _subscription;

    public void Subscribe(ActivityManager manager)
    {
        // 订阅游戏内事件
        _subscription = MessageBroker.Default.Receive<SomeGameEvent>()
            .Subscribe(_ => manager.OnActivitySingleEvent(...));
    }

    public void Unsubscribe()
    {
        _subscription?.Dispose();
    }
}
```

## 注册机制

### ActivityScopeManager 统一管理

注册逻辑统一放在 `ActivityScopeManager` 中，避免重复代码：

| 方法 | 说明 |
|------|------|
| `IsRegistered<TM>()` | 检查类型是否已注册 |
| `GetOrRegisterInstance<TM>(typeKey)` | 获取或注册实例（自动创建 Scope） |
| `GetRegisteredTypeKey<TM>()` | 获取已注册类型对应的 typeKey |

```csharp
// 在 AActivitySentry 中获取管理器实例
protected TM ResolveManager()
{
    return _scopeManager.GetOrRegisterInstance<TM>((EventType, EventSubType));
}

// 在 ActivityManager 中解析
public TM Resolve<TM>() where TM : AEventDataManager
{
    if (!_scopeManager.IsRegistered<TM>()) return null;
    var typeKey = _scopeManager.GetRegisteredTypeKey<TM>();
    if (typeKey == null) return null;
    if (!_scopeManager.HasActiveScope(typeKey.Value)) return null;
    return _scopeManager.GetOrRegisterInstance<TM>(typeKey.Value);
}
```

### 注册流程

```
ResolveManager() 调用
    │
    ├── GetOrRegisterInstance(typeKey)
    │       │
    │       ├── 获取或创建 Scope (GetActivityScope)
    │       │
    │       ├── 如果未注册：
    │       │       │
    │       │       ├── GContext.container.Register<TM>().PerScope()
    │       │       │
    │       │       └── _activeRegistry.Add(typeof(TM), typeKey)
    │       │
    │       └── 返回 scope.GetInstance((typeof(TM), typeof(TM).Name))
    │
    └── 返回 TM 实例
```

## 配置表

活动配置使用 `FishingEvent` 配置表，包含：

- **Type** - 活动类型
- **SubType** - 活动子类型
- **TimeDefinition** - 时间定义
- **ConditionCheckers** - 条件检查器列表

## 注意事项

1. **Scope 隔离**: 每个 (Type, SubType) 组合对应一个独立的 DI Scope
2. **数据持久化**: 通过 `IEventDataRepository` 进行数据存储
3. **代币管理**: 通过 `IEventTokenService` 统一管理活动代币
4. **条件检查**: 支持多条件组合，全部通过才能开启活动
5. **生命周期**: Sentry 实现了 `IDisposable`，确保资源正确释放
6. **按钮预制体**: 确保 UI 组件路径正确，或手动在 Inspector 中赋值
7. **Sentry 注册**: 子类必须正确实现 `AssociatedSentryType`，否则按钮无法注册
8. **统一注册**: 所有管理器实例通过 `ActivityScopeManager` 统一注册和管理

## 可插拔性评估

### 什么是可插拔？

可插拔 = 无需修改框架核心代码，即可新增或删除活动。

### 当前框架可插拔性

| 组件 | 可插拔? | 机制 |
|------|---------|------|
| **Sentry** | ✅ | `[ActivitySentry]` 属性自动发现 |
| **DataManager** | ✅ | 通过 Sentry 泛型参数自动关联 |
| **HomeEntranceBtn** | ✅ | 继承 AbstractHomeEntranceBtn 即可 |
| **ConditionChecker** | ❌ | 需手动添加到 `ConditionCheckerFactory` |
| **EventSubscriber** | ❌ | 需手动注册到 `ActivitySubscriberManager` |

### 新增活动的影响

以 CapsulePack（扭蛋）为例：

| 需创建的文件 | 框架修改？ |
|-------------|-----------|
| `CapsulePackSentry.cs` | ❌ 通过 `[ActivitySentry]` 自动发现 |
| `CapsulePackManager.cs` | ❌ 通过 Sentry 泛型自动关联 |
| `IceCapsuleEntranceButton.cs` | ❌ 继承基类即可 |
| `CapsulePackPanel.cs` | ❌ 业务代码 |
| Excel 配置表 | ✅ 正常配置 |

**结论**：新增活动**不需要修改框架代码**，只需添加业务文件。

### 删除活动的影响

| 删除内容 | 影响 |
|---------|------|
| Sentry | 删除文件即失效 ✅ |
| DataManager | 删除文件即失效 ✅ |
| HomeEntranceBtn | 移除预制件即可 ✅ |
| 配置表 | 删除 Excel 即可 ✅ |

**结论**：删除活动**影响最小**，框架自动处理。

### 结论

**框架可插拔性较好**：
- 新增/删除 Sentry、DataManager、HomeEntranceBtn **完全可插拔** ✅
- UI Panel 取决于具体实现方式
- ConditionChecker 和 EventSubscriber 仍需手动注册

**无需改动框架即可新增/删除活动**。