qn-im-sdk/README.md

QnzsIM SDK

# QN IM SDK

一个支持多平台的即时通讯(IM) SDK，基于 WebSocket 实现，支持 Web、UniApp、微信小程序等平台。

## 功能特性

- 🚀 支持多平台：Web、UniApp、微信小程序
- 💬 完整的即时通讯功能
- 📎 支持多种消息类型：文本、图片、音频、视频、文件
- 🔒 内置敏感词过滤
- ⚡ 文件上传频率限制
- 🎯 基于 WebSocket 的实时通信

## 安装

```bash
npm install qn-im-sdk
```

## SDK 使用步骤

### 1. 引入 SDK

```bash
npm install qn-im-sdk
```

### 2. 实例化 SDK

```javascript
import { QnzsIMSDK } from 'qn-im-sdk';

const im = new QnzsIMSDK();

export default im;
```

### 3. 登录

```javascript
await im.login({
  userID: 'your-user-id',
  token: 'your-token',
  url: 'wss://your-websocket-url',
  platformID: 5,
  censorWordsUrl: 'http://your-censor-words' // 可选，远程敏感词地址
});
```

### 4. 发送消息

```javascript
await im.sendMessage({
  message: JSON.stringify({
    contentType: 101,
    content: 'Hello, World!'
  }),
  recvID: 'receiver-id',
  groupID: '',
  conversationType: 1
});
```

## 使用限制与安全

### 文件上传限制
为了保护服务器资源和防止滥用，SDK 实施了以下限制：
- 每个用户每分钟最多可上传 6 次文件
- 限制适用于所有类型的文件上传（图片、音频、视频、文件）
- 超过限制将收到错误码 `10001`

### 敏感词过滤
SDK 内置敏感词过滤功能，自动过滤不当内容：
- 适用于所有文本类消息
- 支持的消息类型：
  - 文本消息 (101)
  - @消息 (106)
  - 引用消息 (114)
  - 高级文本消息 (117)
- 包含敏感词的消息将被阻止发送
- 返回错误码 `10002` 提示用户
- 支持远程敏感词配置：通过 `censorWordsUrl` 参数动态加载敏感词列表

## 错误码说明

| 错误码 | 说明 | 详细描述 |
|--------|------|----------|
| 10001 | 上传超过时间限制次数 | 文件上传频率超过限制（每分钟最多6次） |
| 10002 | 该消息有敏感词被屏蔽 | 消息包含敏感词，发送被阻止 |

## 更新记录

### 版本 2.3.3 (2025-07-01)
**新增功能：**
- 支持远程敏感词配置
  - 通过 `censorWordsUrl` 参数指定远程敏感词获取地址
  - 登录时自动拉取最新敏感词列表
  - 支持多平台（Web、UniApp、微信小程序）
- 内置完整敏感词库（13997个敏感词）

### 版本 2.3.2 (2025-07-01)
**新增功能：**
1. **文件上传频率限制**
   - 限制每个用户每分钟最多上传 6 次文件
   - 适用于所有文件上传方法
   - 超过限制返回错误码 `10001`

2. **敏感词过滤功能**
   - 对文本类消息进行敏感词检测
   - 支持的消息类型：文本、@消息、引用、高级文本
   - 包含敏感词的消息将被阻止发送，返回错误码 `10002`

## API 文档

详细的 API 文档请参考 `IM_SDK使用文档.mdx`