# 社团管理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 |

#### 响应示例
```json
{
  "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 |

#### 响应示例
```json
{
  "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`
- **功能说明**: 新增社团信息

#### 请求体参数
```json
{
  "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": "备注信息"
}
```

#### 响应示例
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

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

#### 请求体参数
```json
{
  "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`
- **功能说明**: 查询状态正常的社团选项，用于下拉框等

#### 响应示例
```json
{
  "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`
- **功能说明**: 启用或禁用社团

#### 请求体参数
```json
{
  "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 |

#### 响应示例
```json
{
  "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`
- **功能说明**: 新增社团成员

#### 请求体参数
```json
{
  "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`
- **功能说明**: 批量添加成员

#### 请求体参数
```json
{
  "memberType": 1,
  "relationId": 1001,
  "userIds": [100003, 100004, 100005],
  "roleType": 3
}
```

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

#### 请求体参数
```json
{
  "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-拒绝) |

#### 请求示例
```http
PUT /stgl/member/approve/1001?approved=true
```

#### 响应示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": null
}
```

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

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

---

## 🎯 社团报名大厅模块

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

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

#### 响应示例
```json
{
  "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}`
- **权限码**: 无需权限（公开接口）
- **功能说明**: 获取社团详细信息，用于报名页面展示

#### 响应示例
```json
{
  "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": "我对计算机技术很感兴趣，希望能加入贵社团学习交流"
}
```

#### 响应示例
```json
{
  "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`
- **功能说明**: 查询当前用户参与的社团列表

#### 响应示例
```json
{
  "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}`
- **权限码**: 无需权限（公开接口）
- **功能说明**: 检查当前用户是否已报名某个社团

#### 响应示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": true
}
```

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

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

#### 响应示例
```json
{
  "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`

---

## 🚀 使用示例

### 完整的社团报名流程
1. **学生浏览社团**: 调用 `/stgl/register/list` 查看可报名社团
2. **查看社团详情**: 调用 `/stgl/register/{clubId}` 获取详细信息
3. **检查报名状态**: 调用 `/stgl/register/checkRegistered/{clubId}` 确认是否已报名
4. **执行报名操作**: 调用 `/stgl/register/join/{clubId}` 加入社团
5. **查看我的社团**: 调用 `/stgl/register/myClubs` 查看已加入的社团

### 管理员操作流程
1. **创建社团**: 调用 `/stgl/club` POST方法创建社团
2. **添加成员**: 调用 `/stgl/member/batchAdd` 批量添加成员
3. **设置角色**: 调用 `/stgl/member/updateRole` 更新成员角色
4. **查看统计**: 调用 `/stgl/club/{id}` 查看社团成员统计

---

## 📝 注意事项

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

---

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