# 二维码扫码功能使用说明

## 功能特点

- ✅ 使用华为 Customized View Mode 实现精美的自定义扫码界面
- ✅ 全屏沉浸式体验
- ✅ 流畅的扫描线动画
- ✅ **超简洁的 API，业务层只需一行代码**
- ✅ **内部自动处理 Activity Result，无需手动处理 onActivityResult**
- ✅ 单例模式，统一管理

## 快速开始

### 调用方式（与BLE模块完全一致）

```kotlin
import com.narutohuo.xindazhou.qrcode.factory.QRCodeManagerFactory
import com.narutohuo.xindazhou.qrcode.api.QRCodeManager

val qrCodeManager: QRCodeManager = QRCodeManagerFactory.getInstance()
qrCodeManager.scanQRCode(this) { response ->
    if (response.success) {
        // 扫码成功
        val qrCodeContent = response.data
    } else {
        // 扫码失败或取消
        val error = response.errorMessage
    }
}
```

### 完整示例

```kotlin
import com.narutohuo.xindazhou.qrcode.factory.QRCodeManagerFactory
import com.narutohuo.xindazhou.qrcode.api.QRCodeManager
import com.narutohuo.xindazhou.qrcode.model.QRCodeResponse

class MainActivity : AppCompatActivity() {
    
    private val qrCodeManager: QRCodeManager = QRCodeManagerFactory.getInstance()
    
    fun startScan() {
        qrCodeManager.scanQRCode(this) { response ->
            handleScanResult(response)
        }
    }
    
    private fun handleScanResult(response: QRCodeResponse) {
        if (response.success) {
            val content = response.data
            // 处理扫码结果
            processQRCode(content)
        } else {
            // 处理错误
            showError(response.errorMessage)
        }
    }
    
    private fun processQRCode(content: String?) {
        // 业务逻辑处理
    }
    
    private fun showError(message: String?) {
        // 显示错误
    }
}
```

**注意**：✅ 不需要实现 `onActivityResult`！内部已经自动处理了

## API 说明

### QRCodeManager 接口

```kotlin
interface QRCodeManager {
    /**
     * 扫描二维码
     * 
     * @param activity Activity上下文（必须是 FragmentActivity 或 AppCompatActivity）
     * @param callback 扫描结果回调，返回QRCodeResponse
     */
    fun scanQRCode(activity: Activity, callback: (QRCodeResponse) -> Unit)
}
```

### QRCodeResponse 响应模型

```kotlin
data class QRCodeResponse(
    val success: Boolean,           // 是否成功
    val data: String? = null,       // 二维码内容
    val errorCode: Int? = null,     // 错误码
    val errorMessage: String? = null, // 错误消息
    val timestamp: Long = System.currentTimeMillis() // 时间戳
)
```

## 注意事项

1. **Activity 类型**：必须使用 `AppCompatActivity` 或 `FragmentActivity`（内部使用 Fragment 桥接 ActivityResultLauncher）
2. **相机权限**：确保在 AndroidManifest.xml 中声明了相机权限，运行时会自动请求
3. **单例模式**：使用 Factory 获取的实例是单例，多个界面可以共享
4. **无需处理 onActivityResult**：内部已经自动处理，业务层完全不需要关心

## 界面效果

- 全屏沉浸式扫码界面
- 居中显示扫码框（280dp × 280dp）
- 四个角的装饰线条（青色 #00E5FF）
- 流畅的扫描线动画
- 半透明遮罩突出扫码区域
- 顶部返回按钮
- 底部提示文字

## 依赖说明

- 华为 HMS Scan Kit: `2.12.0.300`
- AndroidX AppCompat: `1.6.1`
- AndroidX Fragment: `1.6.2`
- AndroidX Activity: `1.8.2`
- 最低 SDK 版本: 26

## 与其他模块对比

### BLE 模块调用方式
```kotlin
import com.narutohuo.xindazhou.ble.factory.BLEServiceFactory
import com.narutohuo.xindazhou.ble.api.BLEService

val bleService: BLEService = BLEServiceFactory.create(context)
bleService.connect(device) { response ->
    // 处理结果
}
```

### 二维码模块调用方式（完全一致！）
```kotlin
import com.narutohuo.xindazhou.qrcode.factory.QRCodeManagerFactory
import com.narutohuo.xindazhou.qrcode.api.QRCodeManager

val qrCodeManager: QRCodeManager = QRCodeManagerFactory.getInstance()
qrCodeManager.scanQRCode(this) { response ->
    // 处理结果
}
```

**与BLE模块完全一致的调用方式！** 🎉