chore:文档补全

output/feishu-docs/SjeowIyOkiZQs3kg1kpc1utxnPh.md

@@ -0,0 +1,76 @@
+# SjeowIyOkiZQs3kg1kpc1utxnPh
+
+Source: https://dianchukeji.feishu.cn/wiki/SjeowIyOkiZQs3kg1kpc1utxnPh
+
+
+# 一.工作内容概述
+  - 对项目资源进行本地分包重构，将局内玩法、碎片收集、菜单功能、音频、皮肤等资源拆分到不同 Asset Bundle 中，降低首包压力。
+  - 搭建广告 SDK 接入架构，将项目内所有激励视频广告点位统一接入 RewardedAdService.show()方法，并区分抖音真广告环境和本地开发 Mock 环境，保证后续广告位替换和真机测试时可以统一管理。
+  - 接入分享功能，将分享能力纳入统一 Provider 初始化流程，并完成真机测试验证。
+  - 增加单元格标记动画，优化局内操作反馈表现。
+  - 生成一版海报资源，用于替换碎片收集系统中之前使用的临时占位海报。
+# 二.项目分包重构
+## 分包拆分思路
+本次分包的核心思路是按功能模块拆分，而不是简单按资源类型拆分。
+之前项目中的局内场景、碎片收集、皮肤商城、抽奖面板、音频、皮肤资源等内容大多集中在默认资源路径中。随着功能和资源不断增加，首包体积压力会越来越明显，也不利于后续在抖音真机环境中调试。
+因此本次将资源按照实际功能归属拆分到不同 Asset Bundle 中。这样处理后，玩家启动游戏时不需要立刻加载全部资源，而是可以在进入对应功能时再加载对应分包，或者在主菜单阶段进行后台静默加载。
+这种方式可以让资源归属更清晰，也让加载时机更接近真实使用场景。
+## 主要分包内容
+本次主要拆分了以下几个分包：
+  - gameplay_bundle：用于存放局内玩法相关内容，包括局内场景、教程场景、每日挑战、双牛模式、生存模式、棋盘格资源、结果面板、关卡 JSON 和生存配置等。
+  - puzzle_bundle：用于存放碎片收集系统相关内容，包括碎片收集场景、海报 prefab、海报图片、碎片配置、已收集面板和收集页 UI 资源等。
+  - menu_features_bundle：用于存放主菜单中的扩展功能，包括皮肤商城、抽奖面板、个人面板及对应 UI 资源。
+  - audio_bundle：用于存放主菜单、加载页、局内等 BGM 资源。
+  - skin_bundle：用于存放皮肤配置、皮肤 icon 和主菜单小鸡皮肤资源。
+通过这次拆分，项目资源结构从原来的“集中存放”转为“按系统分包管理”。后续新增功能时，也可以继续沿用这种组织方式，避免资源继续堆积到主包中。
+## 加载链路调整
+资源迁移后，原本直接从默认路径加载资源的逻辑也需要同步调整。
+本次补充了对应的 Bundle 加载辅助类，用于统一管理不同分包的加载入口。这样业务模块不需要直接关心资源实际位于哪个目录，也不需要在各个功能代码中写死加载路径。
+同时，场景加载逻辑也进行了调整，使局内场景、教程场景、碎片收集场景等可以从指定 bundle 中加载。
+这部分调整的意义在于，分包不只是移动资源文件，还需要把资源加载入口整理清楚。否则后续资源一旦继续迁移，很容易出现路径混乱、加载失败或重复加载的问题。
+## 功能裁切配置
+在分包之外，也同步检查了 Cocos 构建中的功能裁切配置。
+对于项目没有使用到的模块，可以在功能裁切中将其关闭，避免这些模块参与打包，用来进一步减少首包压力。
+但测试中也确认，不能简单关闭所有 3D 相关能力。因为当前海报拼图展示依赖 MeshRenderer，如果关闭基础 3D 或几何体渲染能力，海报显示会异常，变成彩色色块。
+因此这部分的处理原则是：能确定不用的模块尽量关闭，但与现有表现强相关的基础渲染能力必须保留。包体优化不能只追求体积下降，也要保证已有功能表现不被破坏。
+## 当前验证结果
+目前已经完成分包构建验证，确认抖音小游戏构建后能够生成本地 subpackages，说明本地分包已经生效。
+同时也进一步明确了本地分包的作用：本地分包主要降低首包体积，不会减少小游戏总上传包体。资源仍然会随小游戏整体上传，只是启动时不必全部进入首包。
+因此当前阶段优先处理本地分包和首包体积问题，远程包暂时不作为优先方向。
+# 三.广告和分享 SDK 接入架构搭建
+## 广告接入思路
+今日对项目中的激励视频广告能力进行了统一整理。
+之前项目中广告入口较多，如果每个入口都单独处理平台判断、广告展示、关闭回调和奖励发放，后续会很难维护，也容易出现不同广告入口逻辑不一致的问题。
+因此本次将广告能力抽象为统一 Provider，并用RewardedAdService.show() 对业务层提供统一调用入口。
+业务层只需要关心广告是否观看成功，不需要关心底层具体是抖音真实广告，还是本地 Mock 广告。这样后续替换广告位、调整广告失败提示、统计广告点位或修改奖励发放规则时，都可以集中在服务层处理。
+## 抖音真实广告 Provider
+抖音环境下使用真实广告 Provider，通过 tt.createRewardedVideoAd() 接入抖音激励视频广告。
+当前代码侧已经完成基础链路搭建，包括广告预加载、展示、关闭回调、失败处理等流程。
+后续只要完成抖音流量主认证，在平台后台创建激励视频广告位，拿到真实广告位 ID 后，替换当前占位的 adUnitId，即可使用真实广告。
+也就是说，本次已经先把代码侧的广告架构、点位接入和奖励回调流程准备好了，后续主要剩下平台侧认证、广告位配置和真机验证。
+## 本地 Mock 广告 Provider
+非抖音环境下使用本地 Mock 广告 Provider。
+Mock 广告会模拟一个完整的广告观看流程，包括弹出遮罩、倒计时、结束后返回观看成功等。这样在本地开发阶段，即使没有抖音广告环境，也可以完整测试“点击广告按钮 → 展示广告 → 观看完成 → 发放奖励”的流程。
+这种方式可以减少开发阶段对真机和真实广告位的依赖，也方便在广告 ID 还没申请下来之前，提前验证业务奖励逻辑。
+## 广告点位统一接入
+本次将项目内主要激励广告点位统一接入 RewardedAdService.show()。
+接入完成后，广告奖励逻辑更加集中。后续如果需要调整广告失败提示、统计广告点位、处理奖励发放规则，都可以在统一服务层进行处理，而不需要逐个面板修改。
+目前代码侧的广告链路已经基本准备完成，后续拿到真实广告位 ID 后，可以直接进入抖音环境验证。
+## 广告失败策略
+在抖音环境下，如果广告位 ID 没有配置、广告实例创建失败、广告加载失败或广告展示失败，都不会直接发放奖励。
+这样可以避免上线前配置遗漏，或者广告异常时出现“广告没有正常观看但奖励照发”的问题。
+对广告奖励类功能来说，这个策略比较重要，因为它能保证奖励发放和广告观看结果保持一致。
+## 分享功能接入
+除广告 SDK 外，也同步整理了分享功能的接入方式。分享功能和广告一样，都属于平台相关能力，如果直接写在具体按钮或弹窗逻辑里，后续入口变多后会导致平台判断、回调处理、次数限制和奖励发放逻辑分散，不利于维护。
+因此本次将分享能力也纳入统一 Provider 初始化流程，由 ProviderInit 负责初始化分享 Provider，并和广告 Provider 一样处理，避免在 StartMenuCtrl、GameRoot 或其他场景切换过程中重复创建实例、重复绑定回调。
+整体接入链路可以理解为：
+游戏启动 / 进入主菜单 → 初始化 ProviderInit → 初始化分享 Provider → 业务入口调用分享服务 → 平台分享能力执行 → 根据分享结果刷新次数、按钮状态和奖励逻辑
+这样处理后，业务层不需要直接关心当前是否处于抖音环境，也不需要在每个入口里单独写平台 API 调用。后续如果需要调整分享参数、分享模板、成功/失败回调，或者接入更多分享入口，都可以集中在分享 Provider 或分享服务层处理。
+## 当前验证
+目前广告和分享的代码侧基础架构已经完成。
+广告方面，主要点位已经统一接入服务层，本地 Mock 广告可以支持开发阶段测试完整奖励流程。后续完成抖音流量主认证并拿到广告位 ID 后，即可替换配置并进入真实广告真机测试。
+分享方面，当前已完成统一初始化和体力恢复入口状态修复。后续需要在抖音真机环境下继续验证分享唤起、成功回调、失败回调、每日次数限制和按钮状态刷新是否符合预期。
+# 四.后续计划
+  - 检查是否还有遗漏未接入统一服务层的看广告 / 分享按钮。
+  - 继续验证本地分包后的首包体积、分包加载速度，以及局内、碎片收集、皮肤商城、抽奖面板等功能的首次打开体验。
+  - 了解并尝试接入云服务，用于云端储存玩家存档数据。