XuqmGroup-AndroidSDK/CLAUDE.md

XuqmGroup-AndroidSDK — Claude 项目上下文

项目定位

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

• 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-bugcollect	sdk-bugcollect（新）	新建中
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 — 手动初始化

// Application.onCreate() 中：
XuqmSDK.initialize(context, appKey = "xxx")                    // 公有平台
XuqmSDK.initialize(context, appKey = "xxx", platformUrl = "https://xxx")  // 私有化平台

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

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

用户信息

XuqmSDK.setUserInfo(XuqmUserInfo(
    userId = "u001",
    userSig = "sig",     // IM 登录凭证（仅 IM 强制，其它 SDK 均可不传）
    name = "张三",        // 可选
))
XuqmSDK.setUserInfo(null)  // 登出，触发所有子 SDK 登出

userSig 设计规则（必须遵守）：

SDK	userSig 要求
sdk-im	强制 — 没有 userSig 不能登录 IM
sdk-push	可选 — 只有 userId 也可完成 push 设备注册
sdk-update	可选 — 只有 userId 即可使用
sdk-bugcollect	可选 — 只有 userId 即可使用
sdk-webview	可选 — 只有 userId 即可使用

• 外部用户（无 userSig）：只需 userId，可使用除 IM 外的所有 SDK 功能
• 平台托管用户（有 userSig）：完整功能，包含 IM
• 禁止在 push / update / bugcollect 等 SDK 内部校验 userSig 是否存在

注意： push 设备注册依赖请求签名（signingKey in config.xuqm），与 userSig 无关。signingKey 未配置时，设备注册请求会被服务端拒绝（HTTP 401）。需在平台后台为该 appKey 生成 signingKey 并重新下载 config.xuqm。

平台配置读取（init 完成后）

XuqmSDK.platformConfig?.bugCollectApiUrl   // Bug 采集服务地址
XuqmSDK.bugCollectEnabled                  // 是否开启 Bug 采集
XuqmSDK.appKey                      // 当前 appKey

Bug 采集 SDK（sdk-bugcollect）

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

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

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

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

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

向下兼容约束

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

集成验证项目

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

常用命令

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

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

发版配置

在 gradle.properties 中配置：

NEXUS_USER=your_username
NEXUS_PASSWORD=your_password

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

版本号与发布规则（严禁违反）

核心原则

1. 开发阶段只允许发布 SNAPSHOT：所有 gradle.properties 中的 SDK_*_VERSION 必须以 -SNAPSHOT 结尾。
2. 禁止手动修改版本号为正式版本：不得手动将 1.x.x-SNAPSHOT 改为 1.x.x（去掉 -SNAPSHOT）。
3. 所有正式发版必须走 Jenkins：Jenkins 自动完成版本号提升、去掉 -SNAPSHOT、发布到 Nexus、打 Git tag 等操作。

违禁示例

# ❌ 禁止在代码中手动修改为正式版本
SDK_PUSH_VERSION=1.1.4       # 错误：手动去掉了 -SNAPSHOT
SDK_CORE_VERSION=1.1.6       # 错误

# ✅ 正确：开发阶段保持 SNAPSHOT
SDK_PUSH_VERSION=1.1.4-SNAPSHOT
SDK_CORE_VERSION=1.1.6-SNAPSHOT

允许的手动操作

• 新功能开发需要升版本号时：可以将 1.x.x-SNAPSHOT 改为 1.x+1.0-SNAPSHOT（只提升次版本，保留 -SNAPSHOT）
• 发布 SNAPSHOT 到 Nexus 用于集成测试：./gradlew :sdk-xxx:publish

Jenkins 负责的操作（禁止手动代替）

• 去掉 -SNAPSHOT 发布正式版
• 打 Git release tag
• 更新下一个开发周期的 SNAPSHOT 版本号