yangzhao/MatchMaster
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
MatchMaster/docs/seven-day-gift-maintenance.md

26 KiB
Raw Permalink Blame History

当前交互更新：七日弹窗无关闭按钮；首次外部点击与卡片领取一致，只领取当前奖励，后一次外部点击再关闭。领取及效果期间禁止重复操作。奖励改用 assets/reward_claim_effect/RewardClaimEffect.ts 上浮效果；下文旧版自动领取、关闭按钮和公共奖励动画说明仅作历史记录，测试以 testSeven-local-preview.md 为准。

七日好礼活动实现与维护说明

本文记录 feature/seven_day_gift 分支从 main 拉出后完成的七日签到活动相关改动，供后续开发、联调、测试和上线维护使用。

记录日期：2026-09-04

基线提交：6b56b88284e1bb864241530a23aa3376ce0faf3e

开发分支：feature/seven_day_gift

重要：记录时该分支相对 main 没有新的已提交 commit，功能改动仍在工作区。本文描述的是“当前工作区相对 main”的实际差异，不代表这些文件已经提交或合并。

1. 功能目标

本次增加一个由后端控制状态的七日好礼活动，主要规则如下：

  • 玩家主线达到活动触发条件后，在主页自动弹出七日活动，不再显示手动入口按钮。
  • 当前约定的触发等级为 23，但前端不自行计算触发结果，以后端返回的 triggerReached 为准。
  • 活动有效期由后端的 startAt、endAt 和 status 控制；当前产品约定是 14 天内领取 7 天奖励。
  • 每个服务器自然日最多领取一次，具体是否可领取以后端 canClaim 为准。
  • 当天有奖励可领且当天没有自动弹过时，进入主页自动打开并自动领取当天奖励。
  • 自动领取结束（成功或失败）后才开放关闭按钮；失败时可点击当天卡片重试。
  • 当天领取后关闭页面，即销毁活动实例并释放 Bundle；第二天满足条件时重新加载。
  • 开发版和体验版使用测试服务器；正式版使用正式服务器。
  • 上线代码不包含测试面板、接口反馈、模拟日期或测试资产注入功能。

2. 总体结构

七日活动采用“主包轻量宿主 + 活动 Bundle”的结构。主包只负责首次状态查询、自动弹出判断和 Bundle 生命周期；活动 UI、领取和发奖代码均放入 seven_day_gift Bundle：

HomeScene
└─ Canvas/sevenDayGift                         主包中的轻量宿主节点
   ├─ SevenDayGiftHost                         Bundle 加载与释放
   └─ SevenDayGiftBootstrapApi                 首次状态查询

seven_day_gift Bundle
├─ prefab/sevenDayGift.prefab                  活动弹窗
├─ SevenDayGift + SevenDayGiftRuntime          UI 与业务流程
├─ SevenDayGiftApi + SevenDayGiftReward        完整接口与发奖
└─ texture/*                                   活动图片

核心调用链：

进入 HomeScene / 小游戏回到前台
    ↓
SevenDayGiftHost.queryActivity(true)
    ↓
signInActivityInfo
    ↓
判断活动是否可见、当天是否可领取
    ↓
满足 canClaim 且当天未弹过 → 自动打开活动

自动弹窗完成后自动领取当天卡片
    ↓
使用本次查询的 nextRewardDay 对应 items
    ↓
SevenDayGiftReward.grant
    ↓
更新本地资产并同步相关资产接口
    ↓
打开项目公共奖励动画
    ↓
在当前快照上更新已领取状态，不重复查询

3. 新增文件

3.1 主包引导层

assets/Script/seven_day_gift/SevenDayGiftHost.ts 挂载在 HomeScene 的 sevenDayGift 节点上，只负责：

  • 进入主页时查询活动。
  • 监听 cc.game.EVENT_SHOW，从后台回到前台时重新查询活动。
  • 判断是否需要自动弹出。
  • 按需加载 seven_day_gift Bundle 和 prefab/sevenDayGift。
  • 弹窗关闭后销毁实例，并在下一帧执行 bundle.releaseAll() 和 cc.assetManager.removeBundle()。

assets/Script/seven_day_gift/SevenDayGiftBootstrapApi.ts 是主包中的最小查询接口，只包含 signInActivityInfo、UID 获取、服务器选择、超时和基础日志。它不能引用 Bundle 内的完整 API、Reward、Prefab 或调试脚本，否则这些代码会被重新打进主包。

活动可见条件

isActivityVisible() 当前要求：

  • 返回了 activityId。
  • triggerReached === true。
  • status 不是 expired。
  • status 不是 completed。
  • serverNow < endAt。

前端没有直接检查 startAt，正常情况下应由后端通过 status 保证活动尚未开始时不返回可见状态。

自动弹出条件

shouldAutoOpen() 当前要求：

  • 活动处于可见状态。
  • 后端返回 canClaim === true。
  • 本地没有当前用户、当前活动、当天的自动弹出记录。

本地记录键：

seven_day_gift_auto_open_v1:<uid>:<activityId>

值为根据 serverNow 计算出的东八区自然日编号。自动弹出前先写记录，再执行 show()，防止同一运行过程重复触发。

以下操作不会自动清除该记录：

  • 修改服务器关卡等级。
  • 将等级从 23 改回 22 后再次通关。
  • 重新请求活动接口。
  • 关闭活动但不领取。

清除微信缓存、更换设备、更换 UID 或更换 activityId，会允许再次自动弹出。

查询时机

  • HomeScene 中宿主组件执行 onLoad()。
  • 小游戏触发 cc.game.EVENT_SHOW，并且宿主仍位于当前主页场景。

七日活动宿主不在关卡场景中，因此玩家在关卡里达到触发等级时不会立即弹窗；返回主页后才查询和判断。

加载与释放

  • 点击领取时，加载动画最长兜底 7 秒。
  • 七日 API 自身的请求超时是 5.5 秒。
  • 自动后台查询不主动显示 Loading，避免进入主页时无条件遮挡界面。
  • 各微信环境都只有命中自动弹出条件时才加载 Bundle。
  • Cocos 编辑器预览不主动请求活动，也不加载 Bundle；联调应使用微信开发版或体验版。
  • 节点先销毁，Bundle 在下一帧释放，避免在组件销毁回调尚未结束时回收其脚本和资源。

3.2 assets/seven_day_gift/SevenDayGift.ts

活动弹窗视图组件，负责：

  • 缓存 7 张奖励卡片。
  • 根据接口数据刷新卡片底图、日期、奖励图标和领取状态。
  • 仅允许点击 nextRewardDay 对应且 canClaim 为真的卡片。
  • 防止领取过程中重复点击。
  • 活动打开和关闭时播放缩放、透明度动画。
  • 当前可领取卡片播放轻微循环缩放提示。
  • 自动领取期间隐藏关闭按钮并禁止遮罩关闭；领取回调结束后才允许关闭。

UI 约定：

  • 图片统一保持 cc.Color.WHITE，不对原图进行额外染色。
  • 活动卡片底部状态文字节点被隐藏，不显示“点击领取/未解锁”等附加文字。
  • 单奖励和多奖励使用相同的大图标尺寸。
  • 多奖励从左到右排列并允许部分重叠，但按卡片可用宽度计算间距，避免越界。
  • 卡片只显示道具图片，不显示奖励名称或数量文字。
  • 第 7 天猫皮肤在未解锁时使用隐藏猫图片，解锁后使用正常猫图片。

3.3 assets/seven_day_gift/SevenDayGiftApi.ts

七日活动接口封装和 TypeScript 数据契约，负责：

  • 活动查询由主包 SevenDayGiftBootstrapApi 调用 signInActivityInfo，Bundle 内不再请求活动接口。
  • 保存猫皮肤：setCatArr。
  • 保存普通道具：userProp。
  • 5.5 秒没有回调时返回统一超时结果，迟到回调不再重复执行业务回调。

UID 优先读取：

cc.fx.StorageMessage.getStorage("uid")

并同步回 cc.fx.GameConfig.GM_INFO.uid。如果发现 UID 改变，应先检查登录流程和本地 uid 缓存，而不是只看七日活动脚本。

3.4 assets/seven_day_gift/SevenDayGiftReward.ts

将后端奖励转换成项目现有资产操作，支持以下类型：

后端类型 前端处理
coin cc.fx.GameTool.changeCoin()
hammer 增加 GM_INFO.hammerAmount，保存 prop，通过 SevenDayGiftApi.saveProps() 同步 /userProp
freeze 增加 GM_INFO.freezeAmount，保存 prop，通过 SevenDayGiftApi.saveProps() 同步 /userProp
magic_wand 增加 GM_INFO.magicAmount，保存 prop，通过 SevenDayGiftApi.saveProps() 同步 /userProp
infinite_health 调用 setUserPowerTime(seconds, "seven_day_gift")
cat_skin 使用 itemId 调用 setCatArr?action=save

奖励数量兼容：

const rewardAmount = item.count !== undefined ? item.count : item.amount;

即优先读取 count，旧接口使用 amount 时仍能正常发奖。卡片虽然不显示数量文字，发奖逻辑仍必须保留此兼容，除非后端已确认所有环境和历史数据都统一完成迁移。

领取幂等记录保存在：

seven_day_gift_processed_claims_v1

记录键为 <uid>:<claimId>；这里的 claimId 是前端用 [activityId, startAt, nextRewardDay] 序列化生成的本地同步标识，接口不需要返回该字段。同一个 claimId 在同一设备上再次处理时直接视为成功，不重复增加资产。

注意：这个记录是客户端本地幂等保护，不能代替服务端活动领取的幂等校验。清缓存或换设备后本地记录会消失，后端仍必须保证同一用户、同一天、同一领取不能重复发放。

3.5 assets/seven_day_gift/SevenDayGiftRuntime.ts

Bundle 内的活动业务控制器，只有 Bundle 加载后才进入内存，负责：

  • 直接消费主页查询结果中的当日奖励，交给 SevenDayGiftReward 同步本地资产及对应资产接口。
  • 更新当前快照的领取状态、调用项目公共奖励动画；不再发起额外活动请求。
  • 管理主页 Loading、错误提示和领取失败后的重试状态。
  • 销毁时清理 Loading 和运行状态。

旧的 SevenDayHomeEntryLayout.ts 和主页入口 Prefab 已删除；七日活动不再参与主页入口排序，也不会改动商城、排行榜等既有入口的位置或透明度。

3.6 Prefab 和图片资源

新增：

  • assets/seven_day_gift/prefab/sevenDayGift.prefab：七日活动主弹窗。
  • assets/seven_day_gift/texture/*.png：活动面板、卡片、标题、猫、道具和已领取标记等图片。

所有 Cocos 资源必须连同对应 .meta 文件提交，不能只提交 PNG、Prefab 或 TypeScript 文件。.meta 中的 UUID 是场景和 Prefab 引用资源的依据。

3.7 assets/Script/ActivityPopupAnimator.ts

公共活动弹窗动画工具，七日活动通过 popupAnimation 选择动画类型。该脚本属于主包是因为 Bundle 内弹窗需要引用它；它不包含活动数据、测试入口或网络逻辑。

4. 接口契约

4.1 查询活动 signInActivityInfo

请求：

{
  "uid": "用户UID"
}

主要返回字段：

字段 含义
serverNow 服务器当前时间，支持毫秒、秒级数值或可解析日期字符串
activityId 活动标识，同时用于自动弹出本地键
status 当前状态，前端明确识别 active、completed、expired
triggerLevel 后端配置的触发等级，仅展示/诊断
triggerReached 后端最终触发判断；是否允许自动弹出依赖此字段
startAt 活动开始时间，当前前端不直接校验
endAt 活动结束时间，活动可见性判断会校验
claimedCount 已领取天数
todayClaimed 当天是否已领取
canClaim 当前是否允许领取，同时控制自动弹窗和卡片领取
nextRewardDay 下一次应该领取第几天
rewards 7 天奖励数组及每项 claimed 状态

活动自动弹窗要求活动处于可见状态、canClaim === true 且当天未弹过。当前版本没有手动入口。

4.2 查询结果直接驱动领取

不再使用独立领取接口。signInActivityInfo 的请求携带 uid，由公共 POST 层补 token，不传 gameName。未达到 23 关时 code: 1, data: false，主页不弹窗。

达到条件后，使用查询响应中的 nextRewardDay 在 rewards 中找到对应 day 的 items。自动弹窗动画结束后同步这些奖励，完成后本地更新 claimed、claimedCount、todayClaimed、canClaim 和第七天 completed 状态，再播放公共奖励动画。领取过程不重新请求活动接口。

每天自动弹窗记录按 UID、活动 ID 和服务器 UTC+8 日期隔离。同步失败允许在当前弹窗点击当天卡片重试，但不清除当天已弹记录；关闭后当天不会再次自动弹出。弹窗打开期间切回前台不重复查询。

当前沿用客户端增加资产并调用资产保存接口的方式；查询响应必须是可消费的领取快照。后端若已经直接增加资产，必须改为读取资产最终值，不能再使用客户端累加。服务器需要维护跨日进度和幂等；前端不会把自己计算的 claimedCount 写回活动接口。

4.3 当前奖励配置

当前已联调的后端数据为：

天数 奖励
1 无限体力 900 秒（15 分钟）
2 锤子 ×1
3 无限体力 1800 秒（30 分钟）
4 冻结 ×1、魔法棒 ×1
5 金币 ×600
6 锤子 ×1、冻结 ×1（策划调整：删除魔法棒，服务端待同步确认）
7 无限体力 3600 秒（1 小时）、猫皮肤 itemId=12 ×1

正式奖励完全以服务端 rewards 为准，前端不再维护模拟奖励配置。

5. 环境和服务器路由

服务器地址定义在 assets/Script/module/Pay/Utils.ts：

正式服务器：https://q6rvwvtnga.sealoshzh.site/
测试服务器：https://sor779u2w8.sealoshzh.site/

路由规则：

envVersion 项目识别 使用地址
develop 开发版 测试服务器
trial 体验版 测试服务器
release 正式版 正式服务器
其他/未知 未知版本 正式服务器兜底

因此正常发布流程不需要上线前手工把 testHttpip 改成正式地址。体验版继续访问测试服，正式发布后自动切换正式服。

正式上线前必须同时确认：

  • 微信后台已经配置正式请求域名。
  • 开发/体验测试需要的测试域名也已配置。
  • 两个服务器部署了兼容的数据结构和对应接口。
  • 正式服的活动配置、奖励、触发等级、活动期限已经检查。

6. 对主项目原有文件的修改

6.1 assets/Scene/HomeScene.fire

语义上的新增内容只有 Canvas/sevenDayGift 活动宿主节点，并挂载主包中的 SevenDayGiftHost。场景不再序列化引用活动 Prefab；宿主通过 Bundle 名和资源路径动态加载，避免 Prefab 依赖把整个活动反向带入主包。

由于 Cocos 场景文件使用数组 __id__ 交叉引用，插入节点后大量后续编号发生位移，Git 会显示上千行机械差异。评审时应重点确认新增节点、父节点、组件和 UUID 引用，不应把所有 __id__ 位移误判成业务改动。

6.2 assets/Script/JiaZai.ts

每日任务数据增加空字段保护：

  • levelPass、share、useEnergy、useProp 缺失时建立默认对象。
  • 后端任务数据不完整时只更新实际存在的字段。

这属于联调期间为避免每日任务接口变化导致主页 checkTasks() 崩溃而增加的兼容，不是七日活动核心逻辑，但主页如果在这里抛异常，会连带影响七日活动初始化和测试。七日活动已删除入口，不再修改主页入口渐隐列表。

6.3 assets/Script/GameManager.ts

登录返回的 data.data.task 同时兼容：

  • JSON 字符串。
  • 已经解析好的对象。
  • 缺少部分任务字段。
  • 无法解析的异常字符串。

原实现无条件 JSON.parse()，后端改为对象或返回异常结构时会抛错；现在使用类型判断和 try/catch，只覆盖实际存在的任务字段。

6.4 assets/Script/module/Pay/Utils.ts

修改内容：

  • 恢复独立测试服务器 testHttpip。
  • POST() 根据微信环境选择 testHttpip 或 httpip。
  • 每日任务保存和领取结果增加空字段保护。

这项环境路由是七日活动安全测试和上线的关键。不要为了临时联调再次把 testHttpip 指向正式服，否则开发版和体验版会修改正式用户数据。

6.5 assets/Script/Reward.ts

项目公共奖励弹窗原来只支持 Prefab 中预先存在的固定图标节点。本次增加 getOrCreateRewardIcon()：

  • 优先查找 icon/<reward type> 现有节点。
  • 找不到节点但调用方传入 spriteFrame 时，运行时创建 Sprite 节点。
  • 找不到节点且没有 spriteFrame 时打印警告，不让空引用直接崩溃。
  • cat_skin 使用 1.1 缩放。

七日活动把 magic_wand 转为公共奖励弹窗原有名称 magic；猫皮肤则额外传入活动中的 catArt SpriteFrame。

6.6 build-templates

记录时 build-templates 相对 main 没有差异，不属于本次七日活动功能改动。后续排查 game.json、project.config.json 或分包模板问题时，应单独检查负责人提供的模板版本，不要把模板问题和七日活动脚本混为一谈。

7. 日志和排查方式

上线版本只保留超时、领取失败、资产同步失败和缺失资源等异常日志，不再打印完整请求参数及响应。联调时使用微信开发者工具 Network 面板，并结合后端日志确认接口：

signInActivityInfo
userCoin / userProp / userPower / setCatArr

常见问题排查：

现象 优先检查
达到 23 关但没有自动弹 signInActivityInfo 的 activityId、triggerReached、status、endAt、canClaim；再查服务器 levelAmount 和本地当天自动弹记录
每次回主页都重复弹 是否每次清缓存；UID/activityId 是否变化；自动弹出本地记录是否被其他逻辑清除
卡片不能领取 canClaim、nextRewardDay、当前卡片 claimed；查看 signInActivityInfo 返回及资产同步错误
奖励数量为 0 后端是否返回 count 或 amount；值是否能转换为数字
猫皮肤动画不显示 Reward.ts 是否收到 spriteFrame；活动猫图片 UUID 是否有效
猫皮肤没有保存 查看 setCatArr 的请求、itemId 和返回内容
微信报合法域名错误 微信后台 request 合法域名是否包含当前环境服务器域名
活动测试 UID 变化 登录接口、本地 uid 缓存、GM_INFO.uid 是否被其他流程重写

8. 正确测试流程

8.1 UI 验收

测试代码已从上线分支删除。请由后端准备不同活动进度的测试 UID，在微信开发版或体验版依次验证：

  • 第 1～7 天布局。
  • 单奖励和多奖励的图片大小与重叠，确认不显示数量文字。
  • 今日已领取状态。
  • 七天完成状态。
  • 活动过期状态。
  • 自动弹出、自动领取、领取期间禁止关闭和领取后关闭。
  • 公共奖励动画。

前端不再提供模拟日期、清除自动弹出记录或增加资产按钮。

8.2 完整测试服流程

准备干净测试 UID：服务器等级 22，并且没有七日活动记录。

  1. 22 级进入主页，确认没有自动弹窗。
  2. 通关并让服务器等级变成 23。
  3. 返回主页，确认自动弹一次并自动发起领取。
  4. 自动领取完成前确认关闭按钮不可用，完成后可以关闭。
  5. 再进主页或切前后台，确认当天不重复自动弹。
  6. 确认领取接口、Loading、奖励动画和资产变化。
  7. 重启游戏，确认资产持久化。
  8. 当天重复点击领取，确认后端不重复发放。
  9. 由后端推进测试日期或重置测试活动，完成第 2～7 天验证。
  10. 领满后确认不再弹出。
  11. 使用另一条未领满记录推进到 endAt 之后，确认不再弹出。
  12. 使用一个等级大于 23 且没有活动记录的老玩家 UID，验证补触发逻辑。

修改服务器等级不会删除已经创建的活动记录，也不会清除本地自动弹出记录。要重新测试“22 → 23 首次触发”，必须使用新 UID，或者让后端删除该 UID 的活动记录，并同时清除本地自动弹出记录。

8.3 异常测试

  • 断网进入主页。
  • 查询接口超时后恢复网络。
  • 领取时连续快速点击。
  • 领取响应返回后立即杀进程。
  • 第 7 天保存猫皮肤时断网。
  • 切后台后重新进入。
  • 清缓存后重新登录。
  • 同一设备切换两个 UID。
  • 后端缺少部分每日任务字段时主页不崩溃。

其中“后端已经确认领取，但客户端资产同步尚未完成时退出”是需要重点关注的边界。当前流程消费 signInActivityInfo 返回的奖励快照，再更新金币、道具、无限体力和猫皮肤；服务端必须提供可查询、可重试且幂等的最终结果，不能只依赖本地领取标记。

9. 上线流程

  1. 整理工作区，只保留确认需要的业务改动。
  2. 把七日活动目录和所有对应 .meta 纳入 Git。
  3. 提交功能分支。
  4. 获取并合并最新 main。
  5. 冲突解决后重新执行测试服完整流程。
  6. 合并到发布分支或 main。
  7. 从确定的发布 commit 做一次干净微信小游戏构建。
  8. 微信开发者工具确认无新增红色业务错误、分包正确、请求域名正常。
  9. 上传开发版本并设置体验版。
  10. Android、iOS 真机测试，确认体验版仍访问测试服务器。
  11. 后端确认正式接口和活动配置已部署。
  12. 提交审核；审核通过后发布。
  13. 如果后台支持灰度，优先灰度并观察活动查询、领取、重复领取拦截和猫皮肤保存错误率。

正式发布后需用正式环境测试账号做最小冒烟验证：

  • 页面上不存在“7日测试”和“接口反馈”按钮。
  • signInActivityInfo 请求正式服务器。
  • 达标且可领取用户当天自动弹出一次并自动领取。
  • 一次领取可以完整到账。
  • 领取后状态和资产重登仍一致。

10. 后续修改指南

10.1 修改触发等级或活动期限

触发等级和期限应优先修改后端配置。前端只消费：

  • triggerLevel
  • triggerReached
  • startAt
  • endAt
  • status

前端没有触发等级和期限的本地模拟配置。

10.2 修改奖励数量

修改后端 rewards 配置。保持 count 为首选字段，并继续兼容 amount。

10.3 增加新的奖励类型

至少检查以下位置：

  1. SevenDayRewardItem.type 类型声明。
  2. SevenDayGift.getRewardIcon() 的活动卡片图标。
  3. SevenDayGiftReward.grant() 的真实资产发放。
  4. SevenDayGiftRuntime.showRewardWindow() 对公共奖励类型的转换。
  5. Reward.ts 的公共奖励动画图标创建逻辑。
  6. 图片资源及 .meta。
  7. 后端奖励配置与服务端幂等处理。

只增加图片但不增加发奖分支，会出现“界面能看到、资产不增加”；只增加发奖分支但不配置图标，会出现“奖励到账但动画没有图”。

10.4 修改 Bundle 加载策略

  • 主包只能依赖 SevenDayGiftHost.ts 和 SevenDayGiftBootstrapApi.ts。
  • 不要在主包脚本中静态 import Bundle 内的 SevenDayGift、SevenDayGiftRuntime、完整 API 或 Reward。
  • HomeScene.fire 不要重新添加活动 Prefab 的序列化引用。
  • 正式版保持按需加载；如果修改释放逻辑，必须验证关闭活动后 cc.assetManager.getBundle("seven_day_gift") 返回空，并验证第二天仍可重新加载。

10.5 修改活动图片或 Prefab

  • 优先在 Cocos Creator 2.4.15 中操作 Prefab 和场景。
  • 保留已有 .meta，不要删除后让 Creator 生成新 UUID。
  • 替换图片时检查透明边距、原始尺寸和 Sprite sizeMode。
  • 保存场景后检查是否只产生预期语义变化。
  • 构建后必须在微信开发者工具再次验证，不能只点微信开发者工具“编译”来代替 Cocos 重新构建。

11. 当前工作区风险快照

当前工作区仍有数千项状态变化，绝大多数为 .meta 修改，并有 3 个与七日活动无关的 .meta 删除：

assets/gacha_bundle/img/cat.meta
assets/libs/dn-sdk-minigame.meta
assets/pause/texture.meta

不要使用未经检查的 git add -A，否则可能把大量 Creator 自动改写或无关资源变化一起提交。

建议提交前逐项确认以下范围：

assets/seven_day_gift.meta
assets/seven_day_gift/
assets/Script/seven_day_gift.meta
assets/Script/seven_day_gift/
assets/Script/ActivityPopupAnimator.ts
assets/Script/ActivityPopupAnimator.ts.meta
assets/Scene/HomeScene.fire
assets/Script/GameManager.ts
assets/Script/JiaZai.ts
assets/Script/Reward.ts
assets/Script/module/Pay/Utils.ts
docs/seven-day-gift-maintenance.md

项目配置文件和 build-templates 不属于当前七日活动相对 main 的有效内容差异，除非负责人明确要求更新，否则不要顺手提交。

12. 已知边界与维护原则

  • 活动创建、触发等级、自然日、可领取状态和过期判断的最终权威是后端。
  • 上线分支没有内置测试面板，活动状态测试依赖后端测试账号和微信开发者工具 Network 面板。
  • 自动弹出记录是设备本地状态，清缓存和换设备后可能再次弹出；但后端 canClaim 仍决定是否有奖励可领。
  • 客户端 claimId 防重不能代替服务端幂等。
  • 正式版不打印七日 API 的详细前端日志，因此正式环境需要后端监控。
  • 体验版走测试服，无法仅靠体验版证明正式服务器配置正确；正式发布前必须单独验证正式接口部署和配置。
  • 场景和 Prefab 的 UUID 依赖 .meta，资源提交必须完整。
  • 修改主项目公共奖励窗口或网络基类时，要回归其他活动，避免只验证七日活动。
  • Bundle 卸载只能保证七日活动自身持有的资源引用被释放；若其他主包节点重新持有 Bundle 内 SpriteFrame、Prefab 或脚本对象，资源仍可能无法及时回收。