# 小程序福利领取状态

只记录领取状态，不验证添加操作，不发放奖励。两项独立，每个账号永久各领一次，不支持重置。

## 用户字段与登录

`users.miniProgramWelfare` 为一个对象字段，登录成功时随 `data` 返回：

```json
{
  "miniProgramWelfare": {
    "favorite": false,
    "desktop": false
  }
}
```

- `favorite`：添加到我的小程序奖励；`desktop`：添加到桌面奖励。
- `false` 未领取，`true` 已领取。
- 新用户初始化两项为 `false`。老用户缺少字段或某一项时，返回 `false`；首次上报时按项写入，无需批量迁移。
- 登录只补全返回结构，不回写整个对象，以免覆盖并发上报。

## 记录接口

`POST /miniProgramWelfare`

```json
{
  "uid": "登录返回的data._id",
  "token": "登录返回的data.token",
  "type": "favorite"
}
```

`uid`、`token` 必须为非空字符串，`type` 仅允许 `favorite` 或 `desktop`。接口只处理 `users`，不支持 `gameName: "iaa"`。请求不接受客户端提供的整份领取状态，不提供撤销或重置操作。

首次记录成功示例：

```json
{
  "code": 1,
  "data": {
    "miniProgramWelfare": { "favorite": true, "desktop": false },
    "changed": true
  },
  "msg": "领取状态记录成功"
}
```

重复上报仍返回 `code: 1`，但 `data.changed: false`，并返回两项当前状态。使用带 token 和未领取条件的单项原子更新；同项并发请求只有一次 `changed: true`，不同项不会互相覆盖。

参数错误、用户不存在、token 不匹配或数据库更新失败时返回 `code: 0`、`data: null` 和错误 `msg`；数据库异常也可能表现为请求失败。请求失败可重试；若前次写入已完成但响应丢失，重试返回 `changed: false`。

前端在确认需要记录已领取时调用，点击「查看」不调用本接口。`changed` 仅表示本次是否改变领取标记，不代表奖励发放结果；奖励处理和断网恢复由前端负责。

## 发布与验证

发布新云函数 `miniProgramWelfare`（仅 POST）及更新后的 `login`。不需要新集合或索引。

本地回归：

```powershell
node --test laf-cloud/tests/mini-program-welfare.test.mjs laf-cloud/tests/login-wucai-state.test.mjs laf-cloud/tests/login-cat-arr.test.mjs
```

实现使用 Laf 的条件更新接口，参见 [Laf 更新数据文档](https://doc.laf.run/zh/cloud-database/database-ql/update.html)。