# BugCollect

`@xuqm/rn-bugcollect` 用于采集 JS 异常、原生崩溃、业务面包屑和自定义事件。它共享
Common 的自动配置与会话，不提供第二套初始化或登录入口。

## 安装

```bash
pnpm add @xuqm/rn-bugcollect @xuqm/rn-common
```

完成 [自动配置](./setup) 后无需在 App 入口调用 BugCollect 初始化方法。

## 隐私前置条件

只有宿主明确同步用户授权后才允许采集：

```ts
import { XuqmSDK } from '@xuqm/rn-common'

await XuqmSDK.setPrivacyConsent(true)
```

撤回授权：

```ts
await XuqmSDK.setPrivacyConsent(false)
```

SDK 不负责展示隐私声明，也不会把一次历史授权永久推断为当前授权。

## 自动采集

满足以下条件时，Release 应用自动启用异常采集：

- 租户平台已开启 BugCollect。
- 当前配置有效。
- 用户已同意隐私声明。
- App 构建没有使用应急关闭选项。

服务关闭、网络失败、限流或上传失败不会阻断宿主业务。服务端明确返回关闭状态后，SDK 会
停止后续采集，直到获取到新的有效平台配置。

## 手动记录

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

BugCollect.addBreadcrumb({
  type: 'navigation',
  category: 'order',
  message: '进入订单详情',
  data: { orderType: 'outpatient' },
})

BugCollect.info('开始提交订单')
BugCollect.warn('接口响应较慢', { elapsedMs: 2200 })

try {
  await submitOrder()
} catch (error) {
  BugCollect.captureError(error, {
    scene: 'submit-order',
  })
}
```

不要把密码、Token、身份证号、手机号、病历正文或完整请求响应放入 metadata。

## 自定义事件与漏斗

```ts
BugCollect.event('checkout_started', {
  source: 'cart',
})

BugCollect.defineFunnel({
  id: 'checkout',
  steps: ['checkout_started', 'payment_started', 'payment_completed'],
})

const progress = BugCollect.getFunnelProgress('checkout')
```

事件名应保持稳定，属性只记录分析所需的非敏感枚举和数值。

## 日志级别与环境

```ts
BugCollect.setLogLevel(__DEV__ ? 'debug' : 'warn')
BugCollect.setEnvironment(__DEV__ ? 'development' : 'production')
BugCollect.setSampleRate(0.2)
```

采样率只影响非致命事件，致命异常不参与客户端采样。线上采样与服务端限流共同生效，宿主
不需要自行实现重试队列。

## Debug 验证

Debug 默认不自动上传。开发者工具页可以在用户已同意隐私声明后显式执行：

```ts
await BugCollect.sendTestErrorAndFlush('BugCollect integration test')
```

该方法用于验证配置和上传链路，不应放在正常业务流程中。

## 主动刷新

```ts
await BugCollect.flush()
```

通常不需要主动调用。应用即将退出且确实需要等待当前队列时才使用；上传失败仍应当允许
宿主继续退出。

## 应急关闭

当 BugCollect 服务不可用且影响生产打包时，宿主可以通过自己的 Release 构建参数关闭本次
构建的 BugCollect。该设置只用于应急，不写入平台下发配置，也不允许业务页面在运行时
反向开启平台已关闭的服务。

## 数据与错误边界

- SDK 会对常见敏感字段进行脱敏，但调用方仍须避免主动传入敏感正文。
- 网络和上传错误不会抛到全局导致 App 崩溃。
- 未授权、服务关闭和配置不可用时，自定义记录调用安全跳过。
- `sendTestErrorAndFlush` 是诊断方法，会把错误明确返回给开发者页面。