# 平台概念

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

---

## App / Tenant

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

---

## UserSig

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

### 特点

- 当前版本不过期，只校验 `userId + UserSig` 是否匹配
- `appSecret` **绝不下发到客户端**
- 若需撤销权限，可在租户平台重置 `appSecret` 或拉黑账号

### 签发方式（示例）

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

const userSig = jwt.sign(
  { userId: 'user_001', appKey: 'your_app_key' },
  'your_app_secret',
  { algorithm: 'HS256' }
)
```

---

## 消息类型

| 类型 | 说明 | 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)