@aochuang/client-sdk 1.0.379 → 1.0.381-dev-1

package/components/wechat-chat-control/location/location.vue

@@ -1,6 +1,6 @@
 <template>
   <div class="sdk-chat-control-location" :class="['sdk-chat-control-location--' + type]">
-    <template v-if="type === 'default'">
+    <template v-if="type === 'default' || type === 'thumb'">
       <div class="sdk-chat-control-location__main">
         <div class="sdk-chat-control-location__head">
           <h4 class="sdk-chat-control-location__title">{{address}}</h4>
@@ -46,7 +46,7 @@ export default {
       type: String,
       default: 'default',
       validator (value) {
-        return ['quote', 'default'].includes(value)
+        return ['quote', 'default', 'thumb'].includes(value)
       }
     },
     /**
@@ -89,7 +89,8 @@ export default {
 }
 </script>
 <style lang="less">
-.sdk-chat-control-location--default {
+.sdk-chat-control-location--default,
+.sdk-chat-control-location--thumb {
   .sdk-chat-control-location__body{
     line-height: 0;
   }
@@ -149,6 +150,13 @@ export default {
     z-index: 3;
   }
 }
+.sdk-chat-control-location--thumb {
+  display: inline-block;
+  overflow: hidden;
+  background-color: #fff;
+  border: 1px solid #eee;
+  border-radius: 4px;
+}
 .sdk-chat-control-location__body{
   overflow: hidden;
 }

package/docs//346/266/210/346/201/257/345/273/266/350/277/237/344/270/216/346/234/252/350/257/273/345/274/202/345/270/270/346/216/222/346/237/245//345/210/206/346/236/220/344/270/216/344/274/230/345/214/226/346/226/271/346/241/210.md

@@ -0,0 +1,303 @@
+# 消息延迟与未读异常：分析与优化方案
+
+## 1. 分析范围与结论
+
+本文基于以下当前工作区代码复核：
+
+- `client-sdk`：分支 `master-补充日志`，HEAD `0d5e859`，包版本 `1.0.381`，含未提交的修复和日志改动。
+- 极速客服端 `JavaMain-combine`：依赖文件仍锁定 `@aochuang/client-sdk@1.0.378`，本机 `node_modules` 为 `1.0.381`。
+- 后端 `workphone-java`：确认新消息采用“先推送客户端，finally 中再异步入库”的顺序。
+
+针对客户反馈：
+
+1. “有些消息刷新网页才出现”：当前修改已经修复两条可直接造成该现象的确定路径，即断线补拉水位提前推进和 Socket 在特定失败状态下停止重连。剩余代码中仍有“会话补建轮询耗尽后无持续补偿”和“乱序消息不触发缓存/会话事件”两条可达路径。
+2. “显示有消息，点进去没有，过一会又出现未读”：最强的剩余前端证据链是首次进入会话时 `reloadMessageData` 先清内存，历史接口又处于未入库窗口，同时本地补偿缓存的首次读取和写入发生竞态。三者必须叠加；不能把“先推后存”或 `reload` 单独认定为必现缺陷。
+
+建议先修复两个前端闭环问题：进入会话改为按当前会话原子替换，并让本地补偿合并等待同会话已排队的缓存写入；会话轮询超时后进入低频持续补建。乱序消息事件拆分随后处理。ACK、初始化门禁和已读时机先依赖现有日志确认线上是否命中，再决定是否调整协议或交互语义。
+
+## 2. 已确认且当前代码已修复的问题
+
+### 2.1 断线补拉提前推进水位
+
+原路径中 `loadLossMessageData()` 没有返回异步请求 Promise，`onSocketOpen` 的等待会提前完成，并在请求成功前把水位推进到当前时间。补拉失败时，更早的消息可能永久越过下一次补拉区间，只能在页面刷新后的全量初始化中恢复。
+
+当前修改：
+
+- `client-chat-message.js:586-610` 返回真实 Promise，并统计返回、插入、重复数量。
+- `client-chat.js:1139-1170` 分好友/群等待补拉；只在对应补拉成功后推进水位，失败保留旧水位。
+
+这是明确缺陷，修改方向正确。主要影响是重连后的未读校准会等待补拉任务结束；单类补拉失败时该类会在下一次连接继续从旧水位补拉。
+
+### 2.2 Socket 特定失败状态下停死
+
+原路径中 Connecting 阶段发生 close 时，连接 Promise 可能无法正确结束并启动下一轮；原生连接成功但 signin 失败时，状态也可能停住。此后实时消息不再进入，刷新重建实例后才恢复。
+
+当前修改位于 `services/socket/socket.js`：
+
+- close 会结束当前连接等待，并对非手动关闭进入受控重连。
+- signin 失败把状态置为 Error，并调用已有 `reconnect()`。
+- `_isReconnecting` 继续限制并发重连。
+
+影响范围仅为异常连接恢复路径；手动关闭仍不重连，历史构造方式和正常消息路径不变。
+
+## 3. 仍存在的高优先级问题
+
+### 3.1 进入会话预清空与本地补偿首次读写竞态
+
+证据等级：**确定存在可达竞态；是否为客户本次样本原因需日志关联。**
+
+#### 原因与证据链
+
+1. 后端先推送再异步入库：`NewMessage1007MessageHandler.java:178-197`（群消息）及 `327-360`（好友消息）。因此 Socket 已收到而历史接口暂时为空是设计允许的窗口。
+2. SDK 收到消息后会先插入内存：`client-chat-message.js:111-140`。
+3. 客服端仅监听 `add-message` 后异步调用 `cacheMessage`，调用方不等待：`src/entries/chat/services/client-chat/index.js:484-515`。
+4. 首次进入好友/群详情分别调用 `reloadMessageData`：`chat-panel-friend.vue:943-959`、`chat-panel-room.vue:1165-1180`。
+5. `reloadMessageData` 在请求前执行 `clearMessage()`：`client-chat-message.js:423-425`；而 `clearMessage()` 遍历整个实例的 `messageMap`：`316-320`，不是只清当前会话。
+6. 本地补偿的 `cacheMessage` 和 `mergeMessages` 都会调用 `getMemoryCacheItems`。首次访问同一个 key 时共享 `loadPromiseMap[cacheKey]`：`messageLocalCompensateService.js:232-257`。
+7. 若缓存写入和历史合并同时等待同一份 IndexedDB 旧快照，写入 continuation 会在随后更新 `cacheMap`（`365-395`），但合并 continuation 已持有旧的 `originItems`（`446-454`），本次合并可能仍得到 0 条。
+
+完整可达顺序为：Socket 消息已进入内存 -> 缓存写任务刚开始 -> 用户立即进入会话 -> reload 清掉内存 -> 历史接口因尚未入库返回空 -> merge 读取到写入前快照 -> 页面暂时为空。后端落库或本地缓存完成后，再次加载会恢复。
+
+这也回答了“后端入库后是否还会推送”的疑问：当前 1007 路径展示的是入站时先推一次、随后异步入库，没有证据表明“入库完成后必定再推同一条消息”。正常情况下依靠内存和本地补偿即可，不应把二次推送当成恢复保证。
+
+#### 推荐方案
+
+第一步采用最小兼容方案：
+
+- `mergeMessages` 在读取缓存前，等待该 `cacheKey` 当前已经排队的 `queueMap[cacheKey]` 任务完成；需避免 merge 自身加入同一队列后自等造成死锁。
+- `cacheMessage` 在异步读取 IndexedDB 前先登记会话级 pending message；merge 同时合并 pending memory，缓存写完再清理 pending。
+- 已增加 `chat_reload_result` 聚合日志，记录清理前后内存数量、前后最后消息、加载数量、请求边界和耗时；结合 `message_merge_result` 的 API 数及本地补入数判断，不记录正文。
+
+第二步解决 reload 语义：
+
+- 先请求和合并到临时结果，成功后只对当前 target 原子替换。
+- 请求失败时保留当前 Socket 内存消息。
+- 接口返回空时仍保留当前 target 中、且服务端尚未覆盖的实时消息。
+- 不再清空好友或群实例中的所有会话消息。
+
+#### 影响点
+
+- `reloadMessageData` 从“清整个实例后重载”改成“按 target 原子替换”，需要复核好友、群、筛选和上下文共 6 个调用点。
+- 原子替换要保护临时发送消息、发送状态轮询、Vue 响应式对象引用和分页边界。
+- 不能只做“取消 clear”而一直追加，否则旧查询窗口之外的数据可能残留。
+- 同一条 Socket/接口消息仍需按稳定 ID 去重。
+- 必须增加竞态测试：Socket 到达、历史为空、IndexedDB 首读未完成、缓存写排队、快速切换会话。
+
+### 3.2 会话补建轮询 60 秒耗尽后无持续补偿
+
+证据等级：**确定存在失败后的断点；后端是否曾超过 60 秒需线上日志确认。**
+
+#### 原因与证据链
+
+- 新消息找不到本地会话时，好友和群消息分别调用 `getSession`：`client-chat.js:440-473`、`565-610`。
+- `getSession` 复用同会话轮询并聚合消息回调：`client-chat-session.js:245-344`。
+- 默认每 5 秒请求，最长 60 秒：`utils/util.js:35-129`。
+- 失败后 `finally` 删除 `pollRequestMap[sessionId]`，调用方 `.catch(() => {})` 吞掉失败；当前批次结束后没有定时重试。
+
+因此 Socket 消息可以已经存在于 `messageMap`，但会话列表没有入口。若 60 秒内后端会话始终不可查，后续只有新消息、显式刷新或页面刷新才会重新触发加载，符合“刷新后才出现”的表象。
+
+#### 推荐方案
+
+- 增加 `pendingSessionMap`，轮询超时后每 30 秒低频重试，设置总时长上限，例如 10 分钟。
+- Socket 重连成功、页面重新可见、会话列表主动刷新时立即重试 pending 会话。
+- 同一会话多条消息聚合，成功后按 `messageId/lastMsgTime` 去重合并，确保未读只累计一次。
+- 若业务要求消息入口立即可见，可进一步创建 provisional session；后端正式会话出现后原子替换。
+
+#### 影响点
+
+- 低频重试会增加少量接口请求，必须按会话聚合并设置上限。
+- provisional session 缺少 mute、sticky、权限、协作和任务等完整字段，点击能力需降级或等待正式数据。
+- 正式会话替换时要保护列表排序、当前选中项和账号/会话未读，不能重复累加。
+- 删除、拉黑、群发等本就不应建立会话的消息不能进入 pending。
+
+### 3.3 乱序消息进入内存，但不触发缓存、会话和提醒事件
+
+证据等级：**代码行为确定；线上是否存在异常乱序或未来时间需日志确认。**
+
+#### 原因与证据链
+
+- `addMessage` 在判断 `isBeforeLastMessage` 后仍把消息写入 `messageData/messageMap`：`client-chat-message.js:124-140`。
+- 好友/群 `onAddMessageSuccess` 遇到乱序消息直接返回：`client-chat.js:430-432`、`554-555`。
+- `add-message` 只在非乱序消息时触发：`client-chat-message.js:164-169`。
+- 客服端本地补偿只监听 `add-message`：`src/entries/chat/services/client-chat/index.js:513-515`。
+- 最后消息时间和接收水位只允许增大：`client-chat-message.js:616-638`。若某条消息时间异常偏未来，后续正常消息可能连续被判定为旧消息。
+
+因此乱序消息在当前页面可能已存在于内存，但不会更新会话、不提醒、也不会写入本地补偿；一旦随后 reload 清内存，只能等待历史接口可查后恢复。
+
+#### 推荐方案
+
+- 新增内部 `message-accepted` 或 `message-cache` 事件：所有成功插入的普通入站消息都触发缓存。
+- 保留 `add-message` 作为“允许更新会话、未读和提醒”的事件，避免历史乱序消息产生声音或重复未读。
+- 对明显未来时间只记录异常，不让它无限抬高会话乱序基准；补拉水位优先考虑服务端接收时间或带容差的客户端消息时间。
+
+#### 影响点
+
+- 必须检查全部 `add-message` 监听者，不能简单放开现有条件，否则会产生旧消息提醒和未读重复。
+- 新缓存事件要继续排除临时发送、自动已读、删除、拉黑及不建会话消息，具体口径需与业务确认。
+- 未来时间容差必须与后端时间字段语义统一。
+
+## 4. 中优先级风险
+
+### 4.1 同步业务异常可能阻断 Socket ACK
+
+证据等级：**防护缺口确定；是否线上触发需日志确认。**
+
+`services/socket/socket.js:406-451` 在 ACK 前执行 JSON 解析、通用接收事件和具体 cmd 事件；任一同步异常都会跳过 `CommandResponse`。`client-chat-socket.js:79-109` 虽记录新消息业务异常，但随后重新抛出，仍会回到该路径。
+
+方案取决于协议：若 ACK 表示“帧已收到”，应在受保护的 `finally` 中 ACK，业务处理失败另记并触发补偿；若 ACK 表示“业务处理成功”，应返回失败 ACK，而不是无响应。还应保护 JSON 解析和 cmd 分发边界。
+
+影响是后端重试语义可能改变：过早成功 ACK 会失去依赖重推恢复业务失败的机会。修改前需确认服务端 ACK 定义，并测试 malformed frame、监听器异常和重复推送去重。
+
+### 4.2 初始化失败仍渲染 Chat 并连接 Socket
+
+证据等级：**代码路径确定；是否造成客户样本需日志确认。**
+
+`root.vue:99-147` 捕获用户或配置初始化失败后，仍在 `finally` 设置 `ready = true`。Chat 创建后，移动端和 PC 分别在 `chat.vue:81-90`、`chat-pc.vue:415-417` 直接连接 Socket。用户身份、token 或补偿库名称未准备好时，页面仍可能进入可操作状态。
+
+建议把用户身份、token、补偿 DB 初始化定义为关键门禁；失败时显示可重试状态，不创建 Chat。配置类初始化可按业务允许降级。Socket 连接前校验 accountId、token 和 dbReady。
+
+影响是初始化失败时用户会看到错误/重试页，而不是当前的空页面；需要防止重复初始化和重复建连，并明确哪些配置允许降级。
+
+### 4.3 标记已读早于首屏消息加载完成
+
+证据等级：**时序确定，但不能单独解释“稍后又未读”。**
+
+`setCurrentSession` 立即触发回调：`client-chat-session-manage.js:46-64`；`client-chat.js:405-413` 随即调用 `setSessionRead`。服务端成功后才本地清零：`client-chat-session.js:938-950`，因此“点击即先本地清零”并不成立。详情首屏 reload 是另一条异步链，用户尚未看到消息时服务端标记已读可能已经成功。
+
+后端 `Conversation.markAsRead` 同时写 `unreadMsgCount=0` 和 `markAsReadTime`：`Conversation.java:123-127`；会话 upsert 会结合消息时间更新。因此“稍后又未读”还必须结合新消息时间、`markAsReadTime` 和会话 upsert 才能判断，不能只归因于点击。
+
+建议在首屏历史和本地补偿完成、至少完成首次渲染后再标记已读。更稳妥的协议是提交用户实际看到的最大 `messageId/messageTime`，避免把加载期间新到的消息一并读掉。
+
+影响是未读徽标会多保留短时间；首屏加载失败时应维持未读。PC、H5、Pad 和页面可见性触发的自动已读需统一口径。
+
+## 5. 已排除的单点归因
+
+- **“后端先推后存，所以一定丢消息”不成立。** SDK 内存消息和本地补偿正常情况下会覆盖该窗口；问题需要叠加 reload 清空、补偿竞态或其他失败路径。
+- **“reload 一定丢消息”不成立。** 若历史接口已入库，或本地补偿已经写入并被 merge 读到，消息会正常恢复。
+- **“进入会话立刻在本地清零”不成立。** 当前代码等待服务端 `updateSessionRead` 成功后才本地清零。
+- **“getSession 没有轮询”不成立。** 已有 5 秒一次、最长 60 秒的轮询；缺口是耗尽后的持续补偿。
+- **“Socket 建连早于消息监听注册”暂无证据。** 当前 ClientChat 构造时先注册监听，Chat 组件创建后再 connect。
+
+## 6. 完整阶段计划与当前状态
+
+状态说明：`[x]` 已在当前工作区完成；`[ ]` 尚未实施；“仅日志”表示本次只增加诊断能力，没有改变业务行为。
+
+### 阶段 1：证据链复核与确定缺陷修复
+
+- [x] 复核前端、SDK、后端的新消息、会话、详情、已读和补拉链路。
+- [x] 确认后端好友和群消息均为先推送、后异步入库。
+- [x] 确认本地补偿、会话 60 秒轮询和 reload 的实际边界，排除不成立的单点归因。
+- [x] 修复断线补拉 Promise 未返回及水位提前推进。
+- [x] 修复 Socket Connecting close 和 signin 失败后不再重连。
+- [x] 完成 Socket 重连和断线补拉最小运行测试。
+
+### 阶段 2：前端诊断日志与日志交付
+
+- [x] 页面生命周期：boot、用户初始化、配置初始化、ready、pageshow/pagehide、visibilitychange。
+- [x] Socket 状态：连接代次、open、signin、close/error、重连计划。
+- [x] 新消息接收：消息 ID、目标、时间、同步处理成功/失败；正文截断，token 删除。
+- [x] 会话补建：轮询创建、请求/空响应/错误次数、最终成功或 60 秒失败。
+- [x] 本地补偿：缓存 `success/skipped/failed`、跳过原因、合并前 API 数、本地补入数和最终数。
+- [x] 进入会话：reload 清理前当前会话/全实例数量、清理数、加载数、最终数量、前后最后消息 ID/时间。
+- [x] 消息过滤：消息已入内存但未触发 `add-message` 时记录具体原因。
+- [x] 历史失败、已读请求、断线补拉水位和结果摘要。
+- [x] Socket、SDK、业务层复用唯一日志实例；SDK 未传实例时保留自行创建日志的兼容路径。
+- [x] 下载日志改为点击后直接生成 ZIP，包含微号、已加载会话、统一运行日志和网络日志。
+- [x] 日志实现归并到客服端 `src/entries/chat/utils/log.js`。
+- [ ] 后端推送、MQ、落库、会话 upsert 和 ACK 日志。本轮按要求只增加前端日志。
+
+### 阶段 3：第一批业务一致性优化（建议优先，尚未实施）
+
+- [ ] 本地补偿增加会话级 pending memory。
+- [ ] `mergeMessages` 等待同会话已经排队的缓存写入，消除首次 IndexedDB 旧快照竞态。
+- [ ] 增加 Socket 到达、历史为空、缓存首次读写并发的自动化测试。
+- [ ] 增加 `pendingSessionMap`，会话轮询 60 秒耗尽后低频持续补建。
+- [ ] Socket 重连成功、页面恢复可见、会话列表主动刷新时立即重试 pending 会话。
+
+这一阶段不改变 ACK 和已读协议，也不创建字段不完整的临时会话，兼容风险相对较低。
+
+### 阶段 4：消息列表一致性优化（尚未实施）
+
+- [ ] 将 reload 改为先加载和合并，成功后只原子替换当前 target。
+- [ ] reload 失败或服务端暂时为空时，保留未被远端覆盖的 Socket 内存消息。
+- [ ] 不再由进入一个会话清空好友或群实例中的全部会话消息。
+- [ ] 拆分“消息接受/缓存事件”和“会话未读/提醒事件”，让乱序有效消息仍进入补偿缓存。
+- [ ] 对明显未来的消息时间增加容差或隔离，防止持续抬高乱序基准。
+- [ ] 覆盖好友、群、筛选、上下文 6 个 reload 调用点的回归测试。
+
+### 阶段 5：协议与交互语义优化（需确认后实施）
+
+- [ ] 与后端确认 ACK 代表“帧已收到”还是“业务处理成功”，再决定 finally ACK 或失败 ACK。
+- [ ] 保护 JSON 解析和 cmd 分发边界，并测试异常帧、监听器异常及重复推送。
+- [ ] 将用户身份、token、补偿 DB 设为 Chat 渲染和 Socket 建连门禁。
+- [ ] 将已读调整为首屏历史和本地补偿完成后上报。
+- [ ] 评估按“用户看到的最大 messageId/messageTime”标记已读的协议升级。
+- [ ] 若业务要求会话立即可见，再评估 provisional session 及正式会话替换。
+
+### 阶段 6：发布与线上验证（尚未完成）
+
+- [ ] 发布包含当前修改的新 SDK 版本。
+- [ ] 将客服端依赖和 lock 从 `1.0.378` 升级到新版本。
+- [ ] 重新执行 SDK 运行测试、客服端完整构建和目标环境回归。
+- [ ] 灰度后使用真实 ZIP 日志验证两个客户现象的判定链。
+
+## 7. 日志覆盖审计
+
+### 7.1 覆盖结论
+
+当前前端日志已经可以定位到“问题发生在页面初始化、Socket、消息分发、会话补建、reload、本地缓存、历史合并、已读请求或断线补拉中的哪一段”。对于前端竞态和过滤路径，可以形成较完整证据链。
+
+但只靠前端日志不能证明后端的精确推送时间、消息落库时间、会话 upsert 时间和 ACK 接收结果。因此可以判断“前端已收到但接口仍返回空”或“会话接口连续 60 秒为空”，不能继续断言是 MQ 延迟、数据库失败还是后端会话更新失败。最终端到端定责仍需以后补充后端 messageId 关联日志。
+
+| 场景 | 当前日志 | 能否定位 | 判定依据 |
+|---|---|---|---|
+| 页面初始化失败后仍进入 Chat | `page_boot/user_init_result/common_setting_init_result/page_init_failed/page_ready/sdk_ready` | 可以 | 直接看到失败阶段、`dbReady` 和是否继续 ready |
+| Socket 断开或 signin 失败后未恢复 | `diagnostic:socket_state` | 可以 | 按 `connectionGeneration` 检查 close/error 后是否出现 reconnect、native_open、signin_success |
+| Socket 根本没有收到目标消息 | `client-chat-socket:receiveMessage` | 前端边界可定位 | 日志中没有 messageId；需后端推送日志判断是后端未推还是网络层未达 |
+| Socket 收到但同步处理抛错 | `client-chat-socket:receiveMessage.processing` | 可以 | 同一条消息直接记录 `failed/errorType` |
+| 消息因乱序或业务规则不触发缓存/提醒 | `diagnostic:message_event_suppressed` | 可以 | `reason` 区分 `out_of_order/auto_read/ignore_session/deleted/blocked`，同时记录 messageId 和时间基准 |
+| 消息缓存没有真正写入 | `diagnostic:message_cache_result` | 可以 | 区分 `success/skipped/failed`；skipped 带 `missing_cache_key/missing_message_time/db_unavailable/send_or_temp_message` |
+| reload 清掉内存后详情为空 | `chat_reload_result` + `message_merge_result` | 可以 | `targetMemoryBefore>0`、`clearedCount>0`、`apiCount=0`、`localMergedCount=0`、`finalTargetCount=0` 构成直接证据 |
+| cache/merge 首次读写竞态 | receive + cache + merge + reload | 可以形成强证据 | 同 messageId reload 前存在；merge 先得到 0；cache 随后成功。该顺序命中当前已证明的竞态窗口 |
+| 历史接口请求失败 | `message_history_failed` + `chat_reload_result` | 可以 | 记录 target、错误类型，reload 同时记录失败及清理后的最终数量 |
+| 会话 60 秒轮询耗尽 | `client-chat-session:getSession` | 可以 | 最终失败日志包含请求次数、空响应数、错误数和约 60 秒耗时 |
+| 会话为何在后端 60 秒仍不可查 | 前端会话轮询日志 | 不完全 | 能证明接口持续空或失败，不能证明后端会话何时 upsert；需后端日志 |
+| 断线补拉失败或水位错误 | `diagnostic:loss_sync_result` | 可以 | 失败保留旧水位；成功记录 returned/inserted/duplicate 和新水位 |
+| 点击会话已读请求失败 | `diagnostic:mark_read_result` | 可以 | 记录 conversationId、`unreadBefore`、请求结果和耗时 |
+| 已读后又出现未读 | mark-read + receive + getSession +账号未读日志 | 大部分可以 | 可判断已读后是否又收到新消息，或 getSession 返回了非零未读；后端 `markAsReadTime/upsert` 精确顺序仍需后端日志 |
+| cmd 异常是否阻断 ACK | processing failed + Socket 发送日志 | 不完全 | 可证明业务异常发生；当前没有 ACK 独立结果和服务端收 ACK 日志，不能端到端确认 |
+| 刷新后恢复 | 两个页面实例的生命周期日志 + messageId 链路 | 可以 | 以 `pageInstanceId` 和 page boot 为边界，对比刷新前 receive/cache/reload 与刷新后 merge/reload |
+
+### 7.2 两个客户现象的排查顺序
+
+对于“刷新后才出现消息”：
+
+1. 用消息 ID 或 msgSvrId 查 `client-chat-socket:receiveMessage`。
+2. 未找到时检查 `socket_state`；Socket 正常则只能定位到前端未收到，需要后端推送日志继续判断。
+3. 已收到时检查 `processing` 和 `message_event_suppressed`。
+4. 本地无会话时检查 `client-chat-session:getSession` 是否成功或 60 秒耗尽。
+5. 发生过断线时检查 `loss_sync_result` 的水位和补拉结果。
+6. 对比刷新前后 page boot，确认消息最终从历史合并还是新的 Socket 推送恢复。
+
+对于“显示有消息，点进去为空，稍后又出现未读”：
+
+1. 查 `mark_read_result`，确认点击前未读数和已读请求是否成功。
+2. 查 `chat_reload_result`，确认进入前内存是否有消息、是否执行全实例清理及最终是否为空。
+3. 查同 target 的 `message_merge_result`，确认 API 返回数、本地补入数和首尾消息。
+4. 查同 messageId 的 `message_cache_result`；若它晚于空的 merge/reload 成功，支持首次缓存竞态。
+5. 查空详情之后的 receive/getSession/账号未读日志，确认后续未读是新消息、会话延迟更新还是重新加载旧消息。
+6. 若需要判断后端为何迟到，必须结合后端落库、会话 upsert 和 markAsReadTime 日志。
+
+### 7.3 日志体量与安全
+
+- `chat_reload_result` 每次 reload 一条；`message_event_suppressed` 只在消息不触发外部事件时记录，不增加正常消息的重复日志。
+- 缓存、合并、已读和补拉均是一项操作一条结果，不记录轮询每一轮和心跳成功。
+- 正文只在原 Socket 调试摘要中最多保留前 100 字并记录长度；诊断事件不记录正文。
+- accessToken/token 会删除；不记录完整 URL。
+- 日志使用 3 MB 环形容量，并通过统一 ZIP 一次性导出。
+
+## 8. 发布边界
+
+- 当前修复只存在于 SDK 工作区，客服端依赖声明仍为 `1.0.378`。需要先发布包含本次修改的新 SDK 版本，再升级客服端依赖并重新构建，线上才会生效。
+- 本机 `node_modules` 为 `1.0.381` 只能用于当前本地验证，不能代表正式构建一定使用该版本。
+- 后续业务逻辑优化应拆分提交和灰度：先 cache/merge 竞态，再会话持续补建，再 reload 原子替换，便于日志判断每一步实际收益。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aochuang/client-sdk",
-  "version": "1.0.379",
+  "version": "1.0.381-dev-1",
   "description": "",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"

package/services/client-chat/client-chat-wechat/client-chat-message.js

@@ -72,6 +72,45 @@ export default class ClientChatMessage {
 		this.event = new Event()
 	}
 
+	addDiagnosticLog (event, data = {}) {
+		if (!this.clientChat || !this.clientChat.socket || !this.clientChat.socket.addLog) {
+			return
+		}
+		try {
+			this.clientChat.socket.addLog({
+				group: `diagnostic:${event}`,
+				content: Object.assign({
+					event
+				}, data)
+			})
+		} catch (error) {
+			// 诊断日志失败不能影响消息处理。
+		}
+	}
+
+	getGroupMessageSummary (groupId) {
+		const summary = {
+			count: 0,
+			latestMessageId: null,
+			latestMessageTime: null
+		}
+		if (!groupId) {
+			return summary
+		}
+		Object.keys(this.messageMap).forEach(id => {
+			const message = this.messageMap[id]
+			if (!message || message[this.groupField] !== groupId) {
+				return
+			}
+			summary.count++
+			if (!summary.latestMessageTime || message[this.sortField] > summary.latestMessageTime) {
+				summary.latestMessageId = message.id
+				summary.latestMessageTime = message[this.sortField]
+			}
+		})
+		return summary
+	}
+
 	getSortField (time) {
 		const step = 1000 * 60 * 60 * 24
 		const day = Math.floor(time / step)
@@ -161,14 +200,39 @@ export default class ClientChatMessage {
 					error
 				})
 			}
-			// 如果消息包含这种情况，就不能往外发送add-message事件
-			// 因为例如群发的消息，他没有会话，导致前端在处理来了新消息通知铃声提醒，获取会话一直获取不到，然后会总是发送请求
-			if (!isBeforeLastMessage && !isAutoReadMessage(data) && !shouldIgnoreSessionByMessage(data) && !isDeletedMsg(data) && !isBlockedMsg(data)) {
-				this.event && this.event.emit('add-message', {
-					data
-				})	
+				// 如果消息包含这种情况，就不能往外发送add-message事件
+				// 因为例如群发的消息，他没有会话，导致前端在处理来了新消息通知铃声提醒，获取会话一直获取不到，然后会总是发送请求
+				let suppressedReason = null
+				if (isBeforeLastMessage) {
+					suppressedReason = 'out_of_order'
+				} else if (isAutoReadMessage(data)) {
+					suppressedReason = 'auto_read'
+				} else if (shouldIgnoreSessionByMessage(data)) {
+					suppressedReason = 'ignore_session'
+				} else if (isDeletedMsg(data)) {
+					suppressedReason = 'deleted'
+				} else if (isBlockedMsg(data)) {
+					suppressedReason = 'blocked'
+				}
+				if (!suppressedReason) {
+					this.event && this.event.emit('add-message', {
+						data
+					})
+				} else {
+					this.addDiagnosticLog('message_event_suppressed', {
+						reason: suppressedReason,
+						messageId: data.id,
+						msgSvrId: data.msgSvrId,
+						wechatAccountId: data.wechatAccountId,
+						targetField: this.groupField,
+						targetId: groupField,
+						messageTime: data[this.sortField],
+						lastMessageTime,
+						memoryInserted: true,
+						addMessageEventEmitted: false
+					})
+				}
 			}
-		}
 	}
 
 	removeMessage (id) {
@@ -421,8 +485,54 @@ export default class ClientChatMessage {
 	}
 
 	reloadMessageData (params) {
+		const startedAt = Date.now()
+		const targetId = params && params[this.groupField]
+		const totalMemoryBefore = Object.keys(this.messageMap).length
+		const targetBefore = this.getGroupMessageSummary(targetId)
 		this.clearMessage()
-		return this.loadMessageData(params)
+		return this.loadMessageData(params).then(data => {
+			const targetAfter = this.getGroupMessageSummary(targetId)
+			this.addDiagnosticLog('chat_reload_result', {
+				result: 'success',
+				targetField: this.groupField,
+				targetId,
+				totalMemoryBefore,
+				targetMemoryBefore: targetBefore.count,
+				latestMessageIdBefore: targetBefore.latestMessageId,
+				latestMessageTimeBefore: targetBefore.latestMessageTime,
+				clearedCount: totalMemoryBefore,
+				loadedCount: Array.isArray(data) ? data.length : 0,
+				finalTargetCount: targetAfter.count,
+				latestMessageIdAfter: targetAfter.latestMessageId,
+				latestMessageTimeAfter: targetAfter.latestMessageTime,
+				upward: params && params.upward,
+				smallWechatTime: params && params.smallWechatTime,
+				bigWechatTime: params && params.bigWechatTime,
+				durationMs: Date.now() - startedAt
+			})
+			return data
+		}, error => {
+			const targetAfter = this.getGroupMessageSummary(targetId)
+			this.addDiagnosticLog('chat_reload_result', {
+				result: 'failed',
+				targetField: this.groupField,
+				targetId,
+				totalMemoryBefore,
+				targetMemoryBefore: targetBefore.count,
+				latestMessageIdBefore: targetBefore.latestMessageId,
+				latestMessageTimeBefore: targetBefore.latestMessageTime,
+				clearedCount: totalMemoryBefore,
+				finalTargetCount: targetAfter.count,
+				latestMessageIdAfter: targetAfter.latestMessageId,
+				latestMessageTimeAfter: targetAfter.latestMessageTime,
+				upward: params && params.upward,
+				smallWechatTime: params && params.smallWechatTime,
+				bigWechatTime: params && params.bigWechatTime,
+				durationMs: Date.now() - startedAt,
+				errorType: error && (error.name || error.code) || typeof error
+			})
+			return Promise.reject(error)
+		})
 	}
 
 	/***
@@ -587,18 +697,26 @@ export default class ClientChatMessage {
 		if (!this.loadLossMessageDataMethod) {
 			throw new Error('[ClientChatWechat]缺少loadLossMessageDataMethod方法定义')
 		}
-		this.loadLossMessageDataMethod({
+		return this.loadLossMessageDataMethod({
 			lastReceiveMessageTime: this.data.lastReceiveMessageTime
 		}).then((rs) => {
-			// 做个去重
-			if (rs && rs.data && rs.data.length) {
-				rs.data = rs.data.filter(v => !this.messageMap[v.id])
+			const result = {
+				returnedCount: 0,
+				insertedCount: 0,
+				duplicateCount: 0
 			}
-			if (rs.data.length) {
-				rs.data.forEach(item => {
+			const messages = rs && Array.isArray(rs.data) ? rs.data : []
+			result.returnedCount = messages.length
+			// 做个去重
+			const nextMessages = messages.filter(v => !this.messageMap[v.id])
+			result.insertedCount = nextMessages.length
+			result.duplicateCount = messages.length - nextMessages.length
+			if (nextMessages.length) {
+				nextMessages.forEach(item => {
 					this.addMessage(item)
 				})
 			}
+			return result
 		})
 	}
 

package/services/client-chat/client-chat-wechat/client-chat-socket.js

@@ -1,5 +1,25 @@
 import Socket from '../../socket'
 
+const LOG_CONTENT_MAX_LENGTH = 100
+
+function cloneLogData (data) {
+	const cloneData = Object.assign({}, data)
+	;['content', 'contBody'].forEach(field => {
+		if (typeof cloneData[field] === 'string') {
+			const contentLength = cloneData[field].length
+			cloneData[field] = cloneData[field].substr(0, LOG_CONTENT_MAX_LENGTH)
+			cloneData[`${field}Length`] = contentLength
+			cloneData[`${field}Truncated`] = contentLength > LOG_CONTENT_MAX_LENGTH
+		} else if (cloneData[field] !== undefined) {
+			cloneData[`${field}Type`] = typeof cloneData[field]
+			delete cloneData[field]
+		}
+	})
+	delete cloneData.accessToken
+	delete cloneData.token
+	return cloneData
+}
+
 export default class Websocket {
 	get connectStatus () {
 		return this.socket.connectStatus
@@ -12,6 +32,7 @@ export default class Websocket {
 	constructor (options) {
 		options = Object.assign({
 			socket: null,
+			log: null,
 			// 检查socket事件通知方法，有些场景不需要后端推送的命令执行，比如管理后台
 			checkSocketEventNotifyMethod: null,
 			// 执行回调事件前的方法
@@ -40,7 +61,8 @@ export default class Websocket {
 			throw new Error('socket实例不能为空')
 		}
 		this.socket = options.socket
-		this.socket.log.onBeforeAdd(({ data }) => {
+		this.log = options.log || this.socket.log || null
+		this.log && this.log.onBeforeAdd && this.log.onBeforeAdd(({ data }) => {
 			// 收消息需要拦截一些，因为下面有了
 			if (data && ['socket:sendMessage'].includes(data.group)) {
 				return false
@@ -56,22 +78,35 @@ export default class Websocket {
 		})
 		this.socket.event.on('onCmdNewMessage', (evt) => {
 			if (!options.checkSocketEventNotifyMethod || options.checkSocketEventNotifyMethod(evt) !== false) {
-				const cloneMsg = Object.assign({}, evt.data)
-				const newMsg = Object.assign({}, cloneMsg.chatroomMessage || cloneMsg.friendMessage)
-				if (typeof newMsg.content === 'string') {
-					newMsg.content = newMsg.content.substr(0, 100) // 只保留前100个字符，怕数据太多了
+				let processingError
+				try {
+					options.onCmdNewMessage(evt)
+				} catch (error) {
+					processingError = error
 				}
-				delete cloneMsg.chatroomMessage
-				delete cloneMsg.friendMessage
-				cloneMsg.message = newMsg
-				this.socket.logEnable && this.socket.log.addLog({
+				const cloneData = cloneLogData(evt.data)
+				if (evt.data.friendMessage) {
+					cloneData.friendMessage = cloneLogData(evt.data.friendMessage)
+				}
+				if (evt.data.chatroomMessage) {
+					cloneData.chatroomMessage = cloneLogData(evt.data.chatroomMessage)
+				}
+				this.addLog({
 					group: 'client-chat-socket:receiveMessage',
 					content: {
 						title: 'socket收到消息',
-						data: cloneMsg
+						data: cloneData,
+						processing: processingError ? {
+							result: 'failed',
+							errorType: processingError && (processingError.name || processingError.code) || typeof processingError
+						} : {
+							result: 'success'
+						}
 					}
 				})
-				options.onCmdNewMessage(evt)
+				if (processingError) {
+					throw processingError
+				}
 			}
 		})
 		this.socket.event.on('onCmdSendMessageResult', (evt) => {
@@ -134,14 +169,11 @@ export default class Websocket {
 			options.onHeartbeatSuccess && options.onHeartbeatSuccess(evt)
 		})
 		this.socket.event.on('onSendMessage', (evt) => {
-			const cloneData = Object.assign({}, evt.data)
-			if (cloneData && typeof cloneData.content === 'string') {
-				cloneData.content = cloneData.content.substr(0, 100)
-			}
+			const cloneData = cloneLogData(evt.data)
 			if (evt.data.cmdType === 'CmdRequestWechatAccountsAliveStatus') {
 				delete cloneData.wechatAccountIds
 			}
-			this.socket.logEnable && this.socket.log.addLog({
+			this.addLog({
 				group: 'client-chat-socket:sendMessage',
 				content: {
 					title: '发送消息',
@@ -222,7 +254,7 @@ export default class Websocket {
 	}
     
 	addLog (data) {
-		this.socket.logEnable && this.socket.log.addLog(data)
+		this.socket.logEnable && this.log && this.log.addLog(data)
 	}
 
     exportLogData () {

package/services/client-chat/client-chat-wechat/client-chat.js

@@ -55,6 +55,7 @@ class ClientChat {
 	constructor (options) {
 		options = Object.assign({
 			socket: null,
+			log: null,
 			checkSocketEventNotifyMethod: null,
 			getLoginUserIdMethod: null,
 			getLoginUserTokenMethod: null,
@@ -101,6 +102,7 @@ class ClientChat {
 		if (!options.loadRoomMessageDataMethod) {
 			throw new Error('loadRoomMessageDataMethod不能为空')
 		} 
+		this.log = options.log || (options.socket && options.socket.log) || null
 		this.onOverwriteFriendInfoChange = options.onOverwriteFriendInfoChange
 		this.shouldMarkCurrentSessionReadMethod = options.shouldMarkCurrentSessionReadMethod
 		this.event = new Event({
@@ -803,6 +805,7 @@ class ClientChat {
 		})
 		this.socket = new ClientChatSocket({
 			socket: options.socket,
+			log: this.log,
 			getLoginUserIdMethod: options.getLoginUserIdMethod,
 			getLoginUserTokenMethod: options.getLoginUserTokenMethod,
 			checkSocketEventNotifyMethod: options.checkSocketEventNotifyMethod,
@@ -1134,22 +1137,65 @@ class ClientChat {
 				
 			},
 			onSocketOpen: () => {
-				const ps = []
-				if (this.friendMessage.lastReceiveMessageTime) {
-					ps.push(this.friendMessage.loadLossMessageData())
-				}
-				if (this.roomMessage.lastReceiveMessageTime) {
-					ps.push(this.roomMessage.loadLossMessageData())
+				const reconnectTime = Date.now()
+				const syncTasks = []
+				const syncLossMessages = (type, messageInstance) => {
+					const watermarkBefore = messageInstance.lastReceiveMessageTime
+					if (!watermarkBefore) {
+						messageInstance.setLastReceiveMessageTime(reconnectTime)
+						this.socket.addLog({
+							group: 'diagnostic:loss_sync_result',
+							content: {
+								event: 'loss_sync_result',
+								type,
+								result: 'initialized',
+								watermarkBefore,
+								watermarkAfter: messageInstance.lastReceiveMessageTime
+							}
+						})
+						return
+					}
+					const startedAt = Date.now()
+					const task = messageInstance.loadLossMessageData().then(result => {
+						messageInstance.setLastReceiveMessageTime(reconnectTime)
+						this.socket.addLog({
+							group: 'diagnostic:loss_sync_result',
+							content: Object.assign({
+								event: 'loss_sync_result',
+								type,
+								result: 'success',
+								watermarkBefore,
+								watermarkAfter: messageInstance.lastReceiveMessageTime,
+								durationMs: Date.now() - startedAt
+							}, result)
+						})
+						return true
+					}, error => {
+						this.socket.addLog({
+							group: 'diagnostic:loss_sync_result',
+							content: {
+								event: 'loss_sync_result',
+								type,
+								result: 'failed',
+								watermarkBefore,
+								watermarkAfter: messageInstance.lastReceiveMessageTime,
+								durationMs: Date.now() - startedAt,
+								errorType: error && (error.name || error.code) || typeof error
+							}
+						})
+						return false
+					})
+					syncTasks.push(task)
 				}
-				Promise.all(ps).finally(() => {
-					this.friendMessage.setLastReceiveMessageTime(Date.now())
-					this.roomMessage.setLastReceiveMessageTime(Date.now())
+				syncLossMessages('friend', this.friendMessage)
+				syncLossMessages('room', this.roomMessage)
+				Promise.all(syncTasks).then(() => {
 					// 断线期间本地增量可能和服务端产生偏差（其他端已读、消息延迟等），重连后以服务端为准全量校准一次
-					if (ps.length) {
+					if (syncTasks.length) {
 						this.account.refreshAllAccountUnreadMesageNum()
 					}
 				})
-			}, 
+			},
 			onSocketClose: (evt) => {
 			}, 
 			onSocketKickOut: () => {

package/services/socket/socket.js

@@ -25,6 +25,8 @@ export default class Socket {
     
     maxReconnectInterval = 60000
 
+    connectionGeneration = 0
+
     data = Vue.observable({
         connectIpChange: false, // 连接设备是否变化，如果变化需要提示用户退出重新登录
         connectMessage: null,
@@ -47,6 +49,7 @@ export default class Socket {
             url: null,
 			client: null,
 			logEnable: false,
+			log: null,
 			logName: 'socket',
 			logMaxSize: 3 * 1024 * 1024, // 非网页版本最多记3M日志
             socketAdapter: null, // 支持从外面传一个socket构造函数，但是要实现socket标准的使用方式
@@ -73,7 +76,7 @@ export default class Socket {
         this.logEnable = !!options.logEnable
         this.url = options.url
         this.event = new Event()
-        this.log = new Log({
+        this.log = options.log || new Log({
             maxSize: options.logMaxSize, // 非网页版本日志大小限制
             name: options.logName || 'socket'
         })
@@ -105,6 +108,17 @@ export default class Socket {
         return !!socket && socket === this._ws
     }
 
+    _addSocketStateLog (event, data = {}) {
+        this.logEnable && this.log.addLog({
+            group: 'diagnostic:socket_state',
+            content: Object.assign({
+                event,
+                connectionGeneration: this.connectionGeneration,
+                connectStatus: this.connectStatus
+            }, data)
+        })
+    }
+
     _handleReconnectLimitExceeded () {
         const err = new Error('socket重连次数已超过上限')
         clearTimeout(this._reconnectTimer)
@@ -141,14 +155,20 @@ export default class Socket {
             this.readyPromise = createPromise()
             this.data.connectUrl = this.url + `?client=${this.client}&accountId=${this.accountId}&accessToken=${this.token}`
             let socket = null
+            this.connectionGeneration++
             this.data.connectStatus = CONNECT_STATUS.Connecting
             this.logEnable && this.log.addLog({
                 group: 'socket:connect',
                 content: {
                     title: '开始连接',
-                    socketUrl: this.data.connectUrl
+                    client: this.client,
+                    accountId: this.accountId,
+                    connectionGeneration: this.connectionGeneration
                 }
             })
+            this._addSocketStateLog('connect_start', {
+                to: CONNECT_STATUS.Connecting
+            })
             this._ws = null
             if (this.socketAdapter) {
                 socket = new this.socketAdapter(this.data.connectUrl)
@@ -275,6 +295,9 @@ export default class Socket {
                 title: 'socket连接中'
             }
         })
+        this._addSocketStateLog('native_open', {
+            to: CONNECT_STATUS.Success
+        })
         this.sendMessage(params).then(() => {
             if (socket && !this._isCurrentSocket(socket)) {
                 return
@@ -286,6 +309,9 @@ export default class Socket {
                 }
             })
             this._startHeartbeat() // 注释掉，因为现在心跳的命令改了，用账号在线状态控制，减少命令发送频率
+            this._addSocketStateLog('signin_success', {
+                result: 'success'
+            })
             successFn && successFn()
             this.event.emit('onOpen')
         }, (err) => {
@@ -293,6 +319,13 @@ export default class Socket {
                 return
             }
             errorFn && errorFn(err)
+            this.data.connectStatus = CONNECT_STATUS.Error
+            this._addSocketStateLog('signin_failed', {
+                result: 'failed',
+                errorType: err && (err.name || err.code) || typeof err,
+                willReconnect: true
+            })
+            this.reconnect().catch(() => {})
         })
     }
     
@@ -324,11 +357,15 @@ export default class Socket {
                 reason: evt.reason,
             }
         })
+        this._addSocketStateLog('socket_close', {
+            from: prevConnectStatus,
+            to: CONNECT_STATUS.Close,
+            closeCode: evt.code,
+            reason: evt.reason,
+            willReconnect: !evt.reason || evt.reason.indexOf('(手动关闭)') < 0
+        })
         if (!evt.reason || evt.reason.indexOf('(手动关闭)') < 0) {
-            if (prevConnectStatus === CONNECT_STATUS.Connecting) {
-                return
-            }
-            this.reconnect()
+            this.reconnect().catch(() => {})
         }
         this.event.emit('onClose', {
             code: evt.code,
@@ -355,7 +392,11 @@ export default class Socket {
         if (this.readyPromise && typeof this.readyPromise.reject === 'function') {
             this.readyPromise.reject(new Error('socket连接错误'))
         }
-        this.reconnect()
+        this._addSocketStateLog('socket_error', {
+            to: CONNECT_STATUS.Error,
+            willReconnect: true
+        })
+        this.reconnect().catch(() => {})
     }
     
     mockSocketMessage (evt) {
@@ -373,11 +414,13 @@ export default class Socket {
         if (this.messageCallbackMap[messageData.seq]) {
             if (messageData.code === -1) {
                 this.messageCallbackMap[messageData.seq].reject({
-                    errMsg: messageData.extra
+                    errMsg: messageData.extra,
+                    response: messageData
                 })
             } else {
                 this.messageCallbackMap[messageData.seq].resolve({
-                    data: messageData.extra
+                    data: messageData.extra,
+                    response: messageData
                 })
             }
         }
@@ -443,6 +486,10 @@ export default class Socket {
                     // 指数退避 + 随机抖动
                     const jitter = Math.random() * 500 * 2 - 500
                     const actualInterval = Math.min(this.reconnectInterval + jitter, this.maxReconnectInterval)
+                    this._addSocketStateLog('reconnect_scheduled', {
+                        retryCount: this.reconnectCount,
+                        delayMs: Math.max(0, Math.round(actualInterval))
+                    })
                     // 先翻倍再等待，避免定时器被取消导致倍数丢失
                     this.reconnectInterval = Math.min(this.reconnectInterval * 2, this.maxReconnectInterval)
                     clearTimeout(this._reconnectTimer)
@@ -552,10 +599,18 @@ export default class Socket {
                 messageId,
                 message: nextMessage,
                 resolve: (data) => {
-                    messagePromise.resolve(data)
+                    const resolveData = {
+                        data: data.data,
+                        response: data.response
+                    }
+                    messagePromise.resolve(resolveData)
                     messageObject.destroy()
                     callback && callback({
-                        data
+                        data: resolveData
+                    })
+                    this.event.emit('onSendMessageSuccess', {
+                        data: data.response,
+                        message: nextMessage
                     })
                 },
                 reject: (err) => {