# 短信服务迁移说明 - 从阿里云SMS到腾讯云SMS

## 迁移概述
将短信服务从阿里云SMS迁移到腾讯云SMS，保持原有功能不变。

## 1. 代码变更

### 1.1 SmsServiceImpl.java
**位置**：`src/main/java/com/xy/xyaicpzs/service/impl/SmsServiceImpl.java`

**主要变更**：
- 移除阿里云SDK依赖（`com.aliyun.dysmsapi20170525`）
- 引入腾讯云SDK（`com.tencentcloudapi.sms.v20210111`）
- 修改客户端创建方式
- 修改短信发送请求构建方式
- 手机号格式改为E.164标准（+86前缀）

**关键代码**：
```java
// 创建腾讯云短信客户端
private SmsClient createSmsClient() {
    Credential cred = new Credential(secretId, secretKey);
    return new SmsClient(cred, region);
}

// 发送短信
SendSmsRequest req = new SendSmsRequest();
req.setSmsSdkAppId(sdkAppId);
req.setSignName(signName);
req.setTemplateId(templateId);
req.setTemplateParamSet(new String[]{verificationCode});
req.setPhoneNumberSet(new String[]{"+86" + phoneNumber});
```

### 1.2 配置文件更新
**位置**：`src/main/resources/application.yml`

**旧配置（阿里云）**：
```yaml
aliyun:
  sms:
    sign-name: 西安精彩数据服务社
    template-code: SMS_489840017
    access-key-id: LTAI5tR18rXPYazi3y8kAuep
    access-key-secret: KZ1aKZOupilVc332SXE1g1DfKsqHPu
```

**新配置（腾讯云）**：
```yaml
tencent:
  sms:
    secret-id: ${TENCENT_SMS_SECRET_ID:your-secret-id}
    secret-key: ${TENCENT_SMS_SECRET_KEY:your-secret-key}
    sdk-app-id: 1401068120
    template-id: 2598660
    sign-name: 西安溢彩数智科技有限公司
    region: ap-guangzhou
```

## 2. 配置说明

### 2.1 必需配置项
| 配置项 | 说明 | 示例值 |
|--------|------|--------|
| secret-id | 腾讯云SecretId | 从腾讯云控制台获取 |
| secret-key | 腾讯云SecretKey | 从腾讯云控制台获取 |
| sdk-app-id | 短信应用ID | 1401068120 |
| template-id | 短信模板ID | 2598660 |
| sign-name | 短信签名 | 西安溢彩数智科技有限公司 |
| region | 地域 | ap-guangzhou（默认） |

### 2.2 环境变量配置（推荐）
为了安全，建议使用环境变量配置敏感信息：

**Linux/Mac**：
```bash
export TENCENT_SMS_SECRET_ID=your-secret-id
export TENCENT_SMS_SECRET_KEY=your-secret-key
```

**Windows**：
```cmd
set TENCENT_SMS_SECRET_ID=your-secret-id
set TENCENT_SMS_SECRET_KEY=your-secret-key
```

或者直接在 `application.yml` 中替换默认值。

## 3. Maven依赖

确保 `pom.xml` 中已添加腾讯云SMS SDK依赖：

```xml
<!-- 腾讯云SMS SDK -->
<dependency>
    <groupId>com.tencentcloudapi</groupId>
    <artifactId>tencentcloud-sdk-java-sms</artifactId>
    <version>3.1.xxx</version>
</dependency>
```

**注意**：可以移除阿里云SMS相关依赖：
```xml
<!-- 可以删除 -->
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>dysmsapi20170525</artifactId>
    <version>xxx</version>
</dependency>
```

## 4. 功能保持不变

### 4.1 验证码生成
- 仍然生成6位随机数字验证码
- 验证码有效期：5分钟

### 4.2 发送限制
- 每个手机号每天最多发送10次
- 使用Redis存储发送次数和验证码

### 4.3 API接口
- 接口路径不变：`POST /api/sms/sendCode`
- 请求参数不变：`phoneNumber`
- 响应格式不变

## 5. 腾讯云SMS模板要求

### 5.1 模板格式
根据模板ID `2598660`，模板内容应该类似：
```
您的验证码是{1}，请在5分钟内完成验证。
```

### 5.2 模板参数
代码中传递的参数：
```java
String[] templateParamSet = {verificationCode};
```

**注意**：腾讯云模板参数是数组形式，按顺序对应模板中的 `{1}`, `{2}` 等占位符。

## 6. 手机号格式

### 6.1 阿里云格式
```
13868246742  // 直接11位手机号
```

### 6.2 腾讯云格式（E.164标准）
```
+8613868246742  // 需要加 +86 前缀
```

代码中已自动处理：
```java
String[] phoneNumberSet = {"+86" + phoneNumber};
```

## 7. 错误处理

### 7.1 发送成功判断
腾讯云返回的状态码为 `"Ok"` 表示成功：
```java
if ("Ok".equals(code)) {
    // 发送成功
}
```

### 7.2 常见错误码
| 错误码 | 说明 | 处理方式 |
|--------|------|---------|
| FailedOperation.ContainSensitiveWord | 内容包含敏感词 | 检查模板内容 |
| FailedOperation.SignatureIncorrectOrUnapproved | 签名未审核或不正确 | 检查签名配置 |
| LimitExceeded.PhoneNumberDailyLimit | 手机号日发送量超限 | 已在代码中限制 |
| InvalidParameterValue.TemplateParameterFormatError | 模板参数格式错误 | 检查参数数组 |

## 8. 测试建议

### 8.1 单元测试
1. 测试验证码生成
2. 测试发送次数限制
3. 测试验证码验证

### 8.2 集成测试
1. 发送验证码到真实手机号
2. 验证短信内容格式
3. 验证验证码有效期
4. 验证每日发送次数限制

### 8.3 测试命令
```bash
curl -X POST http://localhost:8123/api/sms/sendCode \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "phoneNumber=13868246742"
```

## 9. 注意事项

1. **配置敏感信息**：
   - 不要将 `secret-id` 和 `secret-key` 提交到代码仓库
   - 使用环境变量或配置中心管理

2. **模板审核**：
   - 确保腾讯云控制台中模板ID `2598660` 已审核通过
   - 确保签名"西安溢彩数智科技有限公司"已审核通过

3. **地域选择**：
   - 默认使用 `ap-guangzhou`（广州）
   - 可根据实际情况修改为其他地域

4. **费用**：
   - 腾讯云SMS按条计费
   - 建议在控制台设置费用告警

## 10. 回滚方案

如果需要回滚到阿里云SMS：

1. 恢复 `SmsServiceImpl.java` 的旧版本
2. 恢复 `application.yml` 中的阿里云配置
3. 确保阿里云SDK依赖存在
4. 重启应用

## 11. 完成状态

✅ 代码迁移完成
✅ 配置文件更新
✅ 编译检查通过
✅ 功能保持不变

**迁移已完成，可以部署使用！**

## 12. 相关文档

- [腾讯云SMS SDK文档](https://cloud.tencent.com/document/product/382/43199)
- [腾讯云SMS API文档](https://cloud.tencent.com/document/api/382/52071)
- [腾讯云SMS控制台](https://console.cloud.tencent.com/smsv2)