Implement TapADN commercialization module

GLOBAL_DESIGN.md

@@ -0,0 +1,107 @@
+# Commercialization.tapadn 全局设计
+
+## 目标
+
+本模块把 TapADN / Dirichlet 聚合广告 SDK 接到 `CC-Framework.Commercialization` 抽象层后面，让业务项目继续只关心 `ADManager` 和 `ADConfig`。
+
+当前实现对齐 `Commercialization.topon` 的分层：
+
+* `CC-Framework.Commercialization`: `ADManager`、`IAdController`、`ADPlayer` 抽象。
+* `Commercialization.tapadn`: 平台 controller、广告播放器、构建自动化。
+* `DirichletMediation`: 官方 SDK 和平台桥。
+
+## 目录
+
+* `Assets/DirichletMediation`: 官方聚合 Unity SDK `4.2.5.0`，已删除官方 Sample。
+* `Assets/Plugins/Android`: 官方 Android AAR、Manifest、ProGuard、本地微信 OpenSDK AAR。
+* `Assets/Plugins/iOS`: 官方 iOS bridge。
+* `Assets/Tapadn_Adapter/Runtime/Scripts`: 商业化抽象层适配。
+* `Assets/Tapadn_Adapter/Editor`: Android 构建后处理和依赖声明。
+* `Assets/Samples~`: 可选调试样例预留，不随主包自动进入业务项目。
+
+## Runtime 设计
+
+`TapadnAdController` 实现 `IAdController`：
+
+* 从 `ADConfig` 和可选 `args` 解析 `TapadnControllerOptions`。
+* 构造 `DirichletAdConfig` 并调用 `DirichletSdk.Init`。
+* 根据 `AD_Type` 创建 `TapadnAwardVideoPlayer`、`TapadnInteractionPlayer`、`TapadnSplashPlayer`。
+
+`TapadnCommercialization` 是便捷入口：
+
+* `CreateController()` 隐藏 controller 创建细节。
+* `InitADManager(...)` 由模块负责创建 controller 并交给 `ADManager`。
+* `CreateConfig(...)` 用代码生成临时 `ADConfig`，适合游戏项目不想维护 TapADN SDK 细节时使用。
+
+## 广告播放器
+
+默认方案：使用 TapADN auto-ad 接口。
+
+原因：
+
+* 官方 Unity 文档推荐 Android auto-ad，接口把加载和展示合并，SDK 自己管理缓存。
+* `ADManager.AsyncAdPlayer` 已有遮罩、超时和回调收口；auto-ad 可以让业务侧首次播放少一个 preload 时序。
+
+备选方案：手动 load/show。
+
+* 已通过 `tapadn.rewarded_auto_load=false` 等 key 保留。
+* 手动模式保存 SDK 返回的 ad handle，并在 `Closed` 时销毁。
+
+不确定点：
+
+* 官方文档说明 auto-ad 目前主要是 Android 能力，iOS auto-ad 会返回 `not_supported`。本模块保留手动 fallback，但真正 iOS 出包前需要用 TapADN iOS 账号和广告位做真机验证。
+* `AD_Type` 抽象层没有 Banner 类型，所以本轮没有将 TapADN Banner 暴露到 `ADManager`。如果抽象层后续新增 Banner，可以直接复用官方 `ShowBannerAutoAd`。
+
+## 配置设计
+
+基础字段复用 `ADConfig`：
+
+* `Id`: MediaId。
+* `Key`: MediaKey。
+* `Key2`: MediaName。
+* `BaseAwardAdKeyValue.value`: 激励视频 SpaceId。
+* `BaseInteractionAdKeyValue.value`: 插屏 SpaceId。
+* `BaseSplashAdKeyValue.value`: 开屏 SpaceId。
+
+高级配置通过 `CommonKeyValues` 或字典传入，使用 `tapadn.*` 前缀，避免和 TopOn 现有 key 冲突。
+
+## Android 构建设计
+
+保留官方 `DirichletGradlePostProcessor`，它负责 Dirichlet AAR 和 Maven 依赖注入。
+
+新增 `TapadnBuildAndroidProcess`，只负责本模块集成层额外需求：
+
+* TapADN Manifest 权限补齐。
+* `com.tapsdk.tapad.internal.TapADFileProvider` 和 `@xml/tapad_ad_file_path`。
+* 微信 OpenSDK 的 `com.tencent.mm` queries 与 `.wxapi.WXEntryActivity`。
+* AndroidX / Jetifier 开关。
+
+方案选择记录：
+
+* 方案 A：只放 `WXDependencies.xml`，依赖宿主 EDM4U 下载微信 SDK。风险是业务项目没有 EDM4U 或未 resolve 时构建失败。
+* 方案 B：只放本地微信 AAR。风险是宿主 EDM4U 依赖图不可见。
+* 当前选择：本地 AAR + `WXDependencies.xml` 同时保留。这样最接近 TopOn 当前工程，也能覆盖无 EDM4U 的构建场景。
+
+## 编辑器可见性
+
+本模块不提供默认可见面板。构建自动化通过 `IPostGenerateGradleAndroidProject` 静默执行；调试能力放入 `Samples~`，由业务项目显式导入。
+
+若后续需要可视化配置面板，应使用宏包裹菜单入口，例如 `COMMERCIALIZATION_TAPADN_DEBUG_MENU`，默认不在业务项目菜单里出现。
+
+## UPM 与本机验证约定
+
+发布包入口是 `Assets/package.json`，其中 `com.foldcc.cc-framework.commercialization` 依赖保持为远程 Git URL：
+
+```json
+"com.foldcc.cc-framework.commercialization": "http://private.lightyears.ltd:18650/foldcc/CC-Framework.Commercialization.git#1.0.14"
+```
+
+当前仓库自身作为 Unity 验证工程时，可以在 `Packages/manifest.json` 使用本地 `file:` 引用：
+
+```json
+"com.foldcc.cc-framework.commercialization": "file:CC-Framework.Commercialization/Assets"
+```
+
+该路径以 `Packages/manifest.json` 所在目录为基准，符合 Unity 本地 UPM package 规则；`Packages/CC-Framework.Commercialization` 只是本机验证副本，已被 `.gitignore` 排除，不进入发布包。
+
+如果 batchmode 出现 `Failed to resolve packages: The "path" argument must be of type string. Received undefined`，不把它直接归因为 manifest 路径错误，也不使用 `-noUpm` 绕过。处理顺序是保存 Unity Editor log 和 `%LOCALAPPDATA%\Unity\Editor\upm.log`，确认没有并发 Unity/UPM 进程，再用官方 `Unity.exe -batchmode -quit -projectPath <project> -logFile <log>` 做一次只解析 package 的验证；若仍复现，则用 Unity Hub/已打开 Editor 作为 GUI 对照入口继续看 Console 编译错误。