core_wing_web/docs/API接口说明.md

API 接口说明

用户相关接

1. 发送验证码

接口地址: POST /user/sendCode

请求参数:

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

响应示例:

{
  "code": 200,
  "message": "验证码发送成功",
  "data": null
}

说明:

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

---

2. 用户注册

接口地址: POST /user/register

请求参数:

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

响应示例:

{
  "code": 200,
  "message": "注册成功",
  "data": null
}

说明:

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

---

3. 用户登录

接口地址: POST /user/login

请求参数:

{
  "account": "testuser",    // 账号（用户名/邮箱/手机号）
  "password": "123456"      // 密码
}

响应示例:

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "uuid-token-string",
    "userId": 1,
    "username": "testuser"
  }
}

说明:

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

---

4. 用户登出

接口地址: POST /user/logout

请求头:

Authorization: your-token

响应示例:

{
  "code": 200,
  "message": "登出成功",
  "data": null
}

---

5. 获取当前用户信息

接口地址: GET /user/info

请求头:

Authorization: your-token

响应示例:

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

响应示例:

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

请求参数:

{
  "id": 1,
  "username": "newusername",
  "email": "newemail@example.com",
  "telephone": "13900139000",
  "avatar": "http://..."
}

响应示例:

{
  "code": 200,
  "message": "更新成功",
  "data": null
}

说明:

• 不能通过此接口修改密码
• 需要修改密码请使用专门的修改密码接口

---

8. 修改密码

接口地址: PUT /user/password

请求头:

Authorization: your-token

请求参数:

{
  "oldPassword": "123456",
  "newPassword": "654321"
}

响应示例:

{
  "code": 200,
  "message": "密码修改成功",
  "data": null
}

---

配置说明

短信宝配置

在 application.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 中配置邮箱信息:

# 邮件配置（以 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 服务器地址

---

数据库说明

用户表结构

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 位随机数字
• 邮件模板包含品牌样式，提升用户体验