shiro/campus-activity-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
12568cb00ea542d6a30e860977941d9afa9882f2
campus-activity-system/web/docs/API接口设计.md
Shiro 12568cb00e release: 提交版修改
2026-01-19 23:15:20 +08:00

25 KiB
Raw 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 ✗ ✓ 仅管理员
Reference in New Issue View Git Blame Copy Permalink