# Telegram 管理系统 API 接口文档 > **版本**: v2.0.0 > **更新时间**: 2024-01-20 > **基础URL**: `https://api.telegram-system.com/v1` > **维护者**: 开发团队 ## 📋 文档目录 - [接口概述](#接口概述) - [认证机制](#认证机制) - [通用规范](#通用规范) - [错误处理](#错误处理) - [用户认证](#用户认证) - [账号管理](#账号管理) - [私信群发](#私信群发) - [营销中心](#营销中心) - [权限管理](#权限管理) - [系统配置](#系统配置) - [文件管理](#文件管理) - [实时通信](#实时通信) --- ## 🔍 接口概述 ### API特性 - **RESTful风格**: 遵循REST架构设计原则 - **JSON格式**: 所有请求和响应均使用JSON格式 - **统一认证**: 基于JWT的Token认证机制 - **版本控制**: URL路径包含版本号，支持向后兼容 - **限流保护**: 每个用户每分钟最多100次请求 - **HTTPS加密**: 生产环境强制使用HTTPS协议 ### 支持的HTTP方法 | 方法 | 说明 | 示例 | | ------ | ------------ | -------------------------- | | GET | 获取资源 | `GET /api/v1/users` | | POST | 创建资源 | `POST /api/v1/users` | | PUT | 更新整个资源 | `PUT /api/v1/users/123` | | PATCH | 部分更新资源 | `PATCH /api/v1/users/123` | | DELETE | 删除资源 | `DELETE /api/v1/users/123` | ### 环境地址 | 环境 | 地址 | 说明 | | -------- | ----------------------------------------- | -------- | | 开发环境 | `http://localhost:3001/api/v1` | 本地开发 | | 测试环境 | `https://test-api.telegram-system.com/v1` | 测试验证 | | 生产环境 | `https://api.telegram-system.com/v1` | 正式环境 | --- ## 🔐 认证机制 ### JWT Token认证 所有需要认证的接口必须在请求头中携带Token： ```http Authorization: Bearer ``` ### Token获取流程 ```mermaid sequenceDiagram participant C as Client participant A as API Server participant D as Database C->>A: POST /auth/login (username, password) A->>D: 验证用户凭据 D-->>A: 返回用户信息 A->>A: 生成JWT Token A-->>C: 返回Token和用户信息 Note over C: 后续请求携带Token C->>A: GET /users (Header: Authorization) A->>A: 验证Token有效性 A-->>C: 返回数据 ``` ### Token结构 JWT Token包含以下信息： ```json { "header": { "alg": "HS256", "typ": "JWT" }, "payload": { "userId": "user123", "username": "admin", "roles": ["admin", "user"], "permissions": ["user:read", "user:write"], "iat": 1642780800, "exp": 1642867200 } } ``` --- ## 📝 通用规范 ### 请求格式 #### Content-Type 所有POST、PUT、PATCH请求必须设置正确的Content-Type： ```http Content-Type: application/json ``` #### 分页参数 支持分页的接口使用统一的分页参数： ```json { "page": 1, // 页码，从1开始 "pageSize": 20, // 每页数量，默认20，最大100 "sortBy": "createdAt", // 排序字段 "sortOrder": "desc" // 排序方向：asc/desc } ``` #### 筛选参数 支持筛选的接口使用统一的筛选格式： ```json { "filters": { "status": "active", // 精确匹配 "name": { "$like": "admin" }, // 模糊匹配 "createdAt": { // 范围查询 "$gte": "2024-01-01", "$lte": "2024-12-31" } } } ``` ### 响应格式 #### 成功响应 ```json { "success": true, "code": 200, "message": "操作成功", "data": { // 具体数据 }, "timestamp": "2024-01-20T10:30:00Z" } ``` #### 分页响应 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "items": [...], "pagination": { "page": 1, "pageSize": 20, "total": 100, "totalPages": 5 } }, "timestamp": "2024-01-20T10:30:00Z" } ``` --- ## ❌ 错误处理 ### 错误响应格式 ```json { "success": false, "code": 400, "message": "请求参数错误", "error": { "type": "ValidationError", "details": [ { "field": "email", "message": "邮箱格式不正确" } ] }, "timestamp": "2024-01-20T10:30:00Z", "requestId": "req-123456789" } ``` ### HTTP状态码 | 状态码 | 说明 | 示例场景 | | ------ | -------------- | ---------------- | | 200 | 操作成功 | 数据获取成功 | | 201 | 创建成功 | 用户创建成功 | | 400 | 请求参数错误 | 参数格式不正确 | | 401 | 未认证 | Token无效或过期 | | 403 | 权限不足 | 没有访问权限 | | 404 | 资源不存在 | 用户不存在 | | 409 | 资源冲突 | 用户名已存在 | | 422 | 数据验证失败 | 业务规则验证失败 | | 429 | 请求过于频繁 | 超出限流阈值 | | 500 | 内部服务器错误 | 系统异常 | ### 错误类型 | 错误类型 | 说明 | 示例 | | ------------------- | ------------ | -------------- | | ValidationError | 数据验证错误 | 邮箱格式不正确 | | AuthenticationError | 认证错误 | Token无效 | | AuthorizationError | 授权错误 | 权限不足 | | NotFoundError | 资源不存在 | 用户不存在 | | ConflictError | 资源冲突 | 用户名重复 | | BusinessError | 业务逻辑错误 | 余额不足 | | SystemError | 系统错误 | 数据库连接失败 | --- ## 👤 用户认证 ### 用户登录 #### 接口信息 - **URL**: `/auth/login` - **方法**: `POST` - **认证**: 无需认证 #### 请求参数 ```json { "username": "admin", // 用户名，必填 "password": "123456", // 密码，必填 "rememberMe": true, // 记住我，可选，默认false "captcha": "ABCD", // 验证码，可选 "captchaId": "cap123" // 验证码ID，可选 } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "登录成功", "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refreshToken": "refresh-token-here", "expiresIn": 7200, "user": { "id": "user123", "username": "admin", "email": "admin@example.com", "profile": { "firstName": "管理员", "lastName": "", "avatar": "https://example.com/avatar.jpg" }, "roles": ["admin"], "permissions": ["*"], "lastLogin": "2024-01-20T10:30:00Z" } } } ``` #### 错误示例 ```json { "success": false, "code": 401, "message": "用户名或密码错误", "error": { "type": "AuthenticationError", "details": [] } } ``` ### 用户登出 #### 接口信息 - **URL**: `/auth/logout` - **方法**: `POST` - **认证**: 需要Token #### 请求参数 ```json { "refreshToken": "refresh-token-here" // 可选，提供则同时注销refresh token } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "登出成功" } ``` ### 刷新Token #### 接口信息 - **URL**: `/auth/refresh` - **方法**: `POST` - **认证**: 需要Refresh Token #### 请求参数 ```json { "refreshToken": "your-refresh-token" } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "Token刷新成功", "data": { "token": "new-jwt-token", "refreshToken": "new-refresh-token", "expiresIn": 7200 } } ``` ### 获取当前用户信息 #### 接口信息 - **URL**: `/auth/me` - **方法**: `GET` - **认证**: 需要Token #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "id": "user123", "username": "admin", "email": "admin@example.com", "profile": { "firstName": "管理员", "lastName": "", "avatar": "https://example.com/avatar.jpg", "phone": "13800138000" }, "roles": ["admin"], "permissions": ["*"], "settings": { "language": "zh-CN", "timezone": "Asia/Shanghai", "theme": "light" }, "status": "active", "lastLogin": "2024-01-20T10:30:00Z", "createdAt": "2024-01-01T00:00:00Z" } } ``` --- ## 📋 账号管理 ### 获取Telegram账号列表 #### 接口信息 - **URL**: `/telegram-accounts` - **方法**: `GET` - **认证**: 需要Token - **权限**: `telegram-account:read` #### 请求参数 ```json { "page": 1, "pageSize": 20, "sortBy": "createdAt", "sortOrder": "desc", "filters": { "status": "active", // 状态筛选 "username": { "$like": "test" }, // 用户名模糊搜索 "phone": { "$like": "138" }, // 手机号模糊搜索 "createdAt": { // 创建时间范围 "$gte": "2024-01-01", "$lte": "2024-12-31" } } } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "items": [ { "id": "acc123", "telegramId": "123456789", "username": "testuser", "firstName": "Test", "lastName": "User", "phone": "13800138000", "status": "active", "isVerified": true, "isPremium": false, "languageCode": "zh-CN", "metadata": { "joinDate": "2024-01-01", "lastSeen": "2024-01-20T10:30:00Z", "messageCount": 150 }, "managedBy": "user123", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-20T10:30:00Z" } ], "pagination": { "page": 1, "pageSize": 20, "total": 100, "totalPages": 5 } } } ``` ### 创建Telegram账号 #### 接口信息 - **URL**: `/telegram-accounts` - **方法**: `POST` - **认证**: 需要Token - **权限**: `telegram-account:create` #### 请求参数 ```json { "telegramId": "123456789", // Telegram ID，必填 "username": "testuser", // 用户名，可选 "firstName": "Test", // 名字，必填 "lastName": "User", // 姓氏，可选 "phone": "13800138000", // 手机号，可选 "languageCode": "zh-CN", // 语言代码，可选 "metadata": { // 元数据，可选 "bio": "用户简介", "location": "北京" } } ``` #### 响应数据 ```json { "success": true, "code": 201, "message": "创建成功", "data": { "id": "acc123", "telegramId": "123456789", "username": "testuser", "firstName": "Test", "lastName": "User", "phone": "13800138000", "status": "active", "managedBy": "user123", "createdAt": "2024-01-20T10:30:00Z" } } ``` ### 获取账号详情 #### 接口信息 - **URL**: `/telegram-accounts/{id}` - **方法**: `GET` - **认证**: 需要Token - **权限**: `telegram-account:read` #### URL参数 | 参数 | 类型 | 说明 | | ---- | ------ | ------ | | id | String | 账号ID | #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "id": "acc123", "telegramId": "123456789", "username": "testuser", "firstName": "Test", "lastName": "User", "phone": "13800138000", "status": "active", "isVerified": true, "isPremium": false, "languageCode": "zh-CN", "bio": "用户简介", "profilePhoto": "https://example.com/photo.jpg", "metadata": { "joinDate": "2024-01-01", "lastSeen": "2024-01-20T10:30:00Z", "messageCount": 150, "groupCount": 25, "contactCount": 100 }, "statistics": { "sentMessages": 50, "receivedMessages": 100, "joinedGroups": 25, "successRate": 95.5 }, "managedBy": "user123", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-20T10:30:00Z" } } ``` ### 更新账号信息 #### 接口信息 - **URL**: `/telegram-accounts/{id}` - **方法**: `PUT` - **认证**: 需要Token - **权限**: `telegram-account:update` #### 请求参数 ```json { "username": "newusername", // 用户名，可选 "firstName": "NewName", // 名字，可选 "lastName": "NewLastName", // 姓氏，可选 "phone": "13900139000", // 手机号，可选 "status": "active", // 状态，可选 "metadata": { // 元数据，可选 "bio": "新的用户简介", "location": "上海" } } ``` ### 删除账号 #### 接口信息 - **URL**: `/telegram-accounts/{id}` - **方法**: `DELETE` - **认证**: 需要Token - **权限**: `telegram-account:delete` #### 响应数据 ```json { "success": true, "code": 200, "message": "删除成功" } ``` ### 批量操作账号 #### 接口信息 - **URL**: `/telegram-accounts/batch` - **方法**: `POST` - **认证**: 需要Token - **权限**: `telegram-account:batch` #### 请求参数 ```json { "action": "update_status", // 操作类型：update_status, delete, export "accountIds": ["acc1", "acc2"], // 账号ID列表 "data": { // 操作数据（根据action不同而不同） "status": "inactive" } } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "批量操作成功", "data": { "total": 2, "success": 2, "failed": 0, "errors": [] } } ``` --- ## 📨 私信群发 ### 获取消息模板列表 #### 接口信息 - **URL**: `/message-templates` - **方法**: `GET` - **认证**: 需要Token - **权限**: `message-template:read` #### 请求参数 ```json { "page": 1, "pageSize": 20, "filters": { "type": "text", // 模板类型 "name": { "$like": "欢迎" }, // 模板名称搜索 "status": "active" // 状态筛选 } } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "items": [ { "id": "tpl123", "name": "欢迎消息模板", "type": "text", "content": "欢迎 {{firstName}} 加入我们！", "variables": [ { "name": "firstName", "type": "string", "description": "用户名字", "required": true, "defaultValue": "朋友" } ], "status": "active", "createdBy": "user123", "usageCount": 50, "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-20T10:30:00Z" } ], "pagination": { "page": 1, "pageSize": 20, "total": 25, "totalPages": 2 } } } ``` ### 创建消息模板 #### 接口信息 - **URL**: `/message-templates` - **方法**: `POST` - **认证**: 需要Token - **权限**: `message-template:create` #### 请求参数 ```json { "name": "新用户欢迎", // 模板名称，必填 "type": "text", // 模板类型：text, media, sticker "content": "欢迎 {{firstName}} 加入我们的群组！\n\n感谢您选择我们的服务。", "variables": [ // 变量定义 { "name": "firstName", "type": "string", "description": "用户名字", "required": true, "defaultValue": "朋友" } ], "media": { // 媒体文件（type为media时） "type": "photo", "url": "https://example.com/welcome.jpg", "caption": "欢迎图片" } } ``` ### 获取群发任务列表 #### 接口信息 - **URL**: `/message-tasks` - **方法**: `GET` - **认证**: 需要Token - **权限**: `message-task:read` #### 请求参数 ```json { "page": 1, "pageSize": 20, "sortBy": "createdAt", "sortOrder": "desc", "filters": { "status": "running", // 任务状态 "name": { "$like": "新年" }, // 任务名称搜索 "createdBy": "user123", // 创建者筛选 "createdAt": { // 创建时间范围 "$gte": "2024-01-01", "$lte": "2024-12-31" } } } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "items": [ { "id": "task123", "name": "新年祝福群发", "description": "向所有活跃用户发送新年祝福消息", "template": { "id": "tpl123", "name": "新年祝福模板", "content": "祝 {{firstName}} 新年快乐！" }, "targetCount": 1000, "status": "running", "priority": "normal", "scheduling": { "type": "immediate", "scheduledTime": null, "recurrence": null }, "progress": { "total": 1000, "sent": 750, "failed": 10, "pending": 240, "percentage": 75.0 }, "statistics": { "successRate": 98.7, "averageResponseTime": 2.5, "errorRate": 1.3 }, "createdBy": "user123", "createdAt": "2024-01-20T08:00:00Z", "updatedAt": "2024-01-20T10:30:00Z", "estimatedCompletion": "2024-01-20T12:00:00Z" } ], "pagination": { "page": 1, "pageSize": 20, "total": 50, "totalPages": 3 } } } ``` ### 创建群发任务 #### 接口信息 - **URL**: `/message-tasks` - **方法**: `POST` - **认证**: 需要Token - **权限**: `message-task:create` #### 请求参数 ```json { "name": "春节祝福活动", // 任务名称，必填 "description": "向所有VIP用户发送春节祝福", // 任务描述，可选 "templateId": "tpl123", // 消息模板ID，必填 "targetUsers": { // 目标用户，必填 "type": "filter", // 选择方式：filter, list, all "filters": { // 筛选条件 "status": "active", "isPremium": true, "lastSeen": { "$gte": "2024-01-01" } }, "userIds": [], // 用户ID列表（type为list时） "excludeIds": ["acc456"] // 排除的用户ID }, "scheduling": { // 调度设置 "type": "scheduled", // 执行类型：immediate, scheduled, recurring "scheduledTime": "2024-01-25T00:00:00Z", // 定时时间 "timezone": "Asia/Shanghai", // 时区 "recurrence": { // 重复设置（type为recurring时） "frequency": "daily", // 频率：daily, weekly, monthly "interval": 1, // 间隔 "endDate": "2024-02-25" // 结束日期 } }, "settings": { // 发送设置 "batchSize": 50, // 批次大小 "interval": 1000, // 发送间隔（毫秒） "retryCount": 3, // 重试次数 "priority": "high" // 优先级：low, normal, high }, "variables": { // 全局变量值 "companyName": "我们公司", "eventDate": "2024-01-25" } } ``` #### 响应数据 ```json { "success": true, "code": 201, "message": "任务创建成功", "data": { "id": "task123", "name": "春节祝福活动", "status": "pending", "targetCount": 500, "estimatedDuration": "00:30:00", "estimatedCompletion": "2024-01-25T00:30:00Z", "createdAt": "2024-01-20T10:30:00Z" } } ``` ### 获取任务详情 #### 接口信息 - **URL**: `/message-tasks/{id}` - **方法**: `GET` - **认证**: 需要Token - **权限**: `message-task:read` #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "id": "task123", "name": "春节祝福活动", "description": "向所有VIP用户发送春节祝福", "template": { "id": "tpl123", "name": "春节祝福模板", "content": "祝 {{firstName}} 春节快乐！恭喜发财！", "type": "text" }, "targetUsers": { "type": "filter", "filters": { "status": "active", "isPremium": true }, "count": 500 }, "status": "running", "priority": "high", "scheduling": { "type": "scheduled", "scheduledTime": "2024-01-25T00:00:00Z", "timezone": "Asia/Shanghai" }, "progress": { "total": 500, "sent": 350, "failed": 5, "pending": 145, "percentage": 70.0, "estimatedRemaining": "00:15:00" }, "statistics": { "startTime": "2024-01-25T00:00:00Z", "lastSentTime": "2024-01-25T00:35:00Z", "averageResponseTime": 1.8, "successRate": 98.6, "errorRate": 1.4, "throughput": 600 // 每小时发送数量 }, "settings": { "batchSize": 50, "interval": 1000, "retryCount": 3 }, "errors": [ { "userId": "acc789", "error": "User blocked bot", "timestamp": "2024-01-25T00:15:00Z", "retryCount": 0 } ], "createdBy": "user123", "createdAt": "2024-01-20T10:30:00Z", "updatedAt": "2024-01-25T00:35:00Z" } } ``` ### 控制任务执行 #### 接口信息 - **URL**: `/message-tasks/{id}/control` - **方法**: `POST` - **认证**: 需要Token - **权限**: `message-task:control` #### 请求参数 ```json { "action": "pause" // 操作类型：start, pause, resume, cancel, retry } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "任务已暂停", "data": { "taskId": "task123", "status": "paused", "timestamp": "2024-01-25T00:40:00Z" } } ``` ### 获取发送记录 #### 接口信息 - **URL**: `/message-records` - **方法**: `GET` - **认证**: 需要Token - **权限**: `message-record:read` #### 请求参数 ```json { "page": 1, "pageSize": 50, "filters": { "taskId": "task123", // 任务ID筛选 "userId": "acc456", // 用户ID筛选 "status": "sent", // 发送状态：sent, failed, pending "sentAt": { // 发送时间范围 "$gte": "2024-01-25T00:00:00Z", "$lte": "2024-01-25T23:59:59Z" } } } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "items": [ { "id": "record123", "taskId": "task123", "taskName": "春节祝福活动", "templateId": "tpl123", "userId": "acc456", "userInfo": { "telegramId": "123456789", "username": "testuser", "firstName": "张三", "lastName": "" }, "message": { "type": "text", "content": "祝 张三 春节快乐！恭喜发财！", "messageId": "msg789" }, "status": "sent", "sentAt": "2024-01-25T00:15:30Z", "responseTime": 1200, // 响应时间（毫秒） "retryCount": 0, "error": null, "metadata": { "batchId": "batch001", "priority": "high" } } ], "pagination": { "page": 1, "pageSize": 50, "total": 500, "totalPages": 10 }, "summary": { "totalSent": 450, "totalFailed": 50, "successRate": 90.0, "averageResponseTime": 1800 } } } ``` --- ## 🎯 营销中心 ### 获取营销活动列表 #### 接口信息 - **URL**: `/marketing-campaigns` - **方法**: `GET` - **认证**: 需要Token - **权限**: `marketing-campaign:read` #### 请求参数 ```json { "page": 1, "pageSize": 20, "filters": { "status": "active", // 活动状态 "type": "promotion", // 活动类型 "name": { "$like": "双11" }, // 活动名称搜索 "startDate": { // 开始时间范围 "$gte": "2024-01-01", "$lte": "2024-12-31" } } } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "items": [ { "id": "camp123", "name": "双11购物节活动", "description": "年度最大促销活动", "type": "promotion", "status": "active", "startDate": "2024-11-01T00:00:00Z", "endDate": "2024-11-11T23:59:59Z", "budget": 100000.0, "targetAudience": { "totalCount": 50000, "segments": [ { "name": "VIP用户", "count": 5000, "criteria": { "isPremium": true, "purchaseAmount": { "$gte": 1000 } } } ] }, "channels": ["telegram", "email", "sms"], "metrics": { "impressions": 45000, "clicks": 9000, "conversions": 1800, "ctr": 20.0, // 点击率 "cvr": 4.0, // 转化率 "roi": 250.0 // 投资回报率 }, "createdBy": "user123", "createdAt": "2024-10-15T00:00:00Z", "updatedAt": "2024-11-05T10:30:00Z" } ], "pagination": { "page": 1, "pageSize": 20, "total": 30, "totalPages": 2 } } } ``` ### 创建营销活动 #### 接口信息 - **URL**: `/marketing-campaigns` - **方法**: `POST` - **认证**: 需要Token - **权限**: `marketing-campaign:create` #### 请求参数 ```json { "name": "春节促销活动", // 活动名称，必填 "description": "春节期间特惠促销", // 活动描述，可选 "type": "promotion", // 活动类型：promotion, retention, acquisition "startDate": "2024-01-20T00:00:00Z", // 开始时间，必填 "endDate": "2024-01-30T23:59:59Z", // 结束时间，必填 "budget": 50000.0, // 预算，可选 "targetAudience": { // 目标受众，必填 "segments": [ { "name": "活跃用户", "criteria": { "status": "active", "lastSeen": { "$gte": "2024-01-01" }, "messageCount": { "$gte": 10 } } } ], "excludeSegments": [ // 排除的用户群体 { "name": "已购买用户", "criteria": { "hasPurchased": true, "lastPurchase": { "$gte": "2024-01-01" } } } ] }, "channels": ["telegram", "email"], // 营销渠道 "content": { // 营销内容 "telegram": { "templateId": "tpl123", "variables": { "discount": "20%", "validUntil": "2024-01-30" } }, "email": { "subject": "春节特惠来了！", "templateId": "email_tpl456" } }, "scheduling": { // 调度设置 "strategy": "immediate", // 策略：immediate, scheduled, drip "batchSize": 1000, // 批次大小 "interval": 3600, // 间隔（秒） "timezone": "Asia/Shanghai" }, "trackingSettings": { // 跟踪设置 "enableClickTracking": true, "enableConversionTracking": true, "conversionEvents": ["purchase", "signup"], "attributionWindow": 7 // 归因窗口（天） } } ``` ### 获取客户分析 #### 接口信息 - **URL**: `/marketing/analytics/customers` - **方法**: `GET` - **认证**: 需要Token - **权限**: `marketing-analytics:read` #### 请求参数 ```json { "dateRange": { "startDate": "2024-01-01", "endDate": "2024-01-31" }, "segmentBy": "userType", // 分组维度：userType, location, channel "metrics": ["count", "revenue", "engagement"] // 需要的指标 } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "overview": { "totalCustomers": 10000, "newCustomers": 1500, "activeCustomers": 8500, "retentionRate": 85.0, "churnRate": 15.0, "averageLifetimeValue": 1200.0 }, "segments": [ { "name": "VIP用户", "count": 1000, "percentage": 10.0, "metrics": { "averageOrderValue": 500.0, "purchaseFrequency": 3.2, "lifetimeValue": 2400.0, "engagementScore": 95.0 }, "characteristics": { "avgAge": 35, "primaryLocation": "北京", "preferredChannel": "telegram" } } ], "trends": { "customerGrowth": [ { "date": "2024-01-01", "newCustomers": 50, "totalCustomers": 9500 } ], "retentionTrend": [ { "cohort": "2024-01", "week1": 95.0, "week2": 87.0, "week4": 82.0, "week8": 78.0 } ] }, "predictions": { "churnRisk": [ { "userId": "acc123", "riskScore": 0.85, "reasons": ["降低活跃度", "减少购买频率"], "recommendedActions": ["发送优惠券", "个性化推荐"] } ], "lifetimeValuePrediction": { "next30Days": 150.0, "next90Days": 380.0, "confidence": 0.82 } } } } ``` ### 获取效果统计 #### 接口信息 - **URL**: `/marketing/analytics/performance` - **方法**: `GET` - **认证**: 需要Token - **权限**: `marketing-analytics:read` #### 请求参数 ```json { "campaignId": "camp123", // 活动ID，可选 "dateRange": { "startDate": "2024-01-01", "endDate": "2024-01-31" }, "groupBy": "day", // 分组：hour, day, week, month "channels": ["telegram", "email"], // 渠道筛选 "metrics": ["impressions", "clicks", "conversions", "revenue"] } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "summary": { "impressions": 100000, "clicks": 15000, "conversions": 3000, "revenue": 150000.0, "cost": 25000.0, "ctr": 15.0, // 点击率 "cvr": 20.0, // 转化率 "cpc": 1.67, // 单次点击成本 "cpa": 8.33, // 单次获客成本 "roi": 500.0, // 投资回报率 "roas": 6.0 // 广告支出回报率 }, "byChannel": [ { "channel": "telegram", "impressions": 60000, "clicks": 10000, "conversions": 2200, "revenue": 110000.0, "cost": 15000.0, "metrics": { "ctr": 16.7, "cvr": 22.0, "roi": 633.3 } }, { "channel": "email", "impressions": 40000, "clicks": 5000, "conversions": 800, "revenue": 40000.0, "cost": 10000.0, "metrics": { "ctr": 12.5, "cvr": 16.0, "roi": 300.0 } } ], "timeline": [ { "date": "2024-01-01", "impressions": 3500, "clicks": 525, "conversions": 105, "revenue": 5250.0 } ], "topPerforming": { "campaigns": [ { "id": "camp123", "name": "双11购物节", "conversions": 1500, "revenue": 75000.0, "roi": 750.0 } ], "templates": [ { "id": "tpl123", "name": "优惠券模板", "usage": 50, "conversionRate": 25.0 } ] }, "insights": [ { "type": "opportunity", "title": "Telegram渠道表现优异", "description": "Telegram渠道的转化率比邮件高37.5%，建议增加投入", "impact": "high", "recommendation": "将预算的60%分配给Telegram渠道" } ] } } ``` --- ## 🔒 权限管理 ### 获取权限列表 #### 接口信息 - **URL**: `/permissions` - **方法**: `GET` - **认证**: 需要Token - **权限**: `permission:read` #### 请求参数 ```json { "page": 1, "pageSize": 50, "filters": { "resource": "user", // 资源类型筛选 "action": "read", // 操作类型筛选 "module": "account-management" // 模块筛选 } } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "items": [ { "id": "perm123", "code": "user:read", "name": "查看用户", "description": "查看用户基本信息和列表", "resource": "user", "action": "read", "module": "account-management", "isSystem": true, "createdAt": "2024-01-01T00:00:00Z" }, { "id": "perm124", "code": "user:create", "name": "创建用户", "description": "创建新的用户账号", "resource": "user", "action": "create", "module": "account-management", "isSystem": true, "createdAt": "2024-01-01T00:00:00Z" } ], "pagination": { "page": 1, "pageSize": 50, "total": 120, "totalPages": 3 }, "groupedByModule": { "account-management": [ { "resource": "user", "actions": ["create", "read", "update", "delete"] }, { "resource": "telegram-account", "actions": ["create", "read", "update", "delete", "batch"] } ], "message-management": [ { "resource": "message-template", "actions": ["create", "read", "update", "delete"] }, { "resource": "message-task", "actions": ["create", "read", "update", "delete", "control"] } ] } } } ``` ### 获取角色列表 #### 接口信息 - **URL**: `/roles` - **方法**: `GET` - **认证**: 需要Token - **权限**: `role:read` #### 请求参数 ```json { "page": 1, "pageSize": 20, "filters": { "status": "active", // 状态筛选 "isSystem": false, // 是否系统角色 "name": { "$like": "管理" } // 角色名称搜索 } } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "items": [ { "id": "role123", "name": "账号管理员", "description": "负责管理Telegram账号", "code": "account_admin", "status": "active", "isSystem": false, "permissions": [ { "id": "perm123", "code": "telegram-account:read", "name": "查看账号" }, { "id": "perm124", "code": "telegram-account:create", "name": "创建账号" } ], "userCount": 5, // 拥有此角色的用户数量 "createdBy": "user123", "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-10T10:30:00Z" } ], "pagination": { "page": 1, "pageSize": 20, "total": 15, "totalPages": 1 } } } ``` ### 创建角色 #### 接口信息 - **URL**: `/roles` - **方法**: `POST` - **认证**: 需要Token - **权限**: `role:create` #### 请求参数 ```json { "name": "消息管理员", // 角色名称，必填 "description": "负责管理消息模板和群发任务", // 角色描述，可选 "code": "message_admin", // 角色代码，必填，唯一 "permissions": [ // 权限ID列表，必填 "perm201", "perm202", "perm203" ], "inherits": ["role456"], // 继承的角色ID列表，可选 "status": "active" // 状态，可选，默认active } ``` #### 响应数据 ```json { "success": true, "code": 201, "message": "角色创建成功", "data": { "id": "role789", "name": "消息管理员", "description": "负责管理消息模板和群发任务", "code": "message_admin", "status": "active", "permissions": [ { "id": "perm201", "code": "message-template:create", "name": "创建消息模板" } ], "createdBy": "user123", "createdAt": "2024-01-20T10:30:00Z" } } ``` ### 分配用户角色 #### 接口信息 - **URL**: `/users/{userId}/roles` - **方法**: `POST` - **认证**: 需要Token - **权限**: `user:assign-role` #### 请求参数 ```json { "roleIds": ["role123", "role456"], // 角色ID列表 "action": "assign" // 操作类型：assign, revoke, replace } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "角色分配成功", "data": { "userId": "user456", "roles": [ { "id": "role123", "name": "账号管理员", "assignedAt": "2024-01-20T10:30:00Z" }, { "id": "role456", "name": "消息管理员", "assignedAt": "2024-01-20T10:30:00Z" } ] } } ``` ### 检查用户权限 #### 接口信息 - **URL**: `/auth/check-permission` - **方法**: `POST` - **认证**: 需要Token #### 请求参数 ```json { "permissions": [ // 需要检查的权限列表 "telegram-account:read", "message-task:create" ], "resource": { // 资源信息（可选，用于资源级权限控制） "type": "telegram-account", "id": "acc123", "ownerId": "user456" } } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "权限检查完成", "data": { "hasAllPermissions": false, "permissions": { "telegram-account:read": true, "message-task:create": false }, "missingPermissions": ["message-task:create"], "userId": "user123", "checkedAt": "2024-01-20T10:30:00Z" } } ``` --- ## ⚙️ 系统配置 ### 获取系统配置 #### 接口信息 - **URL**: `/system/config` - **方法**: `GET` - **认证**: 需要Token - **权限**: `system-config:read` #### 请求参数 ```json { "category": "telegram", // 配置分类：telegram, email, sms, system "keys": ["api_token", "rate_limit"] // 指定配置键，可选 } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "telegram": { "api_token": { "value": "***masked***", "type": "password", "description": "Telegram Bot API Token", "updatedAt": "2024-01-20T10:30:00Z", "updatedBy": "user123" }, "rate_limit": { "value": 30, "type": "number", "description": "每秒最大请求数", "min": 1, "max": 50, "updatedAt": "2024-01-15T08:00:00Z", "updatedBy": "user123" }, "webhook_url": { "value": "https://api.example.com/webhook/telegram", "type": "url", "description": "Webhook回调地址", "updatedAt": "2024-01-10T12:00:00Z", "updatedBy": "user123" } }, "system": { "site_name": { "value": "Telegram管理系统", "type": "string", "description": "系统名称" }, "max_file_size": { "value": 10485760, "type": "number", "description": "最大文件上传大小（字节）", "min": 1048576, "max": 104857600 }, "default_language": { "value": "zh-CN", "type": "select", "description": "默认语言", "options": [ { "value": "zh-CN", "label": "简体中文" }, { "value": "en-US", "label": "English" } ] } } } } ``` ### 更新系统配置 #### 接口信息 - **URL**: `/system/config` - **方法**: `PUT` - **认证**: 需要Token - **权限**: `system-config:update` #### 请求参数 ```json { "telegram": { "rate_limit": 25, "webhook_url": "https://new-api.example.com/webhook/telegram" }, "system": { "site_name": "新的系统名称", "max_file_size": 20971520 } } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "配置更新成功", "data": { "updated": [ { "key": "telegram.rate_limit", "oldValue": 30, "newValue": 25 }, { "key": "system.site_name", "oldValue": "Telegram管理系统", "newValue": "新的系统名称" } ], "updatedBy": "user123", "updatedAt": "2024-01-20T10:30:00Z" } } ``` ### 获取系统统计 #### 接口信息 - **URL**: `/system/statistics` - **方法**: `GET` - **认证**: 需要Token - **权限**: `system:read` #### 请求参数 ```json { "dateRange": { "startDate": "2024-01-01", "endDate": "2024-01-31" }, "metrics": ["users", "messages", "tasks", "performance"] // 需要的统计指标 } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "overview": { "totalUsers": 1500, "activeUsers": 1200, "totalAccounts": 50000, "activeAccounts": 45000, "totalMessages": 1000000, "totalTasks": 500, "systemUptime": "99.9%" }, "users": { "newUsers": 150, "activeUsers": 1200, "userGrowthRate": 11.1, "userRetentionRate": 85.0, "averageSessionDuration": 1800, // 秒 "byRole": { "admin": 5, "manager": 50, "operator": 1145 } }, "messages": { "totalSent": 800000, "totalFailed": 50000, "successRate": 94.1, "averageResponseTime": 1500, // 毫秒 "byChannel": { "telegram": 700000, "email": 100000, "sms": 50000 }, "byType": { "marketing": 600000, "notification": 200000, "support": 50000 } }, "tasks": { "totalCreated": 500, "completed": 450, "failed": 30, "running": 20, "successRate": 90.0, "averageExecutionTime": 3600, // 秒 "byPriority": { "high": 100, "normal": 350, "low": 50 } }, "performance": { "cpuUsage": 45.2, "memoryUsage": 68.5, "diskUsage": 72.1, "networkIO": { "inbound": 1024000, // bytes/sec "outbound": 2048000 }, "databaseConnections": { "active": 15, "idle": 5, "total": 20 }, "cacheHitRate": 95.5, "averageApiResponseTime": 150 // 毫秒 }, "trends": [ { "date": "2024-01-01", "users": 1350, "messages": 25000, "tasks": 15 }, { "date": "2024-01-02", "users": 1355, "messages": 26000, "tasks": 18 } ] } } ``` --- ## 📁 文件管理 ### 上传文件 #### 接口信息 - **URL**: `/files/upload` - **方法**: `POST` - **认证**: 需要Token - **权限**: `file:upload` - **Content-Type**: `multipart/form-data` #### 请求参数 ```form-data file: (binary) // 文件内容，必填 category: "avatar" // 文件分类：avatar, document, image, video description: "用户头像" // 文件描述，可选 isPublic: true // 是否公开，可选，默认false ``` #### 响应数据 ```json { "success": true, "code": 201, "message": "文件上传成功", "data": { "id": "file123", "filename": "avatar.jpg", "originalName": "user-avatar.jpg", "size": 102400, "mimeType": "image/jpeg", "category": "avatar", "isPublic": true, "url": "https://cdn.example.com/files/avatar.jpg", "thumbnailUrl": "https://cdn.example.com/thumbs/avatar_thumb.jpg", "metadata": { "width": 300, "height": 300, "format": "JPEG", "colorSpace": "sRGB" }, "uploadedBy": "user123", "uploadedAt": "2024-01-20T10:30:00Z", "expiresAt": null } } ``` ### 获取文件列表 #### 接口信息 - **URL**: `/files` - **方法**: `GET` - **认证**: 需要Token - **权限**: `file:read` #### 请求参数 ```json { "page": 1, "pageSize": 20, "filters": { "category": "image", // 文件分类筛选 "mimeType": "image/jpeg", // MIME类型筛选 "uploadedBy": "user123", // 上传者筛选 "uploadedAt": { // 上传时间范围 "$gte": "2024-01-01", "$lte": "2024-01-31" }, "filename": { "$like": "avatar" } // 文件名搜索 } } ``` #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "items": [ { "id": "file123", "filename": "avatar.jpg", "originalName": "user-avatar.jpg", "size": 102400, "mimeType": "image/jpeg", "category": "avatar", "isPublic": true, "url": "https://cdn.example.com/files/avatar.jpg", "thumbnailUrl": "https://cdn.example.com/thumbs/avatar_thumb.jpg", "downloadCount": 25, "uploadedBy": "user123", "uploadedAt": "2024-01-20T10:30:00Z" } ], "pagination": { "page": 1, "pageSize": 20, "total": 150, "totalPages": 8 }, "summary": { "totalSize": 52428800, // 总文件大小（字节） "totalCount": 150, "byCategory": { "image": 80, "document": 50, "video": 20 }, "storageUsed": "50.0MB", "storageLimit": "1.0GB", "storageUsedPercentage": 5.0 } } } ``` ### 获取文件详情 #### 接口信息 - **URL**: `/files/{id}` - **方法**: `GET` - **认证**: 需要Token - **权限**: `file:read` #### 响应数据 ```json { "success": true, "code": 200, "message": "获取成功", "data": { "id": "file123", "filename": "document.pdf", "originalName": "重要文档.pdf", "size": 2048000, "mimeType": "application/pdf", "category": "document", "description": "项目需求文档", "isPublic": false, "url": "https://cdn.example.com/files/document.pdf", "downloadUrl": "https://api.example.com/files/file123/download", "metadata": { "pages": 25, "author": "作者名", "title": "项目需求文档", "createdDate": "2024-01-15T00:00:00Z" }, "accessLog": [ { "userId": "user456", "action": "download", "timestamp": "2024-01-20T09:00:00Z", "ip": "192.168.1.100" } ], "downloadCount": 15, "uploadedBy": "user123", "uploadedAt": "2024-01-15T14:30:00Z", "updatedAt": "2024-01-20T10:30:00Z", "expiresAt": "2024-12-31T23:59:59Z" } } ``` ### 下载文件 #### 接口信息 - **URL**: `/files/{id}/download` - **方法**: `GET` - **认证**: 需要Token - **权限**: `file:download` #### URL参数 | 参数 | 类型 | 说明 | | ---- | ------ | ------ | | id | String | 文件ID | #### Query参数 | 参数 | 类型 | 说明 | | --------- | ------- | -------------------------- | | thumbnail | Boolean | 是否下载缩略图 | | download | Boolean | 是否强制下载（设置下载头） | #### 响应 成功时返回文件二进制内容，响应头包含： ```http Content-Type: application/octet-stream Content-Disposition: attachment; filename="filename.ext" Content-Length: 1024000 Cache-Control: private, max-age=3600 ``` ### 删除文件 #### 接口信息 - **URL**: `/files/{id}` - **方法**: `DELETE` - **认证**: 需要Token - **权限**: `file:delete` #### 响应数据 ```json { "success": true, "code": 200, "message": "文件删除成功", "data": { "id": "file123", "filename": "deleted-file.jpg", "deletedAt": "2024-01-20T10:30:00Z", "deletedBy": "user123" } } ``` --- ## 🔄 实时通信 ### WebSocket连接 #### 连接信息 - **URL**: `wss://api.example.com/ws` - **协议**: WebSocket - **认证**: 连接时需要传递Token #### 连接参数 ```javascript const ws = new WebSocket('wss://api.example.com/ws', { headers: { Authorization: 'Bearer your-jwt-token', }, }); // 或通过查询参数 const ws = new WebSocket('wss://api.example.com/ws?token=your-jwt-token'); ``` #### 连接事件 ```javascript ws.onopen = function (event) { console.log('WebSocket连接已建立'); // 发送认证消息 ws.send( JSON.stringify({ type: 'auth', token: 'your-jwt-token', }), ); }; ws.onmessage = function (event) { const message = JSON.parse(event.data); console.log('收到消息:', message); }; ws.onclose = function (event) { console.log('WebSocket连接已关闭:', event.code, event.reason); }; ws.onerror = function (error) { console.error('WebSocket错误:', error); }; ``` ### 消息格式 #### 通用消息结构 ```json { "type": "message_type", // 消息类型 "id": "msg123", // 消息ID，可选 "timestamp": "2024-01-20T10:30:00Z", // 时间戳 "data": { // 消息数据 // 具体内容根据消息类型不同 } } ``` #### 认证消息 ```json { "type": "auth", "token": "your-jwt-token" } ``` #### 认证响应 ```json { "type": "auth_result", "success": true, "message": "认证成功", "userId": "user123", "sessionId": "session456" } ``` ### 订阅频道 #### 订阅消息 ```json { "type": "subscribe", "channels": [ "user.user123", // 用户个人频道 "task.task456", // 特定任务频道 "system.notifications", // 系统通知频道 "global.announcements" // 全局公告频道 ] } ``` #### 订阅响应 ```json { "type": "subscribe_result", "success": true, "channels": [ { "name": "user.user123", "status": "subscribed" }, { "name": "task.task456", "status": "subscribed" } ] } ``` #### 取消订阅 ```json { "type": "unsubscribe", "channels": ["task.task456"] } ``` ### 实时消息类型 #### 1. 任务进度更新 ```json { "type": "task_progress", "timestamp": "2024-01-20T10:30:00Z", "data": { "taskId": "task123", "taskName": "春节祝福活动", "progress": { "total": 1000, "sent": 750, "failed": 10, "pending": 240, "percentage": 75.0 }, "estimatedCompletion": "2024-01-20T12:00:00Z", "currentRate": 50 // 每分钟发送数量 } } ``` #### 2. 任务状态变更 ```json { "type": "task_status_change", "timestamp": "2024-01-20T10:30:00Z", "data": { "taskId": "task123", "taskName": "春节祝福活动", "oldStatus": "running", "newStatus": "completed", "reason": "任务执行完成", "statistics": { "duration": 7200, // 执行时长（秒） "totalSent": 990, "totalFailed": 10, "successRate": 99.0 } } } ``` #### 3. 系统通知 ```json { "type": "system_notification", "timestamp": "2024-01-20T10:30:00Z", "data": { "id": "notify123", "title": "系统维护通知", "message": "系统将在今晚22:00-24:00进行维护，期间服务可能中断", "level": "warning", // 级别：info, warning, error, success "category": "maintenance", "targetUsers": ["user123", "user456"], // 目标用户，null表示所有用户 "actions": [ { "text": "查看详情", "url": "/system/maintenance-notice" } ], "expiresAt": "2024-01-21T00:00:00Z" } } ``` #### 4. 用户在线状态 ```json { "type": "user_status", "timestamp": "2024-01-20T10:30:00Z", "data": { "userId": "user456", "username": "testuser", "status": "online", // 状态：online, offline, away, busy "lastSeen": "2024-01-20T10:30:00Z", "device": "web" // 设备类型：web, mobile, desktop } } ``` #### 5. 实时日志 ```json { "type": "log_message", "timestamp": "2024-01-20T10:30:00Z", "data": { "level": "error", // 日志级别：debug, info, warn, error "message": "消息发送失败: 用户已屏蔽机器人", "source": "message-service", "userId": "user123", "taskId": "task456", "context": { "telegramId": "123456789", "errorCode": "BLOCKED_BY_USER" } } } ``` #### 6. 性能指标 ```json { "type": "performance_metrics", "timestamp": "2024-01-20T10:30:00Z", "data": { "cpu": 45.2, // CPU使用率 "memory": 68.5, // 内存使用率 "disk": 72.1, // 磁盘使用率 "network": { "inbound": 1024, // 入站流量 KB/s "outbound": 2048 // 出站流量 KB/s }, "database": { "connections": 15, "queryTime": 150 // 平均查询时间（毫秒） }, "activeUsers": 120, "activeTasks": 5, "messageRate": 50 // 每分钟消息数 } } ``` ### 心跳机制 #### 心跳消息 客户端每30秒发送一次心跳： ```json { "type": "ping", "timestamp": "2024-01-20T10:30:00Z" } ``` #### 心跳响应 服务器响应心跳： ```json { "type": "pong", "timestamp": "2024-01-20T10:30:00Z", "serverTime": "2024-01-20T10:30:05Z" } ``` ### 错误处理 #### 错误消息格式 ```json { "type": "error", "timestamp": "2024-01-20T10:30:00Z", "error": { "code": "INVALID_TOKEN", "message": "Token无效或已过期", "details": {} } } ``` #### 常见错误代码 | 错误代码 | 说明 | 处理建议 | | ------------------- | ------------ | -------------------- | | INVALID_TOKEN | Token无效 | 重新登录获取新Token | | TOKEN_EXPIRED | Token过期 | 刷新Token或重新登录 | | PERMISSION_DENIED | 权限不足 | 检查用户权限设置 | | RATE_LIMIT_EXCEEDED | 请求频率过高 | 减少请求频率 | | CHANNEL_NOT_FOUND | 频道不存在 | 检查频道名称是否正确 | | CONNECTION_LOST | 连接丢失 | 尝试重新连接 | ### 重连机制 #### 自动重连示例 ```javascript class WebSocketClient { constructor(url, token) { this.url = url; this.token = token; this.reconnectAttempts = 0; this.maxReconnectAttempts = 5; this.reconnectInterval = 1000; // 初始重连间隔 this.connect(); } connect() { this.ws = new WebSocket(this.url); this.ws.onopen = () => { console.log('Connected to WebSocket'); this.reconnectAttempts = 0; this.reconnectInterval = 1000; // 发送认证消息 this.authenticate(); }; this.ws.onmessage = (event) => { const message = JSON.parse(event.data); this.handleMessage(message); }; this.ws.onclose = (event) => { console.log('WebSocket connection closed:', event.code); this.handleReconnect(); }; this.ws.onerror = (error) => { console.error('WebSocket error:', error); }; } authenticate() { this.send({ type: 'auth', token: this.token, }); } handleReconnect() { if (this.reconnectAttempts < this.maxReconnectAttempts) { this.reconnectAttempts++; console.log( `Attempting to reconnect (${this.reconnectAttempts}/${this.maxReconnectAttempts})...`, ); setTimeout(() => { this.connect(); }, this.reconnectInterval); // 指数退避策略 this.reconnectInterval = Math.min(this.reconnectInterval * 2, 30000); } else { console.error('Max reconnection attempts reached'); } } send(message) { if (this.ws.readyState === WebSocket.OPEN) { this.ws.send(JSON.stringify(message)); } else { console.warn('WebSocket is not connected'); } } handleMessage(message) { switch (message.type) { case 'auth_result': if (message.success) { console.log('Authentication successful'); this.subscribeToChannels(); } else { console.error('Authentication failed:', message.message); } break; case 'task_progress': this.onTaskProgress(message.data); break; case 'system_notification': this.onSystemNotification(message.data); break; case 'error': this.onError(message.error); break; default: console.log('Received message:', message); } } subscribeToChannels() { this.send({ type: 'subscribe', channels: [`user.${this.userId}`, 'system.notifications'], }); } onTaskProgress(data) { // 处理任务进度更新 console.log('Task progress:', data); } onSystemNotification(data) { // 处理系统通知 console.log('System notification:', data); } onError(error) { console.error('WebSocket error:', error); if (error.code === 'INVALID_TOKEN') { // Token无效，需要重新登录 this.handleTokenError(); } } handleTokenError() { // 处理Token错误，通常需要重新登录 window.location.href = '/login'; } } // 使用示例 const wsClient = new WebSocketClient('wss://api.example.com/ws', userToken); ``` --- ## 📚 附录 ### API变更历史 #### v2.0.0 (2024-01-20) - 新增营销中心相关接口 - 新增WebSocket实时通信 - 优化权限管理接口 - 增加文件管理功能 #### v1.2.0 (2023-12-15) - 新增批量操作接口 - 优化分页查询性能 - 增加更多筛选条件 #### v1.1.0 (2023-11-20) - 新增消息模板管理 - 增加任务调度功能 - 完善错误处理机制 #### v1.0.0 (2023-10-01) - 初始版本发布 - 基础的用户认证和账号管理 - 简单的消息发送功能 ### SDK与示例 #### JavaScript SDK ```javascript // 安装: npm install telegram-system-sdk import TelegramSystemSDK from 'telegram-system-sdk'; const client = new TelegramSystemSDK({ baseURL: 'https://api.example.com/v1', token: 'your-jwt-token', }); // 获取账号列表 const accounts = await client.accounts.list({ page: 1, pageSize: 20, filters: { status: 'active' }, }); // 创建群发任务 const task = await client.messages.createTask({ name: '新年祝福', templateId: 'tpl123', targetUsers: { type: 'all' }, }); // 监听实时事件 client.on('task_progress', (data) => { console.log('任务进度更新:', data); }); ``` #### Python SDK ```python # 安装: pip install telegram-system-sdk from telegram_system_sdk import TelegramSystemClient client = TelegramSystemClient( base_url='https://api.example.com/v1', token='your-jwt-token' ) # 获取账号列表 accounts = client.accounts.list( page=1, page_size=20, filters={'status': 'active'} ) # 创建消息模板 template = client.templates.create({ 'name': '欢迎模板', 'type': 'text', 'content': '欢迎 {{firstName}} 加入！' }) ``` ### 测试环境 #### Postman集合 提供完整的Postman集合文件，包含所有接口的示例请求： ```json { "info": { "name": "Telegram管理系统API", "description": "完整的API接口测试集合", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{access_token}}", "type": "string" } ] }, "variable": [ { "key": "base_url", "value": "https://api.example.com/v1" } ] } ``` #### 测试数据 提供用于测试的示例数据： ```json { "testUsers": [ { "username": "test_admin", "password": "test123456", "roles": ["admin"] }, { "username": "test_operator", "password": "test123456", "roles": ["operator"] } ], "testAccounts": [ { "telegramId": "123456789", "username": "testuser1", "firstName": "测试", "lastName": "用户1" } ], "testTemplates": [ { "name": "测试模板", "type": "text", "content": "这是一个测试消息模板，用户名：{{firstName}}" } ] } ``` --- ## 🤝 支持与反馈 ### 技术支持 - **文档地址**: https://docs.telegram-system.com - **API控制台**: https://console.telegram-system.com - **状态页面**: https://status.telegram-system.com ### 联系方式 - **技术支持邮箱**: support@telegram-system.com - **开发者邮箱**: dev@telegram-system.com - **问题反馈**: https://github.com/telegram-system/api/issues ### 更新通知 关注API更新和维护通知： - **邮件订阅**: api-updates@telegram-system.com - **Webhook通知**: 可配置Webhook接收API变更通知 - **版本发布**: 关注GitHub Release页面 --- **最后更新**: 2024-01-20 **文档版本**: v2.0.0 **API版本**: v1 > 本文档将随着API的演进持续更新，请定期查看最新版本。如有疑问或建议，欢迎通过上述渠道联系我们。