Files

你的用户名 237c7802e5

Deploy / deploy (push) Has been cancelled

Details

Initial commit: Telegram Management System

Full-stack web application for Telegram management
- Frontend: Vue 3 + Vben Admin
- Backend: NestJS
- Features: User management, group broadcast, statistics

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-04 15:37:50 +08:00

58 KiB

Raw Blame History

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：

Authorization: Bearer <your-jwt-token>

Token获取流程

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包含以下信息：

{
  "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：

Content-Type: application/json

分页参数

支持分页的接口使用统一的分页参数：

{
  "page": 1, // 页码，从1开始
  "pageSize": 20, // 每页数量，默认20，最大100
  "sortBy": "createdAt", // 排序字段
  "sortOrder": "desc" // 排序方向：asc/desc
}

筛选参数

支持筛选的接口使用统一的筛选格式：

{
  "filters": {
    "status": "active", // 精确匹配
    "name": { "$like": "admin" }, // 模糊匹配
    "createdAt": {
      // 范围查询
      "$gte": "2024-01-01",
      "$lte": "2024-12-31"
    }
  }
}

响应格式

成功响应

{
  "success": true,
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体数据
  },
  "timestamp": "2024-01-20T10:30:00Z"
}

分页响应

{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 100,
      "totalPages": 5
    }
  },
  "timestamp": "2024-01-20T10:30:00Z"
}

❌ 错误处理

错误响应格式

{
  "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
认证: 无需认证

请求参数

{
  "username": "admin", // 用户名，必填
  "password": "123456", // 密码，必填
  "rememberMe": true, // 记住我，可选，默认false
  "captcha": "ABCD", // 验证码，可选
  "captchaId": "cap123" // 验证码ID，可选
}

响应数据

{
  "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"
    }
  }
}

错误示例

{
  "success": false,
  "code": 401,
  "message": "用户名或密码错误",
  "error": {
    "type": "AuthenticationError",
    "details": []
  }
}

用户登出

接口信息

URL: /auth/logout
方法: POST
认证: 需要Token

请求参数

{
  "refreshToken": "refresh-token-here" // 可选，提供则同时注销refresh token
}

响应数据

{
  "success": true,
  "code": 200,
  "message": "登出成功"
}

刷新Token

接口信息

URL: /auth/refresh
方法: POST
认证: 需要Refresh Token

请求参数

{
  "refreshToken": "your-refresh-token"
}

响应数据

{
  "success": true,
  "code": 200,
  "message": "Token刷新成功",
  "data": {
    "token": "new-jwt-token",
    "refreshToken": "new-refresh-token",
    "expiresIn": 7200
  }
}

获取当前用户信息

接口信息

URL: /auth/me
方法: GET
认证: 需要Token

响应数据

{
  "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

请求参数

{
  "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"
    }
  }
}

响应数据

{
  "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

请求参数

{
  "telegramId": "123456789", // Telegram ID，必填
  "username": "testuser", // 用户名，可选
  "firstName": "Test", // 名字，必填
  "lastName": "User", // 姓氏，可选
  "phone": "13800138000", // 手机号，可选
  "languageCode": "zh-CN", // 语言代码，可选
  "metadata": {
    // 元数据，可选
    "bio": "用户简介",
    "location": "北京"
  }
}

响应数据

{
  "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

响应数据

{
  "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

请求参数

{
  "username": "newusername", // 用户名，可选
  "firstName": "NewName", // 名字，可选
  "lastName": "NewLastName", // 姓氏，可选
  "phone": "13900139000", // 手机号，可选
  "status": "active", // 状态，可选
  "metadata": {
    // 元数据，可选
    "bio": "新的用户简介",
    "location": "上海"
  }
}

删除账号

接口信息

URL: /telegram-accounts/{id}
方法: DELETE
认证: 需要Token
权限: telegram-account:delete

响应数据

{
  "success": true,
  "code": 200,
  "message": "删除成功"
}

批量操作账号

接口信息

URL: /telegram-accounts/batch
方法: POST
认证: 需要Token
权限: telegram-account:batch

请求参数

{
  "action": "update_status", // 操作类型：update_status, delete, export
  "accountIds": ["acc1", "acc2"], // 账号ID列表
  "data": {
    // 操作数据（根据action不同而不同）
    "status": "inactive"
  }
}

响应数据

{
  "success": true,
  "code": 200,
  "message": "批量操作成功",
  "data": {
    "total": 2,
    "success": 2,
    "failed": 0,
    "errors": []
  }
}

📨 私信群发

获取消息模板列表

接口信息

URL: /message-templates
方法: GET
认证: 需要Token
权限: message-template:read

请求参数

{
  "page": 1,
  "pageSize": 20,
  "filters": {
    "type": "text", // 模板类型
    "name": { "$like": "欢迎" }, // 模板名称搜索
    "status": "active" // 状态筛选
  }
}

响应数据

{
  "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

请求参数

{
  "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

请求参数

{
  "page": 1,
  "pageSize": 20,
  "sortBy": "createdAt",
  "sortOrder": "desc",
  "filters": {
    "status": "running", // 任务状态
    "name": { "$like": "新年" }, // 任务名称搜索
    "createdBy": "user123", // 创建者筛选
    "createdAt": {
      // 创建时间范围
      "$gte": "2024-01-01",
      "$lte": "2024-12-31"
    }
  }
}

响应数据

{
  "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

请求参数

{
  "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"
  }
}

响应数据

{
  "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

响应数据

{
  "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

请求参数

{
  "action": "pause" // 操作类型：start, pause, resume, cancel, retry
}

响应数据

{
  "success": true,
  "code": 200,
  "message": "任务已暂停",
  "data": {
    "taskId": "task123",
    "status": "paused",
    "timestamp": "2024-01-25T00:40:00Z"
  }
}

获取发送记录

接口信息

URL: /message-records
方法: GET
认证: 需要Token
权限: message-record:read

请求参数

{
  "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"
    }
  }
}

响应数据

{
  "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

请求参数

{
  "page": 1,
  "pageSize": 20,
  "filters": {
    "status": "active", // 活动状态
    "type": "promotion", // 活动类型
    "name": { "$like": "双11" }, // 活动名称搜索
    "startDate": {
      // 开始时间范围
      "$gte": "2024-01-01",
      "$lte": "2024-12-31"
    }
  }
}

响应数据

{
  "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

请求参数

{
  "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

请求参数

{
  "dateRange": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  },
  "segmentBy": "userType", // 分组维度：userType, location, channel
  "metrics": ["count", "revenue", "engagement"] // 需要的指标
}

响应数据

{
  "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

请求参数

{
  "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"]
}

响应数据

{
  "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

请求参数

{
  "page": 1,
  "pageSize": 50,
  "filters": {
    "resource": "user", // 资源类型筛选
    "action": "read", // 操作类型筛选
    "module": "account-management" // 模块筛选
  }
}

响应数据

{
  "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

请求参数

{
  "page": 1,
  "pageSize": 20,
  "filters": {
    "status": "active", // 状态筛选
    "isSystem": false, // 是否系统角色
    "name": { "$like": "管理" } // 角色名称搜索
  }
}

响应数据

{
  "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

请求参数

{
  "name": "消息管理员", // 角色名称，必填
  "description": "负责管理消息模板和群发任务", // 角色描述，可选
  "code": "message_admin", // 角色代码，必填，唯一
  "permissions": [
    // 权限ID列表，必填
    "perm201",
    "perm202",
    "perm203"
  ],
  "inherits": ["role456"], // 继承的角色ID列表，可选
  "status": "active" // 状态，可选，默认active
}

响应数据

{
  "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

请求参数

{
  "roleIds": ["role123", "role456"], // 角色ID列表
  "action": "assign" // 操作类型：assign, revoke, replace
}

响应数据

{
  "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

请求参数

{
  "permissions": [
    // 需要检查的权限列表
    "telegram-account:read",
    "message-task:create"
  ],
  "resource": {
    // 资源信息（可选，用于资源级权限控制）
    "type": "telegram-account",
    "id": "acc123",
    "ownerId": "user456"
  }
}

响应数据

{
  "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

请求参数

{
  "category": "telegram", // 配置分类：telegram, email, sms, system
  "keys": ["api_token", "rate_limit"] // 指定配置键，可选
}

响应数据

{
  "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

请求参数

{
  "telegram": {
    "rate_limit": 25,
    "webhook_url": "https://new-api.example.com/webhook/telegram"
  },
  "system": {
    "site_name": "新的系统名称",
    "max_file_size": 20971520
  }
}

响应数据

{
  "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

请求参数

{
  "dateRange": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  },
  "metrics": ["users", "messages", "tasks", "performance"] // 需要的统计指标
}

响应数据

{
  "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

请求参数

file: (binary)                          // 文件内容，必填
category: "avatar"                       // 文件分类：avatar, document, image, video
description: "用户头像"                   // 文件描述，可选
isPublic: true                          // 是否公开，可选，默认false

响应数据

{
  "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

请求参数

{
  "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" } // 文件名搜索
  }
}

响应数据

{
  "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

响应数据

{
  "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	是否强制下载（设置下载头）

响应

成功时返回文件二进制内容，响应头包含：

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

响应数据

{
  "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

连接参数

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');

连接事件

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);
};

消息格式

通用消息结构

{
  "type": "message_type", // 消息类型
  "id": "msg123", // 消息ID，可选
  "timestamp": "2024-01-20T10:30:00Z", // 时间戳
  "data": {
    // 消息数据
    // 具体内容根据消息类型不同
  }
}

认证消息

{
  "type": "auth",
  "token": "your-jwt-token"
}

认证响应

{
  "type": "auth_result",
  "success": true,
  "message": "认证成功",
  "userId": "user123",
  "sessionId": "session456"
}

订阅频道

订阅消息

{
  "type": "subscribe",
  "channels": [
    "user.user123", // 用户个人频道
    "task.task456", // 特定任务频道
    "system.notifications", // 系统通知频道
    "global.announcements" // 全局公告频道
  ]
}

订阅响应

{
  "type": "subscribe_result",
  "success": true,
  "channels": [
    {
      "name": "user.user123",
      "status": "subscribed"
    },
    {
      "name": "task.task456",
      "status": "subscribed"
    }
  ]
}

取消订阅

{
  "type": "unsubscribe",
  "channels": ["task.task456"]
}

实时消息类型

1. 任务进度更新

{
  "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. 任务状态变更

{
  "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. 系统通知

{
  "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. 用户在线状态

{
  "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. 实时日志

{
  "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. 性能指标

{
  "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秒发送一次心跳：

{
  "type": "ping",
  "timestamp": "2024-01-20T10:30:00Z"
}

心跳响应

服务器响应心跳：

{
  "type": "pong",
  "timestamp": "2024-01-20T10:30:00Z",
  "serverTime": "2024-01-20T10:30:05Z"
}

错误处理

错误消息格式

{
  "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	连接丢失	尝试重新连接

重连机制

自动重连示例

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

// 安装: 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

# 安装: 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集合文件，包含所有接口的示例请求：

{
  "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"
    }
  ]
}

测试数据

提供用于测试的示例数据：

{
  "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的演进持续更新，请定期查看最新版本。如有疑问或建议，欢迎通过上述渠道联系我们。

58 KiB Raw Blame History Unescape Escape

Telegram 管理系统 API 接口文档

📋 文档目录

🔍 接口概述

API特性

支持的HTTP方法

环境地址

🔐 认证机制

JWT Token认证

Token获取流程

Token结构

📝 通用规范

请求格式

Content-Type

分页参数

筛选参数

响应格式

成功响应

分页响应

❌ 错误处理

错误响应格式

HTTP状态码

错误类型

👤 用户认证

用户登录

接口信息

请求参数

响应数据

错误示例

用户登出

接口信息

请求参数

响应数据

刷新Token

接口信息

请求参数

响应数据

获取当前用户信息

接口信息

响应数据

📋 账号管理

获取Telegram账号列表

接口信息

请求参数

响应数据

创建Telegram账号

接口信息

请求参数

响应数据

获取账号详情

接口信息

URL参数

响应数据

更新账号信息

接口信息

请求参数

删除账号

接口信息

响应数据

批量操作账号

接口信息

请求参数

响应数据

📨 私信群发

获取消息模板列表

接口信息

请求参数

响应数据

创建消息模板

接口信息

请求参数

获取群发任务列表

接口信息

请求参数

响应数据

创建群发任务

接口信息

请求参数

响应数据

获取任务详情

58 KiB

Raw Blame History