XuqmGroup-AndroidSDK/CLAUDE.md

# XuqmGroup-AndroidSDK — Claude 项目上下文

## 项目定位

XuqmGroup Android SDK，Gradle multi-module 项目。为集成宿主 App（如 YwxMobileApp）提供：初始化、用户认证、OTA 更新、WebView、IM、推送、证书、日志追踪。

- Git 远端：`https://xuqinmin.com/xuqmGroup/XuqmGroup-AndroidSDK.git`
- Nexus Maven 发布：`https://nexus.xuqinmin.com/repository/android-hosted/`
- groupId：`com.xuqm`
- 技术栈：Kotlin 2.3.10，AGP 9.1.0，minSdk 24，compileSdk 36，Java 21

## 模块结构

| 模块 | artifactId | 状态 |
|------|-----------|------|
| sdk-core | `sdk-core` | 活跃开发 |
| sdk-update | `sdk-update` | 活跃开发 |
| sdk-webview | `sdk-webview` | 活跃开发 |
| sdk-log | `sdk-log`（新） | 新建中 |
| sdk-push | `sdk-push` | 代码冻结（仅文档） |
| sdk-im | `sdk-im` | 代码冻结（仅文档） |
| sdk-license | `sdk-license` | 代码冻结（仅文档） |
| sample-app | — | 演示 App |

**代码冻结模块（sdk-push/sdk-im/sdk-license）：不修改代码，仅补充文档。**

## 核心 API（sdk-core）

### 初始化（两种方式，均不得修改签名）

**方式 A — ContentProvider 自动初始化（推荐）**  
将 `config.xuqm` 放入 `src/main/assets/xuqm/`，App 无需调用任何初始化代码。  
`XuqmInitializerProvider` 在 App 启动时自动触发。

**方式 B — 手动初始化**
```kotlin
// Application.onCreate() 中：
XuqmSDK.initialize(context, appKey = "xxx")                    // 公有平台
XuqmSDK.initialize(context, appKey = "xxx", platformUrl = "https://xxx")  // 私有化平台

// 等待平台配置（在 coroutine 中）：
XuqmSDK.awaitInitialization()
```

**两种平台互相独立，不允许自动降级到默认公有平台（`DEFAULT_PLATFORM_URL`）。**

### 用户信息
```kotlin
XuqmSDK.setUserInfo(XuqmUserInfo(
    userId = "u001",
    userSig = "sig",     // IM 登录凭证（可选）
    name = "张三",        // 可选
))
XuqmSDK.setUserInfo(null)  // 登出，触发所有子 SDK 登出
```

### 平台配置读取（init 完成后）
```kotlin
XuqmSDK.platformConfig?.logApiUrl   // 日志服务地址
XuqmSDK.logEnabled                  // 是否开启日志
XuqmSDK.appKey                      // 当前 appKey
```

## 日志 SDK（sdk-log）

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

// 埋点
XLog.event("page_view", mapOf("page" to "home"))

// 错误上报
XLog.captureError(exception)

// 漏斗定义
XLog.defineFunnel("checkout", listOf("cart_view", "checkout_start", "payment_done"))
```

`logApiUrl` 由 SDK 在 init 后从平台配置自动获取，无需 App 传入。

## 向下兼容约束

- `XuqmSDK.initialize()` 现有参数不得删除或修改类型
- `XuqmSDK.setUserInfo()` 现有 `XuqmUserInfo` 字段不得删除
- `SdkPlatformConfig` 新增字段一律为可选（`val xxx: Type? = null`）
- 旧服务端不返回新字段时，客户端使用合理默认值

## 集成验证项目

YwxMobileApp：`/Users/xuqinmin/Projects/TrustProjects/Pad/YwxMobileApp`  
使用 Nexus Maven 引入 SDK，开发阶段可改为 `project()` 本地引用。

## 常用命令

```bash
./gradlew :sdk-log:assembleDebug
./gradlew :sdk-core:assembleDebug
./gradlew :sample-app:installDebug
./gradlew publish   # 发布所有模块到 Nexus

# 发布单个模块
./gradlew :sdk-core:publish -PSDK_CORE_VERSION=1.0.0
```

## 发版配置

在 `gradle.properties` 中配置：
```properties
NEXUS_USER=your_username
NEXUS_PASSWORD=your_password
```

发布至 `https://nexus.xuqinmin.com/repository/android-hosted/`，版本号在各模块 `build.gradle.kts` 中维护。