Files
campus-activity-system/server/docs/API接口设计.md

25 KiB
Raw Permalink Blame History

校园活动系统 - 后端 API 接口文档

基本信息

  • 基础路径: /api/v1
  • 认证方式: JWT Token (Bearer Token)
  • 响应格式: JSON

统一响应格式

所有接口返回统一的响应格式:

{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": 1736620800000
}

状态码说明

状态码 说明
200 成功
400 请求参数错误
401 未认证或Token已过期
403 无权限访问
404 资源不存在
409 业务冲突
500 服务器内部错误

业务错误码

错误码 说明
1001 用户不存在
1002 用户已存在
1003 密码错误
1004 用户名或密码错误
1005 学号已存在
2001 活动不存在
2002 活动已开始,无法取消报名
2003 活动时间冲突
2004 活动报名人数已满
3001 报名记录不存在
3002 您已报名该活动
3003 您未报名该活动
4001 签到失败
4002 已签到
4003 签到时间已过期
5001 您已评价该活动
5002 评价记录不存在
5003 您未参加该活动,无法评价

一、认证模块 (/api/v1/auth)

1.1 用户注册

接口地址: POST /api/v1/auth/register

请求权限: 无需认证

请求参数:

参数名 类型 必填 说明 验证规则
username String 用户名 3-50个字符
password String 密码 6-20个字符
name String 姓名 最多50个字符
studentId String 学号 10-20位数字
email String 邮箱 邮箱格式
phone String 手机号 11位手机号

请求示例:

{
  "username": "student001",
  "password": "123456",
  "name": "张三",
  "studentId": "2021000001",
  "email": "zhangsan@example.com",
  "phone": "13800138000"
}

响应示例:

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

1.2 用户登录

接口地址: POST /api/v1/auth/login

请求权限: 无需认证

请求参数:

参数名 类型 必填 说明
username String 用户名
password String 密码

请求示例:

{
  "username": "student001",
  "password": "123456"
}

响应示例:

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600,
    "tokenType": "Bearer",
    "userInfo": {
      "id": 1,
      "username": "student001",
      "name": "张三",
      "role": 0,
      "avatar": null
    }
  },
  "timestamp": 1736620800000
}

1.3 刷新Token

接口地址: POST /api/v1/auth/refresh

请求权限: 无需认证

请求参数:

参数名 类型 必填 说明
refreshToken String 刷新Token

请求示例:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  },
  "timestamp": 1736620800000
}

1.4 获取当前用户信息

接口地址: GET /api/v1/auth/me

请求权限: 需要认证

请求头:

Authorization: Bearer {accessToken}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "username": "student001",
    "password": "$2a$10$...",
    "name": "张三",
    "studentId": "2021000001",
    "email": "zhangsan@example.com",
    "phone": "13800138000",
    "avatar": null,
    "role": 0,
    "status": 1,
    "createdAt": "2026-01-01T00:00:00",
    "updatedAt": "2026-01-01T00:00:00"
  },
  "timestamp": 1736620800000
}

1.5 修改密码

接口地址: PUT /api/v1/auth/password

请求权限: 需要认证

请求参数:

参数名 类型 必填 说明 验证规则
oldPassword String 旧密码 不能为空
newPassword String 新密码 6-20个字符

请求示例:

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

响应示例:

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

二、活动模块 (/api/v1/activities)

2.1 获取活动列表

接口地址: GET /api/v1/activities

请求权限: 无需认证

请求参数:

参数名 类型 必填 说明 默认值
current Long 当前页码 1
size Long 每页数量 10
status Integer 活动状态 -
keyword String 关键词搜索 -
category String 活动分类 -
startDate LocalDateTime 开始时间(yyyy-MM-dd HH:mm:ss) -
endDate LocalDateTime 结束时间(yyyy-MM-dd HH:mm:ss) -

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "title": "校园音乐节",
        "description": "一年一度的校园音乐盛会",
        "coverImage": "https://example.com/cover.jpg",
        "startTime": "2026-01-15T19:00:00",
        "endTime": "2026-01-15T22:00:00",
        "registrationDeadline": "2026-01-14T18:00:00",
        "location": "大礼堂",
        "maxParticipants": 500,
        "currentParticipants": 300,
        "status": 1,
        "category": "文艺活动",
        "adminId": 1,
        "adminName": "管理员",
        "averageRating": 4.5,
        "reviewCount": 20,
        "isRegistered": false,
        "createdAt": "2026-01-01T00:00:00"
      }
    ],
    "total": 1,
    "pages": 1,
    "current": 1,
    "size": 10
  },
  "timestamp": 1736620800000
}

2.2 获取活动详情

接口地址: GET /api/v1/activities/{id}

请求权限: 无需认证

路径参数:

参数名 类型 必填 说明
id Long 活动ID

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "title": "校园音乐节",
    "description": "一年一度的校园音乐盛会",
    "coverImage": "https://example.com/cover.jpg",
    "startTime": "2026-01-15T19:00:00",
    "endTime": "2026-01-15T22:00:00",
    "registrationDeadline": "2026-01-14T18:00:00",
    "location": "大礼堂",
    "maxParticipants": 500,
    "currentParticipants": 300,
    "status": 1,
    "category": "文艺活动",
    "adminId": 1,
    "adminName": "管理员",
    "averageRating": 4.5,
    "reviewCount": 20,
    "isRegistered": false,
    "createdAt": "2026-01-01T00:00:00"
  },
  "timestamp": 1736620800000
}

2.3 创建活动(管理员)

接口地址: POST /api/v1/activities

请求权限: 管理员 (ADMIN)

请求参数:

参数名 类型 必填 说明 验证规则
title String 活动名称 最多100个字符
description String 活动简介 最多2000个字符
coverImage String 封面图片URL -
startTime LocalDateTime 开始时间 必须是未来时间
endTime LocalDateTime 结束时间 -
registrationDeadline LocalDateTime 报名截止时间 -
location String 活动地点 最多200个字符
maxParticipants Integer 报名人数上限 1-10000
category String 活动分类 最多50个字符

请求示例:

{
  "title": "校园音乐节",
  "description": "一年一度的校园音乐盛会",
  "coverImage": "https://example.com/cover.jpg",
  "startTime": "2026-01-15T19:00:00",
  "endTime": "2026-01-15T22:00:00",
  "registrationDeadline": "2026-01-14T18:00:00",
  "location": "大礼堂",
  "maxParticipants": 500,
  "category": "文艺活动"
}

响应示例:

{
  "code": 200,
  "message": "创建成功",
  "data": 1,
  "timestamp": 1736620800000
}

2.4 更新活动(管理员)

接口地址: PUT /api/v1/activities/{id}

请求权限: 管理员 (ADMIN)

路径参数:

参数名 类型 必填 说明
id Long 活动ID

请求参数:

参数名 类型 必填 说明 验证规则
title String 活动名称 最多100个字符
description String 活动简介 最多2000个字符
coverImage String 封面图片URL -
startTime LocalDateTime 开始时间 -
endTime LocalDateTime 结束时间 -
registrationDeadline LocalDateTime 报名截止时间 -
location String 活动地点 最多200个字符
maxParticipants Integer 报名人数上限 1-10000
status Integer 活动状态 -
category String 活动分类 最多50个字符

响应示例:

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

2.5 删除活动(管理员)

接口地址: DELETE /api/v1/activities/{id}

请求权限: 管理员 (ADMIN)

路径参数:

参数名 类型 必填 说明
id Long 活动ID

响应示例:

{
  "code": 200,
  "message": "删除成功",
  "data": null,
  "timestamp": 1736620800000
}

2.6 获取日历视图活动

接口地址: GET /api/v1/activities/calendar

请求权限: 无需认证

请求参数:

参数名 类型 必填 说明
year Integer 年份
month Integer 月份

响应示例:

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "title": "校园音乐节",
      "description": "一年一度的校园音乐盛会",
      "coverImage": "https://example.com/cover.jpg",
      "startTime": "2026-01-15T19:00:00",
      "endTime": "2026-01-15T22:00:00",
      "registrationDeadline": "2026-01-14T18:00:00",
      "location": "大礼堂",
      "maxParticipants": 500,
      "currentParticipants": 300,
      "status": 1,
      "category": "文艺活动",
      "adminId": 1,
      "adminName": "管理员",
      "averageRating": 4.5,
      "reviewCount": 20,
      "isRegistered": false,
      "createdAt": "2026-01-01T00:00:00"
    }
  ],
  "timestamp": 1736620800000
}

2.7 检测时间冲突(管理员)

接口地址: POST /api/v1/activities/check-conflict

请求权限: 管理员 (ADMIN)

请求参数:

参数名 类型 必填 说明
startTime LocalDateTime 开始时间
endTime LocalDateTime 结束时间
excludeActivityId Long 排除的活动ID更新时使用

请求示例:

{
  "startTime": "2026-01-15T19:00:00",
  "endTime": "2026-01-15T22:00:00",
  "excludeActivityId": 1
}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "hasConflict": true,
    "conflictActivities": [
      {
        "id": 2,
        "title": "校园篮球赛",
        "startTime": "2026-01-15T18:00:00",
        "endTime": "2026-01-15T20:00:00"
      }
    ]
  },
  "timestamp": 1736620800000
}

三、报名模块 (/api/v1/registrations)

3.1 报名活动

接口地址: POST /api/v1/registrations

请求权限: 需要认证

请求参数:

参数名 类型 必填 说明
activityId Long 活动ID

请求示例:

{
  "activityId": 1
}

响应示例:

{
  "code": 200,
  "message": "报名成功",
  "data": {
    "id": 1,
    "activityId": 1,
    "activityTitle": "校园音乐节",
    "activityStartTime": "2026-01-15T19:00:00",
    "activityEndTime": "2026-01-15T22:00:00",
    "activityLocation": "大礼堂",
    "ticketCode": "TICKET202601150001",
    "ticketPdfUrl": "https://example.com/tickets/TICKET202601150001.pdf",
    "status": 1,
    "createdAt": "2026-01-10T10:00:00",
    "canceledAt": null
  },
  "timestamp": 1736620800000
}

3.2 取消报名

接口地址: DELETE /api/v1/registrations/{id}

请求权限: 需要认证

路径参数:

参数名 类型 必填 说明
id Long 报名记录ID

响应示例:

{
  "code": 200,
  "message": "取消成功",
  "data": null,
  "timestamp": 1736620800000
}

3.3 获取我的报名列表

接口地址: GET /api/v1/registrations/my

请求权限: 需要认证

请求参数:

参数名 类型 必填 说明 默认值
current Long 当前页码 1
size Long 每页数量 10
status Integer 报名状态 -

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "activityId": 1,
        "activityTitle": "校园音乐节",
        "activityStartTime": "2026-01-15T19:00:00",
        "activityEndTime": "2026-01-15T22:00:00",
        "activityLocation": "大礼堂",
        "ticketCode": "TICKET202601150001",
        "ticketPdfUrl": "https://example.com/tickets/TICKET202601150001.pdf",
        "status": 1,
        "createdAt": "2026-01-10T10:00:00",
        "canceledAt": null
      }
    ],
    "total": 1,
    "pages": 1,
    "current": 1,
    "size": 10
  },
  "timestamp": 1736620800000
}

3.4 获取活动报名列表(管理员)

接口地址: GET /api/v1/registrations/activity/{activityId}

请求权限: 管理员 (ADMIN)

路径参数:

参数名 类型 必填 说明
activityId Long 活动ID

请求参数:

参数名 类型 必填 说明 默认值
current Long 当前页码 1
size Long 每页数量 10

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "activityId": 1,
        "activityTitle": "校园音乐节",
        "activityStartTime": "2026-01-15T19:00:00",
        "activityEndTime": "2026-01-15T22:00:00",
        "activityLocation": "大礼堂",
        "ticketCode": "TICKET202601150001",
        "ticketPdfUrl": "https://example.com/tickets/TICKET202601150001.pdf",
        "status": 1,
        "createdAt": "2026-01-10T10:00:00",
        "canceledAt": null
      }
    ],
    "total": 1,
    "pages": 1,
    "current": 1,
    "size": 10
  },
  "timestamp": 1736620800000
}

3.5 下载电子票PDF

接口地址: GET /api/v1/registrations/{id}/ticket

请求权限: 需要认证

路径参数:

参数名 类型 必填 说明
id Long 报名记录ID

响应: PDF文件流

响应头:

Content-Disposition: attachment; filename=ticket.pdf
Content-Type: application/pdf

四、签到模块 (/api/v1/checkin)

4.1 生成签到二维码(管理员)

接口地址: POST /api/v1/checkin/qrcode/{activityId}

请求权限: 管理员 (ADMIN)

路径参数:

参数名 类型 必填 说明
activityId Long 活动ID

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "qrCodeUrl": "https://example.com/qrcode/ACTIVITY1.png",
    "qrCodeContent": "activity:1:2026-01-15T19:00:00",
    "expiresAt": "2026-01-15T23:00:00"
  },
  "timestamp": 1736620800000
}

4.2 学生扫码签到

接口地址: POST /api/v1/checkin/scan

请求权限: 需要认证

请求参数:

参数名 类型 必填 说明
qrCodeContent String 二维码内容

请求示例:

{
  "qrCodeContent": "activity:1:2026-01-15T19:00:00"
}

响应示例:

{
  "code": 200,
  "message": "签到成功",
  "data": {
    "id": 1,
    "userId": 1,
    "userName": "张三",
    "studentId": "2021000001",
    "activityId": 1,
    "checkInTime": "2026-01-15T19:30:00",
    "checkInMethod": 1
  },
  "timestamp": 1736620800000
}

4.3 管理员扫学生票签到

接口地址: POST /api/v1/checkin/ticket

请求权限: 管理员 (ADMIN)

请求参数:

参数名 类型 必填 说明
activityId Long 活动ID
ticketCode String 电子票号

请求示例:

{
  "activityId": 1,
  "ticketCode": "TICKET202601150001"
}

响应示例:

{
  "code": 200,
  "message": "签到成功",
  "data": {
    "id": 1,
    "userId": 1,
    "userName": "张三",
    "studentId": "2021000001",
    "activityId": 1,
    "checkInTime": "2026-01-15T19:30:00",
    "checkInMethod": 2
  },
  "timestamp": 1736620800000
}

4.4 获取活动签到列表(管理员)

接口地址: GET /api/v1/checkin/activity/{activityId}

请求权限: 管理员 (ADMIN)

路径参数:

参数名 类型 必填 说明
activityId Long 活动ID

请求参数:

参数名 类型 必填 说明 默认值
current Long 当前页码 1
size Long 每页数量 10

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "userId": 1,
        "userName": "张三",
        "studentId": "2021000001",
        "activityId": 1,
        "checkInTime": "2026-01-15T19:30:00",
        "checkInMethod": 1
      }
    ],
    "total": 1,
    "pages": 1,
    "current": 1,
    "size": 10
  },
  "timestamp": 1736620800000
}

五、评价模块 (/api/v1/reviews)

5.1 提交评价

接口地址: POST /api/v1/reviews

请求权限: 需要认证

请求参数:

参数名 类型 必填 说明 验证规则
activityId Long 活动ID -
rating Integer 评分 1-5分
content String 评论内容 最多500个字符

请求示例:

{
  "activityId": 1,
  "rating": 5,
  "content": "非常精彩的活动!"
}

响应示例:

{
  "code": 200,
  "message": "评价成功",
  "data": {
    "id": 1,
    "userId": 1,
    "userName": "张三",
    "userAvatar": null,
    "activityId": 1,
    "activityTitle": "校园音乐节",
    "rating": 5,
    "content": "非常精彩的活动!",
    "createdAt": "2026-01-16T10:00:00"
  },
  "timestamp": 1736620800000
}

5.2 获取活动评价列表

接口地址: GET /api/v1/reviews/activity/{activityId}

请求权限: 无需认证

路径参数:

参数名 类型 必填 说明
activityId Long 活动ID

请求参数:

参数名 类型 必填 说明 默认值
current Long 当前页码 1
size Long 每页数量 10

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "userId": 1,
        "userName": "张三",
        "userAvatar": null,
        "activityId": 1,
        "activityTitle": "校园音乐节",
        "rating": 5,
        "content": "非常精彩的活动!",
        "createdAt": "2026-01-16T10:00:00"
      }
    ],
    "total": 1,
    "pages": 1,
    "current": 1,
    "size": 10
  },
  "timestamp": 1736620800000
}

5.3 获取我的评价列表

接口地址: GET /api/v1/reviews/my

请求权限: 需要认证

请求参数:

参数名 类型 必填 说明 默认值
current Long 当前页码 1
size Long 每页数量 10

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "userId": 1,
        "userName": "张三",
        "userAvatar": null,
        "activityId": 1,
        "activityTitle": "校园音乐节",
        "rating": 5,
        "content": "非常精彩的活动!",
        "createdAt": "2026-01-16T10:00:00"
      }
    ],
    "total": 1,
    "pages": 1,
    "current": 1,
    "size": 10
  },
  "timestamp": 1736620800000
}

六、统计模块 (/api/v1/statistics)

6.1 获取活动统计数据(管理员)

接口地址: GET /api/v1/statistics/activity/{activityId}

请求权限: 管理员 (ADMIN)

路径参数:

参数名 类型 必填 说明
activityId Long 活动ID

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "activityId": 1,
    "activityTitle": "校园音乐节",
    "registeredCount": 300,
    "checkedInCount": 250,
    "checkInRate": 0.8333,
    "reviewCount": 20,
    "averageRating": 4.5,
    "ratingDistribution": {
      "1": 0,
      "2": 1,
      "3": 3,
      "4": 6,
      "5": 10
    }
  },
  "timestamp": 1736620800000
}

6.2 导出活动数据(管理员)

接口地址: GET /api/v1/statistics/activity/{activityId}/export

请求权限: 管理员 (ADMIN)

路径参数:

参数名 类型 必填 说明
activityId Long 活动ID

请求参数:

参数名 类型 必填 说明 默认值
format String 导出格式 excel

响应: 文件流 (Excel或PDF)


6.3 获取总体统计(管理员)

接口地址: GET /api/v1/statistics/overview

请求权限: 管理员 (ADMIN)

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "totalActivities": 50,
    "totalRegistrations": 1000,
    "totalCheckIns": 800,
    "totalReviews": 500,
    "averageRating": 4.3,
    "monthlyStats": [
      {
        "month": "2026-01",
        "activityCount": 10,
        "registrationCount": 200
      },
      {
        "month": "2026-02",
        "activityCount": 15,
        "registrationCount": 300
      }
    ]
  },
  "timestamp": 1736620800000
}

附录:数据模型说明

用户角色 (role)

说明
0 学生
1 管理员

用户状态 (status)

说明
0 禁用
1 正常

活动状态 (status)

说明
0 草稿
1 已发布
2 进行中
3 已结束
4 已取消

报名状态 (status)

说明
0 已取消
1 已报名

签到方式 (checkInMethod)

说明
1 学生扫码签到
2 管理员扫票签到

接口权限汇总

接口路径 方法 学生 管理员 说明
/auth/register POST 公开
/auth/login POST 公开
/auth/refresh POST 公开
/auth/me GET 需要认证
/auth/password PUT 需要认证
/activities GET 公开
/activities/{id} GET 公开
/activities POST 仅管理员
/activities/{id} PUT 仅管理员
/activities/{id} DELETE 仅管理员
/activities/calendar GET 公开
/activities/check-conflict POST 仅管理员
/registrations POST 需要认证
/registrations/{id} DELETE 需要认证
/registrations/my GET 需要认证
/registrations/activity/{id} GET 仅管理员
/registrations/{id}/ticket GET 需要认证
/checkin/qrcode/{id} POST 仅管理员
/checkin/scan POST 需要认证
/checkin/ticket POST 仅管理员
/checkin/activity/{id} GET 仅管理员
/reviews POST 需要认证
/reviews/activity/{id} GET 公开
/reviews/my GET 需要认证
/statistics/activity/{id} GET 仅管理员
/statistics/activity/{id}/export GET 仅管理员
/statistics/overview GET 仅管理员