schoolNews/schoolNewsServ/auth/邮件服务配置说明.md

# 邮件和短信服务配置说明

## 一、邮件服务配置

### 1. 在 application.yml 中添加邮件配置

```yaml
spring:
  mail:
    # 邮件服务器地址（以QQ邮箱为例）
    host: smtp.qq.com
    # 端口号
    port: 587
    # 发件人邮箱
    username: your-email@qq.com
    # 授权码（不是邮箱密码）
    password: your-authorization-code
    # 编码
    default-encoding: UTF-8
    properties:
      mail:
        smtp:
          auth: true
          starttls:
            enable: true
            required: true
```

### 2. 获取QQ邮箱授权码步骤

1. 登录QQ邮箱
2. 点击【设置】->【账户】
3. 找到【POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务】
4. 开启【POP3/SMTP服务】或【IMAP/SMTP服务】
5. 点击【生成授权码】
6. 按照提示发送短信，获取16位授权码
7. 将授权码填入配置文件的 `password` 字段

### 3. 其他常用邮箱配置

#### 163邮箱
```yaml
spring:
  mail:
    host: smtp.163.com
    port: 465
    username: your-email@163.com
    password: your-authorization-code
```

#### Gmail
```yaml
spring:
  mail:
    host: smtp.gmail.com
    port: 587
    username: your-email@gmail.com
    password: your-app-password
```

## 二、短信服务配置（支持多服务商）

### 1. 通用配置说明

系统支持多种短信服务商，通过 `provider` 配置切换：
- **aliyun**: 阿里云短信服务（已实现）
- **tencent**: 腾讯云短信服务（待实现）

### 2. 配置文件设置

在 `application.yml` 中添加以下配置：

```yaml
sms:
  # 是否启用短信服务（true: 真实发送, false: 模拟模式）
  enabled: false
  # 短信服务商（aliyun: 阿里云, tencent: 腾讯云）
  provider: aliyun
  # AccessKey ID（从服务商控制台获取）
  access-key-id: LTAI5txxxxxxxxxxxxxxxx
  # AccessKey Secret（从服务商控制台获取）
  access-key-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  # 短信签名名称（需要在服务商平台申请）
  sign-name: 红色思政学习平台
  # 验证码模板CODE（需要在服务商平台申请）
  template-code: SMS_123456789
  # 区域ID（阿里云：cn-hangzhou，腾讯云：ap-guangzhou）
  region-id: cn-hangzhou
```

### 3. 阿里云短信服务配置

#### 3.1 申请阿里云短信服务

1. 登录 [阿里云控制台](https://www.aliyun.com/)
2. 开通【短信服务】产品
3. 创建签名（需要企业资质或个人认证）
4. 创建短信模板（验证码类型）
   - 模板示例：`您的验证码为：${code}，该验证码10分钟内有效，请勿泄漏于他人！`
5. 获取 AccessKey ID 和 AccessKey Secret
   - 进入【访问控制】-> 【用户管理】
   - 创建RAM用户并授予 AliyunDysmsFullAccess 权限
   - 创建 AccessKey

#### 3.2 阿里云配置示例

```yaml
sms:
  enabled: true
  provider: aliyun
  access-key-id: LTAI5txxxxxxxxxxxxxxxx
  access-key-secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  sign-name: 红色思政学习平台
  template-code: SMS_123456789
  region-id: cn-hangzhou
```

#### 3.3 费用说明

- **验证码短信**：约 ¥0.045/条
- **通知短信**：约 ¥0.045/条

详细配置步骤请查看：`阿里云短信配置示例.md`

### 4. 腾讯云短信服务配置（待实现）

```yaml
sms:
  enabled: true
  provider: tencent
  access-key-id: your-secret-id
  access-key-secret: your-secret-key
  sign-name: 红色思政学习平台
  template-code: 123456
  region-id: ap-guangzhou
```

### 5. 开发模式说明

如果 `enabled` 设置为 `false` 或未配置 AccessKey，系统会自动使用**模拟模式**：
- ✅ 不会实际发送短信
- ✅ 在日志中输出验证码内容
- ✅ 适合开发和测试环境
- ✅ 不产生任何费用

**推荐**：开发环境始终使用 `enabled: false`

### 6. 模板参数说明

验证码模板需要包含 `${code}` 变量，系统会自动替换为6位数字验证码。

模板示例：
```
【红色思政学习平台】您的验证码为：${code}，该验证码10分钟内有效，请勿泄漏于他人！
```

### 7. 注意事项

- **AccessKey 安全**：不要将 AccessKey 提交到代码仓库
- **短信限流**：各服务商都有频率限制，注意防刷
- **验证码有效期**：建议在模板中明确说明
- **测试建议**：开发环境使用 `enabled: false` 避免浪费

## 三、Redis配置

验证码存储在Redis中，确保Redis服务已启动并配置正确：

```yaml
spring:
  redis:
    host: localhost
    port: 6379
    password: your-redis-password
    database: 0
```

## 四、API接口说明

### 1. 发送邮箱验证码

- **接口**: POST /auth/send-email-code
- **参数**: 
  ```json
  {
    "email": "user@example.com"
  }
  ```
- **返回**: 
  ```json
  {
    "code": 200,
    "message": "验证码已发送到邮箱",
    "data": true
  }
  ```

### 2. 发送手机验证码

- **接口**: POST /auth/send-sms-code
- **参数**: 
  ```json
  {
    "phone": "13800138000"
  }
  ```
- **返回**: 
  ```json
  {
    "code": 200,
    "message": "验证码已发送",
    "data": true
  }
  ```

### 3. 验证码特性

- 验证码有效期：10分钟
- 发送频率限制：60秒内只能发送一次
- 验证码长度：6位数字
- 验证码存储在Redis中，格式为：
  - 邮箱验证码：`email:code:邮箱地址`
  - 手机验证码：`sms:code:手机号`

## 五、前端注册方式

前端支持三种注册方式：

1. **用户名注册**：输入用户名、学号、密码
2. **手机号注册**：输入手机号、验证码、学号、密码
3. **邮箱注册**：输入邮箱、验证码、学号、密码

用户可以通过标签页切换注册方式。

## 六、开发环境测试

在开发环境中：

- 邮件服务：如果未配置邮箱，EmailUtils会记录错误日志
- 短信服务：SmsUtils会在日志中输出验证码，不会实际发送

建议在开发环境中配置一个测试邮箱，以便完整测试邮件发送功能。