社团管理API文档

📋 概述

本文档描述社团管理系统的后端API接口，包含社团信息管理、社团成员管理、社团报名大厅三个核心模块。

模块划分

社团信息管理: 管理员端社团基本信息的CRUD操作
社团成员管理: 社团成员的增删改查、角色管理
社团报名大厅: 学生端社团展示、报名、退出功能

技术规范

权限码格式: stgl:功能:操作 三段式格式
响应格式: 统一使用R类型（非分页）和TableDataInfo（分页）
认证方式: Bearer Token，包含clientid、referer等必需Header
参数验证: 使用Bean Validation进行参数校验

🔢 成员数量统计规则

memberCount字段: 所有社团信息查询接口都会返回当前成员数量
统计范围: 包含所有角色类型的成员（社长、副社长、普通成员等）
统计条件:
- member_type = 1 (社团成员，非志愿者)
- status = 1 (正常状态，非退出状态)
- deleted = 0 (未删除)
注意事项:
- 成员数量为动态计算，实时反映当前状态
- 社长和副社长创建时会自动添加到成员表中，计入总数
- 列表查询和详情查询使用相同的统计逻辑

🏢 社团信息管理模块

1.1 查询社团信息列表

接口路径: GET /stgl/club/list
权限码: stgl:club:list
功能说明: 分页查询社团信息列表，支持按社团类型、名称、状态等条件筛选

请求参数

参数名	类型	必填	说明
clubName	String	否	社团名称（模糊查询）
clubType	String	否	社团类型
status	Integer	否	状态（1-正常 0-停用）
pageNum	Integer	否	页码，默认1
pageSize	Integer	否	每页数量，默认10

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "rows": [
    {
      "id": 1001,
      "clubName": "计算机协会",
      "clubType": "学术科技类",
      "establishDate": "2023-09-01",
      "description": "致力于计算机技术交流和学习",
      "presidentName": "张三",
      "presidentStudentNo": "20230001",
      "memberLimit": 100,
      "memberCount": 85,
      "status": 1,
      "createTime": "2023-09-01 10:00:00"
    }
  ],
  "total": 1
}

1.2 获取社团详细信息

接口路径: GET /stgl/club/{id}
权限码: stgl:club:query
功能说明: 根据ID查询社团详细信息

路径参数

参数名	类型	必填	说明
id	Long	是	社团ID

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1001,
    "clubName": "计算机协会",
    "clubType": "学术科技类",
    "establishDate": "2023-09-01",
    "description": "致力于计算机技术交流和学习",
    "email": "cs@school.edu.cn",
    "phone": "13800138001",
    "logoUrl": "/upload/logo/cs-logo.png",
    "presidentName": "张三",
    "presidentStudentNo": "20230001",
    "presidentDept": "计算机学院",
    "presidentMajor": "计算机科学与技术",
    "presidentClass": "2023级1班",
    "presidentPhone": "13800138001",
    "vicePresidentName": "李四",
    "vicePresidentStudentNo": "20230002",
    "advisorName": "王教授",
    "advisorDept": "计算机学院",
    "memberLimit": 100,
    "departments": "技术部、宣传部、组织部",
    "recruitCycle": "每学期开学",
    "recruitTime": "9月、3月",
    "activityFrequency": "每周一次技术交流",
    "fundingSources": "学校拨款,会员费",
    "charterUrl": "/upload/charter/cs-charter.pdf",
    "status": 1,
    "memberCount": 85,
    "createTime": "2023-09-01 10:00:00",
    "updateTime": "2023-12-01 15:30:00"
  }
}

1.3 新增社团信息

接口路径: POST /stgl/club
权限码: stgl:club:add
功能说明: 新增社团信息

请求体参数

{
  "clubName": "计算机协会",
  "clubType": "学术科技类",
  "establishDate": "2023-09-01",
  "description": "致力于计算机技术交流和学习",
  "email": "cs@school.edu.cn",
  "phone": "13800138001",
  "logoUrl": "/upload/logo/cs-logo.png",
  "presidentName": "张三",
  "presidentStudentNo": "20230001",
  "presidentDept": "计算机学院",
  "presidentMajor": "计算机科学与技术",
  "presidentClass": "2023级1班",
  "presidentPhone": "13800138001",
  "vicePresidentName": "李四",
  "vicePresidentStudentNo": "20230002",
  "advisorName": "王教授",
  "advisorDept": "计算机学院",
  "memberLimit": 100,
  "departments": "技术部、宣传部、组织部",
  "recruitCycle": "每学期开学",
  "recruitTime": "9月、3月",
  "activityFrequency": "每周一次技术交流",
  "fundingSources": "学校拨款,会员费",
  "charterUrl": "/upload/charter/cs-charter.pdf",
  "status": 1,
  "remark": "备注信息"
}

响应示例

{
  "code": 200,
  "msg": "操作成功"
}

1.4 修改社团信息

接口路径: PUT /stgl/club
权限码: stgl:club:edit
功能说明: 修改社团信息

请求体参数

{
  "id": 1001,
  "clubName": "计算机协会",
  "clubType": "学术科技类",
  "description": "更新后的社团简介",
  "memberLimit": 120,
  "status": 1
}

1.5 删除社团信息

接口路径: DELETE /stgl/club/{ids}
权限码: stgl:club:remove
功能说明: 批量删除社团信息（逻辑删除）

路径参数

参数名	类型	必填	说明
ids	String	是	社团ID列表，逗号分隔

1.6 导出社团信息

接口路径: POST /stgl/club/export
权限码: stgl:club:export
功能说明: 导出社团信息Excel文件

1.7 查询可用社团选项

接口路径: GET /stgl/club/options
权限码: stgl:club:query
功能说明: 查询状态正常的社团选项，用于下拉框等

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1001,
      "clubName": "计算机协会",
      "clubType": "学术科技类"
    },
    {
      "id": 1002,
      "clubName": "文学社",
      "clubType": "文化艺术类"
    }
  ]
}

1.8 根据类型查询社团

接口路径: GET /stgl/club/byType/{clubType}
权限码: stgl:club:query
功能说明: 根据社团类型查询社团列表

1.9 查询我管理的社团

接口路径: GET /stgl/club/myClubs
权限码: stgl:club:query
功能说明: 查询当前用户作为社长或副社长的社团列表

1.10 启用/禁用社团

接口路径: PUT /stgl/club/changeStatus
权限码: stgl:club:edit
功能说明: 启用或禁用社团

请求体参数

{
  "id": 1001,
  "status": 0
}

👥 社团成员管理模块

2.1 查询社团成员列表

接口路径: GET /stgl/member/list
权限码: stgl:clubmember:list
功能说明: 分页查询社团成员列表，包含用户基本信息

请求参数

参数名	类型	必填	说明
memberType	Integer	否	成员类型（1-社团成员 2-志愿者）
relationId	Long	否	关联ID（社团ID或志愿者队伍ID）
studentNo	String	否	学号（模糊查询）
studentName	String	否	学生姓名（模糊查询）
roleType	Integer	否	角色类型（1-社长 2-副社长 3-成员）
status	Integer	否	状态（1-正常 0-退出）
pageNum	Integer	否	页码，默认1
pageSize	Integer	否	每页数量，默认10

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "rows": [
    {
      "id": 2001,
      "memberType": 1,
      "relationId": 1001,
      "userId": 100001,
      "studentNo": "20230001",
      "studentName": "张三",
      "roleType": 1,
      "joinTime": "2023-09-01 10:00:00",
      "status": 1,
      "nickName": "张同学",
      "phonenumber": "13800138001",
      "userEmail": "zhangsan@school.edu.cn",
      "memberTypeName": "社团成员",
      "roleTypeName": "社长",
      "statusName": "正常",
      "relationName": "计算机协会"
    }
  ],
  "total": 1
}

2.2 获取成员详细信息

接口路径: GET /stgl/member/{id}
权限码: stgl:clubmember:query
功能说明: 根据ID查询成员详细信息

2.3 新增社团成员

接口路径: POST /stgl/member
权限码: stgl:clubmember:add
功能说明: 新增社团成员

请求体参数

{
  "memberType": 1,
  "relationId": 1001,
  "userId": 100002,
  "studentNo": "20230002",
  "studentName": "李四",
  "roleType": 3,
  "status": 1,
  "remark": "备注信息"
}

2.4 修改成员信息

接口路径: PUT /stgl/member
权限码: stgl:clubmember:edit
功能说明: 修改成员信息

2.5 删除成员

接口路径: DELETE /stgl/member/{ids}
权限码: stgl:clubmember:remove
功能说明: 批量删除成员（逻辑删除）

2.6 导出成员信息

接口路径: POST /stgl/member/export
权限码: stgl:clubmember:export
功能说明: 导出成员信息Excel文件

2.7 根据社团查询成员

接口路径: GET /stgl/member/byClub/{clubId}
权限码: stgl:clubmember:query
功能说明: 根据社团ID查询成员列表

2.8 根据用户查询参与的社团

接口路径: GET /stgl/member/byUser/{userId}
权限码: stgl:clubmember:query
功能说明: 根据用户ID查询参与的社团列表

2.9 检查成员是否存在

接口路径: GET /stgl/member/checkExists
权限码: stgl:clubmember:query
功能说明: 检查用户是否已是某个社团的成员

请求参数

参数名	类型	必填	说明
memberType	Integer	是	成员类型
relationId	Long	是	关联ID
userId	Long	是	用户ID

2.10 批量添加成员

接口路径: POST /stgl/member/batchAdd
权限码: stgl:clubmember:add
功能说明: 批量添加成员

请求体参数

{
  "memberType": 1,
  "relationId": 1001,
  "userIds": [100003, 100004, 100005],
  "roleType": 3
}

2.11 更新成员角色

接口路径: PUT /stgl/member/updateRole
权限码: stgl:clubmember:edit
功能说明: 更新成员角色

请求体参数

{
  "id": 2001,
  "roleType": 2
}

2.12 成员退出

接口路径: PUT /stgl/member/quit/{id}
权限码: stgl:clubmember:edit
功能说明: 成员退出社团

2.13 成员审核

接口路径: PUT /stgl/member/approve/{id}
权限码: stgl:member:approve
功能说明: 审核成员申请（批准或拒绝）

请求参数

参数名	类型	必填	说明
id	Long	是	成员ID（路径参数）
approved	Boolean	是	是否通过(true-通过,false-拒绝)

请求示例

PUT /stgl/member/approve/1001?approved=true

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": null
}

业务逻辑说明

状态检查: 只有状态为"0"（待审核）的申请可以被审核
状态更新:
- 审核通过：状态更新为"2"（已加入）
- 审核拒绝：状态更新为"3"（已驳回）
权限验证: 必须具有stgl:member:approve权限
重复审核检查: 已审核过的申请无法重复审核

成员状态字典说明 (stgl_member_status)

状态值	状态名称	说明
0	待审核	用户提交申请，等待审核
1	审核中	审核进行中（系统状态）
2	已加入	审核通过，正式成员
3	已驳回	审核拒绝
4	已退出	主动退出或被移除

🎯 社团报名大厅模块

3.1 查询社团报名大厅列表

接口路径: GET /stgl/register/list
权限码: 无需权限（公开接口）
功能说明: 分页查询可报名的社团列表，学生端使用

请求参数

参数名	类型	必填	说明
clubType	String	否	社团类型
clubName	String	否	社团名称（模糊查询）
pageNum	Integer	否	页码，默认1
pageSize	Integer	否	每页数量，默认10

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "rows": [
    {
      "id": 1001,
      "clubName": "计算机协会",
      "clubType": "学术科技类",
      "establishDate": "2023-09-01",
      "description": "致力于计算机技术交流和学习",
      "logoUrl": "/upload/logo/cs-logo.png",
      "presidentName": "张三",
      "presidentDept": "计算机学院",
      "advisorName": "王教授",
      "advisorDept": "计算机学院",
      "memberLimit": 100,
      "currentMemberCount": 85,
      "recruitCycle": "每学期开学",
      "recruitTime": "9月、3月",
      "activityFrequency": "每周一次技术交流",
      "canRegister": true,
      "isRegistered": false
    }
  ],
  "total": 1
}

3.2 查询社团报名大厅列表（不分页）

接口路径: GET /stgl/register/listAll
权限码: 无需权限（公开接口）
功能说明: 查询所有可报名的社团列表，不分页

3.3 获取社团详细信息

接口路径: GET /stgl/register/{clubId}
权限码: 无需权限（公开接口）
功能说明: 获取社团详细信息，用于报名页面展示

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1001,
    "clubName": "计算机协会",
    "clubType": "学术科技类",
    "establishDate": "2023-09-01",
    "description": "致力于计算机技术交流和学习",
    "logoUrl": "/upload/logo/cs-logo.png",
    "presidentName": "张三",
    "presidentDept": "计算机学院",
    "advisorName": "王教授",
    "advisorDept": "计算机学院",
    "memberLimit": 100,
    "currentMemberCount": 85,
    "departments": "技术部、宣传部、组织部",
    "recruitCycle": "每学期开学",
    "recruitTime": "9月、3月",
    "activityFrequency": "每周一次技术交流",
    "canRegister": true,
    "isRegistered": false
  }
}

3.4 申请加入社团

接口路径: POST /stgl/clubRegister/apply
权限码: stgl:register:apply
功能说明: 学生申请加入社团，申请理由将存储到成员记录的备注字段中

请求参数

参数名	类型	必填	说明	位置
clubId	Long	是	社团ID	Query参数
reason	String	否	申请理由（最大500字符，存储到成员备注字段）	请求体

请求示例

POST /stgl/clubRegister/apply?clubId=1001
Content-Type: application/json

{
  "reason": "我对计算机技术很感兴趣，希望能加入贵社团学习交流"
}

响应示例

{
  "code": 200,
  "msg": "申请提交成功"
}

异常情况

社团不存在或已停用：{"code": 500, "msg": "社团不存在或已停用"}
已是社团成员：{"code": 500, "msg": "您已是该社团的成员"}
成员已满：{"code": 500, "msg": "该社团成员已满，无法加入"}
重复申请：{"code": 500, "msg": "您已申请过该社团，请勿重复申请"}

数据存储说明

申请理由存储位置: stgl_member 表的 remark 字段
存储时机: 创建成员记录时同步存储
字段限制: 最大500字符，超出部分将被截断
查看方式: 可在社团成员管理页面的备注列中查看申请理由

3.5 退出社团

接口路径: POST /stgl/register/quit/{clubId}
权限码: stgl:register:quit
功能说明: 学生退出社团

路径参数

参数名	类型	必填	说明
clubId	Long	是	社团ID

3.6 查询我参与的社团列表

接口路径: GET /stgl/register/myClubs
权限码: stgl:register:list
功能说明: 查询当前用户参与的社团列表

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1001,
      "clubName": "计算机协会",
      "clubType": "学术科技类",
      "logoUrl": "/upload/logo/cs-logo.png",
      "myRoleType": 1,
      "myRoleName": "社长",
      "myJoinTime": "2023-09-01 10:00:00",
      "isRegistered": true,
      "canRegister": false
    }
  ]
}

3.7 检查是否已报名某个社团

接口路径: GET /stgl/register/checkRegistered/{clubId}
权限码: 无需权限（公开接口）
功能说明: 检查当前用户是否已报名某个社团

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": true
}

3.8 查询推荐社团

接口路径: GET /stgl/register/recommend
权限码: 无需权限（公开接口）
功能说明: 按成员数量排序查询推荐社团

请求参数

参数名	类型	必填	说明
clubType	String	否	社团类型
limit	Integer	否	推荐数量，默认6

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1001,
      "clubName": "计算机协会",
      "clubType": "学术科技类",
      "logoUrl": "/upload/logo/cs-logo.png",
      "currentMemberCount": 85,
      "memberLimit": 100,
      "canRegister": true,
      "isRegistered": false
    }
  ]
}

📊 数据字典

社团类型 (club_type)

学术科技类: 计算机协会、数学建模协会等
文化艺术类: 文学社、书法协会、摄影协会等
体育健身类: 篮球协会、羽毛球协会、瑜伽社等
实践技能类: 创业协会、职业规划协会等
兴趣爱好类: 动漫社、游戏协会、旅游协会等
思想政治类: 马克思主义学习社等

成员类型 (member_type)

1: 社团成员
2: 志愿者

角色类型 (role_type)

1: 社长
2: 副社长
3: 成员

状态 (status)

1: 正常/已加入
0: 停用/已退出

🔐 权限配置

菜单权限

社团管理: stgl:club
- 查询: stgl:club:list
- 新增: stgl:club:add
- 修改: stgl:club:edit
- 删除: stgl:club:remove
- 导出: stgl:club:export
社团成员管理: stgl:clubmember
- 查询: stgl:clubmember:list
- 新增: stgl:clubmember:add
- 修改: stgl:clubmember:edit
- 删除: stgl:clubmember:remove
- 导出: stgl:clubmember:export
社团报名大厅: stgl:register
- 查询: stgl:register:list
- 加入: stgl:register:join
- 退出: stgl:register:quit

🚀 使用示例

完整的社团报名流程

学生浏览社团: 调用 /stgl/register/list 查看可报名社团
查看社团详情: 调用 /stgl/register/{clubId} 获取详细信息
检查报名状态: 调用 /stgl/register/checkRegistered/{clubId} 确认是否已报名
执行报名操作: 调用 /stgl/register/join/{clubId} 加入社团
查看我的社团: 调用 /stgl/register/myClubs 查看已加入的社团

管理员操作流程

创建社团: 调用 /stgl/club POST方法创建社团
添加成员: 调用 /stgl/member/batchAdd 批量添加成员
设置角色: 调用 /stgl/member/updateRole 更新成员角色
查看统计: 调用 /stgl/club/{id} 查看社团成员统计

📝 注意事项

权限验证: 所有管理端接口都需要相应权限码，学生端公开接口无需权限
数据完整性: 社团名称在同一租户下必须唯一
成员限制: 报名时会自动检查成员数量上限
逻辑删除: 所有删除操作都是逻辑删除，不会物理删除数据
多租户支持: 所有表都支持多租户，数据隔离

📅 文档版本: v1.0
🕒 最后更新: 2025-01-15
👤 维护人员: Cursor AI

社团管理API.md 20 KB Permalink Lịch sử Raw

社团管理API文档

📋 概述

模块划分

技术规范

🔢 成员数量统计规则

🏢 社团信息管理模块

1.1 查询社团信息列表

请求参数

响应示例

1.2 获取社团详细信息

路径参数

响应示例

1.3 新增社团信息

请求体参数

响应示例

1.4 修改社团信息

请求体参数

1.5 删除社团信息

路径参数

1.6 导出社团信息

1.7 查询可用社团选项

响应示例

1.8 根据类型查询社团

1.9 查询我管理的社团

1.10 启用/禁用社团

请求体参数

👥 社团成员管理模块

2.1 查询社团成员列表

请求参数

响应示例

2.2 获取成员详细信息

2.3 新增社团成员

请求体参数

2.4 修改成员信息

2.5 删除成员

2.6 导出成员信息

2.7 根据社团查询成员

2.8 根据用户查询参与的社团

2.9 检查成员是否存在

请求参数

2.10 批量添加成员

请求体参数

2.11 更新成员角色

请求体参数

2.12 成员退出

2.13 成员审核

请求参数

请求示例

响应示例

业务逻辑说明

成员状态字典说明 (stgl_member_status)

🎯 社团报名大厅模块

3.1 查询社团报名大厅列表

请求参数

响应示例

3.2 查询社团报名大厅列表（不分页）

3.3 获取社团详细信息

响应示例

3.4 申请加入社团

请求参数

请求示例

响应示例

异常情况

数据存储说明

3.5 退出社团

路径参数

3.6 查询我参与的社团列表

响应示例

3.7 检查是否已报名某个社团

响应示例

3.8 查询推荐社团

请求参数

响应示例

📊 数据字典

社团类型 (club_type)

成员类型 (member_type)

角色类型 (role_type)

状态 (status)

🔐 权限配置

社团管理API.md 20 KB

Permalink Lịch sử Raw