@aochuang/client-sdk 1.0.400 → 1.0.402
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/components/wechat-chat-control/location/location.vue +11 -3
- package/package.json +1 -1
- package/services/client-chat/client-chat-wechat/client-chat-account.js +37 -7
- package/services/client-chat/client-chat-wechat/client-chat-message.js +175 -18
- package/services/client-chat/client-chat-wechat/client-chat-session.js +190 -12
- package/services/client-chat/client-chat-wechat/client-chat-socket.js +80 -22
- package/services/client-chat/client-chat-wechat/client-chat.js +87 -11
- package/services/socket/socket.js +56 -7
- package/utils/log/constants.js +13 -0
- package/utils/log/export.js +88 -0
- package/utils/log/findings.md +141 -0
- package/utils/log/index.js +331 -0
- package/utils/log/indexed-db.js +228 -0
- package/utils/log/progress.md +267 -0
- package/utils/log/serialize.js +146 -0
- package/utils/log/task_plan.md +149 -0
- package/utils/log//345/210/206/346/236/220/344/270/216/344/274/230/345/214/226/346/226/271/346/241/210.md +303 -0
- package/utils/log//346/212/200/346/234/257/346/226/271/346/241/210/346/226/207/346/241/243.md +201 -0
- package/utils/log//346/236/266/346/236/204/346/226/207/346/241/243.md +169 -0
- package/utils/log//351/234/200/346/261/202/346/226/207/346/241/243.md +124 -0
- package/utils/log.js +2 -626
|
@@ -0,0 +1,303 @@
|
|
|
1
|
+
# 消息延迟与未读异常:分析与优化方案
|
|
2
|
+
|
|
3
|
+
## 1. 分析范围与结论
|
|
4
|
+
|
|
5
|
+
本文基于以下当前工作区代码复核:
|
|
6
|
+
|
|
7
|
+
- `client-sdk`:分支 `master-补充日志`,HEAD `0d5e859`,包版本 `1.0.381`,含未提交的修复和日志改动。
|
|
8
|
+
- 极速客服端 `JavaMain-combine`:依赖文件仍锁定 `@aochuang/client-sdk@1.0.378`,本机 `node_modules` 为 `1.0.381`。
|
|
9
|
+
- 后端 `workphone-java`:确认新消息采用“先推送客户端,finally 中再异步入库”的顺序。
|
|
10
|
+
|
|
11
|
+
针对客户反馈:
|
|
12
|
+
|
|
13
|
+
1. “有些消息刷新网页才出现”:当前修改已经修复两条可直接造成该现象的确定路径,即断线补拉水位提前推进和 Socket 在特定失败状态下停止重连。剩余代码中仍有“会话补建轮询耗尽后无持续补偿”和“乱序消息不触发缓存/会话事件”两条可达路径。
|
|
14
|
+
2. “显示有消息,点进去没有,过一会又出现未读”:最强的剩余前端证据链是首次进入会话时 `reloadMessageData` 先清内存,历史接口又处于未入库窗口,同时本地补偿缓存的首次读取和写入发生竞态。三者必须叠加;不能把“先推后存”或 `reload` 单独认定为必现缺陷。
|
|
15
|
+
|
|
16
|
+
建议先修复两个前端闭环问题:进入会话改为按当前会话原子替换,并让本地补偿合并等待同会话已排队的缓存写入;会话轮询超时后进入低频持续补建。乱序消息事件拆分随后处理。ACK、初始化门禁和已读时机先依赖现有日志确认线上是否命中,再决定是否调整协议或交互语义。
|
|
17
|
+
|
|
18
|
+
## 2. 已确认且当前代码已修复的问题
|
|
19
|
+
|
|
20
|
+
### 2.1 断线补拉提前推进水位
|
|
21
|
+
|
|
22
|
+
原路径中 `loadLossMessageData()` 没有返回异步请求 Promise,`onSocketOpen` 的等待会提前完成,并在请求成功前把水位推进到当前时间。补拉失败时,更早的消息可能永久越过下一次补拉区间,只能在页面刷新后的全量初始化中恢复。
|
|
23
|
+
|
|
24
|
+
当前修改:
|
|
25
|
+
|
|
26
|
+
- `client-chat-message.js:586-610` 返回真实 Promise,并统计返回、插入、重复数量。
|
|
27
|
+
- `client-chat.js:1139-1170` 分好友/群等待补拉;只在对应补拉成功后推进水位,失败保留旧水位。
|
|
28
|
+
|
|
29
|
+
这是明确缺陷,修改方向正确。主要影响是重连后的未读校准会等待补拉任务结束;单类补拉失败时该类会在下一次连接继续从旧水位补拉。
|
|
30
|
+
|
|
31
|
+
### 2.2 Socket 特定失败状态下停死
|
|
32
|
+
|
|
33
|
+
原路径中 Connecting 阶段发生 close 时,连接 Promise 可能无法正确结束并启动下一轮;原生连接成功但 signin 失败时,状态也可能停住。此后实时消息不再进入,刷新重建实例后才恢复。
|
|
34
|
+
|
|
35
|
+
当前修改位于 `services/socket/socket.js`:
|
|
36
|
+
|
|
37
|
+
- close 会结束当前连接等待,并对非手动关闭进入受控重连。
|
|
38
|
+
- signin 失败把状态置为 Error,并调用已有 `reconnect()`。
|
|
39
|
+
- `_isReconnecting` 继续限制并发重连。
|
|
40
|
+
|
|
41
|
+
影响范围仅为异常连接恢复路径;手动关闭仍不重连,历史构造方式和正常消息路径不变。
|
|
42
|
+
|
|
43
|
+
## 3. 仍存在的高优先级问题
|
|
44
|
+
|
|
45
|
+
### 3.1 进入会话预清空与本地补偿首次读写竞态
|
|
46
|
+
|
|
47
|
+
证据等级:**确定存在可达竞态;是否为客户本次样本原因需日志关联。**
|
|
48
|
+
|
|
49
|
+
#### 原因与证据链
|
|
50
|
+
|
|
51
|
+
1. 后端先推送再异步入库:`NewMessage1007MessageHandler.java:178-197`(群消息)及 `327-360`(好友消息)。因此 Socket 已收到而历史接口暂时为空是设计允许的窗口。
|
|
52
|
+
2. SDK 收到消息后会先插入内存:`client-chat-message.js:111-140`。
|
|
53
|
+
3. 客服端仅监听 `add-message` 后异步调用 `cacheMessage`,调用方不等待:`src/entries/chat/services/client-chat/index.js:484-515`。
|
|
54
|
+
4. 首次进入好友/群详情分别调用 `reloadMessageData`:`chat-panel-friend.vue:943-959`、`chat-panel-room.vue:1165-1180`。
|
|
55
|
+
5. `reloadMessageData` 在请求前执行 `clearMessage()`:`client-chat-message.js:423-425`;而 `clearMessage()` 遍历整个实例的 `messageMap`:`316-320`,不是只清当前会话。
|
|
56
|
+
6. 本地补偿的 `cacheMessage` 和 `mergeMessages` 都会调用 `getMemoryCacheItems`。首次访问同一个 key 时共享 `loadPromiseMap[cacheKey]`:`messageLocalCompensateService.js:232-257`。
|
|
57
|
+
7. 若缓存写入和历史合并同时等待同一份 IndexedDB 旧快照,写入 continuation 会在随后更新 `cacheMap`(`365-395`),但合并 continuation 已持有旧的 `originItems`(`446-454`),本次合并可能仍得到 0 条。
|
|
58
|
+
|
|
59
|
+
完整可达顺序为:Socket 消息已进入内存 -> 缓存写任务刚开始 -> 用户立即进入会话 -> reload 清掉内存 -> 历史接口因尚未入库返回空 -> merge 读取到写入前快照 -> 页面暂时为空。后端落库或本地缓存完成后,再次加载会恢复。
|
|
60
|
+
|
|
61
|
+
这也回答了“后端入库后是否还会推送”的疑问:当前 1007 路径展示的是入站时先推一次、随后异步入库,没有证据表明“入库完成后必定再推同一条消息”。正常情况下依靠内存和本地补偿即可,不应把二次推送当成恢复保证。
|
|
62
|
+
|
|
63
|
+
#### 推荐方案
|
|
64
|
+
|
|
65
|
+
第一步采用最小兼容方案:
|
|
66
|
+
|
|
67
|
+
- `mergeMessages` 在读取缓存前,等待该 `cacheKey` 当前已经排队的 `queueMap[cacheKey]` 任务完成;需避免 merge 自身加入同一队列后自等造成死锁。
|
|
68
|
+
- `cacheMessage` 在异步读取 IndexedDB 前先登记会话级 pending message;merge 同时合并 pending memory,缓存写完再清理 pending。
|
|
69
|
+
- 已增加 `chat_reload_result` 聚合日志,记录清理前后内存数量、前后最后消息、加载数量、请求边界和耗时;结合 `message_merge_result` 的 API 数及本地补入数判断,不记录正文。
|
|
70
|
+
|
|
71
|
+
第二步解决 reload 语义:
|
|
72
|
+
|
|
73
|
+
- 先请求和合并到临时结果,成功后只对当前 target 原子替换。
|
|
74
|
+
- 请求失败时保留当前 Socket 内存消息。
|
|
75
|
+
- 接口返回空时仍保留当前 target 中、且服务端尚未覆盖的实时消息。
|
|
76
|
+
- 不再清空好友或群实例中的所有会话消息。
|
|
77
|
+
|
|
78
|
+
#### 影响点
|
|
79
|
+
|
|
80
|
+
- `reloadMessageData` 从“清整个实例后重载”改成“按 target 原子替换”,需要复核好友、群、筛选和上下文共 6 个调用点。
|
|
81
|
+
- 原子替换要保护临时发送消息、发送状态轮询、Vue 响应式对象引用和分页边界。
|
|
82
|
+
- 不能只做“取消 clear”而一直追加,否则旧查询窗口之外的数据可能残留。
|
|
83
|
+
- 同一条 Socket/接口消息仍需按稳定 ID 去重。
|
|
84
|
+
- 必须增加竞态测试:Socket 到达、历史为空、IndexedDB 首读未完成、缓存写排队、快速切换会话。
|
|
85
|
+
|
|
86
|
+
### 3.2 会话补建轮询 60 秒耗尽后无持续补偿
|
|
87
|
+
|
|
88
|
+
证据等级:**确定存在失败后的断点;后端是否曾超过 60 秒需线上日志确认。**
|
|
89
|
+
|
|
90
|
+
#### 原因与证据链
|
|
91
|
+
|
|
92
|
+
- 新消息找不到本地会话时,好友和群消息分别调用 `getSession`:`client-chat.js:440-473`、`565-610`。
|
|
93
|
+
- `getSession` 复用同会话轮询并聚合消息回调:`client-chat-session.js:245-344`。
|
|
94
|
+
- 默认每 5 秒请求,最长 60 秒:`utils/util.js:35-129`。
|
|
95
|
+
- 失败后 `finally` 删除 `pollRequestMap[sessionId]`,调用方 `.catch(() => {})` 吞掉失败;当前批次结束后没有定时重试。
|
|
96
|
+
|
|
97
|
+
因此 Socket 消息可以已经存在于 `messageMap`,但会话列表没有入口。若 60 秒内后端会话始终不可查,后续只有新消息、显式刷新或页面刷新才会重新触发加载,符合“刷新后才出现”的表象。
|
|
98
|
+
|
|
99
|
+
#### 推荐方案
|
|
100
|
+
|
|
101
|
+
- 增加 `pendingSessionMap`,轮询超时后每 30 秒低频重试,设置总时长上限,例如 10 分钟。
|
|
102
|
+
- Socket 重连成功、页面重新可见、会话列表主动刷新时立即重试 pending 会话。
|
|
103
|
+
- 同一会话多条消息聚合,成功后按 `messageId/lastMsgTime` 去重合并,确保未读只累计一次。
|
|
104
|
+
- 若业务要求消息入口立即可见,可进一步创建 provisional session;后端正式会话出现后原子替换。
|
|
105
|
+
|
|
106
|
+
#### 影响点
|
|
107
|
+
|
|
108
|
+
- 低频重试会增加少量接口请求,必须按会话聚合并设置上限。
|
|
109
|
+
- provisional session 缺少 mute、sticky、权限、协作和任务等完整字段,点击能力需降级或等待正式数据。
|
|
110
|
+
- 正式会话替换时要保护列表排序、当前选中项和账号/会话未读,不能重复累加。
|
|
111
|
+
- 删除、拉黑、群发等本就不应建立会话的消息不能进入 pending。
|
|
112
|
+
|
|
113
|
+
### 3.3 乱序消息进入内存,但不触发缓存、会话和提醒事件
|
|
114
|
+
|
|
115
|
+
证据等级:**代码行为确定;线上是否存在异常乱序或未来时间需日志确认。**
|
|
116
|
+
|
|
117
|
+
#### 原因与证据链
|
|
118
|
+
|
|
119
|
+
- `addMessage` 在判断 `isBeforeLastMessage` 后仍把消息写入 `messageData/messageMap`:`client-chat-message.js:124-140`。
|
|
120
|
+
- 好友/群 `onAddMessageSuccess` 遇到乱序消息直接返回:`client-chat.js:430-432`、`554-555`。
|
|
121
|
+
- `add-message` 只在非乱序消息时触发:`client-chat-message.js:164-169`。
|
|
122
|
+
- 客服端本地补偿只监听 `add-message`:`src/entries/chat/services/client-chat/index.js:513-515`。
|
|
123
|
+
- 最后消息时间和接收水位只允许增大:`client-chat-message.js:616-638`。若某条消息时间异常偏未来,后续正常消息可能连续被判定为旧消息。
|
|
124
|
+
|
|
125
|
+
因此乱序消息在当前页面可能已存在于内存,但不会更新会话、不提醒、也不会写入本地补偿;一旦随后 reload 清内存,只能等待历史接口可查后恢复。
|
|
126
|
+
|
|
127
|
+
#### 推荐方案
|
|
128
|
+
|
|
129
|
+
- 新增内部 `message-accepted` 或 `message-cache` 事件:所有成功插入的普通入站消息都触发缓存。
|
|
130
|
+
- 保留 `add-message` 作为“允许更新会话、未读和提醒”的事件,避免历史乱序消息产生声音或重复未读。
|
|
131
|
+
- 对明显未来时间只记录异常,不让它无限抬高会话乱序基准;补拉水位优先考虑服务端接收时间或带容差的客户端消息时间。
|
|
132
|
+
|
|
133
|
+
#### 影响点
|
|
134
|
+
|
|
135
|
+
- 必须检查全部 `add-message` 监听者,不能简单放开现有条件,否则会产生旧消息提醒和未读重复。
|
|
136
|
+
- 新缓存事件要继续排除临时发送、自动已读、删除、拉黑及不建会话消息,具体口径需与业务确认。
|
|
137
|
+
- 未来时间容差必须与后端时间字段语义统一。
|
|
138
|
+
|
|
139
|
+
## 4. 中优先级风险
|
|
140
|
+
|
|
141
|
+
### 4.1 同步业务异常可能阻断 Socket ACK
|
|
142
|
+
|
|
143
|
+
证据等级:**防护缺口确定;是否线上触发需日志确认。**
|
|
144
|
+
|
|
145
|
+
`services/socket/socket.js:406-451` 在 ACK 前执行 JSON 解析、通用接收事件和具体 cmd 事件;任一同步异常都会跳过 `CommandResponse`。`client-chat-socket.js:79-109` 虽记录新消息业务异常,但随后重新抛出,仍会回到该路径。
|
|
146
|
+
|
|
147
|
+
方案取决于协议:若 ACK 表示“帧已收到”,应在受保护的 `finally` 中 ACK,业务处理失败另记并触发补偿;若 ACK 表示“业务处理成功”,应返回失败 ACK,而不是无响应。还应保护 JSON 解析和 cmd 分发边界。
|
|
148
|
+
|
|
149
|
+
影响是后端重试语义可能改变:过早成功 ACK 会失去依赖重推恢复业务失败的机会。修改前需确认服务端 ACK 定义,并测试 malformed frame、监听器异常和重复推送去重。
|
|
150
|
+
|
|
151
|
+
### 4.2 初始化失败仍渲染 Chat 并连接 Socket
|
|
152
|
+
|
|
153
|
+
证据等级:**代码路径确定;是否造成客户样本需日志确认。**
|
|
154
|
+
|
|
155
|
+
`root.vue:99-147` 捕获用户或配置初始化失败后,仍在 `finally` 设置 `ready = true`。Chat 创建后,移动端和 PC 分别在 `chat.vue:81-90`、`chat-pc.vue:415-417` 直接连接 Socket。用户身份、token 或补偿库名称未准备好时,页面仍可能进入可操作状态。
|
|
156
|
+
|
|
157
|
+
建议把用户身份、token、补偿 DB 初始化定义为关键门禁;失败时显示可重试状态,不创建 Chat。配置类初始化可按业务允许降级。Socket 连接前校验 accountId、token 和 dbReady。
|
|
158
|
+
|
|
159
|
+
影响是初始化失败时用户会看到错误/重试页,而不是当前的空页面;需要防止重复初始化和重复建连,并明确哪些配置允许降级。
|
|
160
|
+
|
|
161
|
+
### 4.3 标记已读早于首屏消息加载完成
|
|
162
|
+
|
|
163
|
+
证据等级:**时序确定,但不能单独解释“稍后又未读”。**
|
|
164
|
+
|
|
165
|
+
`setCurrentSession` 立即触发回调:`client-chat-session-manage.js:46-64`;`client-chat.js:405-413` 随即调用 `setSessionRead`。服务端成功后才本地清零:`client-chat-session.js:938-950`,因此“点击即先本地清零”并不成立。详情首屏 reload 是另一条异步链,用户尚未看到消息时服务端标记已读可能已经成功。
|
|
166
|
+
|
|
167
|
+
后端 `Conversation.markAsRead` 同时写 `unreadMsgCount=0` 和 `markAsReadTime`:`Conversation.java:123-127`;会话 upsert 会结合消息时间更新。因此“稍后又未读”还必须结合新消息时间、`markAsReadTime` 和会话 upsert 才能判断,不能只归因于点击。
|
|
168
|
+
|
|
169
|
+
建议在首屏历史和本地补偿完成、至少完成首次渲染后再标记已读。更稳妥的协议是提交用户实际看到的最大 `messageId/messageTime`,避免把加载期间新到的消息一并读掉。
|
|
170
|
+
|
|
171
|
+
影响是未读徽标会多保留短时间;首屏加载失败时应维持未读。PC、H5、Pad 和页面可见性触发的自动已读需统一口径。
|
|
172
|
+
|
|
173
|
+
## 5. 已排除的单点归因
|
|
174
|
+
|
|
175
|
+
- **“后端先推后存,所以一定丢消息”不成立。** SDK 内存消息和本地补偿正常情况下会覆盖该窗口;问题需要叠加 reload 清空、补偿竞态或其他失败路径。
|
|
176
|
+
- **“reload 一定丢消息”不成立。** 若历史接口已入库,或本地补偿已经写入并被 merge 读到,消息会正常恢复。
|
|
177
|
+
- **“进入会话立刻在本地清零”不成立。** 当前代码等待服务端 `updateSessionRead` 成功后才本地清零。
|
|
178
|
+
- **“getSession 没有轮询”不成立。** 已有 5 秒一次、最长 60 秒的轮询;缺口是耗尽后的持续补偿。
|
|
179
|
+
- **“Socket 建连早于消息监听注册”暂无证据。** 当前 ClientChat 构造时先注册监听,Chat 组件创建后再 connect。
|
|
180
|
+
|
|
181
|
+
## 6. 完整阶段计划与当前状态
|
|
182
|
+
|
|
183
|
+
状态说明:`[x]` 已在当前工作区完成;`[ ]` 尚未实施;“仅日志”表示本次只增加诊断能力,没有改变业务行为。
|
|
184
|
+
|
|
185
|
+
### 阶段 1:证据链复核与确定缺陷修复
|
|
186
|
+
|
|
187
|
+
- [x] 复核前端、SDK、后端的新消息、会话、详情、已读和补拉链路。
|
|
188
|
+
- [x] 确认后端好友和群消息均为先推送、后异步入库。
|
|
189
|
+
- [x] 确认本地补偿、会话 60 秒轮询和 reload 的实际边界,排除不成立的单点归因。
|
|
190
|
+
- [x] 修复断线补拉 Promise 未返回及水位提前推进。
|
|
191
|
+
- [x] 修复 Socket Connecting close 和 signin 失败后不再重连。
|
|
192
|
+
- [x] 完成 Socket 重连和断线补拉最小运行测试。
|
|
193
|
+
|
|
194
|
+
### 阶段 2:前端诊断日志与日志交付
|
|
195
|
+
|
|
196
|
+
- [x] 页面生命周期:boot、用户初始化、配置初始化、ready、pageshow/pagehide、visibilitychange。
|
|
197
|
+
- [x] Socket 状态:连接代次、open、signin、close/error、重连计划。
|
|
198
|
+
- [x] 新消息接收:消息 ID、目标、时间、同步处理成功/失败;正文截断,token 删除。
|
|
199
|
+
- [x] 会话补建:轮询创建、请求/空响应/错误次数、最终成功或 60 秒失败。
|
|
200
|
+
- [x] 本地补偿:缓存 `success/skipped/failed`、跳过原因、合并前 API 数、本地补入数和最终数。
|
|
201
|
+
- [x] 进入会话:reload 清理前当前会话/全实例数量、清理数、加载数、最终数量、前后最后消息 ID/时间。
|
|
202
|
+
- [x] 消息过滤:消息已入内存但未触发 `add-message` 时记录具体原因。
|
|
203
|
+
- [x] 历史失败、已读请求、断线补拉水位和结果摘要。
|
|
204
|
+
- [x] Socket、SDK、业务层复用唯一日志实例;SDK 未传实例时保留自行创建日志的兼容路径。
|
|
205
|
+
- [x] 下载日志改为点击后直接生成 ZIP,包含微号、已加载会话、统一运行日志和网络日志。
|
|
206
|
+
- [x] 日志实现归并到客服端 `src/entries/chat/utils/log.js`。
|
|
207
|
+
- [ ] 后端推送、MQ、落库、会话 upsert 和 ACK 日志。本轮按要求只增加前端日志。
|
|
208
|
+
|
|
209
|
+
### 阶段 3:第一批业务一致性优化(建议优先,尚未实施)
|
|
210
|
+
|
|
211
|
+
- [ ] 本地补偿增加会话级 pending memory。
|
|
212
|
+
- [ ] `mergeMessages` 等待同会话已经排队的缓存写入,消除首次 IndexedDB 旧快照竞态。
|
|
213
|
+
- [ ] 增加 Socket 到达、历史为空、缓存首次读写并发的自动化测试。
|
|
214
|
+
- [ ] 增加 `pendingSessionMap`,会话轮询 60 秒耗尽后低频持续补建。
|
|
215
|
+
- [ ] Socket 重连成功、页面恢复可见、会话列表主动刷新时立即重试 pending 会话。
|
|
216
|
+
|
|
217
|
+
这一阶段不改变 ACK 和已读协议,也不创建字段不完整的临时会话,兼容风险相对较低。
|
|
218
|
+
|
|
219
|
+
### 阶段 4:消息列表一致性优化(尚未实施)
|
|
220
|
+
|
|
221
|
+
- [ ] 将 reload 改为先加载和合并,成功后只原子替换当前 target。
|
|
222
|
+
- [ ] reload 失败或服务端暂时为空时,保留未被远端覆盖的 Socket 内存消息。
|
|
223
|
+
- [ ] 不再由进入一个会话清空好友或群实例中的全部会话消息。
|
|
224
|
+
- [ ] 拆分“消息接受/缓存事件”和“会话未读/提醒事件”,让乱序有效消息仍进入补偿缓存。
|
|
225
|
+
- [ ] 对明显未来的消息时间增加容差或隔离,防止持续抬高乱序基准。
|
|
226
|
+
- [ ] 覆盖好友、群、筛选、上下文 6 个 reload 调用点的回归测试。
|
|
227
|
+
|
|
228
|
+
### 阶段 5:协议与交互语义优化(需确认后实施)
|
|
229
|
+
|
|
230
|
+
- [ ] 与后端确认 ACK 代表“帧已收到”还是“业务处理成功”,再决定 finally ACK 或失败 ACK。
|
|
231
|
+
- [ ] 保护 JSON 解析和 cmd 分发边界,并测试异常帧、监听器异常及重复推送。
|
|
232
|
+
- [ ] 将用户身份、token、补偿 DB 设为 Chat 渲染和 Socket 建连门禁。
|
|
233
|
+
- [ ] 将已读调整为首屏历史和本地补偿完成后上报。
|
|
234
|
+
- [ ] 评估按“用户看到的最大 messageId/messageTime”标记已读的协议升级。
|
|
235
|
+
- [ ] 若业务要求会话立即可见,再评估 provisional session 及正式会话替换。
|
|
236
|
+
|
|
237
|
+
### 阶段 6:发布与线上验证(尚未完成)
|
|
238
|
+
|
|
239
|
+
- [ ] 发布包含当前修改的新 SDK 版本。
|
|
240
|
+
- [ ] 将客服端依赖和 lock 从 `1.0.378` 升级到新版本。
|
|
241
|
+
- [ ] 重新执行 SDK 运行测试、客服端完整构建和目标环境回归。
|
|
242
|
+
- [ ] 灰度后使用真实 ZIP 日志验证两个客户现象的判定链。
|
|
243
|
+
|
|
244
|
+
## 7. 日志覆盖审计
|
|
245
|
+
|
|
246
|
+
### 7.1 覆盖结论
|
|
247
|
+
|
|
248
|
+
当前前端日志已经可以定位到“问题发生在页面初始化、Socket、消息分发、会话补建、reload、本地缓存、历史合并、已读请求或断线补拉中的哪一段”。对于前端竞态和过滤路径,可以形成较完整证据链。
|
|
249
|
+
|
|
250
|
+
但只靠前端日志不能证明后端的精确推送时间、消息落库时间、会话 upsert 时间和 ACK 接收结果。因此可以判断“前端已收到但接口仍返回空”或“会话接口连续 60 秒为空”,不能继续断言是 MQ 延迟、数据库失败还是后端会话更新失败。最终端到端定责仍需以后补充后端 messageId 关联日志。
|
|
251
|
+
|
|
252
|
+
| 场景 | 当前日志 | 能否定位 | 判定依据 |
|
|
253
|
+
|---|---|---|---|
|
|
254
|
+
| 页面初始化失败后仍进入 Chat | `page_boot/user_init_result/common_setting_init_result/page_init_failed/page_ready/sdk_ready` | 可以 | 直接看到失败阶段、`dbReady` 和是否继续 ready |
|
|
255
|
+
| Socket 断开或 signin 失败后未恢复 | `diagnostic:socket_state` | 可以 | 按 `connectionGeneration` 检查 close/error 后是否出现 reconnect、native_open、signin_success |
|
|
256
|
+
| Socket 根本没有收到目标消息 | `client-chat-socket:receiveMessage` | 前端边界可定位 | 日志中没有 messageId;需后端推送日志判断是后端未推还是网络层未达 |
|
|
257
|
+
| Socket 收到但同步处理抛错 | `client-chat-socket:receiveMessage.processing` | 可以 | 同一条消息直接记录 `failed/errorType` |
|
|
258
|
+
| 消息因乱序或业务规则不触发缓存/提醒 | `diagnostic:message_event_suppressed` | 可以 | `reason` 区分 `out_of_order/auto_read/ignore_session/deleted/blocked`,同时记录 messageId 和时间基准 |
|
|
259
|
+
| 消息缓存没有真正写入 | `diagnostic:message_cache_result` | 可以 | 区分 `success/skipped/failed`;skipped 带 `missing_cache_key/missing_message_time/db_unavailable/send_or_temp_message` |
|
|
260
|
+
| reload 清掉内存后详情为空 | `chat_reload_result` + `message_merge_result` | 可以 | `targetMemoryBefore>0`、`clearedCount>0`、`apiCount=0`、`localMergedCount=0`、`finalTargetCount=0` 构成直接证据 |
|
|
261
|
+
| cache/merge 首次读写竞态 | receive + cache + merge + reload | 可以形成强证据 | 同 messageId reload 前存在;merge 先得到 0;cache 随后成功。该顺序命中当前已证明的竞态窗口 |
|
|
262
|
+
| 历史接口请求失败 | `message_history_failed` + `chat_reload_result` | 可以 | 记录 target、错误类型,reload 同时记录失败及清理后的最终数量 |
|
|
263
|
+
| 会话 60 秒轮询耗尽 | `client-chat-session:getSession` | 可以 | 最终失败日志包含请求次数、空响应数、错误数和约 60 秒耗时 |
|
|
264
|
+
| 会话为何在后端 60 秒仍不可查 | 前端会话轮询日志 | 不完全 | 能证明接口持续空或失败,不能证明后端会话何时 upsert;需后端日志 |
|
|
265
|
+
| 断线补拉失败或水位错误 | `diagnostic:loss_sync_result` | 可以 | 失败保留旧水位;成功记录 returned/inserted/duplicate 和新水位 |
|
|
266
|
+
| 点击会话已读请求失败 | `diagnostic:mark_read_result` | 可以 | 记录 conversationId、`unreadBefore`、请求结果和耗时 |
|
|
267
|
+
| 已读后又出现未读 | mark-read + receive + getSession +账号未读日志 | 大部分可以 | 可判断已读后是否又收到新消息,或 getSession 返回了非零未读;后端 `markAsReadTime/upsert` 精确顺序仍需后端日志 |
|
|
268
|
+
| cmd 异常是否阻断 ACK | processing failed + Socket 发送日志 | 不完全 | 可证明业务异常发生;当前没有 ACK 独立结果和服务端收 ACK 日志,不能端到端确认 |
|
|
269
|
+
| 刷新后恢复 | 两个页面实例的生命周期日志 + messageId 链路 | 可以 | 以 `pageInstanceId` 和 page boot 为边界,对比刷新前 receive/cache/reload 与刷新后 merge/reload |
|
|
270
|
+
|
|
271
|
+
### 7.2 两个客户现象的排查顺序
|
|
272
|
+
|
|
273
|
+
对于“刷新后才出现消息”:
|
|
274
|
+
|
|
275
|
+
1. 用消息 ID 或 msgSvrId 查 `client-chat-socket:receiveMessage`。
|
|
276
|
+
2. 未找到时检查 `socket_state`;Socket 正常则只能定位到前端未收到,需要后端推送日志继续判断。
|
|
277
|
+
3. 已收到时检查 `processing` 和 `message_event_suppressed`。
|
|
278
|
+
4. 本地无会话时检查 `client-chat-session:getSession` 是否成功或 60 秒耗尽。
|
|
279
|
+
5. 发生过断线时检查 `loss_sync_result` 的水位和补拉结果。
|
|
280
|
+
6. 对比刷新前后 page boot,确认消息最终从历史合并还是新的 Socket 推送恢复。
|
|
281
|
+
|
|
282
|
+
对于“显示有消息,点进去为空,稍后又出现未读”:
|
|
283
|
+
|
|
284
|
+
1. 查 `mark_read_result`,确认点击前未读数和已读请求是否成功。
|
|
285
|
+
2. 查 `chat_reload_result`,确认进入前内存是否有消息、是否执行全实例清理及最终是否为空。
|
|
286
|
+
3. 查同 target 的 `message_merge_result`,确认 API 返回数、本地补入数和首尾消息。
|
|
287
|
+
4. 查同 messageId 的 `message_cache_result`;若它晚于空的 merge/reload 成功,支持首次缓存竞态。
|
|
288
|
+
5. 查空详情之后的 receive/getSession/账号未读日志,确认后续未读是新消息、会话延迟更新还是重新加载旧消息。
|
|
289
|
+
6. 若需要判断后端为何迟到,必须结合后端落库、会话 upsert 和 markAsReadTime 日志。
|
|
290
|
+
|
|
291
|
+
### 7.3 日志体量与安全
|
|
292
|
+
|
|
293
|
+
- `chat_reload_result` 每次 reload 一条;`message_event_suppressed` 只在消息不触发外部事件时记录,不增加正常消息的重复日志。
|
|
294
|
+
- 缓存、合并、已读和补拉均是一项操作一条结果,不记录轮询每一轮和心跳成功。
|
|
295
|
+
- 正文只在原 Socket 调试摘要中最多保留前 100 字并记录长度;诊断事件不记录正文。
|
|
296
|
+
- accessToken/token 会删除;不记录完整 URL。
|
|
297
|
+
- 日志使用 3 MB 环形容量,并通过统一 ZIP 一次性导出。
|
|
298
|
+
|
|
299
|
+
## 8. 发布边界
|
|
300
|
+
|
|
301
|
+
- 当前修复只存在于 SDK 工作区,客服端依赖声明仍为 `1.0.378`。需要先发布包含本次修改的新 SDK 版本,再升级客服端依赖并重新构建,线上才会生效。
|
|
302
|
+
- 本机 `node_modules` 为 `1.0.381` 只能用于当前本地验证,不能代表正式构建一定使用该版本。
|
|
303
|
+
- 后续业务逻辑优化应拆分提交和灰度:先 cache/merge 竞态,再会话持续补建,再 reload 原子替换,便于日志判断每一步实际收益。
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
# 消息与会话诊断日志技术方案
|
|
2
|
+
|
|
3
|
+
## 1. 实施顺序
|
|
4
|
+
|
|
5
|
+
1. 目录化 SDK 日志模块并保留旧入口。
|
|
6
|
+
2. 将持久化限定为 IndexedDB,保持数据库 v2。
|
|
7
|
+
3. 实现内部异常隔离、内存队列、批量事务和容量清理。
|
|
8
|
+
4. 增加安全裁剪与新旧记录兼容读取。
|
|
9
|
+
5. 增加按天全量导出 API。
|
|
10
|
+
6. 补齐消息、会话、未读和 Request 链路日志。
|
|
11
|
+
7. 统一 JavaMain-combine 下载入口并完成测试。
|
|
12
|
+
8. 增加运行时异常监听、异常风暴控制和错误日志独立导出。
|
|
13
|
+
|
|
14
|
+
## 2. 兼容入口
|
|
15
|
+
|
|
16
|
+
`utils/log.js` 保留:
|
|
17
|
+
|
|
18
|
+
```js
|
|
19
|
+
export { default } from './log/index'
|
|
20
|
+
export * from './log/index'
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
已有以下用法无需修改:
|
|
24
|
+
|
|
25
|
+
```js
|
|
26
|
+
import Log from '@aochuang/client-sdk/utils/log.js'
|
|
27
|
+
import Log from '../../utils/log'
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## 3. Log 配置
|
|
31
|
+
|
|
32
|
+
```js
|
|
33
|
+
new Log({
|
|
34
|
+
name: 'client_chat',
|
|
35
|
+
console: false,
|
|
36
|
+
indexedDbMaxSize: 200 * 1024 * 1024,
|
|
37
|
+
flushInterval: 300,
|
|
38
|
+
flushThreshold: 50,
|
|
39
|
+
flushBatchSize: 500,
|
|
40
|
+
maxPendingCount: 2000,
|
|
41
|
+
maxPendingBytes: 2 * 1024 * 1024
|
|
42
|
+
})
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
`maxSize` 仅作为旧调用参数保留,不再切换到 localStorage。
|
|
46
|
+
|
|
47
|
+
## 4. addLog 语义
|
|
48
|
+
|
|
49
|
+
```js
|
|
50
|
+
addLog (input) {
|
|
51
|
+
try {
|
|
52
|
+
const log = createLog(input)
|
|
53
|
+
if (this.beforeAddCallback && this.beforeAddCallback({ data: log }) === false) {
|
|
54
|
+
return
|
|
55
|
+
}
|
|
56
|
+
const record = createRecord(log)
|
|
57
|
+
this.enqueue(record)
|
|
58
|
+
return log
|
|
59
|
+
} catch (error) {
|
|
60
|
+
this._recordInternalFailure(error)
|
|
61
|
+
return
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
调用方无需 try/catch。内部错误只增加内存计数,不再调用 logger 记录自身错误。
|
|
67
|
+
|
|
68
|
+
## 5. 安全编码
|
|
69
|
+
|
|
70
|
+
SDK 最终编码处理:
|
|
71
|
+
|
|
72
|
+
- 对象中的 `undefined` 属性直接省略,数组中的 `undefined` 转为 `null`;function、symbol 使用占位符。
|
|
73
|
+
- BigInt 转十进制字符串并标记类型。
|
|
74
|
+
- Error 提取 name、message、code 和有界 stack;运行时异常入口进一步限制为前 10 帧、最多 4000 字符。
|
|
75
|
+
- Date 转 ISO 字符串。
|
|
76
|
+
- 循环引用转 `[circular]`。
|
|
77
|
+
- File、Blob 和二进制转占位符。
|
|
78
|
+
- getter 或 Proxy 读取异常转 `[unavailable]`。
|
|
79
|
+
|
|
80
|
+
Request 层在进入 logger 前执行更严格规则:
|
|
81
|
+
|
|
82
|
+
```js
|
|
83
|
+
truncate('...2480 chars...') === '前100字符...+2380'
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
整体大小超限时返回带 `[truncated]` 的有限预览,不对原始大对象先做 JSON.stringify。
|
|
87
|
+
|
|
88
|
+
## 6. Request 接入
|
|
89
|
+
|
|
90
|
+
请求拦截器生成:
|
|
91
|
+
|
|
92
|
+
```js
|
|
93
|
+
config.__diagnosticLog = {
|
|
94
|
+
requestId,
|
|
95
|
+
startedAt: Date.now(),
|
|
96
|
+
attempt: (config.retryCount || 0) + 1
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
请求开始记录 method、path、裁剪后的 params/data。响应拦截器在返回业务数据前记录 status、duration、result、traceid 和裁剪后的 response data。失败、取消和 429 重试沿用同一个 requestId。
|
|
101
|
+
|
|
102
|
+
Request 日志调用不 await IndexedDB:
|
|
103
|
+
|
|
104
|
+
```js
|
|
105
|
+
requestLogger.addLog(...)
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## 7. 消息与会话链路
|
|
109
|
+
|
|
110
|
+
消息事件至少包含:
|
|
111
|
+
|
|
112
|
+
- `message_received`
|
|
113
|
+
- `message_received_suppressed`(仅 Socket 通知过滤时)
|
|
114
|
+
- `message_rejected` 或 `message_stored`
|
|
115
|
+
- `message_event_suppressed` 或 `message_event_emitted`
|
|
116
|
+
- `message_session_update_failed`(仅会话更新回调异常时)
|
|
117
|
+
- `session_resolved`
|
|
118
|
+
- `session_unread_changed`
|
|
119
|
+
- `loss_sync_result`
|
|
120
|
+
|
|
121
|
+
会话事件至少包含:
|
|
122
|
+
|
|
123
|
+
- `session_list_requested`
|
|
124
|
+
- `session_list_applied` 或 `session_list_failed`
|
|
125
|
+
- `session_poll_started`、`session_poll_completed`、`session_poll_failed`
|
|
126
|
+
- `session_read_requested`、`session_read_applied`、`session_read_failed`
|
|
127
|
+
- `account_unread_changed`
|
|
128
|
+
- `account_unread_refresh_failed`(仅服务端刷新失败时)
|
|
129
|
+
|
|
130
|
+
消息高频链路固定使用 `messageId`、`msgSvrId`、`sessionId` 关联。Socket 的 `message_received` 保存完整 `friendMessage/chatroomMessage`、关联 ID 和 `result/errorType`;通知过滤时由 `message_received_suppressed` 保存同一份快照,两个事件互斥。后续消息节点不重复写账号、目标、类型、正文和可从事件名推导的布尔状态。账号未读刷新成功继续使用已有变化日志,失败才增加一条失败事件。
|
|
131
|
+
|
|
132
|
+
## 8. 页面启动上下文
|
|
133
|
+
|
|
134
|
+
入口调用:
|
|
135
|
+
|
|
136
|
+
```js
|
|
137
|
+
addDiagnosticLog('page_boot', getPageBootContext(navigationType))
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
`page_boot` 每个页面实例只执行一次,环境字段不含 URL query/hash。用户信息成功后在既有 `user_init_result` 中记录登录账号 ID、用户名、姓名和租户 ID,不保存 account/tenant 原始对象、Token、Cookie 或密码。
|
|
141
|
+
|
|
142
|
+
所有诊断事件仍共享 `pageInstanceId` 和 `pageSequence`;`appVersion` 仅属于 `page_boot`,删除每条事件的 `pageAgeMs`。
|
|
143
|
+
|
|
144
|
+
## 9. 导出 API
|
|
145
|
+
|
|
146
|
+
保留兼容 API:
|
|
147
|
+
|
|
148
|
+
```js
|
|
149
|
+
logger.exportLogData() // { size, data }
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
新增下载专用 API:
|
|
153
|
+
|
|
154
|
+
```js
|
|
155
|
+
logger.exportLogFiles() // [{ day, count, size, content: Blob }]
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
`exportLogFiles()` 直接使用记录 payload 组成紧凑 JSON Blob。旧记录临时编码,不修改数据库版本。
|
|
159
|
+
|
|
160
|
+
错误日志下载使用:
|
|
161
|
+
|
|
162
|
+
```js
|
|
163
|
+
logger.exportLogFiles({ separateErrorLogs: true })
|
|
164
|
+
// [{ day, type: 'operation' | 'error', count, size, content }]
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
前端按 `type` 写入 `操作日志/` 或 `错误日志/`。错误记录只属于 error 分组,不复制到 operation 分组。
|
|
168
|
+
|
|
169
|
+
## 10. 运行时异常接入
|
|
170
|
+
|
|
171
|
+
`runtime-error.js` 在 Vue 根实例创建前安装:
|
|
172
|
+
|
|
173
|
+
```js
|
|
174
|
+
window.addEventListener('error', handleWindowError)
|
|
175
|
+
window.addEventListener('unhandledrejection', handleUnhandledRejection)
|
|
176
|
+
Vue.config.errorHandler = handleVueError
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
统一调用 `captureDiagnosticError(source, error, context)`,生成错误指纹并进行 5 秒去重与每分钟 30 个不同错误的限流。监听器不调用 `preventDefault()`;已有 Vue errorHandler 会在记录后继续执行,没有旧 handler 时保持控制台错误输出。
|
|
180
|
+
|
|
181
|
+
Axios 失败先生成 `request_failed`,再通过不可枚举 `__aochuangRequestErrorLogged__` 标记原始错误。`runtime-error.js` 在标准化异常前检查该标记,并兼容识别带 `isAxiosError + config.__diagnosticLog` 的错误;命中后直接跳过。该标记不会被对象遍历或日志序列化导出。网络失败路径必须先判断 response 是否存在,再访问 `response.config`。
|
|
182
|
+
|
|
183
|
+
## 11. 测试方案
|
|
184
|
+
|
|
185
|
+
- 1000 条连续 addLog 的事务次数与顺序。
|
|
186
|
+
- addLog 输入循环引用、BigInt、异常 getter、File、Blob。
|
|
187
|
+
- beforeAdd 回调、JSON 编码、IndexedDB put 和清理游标异常。
|
|
188
|
+
- 队列阈值、定时 flush、页面隐藏 flush 和连续失败退避。
|
|
189
|
+
- 50MB 旧记录读取与 200MB 新上限清理。
|
|
190
|
+
- 新旧记录混合导出、跨天拆分和 JSON 合法性。
|
|
191
|
+
- Request 成功、业务失败、网络失败、取消、重试和 traceid。
|
|
192
|
+
- undefined 对象字段省略、数组 undefined 转 null,以及请求失败不重复进入 runtime_error。
|
|
193
|
+
- 消息重复、乱序、无会话轮询、断线补偿和已读失败链路。
|
|
194
|
+
- 页面刷新环境、登录账号关联、消息正文不重复、Socket 过滤、会话更新异常和账号未读刷新失败。
|
|
195
|
+
- window error、unhandled rejection、Vue errorHandler 和非 Error Promise reason。
|
|
196
|
+
- 同一错误连续触发、每分钟大量不同错误和日志器自身抛错。
|
|
197
|
+
- 错误与操作日志按天互斥拆分、旧记录分类兼容和默认导出 API 兼容。
|
|
198
|
+
|
|
199
|
+
## 12. 发布
|
|
200
|
+
|
|
201
|
+
SDK 完成测试后发布新版本;JavaMain-combine 更新 package.json 和 package-lock.json,不直接修改 node_modules。前端使用正式依赖完成构建与浏览器验证。
|