@antglobal/rlog-sdk 0.0.1755855517-dev.17 → 0.0.1755855517-dev.18

package/README.md

@@ -1,525 +1,245 @@
-# rlog-sdk 性能与安全设计文档
+# @antglobal/rlog-sdk
 
-## 动态配置功能
+基于 [rrweb](https://github.com/rrweb-io/rrweb) 的用户行为录制与上报 SDK，用于 Web 应用的会话回放、错误追踪和行为分析。
 
-### 1. CDN 配置支持
-SDK 现在支持从 CDN 获取动态配置，可以实时调整以下参数：
-- 采集总开关
-- Canvas 录制采样率
-- 数据上传时间间隔
+## 特性
 
-### 2. 配置参数说明
-CDN 配置文件应为 JSON 格式，包含以下字段：
+- **全量录制** — 持续录制用户操作，定时上传
+- **错误模式录制** — 仅在发生错误时上传前后时间窗口内的录制数据
+- **多 Tab 隔离** — 每个标签页独立 Session，分布式锁保证数据安全
+- **存储自动降级** — IndexedDB > LocalStorage > Memory
+- **网络监控** — 拦截 XHR/Fetch，记录请求响应，支持黑白名单过滤
+- **路由监控** — 监听 History API 和 Hash 变化，记录页面停留时间
+- **Console 录制** — 可选的 console 输出捕获（rrweb 插件）
+- **上传重试** — 失败自动重试，超过阈值停止录制并派发事件
+- **Web Worker 上传** — 后台线程上传，不阻塞主线程
+- **只采集不上报** — 可动态切换的 consume-only 模式
+- **自定义事件** — 支持注入业务自定义事件到录制流
+- **错误上报** — 全局 JS 错误和资源加载错误自动捕获
 
-#### 基础配置
-```json
-{
-  "enable": true,           // 采集总开关
-  "uploadInterval": 2000,   // 数据上传时间间隔 (毫秒)
-  "configUpdateInterval": 300000,  // 配置更新时间间隔 (毫秒)，默认 5 分钟
-  "checkoutEveryNms": 5000, // 每N毫秒做一次全量快照，默认 5 秒
-  "captureMode": "full",    // 采集模式: 'full' 全量采集(默认) | 'error' 错误采集
-  "packEvents": false,      // 是否使用rrweb的packFn压缩事件数据，默认false
-  "clearStorageBeforeRecord": true, // 是否在开始录制前清空存储数据，默认true
-  "http": false,            // 是否开启接口请求抓取，默认false
-  "maxRetryCount": 3,       // 上传失败最大重试次数，默认3次
-  "consumeOnly": false,     // 只采集不上报模式，默认false
-  "urlParamsToCache": [],   // 需要从URL中缓存和上报的参数名称列表
-  
-  // 事件采样配置
-  "sampling": {
-    "canvas": 15,           // Canvas 采样率 (帧/秒)，默认 15
-    "mousemove": 50,        // 鼠标移动事件采样间隔 (毫秒)，false表示不录制
-    "scroll": 100,          // 滚动事件防抖间隔 (毫秒)
-    "input": "last"         // 输入事件录制时机: 'all' 全部 | 'last' 只记录最终值
-  },
-  
-  // rrweb 相关 CSS 类名配置
-  "ignoreClass": "rr-ignore",    // 忽略采集的CSS类名
-  "blockClass": "rr-block",      // 阻塞采集的CSS类名
-  "maskTextClass": "rr-mask",    // 文本遮罩的CSS类名
-  
-  // 错误采集模式配置 (仅在 captureMode='error' 时生效)
-  "errorCapture": {
-    "beforeDuration": 30000,     // 错误发生前录制时长 (毫秒)，默认 30000
-    "afterDuration": 30000,      // 错误发生后继续录制时长 (毫秒)，默认 30000
-    "httpErrorThreshold": 400    // HTTP 错误状态码阈值，>= 该值视为错误，默认 400
-  }
-}
-```
+## 安装
 
-#### Console录制插件配置
-```json
-{
-  "console": {
-    "enable": true,                    // 是否启用console录制，默认false
-    "level": ["log", "warn", "error", "info"],  // 需要录制的console方法，默认['log', 'warn', 'error', 'info']
-    "lengthThreshold": 1000,           // 最大录制条数，默认1000
-    "stringifyOptions": {
-      "stringLengthLimit": 500,        // 单个值能转化的最大字符串长度，默认不限制
-      "numOfKeysLimit": 50,            // 被序列化的js对象能够包含的最大key数量，默认50
-      "depthOfLimit": 4                // 对象能够拥有的最大深度（层数），默认4
-    }
-  }
-}
+```bash
+npm install @antglobal/rlog-sdk
 ```
 
-#### 路由监控配置
-```json
-{
-  "routerMonitor": {
-    "enable": false,                   // 是否启用路由监控，默认false
-    "trackHashChange": true,           // 是否监听hash变化，默认true
-    "trackHistoryChange": true,        // 是否监听History API变化，默认true
-    "trackPageStayTime": true,         // 是否计算页面停留时间，默认true
-    "ignoreRoutes": []                 // 需要忽略的路由列表
-  }
-}
-```
+## 快速开始
 
-**支持的console方法级别**：
-- `assert`, `clear`, `count`, `countReset`
-- `debug`, `dir`, `dirxml`, `error`
-- `group`, `groupCollapsed`, `groupEnd`, `info`
-- `log`, `table`, `time`, `timeEnd`, `timeLog`, `trace`, `warn`
+```typescript
+import { init } from '@antglobal/rlog-sdk';
 
-### 3. 使用方式
-```javascript
-// 初始化时传入 CDN 配置 URL
-Rlog.init({
+const rlog = init({
+  serv: 'https://your-server.com/api/rlog/record',
   appId: 'your-app-id',
-  serv: 'your-upload-server',
-  cdnConfigUrl: 'https://your-cdn.com/rlog-config.json'
+  cdnConfigUrl: 'https://your-cdn.com/rlog-config.json', // 可选，远程动态配置
 });
-```
 
-## 请求头注入功能
+// 停止录制
+rlog.cancel();
 
-### 1. 功能说明
-SDK 支持在所有 XMLHttpRequest 和 fetch 请求中自动注入全局自定义请求头，方便添加认证信息、跟踪标识等。
+// 停止录制并清除本地数据
+rlog.cancel({ clearData: true });
+```
 
-### 2. 使用方式
-```javascript
-// 设置全局自定义请求头
-Rlog.setCustomHeaders({
-  'Authorization': 'Bearer your-token',
-  'X-Request-Id': 'unique-request-id',
-  'X-Client-Version': '1.0.0'
-});
+## API
 
-// 设置白名单URL（只有这些URL的请求会被监控和注入请求头）
-Rlog.setWhiteListUrls([
-  'https://api.your-app.com',
-  'https://analytics.your-app.com'
-]);
-```
+### 核心
 
-### 3. 实现原理
-- 拦截 XMLHttpRequest 和 fetch API
-- 在发送请求前自动添加自定义请求头
-- 只对白名单中的 URL 注入请求头
-- 监控请求结果并记录成功/失败事件
-
-## 代码结构优化
-
-### 1. 入口文件精简
-入口文件 [`src/index.ts`](src/index.ts) 已经优化得更加精简，只包含必要的导入和导出：
-- 导入核心初始化函数
-- 导出初始化接口
-- 导出自定义事件接口
-
-### 2. 模块化设计
-项目现在采用更好的模块化设计，按功能域清晰划分：
-
-#### 核心模块
-- [`src/lib/init.ts`](src/lib/init.ts): 初始化逻辑，负责SDK的启动和配置
-- [`src/lib/config.ts`](src/lib/config.ts): 配置管理，支持CDN动态配置
-- [`src/lib/rrweb.ts`](src/lib/rrweb.ts): 录制功能，集成rrweb录制器
-
-#### 数据管理模块
-- [`src/lib/storage-manager.ts`](src/lib/storage-manager.ts): 存储管理，统一处理数据存储
-- [`src/lib/drive/`](src/lib/drive/): 存储驱动层
-  - [`indexeddb-adapt.ts`](src/lib/drive/indexeddb-adapt.ts): IndexedDB存储适配器
-  - [`localstorage-adapt.ts`](src/lib/drive/localstorage-adapt.ts): LocalStorage存储适配器
-  - [`memory-adapt.ts`](src/lib/drive/memory-adapt.ts): 内存存储适配器
-  - [`storage-interface.ts`](src/lib/drive/storage-interface.ts): 存储接口定义
-
-#### 网络通信模块
-- [`src/lib/uploader.ts`](src/lib/uploader.ts): 数据上传逻辑，包含重试机制
-- [`src/lib/request.ts`](src/lib/request.ts): 网络请求工具，封装HTTP请求
-- [`src/lib/net.ts`](src/lib/net.ts): 网络监控，拦截和记录网络请求
-
-#### 功能扩展模块
-- [`src/lib/router-monitor.ts`](src/lib/router-monitor.ts): 路由监控，跟踪页面路由变化
-- [`src/lib/api.ts`](src/lib/api.ts): API接口，提供外部调用接口
-- [`src/lib/utils.ts`](src/lib/utils.ts): 工具函数，通用工具方法
-- [`src/lib/error.ts`](src/lib/error.ts): 错误处理，统一的错误捕获和处理
-
-#### 架构特点
-- **分层架构**: 驱动层、服务层、接口层清晰分离
-- **插件化设计**: 各模块可独立启用/禁用
-- **高内聚低耦合**: 模块间通过明确定义的接口交互
-- **可扩展性**: 易于添加新的存储驱动或功能模块
-
-## 请求工具
-
-### 1. 工具说明
-项目中封装了兼容性更好的请求工具 [`src/lib/request.ts`](src/lib/request.ts)，提供以下功能：
-- 兼容性更好的 HTTP 请求（基于 XMLHttpRequest）
-- 支持 GET/POST 方法
-- 支持超时设置
-- 统一的错误处理
-
-### 2. 使用方式
-```typescript
-import { get, post, request } from './lib/request';
+| 方法 | 说明 |
+|------|------|
+| `init({ serv, appId, cdnConfigUrl? })` | 初始化 SDK，返回 `{ cancel }` |
+| `cancelRecord(options?)` | 停止录制（推荐使用 `rlog.cancel()`） |
+| `addCustomEvent(tag, payload)` | 添加自定义事件到录制流 |
+| `reportError(error)` | 手动上报错误（Error 对象或字符串） |
 
-// GET 请求
-const response = await get('https://api.example.com/data');
+### 网络配置
 
-// POST 请求
-const response = await post('https://api.example.com/data', { key: 'value' });
+| 方法 | 说明 |
+|------|------|
+| `setCustomHeaders(headers)` | 设置全局自定义请求头（注入到 XHR/Fetch） |
+| `getCustomHeaders()` | 获取当前自定义请求头 |
+| `setWhiteListUrls(urls)` | 设置白名单 URL（仅监控这些请求） |
+| `getWhiteListUrls()` | 获取白名单 |
+| `setBlackListUrls(urls)` | 设置黑名单 URL（排除这些请求） |
+| `getBlackListUrls()` | 获取黑名单 |
 
-// 自定义请求
-const response = await request('https://api.example.com/data', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ key: 'value' }),
-  timeout: 5000
-});
-```
+> 黑名单优先于白名单。白名单为空时监控所有非黑名单请求。
 
-## 性能优化方案
-
-### 1. Canvas录制动态采样
-**自适应采样算法**：
-```ts
-class SamplingController {
-  // 设备性能评估
-  static getSamplingRate(): number {
-    const isMobile = /Mobi/.test(navigator.userAgent);
-    const deviceMemory = (navigator as any).deviceMemory || 4;
-    
-    // 动态计算采样率：
-    // 1. 根据设备类型选择基准值
-    // 2. 根据内存大小动态调整（4GB基准，每增加1GB降低1帧）
-    // 3. 最低不低于5帧保证录制可用性
-    const baseRate = isMobile ? 8 : 15;
-    const memoryFactor = Math.max(0, 4 - (deviceMemory - 4));
-    
-    return Math.max(5, baseRate - memoryFactor);
-  }
-  
-  // 实时性能监控（每5秒检测一次）
-  static startPerformanceMonitor() {
-    setInterval(() => {
-      const fps = this.calculateFPS();
-      if (fps < 15) { // 低性能预警
-        this.throttleRecording();
-      } else if (fps > 25) { // 高性能提升
-        this.boostSampling();
-      }
-    }, 5000);
-  }
-}
+### 路由监控
 
-// 在rrweb初始化时应用
-rrweb.record({
-  sampling: {
-    canvas: SamplingController.getSamplingRate()
-  }
-});
-```
+| 方法 | 说明 |
+|------|------|
+| `updateRouterConfig(config)` | 更新路由监控配置 |
+| `getCurrentRouteInfo()` | 获取当前路由信息 |
+| `manualRouteChange(newRoute, prevRoute?)` | 手动触发路由变化事件 |
+| `stopRouterMonitor()` | 停止路由监控 |
 
-**性能指标**：
-| 指标 | 目标值 | 监控方式 |
-|------|-------|---------|
-| FPS | ≥15 | requestAnimationFrame |
-| 内存占用 | ≤15MB | performance.memory |
-| CPU使用率 | ≤30% | navigator.hardwareConcurrency |
-
-### 2. 存储性能优化
-**批量写入策略**：
-```ts
-// IndexedDBAdapter增强
-async push(deviceId: string, data: any): Promise<void> {
-  // 实现批量缓冲
-  if (!this.writeBuffer) {
-    this.writeBuffer = [];
-    // 500ms批量提交
-    setTimeout(() => this.flushBuffer(), 500);
-  }
-  this.writeBuffer.push({ deviceId, data });
-}
+### Consume-Only 模式
 
-private async flushBuffer(): Promise<void> {
-  if (!this.db || !this.writeBuffer) return;
-  
-  const transaction = this.db.transaction(STORE_NAME, 'readwrite');
-  const store = transaction.objectStore(STORE_NAME);
-  
-  // 使用游标批量更新
-  const cursor = await store.openCursor();
-  while (cursor) {
-    const updated = this.writeBuffer.find(
-      item => item.deviceId === cursor.key
-    );
-    if (updated) {
-      await cursor.update({
-        ...cursor.value,
-        data: [...cursor.value.data, ...updated.data]
-      });
-    }
-    await cursor.continue();
-  }
-  
-  this.writeBuffer = null;
-}
-```
+| 方法 | 说明 |
+|------|------|
+| `setConsumeOnlyMode(enable)` | 开启/关闭只采集不上报 |
+| `isConsumeOnlyMode()` | 查询当前是否为只采集模式 |
+| `toggleConsumeOnlyMode()` | 切换模式，返回新状态 |
 
-## 加密模块设计
-
-### 1. 加密架构设计
-```mermaid
-sequenceDiagram
-    participant SDK
-    participant Crypto
-    participant Storage
-    
-    SDK->>Crypto: setEncryptionKey() 设置密钥
-    SDK->>Crypto: encryptData() 请求加密
-    Crypto->>Crypto: 生成IV (12字节)
-    Crypto->>Crypto: 使用AES-GCM加密
-    Crypto-->>SDK: 返回Base64加密数据
-    SDK->>Storage: 存储加密数据
-```
+### 调试工具
 
-### 2. 加密实现细节
-```ts
-// 加密配置接口
-interface EncryptionConfig {
-  enabled: boolean;      // 加密开关
-  algorithm: 'AES-GCM' | 'AES-CBC'; // 算法选择
-  keyLength: 128 | 192 | 256; // 密钥长度
-  autoRotate: boolean;   // 密钥自动轮换
-  rotationInterval: number; // 轮换间隔（小时）
-}
+通过 `debug` 对象访问：
 
-// 加密服务实现
-class EncryptionService {
-  private key: CryptoKey | null = null;
-  private config: EncryptionConfig = {
-    enabled: false,
-    algorithm: 'AES-GCM',
-    keyLength: 256,
-    autoRotate: true,
-    rotationInterval: 24
-  };
-  
-  async setKey(key: CryptoKey): Promise<void> {
-    this.key = key;
-    if (this.config.autoRotate) {
-      this.scheduleKeyRotation();
-    }
-  }
-  
-  async encrypt(data: any): Promise<string> {
-    if (!this.config.enabled || !this.key) {
-      return JSON.stringify(data);
-    }
-    
-    const iv = crypto.getRandomValues(new Uint8Array(12));
-    const encoder = new TextEncoder();
-    const encrypted = await crypto.subtle.encrypt(
-      {
-        name: this.config.algorithm,
-        iv
-      },
-      this.key,
-      encoder.encode(JSON.stringify(data))
-    );
-    
-    // 返回包含元数据的加密数据
-    return JSON.stringify({
-      v: 1, // 版本号
-      alg: this.config.algorithm,
-      iv: arrayBufferToBase64(iv),
-      data: arrayBufferToBase64(encrypted)
-    });
-  }
-  
-  private scheduleKeyRotation(): void {
-    setInterval(async () => {
-      const newKey = await this.generateKey();
-      await this.rotateKey(newKey);
-    }, this.config.rotationInterval * 3600000);
-  }
-}
+```typescript
+import { debug } from '@antglobal/rlog-sdk';
+
+debug.getStorageAdapterType(); // 当前存储类型: 'indexeddb' | 'localstorage' | 'memory'
+debug.getDeviceId();           // 设备 ID
+debug.getSessionId();          // 当前 Tab 的 Session ID
+debug.getStorageKey();         // 存储键 (deviceId_sessionId)
+debug.resetUploadState();      // 重置上传状态
+debug.getStorageState();       // Promise<{ adapterType, eventCount }>
+debug.clearStorage();          // Promise<void> 清空存储
+debug.getConfig();             // 当前 CDN 配置
+debug.shouldRecordUrl(url);    // 判断 URL 是否会被网络监控记录
 ```
 
-### 3. 敏感数据脱敏
-```ts
-// 脱敏配置
-interface SanitizationRule {
-  selector: string;      // CSS选择器
-  type: 'mask' | 'hash' | 'remove'; // 脱敏类型
-  hashAlgorithm?: 'SHA-1' | 'SHA-256'; // 哈希算法
-  maskChar?: string;     // 掩码字符
-  maskLength?: number;   // 掩码长度
-}
+## CDN 动态配置
 
-// 脱敏处理器
-class DataSanitizer {
-  private rules: SanitizationRule[] = [
-    {
-      selector: 'input[type="password"]',
-      type: 'mask',
-      maskChar: '*',
-      maskLength: 8
-    },
-    {
-      selector: 'input[name="credit-card"]',
-      type: 'hash',
-      hashAlgorithm: 'SHA-256'
+通过 `cdnConfigUrl` 传入远程 JSON 配置，SDK 会定期拉取更新。完整配置项：
+
+```json
+{
+  "enable": false,
+  "uploadInterval": 2000,
+  "configUpdateInterval": 300000,
+  "captureMode": "full",
+  "packEvents": false,
+  "clearStorageBeforeRecord": true,
+  "http": false,
+  "maxRetryCount": 3,
+  "consumeOnly": false,
+  "urlParamsToCache": [],
+  "sampling": {
+    "canvas": 15,
+    "mousemove": 50,
+    "scroll": 100,
+    "input": "last"
+  },
+  "ignoreClass": "rr-ignore",
+  "blockClass": "rr-block",
+  "maskTextClass": "rr-mask",
+  "console": {
+    "enable": false,
+    "level": ["log", "warn", "error", "info"],
+    "lengthThreshold": 1000,
+    "stringifyOptions": {
+      "stringLengthLimit": 500,
+      "numOfKeysLimit": 50,
+      "depthOfLimit": 4
     }
-  ];
-  
-  sanitize(data: any): any {
-    const result = { ...data };
-    
-    // 遍历DOM节点应用脱敏规则
-    document.querySelectorAll('*').forEach(node => {
-      const element = node as HTMLElement;
-      this.rules.forEach(rule => {
-        if (element.matches(rule.selector)) {
-          switch (rule.type) {
-            case 'mask':
-              result.textContent = this.applyMask(
-                element.textContent || '',
-                rule.maskChar || '*',
-                rule.maskLength || 8
-              );
-              break;
-            case 'hash':
-              result.textContent = this.hashContent(
-                element.textContent || '',
-                rule.hashAlgorithm || 'SHA-256'
-              );
-              break;
-            case 'remove':
-              result.remove();
-              break;
-          }
-        }
-      });
-    });
-    
-    return result;
+  },
+  "routerMonitor": {
+    "enable": false,
+    "trackHashChange": true,
+    "trackHistoryChange": true,
+    "trackPageStayTime": true,
+    "ignoreRoutes": []
+  },
+  "errorCapture": {
+    "beforeDuration": 30000,
+    "afterDuration": 30000,
+    "httpErrorThreshold": 400
   }
 }
 ```
 
-## 网络配置API参考
-
-### 1. 配置方法
-
-#### setWhiteListUrls(urls: string[])
-设置白名单URL列表，只有这些接口会被记录和监控。
+### 配置说明
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `enable` | `false` | 采集总开关 |
+| `uploadInterval` | `2000` | 上传间隔（ms） |
+| `configUpdateInterval` | `300000` | 配置刷新间隔（ms） |
+| `captureMode` | `"full"` | `"full"` 全量录制 / `"error"` 错误触发录制 |
+| `packEvents` | `false` | 是否压缩事件数据 |
+| `clearStorageBeforeRecord` | `true` | 录制前是否清空存储 |
+| `http` | `false` | 是否开启网络请求监控 |
+| `maxRetryCount` | `3` | 上传失败最大重试次数 |
+| `consumeOnly` | `false` | 只采集不上报 |
+| `sampling.canvas` | `15` | Canvas 采样率（fps） |
+| `sampling.mousemove` | `50` | 鼠标移动采样间隔（ms） |
+| `sampling.scroll` | `100` | 滚动防抖间隔（ms） |
+| `sampling.input` | `"last"` | `"all"` 全部 / `"last"` 仅最终值 |
+| `errorCapture.beforeDuration` | `30000` | 错误前录制时长（ms） |
+| `errorCapture.afterDuration` | `30000` | 错误后继续录制时长（ms） |
+| `errorCapture.httpErrorThreshold` | `400` | HTTP 错误状态码阈值 |
+
+## 采集模式
+
+### Full 模式（默认）
+
+持续录制所有用户操作，按 `uploadInterval` 定时上传，每批最多 100 条事件。
+
+### Error 模式
+
+事件持续写入本地存储，仅在错误发生时触发上传。上传时间窗口为 `[now - beforeDuration, now + afterDuration]`。若 `afterDuration` 期间再次发生错误，窗口自动延长。
+
+## 架构
+
+```
+src/
+├── index.ts                    # 公共 API 导出
+└── lib/
+    ├── init.ts                 # SDK 初始化与销毁
+    ├── config.ts               # CDN 配置管理
+    ├── rrweb.ts                # rrweb 录制启动
+    ├── storage-manager.ts      # 存储管理（序列化队列）
+    ├── uploader.ts             # 上传调度（全量/错误模式）
+    ├── upload-worker-manager.ts # Web Worker 管理
+    ├── upload-worker.ts        # Worker 上传逻辑
+    ├── net.ts                  # 网络监控（XHR/Fetch 拦截）
+    ├── api.ts                  # 上传接口
+    ├── request.ts              # HTTP 请求工具
+    ├── router-monitor.ts       # 路由监控
+    ├── error.ts                # 错误捕获
+    ├── error-trigger.ts        # 错误模式状态机
+    ├── utils.ts                # 工具函数
+    ├── logger.ts               # 日志输出
+    ├── constants.ts            # 常量定义
+    └── drive/
+        ├── storage-interface.ts    # StorageAdapter 接口
+        ├── indexeddb-adapt.ts      # IndexedDB 适配器
+        ├── localstorage-adapt.ts   # LocalStorage 适配器（含分布式锁）
+        ├── memory-adapt.ts         # Memory 适配器
+        └── safe-storage.ts         # 安全 KV 存储（降级到内存）
+```
+
+## 多 Tab 并发
+
+- 每个标签页分配唯一 `sessionId`，存储键为 `deviceId_sessionId`
+- Session 注册表追踪活跃标签页
+- SDK 初始化时自动清理孤儿 session 的残留数据
+- LocalStorage 操作通过分布式锁（CAS + 超时）保证原子性
+
+## 上传重试
+
+上传失败时事件回退到队列头部，下个周期重试。连续失败达到 `maxRetryCount` 后：
+1. 派发 `rlog-upload-failure` 自定义事件（window + rrweb）
+2. 停止 rrweb 录制
+3. 停止上传循环
+
+监听失败事件：
 
-**参数：**
-- `urls`: string[] - URL列表，支持完整URL和相对路径
-
-**示例：**
 ```javascript
-Rlog.setWhiteListUrls([
-  'https://api.example.com',
-  '/api/v1/',  // 相对路径
-  '/ebank/api/v1/rlog/record'
-]);
+window.addEventListener('rlog-upload-failure', (e) => {
+  console.log('上传失败', e.detail);
+});
 ```
 
-#### setBlackListUrls(urls: string[])
-设置黑名单URL列表，这些接口将不会被记录和监控。
-
-**参数：**
-- `urls`: string[] - URL列表，支持完整URL和相对路径
+## 开发
 
-**示例：**
-```javascript
-Rlog.setBlackListUrls([
-  'https://api.sensitive.com/user-info',
-  '/api/auth/token',
-  '/ebank/api/v1/rlog/record'  // 避免循环上报
-]);
+```bash
+npm run dev    # 开发模式
+npm run build  # 构建（ESM + CJS）
 ```
 
-#### getWhiteListUrls(): string[]
-获取当前白名单URL列表。
-
-**返回值：**
-- string[] - 当前白名单URL列表
-
-#### getBlackListUrls(): string[]
-获取当前黑名单URL列表。
-
-**返回值：**
-- string[] - 当前黑名单URL列表
-
-### 2. 配置优先级
-网络接口的过滤优先级如下：
-1. **黑名单优先**：如果URL在黑名单中，无论是否在白名单都不会被记录
-2. **白名单过滤**：只有在白名单中的URL才会被记录（如果不在黑名单中）
-3. **默认行为**：如果白名单为空，则记录所有不在黑名单中的请求
-
-### 3. 路径匹配规则
-
-#### 完整URL匹配
-```javascript
-// 匹配以指定URL开头的请求
-'https://api.example.com/v1/users'  // 匹配 https://api.example.com/v1/users/123
-```
-
-#### 相对路径匹配
-```javascript
-// 匹配以指定路径开头的请求
-'/api/v1/'  // 匹配 /api/v1/users, /api/v1/data 等
-'/ebank/api/v1/rlog/record'  // 精确匹配该路径
-```
-
-#### 域名匹配
-```javascript
-// 匹配指定域名下的所有请求
-'api.example.com'  // 匹配该域名下的所有接口
-```
+## License
 
-## 相关文档和示例
-
-### 1. 路由监控功能
-- [详细使用指南](docs/ROUTER_MONITOR_GUIDE.md) - 包含完整的路由监控配置和使用示例
-- [在线示例](examples/test-router-monitor.html) - 可直接在浏览器中测试路由监控功能
-
-### 2. 上传重试机制
-- [重试逻辑指南](docs/RETRY_LOGIC_GUIDE.md) - 上传失败后的重试策略和配置
-- [重试测试示例](examples/test-retry-logic.html) - 测试上传重试功能
-
-### 3. 消费模式
-- [消费模式指南](docs/CONSUME_ONLY_MODE_GUIDE.md) - 仅消费数据的轻量级使用模式
-- [消费模式示例](examples/consume-only-mode.html) - 消费模式的实际应用示例
-
-### 4. 取消方法
-- [取消方法指南](docs/CANCEL_METHOD_GUIDE.md) - 如何正确停止录制和数据收集
-- [取消方法示例](examples/test-cancel.html) - 演示如何正确停止录制和数据收集
-
-## 改进建议实施状态
-| 改进项 | 实施状态 | 完成度 |
-|-------|----------|--------|
-| IndexedDB降级修复 | 已完成 | 100% |
-| 动态采样率调整 | 已完成 | 100% |
-| 路由监控功能 | 已完成 | 100% |
-| 错误处理优化 | 设计中 | 50% |
-| 上传重试机制 | 已完成 | 100% |
-| 消费模式支持 | 已完成 | 100% |
-| 取消方法支持 | 已完成 | 100% |
-| 移动端触控增强 | 未开始 | 0% |
-| 数据加密模块 | 设计完成 | 50% |
-| 数据压缩模块 | 未开始 | 0% |
+MIT