# 社团管理API文档 ## 📋 文档信息 - **模块名称**: 社团管理系统 - **接口前缀**: `/stgl` - **版本**: v1.0 - **创建时间**: 2025-01-15 - **作者**: Cursor AI - **权限验证**: Sa-Token ## 🎯 功能概述 社团管理系统提供完整的校园社团管理功能,包括: 1. **社团信息管理** - 社团基本信息的增删改查 2. **社团成员管理** - 成员关系和角色管理 3. **社团报名大厅** - 学生浏览和报名社团功能 ## 🔐 权限说明 ### 权限前缀 - `stgl:club:*` - 社团信息管理权限 - `stgl:member:*` - 社团成员管理权限 - `stgl:register:*` - 社团报名大厅权限 ### 角色说明 - **系统管理员**: 拥有所有社团管理权限 - **社长**: 拥有所管理社团的完整权限 - **副社长**: 拥有所管理社团的部分权限 - **学生**: 拥有浏览和报名权限 ## 📊 数据模型 ### 社团信息表 (stgl_club) ```sql 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) ```sql 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` **请求参数**: ```json { "pageNum": 1, "pageSize": 10, "clubName": "社团名称(模糊查询)", "clubType": "社团类型", "presidentName": "社长姓名(模糊查询)", "status": 1, "beginCreateTime": "2025-01-01", "endCreateTime": "2025-12-31" } ``` **返回数据**: ```json { "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` **请求参数**: ```json { "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 } ``` **返回数据**: ```json { "code": 200, "msg": "操作成功" } ``` ### 1.3 查询社团详情 **接口地址**: `GET /stgl/club/{id}` **权限要求**: `stgl:club:query` **路径参数**: - `id`: 社团ID **返回数据**: ```json { "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字段 **返回数据**: ```json { "code": 200, "msg": "操作成功" } ``` ### 1.5 删除社团 **接口地址**: `DELETE /stgl/club/{ids}` **权限要求**: `stgl:club:remove` **路径参数**: - `ids`: 社团ID数组,用逗号分隔 **返回数据**: ```json { "code": 200, "msg": "操作成功" } ``` ### 1.6 查询可用社团选项 **接口地址**: `GET /stgl/club/options` **权限要求**: `stgl:club:list` **返回数据**: ```json { "code": 200, "msg": "操作成功", "data": [ { "id": 1, "clubName": "智能科技社团", "clubType": "学术科技类" }, { "id": 2, "clubName": "文学社", "clubType": "文化艺术类" } ] } ``` ### 1.7 根据社团类型查询社团列表 **接口地址**: `GET /stgl/club/listByType/{clubType}` **权限要求**: `stgl:club:list` **路径参数**: - `clubType`: 社团类型 **返回数据**: ```json { "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` **请求参数**: ```json { "clubName": "社团名称", "excludeId": 1 // 可选,修改时排除的ID } ``` **返回数据**: ```json { "code": 200, "msg": "操作成功", "data": true // true=唯一,false=重复 } ``` ### 1.10 启用/禁用社团 **接口地址**: `PUT /stgl/club/changeStatus` **权限要求**: `stgl:club:edit` **请求参数**: ```json { "id": 1, "status": 0 // 1-启用,0-禁用 } ``` **返回数据**: ```json { "code": 200, "msg": "操作成功" } ``` ### 1.11 导出社团信息 **接口地址**: `POST /stgl/club/export` **权限要求**: `stgl:club:export` **请求参数**: 同查询列表的筛选条件 **返回数据**: Excel文件流 --- ## 2. 社团成员管理 ### 2.1 查询成员列表 **接口地址**: `GET /stgl/member/list` **权限要求**: `stgl:member:list` **请求参数**: ```json { "pageNum": 1, "pageSize": 10, "memberType": 1, // 1-社团成员,2-志愿者 "relationId": 1, // 社团ID或志愿者队伍ID "studentNo": "学号(模糊查询)", "studentName": "学生姓名(模糊查询)", "roleType": 3, // 1-社长,2-副社长,3-成员 "status": 1 // 1-正常,0-退出 } ``` **返回数据**: ```json { "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` **请求参数**: ```json { "memberType": 1, // 1-社团成员,2-志愿者 "relationId": 1, // 社团ID或志愿者队伍ID "userId": 1001, // 用户ID "studentNo": "20250002", "studentName": "李四", "roleType": 3, // 1-社长,2-副社长,3-成员 "status": 1 } ``` **返回数据**: ```json { "code": 200, "msg": "操作成功" } ``` ### 2.3 查询成员详情 **接口地址**: `GET /stgl/member/{id}` **权限要求**: `stgl:member:query` **路径参数**: - `id`: 成员ID **返回数据**: ```json { "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字段 **返回数据**: ```json { "code": 200, "msg": "操作成功" } ``` ### 2.5 删除成员 **接口地址**: `DELETE /stgl/member/{ids}` **权限要求**: `stgl:member:remove` **路径参数**: - `ids`: 成员ID数组,用逗号分隔 **返回数据**: ```json { "code": 200, "msg": "操作成功" } ``` ### 2.6 根据社团ID查询成员列表 **接口地址**: `GET /stgl/member/club/{clubId}` **权限要求**: `stgl:member:list` **路径参数**: - `clubId`: 社团ID **返回数据**: ```json { "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` **请求参数**: ```json { "memberType": 1, // 成员类型 "relationId": 1, // 关联ID "userId": 1001 // 用户ID } ``` **返回数据**: ```json { "code": 200, "msg": "操作成功", "data": true // true=已是成员,false=不是成员 } ``` ### 2.9 批量添加成员 **接口地址**: `POST /stgl/member/batchAdd` **权限要求**: `stgl:member:add` **请求参数**: ```json { "memberType": 1, "relationId": 1, "userIds": [1002, 1003, 1004], "roleType": 3 } ``` **返回数据**: ```json { "code": 200, "msg": "操作成功" } ``` ### 2.10 更新成员角色 **接口地址**: `PUT /stgl/member/updateRole` **权限要求**: `stgl:member:edit` **请求参数**: ```json { "id": 1, "roleType": 2 // 新角色类型 } ``` **返回数据**: ```json { "code": 200, "msg": "操作成功" } ``` ### 2.11 退出社团/队伍 **接口地址**: `PUT /stgl/member/quit/{id}` **权限要求**: `stgl:member:edit` **路径参数**: - `id`: 成员ID **返回数据**: ```json { "code": 200, "msg": "操作成功" } ``` ### 2.12 导出成员信息 **接口地址**: `POST /stgl/member/export` **权限要求**: `stgl:member:export` **请求参数**: 同查询列表的筛选条件 **返回数据**: Excel文件流 --- ## 3. 社团报名大厅 ### 3.1 查询社团报名大厅列表 **接口地址**: `GET /stgl/register/list` **权限要求**: 无(公开接口) **请求参数**: ```json { "pageNum": 1, "pageSize": 10, "clubType": "学术科技类", "clubName": "社团名称(模糊查询)" } ``` **返回数据**: ```json { "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` **权限要求**: 无(公开接口) **请求参数**: ```json { "clubType": "学术科技类", "clubName": "社团名称(模糊查询)" } ``` **返回数据**: ```json { "code": 200, "msg": "操作成功", "data": [ // 社团列表数据,同上 ] } ``` ### 3.3 查询社团详细信息 **接口地址**: `GET /stgl/register/{clubId}` **权限要求**: 无(公开接口) **路径参数**: - `clubId`: 社团ID **返回数据**: ```json { "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 **返回数据**: ```json { "code": 200, "msg": "报名成功,欢迎加入社团!" } ``` **异常情况**: ```json { "code": 500, "msg": "您已是该社团的成员" } { "code": 500, "msg": "该社团成员已满,无法加入" } { "code": 500, "msg": "社团不存在或已停用" } ``` ### 3.5 退出社团 **接口地址**: `POST /stgl/register/quit/{clubId}` **权限要求**: `stgl:register:quit` **路径参数**: - `clubId`: 社团ID **返回数据**: ```json { "code": 200, "msg": "退出社团成功" } ``` **异常情况**: ```json { "code": 500, "msg": "您不是该社团的成员" } { "code": 500, "msg": "社长和副社长不能直接退出,请先转让职务" } ``` ### 3.6 查询我参与的社团列表 **接口地址**: `GET /stgl/register/myClubs` **权限要求**: `stgl:register:list` **返回数据**: ```json { "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 **返回数据**: ```json { "code": 200, "msg": "操作成功", "data": true // true=已报名,false=未报名 } ``` ### 3.8 查询推荐社团 **接口地址**: `GET /stgl/register/recommend` **权限要求**: 无(公开接口) **请求参数**: ```json { "clubType": "学术科技类", // 可选 "limit": 6 // 推荐数量,默认6个 } ``` **返回数据**: ```json { "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` 运行方法: ```bash 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