xuqmGroup/XuqmGroup-AndroidSDK

派生 0

XuqmGroup 9493a07b6b refactor(bugcollect): tighten public contract

2026-07-28 21:24:58 +08:00

5.6 KiB

原始文件 Blame 文件历史

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`	代码冻结（仅文档）
sample-app	—	演示 App

非当前范围模块（sdk-push/sdk-im）：除修复构建阻塞外不扩展功能。

核心 API（sdk-core）

初始化（唯一入口）

将租户平台签发的 config.xuqmconfig 原样放入 src/main/assets/config/config.xuqmconfig。集成任一需要初始化的扩展 SDK 后，合并 Provider 在 App 启动时自动触发；宿主不得手动传 appKey 初始化。

serverUrl 是配置签发时确定的唯一平台地址。运行时不存在默认平台地址，也不允许宿主覆盖、跨平台降级或维护第二套初始化配置。

用户信息

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 设备注册依赖 config.xuqmconfig 中的平台请求签名信息，与 userSig 无关。未配置时设备注册请求会被服务端拒绝，需在平台后台重新生成并下载配置文件。

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

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

Bug 采集 SDK（sdk-bugcollect）

// 平台配置自动初始化完成且宿主已取得隐私授权后：
BugCollect.setLogLevel(LogLevel.INFO)
BugCollect.setEnvironment("production")
// Crash 捕获由平台开关、构建门禁和隐私授权共同驱动，宿主不手动控制。

// 埋点
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 传入。

API 约束

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

发版配置

发布凭据只由 Jenkins Credentials 或开发者本机未入库的 Gradle 属性提供，禁止写入仓库。制品发布至 https://nexus.xuqinmin.com/repository/android-hosted/，模块版本由根目录 gradle.properties 的 SDK_*_VERSION 与 Jenkins 参数统一管理。

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

核心原则

开发阶段只允许发布 SNAPSHOT：所有 gradle.properties 中的 SDK_*_VERSION 必须以 -SNAPSHOT 结尾。
禁止手动修改版本号为正式版本：不得手动将 1.x.x-SNAPSHOT 改为 1.x.x（去掉 -SNAPSHOT）。
所有正式发版必须走 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 版本号

5.6 KiB 原始文件 Blame 文件历史 Unescape Escape