XuqmGroup-AndroidSDK/docs/架构总览.md

# XuqmGroup Android SDK 架构总览

## 整体架构

```
宿主 App
  └── 放置租户平台签发的 assets/config/config.xuqmconfig
        ↓
  sdk-core（核心层；单独集成时零初始化、零权限、零 Provider）
    ├── XuqmMergedProvider 实现（仅由扩展 Manifest 注册）
    ├── 初始化状态：IDLE / INITIALIZING / READY / DEGRADED / FAILED
    ├── 七天加密 LKG（仅平台暂不可用时降级使用）
    ├── XuqmSDK.setUserInfo() → 通知所有子模块（反射 / 接口回调）
    ├── ApiClient（OkHttp 4.12 + Retrofit 3）
    ├── TokenStore（Android Keystore + AES-256-GCM）
    ├── FileSDK（上传 / 下载 / 打开文件）
    ├── ServiceEndpointRegistry（各服务地址注册表）
    └── bugCollectApiUrl / bugCollectEnabled（从平台配置获取）
        ↓ implementation dep
  子模块
    ├── sdk-update   → APK 更新 / 版本检查
    ├── sdk-push     → 厂商推送（FCM/HMS/VIVO/OPPO/Honor/APNs）
    ├── sdk-im       → IM（WebSocket/STOMP 实时通信）
    ├── sdk-webview  → WebView + JSBridge（Compose 组件）
    └── sdk-bugcollect → 日志 / Crash 捕获 / 漏斗分析（依赖 sdk-core）
```

## 依赖关系

```
sdk-core （核心，无 SDK 内部依赖）
  ↑ implementation dep
  ├── sdk-update   （依赖 sdk-core）
  ├── sdk-push     （依赖 sdk-core）
  ├── sdk-im       （依赖 sdk-core）
  ├── sdk-webview  （依赖 sdk-core）
  └── sdk-bugcollect（依赖 sdk-core）
```

## 用户状态分发

```
XuqmSDK.setUserInfo(info)
  ├── PushSDK:  检测厂商 → 注册 token → 上报服务端
  ├── ImSDK:    若 userSig 存在且 imEnabled → 自动登录 WebSocket
  └── UpdateSDK: 更新 userId

XuqmSDK.setUserInfo(null)
  ├── PushSDK:  解绑 token
  ├── ImSDK:    断开 WebSocket
  └── 其他子模块: 清理用户状态
```

## 初始化流程

```
App 启动
  ↓
任一扩展合并的唯一 XuqmMergedProvider.onCreate()
  ↓ 主线程仅读取 assets/config/config.xuqmconfig
IO 线程验证 Ed25519 签名 → 解密 canonical JSON → 校验包身份
  ↓ HTTP GET
/api/sdk/config → 返回 { apiUrl, imWsUrl, fileServiceUrl, ... }
  ↓
成功：READY 并原子保存 LKG
失败且七天 LKG 有效：DEGRADED
失败且无有效 LKG：FAILED；扩展停用，宿主核心业务继续
```

## 技术栈

| 组件 | 版本 |
|------|------|
| Kotlin | 2.3.10 |
| AGP | 9.1.0 |
| minSdk | 24 |
| compileSdk | 36 |
| Java | 21 |
| OkHttp | 4.12.x（与 React Native 宿主二进制兼容） |
| Retrofit | 3.x |
| Coroutines | 1.x |

## 发布

发布到 Nexus Maven：`https://nexus.xuqinmin.com/repository/android-hosted/`  
groupId：`com.xuqm`

```bash
# 发布所有模块
./gradlew publish

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