Inicio Explorar Axuda
Rexistro Iniciar sesión
hzdyjs-xg
/
all-project
2
0
Fork 0
Ficheiros Incidencias 0 Pull Requests 0 Wiki
Árbore: 461396c77f
Ramas Etiquetas
all-project
/
docs
/
开发文档
/
API
/
社团管理API.md

社团管理API.md 18 KB
Histórico Raw

社团管理API文档

📋 文档信息

  • 模块名称: 社团管理系统
  • 接口前缀: /stgl
  • 版本: v1.0
  • 创建时间: 2025-01-15
  • 作者: Cursor AI
  • 权限验证: Sa-Token

🎯 功能概述

社团管理系统提供完整的校园社团管理功能，包括：

  1. 社团信息管理 - 社团基本信息的增删改查
  2. 社团成员管理 - 成员关系和角色管理
  3. 社团报名大厅 - 学生浏览和报名社团功能

🔐 权限说明

权限前缀

  • stgl:club:* - 社团信息管理权限
  • stgl:member:* - 社团成员管理权限
  • stgl:register:* - 社团报名大厅权限

角色说明

  • 系统管理员: 拥有所有社团管理权限
  • 社长: 拥有所管理社团的完整权限
  • 副社长: 拥有所管理社团的部分权限
  • 学生: 拥有浏览和报名权限

📊 数据模型

社团信息表 (stgl_club)

CREATE TABLE `stgl_club` (
  `id` bigint(20) NOT NULL COMMENT '主键ID',
  `tenant_id` varchar(20) NOT NULL DEFAULT '000000' COMMENT '租户编号',
  `club_name` varchar(100) NOT NULL COMMENT '社团名称',
  `club_type` varchar(50) NOT NULL COMMENT '社团类型',
  `establish_date` date COMMENT '成立日期',
  `description` text COMMENT '社团简介',
  `president_name` varchar(50) COMMENT '社长姓名',
  `member_limit` int DEFAULT 0 COMMENT '成员规模上限',
  `status` tinyint DEFAULT 1 COMMENT '状态（1-正常 0-停用）',
  -- 其他字段...
);

成员关系表 (stgl_member)

CREATE TABLE `stgl_member` (
  `id` bigint(20) NOT NULL COMMENT '主键ID',
  `member_type` tinyint NOT NULL COMMENT '成员类型（1-社团成员 2-志愿者）',
  `relation_id` bigint(20) NOT NULL COMMENT '关联ID（社团ID或志愿者队伍ID）',
  `user_id` bigint(20) NOT NULL COMMENT '用户ID',
  `student_no` varchar(20) COMMENT '学号',
  `student_name` varchar(50) COMMENT '学生姓名',
  `role_type` tinyint COMMENT '角色类型（1-社长 2-副社长 3-成员）',
  `status` tinyint DEFAULT 1 COMMENT '状态（1-正常 0-退出）',
  -- 其他字段...
);

📋 API接口列表

1. 社团信息管理

1.1 查询社团列表

接口地址: GET /stgl/club/list

权限要求: stgl:club:list

请求参数:

{
  "pageNum": 1,
  "pageSize": 10,
  "clubName": "社团名称（模糊查询）",
  "clubType": "社团类型",
  "presidentName": "社长姓名（模糊查询）",
  "status": 1,
  "beginCreateTime": "2025-01-01",
  "endCreateTime": "2025-12-31"
}

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 100,
    "rows": [
      {
        "id": 1,
        "clubName": "智能科技社团",
        "clubType": "学术科技类",
        "establishDate": "2025-01-15",
        "description": "专注于人工智能、机器学习等前沿科技领域...",
        "presidentName": "张三",
        "presidentDept": "计算机学院",
        "memberLimit": 50,
        "status": 1,
        "createTime": "2025-01-15 10:00:00"
      }
    ]
  }
}

1.2 新增社团

接口地址: POST /stgl/club

权限要求: stgl:club:add

请求参数:

{
  "clubName": "智能科技社团",
  "clubType": "学术科技类",
  "establishDate": "2025-01-15",
  "description": "专注于人工智能、机器学习等前沿科技领域的学术研究和实践交流社团",
  "email": "aitech@example.com",
  "phone": "028-12345678",
  "presidentName": "张三",
  "presidentStudentNo": "20250001",
  "presidentDept": "计算机学院",
  "presidentMajor": "软件工程",
  "presidentClass": "软工2501班",
  "presidentPhone": "13800138001",
  "advisorName": "李教授",
  "advisorDept": "计算机学院",
  "memberLimit": 50,
  "recruitCycle": "每学期",
  "recruitTime": "9月、3月",
  "activityFrequency": "每周1-2次",
  "fundingSources": "学校拨款,社团自筹",
  "status": 1
}

返回数据:

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

1.3 查询社团详情

接口地址: GET /stgl/club/{id}

权限要求: stgl:club:query

路径参数:

  • id: 社团ID

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "clubName": "智能科技社团",
    "clubType": "学术科技类",
    "establishDate": "2025-01-15",
    "description": "专注于人工智能、机器学习等前沿科技领域...",
    "email": "aitech@example.com",
    "phone": "028-12345678",
    "logoUrl": "/upload/club/logo/2025/01/15/xxx.jpg",
    "presidentName": "张三",
    "presidentStudentNo": "20250001",
    "presidentDept": "计算机学院",
    "presidentMajor": "软件工程",
    "presidentClass": "软工2501班",
    "presidentPhone": "13800138001",
    "vicePresidentName": "李四",
    "vicePresidentStudentNo": "20250002",
    "advisorName": "李教授",
    "advisorDept": "计算机学院",
    "memberLimit": 50,
    "departments": "技术部、宣传部、组织部",
    "recruitCycle": "每学期",
    "recruitTime": "9月、3月",
    "activityFrequency": "每周1-2次",
    "fundingSources": "学校拨款,社团自筹",
    "charterUrl": "/upload/club/charter/2025/01/15/xxx.pdf",
    "status": 1,
    "createTime": "2025-01-15 10:00:00",
    "updateTime": "2025-01-15 14:30:00"
  }
}

1.4 修改社团信息

接口地址: PUT /stgl/club

权限要求: stgl:club:edit

请求参数: 同新增社团，需包含id字段

返回数据:

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

1.5 删除社团

接口地址: DELETE /stgl/club/{ids}

权限要求: stgl:club:remove

路径参数:

  • ids: 社团ID数组，用逗号分隔

返回数据:

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

1.6 查询可用社团选项

接口地址: GET /stgl/club/options

权限要求: stgl:club:list

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "clubName": "智能科技社团",
      "clubType": "学术科技类"
    },
    {
      "id": 2,
      "clubName": "文学社",
      "clubType": "文化艺术类"
    }
  ]
}

1.7 根据社团类型查询社团列表

接口地址: GET /stgl/club/listByType/{clubType}

权限要求: stgl:club:list

路径参数:

  • clubType: 社团类型

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "clubName": "智能科技社团",
      "clubType": "学术科技类",
      "presidentName": "张三"
    }
  ]
}

1.8 查询我管理的社团列表

接口地址: GET /stgl/club/myClubs

权限要求: stgl:club:list

返回数据: 同上

1.9 检查社团名称是否重复

接口地址: GET /stgl/club/checkClubNameUnique

权限要求: stgl:club:list

请求参数:

{
  "clubName": "社团名称",
  "excludeId": 1  // 可选，修改时排除的ID
}

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": true  // true=唯一，false=重复
}

1.10 启用/禁用社团

接口地址: PUT /stgl/club/changeStatus

权限要求: stgl:club:edit

请求参数:

{
  "id": 1,
  "status": 0  // 1-启用，0-禁用
}

返回数据:

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

1.11 导出社团信息

接口地址: POST /stgl/club/export

权限要求: stgl:club:export

请求参数: 同查询列表的筛选条件

返回数据: Excel文件流

2. 社团成员管理

2.1 查询成员列表

接口地址: GET /stgl/member/list

权限要求: stgl:member:list

请求参数:

{
  "pageNum": 1,
  "pageSize": 10,
  "memberType": 1,  // 1-社团成员，2-志愿者
  "relationId": 1,  // 社团ID或志愿者队伍ID
  "studentNo": "学号（模糊查询）",
  "studentName": "学生姓名（模糊查询）",
  "roleType": 3,    // 1-社长，2-副社长，3-成员
  "status": 1       // 1-正常，0-退出
}

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 50,
    "rows": [
      {
        "id": 1,
        "memberType": 1,
        "memberTypeName": "社团成员",
        "relationId": 1,
        "relationName": "智能科技社团",
        "userId": 1001,
        "studentNo": "20250002",
        "studentName": "李四",
        "roleType": 3,
        "roleTypeName": "成员",
        "joinTime": "2025-01-15 14:30:00",
        "status": 1,
        "statusName": "正常"
      }
    ]
  }
}

2.2 新增成员

接口地址: POST /stgl/member

权限要求: stgl:member:add

请求参数:

{
  "memberType": 1,     // 1-社团成员，2-志愿者
  "relationId": 1,     // 社团ID或志愿者队伍ID
  "userId": 1001,      // 用户ID
  "studentNo": "20250002",
  "studentName": "李四",
  "roleType": 3,       // 1-社长，2-副社长，3-成员
  "status": 1
}

返回数据:

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

2.3 查询成员详情

接口地址: GET /stgl/member/{id}

权限要求: stgl:member:query

路径参数:

  • id: 成员ID

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "memberType": 1,
    "relationId": 1,
    "userId": 1001,
    "studentNo": "20250002",
    "studentName": "李四",
    "roleType": 3,
    "joinTime": "2025-01-15 14:30:00",
    "status": 1,
    "remark": "表现优秀"
  }
}

2.4 修改成员信息

接口地址: PUT /stgl/member

权限要求: stgl:member:edit

请求参数: 同新增成员，需包含id字段

返回数据:

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

2.5 删除成员

接口地址: DELETE /stgl/member/{ids}

权限要求: stgl:member:remove

路径参数:

  • ids: 成员ID数组，用逗号分隔

返回数据:

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

2.6 根据社团ID查询成员列表

接口地址: GET /stgl/member/club/{clubId}

权限要求: stgl:member:list

路径参数:

  • clubId: 社团ID

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "studentName": "张三",
      "studentNo": "20250001",
      "roleType": 1,
      "roleTypeName": "社长",
      "joinTime": "2025-01-01 10:00:00"
    },
    {
      "id": 2,
      "studentName": "李四",
      "studentNo": "20250002",
      "roleType": 3,
      "roleTypeName": "成员",
      "joinTime": "2025-01-15 14:30:00"
    }
  ]
}

2.7 根据用户ID查询参与的社团列表

接口地址: GET /stgl/member/user/{userId}

权限要求: stgl:member:list

路径参数:

  • userId: 用户ID

返回数据: 同上

2.8 检查用户是否已是某个社团/队伍的成员

接口地址: GET /stgl/member/checkMemberExists

权限要求: stgl:member:list

请求参数:

{
  "memberType": 1,   // 成员类型
  "relationId": 1,   // 关联ID
  "userId": 1001     // 用户ID
}

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": true  // true=已是成员，false=不是成员
}

2.9 批量添加成员

接口地址: POST /stgl/member/batchAdd

权限要求: stgl:member:add

请求参数:

{
  "memberType": 1,
  "relationId": 1,
  "userIds": [1002, 1003, 1004],
  "roleType": 3
}

返回数据:

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

2.10 更新成员角色

接口地址: PUT /stgl/member/updateRole

权限要求: stgl:member:edit

请求参数:

{
  "id": 1,
  "roleType": 2  // 新角色类型
}

返回数据:

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

2.11 退出社团/队伍

接口地址: PUT /stgl/member/quit/{id}

权限要求: stgl:member:edit

路径参数:

  • id: 成员ID

返回数据:

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

2.12 导出成员信息

接口地址: POST /stgl/member/export

权限要求: stgl:member:export

请求参数: 同查询列表的筛选条件

返回数据: Excel文件流

3. 社团报名大厅

3.1 查询社团报名大厅列表

接口地址: GET /stgl/register/list

权限要求: 无（公开接口）

请求参数:

{
  "pageNum": 1,
  "pageSize": 10,
  "clubType": "学术科技类",
  "clubName": "社团名称（模糊查询）"
}

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 20,
    "rows": [
      {
        "id": 1,
        "clubName": "智能科技社团",
        "clubType": "学术科技类",
        "establishDate": "2025-01-15",
        "description": "专注于人工智能、机器学习等前沿科技领域...",
        "logoUrl": "/upload/club/logo/2025/01/15/xxx.jpg",
        "presidentName": "张三",
        "presidentDept": "计算机学院",
        "advisorName": "李教授",
        "advisorDept": "计算机学院",
        "memberLimit": 50,
        "currentMemberCount": 25,
        "recruitCycle": "每学期",
        "recruitTime": "9月、3月",
        "activityFrequency": "每周1-2次",
        "hasRegistered": false,      // 当前用户是否已报名
        "registrationStatus": 0,     // 报名状态
        "canRegister": true          // 是否可报名
      }
    ]
  }
}

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

接口地址: GET /stgl/register/listAll

权限要求: 无（公开接口）

请求参数:

{
  "clubType": "学术科技类",
  "clubName": "社团名称（模糊查询）"
}

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    // 社团列表数据，同上
  ]
}

3.3 查询社团详细信息

接口地址: GET /stgl/register/{clubId}

权限要求: 无（公开接口）

路径参数:

  • clubId: 社团ID

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "clubName": "智能科技社团",
    "clubType": "学术科技类",
    "establishDate": "2025-01-15",
    "description": "专注于人工智能、机器学习等前沿科技领域的学术研究和实践交流社团",
    "logoUrl": "/upload/club/logo/2025/01/15/xxx.jpg",
    "presidentName": "张三",
    "presidentDept": "计算机学院",
    "advisorName": "李教授",
    "advisorDept": "计算机学院",
    "memberLimit": 50,
    "currentMemberCount": 25,
    "recruitCycle": "每学期",
    "recruitTime": "9月、3月",
    "activityFrequency": "每周1-2次",
    "hasRegistered": false,
    "registrationStatus": 0,
    "canRegister": true
  }
}

3.4 报名加入社团

接口地址: POST /stgl/register/join/{clubId}

权限要求: stgl:register:join

路径参数:

  • clubId: 社团ID

返回数据:

{
  "code": 200,
  "msg": "报名成功，欢迎加入社团！"
}

异常情况:

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

3.5 退出社团

接口地址: POST /stgl/register/quit/{clubId}

权限要求: stgl:register:quit

路径参数:

  • clubId: 社团ID

返回数据:

{
  "code": 200,
  "msg": "退出社团成功"
}

异常情况:

{
  "code": 500,
  "msg": "您不是该社团的成员"
}
{
  "code": 500,
  "msg": "社长和副社长不能直接退出，请先转让职务"
}

3.6 查询我参与的社团列表

接口地址: GET /stgl/register/myClubs

权限要求: stgl:register:list

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "clubName": "智能科技社团",
      "clubType": "学术科技类",
      "presidentName": "张三",
      "currentMemberCount": 25,
      "memberLimit": 50,
      "hasRegistered": true,
      "registrationStatus": 1
    }
  ]
}

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

接口地址: GET /stgl/register/checkRegistered/{clubId}

权限要求: 无（公开接口）

路径参数:

  • clubId: 社团ID

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": true  // true=已报名，false=未报名
}

3.8 查询推荐社团

接口地址: GET /stgl/register/recommend

权限要求: 无（公开接口）

请求参数:

{
  "clubType": "学术科技类",  // 可选
  "limit": 6              // 推荐数量，默认6个
}

返回数据:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "clubName": "智能科技社团",
      "clubType": "学术科技类",
      "description": "专注于人工智能...",
      "logoUrl": "/upload/club/logo/xxx.jpg",
      "currentMemberCount": 25,
      "memberLimit": 50,
      "canRegister": true
    }
  ]
}

🔧 错误码说明

| 错误码 | 说明 | |-------|------| | 200 | 操作成功 | | 400 | 请求参数错误 | | 401 | 未授权，需要登录 | | 403 | 权限不足 | | 404 | 资源不存在 | | 500 | 服务器内部错误 |

📝 常见异常信息

社团管理相关

  • "社团名称已存在，请重新输入"
  • "社团不存在或已停用"
  • "该社团成员已满，无法加入"

成员管理相关

  • "用户已是该组织的成员，不能重复添加"
  • "您不是该社团的成员"
  • "社长和副社长不能直接退出，请先转让职务"

权限相关

  • "权限不足，无法访问该资源"
  • "Token已过期，请重新登录"

🧪 测试说明

测试环境

  • 服务器地址：http://localhost:8080
  • 测试账号：admin/admin123
  • 加密方式：AES+RSA双重加密

测试脚本

项目根目录提供了完整的Node.js测试脚本 stgl-api-test.js

运行方法：

npm install axios crypto
node stgl-api-test.js

测试覆盖：

  • 24个API接口完整测试
  • 权限验证测试
  • 异常情况测试
  • 数据完整性验证

📊 使用统计

接口统计

  • 社团信息管理: 11个接口
  • 社团成员管理: 12个接口
  • 社团报名大厅: 8个接口
  • 总计: 31个API接口

权限统计

  • 管理员权限: 31个接口
  • 社长权限: 23个接口
  • 学生权限: 8个接口
  • 公开接口: 5个接口

📞 技术支持

如有问题请联系开发团队或查看项目文档。

文档版本: v1.0
最后更新: 2025-01-15