# 小程序福利活动

更新日期：2026-09-18。按当前工作区源码核对；这是文档总入口，不代表已上传发布。

## 文档导航

| 文档 | 用途 |
| --- | --- |
| [测试与验收](docs/mini-program-benefits-testing.md) | 白字面板操作、字段解释、回归步骤 |
| [接口与状态](docs/mini-program-welfare-backend.md) | 登录、领取、资产同步、失败重试限制 |
| [预制体维护](docs/mini-program-benefits-prefabs.md) | 编辑入口、节点约束、加载释放 |
| [0914 美术记录](docs/mini-program-benefits-art-0914.md) | 素材来源历史，不作为当前功能规范 |

## 功能规则

| 任务 | 微信入口 scene | 内部任务 ID | 服务端 type | 每项奖励 |
| --- | --- | --- | --- | --- |
| 我的小游戏/小程序入口 | 1104 | favorite_entry | favorite | 冻结、锤子、魔法棒各 1 |
| 桌面入口 | 1023 | desktop_entry | desktop | 冻结、锤子、魔法棒各 1 |

入口资格由客户端观察微信进入参数记录；“已添加”本身不授予资格。优先使用 getEnterOptionsSync 的有效 scene。登录前暂存资格，登录后按账号保存；普通退出重登保留，清缓存或换设备可能丢失。

首页仅在微信小游戏平台启用，GM_INFO.level >= 1 时展示正常福利入口。是否已领取以登录返回 miniProgramWelfare 为准，成功领取后更新内存。可领取或有待确认奖励时亮红点；两项都领取且没有待确认回执时隐藏入口。不会自动打开福利弹窗。

领奖先由 miniProgramWelfare 接口确认，再本地加道具并通过 userProp 上传总量。当前会话重试避免重复加奖；跨重启补偿限制见接口文档。

## 当前代码归属

| 目录/文件 | 职责 |
| --- | --- |
| script/MiniProgramBenefitsPanel.ts | 福利页面、引导、领取展示 |
| script/MiniProgramBenefitsReward.ts | 领取确认、加道具、总量上传 |
| prefab/、texture/、icons/ | 活动预制体、美术和图标 |
| test/BenefitsRuntimeTest.ts、对应 prefab | 首页白字测试面板 |
| assets/Script/module/MiniProgramBenefitsBridge.ts | 主包桥接：入口、登录、红点、分包生命周期 |
| assets/resources/texture/mini-program-benefits-entry.png | 原有 resources 分包中的首页入口图 |

test/ 是普通目录，与活动共用 mini_program_benefits 分包；没有独立测试分包注册。独立预览场景、Mock 适配器和旧重置按钮已移除。自动化测试在 tools/，不作为游戏资源打包。

主要接入点为 GameManager.ts（启动/回前台、登录）、JiaZai.ts（挂载、卸载、布局补位）及 HomeScene.fire 的 Load/Top/chengxu。2026-09-18 工作区仍存在七日 Host、项目配置和四个 meta 删除等未提交变化；旧文档“已恢复”的描述不再适用，发布前需单独核对，不能全部归为福利改动。

## 加载与发布状态

正式环境点击福利入口时加载活动包，窗口销毁后释放。当前白字测试入口已暂停：Bridge.attach 中 mountTestPanel 调用已注释，BenefitsRuntimeTest.prefab 的 entry 未激活，各环境均不自动显示。测试代码仍保留在包内；恢复这两处后才按独立测试服门禁加载，并在测试面板与福利窗口都不再使用时释放共享包。

用户已反馈清理前的功能测试无问题。之后进行了移除 Mock、合并测试目录和共享资源释放调整，尚未重新构建、上传或完成这一版的真机回归。

2026-09-17 历史自动化记录：福利相关 41 项、新手礼包 37 项，共 78 项通过。测试使用隔离桩，不访问真实服务器；后续以实际运行输出为准。运行方式见测试文档。

2026-09-18 提交前复验：使用本机已安装的 TypeScript，福利客户端、奖励、新手礼包三个测试文件共 80 项通过；七日测试面板另 5 项通过。此前依赖缺失已通过指定模块路径解决。测试为本地隔离验证，尚不代表真机或线上验收完成。