@aochuang/client-sdk 1.0.366 → 1.0.368

package/package.json

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

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

@@ -30,7 +30,8 @@ export default class ClientChatAccount {
 			onAccountRemoved: null,
 			onUnreadMessageNumChange: null,
 			onDeleteAccountSession: null,
-			onAccountLoaded: null
+			onAccountLoaded: null,
+			onUnreadMessageNumLog: null
 		}, options)
 		if (!options.loadAccountDataMethod) {
 			throw new Error('缺少loadAccountDataMethod配置')
@@ -51,6 +52,19 @@ export default class ClientChatAccount {
 		this.onUnreadMessageNumChange = options.onUnreadMessageNumChange
 		this.onDeleteAccountSession = options.onDeleteAccountSession
 		this.onAccountLoaded = options.onAccountLoaded
+		this.onUnreadMessageNumLog = options.onUnreadMessageNumLog
+	}
+
+	_addUnreadMessageNumLog (title, data) {
+		if (this.onUnreadMessageNumLog) {
+			this.onUnreadMessageNumLog({
+				group: 'client-chat-account:unreadMessageNum',
+				content: {
+					title,
+					data
+				}
+			})
+		}
 	}
 	
 	get accountData () {
@@ -198,6 +212,10 @@ export default class ClientChatAccount {
 				})
 			}
 			this.data.accountUnreadMessageNumData = nextData
+			this._addUnreadMessageNumLog('服务端全量刷新账号未读数量', {
+				source: 'refreshAll',
+				accounts: nextData
+			})
 		})
 	}
 	
@@ -216,23 +234,33 @@ export default class ClientChatAccount {
 					return true
 				}
 			})
+			const before = index >= 0 ? this.data.accountUnreadMessageNumData[index] : null
+			const after = {
+				id: wechatAccountId,
+				num: rs.data[0].unread || 0,
+				muteNum: rs.data[0].muteUnread || 0
+			}
 			if (index >= 0) {
-				this.data.accountUnreadMessageNumData.splice(index, 1, {
-					id: wechatAccountId,
-					num: rs.data[0].unread || 0,
-					muteNum: rs.data[0].muteUnread || 0
-				})
+				this.data.accountUnreadMessageNumData.splice(index, 1, after)
 			} else {
-				this.data.accountUnreadMessageNumData.push({
-					id: wechatAccountId,
-					num: rs.data[0].unread || 0,
-					muteNum: rs.data[0].muteUnread || 0
-				})
+				this.data.accountUnreadMessageNumData.push(after)
 			}
+			this._addUnreadMessageNumLog('服务端刷新账号未读数量', {
+				source: 'refresh',
+				wechatAccountId,
+				before: before ? { num: before.num, muteNum: before.muteNum } : null,
+				after: { num: after.num, muteNum: after.muteNum }
+			})
 		})
 	}
 	
-	updateAccountUnreadMessageNum (accountId, callback) {
+	/**
+	 * 本地增量更新账号未读数量
+	 * @param { String } accountId
+	 * @param { Function } callback 返回 { num, muteNum }
+	 * @param { String } source 调用来源标记，仅用于日志排查
+	 */
+	updateAccountUnreadMessageNum (accountId, callback, source) {
 		return this.getAccount(accountId).then(rs => {
 			if (!rs || !rs.data) {
 				console.warn('未找到' + accountId + '工作微信号')
@@ -248,11 +276,26 @@ export default class ClientChatAccount {
 					return true
 				}
 			})
+			const beforeNum = unreadMessageNumIndex >= 0 ? this.data.accountUnreadMessageNumData[unreadMessageNumIndex].num : 0
+			const beforeMuteNum = unreadMessageNumIndex >= 0 ? this.data.accountUnreadMessageNumData[unreadMessageNumIndex].muteNum : 0
 			const nextReadMessageNum = callback({
 				account: rs.data,
-				unreadMesasgeNum: unreadMessageNumIndex >= 0 ? this.data.accountUnreadMessageNumData[unreadMessageNumIndex].num : 0,
-				unreadMessageMuteNum: unreadMessageNumIndex >= 0 ? this.data.accountUnreadMessageNumData[unreadMessageNumIndex].muteNum : 0
+				unreadMesasgeNum: beforeNum,
+				unreadMessageMuteNum: beforeMuteNum
 			})
+			if (this.onUnreadMessageNumLog && nextReadMessageNum !== undefined && nextReadMessageNum !== null) {
+				const afterNum = typeof nextReadMessageNum === 'object' ? nextReadMessageNum.num : nextReadMessageNum
+				const afterMuteNum = typeof nextReadMessageNum === 'object' ? nextReadMessageNum.muteNum : beforeMuteNum
+				if (afterNum !== beforeNum || afterMuteNum !== beforeMuteNum) {
+					this._addUnreadMessageNumLog('本地增量更新账号未读数量', {
+						source: source || 'unknown',
+						wechatAccountId: accountId,
+						before: { num: beforeNum, muteNum: beforeMuteNum },
+						after: { num: afterNum, muteNum: afterMuteNum },
+						delta: { num: (afterNum || 0) - (beforeNum || 0), muteNum: (afterMuteNum || 0) - (beforeMuteNum || 0) }
+					})
+				}
+			}
 			if (nextReadMessageNum && typeof nextReadMessageNum === 'object') {
 				/**
 				 * {

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

@@ -610,6 +610,10 @@ export default class ClientChatMessage {
 		if (!groupField || !messageTime || (message && message.msgType === '_EMPTY_')) {
 			return
 		}
+		// 临时占位消息的wechatTime是浏览器本地时间，和手机端的消息时间不是同一个时钟，不能作为判断旧消息的基准，否则时钟偏差会导致对方紧接着的回复被当成旧消息过滤掉
+		if (message && message._temp) {
+			return
+		}
 		const lastMessageTime = this.getLastMessageTime(groupField)
 		if (!lastMessageTime || messageTime > lastMessageTime) {
 			this.lastMessageTimeMap[groupField] = messageTime

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

@@ -311,11 +311,22 @@ export default class ClientChatSession {
 			if (!rs.data) {
 				return Promise.reject('未找到会话' + sessionId)
 			}
+			/**
+			 * 轮询合并上下文，会依次传给每个 serializeMethod（见 client-chat.js onCmdNewMessage 里 getSession 的回调）
+			 * baseLastMsgTime     服务端返回的会话 lastMsgTime，用来判断某条消息服务端是否已经算进 unreadMsgCount
+			 * processedMessageIds 本次轮询期间处理过的所有消息 id
+			 * skippedMessageIds   服务端返回的会话已经包含（wechatTime <= baseLastMsgTime）、本地不再给会话未读 +1 的消息 id
+			 * unreadMessageIds    本地给会话未读 +1 的消息 id
+			 * accountUnreadDelta  本次轮询期间需要累加到工作微信号（账号）未读数量上的条数。
+			 *                     注意它和 unreadMessageIds.length 不同：账号未读初始值是登录时取的，不包含本次收到的任何消息，
+			 *                     所以被 skip 的消息也要算进来；只有"正在看当前会话被直接标记已读"的消息不算
+			 */
 			const context = {
 				baseLastMsgTime: rs.data.lastMsgTime || 0,
 				processedMessageIds: [],
 				skippedMessageIds: [],
-				unreadMessageIds: []
+				unreadMessageIds: [],
+				accountUnreadDelta: 0
 			}
 			const serializeTasks = pollRequest.serializeTasks.slice().sort((a, b) => {
 				return a.wechatTime - b.wechatTime || a.index - b.index
@@ -326,7 +337,11 @@ export default class ClientChatSession {
 					context.processedMessageIds.push(task.messageId)
 				}
 			})
-			this.addSession(rs.data, null)
+			// wechatAccountId 传 null 表示非分页来源，onAddSession 会把未读同步到账号；
+			// 同时带上 unreadDelta，让账号只累加本次新增的条数，而不是服务端返回的整个 unreadMsgCount（那里面的存量部分账号初始值已经包含了）
+			this.addSession(rs.data, null, {
+				unreadDelta: context.accountUnreadDelta
+			})
 			const wechatAccountId = rs.data.wechatAccountId
 			this._addGetSessionLog('会话轮询合并完成', {
 				sessionId,
@@ -341,6 +356,7 @@ export default class ClientChatSession {
 				processedMessageCount: context.processedMessageIds.length,
 				skippedMessageCount: context.skippedMessageIds.length,
 				unreadMessageCount: context.unreadMessageIds.length,
+				accountUnreadDelta: context.accountUnreadDelta,
 				hasSessionMap: !!this.sessionMap[sessionId],
 				hasAllSessionGroup: !!this._getSessionBySessionGroup(sessionId, ALL_WECHAT_ACCOUNT_ID),
 				hasAccountSessionGroup: !!this._getSessionBySessionGroup(sessionId, wechatAccountId)
@@ -486,8 +502,10 @@ export default class ClientChatSession {
 	 *		"unreadMsgCount": 3,
 	 *		"wechatAccountId": "2a39a725814acf07502299ab2285fff8d44377f5"
 	 *	}
+	 * @params { Object } - options
+	 * @params { Number } - options.unreadDelta 本次新增的未读条数，新消息触发getSession拉回会话时传入，用于账号未读数量只累加新增部分而不是整个unreadMsgCount
 	*/
-	addSession (data, wechatAccountId) {
+	addSession (data, wechatAccountId, options = {}) {
 		if (!data || !data.conversationId) {
 			throw new Error('缺少必须参数conversationId')
 		}
@@ -591,7 +609,8 @@ export default class ClientChatSession {
 		}
 		this.onAddSession && this.onAddSession({
 			wechatAccountId,
-			session: nextData
+			session: nextData,
+			unreadDelta: options.unreadDelta
 		})
 	}
 

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

@@ -115,23 +115,42 @@ class ClientChat {
 		const mergeSessionCommonOptions = (options, instance) => {
 			let updateSessioning = false
 			let removeSessioning = false
-			options.onAddSession = ({ session, wechatAccountId }) => {
+			/**
+			 * 会话新增回调，负责把新增会话的未读数量同步到工作微信号（账号）的未读数量上
+			 * @param { Object } session - 新增的会话
+			 * @param { String } wechatAccountId - 有值代表是分页加载（loadData/reload）来的会话，账号未读初始值已经包含，不累加
+			 * @param { Number } unreadDelta - 本次真正新增的未读条数，只有新消息触发 getSession 拉回会话时才会传（见 client-chat-session.js getSession）
+			 *
+			 * 账号未读数量的初始值来自登录时的 getAccountUnreadMessageNumMethod，是服务端按该账号"所有会话"算的，
+			 * 不管本地有没有分页加载到这些会话。所以非分页来源的会话要区分两种情况：
+			 *   1. 分配过来的会话（loadAssignTaskSessionData）：之前不属于这个账号，账号初始值里没有它，
+			 *      需要把整个 session.unreadMsgCount 累加上去。此时 unreadDelta 为 undefined。
+			 *   2. 新消息触发 getSession 拉回来的会话：一直属于这个账号，只是本地没翻页加载到，它的存量未读已经在账号初始值里了，
+			 *      如果再把整个 unreadMsgCount 加上去就会重复计算存量部分（这就是"会话都已读了但账号还有未读数、刷新后归零"的主因）。
+			 *      这种情况只能累加本次轮询期间新增的条数，即 unreadDelta。
+			 */
+			options.onAddSession = ({ session, wechatAccountId, unreadDelta }) => {
 				// 不是来源于分页的时候，没有wechatAccountId就是代表不是走的分页增加的会话，一般为获取新消息或则分配的会话
 				if (!wechatAccountId && instance === this.session) {
-					// 更新账号未读消息数量
-					this.account.updateAccountUnreadMessageNum(session.wechatAccountId, ({ unreadMesasgeNum, unreadMessageMuteNum }) => {
-						if (session.mute) {
-							return {
-								num: (unreadMesasgeNum || 0) + (session.unreadMsgCount || 0),
-								muteNum: (unreadMessageMuteNum || 0) + (session.unreadMsgCount || 0)
-							}
-						} else {
-							return {
-								num: (unreadMesasgeNum || 0) + (session.unreadMsgCount || 0),
-								muteNum: unreadMessageMuteNum
+					// unreadDelta 是数字 → getSession 来源，只加新增；否则 → 分配等来源，整个 unreadMsgCount 加上
+					const delta = typeof unreadDelta === 'number' ? unreadDelta : (session.unreadMsgCount || 0)
+					// delta 为 0 时不更新，避免产生无意义的账号未读更新和日志
+					if (delta > 0) {
+						// 更新账号未读消息数量
+						this.account.updateAccountUnreadMessageNum(session.wechatAccountId, ({ unreadMesasgeNum, unreadMessageMuteNum }) => {
+							if (session.mute) {
+								return {
+									num: (unreadMesasgeNum || 0) + delta,
+									muteNum: (unreadMessageMuteNum || 0) + delta
+								}
+							} else {
+								return {
+									num: (unreadMesasgeNum || 0) + delta,
+									muteNum: unreadMessageMuteNum
+								}
 							}
-						}
-					})
+						}, typeof unreadDelta === 'number' ? 'onAddSession:getSession' : 'onAddSession')
+					}
 				}
 				// 同步未读会话
 				if (instance !== this.sessionUnread && session.unreadMsgCount > 0) {
@@ -231,7 +250,7 @@ class ClientChat {
 								muteNum: unreadMessageMuteNum
 							}
 						}
-					})
+					}, 'onRemoveSession')
 					// 删除会话会同步删除所有的实例，所以需要做这个检查
 					if (this.sessionManage.currentSession && this.sessionManage.currentSession.conversationId === session.conversationId) {
 						this.sessionManage.setCurrentSession(null)
@@ -287,7 +306,7 @@ class ClientChat {
 							muteNum: unreadMessageMuteNum
 						}
 					}
-				})
+				}, 'onSessionReadChange')
 			}
 		}
 		this.session = new ClientChatSession({
@@ -445,8 +464,12 @@ class ClientChat {
 								rs.data.lastMsgId = data.id
 								rs.data.lastUpdateTime = data.updateDate
 							}
+							// 正在看这个会话并且允许自动标记已读
+							const isCurrentSessionRead = this.sessionManage.currentSession && this.sessionManage.currentSession.conversationId === sessionId && this.shouldMarkCurrentSessionRead(sessionId, data)
+							// 会话未读数量：isAfterServerMessage 为 true 表示这条消息比服务端返回的会话 lastMsgTime 新，
+							// 服务端返回的 unreadMsgCount 还没算它，需要本地 +1；否则服务端已经算进去了，skip 掉避免重复
 							if (!data.isSend && isAfterServerMessage) {
-								if (this.sessionManage.currentSession && this.sessionManage.currentSession.conversationId === sessionId && this.shouldMarkCurrentSessionRead(sessionId, data)) {
+								if (isCurrentSessionRead) {
 									rs.data.unreadMsgCount = 0
 								} else {
 									rs.data.unreadMsgCount = (rs.data.unreadMsgCount || 0) + 1
@@ -455,6 +478,13 @@ class ClientChat {
 							} else {
 								context.skippedMessageIds.push(data.id)
 							}
+							// 账号未读数量：和会话未读数量的判断口径不一样。
+							// 账号未读初始值是登录时从服务端取的，不包含这条新消息，所以不管这条消息有没有被服务端算进会话的 unreadMsgCount（即不管是否被 skip），
+							// 账号都要 +1。唯一不加的情况是"正在看当前会话并被直接标记已读"（此时会话未读被置 0，不会再通过 onSessionReadChange 扣减账号）。
+							// 这个累计值会通过 addSession(rs.data, null, { unreadDelta }) 传给 onAddSession，账号只累加这个增量而不是整个 unreadMsgCount
+							if (!data.isSend && !(isAfterServerMessage && isCurrentSessionRead)) {
+								context.accountUnreadDelta += 1
+							}
 						}
 						return rs
 					}, {
@@ -496,7 +526,7 @@ class ClientChat {
 											muteNum: unreadMessageMuteNum
 										}
 									}
-								})
+								}, 'onNewFriendMessage')
 							}
 						}
 						return nextSession
@@ -581,8 +611,12 @@ class ClientChat {
 								rs.data.lastMsgId = data.id
 								rs.data.lastUpdateTime = data.updateDate
 							}
+							// 正在看这个会话并且允许自动标记已读
+							const isCurrentSessionRead = this.sessionManage.currentSession && this.sessionManage.currentSession.conversationId === sessionId && this.shouldMarkCurrentSessionRead(sessionId, data)
+							// 会话未读数量：isAfterServerMessage 为 true 表示这条消息比服务端返回的会话 lastMsgTime 新，
+							// 服务端返回的 unreadMsgCount 还没算它，需要本地 +1；否则服务端已经算进去了，skip 掉避免重复
 							if (!data.isSend && isAfterServerMessage) {
-								if (this.sessionManage.currentSession && this.sessionManage.currentSession.conversationId === sessionId && this.shouldMarkCurrentSessionRead(sessionId, data)) {
+								if (isCurrentSessionRead) {
 									rs.data.unreadMsgCount = 0
 								} else {
 									rs.data.unreadMsgCount = (rs.data.unreadMsgCount || 0) + 1
@@ -594,6 +628,13 @@ class ClientChat {
 							} else {
 								context.skippedMessageIds.push(data.id)
 							}
+							// 账号未读数量：和会话未读数量的判断口径不一样。
+							// 账号未读初始值是登录时从服务端取的，不包含这条新消息，所以不管这条消息有没有被服务端算进会话的 unreadMsgCount（即不管是否被 skip），
+							// 账号都要 +1。唯一不加的情况是"正在看当前会话并被直接标记已读"（此时会话未读被置 0，不会再通过 onSessionReadChange 扣减账号）。
+							// 这个累计值会通过 addSession(rs.data, null, { unreadDelta }) 传给 onAddSession，账号只累加这个增量而不是整个 unreadMsgCount
+							if (!data.isSend && !(isAfterServerMessage && isCurrentSessionRead)) {
+								context.accountUnreadDelta += 1
+							}
 						}
 						return rs
 					}, {
@@ -638,7 +679,7 @@ class ClientChat {
 											muteNum: unreadMessageMuteNum
 										}
 									}
-								})
+								}, 'onNewRoomMessage')
 							}
 						}
 						return nextSession
@@ -748,6 +789,26 @@ class ClientChat {
 			getAccountGreetingUnreadMsgCountMethod: options.getAccountGreetingUnreadMsgCountMethod,
 			batchGetAccountGreetingUnreadMsgCountMethod: options.batchGetAccountGreetingUnreadMsgCountMethod,
 			clearAccountGreetingUnreadMsgCountMethod: options.clearAccountGreetingUnreadMsgCountMethod,
+			// 账号未读数量变化日志，附带该账号本地会话未读之和，用于排查账号未读数和会话未读数不一致的问题
+			onUnreadMessageNumLog: (log) => {
+				if (!this.socket) {
+					return
+				}
+				const wechatAccountId = log.content && log.content.data && log.content.data.wechatAccountId
+				if (wechatAccountId && this.session) {
+					log.content.data.localSessionUnread = Object.keys(this.session.sessionMap).reduce((rs, id) => {
+						const session = this.session.sessionMap[id]
+						if (session && session.wechatAccountId === wechatAccountId) {
+							rs.num += session.unreadMsgCount || 0
+							if (session.mute) {
+								rs.muteNum += session.unreadMsgCount || 0
+							}
+						}
+						return rs
+					}, { num: 0, muteNum: 0 })
+				}
+				this.socket.addLog(log)
+			},
 			onAccountAdded: ({ account }) => {
 				return this.account.refreshAccountUnreadMessageNum({
 					wechatAccountId: account.id
@@ -919,25 +980,10 @@ class ClientChat {
 										return this.contacts.getFriend(sessionFriendId, true)
 									})
 								}
-								// 刷新工作微信号未读消息数量
-								if (rs && rs.length) {
-									rs.forEach(session => {
-										this.account.updateAccountUnreadMessageNum(session.wechatAccountId, ({ unreadMesasgeNum, unreadMessageMuteNum }) => {
-											if (session.mute) {
-												return {
-													num: (unreadMesasgeNum || 0) + (session.unreadMsgCount || 0),
-													muteNum: (unreadMessageMuteNum || 0) + (session.unreadMsgCount || 0)
-												}
-											} else {
-												return {
-													num: (unreadMesasgeNum || 0) + (session.unreadMsgCount || 0),
-													muteNum: unreadMessageMuteNum
-												}
-											}
-										})
-									})
-								}
+								// 分配会话的未读数量已经在onAddSession里累加到工作微信号上了，这里不再重复累加
+								// 转移/删除的好友如果本地没有加载到对应会话，本地是无法扣减的，所以统一以服务端为准刷新一次
 								return ps.finally(() => {
+									this.refreshAccountsUnreadMessageNum([].concat(wechatAccountIds, data.wechatAccountIds || []))
 									// 这里应该标记那些工作微信号的通讯录修改了，后面要在界面打个提示，告诉用户通讯录变化了，让手动刷新一下
 									// 同时也将缓存都清理一下，例如工作微信号分组统计数量等
 									this.contacts.markModify() // 标记通讯录修改
@@ -963,6 +1009,8 @@ class ClientChat {
 								this.session.removeSession(session.conversationId)
 							}
 						}
+						// 本地没有加载到该会话时无法扣减未读数量，以服务端为准刷新一次
+						this.refreshAccountsUnreadMessageNum(data.wechatAccountIds)
 						// todo 刷新一下微信号，如果微信号一个好友都没了，应该要删除掉的
 						this.contacts.markModify() // 标记通讯录修改
 					} 
@@ -1001,25 +1049,10 @@ class ClientChat {
 								ps = this.account.reloadData()
 							}
 						}
-						// 刷新工作微信号未读消息数量
-						if (rs && rs.length) {
-							rs.forEach(session => {
-								this.account.updateAccountUnreadMessageNum(session.wechatAccountId, ({ unreadMesasgeNum, unreadMessageMuteNum }) => {
-									if (session.mute) {
-										return {
-											num: (unreadMesasgeNum || 0) + (session.unreadMsgCount || 0),
-											muteNum: (unreadMessageMuteNum || 0) + (session.unreadMsgCount || 0)
-										}
-									} else {
-										return {
-											num: (unreadMesasgeNum || 0) + (session.unreadMsgCount || 0),
-											muteNum: unreadMessageMuteNum
-										}
-									}
-								})
-							})
-						}
+						// 分配会话的未读数量已经在onAddSession里累加到工作微信号上了，这里不再重复累加
+						// 转移/删除的群聊如果本地没有加载到对应会话，本地是无法扣减的，所以统一以服务端为准刷新一次
 						return ps.finally(() => {
+							this.refreshAccountsUnreadMessageNum([].concat(wechatAccountIds, data.wechatAccountIds || []))
 							// 这里应该标记那些工作微信号的通讯录修改了，后面要在界面打个提示，告诉用户通讯录变化了，让手动刷新一下
 							// 同时也将缓存都清理一下，例如工作微信号分组统计数量等
 							this.contacts.markModify() // 标记通讯录修改
@@ -1043,6 +1076,8 @@ class ClientChat {
 					}
 					// 删除群聊
 					this.contacts.removeRoom(data.wechatChatroomId)
+					// 本地没有加载到该会话时无法扣减未读数量，以服务端为准刷新一次
+					this.refreshAccountsUnreadMessageNum(data.wechatAccountIds)
 				} 
 				// 更新群聊
 				else {
@@ -1080,6 +1115,8 @@ class ClientChat {
 					wechatAccountId: data.wechatAccountId,
 					unreadGreetingMsgCount: data.unreadGreetingMsgCount
 				})
+				// 刷新所有微信号请求数量
+				this.account.getAccountGreetingUnreadMsgCount()
 			},
 			onCmdNewFriendRequest: ({ data }) => {
 				// 刷新指定微信号请求数量
@@ -1151,6 +1188,10 @@ class ClientChat {
 				Promise.all(ps).finally(() => {
 					this.friendMessage.setLastReceiveMessageTime(Date.now())
 					this.roomMessage.setLastReceiveMessageTime(Date.now())
+					// 断线期间本地增量可能和服务端产生偏差（其他端已读、消息延迟等），重连后以服务端为准全量校准一次
+					if (ps.length) {
+						this.account.refreshAllAccountUnreadMesageNum()
+					}
 				})
 			}, 
 			onSocketClose: (evt) => {
@@ -1205,6 +1246,17 @@ class ClientChat {
 		this.shouldMarkCurrentSessionReadMethod = method
 	}
 
+	/**
+	 * 以服务端为准刷新指定工作微信号的未读消息数量，用于本地增量无法处理的场景（例如本地未加载到的会话被删除/转移）
+	 * @param { Array<String> } wechatAccountIds
+	 */
+	refreshAccountsUnreadMessageNum (wechatAccountIds) {
+		const ids = Array.from(new Set((wechatAccountIds || []).filter(id => id && this.account.accountMap[id])))
+		ids.forEach(wechatAccountId => {
+			this.account.refreshAccountUnreadMessageNum({ wechatAccountId })
+		})
+	}
+
 	shouldMarkCurrentSessionRead (sessionId, data) {
 		if (typeof this.shouldMarkCurrentSessionReadMethod === 'function') {
 			return this.shouldMarkCurrentSessionReadMethod({

package/services/client-chat/client-chat-wechat/docs//350/264/246/345/217/267/346/234/252/350/257/273/346/225/260/351/207/217/344/270/216/344/274/232/350/257/235/346/234/252/350/257/273/346/225/260/351/207/217/344/270/215/344/270/200/350/207/264/351/227/256/351/242/230/344/277/256/345/244/215.md

@@ -0,0 +1,296 @@
+# 工作微信号未读数量与会话未读数量不一致问题修复
+
+- 日期：2026-09-29
+- 涉及文件：
+  - `services/client-chat/client-chat-wechat/client-chat.js`
+  - `services/client-chat/client-chat-wechat/client-chat-session.js`
+  - `services/client-chat/client-chat-wechat/client-chat-account.js`
+- 相关提交：`2679dd9`（A2 / A4 / B1 / D），A1 为后续单独提交
+
+---
+
+## 1. 问题现象
+
+客户端左侧工作微信号徽标显示有未读（例如 8），但右侧"最近会话"里除免打扰会话外已经没有任何未读会话；刷新页面后，从服务端重新拉取的账号未读数量为 0。
+
+即：**本地账号未读数 > 服务端账号未读数，且本地会话未读之和为 0**。
+
+---
+
+## 2. 根因分析
+
+SDK 里维护着两套彼此独立的本地"账本"：
+
+| 账本 | 初始值 | 增量维护 |
+|---|---|---|
+| 账号未读数（`account.accountUnreadMessageNumData`） | 登录时 `getAccountUnreadMessageNumMethod`，服务端按该账号**所有会话**（不管本地是否加载）计算 | 本地 ±N |
+| 会话未读数（`session.sessionMap[id].unreadMsgCount`） | 分页拉会话列表时服务端给的 | 本地 ±1 |
+
+账号未读数只有两处减法，都是按**本地会话**的 `unreadMsgCount` 减：
+
+- `onSessionReadChange`：会话被标记已读
+- `onRemoveSession`：会话被移除
+
+所以，凡是"加到账号上的数，没有等量落到某个本地会话的 `unreadMsgCount` 上"的路径，都会在账号上留下永远减不掉的残数。再加上所有减法都用了 `Math.max(0, …)` 钳位，少算的被抹平、多算的一直留着，长期运行必然表现为"本地 ≥ 服务端，刷新归零"。
+
+本次排查出的具体路径：
+
+### 2.1 新消息触发 `getSession` 时，把服务端存量未读整个加到账号（主因）
+
+场景：某会话本地还没分页加载到（一个号几百个会话很常见），来了一条新消息 → `findSession` 找不到 → `getSession` 从服务端拉回 → `addSession(rs.data, null)` → `onAddSession` 把服务端返回的 `unreadMsgCount`（存量 k + 新增 1）**整个**加到账号。
+
+而账号初始值里已经含了这 k 条存量，于是多算了 k。用户点开该会话只减 k+1，账号永久多出 k。
+
+举例：会话 C 服务端存量 5、本地未加载，账号初始值 10。来 1 条新消息：
+
+```
+服务端：C 未读 6，账号 11
+本地：  C 未读 6，账号 10 + 6 = 16   ← 多了 5
+点开 C：账号 16 - 6 = 10，实际应为 5，再点完其他会话后本地剩 5、服务端 0
+```
+
+### 2.2 分配会话（`CmdFriendInfoChanged` / `CmdChatroomInfoChanged` changeType=4）重复累加两次
+
+`loadAssignTaskSessionData` 内部 `setSessionData(rs, null, false)` → `addSession(item, null)` → `onAddSession` 累加一次；外层 `.then` 回调里又对同一批 `rs` 手动 `updateAccountUnreadMessageNum` 累加一次。有未读的分配会话账号直接翻倍，点开只减一半。
+
+### 2.3 本地未加载到的会话被服务端删除 / 转移，本地无法扣减
+
+好友转移（changeType=4 且 `friends[].changeType === 3`）、删除好友（changeType=3）、群聊同理。服务端会把账号未读减 k；本地走 `removeSession` 时 `sessionMap` 里没有它，直接 return，账号不减。这个会话从未在本地列表出现过（所以看起来"全部已读"），账号却多 k。
+
+### 2.4 断线重连后没有校准
+
+重连本身不会单独制造偏差（补拉消息是成对累加的），但断线期间是偏差最容易堆积的时刻（手机端很可能处理了消息），且重连是天然的"该对账了"信号，此前没有利用。
+
+### 2.5 缺少排查手段
+
+账号未读数量的每次变化没有日志，拿到客户日志也无法定位是哪条路径漂的。
+
+---
+
+## 3. 修复内容
+
+### A1. `getSession` 路径账号只累加"本次新增"条数
+
+**client-chat-session.js**
+
+- `getSession` 的轮询合并 `context` 新增 `accountUnreadDelta: 0`（第 329 行附近），并在"会话轮询合并完成"日志里输出
+- `addSession(data, wechatAccountId, options = {})` 新增第三个参数，`options.unreadDelta` 透传给 `onAddSession`（第 508 行）
+- 合并完成后 `addSession(rs.data, null, { unreadDelta: context.accountUnreadDelta })`（第 343 行）
+
+**client-chat.js**
+
+- 好友 / 群聊两处 `getSession` 的 serialize 回调（第 486 / 636 行附近）：
+
+  ```js
+  // 会话未读：只在服务端没算过这条消息时 +1（原逻辑不变）
+  if (!data.isSend && isAfterServerMessage) { ... }
+  // 账号未读：不管是否被 skip 都 +1，只有"正在看当前会话被直接标记已读"不加
+  if (!data.isSend && !(isAfterServerMessage && isCurrentSessionRead)) {
+      context.accountUnreadDelta += 1
+  }
+  ```
+
+  注意 `accountUnreadDelta` **不等于** `unreadMessageIds.length`：被 skip 的消息表示服务端返回的会话已经把它算进 `unreadMsgCount`，但账号初始值是登录时取的，仍然不含这条，所以账号还是要 +1。
+
+- `onAddSession`（第 132 行附近）：
+
+  ```js
+  const delta = typeof unreadDelta === 'number' ? unreadDelta : (session.unreadMsgCount || 0)
+  if (delta > 0) { 账号 += delta }
+  ```
+
+  - `unreadDelta` 是数字 → `getSession` 来源 → 只加新增（日志 source：`onAddSession:getSession`）
+  - `unreadDelta` 为 `undefined` → 分配等来源 → 整个 `unreadMsgCount` 加上（原逻辑，日志 source：`onAddSession`）
+  - 分页来源（有 `wechatAccountId`）不加，原逻辑不变
+
+  副带收益：`addSession` 的 `isRefreshAll` 路径（会话已存在时又被 `getSession` 拉回）以前也会整量重复累加，现在只加 delta。
+
+### A2. 去掉分配会话的重复累加
+
+**client-chat.js** `onCmdFriendInfoChanged` / `onCmdChatroomInfoChanged` 的 `changeType === 4` 分支：删掉外层 `.then` 里对 `rs` 逐个 `updateAccountUnreadMessageNum(+unreadMsgCount)` 的两段代码，累加只保留 `onAddSession` 这一个入口。
+
+### A4. 删除 / 转移后以服务端为准刷新账号未读
+
+**client-chat.js** 新增方法：
+
+```js
+refreshAccountsUnreadMessageNum (wechatAccountIds)   // 第 1251 行附近
+```
+
+对 id 去重、过滤掉不在 `accountMap` 中的账号后，逐个调用 `account.refreshAccountUnreadMessageNum({ wechatAccountId })`。
+
+调用位置：
+
+| 位置 | 传入的账号 |
+|---|---|
+| 好友 changeType=4，`ps.finally` 内（`reloadData` 之后） | `rs` 中的账号 ∪ `data.wechatAccountIds` |
+| 好友 changeType=3 | `data.wechatAccountIds` |
+| 群聊 changeType=4，`ps.finally` 内 | `rs` 中的账号 ∪ `data.wechatAccountIds` |
+| 群聊 changeType=3 | `data.wechatAccountIds` |
+
+本地没有会话数据时增量是做不了的，只能靠服务端对账。
+
+### B1. 重连后全量校准
+
+**client-chat.js** `onSocketOpen`（第 1191 行附近）：`loadLossMessageData` 补拉完成后调用 `account.refreshAllAccountUnreadMesageNum()`。加了 `if (ps.length)` 判断，首次连接（没有 `lastReceiveMessageTime`）不会多刷，因为登录时 `onAccountAdded` 已经拉过。
+
+### D. 排查日志
+
+**client-chat-account.js**
+
+- 新增配置项 `onUnreadMessageNumLog` 和 `_addUnreadMessageNumLog(title, data)`，日志 group：`client-chat-account:unreadMessageNum`
+- `updateAccountUnreadMessageNum(accountId, callback, source)` 新增第三个参数 `source`（可选），数值有变化时记录：
+
+  ```json
+  {
+    "source": "onNewFriendMessage",
+    "wechatAccountId": "...",
+    "before": { "num": 10, "muteNum": 2 },
+    "after":  { "num": 11, "muteNum": 2 },
+    "delta":  { "num": 1,  "muteNum": 0 },
+    "localSessionUnread": { "num": 11, "muteNum": 2 }
+  }
+  ```
+
+- `refreshAccountUnreadMessageNum` / `refreshAllAccountUnreadMesageNum` 也各记一条（source：`refresh` / `refreshAll`，带 before / after），用于观察服务端值和本地值差多少
+
+**client-chat.js**
+
+- 五个本地增量调用点打上 source：`onAddSession`、`onAddSession:getSession`、`onRemoveSession`、`onSessionReadChange`、`onNewFriendMessage`、`onNewRoomMessage`
+- 注入 `onUnreadMessageNumLog` 时（第 793 行附近），额外计算该账号在 `session.sessionMap` 中本地会话未读之和 `localSessionUnread`，一起写进日志后交给 `socket.addLog`
+
+日志受 `socket.logEnable` 控制，关闭时零开销；存储走现有 3MB 上限自动淘汰。
+
+---
+
+## 4. 如何用日志定位问题
+
+1. 导出客户端日志，过滤 group 为 `client-chat-account:unreadMessageNum`
+2. 逐条对比 `after.num` 与 `localSessionUnread.num`：
+   - 两者相等：账号和本地会话是配平的
+   - `after.num > localSessionUnread.num` 且此后一直不回落：从这条开始漂了，看 `source` 即可知道是哪条路径
+3. 对比 `source: refresh` 的 `before` / `after`：差值就是当时本地相对服务端的累计偏差
+4. 结合 `client-chat-session:getSession` 里"会话轮询合并完成"的 `accountUnreadDelta` / `unreadMessageCount` / `skippedMessageCount`，可以验证 A1 的增量是否正确
+
+---
+
+## 5. 测试场景
+
+### 5.1 测试前准备
+
+- 打开 SDK 日志（`socket.logEnable = true`），测试过程中随时导出日志按 group 过滤
+- 准备一个有较多会话的工作微信号（至少能分 3 页以上），下文称账号 X
+- 准备"对照值"获取方式：刷新页面后左侧徽标显示的就是服务端值；或直接调 `getAccountUnreadMessageNumMethod`
+- 每个场景通用验收标准：
+  1. 操作过程中左侧账号徽标 = 右侧该账号本地会话未读之和（免打扰会话单独算 `muteNum`）
+  2. 把所有会话点开读完后，账号徽标归 0
+  3. 刷新页面后徽标值不变（本地 = 服务端）
+  4. 日志中每条 `client-chat-account:unreadMessageNum` 的 `after.num` 与 `localSessionUnread.num` 相等
+
+### 5.2 A1：本地未加载的会话收到新消息
+
+| 步骤 | 预期 |
+|---|---|
+| 1. 让账号 X 的某个会话 C 积累 k 条未读（例如 3 条），并确保 C 排在会话列表第 3 页之后（用其他会话把它往下压） | — |
+| 2. 登录客户端，只加载第 1 页，记录账号 X 徽标值 N（其中已含 C 的 3 条） | 徽标 = N |
+| 3. 用 C 对应的微信给账号 X 发 1 条消息 | 会话 C 出现在列表顶部，未读 4；账号徽标 = **N + 1**（修复前是 N + 4） |
+| 4. 查日志 `client-chat-session:getSession` 的"会话轮询合并完成" | `accountUnreadDelta: 1`；如果服务端返回的会话已含这条消息则 `skippedMessageCount: 1, unreadMessageCount: 0`，否则反过来，但 `accountUnreadDelta` 都是 1 |
+| 5. 查日志 `client-chat-account:unreadMessageNum` | 有一条 `source: "onAddSession:getSession"`，`delta.num: 1` |
+| 6. 点开 C | 账号徽标 = N - 3；`source: "onSessionReadChange"`，`delta.num: -4` |
+| 7. 把账号 X 其余会话全部点开 | 徽标归 0；刷新后仍为 0 |
+
+变体 A1-b：步骤 3 连续快速发 3 条消息（同一轮询周期内合并）→ 徽标 = N + 3，`accountUnreadDelta: 3`。
+
+变体 A1-c：步骤 3 前先点开另一个会话保持选中，再让 C 来消息 → 与主流程一致（C 不是当前会话，正常计数）。
+
+变体 A1-d：先点开 C（此时 C 已加载到本地，不走 getSession 路径）→ 走 `onNewFriendMessage` 分支，与本次改动无关，用作对照：徽标不变（自动已读）或 +1（`shouldMarkCurrentSessionRead` 返回 false 时）。
+
+### 5.3 A1 回归：分配来源不受影响
+
+| 步骤 | 预期 |
+|---|---|
+| 1. 后台把一个有 k 条未读的好友从其他客服分配到当前客服的账号 X | 收到 `CmdFriendInfoChanged changeType=4` |
+| 2. 观察账号 X 徽标 | 先 +k（`source: "onAddSession"`，注意不是 `onAddSession:getSession`），随后被 A4 的服务端刷新覆盖为服务端值（正常情况下两者相等，界面无跳动） |
+| 3. 点开该会话 | 徽标 -k，归 0 |
+
+### 5.4 A2：分配会话不再重复累加
+
+| 步骤 | 预期 |
+|---|---|
+| 1. 账号 X 徽标为 0 | — |
+| 2. 后台分配 1 个有 3 条未读的好友到账号 X | 徽标 = **3**（修复前是 6） |
+| 3. 查日志 | `source: "onAddSession"` 只有 1 条，`delta.num: 3`；紧接着一条 `source: "refresh"`，`before.num: 3, after.num: 3` |
+| 4. 点开该会话 | 徽标 = 0 |
+| 5. 同样步骤对群聊分配（`CmdChatroomInfoChanged changeType=4`）重复一遍 | 结果相同 |
+
+### 5.5 A4：本地未加载的会话被删除 / 转移
+
+| 步骤 | 预期 |
+|---|---|
+| 1. 让账号 X 的会话 C 有 3 条未读，且排在本地未加载的页（同 5.2 步骤 1） | — |
+| 2. 登录，只加载第 1 页，记录徽标 N | — |
+| 3. 后台把 C 对应的好友**转移**给其他客服 | 收到 `CmdFriendInfoChanged changeType=4`，`friends[].changeType=3` |
+| 4. 观察徽标 | = **N - 3**（修复前保持 N）；日志有 `source: "refresh"`，`before.num: N, after.num: N-3` |
+| 5. 把账号 X 其余会话点开 | 归 0 |
+| 6. 换成后台**删除**好友（`changeType=3`）重复 1~5 | 结果相同 |
+| 7. 换成群聊转移 / 删除（`CmdChatroomInfoChanged changeType=4 / 3`）重复 1~5 | 结果相同 |
+
+变体 A4-b：C 已加载到本地时执行同样操作 → 走 `onRemoveSession` 本地扣减，随后 `refresh` 覆盖，两者值应一致。
+
+### 5.6 B1：断线重连后校准
+
+| 步骤 | 预期 |
+|---|---|
+| 1. 登录，账号 X 徽标为 N，本地会话和账号配平 | — |
+| 2. 断开网络（或 devtools 里 Offline），等待 socket 触发 onclose | 日志 `socket:onclose` |
+| 3. 断网期间：用手机端把账号 X 的某个有未读的会话读掉（服务端未读减少） | — |
+| 4. 恢复网络，等待重连 | 日志 `socket:onopen` |
+| 5. 观察徽标 | 补拉消息完成后，有一条 `source: "refreshAll"` 日志，徽标变为服务端当前值（比 N 少了步骤 3 读掉的条数） |
+| 6. 首次登录（非重连）时查日志 | **没有** `source: "refreshAll"`（`ps.length` 为 0 时不刷） |
+
+### 5.7 D：日志字段正确性
+
+| 检查项 | 预期 |
+|---|---|
+| 收到新消息（会话已在本地） | `source: "onNewFriendMessage"` 或 `"onNewRoomMessage"`，`delta.num: 1`；免打扰会话时 `delta.muteNum: 1` |
+| 点开会话 | `source: "onSessionReadChange"`，`delta.num` 为负 |
+| 删除会话 | `source: "onRemoveSession"`，`delta.num` 为负 |
+| 切换免打扰 | `source: "refresh"` |
+| 任意一条日志 | `localSessionUnread.num` = 右侧该账号所有本地会话未读之和（手动数一下核对）；`after.num` = 左侧徽标当前值 |
+| `logEnable = false` | 没有任何 `client-chat-account:unreadMessageNum` 日志，功能正常 |
+| 长时间运行 | 日志总量受 3MB 上限约束，不会无限增长 |
+
+### 5.8 综合回归
+
+| 场景 | 预期 |
+|---|---|
+| 正常收发消息、点开会话、免打扰、置顶、星标、删除会话 | 徽标行为与修复前一致 |
+| "全部微号" 与具体微信号之间反复切换 | 徽标不变（此路径 A3 尚未处理，但不应比修复前更差） |
+| 多个账号同时收消息 | 各账号徽标独立正确 |
+| 群聊 @ 消息 | `lastAtMsgContent` 仍正常显示（A1 改动没有影响 `atMessage` 逻辑） |
+| 企微（wework）入口 | 完全不受影响 |
+| 跑一个工作日后刷新页面 | 刷新前后徽标一致，或差值明显小于修复前 |
+
+---
+
+## 6. 兼容性说明
+
+- `updateAccountUnreadMessageNum` 第三参数、`addSession` 第三参数、`onAddSession` 的 `unreadDelta` 字段、`ClientChatAccount` 的 `onUnreadMessageNumLog` 均为可选，缺省行为与原来一致
+- workphone-client `src/` 下没有直接调用上述方法的地方，无需改动业务代码
+- `client-chat-wework` 是独立实现，未改动
+- 分配路径下 `onAddSession` 先本地 +N、随后 A4 服务端刷新覆盖，界面可能有一次短暂跳动，最终以服务端为准
+
+---
+
+## 7. 未处理项（后续可选）
+
+| 编号 | 内容 | 说明 |
+|---|---|---|
+| A3 | `addSession` 对已存在会话的静默覆盖（`client-chat-session.js` `isRefreshAll` 分支用 `Vue.set` 直接覆盖 `unreadMsgCount`）不同步账号 | 切号 / 分页拉回已存在会话时，本地多计或其他端已读的差额会在这里悄悄消失进账号。修法：覆盖前后比较 `unreadMsgCount`，差值通过 `onUpdateSession` 的 `changeProps` 流出并调整账号 |
+| B2 | 新消息后按账号 debounce（1~2s）调 `refreshAccountUnreadMessageNum` | 兜底对账，能自动纠正所有本地增量无法覆盖的偏差（其他端已读、服务端不计某些消息类型、免打扰状态在其他端修改等） |
+| C1 | 免打扰归属：增量按本地 `session.mute` 分桶，其他端改的 mute 本地感知不到 | 有 B2 后自愈 |
+| C2 | `Math.max(0, …)` 钳位掩盖少算 | 可在开发环境结果 < 0 时打 warn |
+| C3 | `updateAccountUnreadMessageNum` 是异步的（`getAccount().then`），账号不在 `accountMap` 时先 `loadData`，可能与 refresh 交叉 | `accountMap` 里已有时可改为同步执行 |
+| C4 | 服务端计数规则核对：`msgType 10000`（"你已添加了xx"）、`49`（群邀请）等客户端计未读，服务端是否也计 | 需和后端确认，不一致在 `shouldIgnoreSessionByMessage` 补规则 |
+| C5 | `getSession` 路径命中当前会话时只本地置 0，未调 `setSessionRead` 通知服务端 | 方向是"服务端 > 本地"，不是本次现象，但也不一致 |
+| — | 协议层面：`CmdNewMessage` 由服务端带上会话 `unreadMsgCount` 和账号 `unread`，客户端直接覆盖；增加"其他端已读"推送 | 长期方案，两边天然一致 |