# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

Combo SDK for Unity — 世游多平台游戏 SDK 的 Unity 封装层。以 Unity Package（`com.seayoo.sdk`）形式集成到宿主项目 `combo-demo-unity` 中。

- Unity 版本要求：`2019.4` 起
- 包名：`com.seayoo.sdk`
- 当前版本存储在四个位置（修改版本号时必须同步更新）：
  - `package.json` → `"version"`
  - `Combo/Runtime/Version.cs` → `SDKVersion`
  - `Combo/Plugins/Windows/ComboSDK/Runtime/Version.cs` → `SDKVersion`
  - `Combo/Plugins/Windows/SeayooAccount/Runtime/Constants.cs` → `SDKVersion`

## 构建与 CI

本项目不能独立构建，必须作为 Unity Package 嵌入到 `combo-demo-unity` 宿主项目中，通过 Unity Editor 进行构建。Jenkins pipeline（`Jenkinsfile`）负责将本包打成 zip 发布产物。

## 架构

### 分层结构

```
Combo/Runtime/          — 跨平台公共 API 层（ComboSDK.cs 是唯一对外入口）
  ├── ComboSDK.cs       — 公共静态 API，所有方法委托给 Native
  ├── Initializer.cs    — RuntimeInitializeOnLoadMethod 自动初始化
  ├── Native/           — 平台桥接层，每个平台一个文件
  │   ├── NativeAndroid.cs
  │   ├── NativeIOS.cs
  │   ├── NativeWindows.cs
  │   ├── NativeOpenHarmony.cs
  │   └── NativeWebGL.cs
  ├── Core/             — Configuration、Sentry、ThinkingData 等基础设施
  └── Model/            — 公共数据模型（Options、Results、Enums、Error）

Combo/Editor/           — Unity Editor 脚本
  ├── ComboSDKWizard.cs           — ComboSDK/Wizard 菜单，配置 GameId/PublishableKey/Endpoint
  ├── ComboSDKWindowsPostBuild.cs — Windows 构建后处理（插件裁剪）
  ├── ComboSDKAndroidPostBuild.cs — Android Gradle 后处理
  ├── ComboSDKIOSPostBuild.cs     — iOS Xcode 后处理
  └── ComboSDKOpenHarmonyPostBuild.cs

Combo/Plugins/          — 各平台原生实现
  ├── Android/          — Java 桥接文件
  ├── iOS/              — ObjC 桥接文件
  ├── OpenHarmony/      — ETS 桥接文件
  ├── WebGL/            — jslib 桥接文件
  └── Windows/          — Windows 平台完整 C# 实现（见下文详述）

Sentry/                 — Sentry SDK 集成
ThinkingData/           — 数数科技 SDK 集成
LitJson/                — JSON 序列化库
```

### 平台桥接模式

- **Android/iOS/OpenHarmony/WebGL**：Unity C# 层只做桥接，实际逻辑在各平台原生 SDK 中。`Native*.cs` 通过 `AndroidJavaObject`（Android）、`DllImport`（iOS）等方式调用原生代码。
- **Windows**：完整的 C# 实现在 `Combo/Plugins/Windows/` 中，包含账号、支付、UI 等全部逻辑，不依赖外部原生 SDK。

### Windows 平台内部架构

Windows SDK 使用 `_Combo` 命名空间（内部），通过 `Seayoo.ComboSDK.Windows` 命名空间对外暴露。

核心类：
- `_Combo.Combo`（Singleton）— 初始化、Login/Logout/Purchase 等核心流程
- `_Combo.Configuration` — 从 `ComboSDK.json` 读取 distro/domains/parameters
- `_Combo.IdPManager` — 身份提供者管理，根据 domains 动态加载 IdP 模块
- `_Combo.StoreManager` — 支付渠道管理，根据 domains 动态加载 Store 模块
- `_Combo.Reflector` — 反射加载模块，维护 Module → DLL 程序集映射

### Windows 平台 Distro 区分机制

Windows 平台通过 `ComboSDK.json` 配置文件（位于 `Assets/Resources/ComboSDK.json`）区分不同发行渠道：

```json
{
  "distro": "windows",
  "domains": ["seayoo_account", "seayoo_store", "taptap", "lenovo_pc"],
  "parameters": { ... }
}
```

**三层机制协同工作：**

1. **配置驱动**：`distro` 字段标识发行渠道，通过 HTTP Header `x-game-distro` 传递给后端；`domains` 字段声明需要启用的功能模块列表。

2. **运行时反射加载**：`Reflector` 根据 `domains` 中声明的模块名，通过反射从对应 DLL 程序集加载实现类：

   | domain 字符串 | Module 枚举 | DLL 程序集 | 实现类 |
   |---|---|---|---|
   | `seayoo_account` | SeayooAccount | `ComboSDK-SeayooAccount` | `Seayoo.ComboSDK.Windows.Account.SeayooAccount` |
   | `seayoo_store` | SeayooStore | `ComboSDK_SeayooStore` | `Seayoo.ComboSDK.Windows.Store.SeayooStore` |
   | `taptap` | TapTap | `ComboSDK_TapTap` | `Seayoo.ComboSDK.Windows.TapTap.TapTap` |
   | `lenovo_pc` | Lenovo | `ComboSDK_Lenovo` | `Seayoo.ComboSDK.Windows.Lenovo.Lenovo` |

3. **构建后插件裁剪**：`ComboSDKWindowsPostBuild.cs` 在构建前后处理 `Combo/Plugins/Windows/Plugins/` 下的第三方插件目录。不在 `domains` 中的插件目录会被加上 `~` 后缀（Unity 会忽略带 `~` 后缀的目录），构建完成后再移除 `~` 后缀恢复原状。目录映射关系在 `Utils.thirdNameDic` 中维护：
   - `TapSDK` → `taptap`
   - `Lenovo` → `lenovo_pc`

**切换 Distro 只需更换 `ComboSDK.json` 配置文件，无需修改代码。** 也可通过 ComboSDK Wizard 的 "Custom Path for ComboSDK.json" 指定自定义配置路径。

### Assembly Definition 结构

项目通过 `.asmdef` 文件管理程序集依赖：
- `ComboSDK` — 主程序集（`Combo/Runtime/`），引用 Windows SDK、SeayooAccount、ThinkingData、Sentry、Lenovo、Vuplex.WebView、LitJson
- `ComboSDK-Windows` — Windows SDK 核心（`Combo/Plugins/Windows/ComboSDK/Runtime/`）
- `ComboSDK-SeayooAccount` — 世游账号模块
- `ComboSDK_SeayooStore` — 世游支付模块
- `ComboSDK_TapTap` — TapTap 模块
- `ComboSDK_Lenovo` — 联想 PC 模块
- `ComboSDK_Editor` — Editor 脚本

### 初始化流程

`Initializer.cs` 使用 `[RuntimeInitializeOnLoadMethod]` 在两个阶段自动执行：
1. `AfterAssembliesLoaded` — 初始化 Sentry
2. `BeforeSceneLoad` — 初始化 ThinkingData，从 `Configuration` ScriptableObject 读取 GameId/PublishableKey/Endpoint 调用 `Native.Setup()`

### 配置系统

两套独立的 Configuration：
- `Combo.Configuration`（ScriptableObject，`Assets/ComboSDK/Resources/ComboSDKSettings.asset`）— Editor 配置，存储 GameId、PublishableKey、Endpoint、各平台开关
- `_Combo.Configuration`（从 `ComboSDK.json` 加载）— Windows 运行时配置，存储 distro、domains、parameters

## CHANGELOG 格式

```markdown
## x.x.x (YYYY-MM-DD)

**FEATURES:**
- 描述

**IMPROVEMENTS:**
- 描述

**BUG FIXES:**
- 描述
```

未发布的改动放在文件顶部的 `## Unreleased` 区块中。
