# catArr 服务器云函数设计

## 目标

在服务器端新增独立的 `catArr` 数据链路，用于保存玩家已经拥有的猫咪 ID。第一期仅实现登录初始化、读取和手动保存，不实现抽取逻辑。

## 数据约定

- `catArr` 保存为非负整数数组。
- 新用户的默认值为 `[1, 2, 3]`。
- 老用户没有 `catArr` 字段时，读取接口返回 `[1, 2, 3]`。
- 保存猫咪时不允许重复添加同一个 ID。
- `users` 和 `usersAd` 两个用户集合使用相同行为。

## 云函数改动

### login

在新用户写入数据库时增加：

```ts
catArr: user?.catArr || [1, 2, 3]
```

老用户登录时不覆盖已有的 `catArr`。

### setCatArr

新增独立的 `setCatArr.ts` 和 `setCatArr.yaml`，接口结构与 `setHeadArr` 保持一致：

- 根据 `gameName` 选择 `users` 或 `usersAd`。
- 根据 `uid` 查询用户。
- 按现有方式校验 token。
- `action: "read"` 返回 `{ catArr }`。
- `action: "save"` 将 `ctx.body.catNum` 转换为数字，仅接受非负整数，校验后去重追加并写回数据库。
- 不支持的 action 返回错误。

## 兼容与错误处理

- 用户不存在时返回明确错误，不访问空的用户数据。
- `catNum` 不是非负整数时拒绝保存。
- 重复保存已有猫咪 ID 时返回“已保存猫咪”，不重复写数据库。
- 老用户首次保存时，以 `[1, 2, 3]` 为基础追加，避免丢失默认猫咪。

## 验证

- 静态检查 `login` 的新用户数据包含默认 `catArr`。
- 验证读取缺少字段的老用户时返回 `[1, 2, 3]`。
- 验证保存新猫咪 ID 会追加并持久化。
- 验证重复 ID 和无效 ID 不会写入。
- 验证 `users` 与 `usersAd` 的集合路由不变。