MatchMaster/docs/superpowers/specs/2026-07-24-cat-arr-design.md

catArr 服务器云函数设计

目标

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

数据约定

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

云函数改动

login

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

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 的集合路由不变。