From a53438a3f011621b470159b089f4a65d8192c5e9 Mon Sep 17 00:00:00 2001 From: XuqmGroup Date: Tue, 16 Jun 2026 17:18:35 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20rn-log=20=E2=86=92=20rn-bugcollect=20?= =?UTF-8?q?=E9=87=8D=E5=91=BD=E5=90=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude --- CLAUDE.md | 24 +++++++++--------- packages/log/README.md | 56 +++++++++++++++++++++--------------------- 2 files changed, 40 insertions(+), 40 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6d06c3d..664d214 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,7 +18,7 @@ XuqmGroup React Native SDK monorepo。为集成宿主 App（如 YiwangxinApp4） | `@xuqm/rn-im` | packages/im | 0.2.2 | IM 会话、消息（代码冻结，仅文档） | | `@xuqm/rn-xwebview` | packages/xwebview | 0.2.2 | WebView 容器 + JSBridge UI 组件 | | `@xuqm/rn-license` | packages/license | 0.3.0 | 证书授权（代码冻结，仅文档） | -| `@xuqm/rn-log` | packages/log | 0.1.0 | 日志、错误追踪、漏斗分析（新） | +| `@xuqm/rn-bugcollect` | packages/bugcollect | 0.1.0 | 日志、错误追踪、漏斗分析（新） | **代码冻结模块（push/im/license）：不修改代码，仅补充文档。** @@ -59,20 +59,20 @@ XuqmSDK.setUserInfo(null) // 登出，触发所有子 SDK 登出 子 SDK 自动订阅 `setUserInfo` 事件：Push 自动注册/解绑 token，IM 自动登录/断开，Update 更新 userId。 -## 日志 SDK（@xuqm/rn-log） +## 日志 SDK（@xuqm/rn-bugcollect） ```ts -import { XLog } from '@xuqm/rn-log' +import { BugCollect } from '@xuqm/rn-bugcollect' -XLog.setLogLevel('debug') -XLog.setEnvironment('production') -XLog.startCapture() // 开启全局错误捕获 -XLog.event('page_view', { page: 'home' }) -XLog.captureError(new Error('xxx')) -XLog.defineFunnel('checkout', ['cart_view', 'checkout_start', 'payment_done']) +BugCollect.setLogLevel('debug') +BugCollect.setEnvironment('production') +BugCollect.startCapture() // 开启全局错误捕获 +BugCollect.event('page_view', { page: 'home' }) +BugCollect.captureError(new Error('xxx')) +BugCollect.defineFunnel('checkout', ['cart_view', 'checkout_start', 'payment_done']) ``` -`logApiUrl` 由 SDK 在 init 后从 `/api/sdk/config` 自动获取，无需 App 传入。 +`bugCollectApiUrl` 由 SDK 在 init 后从 `/api/sdk/config` 自动获取，无需 App 传入。 ## 关键约束 @@ -80,7 +80,7 @@ XLog.defineFunnel('checkout', ['cart_view', 'checkout_start', 'payment_done']) - `XuqmSDK.setUserInfo()` 现有字段不得删除 - 新增字段一律为可选，有合理默认值 - 不允许静默降级（autoInit 失败时 `__DEV__` 模式 throw） -- rn-common 与 rn-log 解耦：rn-common 可独立使用；rn-log peerDep rn-common +- rn-common 与 rn-bugcollect 解耦：rn-common 可独立使用；rn-bugcollect peerDep rn-common ## XWebView JSBridge 标准 Handler @@ -90,7 +90,7 @@ XLog.defineFunnel('checkout', ['cart_view', 'checkout_start', 'payment_done']) ```bash yarn workspace @xuqm/rn-common typecheck -yarn workspace @xuqm/rn-log typecheck +yarn workspace @xuqm/rn-bugcollect typecheck yarn workspace @xuqm/rn-update typecheck yarn workspace @xuqm/rn-push typecheck yarn workspace @xuqm/rn-im typecheck diff --git a/packages/log/README.md b/packages/log/README.md index be68d59..b30cfd0 100644 --- a/packages/log/README.md +++ b/packages/log/README.md @@ -1,11 +1,11 @@ -# @xuqm/rn-log +# @xuqm/rn-bugcollect -XuqmGroup RN SDK 日志模块。提供日志采集、错误追踪、漏斗分析能力。 +XuqmGroup RN SDK 错误采集模块。提供日志采集、错误追踪、漏斗分析能力。 ## 安装 ```bash -yarn add @xuqm/rn-log +yarn add @xuqm/rn-bugcollect ``` Peer dependencies：`@xuqm/rn-common >= 0.4.0`，`@react-native-async-storage/async-storage >= 1.21.0`，`react-native >= 0.76` @@ -13,40 +13,40 @@ Peer dependencies：`@xuqm/rn-common >= 0.4.0`，`@react-native-async-storage/as ## 快速开始 ```ts -import { XLog } from '@xuqm/rn-log' +import { BugCollect } from '@xuqm/rn-bugcollect' // 1. 设置日志级别 -XLog.setLogLevel('debug') // 'debug' | 'info' | 'warn' | 'error' +BugCollect.setLogLevel('debug') // 'debug' | 'info' | 'warn' | 'error' // 2. 设置环境标签 -XLog.setEnvironment('production') // 'development' | 'staging' | 'production' +BugCollect.setEnvironment('production') // 'development' | 'staging' | 'production' // 3. 开启全局错误捕获（App 启动时调用一次） -XLog.startCapture() +BugCollect.startCapture() // 4. 记录自定义事件 -XLog.event('page_view', { page: 'home' }) +BugCollect.event('page_view', { page: 'home' }) // 5. 上报错误 -try { ... } catch (e) { XLog.captureError(e) } +try { ... } catch (e) { BugCollect.captureError(e) } ``` ## API -### XLog 对象 +### BugCollect 对象 | API | 说明 | |-----|------| -| `XLog.setLogLevel(level)` | 设置最低日志级别（低于此级别的事件被丢弃） | -| `XLog.setEnvironment(env)` | 设置环境标签（附加到每个事件） | -| `XLog.startCapture()` | 开启全局 JS 错误和未处理 Promise rejection 捕获 | -| `XLog.event(name, properties?)` | 记录自定义分析事件 | -| `XLog.captureError(error, metadata?)` | 上报 JS 异常 | -| `XLog.warn(message, metadata?)` | 记录警告（需级别允许） | -| `XLog.info(message, metadata?)` | 记录信息事件（需级别允许） | -| `XLog.defineFunnel(id, steps)` | 定义漏斗（按步骤顺序追踪转化） | -| `XLog.getFunnelProgress(funnelId)` | 获取客户端漏斗进度 | -| `XLog.flush()` | 立即刷新所有待发送事件（如 App 进后台前调用） | +| `BugCollect.setLogLevel(level)` | 设置最低日志级别（低于此级别的事件被丢弃） | +| `BugCollect.setEnvironment(env)` | 设置环境标签（附加到每个事件） | +| `BugCollect.startCapture()` | 开启全局 JS 错误和未处理 Promise rejection 捕获 | +| `BugCollect.event(name, properties?)` | 记录自定义分析事件 | +| `BugCollect.captureError(error, metadata?)` | 上报 JS 异常 | +| `BugCollect.warn(message, metadata?)` | 记录警告（需级别允许） | +| `BugCollect.info(message, metadata?)` | 记录信息事件（需级别允许） | +| `BugCollect.defineFunnel(id, steps)` | 定义漏斗（按步骤顺序追踪转化） | +| `BugCollect.getFunnelProgress(funnelId)` | 获取客户端漏斗进度 | +| `BugCollect.flush()` | 立即刷新所有待发送事件（如 App 进后台前调用） | ### 事件类型 @@ -62,28 +62,28 @@ try { ... } catch (e) { XLog.captureError(e) } ### 漏斗分析示例 ```ts -import { XLog } from '@xuqm/rn-log' +import { BugCollect } from '@xuqm/rn-bugcollect' // 定义漏斗 -XLog.defineFunnel('checkout', ['cart_view', 'checkout_start', 'payment_done']) +BugCollect.defineFunnel('checkout', ['cart_view', 'checkout_start', 'payment_done']) // 在业务代码中记录步骤事件（SDK 自动推进漏斗） -XLog.event('cart_view') -XLog.event('checkout_start') -XLog.event('payment_done') +BugCollect.event('cart_view') +BugCollect.event('checkout_start') +BugCollect.event('payment_done') // 查询进度 -const progress = XLog.getFunnelProgress('checkout') +const progress = BugCollect.getFunnelProgress('checkout') console.log(progress?.completedSteps) // ['cart_view', 'checkout_start', 'payment_done'] ``` ## 工作原理 -1. **LogQueue**：事件先进入内存队列，按批次异步上传到 `logApiUrl` +1. **LogQueue**：事件先进入内存队列，按批次异步上传到 `bugCollectApiUrl` 2. **ErrorCapture**：`startCapture()` 注册全局 `ErrorUtils` handler，自动捕获未处理异常 3. **Fingerprint**：为每个错误生成指纹（基于 message + stack），用于服务端去重聚合 4. **FunnelTracker**：客户端维护漏斗进度，服务端跨 session 聚合 ## 配置 -`logApiUrl` 和 `logEnabled` 由 `@xuqm/rn-common` 在 init 后从 `/api/sdk/config` 自动获取，无需 App 传入。 +`bugCollectApiUrl` 和 `bugCollectEnabled` 由 `@xuqm/rn-common` 在 init 后从 `/api/sdk/config` 自动获取，无需 App 传入。