core_wing_web/docs/API接口说明.md

# API 接口说明

## 用户相关接口

### 1. 发送验证码

**接口地址:** `POST /user/sendCode`

**请求参数:**
```json
{
  "account": "13800138000",  // 手机号或邮箱
  "type": "register"         // 验证码类型: register-注册, login-登录, reset-重置密码
}
```

**响应示例:**
```json
{
  "code": 200,
  "message": "验证码发送成功",
  "data": null
}
```

**说明:**
- 手机号格式: 1开头的11位数字
- 邮箱格式: 标准邮箱格式
- 验证码有效期: 5分钟
- 验证码长度: 6位数字

---

### 2. 用户注册

**接口地址:** `POST /user/register`

**请求参数:**
```json
{
  "username": "testuser",          // 用户名（必填）
  "password": "123456",            // 密码（必填）
  "email": "test@example.com",     // 邮箱（邮箱和手机号至少填一个）
  "telephone": "13800138000",      // 手机号（邮箱和手机号至少填一个）
  "code": "123456",                // 验证码（必填）
  "avatar": "http://..."           // 头像URL（可选）
}
```

**响应示例:**
```json
{
  "code": 200,
  "message": "注册成功",
  "data": null
}
```

**说明:**
- 用户名不能重复
- 邮箱和手机号至少填写一个
- 邮箱和手机号不能重复
- 需要先调用发送验证码接口
- 密码会自动进行 MD5 加密

---

### 3. 用户登录

**接口地址:** `POST /user/login`

**请求参数:**
```json
{
  "account": "testuser",    // 账号（用户名/邮箱/手机号）
  "password": "123456"      // 密码
}
```

**响应示例:**
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "uuid-token-string",
    "userId": 1,
    "username": "testuser"
  }
}
```

**说明:**
- account 支持用户名、邮箱、手机号三种方式登录
- 登录成功后返回 token，后续请求需要在 Header 中携带: `Authorization: token值`

---

### 4. 用户登出

**接口地址:** `POST /user/logout`

**请求头:**
```
Authorization: your-token
```

**响应示例:**
```json
{
  "code": 200,
  "message": "登出成功",
  "data": null
}
```

---

### 5. 获取当前用户信息

**接口地址:** `GET /user/info`

**请求头:**
```
Authorization: your-token
```

**响应示例:**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "username": "testuser",
    "password": null,
    "email": "test@example.com",
    "telephone": "13800138000",
    "avatar": null,
    "loginIp": "127.0.0.1",
    "status": 1,
    "createTime": "2025-01-01T12:00:00",
    "updateTime": "2025-01-01T12:00:00"
  }
}
```

---

### 6. 根据ID查询用户

**接口地址:** `GET /user/{id}`

**请求头:**
```
Authorization: your-token
```

**响应示例:**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "username": "testuser",
    "password": null,
    "email": "test@example.com",
    "telephone": "13800138000",
    "avatar": null,
    "loginIp": "127.0.0.1",
    "status": 1,
    "createTime": "2025-01-01T12:00:00",
    "updateTime": "2025-01-01T12:00:00"
  }
}
```

---

### 7. 更新用户信息

**接口地址:** `PUT /user`

**请求头:**
```
Authorization: your-token
```

**请求参数:**
```json
{
  "id": 1,
  "username": "newusername",
  "email": "newemail@example.com",
  "telephone": "13900139000",
  "avatar": "http://..."
}
```

**响应示例:**
```json
{
  "code": 200,
  "message": "更新成功",
  "data": null
}
```

**说明:**
- 不能通过此接口修改密码
- 需要修改密码请使用专门的修改密码接口

---

### 8. 修改密码

**接口地址:** `PUT /user/password`

**请求头:**
```
Authorization: your-token
```

**请求参数:**
```json
{
  "oldPassword": "123456",
  "newPassword": "654321"
}
```

**响应示例:**
```json
{
  "code": 200,
  "message": "密码修改成功",
  "data": null
}
```

---

## 配置说明

### 短信宝配置

在 `application.properties` 中配置短信宝账号信息:

```properties
# 短信宝配置
# 请前往 https://www.smsbao.com/ 注册账号并获取用户名和密码
smsbao.username=your_username
smsbao.password=your_password
```

**注册短信宝账号:**
1. 访问 https://www.smsbao.com/
2. 注册账号并充值
3. 获取用户名和密码（注意：密码是 MD5 加密后的值）
4. 配置到 application.properties 中

---

### 邮件配置

在 `application.properties` 中配置邮箱信息:

```properties
# 邮件配置（以 QQ 邮箱为例）
spring.mail.host=smtp.qq.com
spring.mail.port=587
spring.mail.username=your_email@qq.com
spring.mail.password=your_authorization_code
spring.mail.default-encoding=UTF-8
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true
```

**配置 QQ 邮箱:**
1. 登录 QQ 邮箱网页版
2. 进入【设置】->【账户】
3. 找到【POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务】
4. 开启 SMTP 服务
5. 生成授权码（注意：不是 QQ 密码！）
6. 将邮箱地址和授权码配置到 application.properties 中

**其他邮箱配置:**
- **163 邮箱**: `smtp.163.com`，端口 `465` 或 `25`
- **Gmail**: `smtp.gmail.com`，端口 `587`
- **企业邮箱**: 联系管理员获取 SMTP 服务器地址

---

## 数据库说明

### 用户表结构

```sql
CREATE TABLE `app_user` (
    `id` BIGINT(20) NOT NULL AUTO_INCREMENT COMMENT '用户ID',
    `username` VARCHAR(50) NOT NULL COMMENT '用户名',
    `password` VARCHAR(100) NOT NULL COMMENT '密码',
    `email` VARCHAR(100) DEFAULT NULL COMMENT '邮箱',
    `telephone` VARCHAR(20) DEFAULT NULL COMMENT '手机号',
    `avatar` VARCHAR(255) DEFAULT NULL COMMENT '头像URL',
    `login_ip` VARCHAR(50) DEFAULT NULL COMMENT '最后登录IP',
    `status` TINYINT(1) DEFAULT 1 COMMENT '状态：0-禁用 1-启用',
    `create_time` DATETIME DEFAULT NULL COMMENT '创建时间',
    `update_time` DATETIME DEFAULT NULL COMMENT '更新时间',
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_username` (`username`),
    UNIQUE KEY `uk_email` (`email`),
    UNIQUE KEY `uk_telephone` (`telephone`),
    KEY `idx_create_time` (`create_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='应用用户表';
```

---

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 500 | 失败 |

---

## 开发说明

### 验证码存储

- 验证码存储在 Redis 中
- Key 格式: `verify_code:{type}:{account}`
- 有效期: 5分钟
- 验证成功后自动删除

### 密码加密

- 使用 MD5 加密
- 前端传输明文密码，后端自动加密存储

### 登录认证

- 使用 Sa-Token 进行身份认证
- Token 有效期: 30天
- 除登录、注册、发送验证码接口外，其他接口都需要认证

### 验证码发送

- **手机验证码**: 通过短信宝自动发送短信
- **邮件验证码**: 通过 Spring Mail 自动发送 HTML 格式的精美邮件
- 验证码为 6 位随机数字
- 邮件模板包含品牌样式，提升用户体验