@aochuang/client-sdk 1.0.400 → 1.0.401
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 +91 -12
- package/services/client-chat/client-chat-wechat/client-chat-socket.js +80 -22
- package/services/client-chat/client-chat-wechat/client-chat.js +59 -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,169 @@
|
|
|
1
|
+
# 消息与会话诊断日志架构文档
|
|
2
|
+
|
|
3
|
+
## 1. 总体架构
|
|
4
|
+
|
|
5
|
+
```text
|
|
6
|
+
Socket / ClientChat / Axios / 页面生命周期 / 运行时异常
|
|
7
|
+
|
|
|
8
|
+
v
|
|
9
|
+
logger.addLog
|
|
10
|
+
同步裁剪、编号、进入内存队列
|
|
11
|
+
|
|
|
12
|
+
300ms / 50条 / 页面隐藏触发
|
|
13
|
+
v
|
|
14
|
+
单写链批量调度器
|
|
15
|
+
|
|
|
16
|
+
IndexedDB v2
|
|
17
|
+
logs object store + meta store
|
|
18
|
+
|
|
|
19
|
+
全量读取 / 按天组成 Blob
|
|
20
|
+
v
|
|
21
|
+
JSZip 下载
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
日志是业务旁路。所有入口均为尽力记录,任何日志异常都在边界内终止,不回流到业务 Promise 或事件回调。
|
|
25
|
+
|
|
26
|
+
## 2. 模块边界
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
utils/log.js 旧公共入口,仅转发默认导出
|
|
30
|
+
utils/log/index.js Log 类与公共 API
|
|
31
|
+
utils/log/constants.js 阈值、store 名称、版本与默认容量
|
|
32
|
+
utils/log/serialize.js 安全编码、字符串裁剪和类型占位
|
|
33
|
+
utils/log/indexed-db.js 数据库打开、批量写入、读取和清理
|
|
34
|
+
utils/log/export.js 按天组织紧凑 JSON Blob
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Request 专用裁剪放在 JavaMain-combine,SDK 的安全编码负责最终兜底。这样 SDK 不依赖 Axios,Request 规则也不会污染普通日志 API。
|
|
38
|
+
|
|
39
|
+
两层编码都省略对象中的 undefined 属性;数组 undefined 转为 null 保持位置。请求失败在写入 `request_failed` 前给原始 Error 增加不可枚举内部标记,运行时异常监听器识别该标记或 Axios 请求上下文后跳过,避免同一失败重复进入错误日志。
|
|
40
|
+
|
|
41
|
+
JavaMain-combine 的 `runtime-error.js` 统一监听 window error、unhandled rejection 和 Vue errorHandler。监听器只生成有界诊断字段,不保存异常事件、Promise、Vue 实例或原始业务对象。
|
|
42
|
+
|
|
43
|
+
页面启动上下文拆成两条低频日志:入口立即写 `page_boot` 环境快照,用户信息加载成功后扩展现有 `user_init_result` 写登录身份。两者共享 `pageInstanceId`;全局诊断包装器只为后续事件追加 `pageInstanceId` 和递增的 `pageSequence`,不重复追加版本、页面存活时长或登录账号。
|
|
44
|
+
|
|
45
|
+
## 3. 写入链路
|
|
46
|
+
|
|
47
|
+
### 3.1 同步阶段
|
|
48
|
+
|
|
49
|
+
`addLog()` 只执行有界工作:
|
|
50
|
+
|
|
51
|
+
1. 合并 group、refererId、createTime、timestamp 和 ID。
|
|
52
|
+
2. 执行 `beforeAddCallback`;异常视为日志被拒绝。
|
|
53
|
+
3. 对日志做安全紧凑编码,编码失败则丢弃当前日志。
|
|
54
|
+
4. 将记录加入内存队列并安排 flush。
|
|
55
|
+
5. 立即返回,不等待 IndexedDB。
|
|
56
|
+
|
|
57
|
+
### 3.2 批量阶段
|
|
58
|
+
|
|
59
|
+
- 300ms 到期或队列达到 50 条时触发。
|
|
60
|
+
- 从队列取最多 500 条进入一个 readwrite transaction。
|
|
61
|
+
- 一个批次只读取一次 meta,批量 put 后更新统计。
|
|
62
|
+
- 仅当总大小超过 200MB 时打开 order 游标删除最旧记录。
|
|
63
|
+
- 同一 Log 实例使用 Promise 写链串行事务。
|
|
64
|
+
|
|
65
|
+
### 3.3 失败与退避
|
|
66
|
+
|
|
67
|
+
失败批次放回队首,并按失败次数增加重试间隔。达到内存队列限制后丢弃最旧普通日志并累计 droppedCount;恢复写入后生成一条汇总,不递归记录每次失败。
|
|
68
|
+
|
|
69
|
+
## 4. 数据结构
|
|
70
|
+
|
|
71
|
+
新记录在现有 v2 `logs` store 中使用:
|
|
72
|
+
|
|
73
|
+
```js
|
|
74
|
+
{
|
|
75
|
+
recordId: 'pageInstanceId:sequence',
|
|
76
|
+
order: 12345,
|
|
77
|
+
byteSize: 768,
|
|
78
|
+
day: '2026-11-07',
|
|
79
|
+
group: 'diagnostic:runtime_error',
|
|
80
|
+
payload: '{"id":...,"group":...}'
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
`group` 是 v2 记录包装层的可选字段,不新增 object store 或索引。旧记录没有该字段时仍按原结构读取;错误分类可从紧凑 payload 中识别,数据库不升级版本。
|
|
85
|
+
|
|
86
|
+
旧记录结构:
|
|
87
|
+
|
|
88
|
+
```js
|
|
89
|
+
{
|
|
90
|
+
recordId,
|
|
91
|
+
order,
|
|
92
|
+
byteSize,
|
|
93
|
+
log: { ... }
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
读取时优先使用 `payload`;旧记录从 `log` 临时编码。由于下载始终全量扫描,不需要 day 索引,因此保持 IndexedDB v2。
|
|
98
|
+
|
|
99
|
+
## 5. 一致性和丢失窗口
|
|
100
|
+
|
|
101
|
+
- transaction `oncomplete` 后视为批次已提交。
|
|
102
|
+
- 页面正常运行时,丢失窗口最多是 300ms 或一个未提交批次。
|
|
103
|
+
- `visibilitychange=hidden` 和 `pagehide` 会提前触发 flush,但浏览器不会等待异步事务,因此不承诺强杀场景零丢失。
|
|
104
|
+
- 不使用同步 localStorage 备份,以避免主线程阻塞和双存储一致性复杂度。
|
|
105
|
+
|
|
106
|
+
## 6. 并发
|
|
107
|
+
|
|
108
|
+
- 单实例写入通过 Promise 链串行。
|
|
109
|
+
- 多标签页的 IndexedDB readwrite transaction 由浏览器串行化。
|
|
110
|
+
- `recordId` 包含页面实例 ID,避免多标签页碰撞。
|
|
111
|
+
- meta 在每个事务内读取和更新,避免跨标签页长期缓存统计值。
|
|
112
|
+
|
|
113
|
+
## 7. 下载快照
|
|
114
|
+
|
|
115
|
+
下载先请求当前 logger flush,然后打开只读事务。只读事务建立后的游标视为本次下载快照;之后产生的新日志进入下一次下载。
|
|
116
|
+
|
|
117
|
+
按 `day` 和导出类型分组后使用 Blob parts 构造:
|
|
118
|
+
|
|
119
|
+
```text
|
|
120
|
+
[
|
|
121
|
+
payload1,
|
|
122
|
+
,
|
|
123
|
+
payload2
|
|
124
|
+
]
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
实际文件为紧凑单行 JSON,不执行美化格式化。
|
|
128
|
+
|
|
129
|
+
启用 `separateErrorLogs` 时,`diagnostic:runtime_error` 和 `diagnostic:runtime_error_suppressed` 归入 `error` 类型,其余记录归入 `operation` 类型。一次全量扫描同时生成两类 Blob,前端不需要再次解析 200MB JSON。默认不传选项时仍生成原有合并文件,保持 SDK API 兼容。
|
|
130
|
+
|
|
131
|
+
## 8. 消息关联与去重
|
|
132
|
+
|
|
133
|
+
```text
|
|
134
|
+
message_stored(messageId, msgSvrId, sessionId)
|
|
135
|
+
|
|
|
136
|
+
session_resolved / session_unread_changed
|
|
137
|
+
|
|
|
138
|
+
message_event_emitted / message_event_suppressed
|
|
139
|
+
|
|
|
140
|
+
message_received(messageId, msgSvrId, result) / message_cache_result
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
`message_received` 在 Socket 同步业务回调执行完成后才记录处理结果,因此时间顺序晚于回调内部的 stored/session/emitted;它同时承担这条 Socket 消息唯一完整快照的职责。通知被过滤时改由 `message_received_suppressed` 保存该快照,两者不会同时出现。
|
|
144
|
+
|
|
145
|
+
- Socket 层保留完整 `friendMessage/chatroomMessage` 和正文结构,删除 token/accessToken,并受统一序列化的二进制占位和 10,000 字符单值安全上限保护。
|
|
146
|
+
- 消息内存层以 `messageId + msgSvrId + sessionId` 关联;正常派发事件不保存 `memoryInserted=true` 等可由事件名推导的字段。
|
|
147
|
+
- 乱序抑制才额外保存消息时间与原末条时间;普通抑制只保存原因。
|
|
148
|
+
- Socket 过滤、会话更新回调异常和账号未读刷新失败只在异常分支各写一条,不增加正常路径日志数量。
|
|
149
|
+
- 所有诊断入口内部隔离异常,`sessionId` 计算或日志回调失败均不改变消息事件派发。
|
|
150
|
+
|
|
151
|
+
## 9. 运行时异常保护
|
|
152
|
+
|
|
153
|
+
- 相同错误按 name、message、首帧、脚本路径和行列号生成稳定指纹。
|
|
154
|
+
- 5 秒去重窗口结束后只写一条 suppressedCount 汇总。
|
|
155
|
+
- 每分钟最多接收 30 个不同错误,避免第三方脚本异常风暴挤占消息日志。
|
|
156
|
+
- 异常监听器使用递归锁和最外层 try/catch;日志器故障不会再次触发业务异常。
|
|
157
|
+
- 异常仍进入现有 300ms/50 条批量队列,不为单个错误立即创建 IndexedDB 事务。
|
|
158
|
+
- 已由 Request 日志覆盖的 Axios error/unhandled rejection 在采集源跳过,不进入指纹、限流或错误导出流程。
|
|
159
|
+
|
|
160
|
+
## 10. 故障隔离
|
|
161
|
+
|
|
162
|
+
```text
|
|
163
|
+
业务调用 -> addLog -> try/catch -> 内部返回
|
|
164
|
+
后台 flush -> catch -> 恢复队列/退避 -> 吞掉 rejection
|
|
165
|
+
主动 publish/export -> 失败可 reject 给下载 UI
|
|
166
|
+
导出失败 -> rejected export Promise,仅影响用户主动下载
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
主动下载允许向 UI 返回失败提示;后台日志写入不得产生未处理 rejection。
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# 消息与会话诊断日志需求文档
|
|
2
|
+
|
|
3
|
+
## 1. 背景
|
|
4
|
+
|
|
5
|
+
云客服偶发收不到消息、刷新后消息恢复、会话未读数量不一致。现有日志偏重 Socket 连接,缺少 HTTP 请求、消息处理、会话补建和未读变化之间的关联信息,且日志写入频率和下载体积需要重新控制。
|
|
6
|
+
|
|
7
|
+
## 2. 目标
|
|
8
|
+
|
|
9
|
+
1. 建立 Socket、HTTP、消息、会话和账号未读的可关联诊断链路。
|
|
10
|
+
2. 日志故障不得改变业务控制流或阻塞消息处理。
|
|
11
|
+
3. 消息密集时避免逐条读写 IndexedDB。
|
|
12
|
+
4. 浏览器正常运行时可靠持久化;刷新或异常退出允许丢失最后一个尚未提交的小批次。
|
|
13
|
+
5. 全量下载最多 200MB 日志,并按自然日拆分 ZIP 内文件。
|
|
14
|
+
6. 控制请求参数、响应和消息内容体积,禁止记录文件和二进制正文。
|
|
15
|
+
7. 捕获页面运行期脚本异常,并将错误日志从操作日志中独立导出。
|
|
16
|
+
|
|
17
|
+
## 3. 范围
|
|
18
|
+
|
|
19
|
+
### 3.1 SDK
|
|
20
|
+
|
|
21
|
+
- Socket 建连、登录、重连、关闭、心跳、发送和接收。
|
|
22
|
+
- 新消息接收、校验、去重、过滤、内存插入、事件派发和断线补偿。
|
|
23
|
+
- 会话列表加载、置顶加载、未读列表、会话轮询、会话增删改和已读。
|
|
24
|
+
- 账号未读总数与免打扰未读的服务端刷新和本地增量。
|
|
25
|
+
- IndexedDB 日志持久化、容量清理、全量读取和按天导出。
|
|
26
|
+
|
|
27
|
+
### 3.2 JavaMain-combine
|
|
28
|
+
|
|
29
|
+
- Axios 请求开始、成功响应、失败响应、取消和重试。
|
|
30
|
+
- 后端 `traceid` 提取。
|
|
31
|
+
- 统一操作日志下载入口和显示名称。
|
|
32
|
+
- 微号数据、已加载会话、网络日志等诊断快照。
|
|
33
|
+
- 全局 JavaScript 异常、未处理 Promise 拒绝和 Vue 运行期异常。
|
|
34
|
+
- 异常去重、限流、敏感 URL 清理和独立错误日志下载。
|
|
35
|
+
|
|
36
|
+
## 4. 日志内容规则
|
|
37
|
+
|
|
38
|
+
### 4.1 Request
|
|
39
|
+
|
|
40
|
+
成功和失败均记录:
|
|
41
|
+
|
|
42
|
+
- `requestId`、method、API path、attempt、status、duration、result。
|
|
43
|
+
- 裁剪后的 `params`、`data`、`response.data`。
|
|
44
|
+
- 后端返回的 `traceid`,独立放在响应日志顶层。
|
|
45
|
+
- 失败时补充 error name、code 和 message。
|
|
46
|
+
|
|
47
|
+
不记录完整 headers、Authorization、Cookie、Token 或原始 response 对象。
|
|
48
|
+
|
|
49
|
+
### 4.2 裁剪
|
|
50
|
+
|
|
51
|
+
- 字符串保留前 100 个字符,后缀为 `...+N`,N 是被舍弃字符数。
|
|
52
|
+
- File、Blob、二进制分别记录 `[file]`、`[blob]`、`[binary]`。
|
|
53
|
+
- 数组最多 100 项,对象最多 100 个自有属性,最大深度 6。
|
|
54
|
+
- 单个请求参数或响应裁剪结果最多 64KB。
|
|
55
|
+
- 循环引用、不可读取属性和不支持类型使用占位符。
|
|
56
|
+
- 对象属性值为 `undefined` 时直接省略,不写入 `"[undefined]"`;数组中的 undefined 按 JSON 语义写为 `null` 以保持索引。
|
|
57
|
+
- 密码、Token、Cookie、验证码、密钥和 Base64 字段必须先脱敏再裁剪。
|
|
58
|
+
|
|
59
|
+
### 4.3 消息与会话
|
|
60
|
+
|
|
61
|
+
- Socket 收包层作为唯一完整消息快照,记录 `friendMessage/chatroomMessage` 完整结构、两个消息 ID 和处理结果;后续高频阶段只重复 `messageId`、服务端 `msgSvrId` 和 `sessionId` 三个关联键。
|
|
62
|
+
- 记录处理决定、过滤原因、会话来源、轮询次数和补偿数量。
|
|
63
|
+
- 记录会话未读和账号未读变化前后值及来源。
|
|
64
|
+
- 同一条消息只允许在 `message_received` 或 `message_received_suppressed` 其中之一保存完整对象;内存插入、事件派发、会话、未读和缓存阶段不得再次保存消息对象。
|
|
65
|
+
- 账号未读刷新成功复用 `account_unread_changed`;仅失败时增加一条 `account_unread_refresh_failed`,不为成功请求再写 requested/applied 两条日志。
|
|
66
|
+
- 不记录完整消息正文、文件内容、完整消息/会话数组或登录凭据。
|
|
67
|
+
|
|
68
|
+
### 4.4 页面启动上下文
|
|
69
|
+
|
|
70
|
+
- 每次页面加载或刷新只写一条 `page_boot`,记录版本、导航类型、无查询参数的路由、协议、语言、平台、浏览器标识、在线状态、视口、屏幕、像素比、时区和可见状态。
|
|
71
|
+
- 用户信息接口成功后,在现有 `user_init_result` 中追加当前登录账号 ID、用户名、姓名和租户 ID;不新增重复的身份事件。
|
|
72
|
+
- `page_boot` 与 `user_init_result` 通过同一个 `pageInstanceId` 关联。
|
|
73
|
+
- `appVersion` 不注入后续每条诊断日志;`pageAgeMs` 可由日志时间和 `page_boot` 时间计算,不落库。
|
|
74
|
+
|
|
75
|
+
### 4.5 脚本异常
|
|
76
|
+
|
|
77
|
+
- 使用统一 `runtime_error` 事件记录来源、错误指纹、name、message、安全栈、脚本路径、行列号和页面状态。
|
|
78
|
+
- 来源区分 `window_error`、`unhandled_rejection` 和 `vue_error`。
|
|
79
|
+
- Vue 异常补充组件名和生命周期信息,但不记录 Vue 实例、组件 data 或 DOM。
|
|
80
|
+
- URL 只保留 origin 和 pathname;查询参数、hash、Token、Cookie、密码和密钥不得进入日志。
|
|
81
|
+
- 错误栈最多保留前 10 帧和 4000 字符,Promise reason 不保存原始对象。
|
|
82
|
+
- 相同指纹 5 秒内只记录首条,重复数量写入 `runtime_error_suppressed` 汇总。
|
|
83
|
+
- 每分钟最多记录 30 个不同异常,超限数量使用汇总日志记录。
|
|
84
|
+
- 已经写入 `request_failed` 的 Axios/请求异常不再重复写入 `runtime_error`;普通脚本异常和非请求 Promise rejection 仍需记录。
|
|
85
|
+
|
|
86
|
+
## 5. 存储要求
|
|
87
|
+
|
|
88
|
+
- 只使用 IndexedDB,不使用 localStorage 作为降级、迁移或退出备份。
|
|
89
|
+
- 保持数据库版本 v2;新增字段直接写入现有 object store。
|
|
90
|
+
- 默认上限 200MB,超过后按最旧记录清理。
|
|
91
|
+
- `addLog()` 只入内存队列,不读取 IndexedDB,不等待持久化。
|
|
92
|
+
- 最长 300ms 或累计 50 条时触发批量写入,单事务最多 500 条。
|
|
93
|
+
- 页面隐藏和 `pagehide` 时请求立即 flush,但不阻塞页面退出。
|
|
94
|
+
- 浏览器进程强杀、系统断电或存储失效时,允许丢失最后一个未提交批次。
|
|
95
|
+
|
|
96
|
+
## 6. 异常隔离
|
|
97
|
+
|
|
98
|
+
- `logger.addLog()` 必须捕获内部同步异常,不向调用方抛出。
|
|
99
|
+
- 异步写入、清理和导出必须自行处理 Promise rejection。
|
|
100
|
+
- 日志失败不得影响 Socket ACK、消息处理、会话状态和 HTTP 返回。
|
|
101
|
+
- 连续写入失败时采用退避,禁止形成错误日志递归。
|
|
102
|
+
- 调用方不应为普通 `addLog()` 大量添加 `try/catch`。
|
|
103
|
+
|
|
104
|
+
## 7. 下载要求
|
|
105
|
+
|
|
106
|
+
- 下载全部日志,不提供日期筛选。
|
|
107
|
+
- ZIP 内操作日志、错误日志和网络日志按自然日拆成紧凑 JSON 文件。
|
|
108
|
+
- `runtime_error` 和 `runtime_error_suppressed` 只进入 `错误日志/错误日志-YYYY-MM-DD.json`,不得重复出现在操作日志中。
|
|
109
|
+
- 下载阶段不做 4 空格格式化;用户下载后自行决定是否格式化。
|
|
110
|
+
- 新记录优先复用落库时生成的紧凑 JSON payload,避免再次编码大对象。
|
|
111
|
+
|
|
112
|
+
## 8. 验收标准
|
|
113
|
+
|
|
114
|
+
1. 日志模块同步或异步故障时,业务测试仍通过。
|
|
115
|
+
2. 1000 条连续日志不会产生 1000 个 IndexedDB 写事务。
|
|
116
|
+
3. 成功和失败响应均能查到裁剪内容与 traceid。
|
|
117
|
+
4. 超长字符串、深层对象、循环引用、File 和 Blob 不造成异常或大日志。
|
|
118
|
+
5. 全量下载可以按日期得到合法紧凑 JSON。
|
|
119
|
+
6. 旧 import 路径 `@aochuang/client-sdk/utils/log.js` 保持可用。
|
|
120
|
+
7. 脚本异常不会改变浏览器或 Vue 的原有错误处理,异常风暴不会造成逐条 IndexedDB 写入。
|
|
121
|
+
8. 同一天错误记录与普通记录分别生成合法 JSON,且两个文件不存在重复记录。
|
|
122
|
+
9. 导出对象不得出现 `"[undefined]"`,同一请求失败不得同时出现在 Request 日志和错误日志。
|
|
123
|
+
10. 单条新消息在 Socket 层存在且仅存在一份完整快照,后续处理阶段不重复正文,并可通过消息 ID、会话 ID 串起处理链路。
|
|
124
|
+
11. 每次刷新只有一条完整环境日志,登录成功事件能关联当前账号,后续事件不重复携带环境和身份字段。
|