@aochuang/client-sdk 1.0.381-dev-2 → 1.0.381-dev-3
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/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 +58 -19
- package/services/client-chat/client-chat-wechat/client-chat-session.js +83 -10
- package/services/client-chat/client-chat-wechat/client-chat-socket.js +48 -22
- package/services/client-chat/client-chat-wechat/client-chat.js +2 -0
- package/services/socket/socket.js +4 -0
- 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//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
- /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 → utils/log}//345/210/206/346/236/220/344/270/216/344/274/230/345/214/226/346/226/271/346/241/210.md" +0 -0
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# 任务计划:消息与会话诊断日志完善
|
|
2
|
+
|
|
3
|
+
## 目标
|
|
4
|
+
|
|
5
|
+
完善 SDK 与 JavaMain-combine 的消息、会话、HTTP 请求诊断日志,使用高性能 IndexedDB 批量持久化和按天全量导出,并确保日志故障不影响业务。
|
|
6
|
+
|
|
7
|
+
## 下一步
|
|
8
|
+
|
|
9
|
+
补充精简且可关联的消息/会话异常日志,并记录页面刷新环境与当前登录账号上下文。
|
|
10
|
+
|
|
11
|
+
## 当前阶段
|
|
12
|
+
|
|
13
|
+
阶段 11(诊断关联与启动上下文)
|
|
14
|
+
|
|
15
|
+
## 各阶段
|
|
16
|
+
|
|
17
|
+
### 阶段 1:需求与现状确认
|
|
18
|
+
- [x] 确认仅使用 IndexedDB,不考虑 localStorage 降级或应急备份
|
|
19
|
+
- [x] 确认 Request 成功和失败响应均记录裁剪内容及 traceid
|
|
20
|
+
- [x] 审阅现有日志、消息、会话和下载实现
|
|
21
|
+
- **状态:** complete
|
|
22
|
+
|
|
23
|
+
### 阶段 2:文档设计
|
|
24
|
+
- [x] 补充需求文档
|
|
25
|
+
- [x] 补充架构文档
|
|
26
|
+
- [x] 补充技术方案文档
|
|
27
|
+
- **状态:** complete
|
|
28
|
+
|
|
29
|
+
### 阶段 3:SDK 日志模块重构
|
|
30
|
+
- [x] 将 utils/log.js 重构为 utils/log/ 目录并保持原 import 兼容
|
|
31
|
+
- [x] 实现内部异常隔离、裁剪、内存队列和 IndexedDB 批量写入
|
|
32
|
+
- [x] 实现全量按天导出且不做美化格式化
|
|
33
|
+
- **状态:** complete
|
|
34
|
+
|
|
35
|
+
### 阶段 4:消息、会话与 Request 接入
|
|
36
|
+
- [x] 补齐 SDK 消息与会话关键链路日志
|
|
37
|
+
- [x] 接入前端 Axios 请求、响应、traceid 和失败信息日志
|
|
38
|
+
- [x] 更新日志下载入口和显示名称
|
|
39
|
+
- **状态:** complete
|
|
40
|
+
|
|
41
|
+
### 阶段 5:测试与交付
|
|
42
|
+
- [x] 覆盖裁剪、异常隔离、刷新窗口和导出定向测试
|
|
43
|
+
- [x] 完成 SDK 与前端构建验证
|
|
44
|
+
- [x] 检查文档和工作区状态
|
|
45
|
+
- **状态:** complete
|
|
46
|
+
|
|
47
|
+
### 阶段 6:UI 自动化与真实消息验证
|
|
48
|
+
- [x] 完成登录、刷新、IndexedDB、Request、会话及下载 UI 自动化验证
|
|
49
|
+
- [x] 生成包含真实统计和产物哈希的测试报告
|
|
50
|
+
- [ ] 捕获真实新消息完整日志链路
|
|
51
|
+
- [ ] 补齐最终测试结论
|
|
52
|
+
- **状态:** pending(等待测试人员发送真实消息)
|
|
53
|
+
|
|
54
|
+
### 阶段 7:脚本异常日志与独立下载
|
|
55
|
+
- [x] 捕获 window error、未处理 Promise rejection 和 Vue 全局异常
|
|
56
|
+
- [x] 实现异常去重、限流、敏感信息控制和内部故障隔离
|
|
57
|
+
- [x] SDK 按天拆分操作日志与错误日志,错误记录不重复进入操作日志
|
|
58
|
+
- [x] 下载 UI 增加错误日志类型并默认全选
|
|
59
|
+
- [x] 更新需求、架构、方案文档并完成定向测试与构建
|
|
60
|
+
- **状态:** complete
|
|
61
|
+
|
|
62
|
+
### 阶段 8:最终 UI 自动化与证据归档
|
|
63
|
+
- [x] 建立 `test/ui-automation/log-diagnostics` 专用产物目录
|
|
64
|
+
- [x] 截取页面登录、下载入口和消息前后未读状态的真实截图
|
|
65
|
+
- [x] 建立新鲜 IndexedDB 基线并通过浏览器 UI 提示测试人员发送消息
|
|
66
|
+
- [x] 关联真实消息接收、存储、派发、缓存、会话和未读变化日志
|
|
67
|
+
- [x] 通过页面入口下载完整日志并验证分类、数量、大小与哈希
|
|
68
|
+
- [x] 生成包含截图和真实数据的最终 UI 自动化测试报告
|
|
69
|
+
- **状态:** complete
|
|
70
|
+
|
|
71
|
+
### 阶段 9:undefined 与请求异常去重
|
|
72
|
+
- [x] 对象中的 undefined 字段不再持久化,数组 undefined 按 JSON 语义写为 null
|
|
73
|
+
- [x] Request 失败异常增加内部标记,错误日志排除已记录的请求异常
|
|
74
|
+
- [x] 修复网络错误路径读取空 response.config 的二次 TypeError
|
|
75
|
+
- [x] 更新需求、架构和方案文档
|
|
76
|
+
- [x] 增加定向测试并完成构建、差异检查
|
|
77
|
+
- **状态:** complete
|
|
78
|
+
|
|
79
|
+
### 阶段 10:undefined 与请求异常 UI 自动化回归
|
|
80
|
+
- [x] 启动真实客服页面并建立 IndexedDB 新增日志基线
|
|
81
|
+
- [x] 触发真实请求并验证新增对象不包含 `"[undefined]"`
|
|
82
|
+
- [x] 触发请求异常并验证只进入 Request 日志,不进入错误日志
|
|
83
|
+
- [x] 触发普通脚本异常并验证仍进入独立错误日志
|
|
84
|
+
- [x] 下载日志、保存截图和真实统计,更新 UI 自动化测试报告
|
|
85
|
+
- **状态:** complete
|
|
86
|
+
|
|
87
|
+
### 阶段 11:精简关联日志与页面启动上下文
|
|
88
|
+
- [x] 消息链路统一使用 ID/sessionId 关联,不重复记录完整消息数据
|
|
89
|
+
- [x] 补充 Socket 过滤和会话更新异常的低频结果日志
|
|
90
|
+
- [x] 账号未读刷新成功复用现有变化日志,仅补充失败事件,避免 requested/applied 冗余
|
|
91
|
+
- [x] 页面刷新记录一次环境信息,登录完成后记录一次当前账号上下文
|
|
92
|
+
- [x] 更新文档、增加定向测试并完成构建与差异检查
|
|
93
|
+
- **状态:** complete
|
|
94
|
+
|
|
95
|
+
### 阶段 12:保留 Socket 新消息完整快照
|
|
96
|
+
- [x] `message_received` 或过滤事件保留一份完整 friendMessage/chatroomMessage 快照
|
|
97
|
+
- [x] 后续消息、会话、未读和缓存阶段继续只保存关联 ID 与结果
|
|
98
|
+
- [x] 更新测试与文档,完成构建和差异检查
|
|
99
|
+
- **状态:** complete
|
|
100
|
+
|
|
101
|
+
### 阶段 13:清空日志后的 UI 自动化回归
|
|
102
|
+
- [x] 通过浏览器页面上下文只清理 `log_client_chat` 日志数据库并验证清零
|
|
103
|
+
- [x] 刷新页面验证 page_boot、登录身份、Request 和初始化链路
|
|
104
|
+
- [x] 验证真实新消息完整 Socket 快照、会话和未读关联链路
|
|
105
|
+
- [x] 通过真实 UI 下载日志,归档截图、ZIP、统计和测试报告
|
|
106
|
+
- **状态:** complete
|
|
107
|
+
|
|
108
|
+
### 阶段 14:生产发布前非侵入性审查
|
|
109
|
+
- [x] 盘点前端与 SDK 的全部已跟踪、未跟踪差异及分支状态
|
|
110
|
+
- [x] 审查日志调用对消息、会话、Request、Socket 和页面生命周期的控制流影响
|
|
111
|
+
- [x] 审查 IndexedDB 批量写入、异常隔离、容量清理和下载的性能/兼容性边界
|
|
112
|
+
- [x] 重新执行定向测试、正式构建和差异完整性检查
|
|
113
|
+
- [x] 给出生产发布结论、阻断项与残余风险
|
|
114
|
+
- **状态:** complete(结论:当前存在发布阻断项,处理后需用正式 SDK tarball 重跑构建与冒烟)
|
|
115
|
+
|
|
116
|
+
## 关键问题
|
|
117
|
+
|
|
118
|
+
1. 如何在不频繁写 IndexedDB 的前提下,将异常退出时的日志丢失控制在可接受窗口?
|
|
119
|
+
2. 如何在保持 `@aochuang/client-sdk/utils/log.js` 兼容的同时目录化实现?
|
|
120
|
+
3. 如何避免成功响应、消息正文和大参数造成日志膨胀或主线程卡顿?
|
|
121
|
+
|
|
122
|
+
## 已做决策
|
|
123
|
+
|
|
124
|
+
| 决策 | 理由 |
|
|
125
|
+
|------|------|
|
|
126
|
+
| 保持 IndexedDB v2 | 全量导出无需日期索引,现有 object store 可直接容纳新增字段,避免版本升级阻塞 |
|
|
127
|
+
| 仅使用 IndexedDB | 用户明确不考虑 localStorage 方案 |
|
|
128
|
+
| addLog 内部吞掉日志异常 | 日志属于旁路能力,不能要求所有调用方重复 try/catch |
|
|
129
|
+
| 字符串保留前 100 字符并追加省略数量 | 控制体积并保留诊断上下文,例如 `...+2380` 表示省略 2380 字符 |
|
|
130
|
+
| 成功和失败响应均记录裁剪副本 | 需要完整请求链路,同时禁止记录原始大对象和二进制内容 |
|
|
131
|
+
|
|
132
|
+
## 遇到的错误
|
|
133
|
+
|
|
134
|
+
| 错误 | 尝试次数 | 解决方案 |
|
|
135
|
+
|------|---------|---------|
|
|
136
|
+
| JavaMain-combine 直接执行 ESLint 无法识别 import/Vue | 1 | 仓库没有 CLI 可读取的 parser 配置,改用 Vue CLI 正式构建和 Babel 定向解析验证 |
|
|
137
|
+
| 定向运行时测试找不到 `@babel/register` | 1 | 不新增依赖,改用已有 `@babel/core` 转换后通过 VM/函数加载测试 |
|
|
138
|
+
| JSON 字符串中的 `access_token` 未脱敏 | 1 | 扩展字符串键名匹配,覆盖敏感词位于键名中间的情况 |
|
|
139
|
+
| 默认 Node 14 不支持 `node --test` | 1 | 使用本机 Node 22 运行 node:test,项目构建继续使用 Node 14 |
|
|
140
|
+
| Node 22 构建触发旧 Webpack OpenSSL 错误 | 1 | 改用项目原 Node 14,正式构建成功 |
|
|
141
|
+
| 仓库 ESLint 未加载 parser,无法解析现有 import/Vue | 1 | 沿用 Babel、node:test 和 Vue CLI 正式构建验证 |
|
|
142
|
+
| SDK 仓库独立执行 Babel 校验找不到 `@babel/core` | 1 | 不在 SDK 仓库重复执行该命令;由 JavaMain-combine 已安装的 Babel 加载 SDK 源码,并通过定向测试验证 |
|
|
143
|
+
| 系统 unzip 中文文件名显示为问号,shasum 提示 locale fallback | 1 | 改用项目 JSZip 读取归档文件名和内容;哈希计算结果仍有效 |
|
|
144
|
+
| 更新阶段 10 规划文件时补丁上下文顺序不匹配 | 1 | 重新定位准确标题后分块更新 |
|
|
145
|
+
| 检索前端认证代码时误用了不存在的 `src/store` 路径 | 1 | 改用实际目录 `src/entries/chat/store`,不重复无效检索 |
|
|
146
|
+
| zsh 展开不存在的 `.env*` 导致 no matches found | 1 | 后续使用 `rg --files -g '.env*'` 或仅检查确定存在的配置文件 |
|
|
147
|
+
| 静默 `npm pack @aochuang/client-sdk@1.0.382` 未生成临时归档,后续 tar 无输入 | 1 | 改用非静默 npm pack 获取 registry 的明确响应,不重复静默命令 |
|
|
148
|
+
| Node 14 自带旧 npm 不支持 `--pack-destination`,且默认 npm cache 有历史权限问题 | 1 | 在独立 mktemp 目录中设置任务专用 npm cache 并从该目录执行 pack |
|
|
149
|
+
| Socket 快照故障注入首次 stub 误拦截 Babel runtime,导致模块加载 TypeError | 1 | 仅 stub `../../socket`,其他 Babel runtime 依赖交给真实 require |
|
|
@@ -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。前端使用正式依赖完成构建与浏览器验证。
|
|
@@ -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. 每次刷新只有一条完整环境日志,登录成功事件能关联当前账号,后续事件不重复携带环境和身份字段。
|