telegram-management-system/SMS_PLATFORM_INTEGRATION_GUIDE.md

# 短信接码平台集成使用指南

## 一、系统概述

本系统已集成10个主流短信接码平台，提供统一的接口和智能路由功能，支持：
- 多平台自动切换
- 智能价格比较
- 自动故障转移
- 负载均衡
- 统一的API接口

## 二、已集成的平台

| 平台名称 | 平台代码 | 特点 | 支持国家数 |
|---------|---------|------|-----------|
| SMS-Activate | smsactivate | 老牌服务商，稳定可靠 | 180+ |
| SMS-PVA | smspva | 价格适中，服务稳定 | 100+ |
| 5SIM | 5sim | 价格低廉，号码质量高 | 180+ |
| SMS-Man | smsman | 即时激活，高成功率 | 150+ |
| GetSMSCode | getsmscode | 支持支付宝/微信支付 | 100+ |
| SMS-REG | smsreg | 老牌服务商，稳定可靠 | 120+ |
| OnlineSIM | onlinesim | 号码资源丰富 | 100+ |
| TextNow | textnow | 免费美国号码 | 美国/加拿大 |
| Receive-SMS | receivesms | 支持长期租赁 | 80+ |
| SMS-Service | smsservice | 新兴平台，价格优势 | 90+ |

## 三、配置说明

### 1. 平台API密钥配置

在数据库的 `config` 表中配置各平台的API密钥：

```javascript
// SMS-Activate
smsKey: "你的API密钥"

// SMS-PVA
sms2Username: "用户名"
sms2Pwd: "密码"

// 新平台配置格式
sms_5sim_apiKey: "API密钥"
sms_smsman_apiKey: "API密钥"
sms_getsmscode_username: "用户名"
sms_getsmscode_apiKey: "API密钥"
// ... 其他平台类似
```

### 2. 平台启用配置

```javascript
// 在 sms_platforms 表中配置
{
    platform_code: "5sim",
    is_enabled: true,      // 是否启用
    priority: 1,           // 优先级（数字越小优先级越高）
    api_key: "xxx"         // API密钥
}
```

### 3. 路由策略配置

```javascript
// 在 config 表中配置
sms_default_strategy: "price"  // 默认策略
sms_failover_strategy: "priority"  // 故障转移策略
sms_max_retries: 30  // 最大重试次数
sms_retry_interval: 20000  // 重试间隔(毫秒)
```

## 四、API接口使用

### 1. 获取手机号码

```bash
POST /api/sms/getPhone
Content-Type: application/json
Authorization: Bearer {token}

{
    "country": "us",        // 国家代码（可选）
    "service": "tg",        // 服务类型，默认tg
    "platform": "5sim",     // 指定平台（可选）
    "strategy": "price"     // 选择策略：price|success|balance|random|priority
}

# 响应
{
    "code": 0,
    "data": {
        "id": "12345",
        "phone": "1234567890",
        "country": "us",
        "price": 15,
        "platform": "5sim",
        "platformName": "5SIM"
    }
}
```

### 2. 获取验证码

```bash
POST /api/sms/getSmsCode
Content-Type: application/json
Authorization: Bearer {token}

{
    "orderId": "12345",
    "phone": "1234567890",
    "platform": "5sim",
    "maxRetries": 30,        // 可选，默认30次
    "retryInterval": 20000   // 可选，默认20秒
}

# 响应
{
    "code": 0,
    "data": {
        "code": "123456"
    }
}
```

### 3. 设置订单状态

```bash
POST /api/sms/setStatus
Content-Type: application/json
Authorization: Bearer {token}

{
    "orderId": "12345",
    "status": "complete",   // complete|cancel|6|8
    "platform": "5sim"
}
```

### 4. 查询平台余额

```bash
# 单个平台余额
GET /api/sms/platforms/{platformCode}/balance
Authorization: Bearer {token}

# 所有平台余额
GET /api/sms/balances
Authorization: Bearer {token}
```

### 5. 获取价格列表

```bash
GET /api/sms/prices?service=tg&country=us
Authorization: Bearer {token}

# 响应
{
    "code": 0,
    "data": {
        "priceList": [
            {
                "platform": "5sim",
                "platformName": "5SIM",
                "code": "us",
                "name": "美国",
                "price": 15,
                "count": 1000
            }
        ]
    }
}
```

### 6. 平台健康检查

```bash
GET /api/sms/platforms/{platformCode}/health
Authorization: Bearer {token}
```

### 7. 获取统计信息

```bash
GET /api/sms/statistics?startDate=2024-01-01&endDate=2024-01-31
Authorization: Bearer {token}
```

## 五、代码使用示例

### 1. 直接使用SmsServiceManager

```javascript
const SmsServiceManager = require("@src/util/sms/SmsServiceManager");

// 获取手机号码（自动选择最优平台）
const phoneResult = await SmsServiceManager.getPhone({
    country: "us",
    service: "tg",
    strategy: "price"  // 选择最便宜的平台
});

console.log(`获取到号码: ${phoneResult.phone}, 平台: ${phoneResult.platformName}`);

// 获取验证码
const code = await SmsServiceManager.getSmsCode(
    phoneResult.id,
    phoneResult.phone,
    phoneResult.platform
);

console.log(`验证码: ${code}`);

// 完成激活
await SmsServiceManager.setOrderStatus(phoneResult.id, "complete", phoneResult.platform);
```

### 2. 使用兼容的SimUtil

```javascript
const SimUtil = require("@src/util/SimUtil");

// 新方法（推荐）
const phone = await SimUtil.getPhone({
    country: "us",
    strategy: "price"
});

// 旧方法（兼容）
const smsBean = await SimUtil.getBean();
const phone2 = await smsBean.getPhone();
```

### 3. 批量价格比较

```javascript
// 获取所有平台的美国号码价格
const priceList = await SmsServiceManager.getPriceList("tg", "us");
console.log("价格列表（从低到高）:", priceList);

// 获取推荐平台
const recommended = await SmsServiceManager.getRecommendedPlatform({
    country: "us",
    service: "tg"
});
console.log("推荐平台:", recommended);
```

## 六、高级功能

### 1. 智能路由策略

系统支持5种路由策略：

- **price**: 价格优先，自动选择最便宜的平台
- **success**: 成功率优先，选择成功率最高的平台
- **balance**: 余额均衡，优先使用余额较多的平台
- **random**: 随机选择，实现负载均衡
- **priority**: 优先级模式，按配置的优先级选择

### 2. 自动故障转移

当某个平台出现故障时，系统会自动切换到备用平台：

```javascript
// 平台故障时会自动重试其他平台
const phone = await SmsServiceManager.getPhone({
    maxRetries: 3  // 最多尝试3个不同的平台
});
```

### 3. 缓存机制

- 国家列表缓存：24小时
- 价格信息缓存：1小时
- 平台状态缓存：5分钟
- 验证码缓存：10分钟

### 4. 健康检查

系统每5分钟自动检查所有平台的健康状态，包括：
- API连通性
- 余额查询
- 响应时间

## 七、监控和统计

### 1. 实时监控

- 平台余额监控
- 成功率统计
- 响应时间监控
- 故障告警

### 2. 统计报表

- 日/周/月使用统计
- 成本分析
- 平台对比
- 国家分布

## 八、最佳实践

1. **合理配置优先级**：将稳定性高的平台设置较高优先级
2. **启用多个平台**：至少启用3-5个平台确保高可用性
3. **定期检查余额**：设置余额告警阈值
4. **监控成功率**：定期查看各平台成功率，调整策略
5. **使用缓存**：充分利用价格缓存减少API调用

## 九、故障排查

### 1. 常见错误

- **余额不足**：检查平台余额，及时充值
- **API密钥错误**：验证配置的API密钥是否正确
- **无可用号码**：该国家/服务暂时无号码，尝试其他平台
- **超时错误**：增加重试次数或重试间隔

### 2. 日志查看

```bash
# 查看短信服务日志
tail -f backend/logs/tg.log | grep "短信"

# 查看特定平台日志
tail -f backend/logs/tg.log | grep "5SIM"
```

## 十、后续优化计划

1. 添加更多短信平台支持
2. 实现智能定价策略
3. 添加批量号码获取功能
4. 支持号码池管理
5. 增强统计分析功能
6. 添加WebSocket实时推送