# SAMS系统接口文档

## 1. 认证接口 (AuthController)

### 1.1 用户登录
- **接口路径**: `/login`
- **请求方式**: POST
- **请求参数**:
```json
{
    "username": "string",  // 用户名/学号/邮箱
    "password": "string"   // 密码
}
```
- **响应结果**:
```json
{
    "code": 200,
    "msg": "登录成功",
    "data": "JWT令牌"
}
```

## 2. 系统管理接口 (sys)

### 2.1 用户管理 (UserController)
- **接口路径**: `/api/user`
- **功能**: 普通用户管理相关接口

#### 2.1.1 修改密码
- **接口路径**: `/api/user/change-password`
- **请求方式**: PUT
- **请求参数**:
```json
{
    "userId": "number",      // 用户ID
    "oldPassword": "string", // 旧密码
    "newPassword": "string"  // 新密码
}
```
- **响应结果**:
```json
{
    "code": 200,
    "msg": "密码修改成功",
    "data": null
}
```

#### 2.1.2 更新个人信息
- **接口路径**: `/api/user/profile`
- **请求方式**: PUT
- **请求参数**:
```json
{
    "userId": "number",      // 用户ID
    "nickname": "string",    // 昵称
    "email": "string",       // 邮箱
    "avatar": "string"       // 头像URL
}
```
- **响应结果**:
```json
{
    "code": 200,
    "msg": "个人信息更新成功",
    "data": null
}
```

#### 2.1.3 获取用户详情
- **接口路径**: `/api/user/{userId}`
- **请求方式**: GET
- **路径参数**:
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "userId": "number",
        "username": "string",
        "nickname": "string",
        "email": "string",
        "avatar": "string"
    }
}
```

#### 2.1.4 上传头像
- **接口路径**: `/api/user/avatar`
- **请求方式**: POST
- **请求参数**:
  - file: 头像文件（MultipartFile）
- **响应结果**: 返回上传后的头像URL字符串

### 2.2 管理员用户管理 (AdminUserController)
- **接口路径**: `/api/admin/user`
- **功能**: 管理员用户管理相关接口

#### 2.2.1 批量导入用户
- **接口路径**: `/api/admin/user/import`
- **请求方式**: POST
- **请求参数**:
```json
[
    {
        "username": "string",
        "password": "string",
        "email": "string",
        "role": "string"
    }
]
```
- **响应结果**:
```json
{
    "code": 200,
    "msg": "用户导入成功",
    "data": null
}
```

#### 2.2.2 查询用户列表
- **接口路径**: `/api/admin/user/list`
- **请求方式**: GET
- **请求参数**:
  - keyword: 关键字（可选，用于搜索用户名、学号、邮箱）
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "userId": "number",
            "username": "string",
            "email": "string",
            "role": "string",
            "status": "string"
        }
    ]
}
```

#### 2.2.3 更新用户信息
- **接口路径**: `/api/admin/user/update`
- **请求方式**: PUT
- **请求参数**:
```json
{
    "userId": "number",
    "role": "string",
    "status": "string",
    "password": "string"
}
```
- **响应结果**:
```json
{
    "code": 200,
    "msg": "用户信息更新成功",
    "data": null
}
```

#### 2.2.4 重置用户密码
- **接口路径**: `/api/admin/user/reset-password/{userId}`
- **请求方式**: PUT
- **路径参数**:
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "密码已重置为 123456",
    "data": null
}
```

#### 2.2.5 封禁用户
- **接口路径**: `/api/admin/user/ban/{userId}`
- **请求方式**: PUT
- **路径参数**:
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "用户已封禁",
    "data": null
}
```

#### 2.2.6 删除用户
- **接口路径**: `/api/admin/user/{userId}`
- **请求方式**: DELETE
- **路径参数**:
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "用户已删除",
    "data": null
}
```

### 2.3 文件管理 (FileController)
- **接口路径**: `/api/file`
- **功能**: 文件上传下载相关接口
- **说明**: 该模块目前为空，待实现

## 3. 活动管理接口 (ams)

### 3.1 活动管理 (ActivityController)
- **接口路径**: `/api/admin/activity`
- **功能**: 活动创建、修改、查询等
- **权限要求**: 需要相应角色权限

#### 3.1.1 创建活动
- **接口路径**: `/api/admin/activity/create`
- **请求方式**: POST
- **权限要求**: USER, CLUB_ADMIN
- **请求参数**:
```json
{
    "title": "string",           // 活动标题
    "description": "string",     // 活动描述
    "startTime": "string",       // 开始时间
    "endTime": "string",         // 结束时间
    "location": "string",        // 活动地点
    "maxParticipants": "number", // 最大参与人数
    "clubId": "number"          // 主办社团ID
}
```
- **响应结果**:
```json
{
    "code": 200,
    "msg": "活动创建成功，等待审批",
    "data": null
}
```

#### 3.1.2 取消活动
- **接口路径**: `/api/admin/activity/cancel`
- **请求方式**: PUT
- **权限要求**: CLUB_ADMIN
- **请求参数**:
  - actId: 活动ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "活动已取消",
    "data": null
}
```

### 3.2 审批管理 (ApprovalController)
- **接口路径**: `/api/admin/approval`
- **功能**: 活动审批相关接口
- **权限要求**: 需要相应角色权限

#### 3.2.1 审批通过
- **接口路径**: `/api/admin/approval/approve`
- **请求方式**: POST
- **权限要求**: CLUB_ADMIN, DEPARTMENT_ADMIN, COLLEGE_ADMIN
- **请求参数**:
  - apprId: 审批ID
  - approverId: 审批人ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "审批已通过",
    "data": null
}
```

#### 3.2.2 审批拒绝
- **接口路径**: `/api/admin/approval/reject`
- **请求方式**: POST
- **权限要求**: CLUB_ADMIN, DEPARTMENT_ADMIN, COLLEGE_ADMIN
- **请求参数**:
  - apprId: 审批ID
  - reason: 拒绝原因
  - approverId: 审批人ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "审批已拒绝",
    "data": null
}
```

### 3.3 评论管理 (CommentController)
- **接口路径**: `/api/comment`
- **功能**: 活动评论相关接口
- **权限要求**: 需要相应角色权限

#### 3.3.1 发表评论
- **接口路径**: `/api/comment/add`
- **请求方式**: POST
- **权限要求**: USER
- **请求参数**:
  - userId: 用户ID
  - actId: 活动ID
  - content: 评论内容
  - parentCommentId: 父评论ID（可选，用于回复）
- **响应结果**:
```json
{
    "code": 200,
    "msg": "评论成功",
    "data": null
}
```

#### 3.3.2 删除评论
- **接口路径**: `/api/comment/delete`
- **请求方式**: DELETE
- **权限要求**: USER, ADMIN
- **请求参数**:
  - commentId: 评论ID
  - userId: 用户ID
  - isAdmin: 是否为管理员
- **响应结果**:
```json
{
    "code": 200,
    "msg": "评论已删除",
    "data": null
}
```

#### 3.3.3 获取活动评论列表
- **接口路径**: `/api/comment/list`
- **请求方式**: GET
- **请求参数**:
  - actId: 活动ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "commentId": "number",
            "userId": "number",
            "content": "string",
            "createTime": "string"
        }
    ]
}
```

#### 3.3.4 获取评论回复
- **接口路径**: `/api/comment/replies`
- **请求方式**: GET
- **请求参数**:
  - parentCommentId: 父评论ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "commentId": "number",
            "userId": "number",
            "content": "string",
            "createTime": "string"
        }
    ]
}
```

### 3.4 反应管理 (ReactionController)
- **接口路径**: `/api/reaction`
- **功能**: 活动反应（点赞等）相关接口
- **权限要求**: 需要相应角色权限

#### 3.4.1 添加反应
- **接口路径**: `/api/reaction/add`
- **请求方式**: POST
- **权限要求**: USER
- **请求参数**:
  - actId: 活动ID
  - userId: 用户ID
  - reactionType: 反应类型（LIKE/DISLIKE）
- **响应结果**:
```json
{
    "code": 200,
    "msg": "操作成功",
    "data": null
}
```

#### 3.4.2 取消反应
- **接口路径**: `/api/reaction/remove`
- **请求方式**: DELETE
- **权限要求**: USER
- **请求参数**:
  - actId: 活动ID
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "已取消点赞/点踩",
    "data": null
}
```

#### 3.4.3 获取反应统计
- **接口路径**: `/api/reaction/stats`
- **请求方式**: GET
- **请求参数**:
  - actId: 活动ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "likes": "number",
        "dislikes": "number"
    }
}
```

#### 3.4.4 获取活动反应列表
- **接口路径**: `/api/reaction/list`
- **请求方式**: GET
- **权限要求**: ADMIN
- **请求参数**:
  - actId: 活动ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "reactionId": "number",
            "userId": "number",
            "reactionType": "string",
            "createTime": "string"
        }
    ]
}
```

### 3.5 报名管理 (RegistrationController)
- **接口路径**: `/api/registration`
- **功能**: 活动报名相关接口
- **权限要求**: 需要相应角色权限

#### 3.5.1 报名活动
- **接口路径**: `/api/registration/register`
- **请求方式**: POST
- **权限要求**: USER
- **请求参数**:
  - actId: 活动ID
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "报名成功",
    "data": null
}
```

#### 3.5.2 取消报名
- **接口路径**: `/api/registration/cancel`
- **请求方式**: PUT
- **权限要求**: USER
- **请求参数**:
  - actId: 活动ID
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "报名已取消",
    "data": null
}
```

#### 3.5.3 活动签到
- **接口路径**: `/api/registration/attend`
- **请求方式**: PUT
- **权限要求**: USER
- **请求参数**:
  - actId: 活动ID
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "签到成功",
    "data": null
}
```

#### 3.5.4 获取我的报名列表
- **接口路径**: `/api/registration/my-registrations`
- **请求方式**: GET
- **权限要求**: USER
- **请求参数**:
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "registrationId": "number",
            "actId": "number",
            "userId": "number",
            "status": "string",
            "createTime": "string"
        }
    ]
}
```

#### 3.5.5 获取活动报名列表
- **接口路径**: `/api/registration/list`
- **请求方式**: GET
- **权限要求**: ADMIN, COLLEGE_ADMIN, DEPARTMENT_ADMIN
- **请求参数**:
  - actId: 活动ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "registrationId": "number",
            "actId": "number",
            "userId": "number",
            "status": "string",
            "createTime": "string"
        }
    ]
}
```

## 4. 社团管理接口 (sms)

### 4.1 社团管理 (ClubController)
- **接口路径**: `/api/admin/club`
- **功能**: 社团基本信息管理
- **权限要求**: 需要相应角色权限

#### 4.1.1 添加社团
- **接口路径**: `/api/admin/club/add`
- **请求方式**: POST
- **权限要求**: ADMIN, COLLEGE_ADMIN, DEPARTMENT_ADMIN
- **请求参数**:
```json
{
    "name": "string",        // 社团名称
    "description": "string", // 社团描述
    "collegeId": "number",   // 所属学院ID
    "type": "string"        // 社团类型
}
```
- **响应结果**:
```json
{
    "code": 200,
    "msg": "社团添加成功",
    "data": null
}
```

#### 4.1.2 更新社团信息
- **接口路径**: `/api/admin/club/update`
- **请求方式**: PUT
- **权限要求**: ADMIN, CLUB_ADMIN
- **请求参数**:
```json
{
    "clubId": "number",      // 社团ID
    "name": "string",        // 社团名称
    "description": "string", // 社团描述
    "type": "string"        // 社团类型
}
```
- **响应结果**:
```json
{
    "code": 200,
    "msg": "社团信息更新成功",
    "data": null
}
```

#### 4.1.3 删除社团
- **接口路径**: `/api/admin/club/delete/{clubId}`
- **请求方式**: DELETE
- **权限要求**: ADMIN, COLLEGE_ADMIN, DEPARTMENT_ADMIN
- **路径参数**:
  - clubId: 社团ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "社团删除成功",
    "data": null
}
```

#### 4.1.4 获取社团详情
- **接口路径**: `/api/admin/club/{clubId}`
- **请求方式**: GET
- **权限要求**: ADMIN, COLLEGE_ADMIN, DEPARTMENT_ADMIN, CLUB_ADMIN
- **路径参数**:
  - clubId: 社团ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "clubId": "number",
        "name": "string",
        "description": "string",
        "collegeId": "number",
        "type": "string"
    }
}
```

#### 4.1.5 查询社团列表
- **接口路径**: `/api/admin/club/list`
- **请求方式**: GET
- **权限要求**: ADMIN, COLLEGE_ADMIN, DEPARTMENT_ADMIN, CLUB_ADMIN
- **请求参数**:
  - keyword: 关键字（可选，用于搜索）
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "clubId": "number",
            "name": "string",
            "description": "string",
            "collegeId": "number",
            "type": "string"
        }
    ]
}
```

### 4.2 社团成员管理 (ClubUserController)
- **接口路径**: `/api/admin/club/user`
- **功能**: 社团成员管理相关接口
- **权限要求**: 需要相应角色权限

#### 4.2.1 添加社团成员
- **接口路径**: `/api/admin/club/user/add`
- **请求方式**: POST
- **权限要求**: CLUB_ADMIN
- **请求参数**:
  - clubId: 社团ID
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "成员已加入社团",
    "data": null
}
```

#### 4.2.2 移除社团成员
- **接口路径**: `/api/admin/club/user/remove`
- **请求方式**: DELETE
- **权限要求**: CLUB_ADMIN, COLLEGE_ADMIN
- **请求参数**:
  - clubId: 社团ID
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "成员已移除",
    "data": null
}
```

#### 4.2.3 查询社团成员列表
- **接口路径**: `/api/admin/club/user/list`
- **请求方式**: GET
- **权限要求**: ADMIN, COLLEGE_ADMIN, DEPARTMENT_ADMIN
- **请求参数**:
  - clubId: 社团ID
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "userId": "number",
            "username": "string",
            "role": "string"
        }
    ]
}
```

#### 4.2.4 查看我的社团成员
- **接口路径**: `/api/admin/club/user/my-club-members`
- **请求方式**: GET
- **权限要求**: CLUB_ADMIN
- **请求参数**:
  - clubId: 社团ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "userId": "number",
            "username": "string",
            "role": "string"
        }
    ]
}
```

### 4.3 学院管理 (CollegeController)
- **接口路径**: `/api/admin/college`
- **功能**: 学院信息管理相关接口
- **权限要求**: 需要相应角色权限

#### 4.3.1 添加学院
- **接口路径**: `/api/admin/college/add`
- **请求方式**: POST
- **权限要求**: ADMIN, COLLEGE_ADMIN
- **请求参数**:
```json
{
    "name": "string",        // 学院名称
    "description": "string", // 学院描述
    "code": "string"        // 学院代码
}
```
- **响应结果**:
```json
{
    "code": 200,
    "msg": "学院添加成功",
    "data": null
}
```

#### 4.3.2 更新学院信息
- **接口路径**: `/api/admin/college/update`
- **请求方式**: PUT
- **权限要求**: ADMIN, COLLEGE_ADMIN
- **请求参数**:
```json
{
    "collegeId": "number",   // 学院ID
    "name": "string",        // 学院名称
    "description": "string", // 学院描述
    "code": "string"        // 学院代码
}
```
- **响应结果**:
```json
{
    "code": 200,
    "msg": "学院更新成功",
    "data": null
}
```

#### 4.3.3 删除学院
- **接口路径**: `/api/admin/college/delete/{collegeId}`
- **请求方式**: DELETE
- **权限要求**: ADMIN, COLLEGE_ADMIN
- **路径参数**:
  - collegeId: 学院ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "学院删除成功",
    "data": null
}
```

#### 4.3.4 获取学院详情
- **接口路径**: `/api/admin/college/{collegeId}`
- **请求方式**: GET
- **权限要求**: ADMIN, COLLEGE_ADMIN
- **路径参数**:
  - collegeId: 学院ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "collegeId": "number",
        "name": "string",
        "description": "string",
        "code": "string"
    }
}
```

#### 4.3.5 获取我的学院信息
- **接口路径**: `/api/admin/college/my-college`
- **请求方式**: GET
- **权限要求**: DEPARTMENT_ADMIN
- **请求参数**:
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "collegeId": "number",
        "name": "string",
        "description": "string",
        "code": "string"
    }
}
```

#### 4.3.6 查询学院列表
- **接口路径**: `/api/admin/college/list`
- **请求方式**: GET
- **权限要求**: ADMIN, COLLEGE_ADMIN, DEPARTMENT_ADMIN
- **请求参数**:
  - keyword: 关键字（可选，用于搜索）
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "collegeId": "number",
            "name": "string",
            "description": "string",
            "code": "string"
        }
    ]
}
```

#### 4.3.7 指派学院负责人
- **接口路径**: `/api/admin/college/assign`
- **请求方式**: POST
- **权限要求**: ADMIN, COLLEGE_ADMIN
- **请求参数**:
  - collegeId: 学院ID
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "负责人指派成功",
    "data": null
}
```

#### 4.3.8 移除学院负责人
- **接口路径**: `/api/admin/college/remove`
- **请求方式**: DELETE
- **权限要求**: ADMIN, COLLEGE_ADMIN
- **请求参数**:
  - collegeId: 学院ID
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "负责人移除成功",
    "data": null
}
```

#### 4.3.9 获取学院负责人
- **接口路径**: `/api/admin/college/getleader/{collegeId}`
- **请求方式**: GET
- **权限要求**: ADMIN, COLLEGE_ADMIN, DEPARTMENT_ADMIN
- **路径参数**:
  - collegeId: 学院ID
- **请求参数**:
  - userId: 用户ID
- **响应结果**:
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "userId": "number",
        "username": "string",
        "role": "string"
    }
}
```

## 通用说明

1. **认证方式**：
   - 除登录接口外，所有接口都需要在请求头中携带 JWT Token
   - Token 格式：`Authorization: Bearer <token>`

2. **响应格式**：
   - 所有接口统一使用 `AjaxResult` 封装响应
   - 成功响应示例：
   ```json
   {
       "code": 200,
       "msg": "操作成功",
       "data": {}
   }
   ```
   - 失败响应示例：
   ```json
   {
       "code": 500,
       "msg": "操作失败",
       "data": null
   }
   ```

3. **请求方式**：
   - 查询类接口使用 GET
   - 创建类接口使用 POST
   - 更新类接口使用 PUT
   - 删除类接口使用 DELETE

4. **数据格式**：
   - 请求和响应均使用 JSON 格式
   - 日期时间格式统一使用 ISO 8601 标准