@pluve/logger-sdk 0.0.8 → 0.0.9

package/README.md

@@ -1,208 +1,146 @@
-# @pluve/logger-sdk 使用说明
+# Logger SDK v2 说明文档
 
 ## 概览
 
-- 轻量级前端日志采集 SDK，支持浏览器与微信小程序
-- 传输优先级：Beacon（页面卸载可靠）→ Image（像素降级）；小程序使用 wx.request
-- 支持：批量上报（默认关闭）、重试与指数退避、持久化队列、自动卸载刷新
-- 会话锁定：init 时生成并锁定 sessionId，destroy 前所有日志使用同一会话
+- 跨环境支持：浏览器与微信小程序
+- 采集与采样：开关、日志等级白名单、分级/来源/路径采样率
+- 传输适配：Beacon、像素图 Image、微信 `wx.request`
+- 批量与队列：批量阈值与定时器、队列持久化（localforage）
+- 重试策略：可配置最大次数与指数退避
+- 压缩能力：可选 gzip 压缩，优先使用浏览器 CompressionStream，回退 fflate.gzipSync
 
-## 安装与引入
-
-- 安装：`yarn add @pluve/logger-sdk`
-- ESM：`import { LoggerSDK } from '@pluve/logger-sdk'`
-- UMD：构建后全局为 `LoggerSDK`
-
-## 快速开始（单例 + init）
+## 快速开始
 
 ```ts
-import { LoggerSDK } from '@pluve/logger-sdk';
+import { LoggerSDK } from './core/loggerSDK';
 
 const sdk = LoggerSDK.getInstance();
+
 sdk.init({
-  endpoint: '/api/log',
-  appId: 'web-shop',
-  env: 'prod', // prod/stage/dev
+  // endpoint: 'https://logger.yfpharmacy.com/log', // 实际使用以 config 中 API 为准
+  appId: 'fe-vue-pc-seed-frontend',
+  env: 'develop',
+  logStage: 'develop',
   debug: true,
-  // enableBatch: true, // 默认 false，如需开启批量
+  // 采集与性能
+  enableGzip: true,
+  enableBatch: true,
+  batchSize: 10,
+  batchInterval: 15000,
+  maxPixelUrlLen: 8192,
+  // 重试
+  enableRetry: true,
+  maxRetries: 3,
+  retryDelay: 1000,
+  retryBackoff: true,
+  // 身份与鉴权
+  userId: 'u-001',
+  storeCode: 's-001',
+  token: '<token>',
+  // 采样率（可选）
+  sampleRate: 1,
 });
 
-// 可选：设置用户与店铺编码，后续上报自动携带
-sdk.identify('user_123');
-sdk.setStoreCode('STORE_001');
-
-// 记录错误（推荐传入 Error，提高定位能力）
-await sdk.track({
-  message: 'TypeError: Cannot read property',
-  error: new Error('TypeError: Cannot read property'),
-  traceId: 'trace-abc-123', // 可选
-  logLevel: 'error', // 可选，默认 'info'
-});
-
-// 记录普通信息
-await sdk.track({
-  message: 'User clicked submit',
-  logLevel: 'info',
-});
-```
-
-## 事件数据结构（实际实现）
-
-```ts
-{
-  // 唯一日志标识：由 appId + UUID + 时间戳组成（非纯 v4）
-  logId: "web-shop24f8d7ef-1ed4-41fc-8aa8-c1c01cfa5b291767079629320",
-  traceId: "trace-123456",        // 可选
-  appId: "web-shop",
-  stage: "prod",                  // prod/stage/dev
-  level: "error",                 // info/warn/error/fatal
-  message: "TypeError: ...",
-  stack: "...",                   // 可选
-  url: "https://...",             // 当前页面
-  userId: "123",                  // 可选（建议脱敏）
-  frontendId: "session_xxx",      // init 时锁定的会话标识（同 sessionId）
-  tags: {                         // 环境标签（init 时收集）
-    platform: "browser",
-    browser: "Chrome",
-    os: "macOS",
-    screenWidth: 1920,
-    screenHeight: 1080,
-    language: "zh-CN"
-  }
-}
-```
-
-## API 与行为
-
-### 单例与初始化
-
-- `LoggerSDK.getInstance(): LoggerSDK` 获取全局唯一实例
-- `init(options: SDKOptions)` 初始化、锁定 `sessionId`、收集环境标签
-- `new LoggerSDK(options?: SDKOptions)` 构造时传入 options 会自动 init
-
-### SDKOptions（实际默认值）
-
-```ts
-interface SDKOptions {
-  endpoint: string; // 必填
-  appId: string; // 必填
-  env?: 'prod' | 'stage' | 'dev'; // 默认 'dev'
-  debug?: boolean; // 默认 false
-  pixelParam?: string; // 默认 'data'
-  maxPixelUrlLen?: number; // 默认 4096
-  enableGzip?: boolean; // 默认 true（传输适配器内部处理）
-  enableBatch?: boolean; // 默认 false（需显式开启）
-  batchSize?: number; // 默认 10
-  batchInterval?: number; // 默认 5000 ms
-  maxQueueSize?: number; // 默认 100
-  enableStorage?: boolean; // 默认 true（队列持久化）
-  storagePrefix?: string; // 默认 'logger_sdk'
-  enableRetry?: boolean; // 默认 true
-  maxRetries?: number; // 默认 3
-  retryDelay?: number; // 默认 1000 ms
-  retryBackoff?: boolean; // 默认 true（指数退避 + 0-30% 抖动，上限 30s）
-}
-```
-
-### 事件上报
-
-- `track(options: TrackOptions)`
-  - `message: string`（必填）
-  - `error?: Error`（推荐在错误场景传入）
-  - `traceId?: string`
-  - `logLevel?: 'info' | 'warn' | 'error' | 'fatal'`（默认 'info'）
-  - `logId` 由 `appId + UUID + now()` 组成，保证唯一
-- `identify(userId: string)` 设置用户标识（自动随事件上报）
-- `setStoreCode(storeCode: string)` 设置店铺编码（自动随事件上报）
-- `flush()` 在批量开启时立即上报队列内容
-- `destroy()` 停止定时器与重试，刷新队列，清理单例并重置会话锁定
-
-### 自动采集
-
-- 浏览器：visibilitychange/pagehide/beforeunload 触发 `flush()`，确保卸载时尽量发送
-- 微信小程序：建议在 App 生命周期中调用（SDK 内部识别环境）
-
-## 传输适配器
-
-- 默认选择：
-  - 小程序：`wx.request`
-  - 浏览器：`navigator.sendBeacon` → 降级到 Image 像素
-- Content-Type：
-  - Beacon：`application/json`；启用 gzip 时为 `application/json; charset=utf-8`
-  - 小程序：`application/json`；启用 gzip 时为 `application/json; charset=utf-8`
-  - Image：通过 query 拼接，受 URL 长度限制（默认 4096）
-
-## 重试策略（实际实现）
-
-- 启用时对单事件与批量发送采用统一重试
-- 指数退避：`baseDelay * (2 ** (attempt - 1))`
-- 抖动：`delay * [0, 0.3]`，最大不超过 30000ms
-- 防重复：同一 taskId 重试中会拒绝重复执行
-
-## 场景示例
-
-```ts
-// 错误监控（浏览器）
-window.addEventListener('error', (event) => {
-  sdk.track({
-    message: event.message,
-    error: event.error,
-    logLevel: 'error',
-    traceId: `err-${Date.now()}`,
-  });
-});
-
-// Promise 未捕获
-window.addEventListener('unhandledrejection', (event) => {
-  sdk.track({
-    message: 'Unhandled Promise Rejection',
-    error: new Error(String(event.reason)),
-    logLevel: 'error',
-  });
-});
-
-// 页面浏览
+// 业务日志
 sdk.track({
-  message: `Pageview: ${document.title}`,
-  logLevel: 'info',
-  traceId: `pv-${Date.now()}`,
+  message: '用户点击了购买按钮',
+  traceId: 'trace-xyz',
+  logLevel: 'INFO',
 });
+
+// 动态设置
+sdk.identify('u-002');
+sdk.setStoreCode('s-002');
+sdk.setStage('testing');
 ```
 
-## 最佳实践与安全
-
-- 初始化后统一设置用户与店铺信息（`identify`/`setStoreCode`）
-- userId/message/stack/tags 建议在业务侧脱敏与裁剪
-- 避免在 tags 中上传 cookie/localStorage 原始值、账户/手机号/身份证等敏感信息
-
-## 迁移指南（多实例 → 单例 + init）
-
-- 统一在应用入口：`LoggerSDK.getInstance().init(opts)`
-- 其他模块直接使用该单例进行 `track/trace/flush`
-- 会话边界：登出/身份切换/子应用卸载时调用 `destroy()`，随后重新 `init()`
-
-## 发布与类型构建
-
-- 多产物发布
-  - ESM：dist/esm（现代浏览器与打包器）
-  - CJS：dist/cjs（Node/工具链）
-  - UMD（压缩）：dist/umd/logger-sdk.min.js（CDN/script 标签，全局 `LoggerSDK`）
-- 包入口与导出
-  - main 指向 CJS，module 指向 ESM，browser 指向 ESM
-  - exports 同时声明 import/require/default，现代打包器自动选择
-  - unpkg/jsdelivr 指向 UMD 压缩产物
-- tsconfig 策略
-  - tsconfig.base.json：通用编译选项（target、module、lib、skipLibCheck 等）
-  - tsconfig.json：仅类型检查（noEmit: true）
-  - tsconfig.types.json：仅声明构建（emitDeclarationOnly，declarationDir: dist/types）
-- 脚本
-  - 类型检查：`yarn typecheck`
-  - 声明构建：`yarn build-types`
-  - 代码产物：`yarn build`
-- 使用建议
-  - CDN：`https://unpkg.com/@pluve/logger-sdk/dist/umd/logger-sdk.min.js`，全局变量 `LoggerSDK`
-  - 打包器：优先使用 ESM（import { LoggerSDK } from '@pluve/logger-sdk'）
-
-## 其他
-
-生成 mermaid 图：`yarn generate-mermaid`
+## 配置项（节选）
+
+- enableGzip：是否启用 gzip 压缩（默认 true）
+- enableBatch：是否启用批量上报（默认需显式开启）
+- batchSize：批量阈值（默认 10）
+- batchInterval：批量定时器间隔（默认 15000ms）
+- maxPixelUrlLen：像素图 URL 最大长度（默认 8192）
+- enableStorage：队列持久化开关（默认 true）
+- enableRetry/maxRetries/retryDelay/retryBackoff：重试相关配置
+- sampleRate/levelSampleRate/sourceSampleRate/pathSampleRate：采样配置
+
+详细定义参考类型文件：[sdkOptions.ts](src/pages/logger-sdk-tester/logger-sdk-v2/types/sdkOptions.ts).
+
+## 压缩实现
+
+- gzipCompress(data)
+  - 浏览器支持 CompressionStream 时，流式 gzip 压缩，再转 Base64 字符串
+  - 不支持时，回退到 fflate.gzipSync(默认压缩级别)，转 Base64
+  - 返回值为 Base64 字符串，适用于传输（像素图 URL/JSON 体）
+- 代码参考：[compression.ts](src/pages/logger-sdk-tester/logger-sdk-v2/compress/compression.ts).
+- 备注：当前默认压缩级别，无级别可调参数暴露；如需级别控制可在 fflate 路径引入配置。
+
+## 传输适配
+
+- TransportAdapter 根据环境选择传输器：
+  - 微信：WechatTransport（wx.request POST，支持 gzip）
+  - 浏览器：优先 BeaconTransport（sendBeacon Blob），否则 PixelImageTransport（Image GET）
+- WechatTransport
+  - 请求体字符串化 safeStringify
+  - enableGzip 时使用 gzipCompress 生成 Base64，Content-Type 设为 `application/json; charset=utf-8`
+- PixelImageTransport
+  - 字符串化 items，enableGzip 时压缩为 Base64，URL 参数附带 `gzip=1`
+  - 构造像素上报 URL（含 appId、appStage、items、cacheBuster）
+  - URL 超长打印警告
+- BeaconTransport
+  - 使用 Blob 指定 Content-Type，通过 `navigator.sendBeacon` 发送
+
+代码参考：
+
+- 适配器选择：[transportAdapter.ts](src/pages/logger-sdk-tester/logger-sdk-v2/transport/transportAdapter.ts)
+- WeChat：[wechatTransport.ts](src/pages/logger-sdk-tester/logger-sdk-v2/transport/wechatTransport.ts)
+- Pixel Image：[pixelImageTransport.ts](src/pages/logger-sdk-tester/logger-sdk-v2/transport/pixelImageTransport.ts)
+- Beacon：[beaconTransport.ts](src/pages/logger-sdk-tester/logger-sdk-v2/transport/beaconTransport.ts)
+
+## 批量与队列
+
+- 启用批量后，事件入队，当队列大小达到 batchSize 或定时器触发时 flush
+- flush：按 appId|stage 分组与分块（最多 200/块），批量发送成功后出队
+- 队列持久化：localforage 存储，页面刷新/卸载可恢复
+- 页面事件触发 flush：visibilitychange（hidden）、pagehide、beforeunload
+- 代码参考：
+  - [queueManager.ts](src/pages/logger-sdk-tester/logger-sdk-v2/core/queueManager.ts)
+  - [loggerSDK.ts（flush/sendBatch）](src/pages/logger-sdk-tester/logger-sdk-v2/core/loggerSDK.ts#L452-L485)
+
+## 重试策略
+
+- 单个事件 sendEvent 与批量 sendBatch 均支持 executeWithRetry
+- 可配置最大次数、基础延迟、指数退避
+- 代码参考：[retryManager.ts](src/pages/logger-sdk-tester/logger-sdk-v2/core/retryManager.ts)
+
+## 采样与开关
+
+- 后端注册返回：
+  - collectSwitch：采集开关（0 关闭）
+  - collectLogLevel：采集日志等级白名单
+  - samplingRate：全局采样率
+- 前端 shouldSend：
+  - 综合 level/source/path/global 采样率
+  - 基于 seed 哈希概率决定是否发送
+- 参考：
+  - [loggerSDK.ts（shouldSend）](src/pages/logger-sdk-tester/logger-sdk-v2/core/loggerSDK.ts#L348-L411)
+  - [api.ts](src/pages/logger-sdk-tester/logger-sdk-v2/types/api.ts)
+
+## 数据格式
+
+- LogEvent：标准化日志格式（logId/seq/appId/stage/level/traceId/frontendId/url/location/message/throwable/userId/storeCode/tags）
+  - 类型参考：[logEvent.ts](src/pages/logger-sdk-tester/logger-sdk-v2/types/logEvent.ts)
+- ReportData：上报批次（appId/appStage/items[]）
+
+## 限制与注意
+
+- Beacon：浏览器与网络环境兼容性依赖，失败仅打印不抛出
+- 像素图：URL 长度受限；压缩可显著降低长度但 Base64 会比二进制略增
+- 压缩：CompressionStream 不提供压缩级别参数；fflate 同步压缩适合小批量数据
+- 安全：不要在日志中包含敏感数据（token、密码、隐私信息等）
+
+## 流程图
+
+- 完整 Mermaid 流程图见文件：
+  - [logger-sdk.mermaid](src/pages/logger-sdk-tester/logger-sdk-v2/logger-sdk.mermaid)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pluve/logger-sdk",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "logger sdk",
   "keywords": [
     "logger"

package/dist/cjs/logger-sdk.mermaid

@@ -1,84 +0,0 @@
-flowchart TD
-  A[初始化 SDK] --> B[设置选项（批量/重试/gzip/自动采集）]
-  B --> C{启用批量?}
-  C -->|是| D[创建队列管理器并加载存储]
-  C -->|否| E[跳过队列管理器]
-  B --> F{启用重试?}
-  F -->|是| G[创建重试管理器]
-  F -->|否| H[跳过重试管理器]
-  B --> I[选择传输适配器]
-  I --> J{运行环境}
-  J -->|微信小程序| K[WechatTransport]
-  J -->|浏览器| L{支持 Beacon?}
-  L -->|是| M[BeaconTransport]
-  L -->|否| N[PixelImageTransport]
-  B --> O[生成会话ID]
-  B --> P[收集环境标签]
-  B --> Q[注册 SDK]
-  Q --> R[接收初始化数据: 开关/等级/采样率]
-  R --> S{启用批量?}
-  S -->|是| T[启动批量定时器]
-  R --> U[挂载卸载/可见性事件处理]
-  U --> V{enableAutoCapture?}
-  V -->|是| V1[按 autoCapture: 注册 js/promise/resource/wechat]
-  V -->|否| V2[跳过自动采集]
-
-  subgraph 采集与上报
-    W[调用 track 或自动采集] --> X{已初始化且未关闭?}
-    X -->|否| X1[跳过]
-    X -->|是| X2{3秒去重窗口?}
-    X2 -->|重复| X3[跳过]
-    X2 -->|非重复| Y{shouldSend 采样?}
-    Y -->|否| Y1[采样丢弃]
-    Y -->|是| Z[构建 LogEvent]
-    Z --> AA{启用批量?}
-    AA -->|是| AB[enqueue 入队]
-    AB --> AC{队列达到批量阈值?}
-    AC -->|是| AD[flush 刷新]
-    AC -->|否| AE[等待定时器/下一次触发]
-    AA -->|否| AF[sendEvent 直接发送]
-  end
-
-  subgraph 批量刷新
-    AD --> AG[peek 读取待发事件]
-    AG --> AH[sendBatch 批量发送]
-    AH --> AI[按 appId & stage 分组并分块]
-    AI --> AJ[transporter.send（并发收集）]
-    AJ --> AK[dequeue 成功后出队]
-  end
-
-  subgraph 传输细节
-    K --> K1[字符串化; 启用 gzip 时压缩成 Base64; wx.request POST]
-    M --> M1{启用 gzip? 且满足批量条件}
-    M1 -->|是| M2[压缩 items 为 Base64 字符串; 替换 body 为 「...payload, items: Base64」; 设置 Content-Type]
-    M1 -->|否| M3[直接 JSON body; Blob 包裹; sendBeacon POST]
-    N --> N1[字符串化 items; gzip: Base64 / btoa / encodeURIComponent 回退; Image GET]
-  end
-
-  subgraph 压缩流程
-    C1[gzipCompress（data）] --> C2{支持 CompressionStream?}
-    C2 -->|是| C3[CompressionStream（'gzip'） 流式压缩后 Base64]
-    C2 -->|否| C4[fflate.gzipSync + Base64.fromUint8Array]
-  end
-
-  subgraph 定时与卸载
-    T --> T1[setInterval 周期性 flush]
-    U --> U1[visibilitychange/pagehide/beforeunload 触发 flush]
-    V1 --> U2[销毁时统一 off（js/promise/resource/wechat）]
-  end
-
-  subgraph 重试策略
-    AF --> R1{启用重试?}
-    R1 -->|是| R2[executeWithRetry（event.logId, sendFn）]
-    R1 -->|否| R3[直接 sendFn]
-    AH --> R4{启用重试?}
-    R4 -->|是| R5[executeWithRetry（batchId, sendFn）]
-    R4 -->|否| R6[直接 sendFn]
-  end
-
-  subgraph 存储兼容
-    D --> D1{环境}
-    D1 -->|浏览器| D2[动态 import localforage 使用 IndexedDB; 失败回退 localStorage]
-    D2 --> D2a[如解析失败: 回退 globalThis.localforage]
-    D1 -->|微信小程序| D3[使用 wx.storage 同步 API]
-  end