XuqmGroup-RNSDK/packages/log/README.md

# @xuqm/rn-bugcollect

XuqmGroup RN SDK 错误采集模块。提供日志采集、错误追踪、漏斗分析能力。

## 安装

```bash
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`

## 快速开始

```ts
import { BugCollect } from '@xuqm/rn-bugcollect'

// 1. 设置日志级别
BugCollect.setLogLevel('debug')  // 'debug' | 'info' | 'warn' | 'error'

// 2. 设置环境标签
BugCollect.setEnvironment('production')  // 'development' | 'staging' | 'production'

// 3. 开启全局错误捕获（App 启动时调用一次）
BugCollect.startCapture()

// 4. 记录自定义事件
BugCollect.event('page_view', { page: 'home' })

// 5. 上报错误
try { ... } catch (e) { BugCollect.captureError(e) }
```

## API

### BugCollect 对象

| API | 说明 |
|-----|------|
| `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 进后台前调用） |

### 事件类型

| 类型 | 说明 |
|------|------|
| `LogEvent` | 自定义事件（`type: 'event'`） |
| `IssueEvent` | 错误事件（`type: 'js_error'` / `'native_crash'` / `'api_error'` / `'warning'`） |

### 日志级别

`'debug'` (0) < `'info'` (1) < `'warn'` (2) < `'error'` (3)

### 漏斗分析示例

```ts
import { BugCollect } from '@xuqm/rn-bugcollect'

// 定义漏斗
BugCollect.defineFunnel('checkout', ['cart_view', 'checkout_start', 'payment_done'])

// 在业务代码中记录步骤事件（SDK 自动推进漏斗）
BugCollect.event('cart_view')
BugCollect.event('checkout_start')
BugCollect.event('payment_done')

// 查询进度
const progress = BugCollect.getFunnelProgress('checkout')
console.log(progress?.completedSteps) // ['cart_view', 'checkout_start', 'payment_done']
```

## 工作原理

1. **LogQueue**：事件先进入内存队列，按批次异步上传到 `bugCollectApiUrl`
2. **ErrorCapture**：`startCapture()` 注册全局 `ErrorUtils` handler，自动捕获未处理异常
3. **Fingerprint**：为每个错误生成指纹（基于 message + stack），用于服务端去重聚合
4. **FunnelTracker**：客户端维护漏斗进度，服务端跨 session 聚合

## 配置

`bugCollectApiUrl` 和 `bugCollectEnabled` 由 `@xuqm/rn-common` 在 init 后从 `/api/sdk/config` 自动获取，无需 App 传入。