# 汪圈小程序 - 功能缺陷核验与修复设计

> 核验日期：2026-06-20  
> 来源报告：`docs/功能缺陷审查报告.md`  
> 核验基线：当前工作区源码，重点核验 `src` 与 `cloudfunctions`，忽略 `dist` 构建产物  
> 目标：逐项确认报告中仍被标为缺陷/风险的条目是否真实存在，并为需要修改的条目形成可落地设计

## 1. 总体结论

报告中的“已修复确认”条目，当前代码整体能支撑报告结论；本次未发现需要重新打开的已修复项。消息页、发布页、附近页、聊天页的主要 v1 修复点均能在当前实现中找到对应逻辑。

报告中仍被标为遗留、新发现或系统性问题的条目共核验 35 项：

| 结论 | 数量 | 说明 |
|------|------|------|
| 成立 | 24 | 当前代码中确实存在对应行为或缺口 |
| 部分成立 | 5 | 现象存在，但报告描述、严重程度或根因需要修正 |
| 不成立 | 6 | 当前代码已解决或报告判断与实现不符 |

需要特别修正报告优先级：

- `nearbyPets` 云函数不按距离排序：不成立。当前 `cloudfunctions/nearbyPets/index.js` 会计算距离、筛选半径内位置，并按 `_dist` 升序排序。
- `messageList` 变量遮蔽：成立，但只是维护性风险，不应列为 P0。
- 聊天图片 `cloud://` 不显示：部分成立。服务层已经尝试解析 `cloud://` 为临时 URL；真实问题是解析失败后会丢失可重试的 fileId，页面只能显示“图片暂不可用”。
- 当前没有阻断级 P0 缺陷；建议从 P1 的数据一致性、分页、错误回滚开始修。

## 2. 已修复条目复核摘要

| 页面/模块 | 报告已修复项 | 本次复核 |
|-----------|--------------|----------|
| 广场页 | 分页、动态话题、广告随机、详情页、点赞竞态、搜索入口 | 代码中存在 `nextCursor`、`normalizeTopicOptions`、`createAdStartIndex`、`post-detail` 导航、`pendingLikeIds`/`pendingLikeOverrides`、搜索防抖 |
| 附近页 | 位置上报、尊重可见性、喜欢乐观更新、online 过滤 | 代码中存在 `updateLocation`、`nearbyVisible` 分支、`pendingLikeIds` 回滚、前后端 online 过滤 |
| 发布页 | 草稿恢复、字数上限、上传失败提示、关闭前保存草稿提示 | 代码中存在 `getDraft`/`restoreDraft`、`textLength <= 2000`、`UploadPostMediaError`、`handleClose` 草稿弹窗 |
| 消息页 | 已读等待、系统会话区分、搜索 activeUsers | 代码中 `openConversation` 会等待跳转/已读结果，系统消息不进聊天，搜索同时过滤在线汪友 |
| 聊天页 | 历史分页、智能轮询、发送失败不清空、发送状态、可靠滚动、图片/表情 | 代码中存在 `loadOlder`、3s/12s 轮询、成功后清空输入、`sending` 状态、`scrollIntoView`、图片和表情发送 |
| 我的动态 | 首次 onShow 重复加载 | `useRefreshOnShow` 会跳过首次 show |
| 跨页面 | 草稿系统、操作错误提示、`commentCreate` 类型 | 当前代码已接入草稿解析、常见操作 try/catch、`CloudFunctionName` 包含 `commentCreate` |

## 3. 逐项核验清单

| # | 报告条目 | 核验结论 | 是否需要修改 | 设计归属 |
|---|----------|----------|--------------|----------|
| 1 | 广场收藏功能入口缺失 | 成立。`Post`/云函数有收藏字段与能力，但 `PostCard` 无入口，`feed.service.ts` 也没有封装 `setPostFavorite` | 需要 | D1 |
| 2 | 广场 `loadFeed` 依赖 `debouncedKeyword` 导致频繁清空 | 部分成立。每次防抖关键词变化都会重载并清空列表；这是搜索行为的一部分，但会造成闪空体验 | 建议修改 | D4 |
| 3 | `PostCard` 移除更多按钮 | 成立。当前只剩点赞/评论，无举报、分享等入口 | 暂缓，需产品确认更多菜单内容 | D6 |
| 4 | 话题搜索与关键词不能同时生效 | 不成立。前端同时传 `topic` 和 `keyword`，云函数也会按 topic 查询后做关键词匹配 | 不修改，仅可优化提示文案 | D4 |
| 5 | 附近页 `nearbyVisible=null` 时显示默认上海与空列表 | 成立。偏好加载期间页面会渲染默认中心与空状态 | 需要 | D4 |
| 6 | 关闭附近可见不清理旧位置 | 不成立。`locationUpdate` 在 `visible=false` 时会写入 `location:null`、`geo:null`、`visible:false`，不会被附近查询命中 | 不修改 | - |
| 7 | `useUploadMedia` 暴露内部 `setMedia` | 成立。发布页直接用 setter 恢复草稿 | 建议小改 | D4 |
| 8 | 草稿恢复后宠物默认选中逻辑冲突 | 部分成立。当前逻辑会把“草稿无 petId”解释为“不关联宠物”，但无法区分历史缺字段与用户主动不关联 | 需要明确语义后修改 | D4 |
| 9 | 聊天图片 `cloud://` 不显示 | 部分成立。正常路径会解析为临时 URL；解析失败时会丢失 fileId，无法重试 | 需要 | D3 |
| 10 | `loadLatest` 提前返回不清 `loadingInitial` | 不成立。`return` 位于 `try` 内，`finally` 仍会执行 | 不修改 | - |
| 11 | 个人页偏好开关无失败回滚 | 成立。`changePreference` 先改 UI，`await updateProfile` 无 catch | 需要 | D1 |
| 12 | `useSession` 与个人页重复 `ensureLogin` | 成立但影响很低。store 有 inflight 去重，不会造成重复请求 | 暂不修改，可作为结构清理 | D6 |
| 13 | 资料编辑 `type='nickname'` 仅真机生效 | 成立但属于微信平台限制 | 不按缺陷修，可补充提示 | D6 |
| 14 | `avatarUrl` 与 `avatarKey` 共存冲突 | 不成立。当前是图片优先、渐变头像兜底；`getProfile` 已解析 cloud URL | 不修改 | - |
| 15 | 资料编辑页无未保存离开提示 | 成立。关闭按钮直接 `navigateBack` | 需要 | D4 |
| 16 | 宠物数量无上限 | 部分成立。当前确实无限制，但是否是缺陷取决于产品策略 | 需要产品确定上限后修改 | D6 |
| 17 | 宠物照片交互暗示必填 | 不成立。当前无必填标识，校验也只要求名字和品种 | 不修改，可加“可选”文案 | - |
| 18 | 联系人互关后 `isFriend` 未即时更新 | 成立。`toggleFollow` 返回 `mutual`，页面未使用 | 需要 | D1 |
| 19 | 联系人“发现”搜索需手动提交 | 成立。`onInput` 只更新本地关键词，只有 `onConfirm` 请求 | 建议修改 | D1 |
| 20 | 点击用户只能发起聊天，无个人主页 | 成立。当前没有用户主页页面 | 中期功能 | D6 |
| 21 | 我的动态点赞无错误回滚 | 成立。`likePost` 无 try/catch | 需要 | D1 |
| 22 | 我的动态无分页，云函数 `limit(50)` | 成立。`userPosts` 无 cursor，前端一次加载 | 需要 | D2 |
| 23 | 我的动态点赞事件导致重复 setPosts | 成立但影响低。服务成功会广播，页面本地也已设置 | 可随点赞回滚一起收敛 | D1 |
| 24 | 帖子详情评论缺少分页 | 成立。`postDetail` 一次最多 200 条评论 | 需要 | D2 |
| 25 | 帖子详情点赞闭包竞态 | 成立。回滚用当前渲染闭包中的 `post` | 需要 | D1 |
| 26 | 发送评论后作者硬编码“我” | 成立。乐观评论未使用当前用户资料 | 需要 | D1 |
| 27 | 帖子详情加载失败也设 `commentsLoaded=true` | 成立。`load` 无 catch，失败后会显示空评论 | 需要 | D4 |
| 28 | 全局登录态守卫缺失 | 成立。`logout` 是本地标记，非 profile 页面未统一拦截 | 需要设计为轻量会话门禁 | D5 |
| 29 | `StatsRow` 计数可能不同步 | 部分成立。`profileGet` 已实时计算，但 follow/favorite 等操作后没有统一标记 profile 失效 | 需要 | D5 |
| 30 | `cloud-file.ts` 临时 URL 缓存永不过期 | 成立 | 需要 | D5 |
| 31 | `dataBus.ts` `postCache` 永不清除 | 成立 | 需要 | D5 |
| 32 | `messageList` 中 `openid` 回调变量遮蔽 | 成立，但只是可维护性问题 | 顺手修 | D6 |
| 33 | `messageThread` 每次轮询都写已读 | 成立。云函数每次取线程都会 update 会话已读 | 需要 | D3 |
| 34 | `nearbyPets` 不按距离排序 | 不成立。当前会按距离排序 | 不修改 | - |
| 35 | 消息通知/推送未接入 | 成立，但这是新功能，不是当前消息列表逻辑缺陷 | 长期迭代 | D6 |

## 4. 修复设计

### D1. 互动状态一致性与回滚

目标：统一点赞、收藏、关注、偏好开关、评论乐观更新的失败回滚与跨页面同步，优先解决用户可感知的数据错乱。

涉及文件：

- `src/services/feed.service.ts`
- `src/services/social.service.ts`
- `src/pages/my-posts/index.tsx`
- `src/pages/post-detail/index.tsx`
- `src/pages/profile/index.tsx`
- `src/pages/contacts/index.tsx`
- `src/features/feed/components/PostCard/index.tsx`
- `cloudfunctions/postFavorite/index.js`

设计：

1. 收藏能力补齐：
   - 在 `feed.service.ts` 新增 `setPostFavorite(postId, favorited)`，调用 `postFavorite` 云函数。
   - `postFavorite` 云函数补齐缺集合兜底，避免新库第一次收藏失败。
   - `PostCard` 增加收藏按钮与数量展示，使用 `post.favoritedByMe` 和 `counts.favorites`。
   - 广场、我的动态、帖子详情统一实现乐观收藏、失败回滚、成功后写入服务端返回值。
   - 新增收藏同步事件或复用 dataBus 扩展，例如 `emitPostFavorite({ postId, favorited, favorites })`。

2. 我的动态点赞：
   - 引入 `postsRef` 和 `pendingLikeIds`，按广场页模式保存操作前快照。
   - `setPostLike` 失败时恢复 `likedByMe` 与 `counts.likes`。
   - `onPostLike` 监听中先比较目标 post 当前值，相同则返回原数组，减少重复 re-render。

3. 帖子详情点赞：
   - 新增 `postRef` 保存最新 post，`likePost` 以 ref 为准，不用渲染闭包中的 `post`。
   - 加 `pendingLikeIds` 防止同一帖子连续点击造成并发请求。
   - 失败时回滚到请求开始时的 snapshot。

4. 评论乐观作者：
   - `PostDetailPage` 使用 `useSession()` 获取当前用户。
   - 乐观评论 author 使用 `user._id`、`user.nickname`、`user.avatarKey`、`user.avatarUrl`。
   - `commentCreate` 可在后续返回完整 comment；短期先保持 `{ commentId, comments }` 返回结构不变。

5. 联系人关注：
   - `onFollow` 使用 `toggleFollow` 返回的 `following` 与 `mutual` 回写 `isFollowing`、`isFriend`。
   - 失败回滚到完整旧 user snapshot，而不是只反转 `isFollowing`。
   - `social.service.toggleFollow` 成功后调用 `markStale('profile')`，让资料页统计在返回时刷新。

6. 偏好开关：
   - `changePreference` 保存 previous user。
   - 乐观更新后 `try/catch` 调用 `updateProfile`；失败恢复 previous user 并 toast。
   - `updateProfile` 的 `markStale('profile')` 建议移动到云函数成功后，避免失败也标记新鲜/脏状态混乱。

验收：

- 断网或云函数失败时，点赞/收藏/关注/偏好开关都能回滚 UI。
- 互关后联系人页立即显示“汪友”。
- 新评论展示当前用户昵称和头像，不再硬编码“我”。
- 同一帖子在广场、我的动态、详情页的点赞/收藏状态保持一致。

### D2. 列表与评论分页

目标：移除 50/200 条硬上限，保证长列表可继续加载。

涉及文件：

- `cloudfunctions/userPosts/index.js`
- `cloudfunctions/postDetail/index.js`
- `src/services/feed.service.ts`
- `src/pages/my-posts/index.tsx`
- `src/pages/post-detail/index.tsx`
- `src/types/cloud.ts`

设计：

1. `userPosts` 分页：
   - 云函数入参新增 `cursor?: string`、`pageSize?: number`。
   - 按 `createdAt desc` 查询 `pageSize + 1` 条，cursor 使用上一页最后一条 `createdAt`。
   - 返回 `{ list, nextCursor }`。
   - `getUserPosts` 改为返回 `CursorResponse<Post>`，兼容 `authorId`。
   - `MyPostsPage` 增加 `nextCursor`、`loadingMore`、`loadMore`，在滚动到底部加载。

2. 评论分页：
   - `postDetail` 入参新增 `commentCursor?: string`、`commentPageSize?: number`。
   - 评论按 `createdAt asc` 返回，初始取最早一页；下一页使用 `createdAt > commentCursor`。
   - 返回 `{ post, comments, commentsNextCursor }`。
   - `PostDetailPage` 增加 `commentsNextCursor`、`loadingCommentsMore`、底部“加载更多评论”。
   - 为避免刷新帖子详情时重复替换图片，继续保留当前“只更新计数”的策略。

验收：

- 我的动态超过 50 条时可以继续加载。
- 帖子评论超过单页限制时可以继续加载下一页。
- 分页加载失败有 toast，当前列表不被清空。

### D3. 聊天图片可靠展示与已读写入控制

目标：图片临时 URL 解析失败后可重试；聊天轮询不再每次写数据库。

涉及文件：

- `src/services/message.service.ts`
- `src/pages/chat/index.tsx`
- `src/types/domain.ts`
- `cloudfunctions/messageThread/index.js`

设计：

1. 图片消息数据结构：
   - `ChatMessage` 增加可选字段 `fileId?: string`、`assetState?: 'ready' | 'unresolved'`。
   - `resolveThreadAssets` 解析图片时保留原始 `cloud://` 到 `fileId`，`content` 存临时 URL；解析失败时 `content=''` 且 `assetState='unresolved'`。
   - 页面渲染 unresolved 图片时展示占位和“重试”操作。
   - 重试时调用 `resolveCloudFileUrl(fileId)`，成功后只更新该条消息。

2. 已读写入控制：
   - `messageThread` 入参新增 `markRead?: boolean`，默认 `true` 以兼容旧调用。
   - 首次打开会话、用户主动刷新时传 `markRead:true`。
   - 静默轮询 `loadLatest({ silent:true })` 和加载历史传 `markRead:false`。
   - 云函数仅在 `markRead !== false` 且会话存在时执行已读 update。

验收：

- 图片临时 URL 获取失败后，页面不会永久丢失 cloud fileId。
- 静默轮询不再触发会话已读 update。
- 首次进入聊天仍会清除当前用户未读数。

### D4. 页面加载、搜索与离开保护

目标：减少空白闪烁，补齐错误状态与未保存提示。

涉及文件：

- `src/pages/plaza/index.tsx`
- `src/pages/nearby/index.tsx`
- `src/features/nearby/components/NearbySheet/index.tsx`
- `src/pages/post-detail/index.tsx`
- `src/pages/profile-edit/index.tsx`
- `src/hooks/useUploadMedia.ts`
- `src/pages/publish/index.tsx`

设计：

1. 广场搜索：
   - 搜索参数变化时保留旧列表，设置 `searching=true`，新结果回来后替换。
   - 或仅在用户按确认键时清空列表，防抖输入走静默刷新。
   - 搜索结果文案增加当前 topic，例如“在 #遛弯 中搜索...”，解决语义提示问题。

2. 附近偏好加载：
   - 增加 `preferenceLoading = nearbyVisible === null`。
   - 偏好未返回前，地图可显示默认中心，但列表区展示“正在读取附近设置”，不展示“附近暂时没有汪友”。
   - `NearbySheet` 接收 `loading` 或 `state`，区分 loading、disabled、empty 三种状态。

3. 帖子详情加载失败：
   - `load` 增加 catch，设置 `commentsError`。
   - 失败时展示“评论加载失败，点击重试”，不显示“还没有评论”。
   - `finally` 只负责关闭 loading，不吞掉错误状态。

4. 资料编辑未保存提示：
   - 加 `initialRef` 保存首次加载后的表单快照。
   - 关闭按钮走 `handleClose`：dirty 时弹窗确认放弃/继续编辑。
   - 保存成功后更新 dirty 基线或直接返回。

5. 上传媒体 hook：
   - `useUploadMedia` 对外暴露 `replaceMedia(next)`，发布页草稿恢复改用该方法。
   - 保留内部 `setMedia` 私有，后续上传状态不会被外部绕过。

6. 草稿宠物语义：
   - 新草稿保存时增加 `petSelectionExplicit: boolean` 或将 `petId` 扩展为 `string | null`。
   - `petId=null` 表示用户明确选择“不关联宠物”；`petId` 缺失表示历史草稿/未选择，可默认第一只宠物。
   - 对旧草稿做兼容：没有该字段时默认第一只宠物，除非后续产品明确要求保持“不关联”。

验收：

- 广场搜索输入时不出现明显空白闪烁。
- 附近页读取设置期间不显示错误的空列表语义。
- 评论加载失败有可见错误和重试。
- 编辑资料有未保存离开确认。
- 草稿恢复不会误把历史缺字段理解为用户主动不关联。

### D5. 会话门禁、统计失效与缓存淘汰

目标：统一“本地登出/资料未完成”的门禁语义，并控制长期运行内存增长。

涉及文件：

- `src/store/session.store.ts`
- `src/services/auth.service.ts`
- `src/services/social.service.ts`
- `src/services/feed.service.ts`
- `src/services/pet.service.ts`
- `src/store/dataBus.ts`
- `src/services/cloud-file.ts`
- `src/pages/home/index.tsx`

设计：

1. 轻量登录态守卫：
   - 新增 `useSessionGate({ requireCompleted?: boolean })` 或等价 helper。
   - 对发布、消息、联系人、附近等需要真实用户态的页面/操作，若 `isLoggedOut()` 或 `!user.profileCompleted`，引导到“我的”完成登录资料。
   - 广场可保持只读，但点赞、收藏、评论、关注等写操作必须先过 gate。
   - 由于微信 openid 是静默登录，本设计不把“未登录”理解为无 openid，而是“用户本地退出或资料未完成”。

2. 统计失效：
   - follow、favorite、post create/delete、pet save/delete 成功后统一 `markStale('profile')`。
   - 资料页返回时通过现有 `useTabRefresh('profile')` 获取实时 `profileGet` 统计。
   - 如后续新增联系人资源 key，可扩展 `ResourceKey` 为 `contacts`，用于关注列表自身失效。

3. 临时 URL 缓存：
   - `tempUrlCache` 从 `Map<string,string>` 改为 `Map<string,{ url:string; expiresAt:number; lastAccess:number }>`。
   - 默认 TTL 50 分钟，低于微信临时 URL 常见有效期。
   - 最大容量建议 500；超出时按 `lastAccess` 淘汰最旧项。
   - 每次 resolve 前执行轻量 prune。

4. 帖子 hand-off 缓存：
   - `postCache` 增加 TTL 10 分钟、最大容量 100。
   - `getCachedPost` 读取过期项时删除并返回 `undefined`。
   - `cachePost` 写入时执行容量淘汰。

验收：

- 本地退出后，写操作不会继续静默执行。
- 关注/收藏后回到资料页，统计能刷新。
- 长时间浏览大量帖子/图片后，缓存 Map 不会无界增长。

### D6. 中长期产品能力与低风险清理

这些条目成立或部分成立，但不建议混入第一批稳定性修复。

1. 更多菜单：
   - `PostCard` 预留 `onMore`。
   - 菜单项建议先做“分享”“复制内容/链接”“举报”。
   - 举报若上线，需要新增 `postReport` 云函数和审核字段，不只是前端按钮。

2. 用户个人主页：
   - 新增 `/pages/user-profile/index?userId=...`。
   - 复用 `profileGet({ userId })`、`userPosts({ authorId })`，只展示公开资料与公开动态。
   - 联系人列表头像/名称点击进主页，聊天按钮保留为独立操作。

3. 宠物数量上限：
   - 需要先确定产品上限，例如 6 或 10。
   - 前端 `PetShelf` 达上限隐藏/禁用“添加宠物”。
   - 后端 `petSave` 新增创建前 count 校验，防止绕过前端。

4. 消息推送：
   - 作为订阅消息能力单独立项。
   - 需要用户授权订阅模板、发送时机、频率限制、退订处理。

5. 低风险清理：
   - `messageList` 回调参数 `openid` 改名为 `memberOpenid`。
   - 个人页重复 `ensureLogin` 可在重构时简化，但当前无需优先。
   - `type='nickname'` 平台限制可在开发/非真机环境补充提示，不作为功能修复。

## 5. 推荐实施顺序

| 阶段 | 内容 | 原因 |
|------|------|------|
| P1 | D1 互动状态一致性、D2 我的动态分页、D3 聊天图片重试、D4 帖子详情错误状态 | 直接影响用户操作结果与内容可见性 |
| P2 | D2 评论分页、D4 广场/附近加载体验、资料编辑离开保护、D5 统计失效与会话门禁 | 提升长列表、返回刷新和基础流程可靠性 |
| P3 | D5 缓存淘汰、D6 更多菜单/用户主页/宠物上限/推送/清理项 | 风险较低或属于产品能力扩展 |

## 6. 开发校验建议

1. 每个云函数分页改动都保留旧入参兼容，避免旧包调用失败。
2. 点赞、收藏、关注、偏好开关需要分别模拟云函数失败，确认 UI 回滚。
3. 图片消息需要模拟 `getTempFileURL` 失败，确认 fileId 被保留且可重试。
4. 使用 `npm run typecheck` 验证类型改动。
5. 微信开发者工具中重点回归：广场搜索、附近首次进入、聊天轮询、我的动态滚动加载、帖子详情评论加载。