# 平台概念

了解 XuqmGroup 平台的核心概念，有助于更好地接入 SDK。

---

## App / Tenant

| 概念 | 说明 |
|------|------|
| **Tenant（租户）** | 对应一个开发者账号/企业，可在控制台创建多个应用 |
| **App（应用）** | 对应一个具体的客户端应用，拥有独立的 `appKey` 和 `appSecret` |
| **appKey** | 应用唯一标识，客户端初始化时传入 |
| **appSecret** | 应用密钥，**仅保存在服务端**，用于签发 UserSig |

---

## UserSig

UserSig 是 XuqmGroup 的登录鉴权凭证，由业务服务端用 `appSecret` 为用户签发的安全凭证。

### 特点

- 客户端 IM 登录使用 `userId + UserSig`
- 服务端 SDK 可本地生成和校验 UserSig
- 当前版本支持过期时间，签发时可按业务控制有效期
- `appSecret` **绝不下发到客户端**
- 若需撤销权限，可在租户平台重置 `appSecret` 或拉黑账号
- 注册用户可标记为管理员；管理员账号可用于服务端 SDK / 管理端 REST API

### 签发方式（示例）

```ts
// Node.js 示例
import jwt from 'jsonwebtoken'

const userSig = jwt.sign(
  { userId: 'user_001', appKey: 'your_app_key', iat: Math.floor(Date.now() / 1000) },
  'your_app_secret',
  { algorithm: 'HS256', expiresIn: '180d' }
)
```

---

## 服务模块

XuqmGroup 平台由以下核心服务模块组成，各模块可独立按需接入：

| 模块 | 说明 |
|------|------|
| **IM** | 即时通讯：单聊、群聊、消息收发、会话管理、好友、群组 |
| **Push** | 消息推送：自动检测厂商通道（华为/小米/OPPO/vivo/荣耀/FCM），设备 Token 注册 |
| **Update** | 版本更新：App 更新检查、下载安装、商店跳转 |
| **BugCollect** | 异常采集：崩溃日志、ANR、异常上报，支持 Android / iOS / RN 多端统一采集 |
| **File** | 文件服务：文件上传、下载、消息附件管理 |

---

## 消息类型

| 类型 | 说明 | content 结构 |
|------|------|-------------|
| TEXT | 纯文本 | `String` |
| IMAGE | 图片 | `{url, width, height, thumbnailUrl?}` |
| VIDEO | 视频 | `{url, duration, thumbnailUrl, size}` |
| AUDIO | 语音 | `{url, duration, size}` |
| FILE | 文件 | `{url, name, size, mimeType}` |
| LOCATION | 位置 | `{lat, lng, address, title}` |
| CUSTOM | 自定义 | 任意 JSON |
| NOTIFY | 系统通知 | `{title, content}` |
| RICH_TEXT | 富文本 | `{html}` |
| CALL_AUDIO | 语音通话信令 | `{action}` |
| CALL_VIDEO | 视频通话信令 | `{action}` |
| QUOTE | 引用 | `{quotedMsgId, quotedContent, text}` |
| MERGE | 合并转发 | `{title, msgList}` |
| FORWARD | 转发 | `{originalSender, originalContent}` |
| REVOKED | 撤回 | 系统内部填充 |

---

## 会话

会话（Conversation）是用户与单聊对象或群组的聊天关系抽象。

| 属性 | 说明 |
|------|------|
| targetId | 对方用户 ID 或群 ID |
| chatType | `SINGLE` / `GROUP` |
| unreadCount | 未读消息数 |
| isPinned | 是否置顶 |
| isMuted | 是否免打扰 |
| lastMsgContent | 最后一条消息内容 |
| lastMsgTime | 最后一条消息时间（Unix 毫秒）|

---

## 群组

| 属性 | 说明 |
|------|------|
| id | 群唯一 ID |
| name | 群名称 |
| creatorId | 创建者用户 ID |
| memberIds | 成员列表（JSON 数组字符串）|
| adminIds | 管理员列表（JSON 数组字符串）|
| groupType | 群类型：`WORK` / `PUBLIC` / `PRIVATE` |
| announcement | 群公告 |

### 群角色

| 角色 | 说明 |
|------|------|
| OWNER | 群主 |
| ADMIN | 管理员 |
| MEMBER | 普通成员 |

---

## 消息状态

| 状态 | 说明 |
|------|------|
| SENDING | 发送中 |
| SENT | 已发送 |
| DELIVERED | 已送达 |
| READ | 已读 |
| FAILED | 发送失败 |
| REVOKED | 已撤回 |

[→ 接入流程 →](./flow)
