115 lines
9.1 KiB
Markdown
115 lines
9.1 KiB
Markdown
# 七日活动预览与测试说明
|
||
|
||
核对日期：2026-09-16。实现和资源维护见 [实现与维护说明](seven-day-gift-maintenance.md)。
|
||
|
||
## 当前入口状态（2026-09-18 补充核对）
|
||
|
||
七日白字入口也已暂停：SevenDayGiftHost.onLoad 中 loadTestEntry 调用被注释。恢复时需重新启用调用并打开 SevenDayTest.prefab 的 entry，再重新构建。下面白字面板操作以恢复为前提；正常活动查询仍保留。
|
||
|
||
当前项目没有旧版 `assets/testSeven/` 或 `TestSeven.fire`。新版真实接口测试入口位于 `assets/seven_day_gift/test/`，与七日活动共用 Bundle，不需要手动移走测试目录。
|
||
|
||
### 主页“七日测试”白字入口
|
||
|
||
仅微信开发版或体验版、且 `Utils.testHttpip` 与 `Utils.httpip` 为不同服务器源时加载显示。正式版、网页环境、空地址及同源地址均不开放。地址是否同源以当前 Utils 配置为准；即使配置独立测试服，已暂停的挂载也不会自动恢复。
|
||
|
||
点击主页右上方白色“七日测试”打开面板：
|
||
|
||
测试预制体只保存内置 UI 组件，不挂 `SevenDayTest` 脚本引用。宿主在分包加载后通过 `cc.js.getClassByName("SevenDayTest")` 取得构造函数并挂载，初始化后才显示。不要重新添加旧 UUID 的脚本组件；失效引用在构建后可能变成空组件，导致 `getComponent` 报 `Cannot read property 'constructor' of null`。
|
||
|
||
- `查询接口`：使用当前登录 UID 查询 `signInActivityInfo`，显示实际请求地址、响应 code、所有业务使用字段、七天奖励明细、已弹日期和当前奖励防重状态。不会显示 token，不自动领取；查询本身可能影响后端记录。
|
||
- `清本地领取`：仅删除当前 UID、当前活动 ID 和 startAt 对应的本地领取成功记录，保留其他账号、活动和轮次。
|
||
- `清自动弹窗`：仅删除当前 UID、当前活动的自动弹窗日期记录。
|
||
- `重查并尝试弹出`：关闭测试面板，重新走主页查询和自动弹窗条件，不绕过后端领取资格。
|
||
- `关闭`：收起面板，保留白字入口。
|
||
|
||
清理前必须取得当前账号、当前地址下的有效活动快照。活动加载、展示或查询期间禁止清理；账号或地址改变后必须重新查询。清缓存不修改服务器领取进度、不回滚已到账资产，重新领取可能再次增加资产。测试 UI 持有 Bundle 期间不会因活动弹窗关闭而卸载本包，退出主页时一并释放。
|
||
|
||
- 静态检查：用 Cocos Creator 2.4.15 打开 `assets/seven_day_gift/prefab/sevenDayGift.prefab`。
|
||
- 离线逻辑检查：运行下文 Node 测试，不请求后端或修改账号资产。
|
||
- 完整流程：从正常游戏登录进入 `HomeScene`，在确认服务器和账号后验证微信开发/体验环境。
|
||
|
||
主页宿主在 `CC_PREVIEW` 下跳过自动查询，因此直接预览主页不会自动弹出七日活动。静态打开预制体也不会运行完整领取流程。当前没有随项目提供的独立交互预览场景。
|
||
|
||
## 预制体检查
|
||
|
||
默认外观为第 1 天可领取，其余未领取。检查以下内容：
|
||
|
||
- 7 张卡片，道具及数量显示与维护文档的默认展示表一致。
|
||
- 面板共 85 个节点；默认未激活节点仅有七天的 `claimedOverlay` 和 `claimedBadge`。
|
||
- 无关闭按钮、提示文字、备用布局和数量文字兜底。
|
||
- “分钟”与数字可见高度一致；同一卡片的数量位于同一水平线。
|
||
- 数量已放大 15%；第七天爱心已放大 10% 并左移 6px。
|
||
- 各卡片仅保留实际奖励槽位和图片字位，数量或奖励项调整后检查容量。
|
||
|
||
这些规格用于面板。领取上浮特效使用独立脚本，不能用静态预制体检查代替特效验收。
|
||
|
||
## 离线自动化测试
|
||
|
||
需有 Node.js，且项目可解析 `typescript` 依赖（`package.json` 已声明）。在项目根目录执行：
|
||
|
||
```powershell
|
||
node --test tools/test-seven-day-prefab.cjs tools/test-seven-day-loading.cjs tools/test-seven-day-stamina.cjs tools/test-seven-day-debug.cjs
|
||
```
|
||
|
||
`npm test` 当前仍是占位命令，不用于七日活动测试。若提示找不到 `typescript`，先按项目依赖管理流程安装开发依赖。
|
||
|
||
| 测试文件 | 覆盖内容 |
|
||
| --- | --- |
|
||
| `tools/test-seven-day-prefab.cjs` | Prefab 引用、固定槽位、必要隐藏节点、默认布局刷新一致、七天状态、数量图片更新及无文字兜底 |
|
||
| `tools/test-seven-day-loading.cjs` | 新加载/缓存 Bundle 的依赖等待、依赖失败后重试、宿主销毁时忽略回调 |
|
||
| `tools/test-seven-day-stamina.cjs` | 不同体力状态下首次领取、倒计时刷新、成功领取记录防重 |
|
||
| `tools/test-seven-day-debug.cjs` | 测试服环境门禁、当前账号和活动缓存隔离、状态变化拦截、测试预制体引用 |
|
||
|
||
这些是使用模拟 Cocos 对象的逻辑测试，不覆盖真实引擎渲染、动画、网络到账或跨设备幂等。新增测试面板后完整执行 14 项测试，均通过。静态绘制预览已检查，但尚未完成 Cocos 实际运行或真机验收。
|
||
|
||
## 真实环境验证
|
||
|
||
当前 `Utils.testHttpip` 与 `httpip` 指向同一地址，开发版/体验版并不隔离到独立测试服。开始真实查询和领取前，确认项目实际配置及专用测试账号；不要将本地逻辑测试结果写成线上验证结果。
|
||
|
||
| 场景 | 应检查的结果 |
|
||
| --- | --- |
|
||
| 未达到触发条件 / 接口返回 `data:false` | 不加载展示七日活动 |
|
||
| 活动可见、当天可领、尚未弹出 | 经主页队列加载并展示；成功显示后才写当天已弹记录 |
|
||
| 加载失败 / 初始化失败 | 不写已弹记录；后续符合条件的查询可再次尝试 |
|
||
| 刚打开弹窗 | 不自动发奖，无关闭按钮 |
|
||
| 点击当天可领卡片 | 领取一次，完成后显示遮罩、印章及上浮效果 |
|
||
| 当天可领时点击外部 | 本次只领取，弹窗保留 |
|
||
| 领取完再次点击外部 | 关闭活动，释放活动资源，允许后续主页弹窗展示 |
|
||
| 点击非当天卡片或其他可见 UI | 不领取，也不按外部点击关闭 |
|
||
| 领取或效果播放期间连点 | 不重复领取或预约关闭 |
|
||
| 保存失败 | 当前弹窗可重试；核对已增加的资产是否在重试中重复累计 |
|
||
| 领取前后切到后台再回来 | 正在展示或加载时不重复查询、重复开窗 |
|
||
| 同账号同活动同自然日再进入主页 | 已成功展示过则不再次自动弹出；次日按新查询判断 |
|
||
| 第七天领取 | 猫正常图、体力和猫资产正确，本地状态标记完成 |
|
||
| 接口返回已完成或已过期 | 主页不自动展示；弹窗打开后跨过期时间需另行核对后端约定 |
|
||
|
||
金币、体力、普通道具和猫分别核对实际资产与接口结果，不能只看领取印章。重点检查“部分资产已增加、后续保存失败”的重试场景，当前实现没有完整回滚。
|
||
|
||
### 数量与布局异常
|
||
|
||
验证正常整数、旧字段 `amount`、空奖励数组，以及超出固定槽位/字位容量的数据。字位不足、小数或缺图时数量隐藏并输出警告，没有面板文字兜底；超出槽位的奖励不显示，但业务仍处理完整奖励列表。因此实际奖励配置变更必须先同步预制体。
|
||
|
||
### 透明区域点击
|
||
|
||
有命中数据的 SIMPLE Sprite 按 Alpha ≥ 16/255 判断。透明位置继续向下找可见 UI；没有可见 UI 才按外部点击处理。没有命中数据的图片、其他 Sprite 类型及文字使用节点矩形范围。
|
||
|
||
修改活动顶层贴图后执行：
|
||
|
||
```powershell
|
||
python tools/generate-seven-hit-masks.py
|
||
```
|
||
|
||
需要 Pillow。脚本当前扫描 `assets/seven_day_gift/texture/*.png` 和 `assets/UI/Cat/cat.png`，不递归扫描数字子目录。更新后让 Creator 重新导入；新增其他路径的命中图片需同步调整生成脚本。验收时同时检查弹窗缩放和卡片呼吸缩放状态。
|
||
|
||
### 上浮效果
|
||
|
||
`RewardClaimEffect` 临时创建图标和数量，不使用旧公共 RewardWindow。多奖励按来源位置从左到右排列到同一行，每项间隔 0.145 秒启动；两次弹到 1.25 倍后回正，按脚本时序停留，再用 0.6 秒上移 150px 并淡出。检查双奖励是否重叠、来源位置是否正确、全部结束后交互是否解锁。
|
||
|
||
## 构建与验收记录
|
||
|
||
修改脚本、图片或预制体后，保留 `.meta`，等待 Creator 导入并重新构建，再到微信开发者工具验证。记录构建版本、实际服务器地址、账号、日期及用例结果；发布前确认七天状态、失败重试、后台恢复、关闭释放及其他主页弹窗顺序均通过。
|
||
|
||
## 第七天小猫光效
|
||
|
||
小猫背后的 catGlow 已固化在预制体中，使用本包独立复制的 exture/catAnimation3.png，不引用扭蛋包资源。CatRewardGlow.anim 循环播放（视图刷新时显式确保启动，重复刷新不重播）：6 秒旋转一圈、2 秒明暗呼吸，金色，480×480，透明度 170～255。第七天包含猫奖励且尚未领取时显示，领取后隐藏；装饰节点不参与点击命中。编辑器可直接调整位置、尺寸、颜色和动画。此效果与领取后的上浮动画相互独立。
|