MatchMaster/docs/seven-day-gift-maintenance.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` 为准。
- 当天有奖励可领且当天没有自动弹过时，进入主页自动打开活动。
- 自动弹出后即使不领取就关闭，当天也不再自动弹；入口仍保留，可手动打开。
- 领取完 7 天或活动过期后隐藏入口。
- 开发版和体验版使用测试服务器；正式版使用正式服务器。
- 正式版不显示测试面板和接口反馈面板。

## 2. 总体结构

七日活动采用“主页宿主 + 活动视图 + API 封装 + 发奖适配 + 调试工具”的结构：

```text
HomeScene
├─ Canvas/Load/Top/sevenDayDoor       主页入口占位节点
└─ Canvas/sevenDayGift                SevenDayGiftHost 宿主节点
   ├─ 动态实例化 sevenDayGift.prefab  活动弹窗
   ├─ 动态挂载入口内容 Prefab
   ├─ 开发/体验环境测试面板
   └─ 开发/体验环境接口反馈面板
```

核心调用链：

```text
进入 HomeScene / 小游戏回到前台
    ↓
SevenDayGiftHost.queryActivity(true)
    ↓
signInActivityInfo
    ↓
刷新入口、红点、活动卡片
    ↓
满足 canClaim 且当天未弹过 → 自动打开活动

玩家点击可领取卡片
    ↓
signInClaim
    ↓
SevenDayGiftReward.grant
    ↓
更新本地资产并同步相关资产接口
    ↓
打开项目公共奖励动画
    ↓
再次查询 signInActivityInfo 刷新最终状态
```

## 3. 新增文件

### 3.1 `assets/seven_day_gift/SevenDayGiftHost.ts`

活动总控制器，挂载在 `HomeScene` 的 `sevenDayGift` 节点上，负责：

- 实例化活动弹窗 Prefab。
- 查找 `Canvas/Load/Top/sevenDayDoor` 入口节点。
- 挂载入口图片内容、红点和点击事件。
- 进入主页时查询活动。
- 监听 `cc.game.EVENT_SHOW`，从后台回到前台时重新查询活动。
- 根据接口状态控制入口显示、自动弹窗和活动消失。
- 领取时复用主页 `JiaZai.openLoad/closeLoad` 加载动画。
- 调用公共奖励弹窗展示领取动画。
- 在非正式环境创建测试面板和接口反馈面板。

#### 入口显示条件

`isActivityVisible()` 当前要求：

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

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

#### 自动弹出条件

`shouldAutoOpen()` 当前要求：

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

本地记录键：

```text
seven_day_gift_auto_open_v1:<uid>:<activityId>
```

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

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

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

清除微信缓存、更换设备、更换 UID、更换 `activityId`，或者点击测试面板“清除自动弹出”，会允许再次自动弹出。

#### 查询时机

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

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

#### 加载动画

- 点击主页入口查询活动时，加载动画最长兜底 12 秒。
- 点击领取时，加载动画最长兜底 7 秒。
- 七日 API 自身的请求超时是 5.5 秒。
- 自动后台查询不主动显示 Loading，避免进入主页时无条件遮挡界面。

### 3.2 `assets/seven_day_gift/SevenDayGift.ts`

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

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

UI 约定：

- 图片统一保持 `cc.Color.WHITE`，不对原图进行额外染色。
- 活动卡片底部状态文字节点被隐藏，不显示“点击领取/未解锁”等附加文字。
- 奖励数量直接叠放在奖励图片下方。
- 单奖励和多奖励使用相同的大图标尺寸。
- 多奖励从左到右排列并允许部分重叠，但按卡片可用宽度计算间距，避免越界。
- 数量节点使用更高 `zIndex`，避免被后一个重叠图标遮挡。
- 无限体力把秒数格式化为小时、分钟或秒，例如 `900` 显示为 `x15分钟`。
- 第 7 天猫皮肤在未解锁时使用隐藏猫图片，解锁后使用正常猫图片。

### 3.3 `assets/seven_day_gift/SevenDayGiftApi.ts`

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

- 查询活动：`signInActivityInfo`。
- 领取活动：`signInClaim`。
- 保存猫皮肤：`setCatArr`。
- 测试面板查询/写入等级、金币、道具、无限体力。
- 在非正式环境打印每次请求和响应。
- 把请求、响应和超时事件发送给接口反馈面板。
- 为每次请求分配递增 `requestId`，便于匹配请求和响应。
- 5.5 秒没有回调时返回统一超时结果，迟到回调不再重复执行业务回调。

UID 优先读取：

```text
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`，调用 `setUserProp` |
| `freeze` | 增加 `GM_INFO.freezeAmount`，保存 `prop`，调用 `setUserProp` |
| `magic_wand` | 增加 `GM_INFO.magicAmount`，保存 `prop`，调用 `setUserProp` |
| `infinite_health` | 调用 `setUserPowerTime(seconds, "seven_day_gift")` |
| `cat_skin` | 使用 `itemId` 调用 `setCatArr?action=save` |

奖励数量兼容：

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

即优先读取 `count`，旧接口使用 `amount` 时仍能正常发奖和显示数量。以后不能删除该兼容，除非后端已确认所有环境和历史数据都统一完成迁移。

领取幂等记录保存在：

```text
seven_day_gift_processed_claims_v1
```

记录键为 `<uid>:<claimId>`。同一个 `claimId` 在同一设备上再次处理时直接视为成功，不重复增加资产。

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

### 3.5 `assets/seven_day_gift/SevenDayHomeEntryLayout.ts`

主页活动入口排列管理。它只调整已经显示的入口位置，不修改节点显隐、父节点和层级顺序。

左侧顺序：

```text
shop
sevenDayDoor
yicon
redeemBtn
passBtn
jungle
xinshou
```

右侧顺序：

```text
rank
gacha
day
posBtn
topBtn
hammer
```

布局参数：

- 第一项 Y：`-143.83`
- 相邻入口间距：`220`
- 只排列 `active === true` 的节点，隐藏入口不占空位。
- 宿主每 0.25 秒刷新一次，兼容其他活动运行时改变显隐。

以后修改入口顺序时，应修改这里的名称数组；节点名必须与 `HomeScene` 的 `Canvas/Load/Top` 子节点完全一致。

### 3.6 `assets/seven_day_gift/debug/SevenDayGiftDebugPanel.ts`

七日活动测试面板，仅在 Cocos 预览、微信开发版或体验版创建，正式版不创建。

能力包括：

- 查看当前环境、服务器地址、UID、本地关卡和资产。
- 查询真实测试服活动。
- 手动打开活动。
- 清除当天自动弹出记录。
- 本地模拟第 1～7 天。
- 本地模拟今日已领取、七天完成、活动过期。
- 增加金币、锤子、冻结、魔法棒和无限体力。
- 在微信开发版/体验版中把测试资产同步到测试服务器。

“本地模拟”用于检查 UI，不证明后端领取流程正确；“真实测试服”会修改测试服数据。

### 3.7 `assets/seven_day_gift/debug/SevenDayGiftApiFeedbackPanel.ts`

独立接口反馈面板，仅用于非正式环境。

可主动查询：

- 全部相关查询接口。
- `/userLevel?action=read`，显示服务器 `levelAmount`。
- `signInActivityInfo`。
- `/userCoin?action=read`。
- `/userProp?action=read`。
- `/userPower?action=read`。

领取时产生的 `signInClaim` 和 `setCatArr` 请求也会自动进入记录。面板最多保存 120 条记录，按最新记录在上方展示，内容区域支持垂直滚动。

### 3.8 Prefab 和图片资源

新增：

- `assets/seven_day_gift/prefab/sevenDayGift.prefab`：七日活动主弹窗。
- `assets/seven_day_gift/resources/seven_day_gift/sevenDayGiftDoor.prefab`：主页入口内容。
- `assets/seven_day_gift/resources/seven_day_gift/*.png`：活动卡片、标题、猫、道具、已领取标记等图片。
- `assets/seven_day_gift/texture/*.png`：活动基础面板和卡片资源。

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

## 4. 接口契约

### 4.1 查询活动 `signInActivityInfo`

请求：

```json
{
  "uid": "用户UID"
}
```

主要返回字段：

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

入口出现并不等于一定自动弹窗。入口只依赖活动可见状态；自动弹窗额外要求 `canClaim === true` 且当天未弹过。

### 4.2 领取活动 `signInClaim`

请求：

```json
{
  "uid": "用户UID"
}
```

主要返回字段：

| 字段 | 含义 |
| --- | --- |
| `claimId` | 本次领取唯一标识，用于客户端和服务端幂等 |
| `rewardDay` | 本次领取第几天 |
| `rewards` | 实际发放的奖励数组 |
| `claimedCount` | 领取后的总进度 |
| `todayClaimed` | 领取后应为真 |
| `completed` | 是否已经领满 7 天 |

后端必须让同一个领取请求具备幂等性。客户端成功收到领取结果后才执行本地发奖，随后再次查询活动状态。

### 4.3 当前奖励配置

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

| 天数 | 奖励 |
| ---: | --- |
| 1 | 无限体力 900 秒（15 分钟） |
| 2 | 锤子 ×1 |
| 3 | 无限体力 1800 秒（30 分钟） |
| 4 | 冻结 ×1、魔法棒 ×1 |
| 5 | 金币 ×600 |
| 6 | 锤子 ×1、冻结 ×1、魔法棒 ×1 |
| 7 | 无限体力 3600 秒（1 小时）、猫皮肤 `itemId=12` ×1 |

正式奖励以服务端 `rewards` 为准。修改服务器奖励后，也要同步修改 `createPreviewInfo()`，否则本地模拟面板展示的内容会与真实活动不一致。

## 5. 环境和服务器路由

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

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

路由规则：

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

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

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

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

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

### 6.1 `assets/Scene/HomeScene.fire`

语义上的新增内容只有两个主要节点：

- `Canvas/Load/Top/sevenDayDoor`：主页入口占位。
- `Canvas/sevenDayGift`：活动宿主节点，挂载 `SevenDayGiftHost`。

宿主组件序列化引用：

- 七日活动主弹窗 Prefab。
- 七日入口 Prefab。

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

### 6.2 `assets/Script/JiaZai.ts`

有两类修改：

1. 将 `sevenDayDoor` 加入主页 Top 入口渐隐列表。
   - 移动端开始滑动时与商城、排行榜等入口一起淡出。
   - 松手后恢复透明度。
2. 每日任务数据增加空字段保护。
   - `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 `assets/shop/prefab/rewardNode.prefab`

在 `rewardNode/icon` 下增加默认隐藏的 `cat_skin` 节点和 Sprite，用于公共奖励弹窗展示猫皮肤奖励。

同时存在 `Reward.ts` 的运行时创建兜底，因此即使旧 Prefab 缓存暂时没有新节点，只要传入 `spriteFrame` 也可以显示；正式构建仍应包含修改后的 Prefab。

### 6.7 `build-templates`

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

## 7. 日志和排查方式

开发版/体验版控制台过滤：

```text
[SevenDayGiftApi]
```

请求日志包含：

- 请求编号。
- 请求时间。
- 接口名。
- 完整地址。
- 请求参数。
- 响应耗时。
- 完整响应内容。
- 超时记录。

常见问题排查：

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

## 8. 正确测试流程

### 8.1 UI 模拟测试

使用测试面板依次验证：

- 第 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。
- 后端缺少部分每日任务字段时主页不崩溃。

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

## 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`

修改后同步更新 `SevenDayGiftHost.createPreviewInfo()`，让本地测试数据保持一致。

### 10.2 修改奖励数量

优先修改后端 `rewards` 配置，同时更新预览数据。保持 `count` 为首选字段，并继续兼容 `amount`。

### 10.3 增加新的奖励类型

至少检查以下位置：

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

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

### 10.4 修改主页入口顺序

修改 `SevenDayHomeEntryLayout.ts` 的左右列表。新增入口还需要检查：

- `HomeScene` 中节点是否位于 `Canvas/Load/Top`。
- 节点名是否一致。
- 是否需要加入 `JiaZai.initTopBarTouchFade()` 的淡化名单。
- 是否具备与其他按钮一致的 `cc.Button.Transition.SCALE`。

### 10.5 修改活动图片或 Prefab

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

## 11. 当前工作区风险快照

记录时 `git status` 约有 3591 项，绝大多数为 `.meta` 修改，并有 3 个与七日活动无关的 `.meta` 删除：

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

七日活动目录约 64 个文件仍为未跟踪状态。不要使用未经检查的 `git add -A`，否则可能把大量 Creator 自动改写或无关资源变化一起提交。

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

```text
assets/seven_day_gift.meta
assets/seven_day_gift/
assets/Scene/HomeScene.fire
assets/Script/GameManager.ts
assets/Script/JiaZai.ts
assets/Script/Reward.ts
assets/Script/module/Pay/Utils.ts
assets/shop/prefab/rewardNode.prefab
docs/seven-day-gift-maintenance.md
```

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

## 12. 已知边界与维护原则

- 活动创建、触发等级、自然日、可领取状态和过期判断的最终权威是后端。
- 本地测试面板不能代替真实接口测试。
- 自动弹出记录是设备本地状态，清缓存和换设备后可能再次弹出；但后端 `canClaim` 仍决定是否有奖励可领。
- 客户端 `claimId` 防重不能代替服务端幂等。
- 正式版不显示调试面板，也不打印七日 API 的详细前端日志，因此正式环境需要后端监控。
- 体验版走测试服，无法仅靠体验版证明正式服务器配置正确；正式发布前必须单独验证正式接口部署和配置。
- 场景和 Prefab 的 UUID 依赖 `.meta`，资源提交必须完整。
- 修改主项目公共奖励窗口、主页入口排列或网络基类时，要回归其他活动，避免只验证七日活动。