XuqmGroup-AndroidSDK/sdk-log/README.md

# sdk-bugcollect

XuqmGroup Android SDK Bug 采集模块。提供错误采集、Crash 捕获、漏斗分析能力。

## 依赖

```kotlin
implementation("com.xuqm:sdk-bugcollect:VERSION")
implementation("com.xuqm:sdk-core:VERSION")  // 必须
```

## 快速开始

```kotlin
// Application.onCreate() 中（XuqmSDK.initialize 之后）：
BugCollect.setLogLevel(LogLevel.INFO)
BugCollect.setEnvironment("production")
BugCollect.startCrashCapture()

// 业务代码中
BugCollect.event("page_view", mapOf("page" to "home"))
BugCollect.captureError(exception)
```

## API

### BugCollect 对象

| API | 说明 |
|-----|------|
| `BugCollect.setLogLevel(level)` | 设置日志级别（`DEBUG` / `INFO` / `WARN` / `ERROR`） |
| `BugCollect.setEnvironment(env)` | 设置环境标签 |
| `BugCollect.startCrashCapture()` | 开启全局 UncaughtExceptionHandler |
| `BugCollect.event(name, properties?)` | 记录自定义事件 |
| `BugCollect.captureError(error, metadata?)` | 上报异常 |
| `BugCollect.warn(message, metadata?)` | 记录警告 |
| `BugCollect.info(message, metadata?)` | 记录信息 |
| `BugCollect.defineFunnel(id, steps)` | 定义漏斗 |

### LogLevel

```kotlin
enum class LogLevel { DEBUG, INFO, WARN, ERROR, NONE }
```

### 工作原理

- **LogQueue**：事件进入内存队列，按批次异步上传到 `bugCollectApiUrl`
- **CrashCapture**：注册 `Thread.UncaughtExceptionHandler`，捕获 Native Crash 并写入文件，下次启动时上传
- **Fingerprint**：为错误生成指纹（基于 message + stack），服务端去重聚合
- **FunnelTracker**：客户端维护漏斗进度，服务端跨 session 聚合

### 配置

`bugCollectApiUrl` 和 `bugCollectEnabled` 由 `sdk-core` 在 init 后从平台配置自动获取，无需 App 传入。