@aigc-kino/logger-sdk 1.3.0

package/README.md

@@ -0,0 +1,280 @@
+# Logger SDK 使用文档
+
+> `@aigc-kino/logger-sdk` — 前端日志采集 SDK（TypeScript）
+>
+> 支持异常监控、性能监控、网络监控、用户行为、业务日志、qiankun 微前端。
+
+## 1. 安装
+
+```bash
+pnpm add @aigc-kino/logger-sdk
+# 或
+npm install @aigc-kino/logger-sdk
+```
+
+CDN 方式：
+
+```html
+<!-- 建议锁定版本并启用 SRI 完整性校验，防止 CDN 被篡改 -->
+<script
+  src="https://cdn.example.com/logger-sdk/1.0.0/index.umd.js"
+  integrity="sha384-<构建时生成的哈希>"
+  crossorigin="anonymous"
+></script>
+<script>
+  LoggerSDK.init({ projectId: 'kino-log-platfrom', token: 'YOUR_TOKEN' })
+</script>
+```
+
+## 2. 快速开始
+
+在应用入口尽早初始化（建议在所有业务代码之前）：
+
+```ts
+import { init } from '@aigc-kino/logger-sdk'
+
+init({
+  projectId: 'kino-log-platfrom',       // 必填：项目 ID（Admin 后台创建）
+  token: 'YOUR_TOKEN',            // 必填：上报 Token
+  serverUrl: 'https://log.example.com', // 必填：网关地址
+  env: 'production',              // 环境：development / test / production
+  version: '2.1.0',               // 应用版本，需与 SourceMap 上传版本一致
+})
+```
+
+初始化后 SDK 自动采集：JS 错误、Promise 错误、资源错误、fetch 请求、性能指标、PV。
+
+## 3. 完整配置项
+
+```ts
+init({
+  // ---- 基础（必填） ----
+  projectId: 'kino-log-platfrom',
+  token: 'YOUR_TOKEN',
+  serverUrl: 'https://log.example.com',
+
+  // ---- 基础（可选） ----
+  env: 'production',
+  version: '2.1.0',
+  userId: '10001',              // 也可稍后通过 setUser 设置
+
+  // ---- 采集开关 ----
+  enableError: true,            // JS/Promise/资源错误
+  enablePerformance: true,      // LCP、FCP 等性能指标
+  enableBehavior: true,         // 点击、路由等用户行为
+  enableNetwork: true,          // fetch/axios 请求
+  enableConsole: false,         // console.error/warn 采集
+
+  // ---- 上报策略 ----
+  sampleRate: 1,                // 采样率 0~1
+  batchSize: 50,                // 批量上报条数阈值
+  uploadInterval: 5000,         // 上报间隔（ms）
+  maxRetry: 3,                  // 失败重试次数
+  ignoreErrors: [               // 忽略的错误（字符串或正则）
+    'ResizeObserver loop',
+    /Script error/,
+  ],
+  ignoreUrls: [/\/api\/heartbeat/], // 忽略采集的请求 URL
+
+  // ---- 钩子 ----
+  beforeSend(log) {             // 上报前拦截/加工，返回 false 丢弃
+    if (log.message?.includes('password')) return false
+    // 页面地址脱敏：仅掩码敏感 query 参数，保留非敏感 query 与 hash（推荐，避免页面地址不完整）
+    log.url = scrubUrl(log.url)
+    return log
+  },
+})
+```
+
+> 说明：`sampleRate`、`ignoreErrors`、`uploadInterval`、`batchSize` 等支持在 Admin 后台「SDK 配置中心」动态下发，远端配置优先级高于本地。
+
+## 4. 框架接入
+
+### 4.1 Vue3
+
+```ts
+import { createApp } from 'vue'
+import { init, VuePlugin } from '@aigc-kino/logger-sdk'
+import App from './App.vue'
+
+init({ projectId: 'kino-log-platfrom', token: 'YOUR_TOKEN', serverUrl: 'https://log.example.com' })
+
+const app = createApp(App)
+app.use(VuePlugin)   // 采集 Vue 组件错误（含组件名、props 摘要）
+app.mount('#app')
+```
+
+> 路由 PV 已由内置页面插件自动采集：SDK 劫持 `history.pushState`/`replaceState`/`popstate`/`hashchange`，在 SPA 路由变更时自动上报 `type=page` 的 PV 日志，**无需也不存在 `RouterPlugin`**。若需在主日志中附带当前路由字段，设置 `microFrontend: { hostApp }` 即可（见第 6 节）。
+
+### 4.2 Axios
+
+```ts
+import axios from 'axios'
+import { attachAxios } from '@aigc-kino/logger-sdk'
+
+attachAxios(axios)   // 采集请求 URL、状态码、耗时、失败原因
+```
+
+## 5. API
+
+### 5.1 用户与会话
+
+```ts
+import { clearUser, setUser, setTag, getSessionId, getTraceId } from '@aigc-kino/logger-sdk'
+
+setUser('10001')                     // 兼容旧用法：只设置用户 ID
+setUser('10001', {
+  nickname: 'Alice',
+  email: 'alice@example.com',
+  phone: '13800000000',
+  avatar: 'https://example.com/avatar.png',
+  custom: { plan: 'pro', region: 'cn-east' },
+})
+clearUser()                          // 退出登录时解除后续日志的用户关联
+setTag('channel', 'app')             // 附加全局标签（写入 extra）
+const sessionId = getSessionId()     // 当前会话 ID
+const traceId = getTraceId()         // 当前 Trace ID
+```
+
+用户资料由固定基础字段 `nickname`、`email`、`phone`、`avatar` 和 `custom` 扩展对象组成。部分更新时，未提供的字段保留服务端旧值；显式传入 `null` 会清除对应字段；非空 `custom` 每次整体替换，不做深层合并，`custom: null` 会清空扩展对象。`clearUser()` 只清除 SDK 当前关联，不删除服务端已保存的资料。
+
+资料上报设置 5 秒超时，失败不会阻塞日志采集。SDK 仅在初始化配置启用 `debug` 时输出诊断信息，诊断信息不会包含项目 Token 或用户资料。SDK 不会自动采集姓名、邮箱、手机号等个人信息；接入方必须在取得合法授权并满足适用隐私与合规要求后，才可显式传入这些字段。
+
+### 5.2 业务日志
+
+```ts
+import { track } from '@aigc-kino/logger-sdk'
+
+track('order-paid', {                // type=business
+  orderId: 'O20260731001',
+  amount: 99,
+})
+```
+
+### 5.3 手动上报
+
+```ts
+import { captureError, captureMessage } from '@aigc-kino/logger-sdk'
+
+try {
+  riskyOperation()
+} catch (e) {
+  captureError(e, { scene: 'checkout' })   // type=js-error，extra 附加上下文
+}
+
+captureMessage('库存同步延迟', 'warn')       // type=custom
+```
+
+### 5.4 立即上报与销毁
+
+```ts
+import { flush, destroy } from '@aigc-kino/logger-sdk'
+
+await flush()   // 立即上报缓存中全部日志
+destroy()       // 移除全部监听器并清理（SPA 子应用卸载时调用）
+```
+
+### 5.5 页面地址脱敏
+
+```ts
+import { scrubUrl } from '@aigc-kino/logger-sdk'
+
+// 仅掩码敏感 query 参数（token/password/phone 等）的值，保留非敏感 query 与 hash
+scrubUrl('https://a.com/detail?id=1&token=xx#/edit?tab=2')
+// => 'https://a.com/detail?id=1&token=***#/edit?tab=2'
+```
+
+> 脱敏请在 `beforeSend` 中使用 `scrubUrl`，**不要**直接 `url.search = ''` 全量剥离 query/hash，否则日志中的页面地址会丢失路由参数、无法定位页面。
+
+## 6. qiankun 微前端接入
+
+主应用：
+
+```ts
+init({
+  projectId: 'portal',
+  token: 'PORTAL_TOKEN',
+  serverUrl: 'https://log.example.com',
+  microFrontend: { hostApp: 'portal' },
+})
+```
+
+子应用：
+
+```ts
+init({
+  projectId: 'editor',
+  token: 'EDITOR_TOKEN',
+  serverUrl: 'https://log.example.com',
+  microFrontend: {
+    hostApp: 'portal',
+    microApp: 'editor',
+    container: '#subapp',
+  },
+})
+```
+
+- 日志自动附加 `hostApp`、`microApp`、`route`、`container` 字段；
+- 主/子应用共享 `traceId`，可在 Admin 中跨应用关联查询；
+- 子应用卸载生命周期中调用 `destroy()` 防止内存泄漏。
+
+## 7. SourceMap 上传（配合错误定位）
+
+构建后将 `.map` 文件上传到平台（勿部署到线上 CDN）：
+
+```bash
+curl -X POST https://log.example.com/api/sourcemap/upload \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -F "project=kino-log-platfrom" \
+  -F "version=2.1.0" \
+  -F "file=@dist/assets/main.63df3.js.map"
+```
+
+> `version` 必须与 `init({ version })` 一致，否则堆栈无法解析到源码。
+
+上传后异常中心展示效果：
+
+```text
+原始： main.63df3.js:10982:12
+解析： src/views/Home.vue  line 132  column 18（支持源码预览）
+```
+
+## 8. 上报机制说明
+
+```text
+采集 → 标准化 → IndexedDB 缓存 → 批量上报（fetch keepalive）
+                                    ↓ 失败
+                                  重试（maxRetry）
+页面卸载 → sendBeacon 兜底上报
+```
+
+- 达到 `batchSize` 或到达 `uploadInterval` 即触发一次批量上报；
+- 断网/失败日志持久化在 IndexedDB，恢复后自动补报，不重复；
+- SDK 自身上报请求不会被网络采集（防循环）。
+
+## 9. 日志字段参考
+
+| 字段 | 说明 | 来源 |
+|------|------|------|
+| projectId / env / version | 项目标识 | init 配置 |
+| type / level / message / stack | 日志内容 | 自动采集或手动 API |
+| url | 页面地址 | 自动 |
+| userId | 用户 ID | setUser |
+| sessionId / traceId | 会话 / 链路 | 自动生成 |
+| browser / device / network | 环境信息 | 自动解析 |
+| timestamp | 毫秒时间戳 | 自动 |
+| extra | 扩展字段 | setTag / track / capture* |
+
+## 10. 常见问题（FAQ）
+
+**Q：日志没有上报？**
+依次检查：`projectId`/`token` 是否正确 → 网关地址可达 → 是否被 `sampleRate`/`ignoreErrors` 过滤 → Network 面板中 `/api/log/upload` 响应是否为 `{"success":true}`。
+
+**Q：Script error 无堆栈？**
+跨域脚本需在 `<script>` 上加 `crossorigin="anonymous"`，且 CDN 响应头包含 `Access-Control-Allow-Origin`。
+
+**Q：错误堆栈未解析为源码？**
+确认对应 `version` 的 sourcemap 已上传，且构建产物 hash 与 map 文件匹配。
+
+**Q：如何临时关闭采集？**
+Admin 后台将该项目 `sampleRate` 设为 0，SDK 拉取配置后即停止上报，无需发版。