# 小程序福利接口与状态

更新日期：2026-09-18。以当前客户端实现为准。[返回活动总览](../README.md)

## 状态来源

| 数据 | 来源与保存位置 | 说明 |
| --- | --- | --- |
| miniProgramWelfare.favorite / desktop | 登录接口返回，保存在运行时 GM_INFO | boolean；true 为已领取，领取确认成功后本会话也更新 |
| 入口资格 | 本机 mini_program_benefits_eligibility_v1:<uid> | favorite_entry、desktop_entry 对应正数时间戳；按账号隔离 |
| 当前领取状态 | Bridge 的内存 state | 登录时重建；包含资格、领取、展示确认及待同步状态 |
| prop.welfareCredits | 本地道具缓存 | 按福利回执记录已加奖，避免重试再次增加道具 |
| mini_program_benefits_rewards_v1:<uid> | 请求串行队列标识 | 当前代码不把完整领取状态写入这个同名存储键 |

旧 Mock 数据不读取，也不迁移。清本地入口资格不改变服务器领取状态、道具数量或回执。完整运行时回执不跨登录/重启恢复。

## 接口流程

1. 登录提供 miniProgramWelfare: { favorite: boolean, desktop: boolean }。字段缺失或类型错误时，实际领取被拒绝并提示重新登录。
2. 客户端检查已过首关、已获得对应入口资格及道具基数有效。
3. Utils.POST("miniProgramWelfare", { uid, type })，type 为 favorite 或 desktop；Utils 自动附加 token，并按现有环境规则选址。
4. code === 1 后更新已领取标记，生成 welfare:<uid>:<type> 回执，设置 acknowledged=false、deliveryPending=true。
5. 本地 prop.welfareCredits 无此回执时，冻结、锤子、魔法棒各加 1（道具 ID 2001、2002、2003），写入道具缓存并校验回执已保存。
6. Utils.POST("userProp", { uid, action: "save", propType: 0, propData })。propData 为 JSON 字符串，包含 freeze、hammer、magic_wand 的当前总量，不是本次增加量。成功后 deliveryPending=false。
7. 播放活动奖励展示，玩家关闭展示后 acknowledged=true。两项已领取且无未确认回执时隐藏首页入口。

领取确认不直接视为服务端已经加道具。当前客户端固定发放数量，不解析福利接口返回的奖励清单。完整成功/重复领取响应样本未随当前项目文档保存，客户端只使用 code === 1 和失败时的 msg；服务端必须保证已消费的领取不能再次返回可重复发奖的成功确认。

## 查询与重试边界

- 没有单独的福利状态查询接口接入。白字面板恢复启用后显示本次登录及领奖后的内存快照，当前入口已暂停。
- 正常福利面板的 read 操作读取内存，并会重试尚未完成的道具上传；不是向服务器查询福利资格。
- 同账号请求串行。账号切换后拒绝旧请求结果；miniProgramWelfare 和 userProp 每个请求等待上限均为 5500 ms，迟到或重复回调不重复处理。
- 当前会话上传失败后重新打开福利可重试上传当前道具总量，已记录回执的奖励不重复增加。
- 福利确认与道具保存是两个独立请求。确认成功响应丢失、确认后退出、重新登录或缓存丢失，可能造成“已领取但漏发/未同步”；现有客户端不能保证跨重启补偿。
- userProp 是总量写入，不能保证多设备并发修改的原子性。可靠补发及跨设备一致性需要后端回执或原子发奖机制支持。

测试记录与发布状态统一见 [测试文档](mini-program-benefits-testing.md)，不在此重复维护测试数量。