unilife/UniLife开发文档.md

一、API规范

1.1 基础信息

• 基础URL: http://localhost:8080(本地测试)

• 接口格式: RESTful API

• 数据格式: JSON

• 字符编码: UTF-8

• 认证方式: JWT (JSON Web Token)

• GET: 获取资源

• POST: 创建资源

• PUT: 更新资源（全量更新）

• PATCH: 部分更新资源

• DELETE: 删除资源

1.2 响应规范

响应状态码

• 200: 成功
• 400: 请求参数错误
• 401: 未授权
• 403: 禁止访问
• 404: 资源不存在
• 500: 服务器内部错误

后端相应格式

成功响应:

{
  "code": 200,  // 200表示成功
  "message": "success",
  "data": {   // 实际返回数据
    // ...
  }
}

错误相应:

{
  "code": 400,  
  "message": "参数错误",  // 错误信息
  "data": null  
}

二、 数据库设计

2.1用户表设计 (users)

字段名	类型	约束	说明
id	BIGINT	PRIMARY KEY, AUTO_INCREMENT	用户ID
username	VARCHAR(50)	NOT NULL, UNIQUE	用户名
email	VARCHAR(100)	NOT NULL, UNIQUE	邮箱地址（学校邮箱）
password	VARCHAR(255)	NOT NULL	密码（加密存储）
nickname	VARCHAR(50)	NOT NULL	昵称
avatar	VARCHAR(255)		头像URL
bio	TEXT		个人简介
gender	TINYINT		性别（0-未知, 1-男, 2-女）
student_id	VARCHAR(20)	UNIQUE	学号
department	VARCHAR(100)		院系
major	VARCHAR(100)		专业
grade	VARCHAR(20)		年级
points	INT	DEFAULT 0	积分
role	TINYINT	DEFAULT 0	角色（0-普通用户, 1-版主, 2-管理员）
status	TINYINT	DEFAULT 1	状态（0-禁用, 1-启用）
is_verified	TINYINT	DEFAULT 0	是否验证（0-未验证, 1-已验证）
login_ip	VARCHAR(50)		最近登录IP
login_time	DATETIME		最近登录时间
created_at	DATETIME	DEFAULT CURRENT_TIMESTAMP	创建时间
updated_at	DATETIME	DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP	更新时间

建表语句

CREATE TABLE `users` (
  `id` BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '用户ID',
  `username` VARCHAR(50) NOT NULL UNIQUE COMMENT '用户名',
  `email` VARCHAR(100) NOT NULL UNIQUE COMMENT '邮箱地址（学校邮箱）',
  `password` VARCHAR(255) NOT NULL COMMENT '密码（加密存储）',
  `nickname` VARCHAR(50) NOT NULL COMMENT '昵称',
  `avatar` VARCHAR(255) DEFAULT NULL COMMENT '头像URL',
  `bio` TEXT DEFAULT NULL COMMENT '个人简介',
  `gender` TINYINT DEFAULT 0 COMMENT '性别（0-未知, 1-男, 2-女）',
  `student_id` VARCHAR(20) UNIQUE DEFAULT NULL COMMENT '学号',
  `department` VARCHAR(100) DEFAULT NULL COMMENT '院系',
  `major` VARCHAR(100) DEFAULT NULL COMMENT '专业',
  `grade` VARCHAR(20) DEFAULT NULL COMMENT '年级',
  `points` INT DEFAULT 0 COMMENT '积分',
  `role` TINYINT DEFAULT 0 COMMENT '角色（0-普通用户, 1-版主, 2-管理员）',
  `status` TINYINT DEFAULT 1 COMMENT '状态（0-禁用, 1-启用）',
  `is_verified` TINYINT DEFAULT 0 COMMENT '是否验证（0-未验证, 1-已验证）',
  `login_ip` VARCHAR(50) DEFAULT NULL COMMENT '最近登录IP',
  `login_time` DATETIME DEFAULT NULL COMMENT '最近登录时间',
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  INDEX `idx_email` (`email`),
  INDEX `idx_username` (`username`),
  INDEX `idx_student_id` (`student_id`),
  INDEX `idx_role` (`role`),
  INDEX `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户表';

三、Api功能实现

3.1用户认证模块

3.1.1 用户注册

• URL: /users/register

• 方法: POST

• 描述: 创建新用户账号

  请求参数：

  {
    "username": "student123",
    "email": "student@school.edu",
    "password": "Secure@Password123",
    "nickname": "学生昵称",
    "studentId": "20220101001",
    "department": "计算机学院",
    "major": "软件工程",
    "grade": "2023级"
  }
  

  响应结果：

  {
    "code": 200,
    "message": "注册成功",
    "data": {
      "userId": 12345,
      "username": "student123",
      "nickname": "学生昵称"
    }
  }
  

3.1.2 用户密码登录

• URL: /users/login
• 方法: POST
• 描述: 用户登录

请求参数：

{
  "username": "student123",  // 用户名或邮箱
  "password": "Secure@Password123"
}

响应结果：

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userInfo": {
      "userId": 12345,
      "username": "student123",
      "nickname": "学生昵称",
      "avatar": "https://example.com/avatar.jpg",
      "role": 0,
      "isVerified": true,
      "status": 1
    }
  }
}

3.1.3 获取邮箱验证码

• URL: /users/code

• 方法: POST

• 描述: 向指定邮箱发送登录验证码

  请求参数

  {
    "email": "student@school.edu"
  }
  

  响应结果:

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

3.1.4 邮箱验证码登录

• URL: /users/login/code
• 方法: POST
• 描述: 使用邮箱和验证码进行登录

请求参数

{
  "email": "student@school.edu",
  "code": "123456"
}

成功响应:

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userInfo": {
      "userId": 12345,
      "username": "student123",
      "nickname": "学生昵称",
      "avatar": "https://example.com/avatar.jpg",
      "role": 0
    }
  }
}