Pet3/docs/03-云函数设计.md

03 · 云函数设计

约定：所有云函数用 wx-server-sdk，统一返回 { ok: true, data } 或 { ok: false, code, msg }。openid 一律从 cloud.getWXContext().OPENID 取，绝不信任客户端传入的 openid。

---

1. login — 登录 / 首次建用户

职责：拿 openid，若用户不存在则建档，返回用户信息 + 是否已有狗狗（决定跳建档还是首页）。

入参: {}
出参: {
  ok, data: {
    userInfo: { openid, nickname, avatar, walkCount, joinedAt },
    hasDog: Boolean   // false → 前端跳 0b 建档；true → 跳首页
  }
}

逻辑：users 查 _openid，无则插入默认用户；再 dogs count 判断 hasDog。

---

2. dogManage — 狗狗增 / 改 / 查

职责：建档、编辑、列表（建档与编辑复用，由 action 区分）。

入参: {
  action: 'create' | 'update' | 'list',
  dog?: { _id?, name, breed, sizeLevel?, gender, ageStage, ageText, weight, avatar }
}
出参: { ok, data: dog | dogs[] }

要点：

• 服务端校验 name、breed 非空。
• 由 breed 查表得到体型档位 sizeLevel；中华田园犬、串串、找不到的犬种必须由前端让用户手动选择 sizeLevel 后再提交。
• 由 sizeLevel 得到 baseStride，填了 weight 时计算最终 stride：baseStride * (1 + (weight - 档位标准体重) * 0.005)，修正幅度封顶 ±15%。
• create 时初始化 stats 全 0。
• update 校验该 dog 的 _openid == 调用者，防越权改他人狗。

---

3. walkSave — 保存遛狗（核心）

职责：写入一条 walks，事务式更新每只狗 stats，触发成就判定；并支持成果卡页回写选填字段。这是 V1 最重的云函数。

3.1 结束遛狗：action='finish'

入参: {
  action: 'finish',
  dogIds: [String],
  startAt, endAt, duration,
  distance?,
  pooped
}
出参: {
  ok, data: {
    walkId,
    dogStepsByDog,
    newAchievements: [{ key, name, desc }]  // 本次新解锁，成果卡展示
  }
}

执行步骤：

1. 校验 dogIds 均归属当前 openid；未建档任何狗时拒绝保存。
2. 计算 walkDate（按用户本地时区，前端传时区偏移或统一 +8）。
3. 插入 walks，source='realtime'、isManual=false、countsForRanking=true。
4. 获得定位授权时写入 distance，并按每只狗的 stride 在服务端计算 dogStepsByDog；未授权时 distance 与 dogStepsByDog 为 null，只保存时长。
5. 对每个 dogId：
   • totalWalks += 1，totalDistance += distance||0，totalSteps += dogStepsByDog[dogId]||0。
   • 连续天数：比较 lastWalkDate 与 walkDate——同日不变；昨日则 currentStreak += 1；更早则重置为 1。更新 lastWalkDate。
   • 用 db.command.inc() 做原子自增，避免并发覆盖。
6. users.walkCount += 1。
7. 调成就判定（见 achievementCheck），收集新解锁返回。

3.2 成果卡补充字段：action='attach'

入参: {
  action: 'attach',
  walkId,
  weather?, mood?, note?, photos?
}
出参: { ok, data: { walkId, newAchievements?: [{ key, name, desc }] } }

要点：

• weather/mood/note/photos 全部选填，用户跳过也不影响 finish 已保存的核心记录。
• 只允许回写当前 openid 自己的 walk。
• 若 weather='rainy'，可在 attach 后补触发「雨天战士」等场景成就，并返回新增成就给成果卡刷新。
• 旧记录回看不复用 attach；后续单次记录详情页若支持编辑，应单独定义记录编辑能力。

---

4. walkManual — 手动补记

职责：补记一次遛狗。规则与 walkSave 不同。

入参: { dogId, startAt, duration, distance? }
出参: { ok, data: { walkId, newAchievements?: [{ key, name, desc }] } }

关键差异（业务规则，必落地）：

• source='manual'、isManual=true、countsForRanking=false（不计排行榜，防刷量）。
• 可维持连续打卡：同样参与 currentStreak 计算（不断签）。
• 不触发「分享/成果卡」类成就，但可触发「连续」类成就。
• 列表展示带「补记」标识（前端按 isManual 渲染）。

---

5. getDogDetail — 狗狗主页聚合

职责：一次返回狗狗主页所需全部数据，减少往返。

入参: { dogId }
出参: {
  ok, data: {
    dog: {...},                  // 含 stats
    achievements: {              // 成就墙
      unlocked: [{key,name,unlockedAt}],
      total: 12
    },
    recentWalks: [walk, ...]     // 近期记录（取最近 5~10 条）
  }
}

---

6. getHistory — 历史 / 记录 Tab 聚合

职责：返回当前用户全部狗狗的遛狗记录列表，供历史页和记录 Tab 复用，减少前端跨集合拼装。

入参: { dogId?, page?, pageSize? }
出参: {
  ok, data: {
    list: [{ walk, dogNames, manualLabel }],
    hasMore: Boolean
  }
}

要点：

• 默认查当前 openid 下全部记录；传 dogId 时只查某只狗。
• 按 walkDate/startAt 倒序返回，可由前端按周或日期分组。
• 返回项带狗名、是否补记标识，避免列表层再多次请求 dogs。
• 只读，不写库。

---

7. 内部模块：achievementCheck（被 walkSave/walkManual 复用）

不是独立云函数，是云函数内共享的判定模块（也可做成被 cloud.callFunction 内部调用的函数）。

输入: dogId, 该狗最新 stats, 本次 walk（含 weather/时间）
流程:
  for 每个成就定义:
    if 已解锁(查 dog_achievements) → skip
    if 满足条件(基于 stats / walk):
      插入 dog_achievements
      收集进 newAchievements
返回: newAchievements[]

判定基于 连续 / 累计 / 场景，不基于「最多 / 最快」。

---

8. 云函数清单速查

云函数	触发时机	写库
login	App 启动	users
dogManage	建档/编辑/进首页	dogs
walkSave	结束遛狗、成果卡补充字段回写	walks, dogs, users, dog_achievements
walkManual	历史页补记保存	walks, dogs, dog_achievements
getDogDetail	进狗狗主页	只读
getHistory	进历史页 / 记录 Tab	只读（跨全部狗狗，附狗名）

后续若上排行榜（pending），新增定时触发云函数做聚合，按 countsForRanking=true 统计。