@pluve/logger-sdk 0.0.6 → 0.0.8

package/README.md

@@ -1,501 +1,208 @@
 # @pluve/logger-sdk 使用说明
 
-## 简介
+## 概览
 
-- 轻量级前端日志采集 SDK，支持 H5 浏览器环境和微信小程序
-- 使用 Beacon 和像素图（Image）方式上报，确保兼容性与可靠性
-- 标准化日志格式，易于分析和处理
-- 支持批量上报、异常重试、持久化存储等高级功能
+- 轻量级前端日志采集 SDK，支持浏览器与微信小程序
+- 传输优先级：Beacon（页面卸载可靠）→ Image（像素降级）；小程序使用 wx.request
+- 支持：批量上报（默认关闭）、重试与指数退避、持久化队列、自动卸载刷新
+- 会话锁定：init 时生成并锁定 sessionId，destroy 前所有日志使用同一会话
 
 ## 安装与引入
 
-- 安装：`pnpm add @pluve/logger-sdk`
-- ESM：`import LoggerSDK from '@pluve/logger-sdk'`
+- 安装：`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 '@pluve/logger-sdk';
 
-// 推荐使用单例
 const sdk = LoggerSDK.getInstance();
 sdk.init({
   endpoint: '/api/log',
   appId: 'web-shop',
   env: 'prod', // prod/stage/dev
   debug: true,
-  // 默认批量关闭，如需开启：
-  // enableBatch: true,
+  // enableBatch: true, // 默认 false，如需开启批量
 });
 
-// init 会自动上报一次 'session_start'，携带环境信息（UA/OS/屏幕等）
-// 后续事件默认不再合并环境标签（节省流量）
-
-// 记录错误日志
-await sdk.track('error', 'TypeError: Cannot read property', undefined, {
-  level: 'error',
-  stack: 'Error stack trace...',
-  userId: '123',
-  tags: {
-    component: 'checkout',
-  },
-});
+// 可选：设置用户与店铺编码，后续上报自动携带
+sdk.identify('user_123');
+sdk.setStoreCode('STORE_001');
 
-// 记录带 traceId 的错误（用于关联多个日志）
-await sdk.track('error', 'Request failed', 'trace-abc-123', {
-  level: 'error',
-  tags: { api: '/api/user' },
+// 记录错误（推荐传入 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('custom', 'User clicked button', undefined, {
-  level: 'info',
-  tags: { action: 'click', button: 'submit' },
+// 记录普通信息
+await sdk.track({
+  message: 'User clicked submit',
+  logLevel: 'info',
 });
 ```
 
-## 标准化日志格式
-
-上报的日志数据遵循以下标准格式：
+## 事件数据结构（实际实现）
 
-```typescript
+```ts
 {
-  "logId": "550e8400-e29b-41d4-a716-446655440000",  // 日志 ID（UUID v4）
-  "traceId": "trace-123456",    // 可选：追踪 ID（用于关联多个日志）
-  "eventType": "error",          // 固定：error/crash/pageview/custom/session_start
-  "ts": 1690000000000,           // 毫秒时间戳
-  "appId": "web-shop",           // 应用标识
-  "env": "prod",                 // prod/stage/dev
-  "level": "error",              // info/warn/error/fatal
-  "message": "TypeError: ...",   // 摘要
-  "stack": "...",                // 可选：长字符串
-  "url": "https://...",          // 发生页面
-  "userId": "123",               // 可选：用户ID（脱敏）
-  "sessionId": "...",            // 会话标识
-  "tags": {                       // 可选的结构化额外信息
-    "component": "checkout",
-    "browser": "Chrome 120"
+  // 唯一日志标识：由 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
+## API 与行为
 
 ### 单例与初始化
 
-#### `LoggerSDK.getInstance(): LoggerSDK`
-
-获取全局唯一实例。
-
-#### `init(options: SDKOptions)`
+- `LoggerSDK.getInstance(): LoggerSDK` 获取全局唯一实例
+- `init(options: SDKOptions)` 初始化、锁定 `sessionId`、收集环境标签
+- `new LoggerSDK(options?: SDKOptions)` 构造时传入 options 会自动 init
 
-初始化 SDK、生成并锁定 sessionId、收集环境信息并上报一次 `session_start`。
-注意：锁定的 sessionId 将在销毁前用于所有日志上报。
+### SDKOptions（实际默认值）
 
-#### `new LoggerSDK(options?: SDKOptions)`
-
-创建 SDK 实例；如果传入 `options`，会在构造时自动调用 `init(options)`。
-
-**配置项：**
-
-```typescript
+```ts
 interface SDKOptions {
-  endpoint: string; // 上报端点 URL（必选）
-  appId: string; // 应用 ID（必选）
-  env?: Env; // 环境标识：prod/stage/dev，默认 'dev'
-  debug?: boolean; // 是否开启调试模式
-  pixelParam?: string; // 像素上报参数名，默认 'data'
-  maxPixelUrlLen?: number; // 像素上报 URL 最大长度，默认 1900
-  enableGzip?: boolean; // 是否启用 gzip（传输适配器内部处理）
-  
-  // 批量上报配置
-  enableBatch?: boolean; // 是否启用批量上报，默认 false（需显式开启）
-  batchSize?: number; // 批量上报最大数量，默认 10
-  batchInterval?: number; // 批量上报时间间隔（毫秒），默认 5000
-  maxQueueSize?: number; // 队列最大长度，默认 100
-  
-  // 持久化存储配置
-  enableStorage?: boolean; // 是否启用持久化存储，默认 true
-  storagePrefix?: string; // 持久化存储的 key 前缀，默认 'logger_sdk'
-  
-  // 重试配置
-  enableRetry?: boolean; // 是否启用重试，默认 true
-  maxRetries?: number; // 最大重试次数，默认 3
-  retryDelay?: number; // 重试基础延迟时间（毫秒），默认 1000
-  retryBackoff?: boolean; // 是否使用指数退避策略，默认 true
+  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(eventType, message, traceId?, options?)`
-
-记录事件日志。每条日志会自动生成唯一的 `logId`（UUID v4 格式）。
-
-**参数：**
-
-- `eventType`: 事件类型（`'error' | 'crash' | 'pageview' | 'custom'`）
-- `message`: 摘要信息
-- `traceId`: (可选) 追踪 ID，用于关联多个相关日志
-- `options`: 可选配置
-  - `level?`: 日志级别（`'info' | 'warn' | 'error' | 'fatal'`），默认 `'info'`
-  - `stack?`: 堆栈信息
-  - `userId?`: 用户 ID
-  - `tags?`: 额外的结构化信息
-
-**示例：**
-
-```typescript
-// 记录错误
-sdk.track('error', 'Failed to load resource', {
-  level: 'error',
-  stack: error.stack,
-  userId: '123',
-  tags: { resource: 'image.png' },
-});
-
-// 记录带 traceId 的错误（用于关联多个日志）
-sdk.track('error', 'API request failed', 'trace-xyz-789', {
-  level: 'error',
-  tags: { endpoint: '/api/users', statusCode: 500 },
-});
-
-// 记录页面浏览
-sdk.track('pageview', 'User viewed product page', {
-  level: 'info',
-  tags: { productId: 'P123' },
-});
-```
-
-### 日志 ID 和追踪 ID
-
-- **logId**: 每条日志自动生成的唯一标识符（UUID v4 格式），用于全局唯一定位日志
-- **traceId**: 可选的追踪 ID，用于关联同一请求链路上的多个日志（例如：前端请求、后端处理、数据库查询等）
+### 事件上报
 
-```typescript
-// 在请求开始时生成 traceId
-const traceId = `trace-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+- `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()` 停止定时器与重试，刷新队列，清理单例并重置会话锁定
 
-// 在请求的不同阶段使用相同的 traceId
-sdk.track('custom', 'Request started', traceId, {
-  level: 'info',
-  tags: { endpoint: '/api/checkout' },
-});
+### 自动采集
 
-// ... 请求处理 ...
+- 浏览器：visibilitychange/pagehide/beforeunload 触发 `flush()`，确保卸载时尽量发送
+- 微信小程序：建议在 App 生命周期中调用（SDK 内部识别环境）
 
-sdk.track('error', 'Request failed', traceId, {
-  level: 'error',
-  tags: { endpoint: '/api/checkout', error: 'Network timeout' },
-});
-```
+## 传输适配器
 
-### `identify(userId: string)`
+- 默认选择：
+  - 小程序：`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）
 
-设置用户 ID（用于后续日志关联）。
+## 重试策略（实际实现）
 
-### `trace(error: Error | string, options?)`
+- 启用时对单事件与批量发送采用统一重试
+- 指数退避：`baseDelay * (2 ** (attempt - 1))`
+- 抖动：`delay * [0, 0.3]`，最大不超过 30000ms
+- 防重复：同一 taskId 重试中会拒绝重复执行
 
-错误专用方法，自动设置 `eventType: 'error'` 与 `level: 'error'`，不合并环境标签。
+## 场景示例
 
 ```ts
-try {
-  throw new Error('Network Error');
-} catch (e) {
-  await sdk.trace(e as Error, { userId: 'u123', traceId: 'req-1' });
-}
-```
-
-### `destroy()`
-
-销毁 SDK 实例，停止所有监听。
-
-销毁后单例会被清理；如需新会话，重新调用 `init()` 即可生成新的 sessionId。
-
-### 会话管理
-
-- 在 `init()` 时生成并锁定 `sessionId`
-- 在调用 `destroy()` 前，所有日志都会使用该 `sessionId`
-- 重新 `init()` 将开始新的会话（新的 `sessionId`）
-
-## 自动采集
-
-SDK 会自动监听以下页面事件并上报：
-
-- **页面隐藏**（`visibilitychange`）：当页面变为隐藏状态时
-- **页面卸载**（`pagehide`, `beforeunload`）：当用户离开页面时
-
-这些事件使用 Beacon API 上报，确保在页面关闭时仍能成功发送。
-
-## 上报方式
-
-SDK 使用两种上报方式，按优先级自动选择：
-
-### 1. Beacon API（优先）
-
-- **兼容性**：Chrome 39+, Firefox 31+, Edge 14+
-- **特点**：页面卸载时可靠传输，不阻塞页面关闭
-- **限制**：无法获取响应，队列大小限制（通常 64KB）
-
-### 2. Image 像素上报（降级）
-
-- **兼容性**：所有浏览器
-- **特点**：轻量级，无跨域限制
-- **限制**：URL 长度限制（默认 1900 字符）
-
-如果 Beacon 失败，会自动降级到 Image 方式。
-
-### 微信小程序适配器
-
-- 环境：微信小程序
-- 支持：请求成功/失败/非 2xx 状态码与超时控制
-- Header Content-Type 会根据是否启用 gzip 自动调整
-
-## 使用场景
-
-### 错误监控
-
-```typescript
-// 全局错误捕获
+// 错误监控（浏览器）
 window.addEventListener('error', (event) => {
-  sdk.track('error', event.message, {
-    level: 'error',
-    stack: event.error?.stack,
-    tags: {
-      filename: event.filename,
-      lineno: event.lineno,
-      colno: event.colno,
-    },
+  sdk.track({
+    message: event.message,
+    error: event.error,
+    logLevel: 'error',
+    traceId: `err-${Date.now()}`,
   });
 });
 
-// Promise 错误捕获
+// Promise 未捕获
 window.addEventListener('unhandledrejection', (event) => {
-  sdk.track('error', 'Unhandled Promise Rejection', {
-    level: 'error',
-    stack: event.reason?.stack || String(event.reason),
+  sdk.track({
+    message: 'Unhandled Promise Rejection',
+    error: new Error(String(event.reason)),
+    logLevel: 'error',
   });
 });
-```
-
-### 页面浏览统计
 
-```typescript
-// 记录页面浏览
-sdk.track('pageview', document.title, {
-  level: 'info',
-  tags: {
-    path: window.location.pathname,
-    referrer: document.referrer,
-  },
+// 页面浏览
+sdk.track({
+  message: `Pageview: ${document.title}`,
+  logLevel: 'info',
+  traceId: `pv-${Date.now()}`,
 });
 ```
 
-### 用户行为追踪
-
-```typescript
-// 记录用户点击
-button.addEventListener('click', () => {
-  sdk.track('custom', 'Button clicked', {
-    level: 'info',
-    userId: currentUserId,
-    tags: {
-      buttonId: button.id,
-      page: 'checkout',
-    },
-  });
-});
-```
-
-## 最佳实践
-
-1. **设置正确的环境标识**：确保在不同环境（prod/stage/dev）使用正确的配置
-2. **使用有意义的 message**：摘要信息应简洁明了，便于快速定位问题
-3. **合理使用 tags**：将额外的结构化信息放在 tags 中，便于分析和过滤
-4. **用户隐私保护**：userId 应该经过脱敏处理
-5. **控制日志量**：避免在高频操作中记录过多日志
-
-## 调试
-
-开启调试模式查看控制台输出：
+## 最佳实践与安全
 
-```typescript
-const sdk = new LoggerSDK({
-  endpoint: '/api/log',
-  debug: true, // 开启调试
-});
-```
+- 初始化后统一设置用户与店铺信息（`identify`/`setStoreCode`）
+- userId/message/stack/tags 建议在业务侧脱敏与裁剪
+- 避免在 tags 中上传 cookie/localStorage 原始值、账户/手机号/身份证等敏感信息
 
-## 高级功能
-
-### 批量上报
-
-SDK 支持批量上报功能，可以显著减少网络请求次数，提高性能：
-
-- **队列缓存**：日志先缓存到内存队列，达到条件后批量发送
-- **智能触发**：支持按数量阈值和时间间隔触发上报
-- **手动控制**：提供 `flush()` 方法可手动立即上报
-
-### 异常重试
-
-为确保日志可靠上报，SDK 提供了自动重试机制：
-
-- **自动重试**：上报失败时自动重试（默认最多3次）
-- **指数退避**：采用指数退避策略（1秒→2秒→4秒...）
-- **随机抖动**：添加0-30%随机延迟避免惊群效应
-
-### 持久化存储
-
-为了防止因页面意外关闭导致日志丢失，SDK 支持持久化存储：
-
-- **自动保存**：队列数据自动保存到 localStorage（浏览器）或 Storage（微信小程序）
-- **自动恢复**：页面刷新后自动恢复未上报的日志
-
-## 核心流程
-
-```mermaid
-graph TB
-    A[用户调用 track() 方法] --> B{SDK是否已销毁?}
-    B -- 是 --> C[直接返回，不处理]
-    B -- 否 --> D[生成标准化日志对象]
-    D --> E{是否启用批量上报?}
-    E -- 否 --> F[直接上报日志]
-    E -- 是 --> G[将日志加入队列]
-    G --> H{队列大小是否达到批处理阈值?}
-    H -- 是 --> I[立即触发批量上报]
-    H -- 否 --> J[等待下次触发]
-    
-    F --> K{是否启用重试机制?}
-    K -- 是 --> L[使用重试管理器发送]
-    K -- 否 --> M[直接发送请求]
-    
-    L --> N[重试管理器执行发送任务]
-    N --> O{发送是否成功?}
-    O -- 是 --> P[上报完成]
-    O -- 否 --> Q[是否达到最大重试次数?]
-    Q -- 否 --> R[计算延迟时间<br/>（指数退避+随机抖动）]
-    R --> S[等待后重试]
-    S --> N
-    Q -- 是 --> T[上报失败，记录错误]
-    
-    M --> U{发送是否成功?}
-    U -- 是 --> P
-    U -- 否 --> T
-    
-    I --> V[执行批量上报]
-    V --> W[从队列获取待发送日志]
-    W --> X[调用重试管理器发送批量日志]
-    X --> Y{批量发送是否成功?}
-    Y -- 是 --> Z[从队列中移除已发送日志]
-    Y -- 否 --> AA[保留队列中的日志，下次重试]
-    
-    J --> AB{定时器是否触发?}
-    AB -- 是 --> AC[执行批量上报]
-    AB -- 否 --> AD{页面是否卸载?}
-    AD -- 是 --> AE[调用 flush() 方法上报所有日志]
-    
-    subgraph 队列管理
-        AF[内存队列]
-        AG[持久化存储<br/>localStorage/Storage]
-        AF <--> AG
-    end
-    
-    subgraph 传输适配器
-        AH[Beacon 适配器]
-        AI[Image 像素适配器]
-        AJ[微信小程序适配器]
-        AK[自动选择最佳适配器]
-        AH --> AK
-        AI --> AK
-        AJ --> AK
-    end
-    
-    Z --> P
-    AA --> P
-    AC --> V
-    AE --> V
-```
+## 迁移指南（多实例 → 单例 + init）
 
-## 使用示例
+- 统一在应用入口：`LoggerSDK.getInstance().init(opts)`
+- 其他模块直接使用该单例进行 `track/trace/flush`
+- 会话边界：登出/身份切换/子应用卸载时调用 `destroy()`，随后重新 `init()`
 
-### 基础使用（默认启用所有高级功能）
+## 发布与类型构建
 
-```typescript
-import { LoggerSDK } from '@pluve/logger-sdk';
-
-const sdk = new LoggerSDK({
-  endpoint: 'https://your-api.com/logs',
-  appId: 'my-app',
-  env: 'prod',
-  debug: false,
-});
-
-// 记录错误日志
-sdk.track('error', 'TypeError: Cannot read property', {
-  level: 'error',
-  stack: 'Error stack trace...',
-  userId: '123',
-  tags: {
-    component: 'checkout',
-    browser: 'Chrome 120',
-  },
-});
-```
-
-### 批量上报配置
-
-```typescript
-const sdk = new LoggerSDK({
-  endpoint: 'https://your-api.com/logs',
-  appId: 'my-app',
-  
-  // 批量上报配置
-  enableBatch: true,     // 启用批量上报
-  batchSize: 20,         // 队列达到20条时批量上报
-  batchInterval: 10000,  // 或每隔10秒上报一次
-  maxQueueSize: 100,     // 队列最大100条日志
-  
-  // 持久化存储配置
-  enableStorage: true,   // 启用持久化存储
-  storagePrefix: 'my_app_logger',
-});
-```
-
-### 重试机制配置
-
-```typescript
-const sdk = new LoggerSDK({
-  endpoint: 'https://your-api.com/logs',
-  appId: 'my-app',
-  
-  // 重试配置
-  enableRetry: true,     // 启用重试机制
-  maxRetries: 5,         // 最多重试5次
-  retryDelay: 2000,      // 基础延迟2秒
-  retryBackoff: true,    // 启用指数退避
-});
-```
-
-### 手动刷新队列
-
-```typescript
-// 立即上报所有待发送日志
-await sdk.flush();
-```
-
-### 禁用批量上报（实时上报）
-
-```typescript
-const sdk = LoggerSDK.getInstance();
-sdk.init({
-  endpoint: 'https://your-api.com/logs',
-  appId: 'my-app',
-  enableBatch: false, // 默认即为 false；每条日志立即发送
-  enableRetry: true,
-});
-```
+- 多产物发布
+  - 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'）
 
-## 重要说明
+## 其他
 
-- `init()` 会自动上报 `session_start`，携带环境信息标签（仅此一次）
-- 普通事件默认不合并环境标签，建议仅在必要时通过 `tags` 传入额外信息
-- 推荐使用 `LoggerSDK.getInstance()` 获取单例，避免多实例重复初始化
+生成 mermaid 图：`yarn generate-mermaid`