# 校园活动系统 - 后端 API 接口文档

## 基本信息

- **基础路径**: `/api/v1`
- **认证方式**: JWT Token (Bearer Token)
- **响应格式**: JSON

## 统一响应格式

所有接口返回统一的响应格式：

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": 1736620800000
}
```

### 状态码说明

| 状态码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未认证或Token已过期 |
| 403 | 无权限访问 |
| 404 | 资源不存在 |
| 409 | 业务冲突 |
| 500 | 服务器内部错误 |

### 业务错误码

| 错误码 | 说明 |
|--------|------|
| 1001 | 用户不存在 |
| 1002 | 用户已存在 |
| 1003 | 密码错误 |
| 1004 | 用户名或密码错误 |
| 1005 | 学号已存在 |
| 2001 | 活动不存在 |
| 2002 | 活动已开始，无法取消报名 |
| 2003 | 活动时间冲突 |
| 2004 | 活动报名人数已满 |
| 3001 | 报名记录不存在 |
| 3002 | 您已报名该活动 |
| 3003 | 您未报名该活动 |
| 4001 | 签到失败 |
| 4002 | 已签到 |
| 4003 | 签到时间已过期 |
| 5001 | 您已评价该活动 |
| 5002 | 评价记录不存在 |
| 5003 | 您未参加该活动，无法评价 |

---

## 一、认证模块 (`/api/v1/auth`)

### 1.1 用户注册

**接口地址**: `POST /api/v1/auth/register`

**请求权限**: 无需认证

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 验证规则 |
|--------|------|------|------|----------|
| username | String | 是 | 用户名 | 3-50个字符 |
| password | String | 是 | 密码 | 6-20个字符 |
| name | String | 是 | 姓名 | 最多50个字符 |
| studentId | String | 否 | 学号 | 10-20位数字 |
| email | String | 否 | 邮箱 | 邮箱格式 |
| phone | String | 否 | 手机号 | 11位手机号 |

**请求示例**:
```json
{
  "username": "student001",
  "password": "123456",
  "name": "张三",
  "studentId": "2021000001",
  "email": "zhangsan@example.com",
  "phone": "13800138000"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "注册成功",
  "data": null,
  "timestamp": 1736620800000
}
```

---

### 1.2 用户登录

**接口地址**: `POST /api/v1/auth/login`

**请求权限**: 无需认证

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | String | 是 | 用户名 |
| password | String | 是 | 密码 |

**请求示例**:
```json
{
  "username": "student001",
  "password": "123456"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600,
    "tokenType": "Bearer",
    "userInfo": {
      "id": 1,
      "username": "student001",
      "name": "张三",
      "role": 0,
      "avatar": null
    }
  },
  "timestamp": 1736620800000
}
```

---

### 1.3 刷新Token

**接口地址**: `POST /api/v1/auth/refresh`

**请求权限**: 无需认证

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| refreshToken | String | 是 | 刷新Token |

**请求示例**:
```json
{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  },
  "timestamp": 1736620800000
}
```

---

### 1.4 获取当前用户信息

**接口地址**: `GET /api/v1/auth/me`

**请求权限**: 需要认证

**请求头**:
```
Authorization: Bearer {accessToken}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "username": "student001",
    "password": "$2a$10$...",
    "name": "张三",
    "studentId": "2021000001",
    "email": "zhangsan@example.com",
    "phone": "13800138000",
    "avatar": null,
    "role": 0,
    "status": 1,
    "createdAt": "2026-01-01T00:00:00",
    "updatedAt": "2026-01-01T00:00:00"
  },
  "timestamp": 1736620800000
}
```

---

### 1.5 修改密码

**接口地址**: `PUT /api/v1/auth/password`

**请求权限**: 需要认证

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 验证规则 |
|--------|------|------|------|----------|
| oldPassword | String | 是 | 旧密码 | 不能为空 |
| newPassword | String | 是 | 新密码 | 6-20个字符 |

**请求示例**:
```json
{
  "oldPassword": "123456",
  "newPassword": "654321"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "密码修改成功",
  "data": null,
  "timestamp": 1736620800000
}
```

---

## 二、活动模块 (`/api/v1/activities`)

### 2.1 获取活动列表

**接口地址**: `GET /api/v1/activities`

**请求权限**: 无需认证

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 默认值 |
|--------|------|------|------|--------|
| current | Long | 否 | 当前页码 | 1 |
| size | Long | 否 | 每页数量 | 10 |
| status | Integer | 否 | 活动状态 | - |
| keyword | String | 否 | 关键词搜索 | - |
| category | String | 否 | 活动分类 | - |
| startDate | LocalDateTime | 否 | 开始时间(yyyy-MM-dd HH:mm:ss) | - |
| endDate | LocalDateTime | 否 | 结束时间(yyyy-MM-dd HH:mm:ss) | - |

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "title": "校园音乐节",
        "description": "一年一度的校园音乐盛会",
        "coverImage": "https://example.com/cover.jpg",
        "startTime": "2026-01-15T19:00:00",
        "endTime": "2026-01-15T22:00:00",
        "registrationDeadline": "2026-01-14T18:00:00",
        "location": "大礼堂",
        "maxParticipants": 500,
        "currentParticipants": 300,
        "status": 1,
        "category": "文艺活动",
        "adminId": 1,
        "adminName": "管理员",
        "averageRating": 4.5,
        "reviewCount": 20,
        "isRegistered": false,
        "createdAt": "2026-01-01T00:00:00"
      }
    ],
    "total": 1,
    "pages": 1,
    "current": 1,
    "size": 10
  },
  "timestamp": 1736620800000
}
```

---

### 2.2 获取活动详情

**接口地址**: `GET /api/v1/activities/{id}`

**请求权限**: 无需认证

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 活动ID |

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "title": "校园音乐节",
    "description": "一年一度的校园音乐盛会",
    "coverImage": "https://example.com/cover.jpg",
    "startTime": "2026-01-15T19:00:00",
    "endTime": "2026-01-15T22:00:00",
    "registrationDeadline": "2026-01-14T18:00:00",
    "location": "大礼堂",
    "maxParticipants": 500,
    "currentParticipants": 300,
    "status": 1,
    "category": "文艺活动",
    "adminId": 1,
    "adminName": "管理员",
    "averageRating": 4.5,
    "reviewCount": 20,
    "isRegistered": false,
    "createdAt": "2026-01-01T00:00:00"
  },
  "timestamp": 1736620800000
}
```

---

### 2.3 创建活动（管理员）

**接口地址**: `POST /api/v1/activities`

**请求权限**: 管理员 (ADMIN)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 验证规则 |
|--------|------|------|------|----------|
| title | String | 是 | 活动名称 | 最多100个字符 |
| description | String | 否 | 活动简介 | 最多2000个字符 |
| coverImage | String | 否 | 封面图片URL | - |
| startTime | LocalDateTime | 是 | 开始时间 | 必须是未来时间 |
| endTime | LocalDateTime | 是 | 结束时间 | - |
| registrationDeadline | LocalDateTime | 否 | 报名截止时间 | - |
| location | String | 是 | 活动地点 | 最多200个字符 |
| maxParticipants | Integer | 是 | 报名人数上限 | 1-10000 |
| category | String | 否 | 活动分类 | 最多50个字符 |

**请求示例**:
```json
{
  "title": "校园音乐节",
  "description": "一年一度的校园音乐盛会",
  "coverImage": "https://example.com/cover.jpg",
  "startTime": "2026-01-15T19:00:00",
  "endTime": "2026-01-15T22:00:00",
  "registrationDeadline": "2026-01-14T18:00:00",
  "location": "大礼堂",
  "maxParticipants": 500,
  "category": "文艺活动"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "创建成功",
  "data": 1,
  "timestamp": 1736620800000
}
```

---

### 2.4 更新活动（管理员）

**接口地址**: `PUT /api/v1/activities/{id}`

**请求权限**: 管理员 (ADMIN)

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 活动ID |

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 验证规则 |
|--------|------|------|------|----------|
| title | String | 是 | 活动名称 | 最多100个字符 |
| description | String | 否 | 活动简介 | 最多2000个字符 |
| coverImage | String | 否 | 封面图片URL | - |
| startTime | LocalDateTime | 是 | 开始时间 | - |
| endTime | LocalDateTime | 是 | 结束时间 | - |
| registrationDeadline | LocalDateTime | 否 | 报名截止时间 | - |
| location | String | 是 | 活动地点 | 最多200个字符 |
| maxParticipants | Integer | 是 | 报名人数上限 | 1-10000 |
| status | Integer | 否 | 活动状态 | - |
| category | String | 否 | 活动分类 | 最多50个字符 |

**响应示例**:
```json
{
  "code": 200,
  "message": "更新成功",
  "data": null,
  "timestamp": 1736620800000
}
```

---

### 2.5 删除活动（管理员）

**接口地址**: `DELETE /api/v1/activities/{id}`

**请求权限**: 管理员 (ADMIN)

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 活动ID |

**响应示例**:
```json
{
  "code": 200,
  "message": "删除成功",
  "data": null,
  "timestamp": 1736620800000
}
```

---

### 2.6 获取日历视图活动

**接口地址**: `GET /api/v1/activities/calendar`

**请求权限**: 无需认证

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| year | Integer | 是 | 年份 |
| month | Integer | 是 | 月份 |

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "title": "校园音乐节",
      "description": "一年一度的校园音乐盛会",
      "coverImage": "https://example.com/cover.jpg",
      "startTime": "2026-01-15T19:00:00",
      "endTime": "2026-01-15T22:00:00",
      "registrationDeadline": "2026-01-14T18:00:00",
      "location": "大礼堂",
      "maxParticipants": 500,
      "currentParticipants": 300,
      "status": 1,
      "category": "文艺活动",
      "adminId": 1,
      "adminName": "管理员",
      "averageRating": 4.5,
      "reviewCount": 20,
      "isRegistered": false,
      "createdAt": "2026-01-01T00:00:00"
    }
  ],
  "timestamp": 1736620800000
}
```

---

### 2.7 检测时间冲突（管理员）

**接口地址**: `POST /api/v1/activities/check-conflict`

**请求权限**: 管理员 (ADMIN)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| startTime | LocalDateTime | 是 | 开始时间 |
| endTime | LocalDateTime | 是 | 结束时间 |
| excludeActivityId | Long | 否 | 排除的活动ID（更新时使用） |

**请求示例**:
```json
{
  "startTime": "2026-01-15T19:00:00",
  "endTime": "2026-01-15T22:00:00",
  "excludeActivityId": 1
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "hasConflict": true,
    "conflictActivities": [
      {
        "id": 2,
        "title": "校园篮球赛",
        "startTime": "2026-01-15T18:00:00",
        "endTime": "2026-01-15T20:00:00"
      }
    ]
  },
  "timestamp": 1736620800000
}
```

---

## 三、报名模块 (`/api/v1/registrations`)

### 3.1 报名活动

**接口地址**: `POST /api/v1/registrations`

**请求权限**: 需要认证

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| activityId | Long | 是 | 活动ID |

**请求示例**:
```json
{
  "activityId": 1
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "报名成功",
  "data": {
    "id": 1,
    "activityId": 1,
    "activityTitle": "校园音乐节",
    "activityStartTime": "2026-01-15T19:00:00",
    "activityEndTime": "2026-01-15T22:00:00",
    "activityLocation": "大礼堂",
    "ticketCode": "TICKET202601150001",
    "ticketPdfUrl": "https://example.com/tickets/TICKET202601150001.pdf",
    "status": 1,
    "createdAt": "2026-01-10T10:00:00",
    "canceledAt": null
  },
  "timestamp": 1736620800000
}
```

---

### 3.2 取消报名

**接口地址**: `DELETE /api/v1/registrations/{id}`

**请求权限**: 需要认证

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 报名记录ID |

**响应示例**:
```json
{
  "code": 200,
  "message": "取消成功",
  "data": null,
  "timestamp": 1736620800000
}
```

---

### 3.3 获取我的报名列表

**接口地址**: `GET /api/v1/registrations/my`

**请求权限**: 需要认证

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 默认值 |
|--------|------|------|------|--------|
| current | Long | 否 | 当前页码 | 1 |
| size | Long | 否 | 每页数量 | 10 |
| status | Integer | 否 | 报名状态 | - |

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "activityId": 1,
        "activityTitle": "校园音乐节",
        "activityStartTime": "2026-01-15T19:00:00",
        "activityEndTime": "2026-01-15T22:00:00",
        "activityLocation": "大礼堂",
        "ticketCode": "TICKET202601150001",
        "ticketPdfUrl": "https://example.com/tickets/TICKET202601150001.pdf",
        "status": 1,
        "createdAt": "2026-01-10T10:00:00",
        "canceledAt": null
      }
    ],
    "total": 1,
    "pages": 1,
    "current": 1,
    "size": 10
  },
  "timestamp": 1736620800000
}
```

---

### 3.4 获取活动报名列表（管理员）

**接口地址**: `GET /api/v1/registrations/activity/{activityId}`

**请求权限**: 管理员 (ADMIN)

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| activityId | Long | 是 | 活动ID |

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 默认值 |
|--------|------|------|------|--------|
| current | Long | 否 | 当前页码 | 1 |
| size | Long | 否 | 每页数量 | 10 |

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "activityId": 1,
        "activityTitle": "校园音乐节",
        "activityStartTime": "2026-01-15T19:00:00",
        "activityEndTime": "2026-01-15T22:00:00",
        "activityLocation": "大礼堂",
        "ticketCode": "TICKET202601150001",
        "ticketPdfUrl": "https://example.com/tickets/TICKET202601150001.pdf",
        "status": 1,
        "createdAt": "2026-01-10T10:00:00",
        "canceledAt": null
      }
    ],
    "total": 1,
    "pages": 1,
    "current": 1,
    "size": 10
  },
  "timestamp": 1736620800000
}
```

---

### 3.5 下载电子票PDF

**接口地址**: `GET /api/v1/registrations/{id}/ticket`

**请求权限**: 需要认证

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 报名记录ID |

**响应**: PDF文件流

**响应头**:
```
Content-Disposition: attachment; filename=ticket.pdf
Content-Type: application/pdf
```

---

## 四、签到模块 (`/api/v1/checkin`)

### 4.1 生成签到二维码（管理员）

**接口地址**: `POST /api/v1/checkin/qrcode/{activityId}`

**请求权限**: 管理员 (ADMIN)

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| activityId | Long | 是 | 活动ID |

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "qrCodeUrl": "https://example.com/qrcode/ACTIVITY1.png",
    "qrCodeContent": "activity:1:2026-01-15T19:00:00",
    "expiresAt": "2026-01-15T23:00:00"
  },
  "timestamp": 1736620800000
}
```

---

### 4.2 学生扫码签到

**接口地址**: `POST /api/v1/checkin/scan`

**请求权限**: 需要认证

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| qrCodeContent | String | 是 | 二维码内容 |

**请求示例**:
```json
{
  "qrCodeContent": "activity:1:2026-01-15T19:00:00"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "签到成功",
  "data": {
    "id": 1,
    "userId": 1,
    "userName": "张三",
    "studentId": "2021000001",
    "activityId": 1,
    "checkInTime": "2026-01-15T19:30:00",
    "checkInMethod": 1
  },
  "timestamp": 1736620800000
}
```

---

### 4.3 管理员扫学生票签到

**接口地址**: `POST /api/v1/checkin/ticket`

**请求权限**: 管理员 (ADMIN)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| activityId | Long | 是 | 活动ID |
| ticketCode | String | 是 | 电子票号 |

**请求示例**:
```json
{
  "activityId": 1,
  "ticketCode": "TICKET202601150001"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "签到成功",
  "data": {
    "id": 1,
    "userId": 1,
    "userName": "张三",
    "studentId": "2021000001",
    "activityId": 1,
    "checkInTime": "2026-01-15T19:30:00",
    "checkInMethod": 2
  },
  "timestamp": 1736620800000
}
```

---

### 4.4 获取活动签到列表（管理员）

**接口地址**: `GET /api/v1/checkin/activity/{activityId}`

**请求权限**: 管理员 (ADMIN)

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| activityId | Long | 是 | 活动ID |

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 默认值 |
|--------|------|------|------|--------|
| current | Long | 否 | 当前页码 | 1 |
| size | Long | 否 | 每页数量 | 10 |

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "userId": 1,
        "userName": "张三",
        "studentId": "2021000001",
        "activityId": 1,
        "checkInTime": "2026-01-15T19:30:00",
        "checkInMethod": 1
      }
    ],
    "total": 1,
    "pages": 1,
    "current": 1,
    "size": 10
  },
  "timestamp": 1736620800000
}
```

---

## 五、评价模块 (`/api/v1/reviews`)

### 5.1 提交评价

**接口地址**: `POST /api/v1/reviews`

**请求权限**: 需要认证

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 验证规则 |
|--------|------|------|------|----------|
| activityId | Long | 是 | 活动ID | - |
| rating | Integer | 是 | 评分 | 1-5分 |
| content | String | 否 | 评论内容 | 最多500个字符 |

**请求示例**:
```json
{
  "activityId": 1,
  "rating": 5,
  "content": "非常精彩的活动！"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "评价成功",
  "data": {
    "id": 1,
    "userId": 1,
    "userName": "张三",
    "userAvatar": null,
    "activityId": 1,
    "activityTitle": "校园音乐节",
    "rating": 5,
    "content": "非常精彩的活动！",
    "createdAt": "2026-01-16T10:00:00"
  },
  "timestamp": 1736620800000
}
```

---

### 5.2 获取活动评价列表

**接口地址**: `GET /api/v1/reviews/activity/{activityId}`

**请求权限**: 无需认证

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| activityId | Long | 是 | 活动ID |

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 默认值 |
|--------|------|------|------|--------|
| current | Long | 否 | 当前页码 | 1 |
| size | Long | 否 | 每页数量 | 10 |

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "userId": 1,
        "userName": "张三",
        "userAvatar": null,
        "activityId": 1,
        "activityTitle": "校园音乐节",
        "rating": 5,
        "content": "非常精彩的活动！",
        "createdAt": "2026-01-16T10:00:00"
      }
    ],
    "total": 1,
    "pages": 1,
    "current": 1,
    "size": 10
  },
  "timestamp": 1736620800000
}
```

---

### 5.3 获取我的评价列表

**接口地址**: `GET /api/v1/reviews/my`

**请求权限**: 需要认证

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 默认值 |
|--------|------|------|------|--------|
| current | Long | 否 | 当前页码 | 1 |
| size | Long | 否 | 每页数量 | 10 |

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": 1,
        "userId": 1,
        "userName": "张三",
        "userAvatar": null,
        "activityId": 1,
        "activityTitle": "校园音乐节",
        "rating": 5,
        "content": "非常精彩的活动！",
        "createdAt": "2026-01-16T10:00:00"
      }
    ],
    "total": 1,
    "pages": 1,
    "current": 1,
    "size": 10
  },
  "timestamp": 1736620800000
}
```

---

## 六、统计模块 (`/api/v1/statistics`)

### 6.1 获取活动统计数据（管理员）

**接口地址**: `GET /api/v1/statistics/activity/{activityId}`

**请求权限**: 管理员 (ADMIN)

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| activityId | Long | 是 | 活动ID |

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "activityId": 1,
    "activityTitle": "校园音乐节",
    "registeredCount": 300,
    "checkedInCount": 250,
    "checkInRate": 0.8333,
    "reviewCount": 20,
    "averageRating": 4.5,
    "ratingDistribution": {
      "1": 0,
      "2": 1,
      "3": 3,
      "4": 6,
      "5": 10
    }
  },
  "timestamp": 1736620800000
}
```

---

### 6.2 导出活动数据（管理员）

**接口地址**: `GET /api/v1/statistics/activity/{activityId}/export`

**请求权限**: 管理员 (ADMIN)

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| activityId | Long | 是 | 活动ID |

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 默认值 |
|--------|------|------|------|--------|
| format | String | 否 | 导出格式 | excel |

**响应**: 文件流 (Excel或PDF)

---

### 6.3 获取总体统计（管理员）

**接口地址**: `GET /api/v1/statistics/overview`

**请求权限**: 管理员 (ADMIN)

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "totalActivities": 50,
    "totalRegistrations": 1000,
    "totalCheckIns": 800,
    "totalReviews": 500,
    "averageRating": 4.3,
    "monthlyStats": [
      {
        "month": "2026-01",
        "activityCount": 10,
        "registrationCount": 200
      },
      {
        "month": "2026-02",
        "activityCount": 15,
        "registrationCount": 300
      }
    ]
  },
  "timestamp": 1736620800000
}
```

---

## 附录：数据模型说明

### 用户角色 (role)

| 值 | 说明 |
|----|------|
| 0 | 学生 |
| 1 | 管理员 |

### 用户状态 (status)

| 值 | 说明 |
|----|------|
| 0 | 禁用 |
| 1 | 正常 |

### 活动状态 (status)

| 值 | 说明 |
|----|------|
| 0 | 草稿 |
| 1 | 已发布 |
| 2 | 进行中 |
| 3 | 已结束 |
| 4 | 已取消 |

### 报名状态 (status)

| 值 | 说明 |
|----|------|
| 0 | 已取消 |
| 1 | 已报名 |

### 签到方式 (checkInMethod)

| 值 | 说明 |
|----|------|
| 1 | 学生扫码签到 |
| 2 | 管理员扫票签到 |

---

## 接口权限汇总

| 接口路径 | 方法 | 学生 | 管理员 | 说明 |
|----------|------|------|--------|------|
| `/auth/register` | POST | ✓ | ✓ | 公开 |
| `/auth/login` | POST | ✓ | ✓ | 公开 |
| `/auth/refresh` | POST | ✓ | ✓ | 公开 |
| `/auth/me` | GET | ✓ | ✓ | 需要认证 |
| `/auth/password` | PUT | ✓ | ✓ | 需要认证 |
| `/activities` | GET | ✓ | ✓ | 公开 |
| `/activities/{id}` | GET | ✓ | ✓ | 公开 |
| `/activities` | POST | ✗ | ✓ | 仅管理员 |
| `/activities/{id}` | PUT | ✗ | ✓ | 仅管理员 |
| `/activities/{id}` | DELETE | ✗ | ✓ | 仅管理员 |
| `/activities/calendar` | GET | ✓ | ✓ | 公开 |
| `/activities/check-conflict` | POST | ✗ | ✓ | 仅管理员 |
| `/registrations` | POST | ✓ | ✗ | 需要认证 |
| `/registrations/{id}` | DELETE | ✓ | ✗ | 需要认证 |
| `/registrations/my` | GET | ✓ | ✗ | 需要认证 |
| `/registrations/activity/{id}` | GET | ✗ | ✓ | 仅管理员 |
| `/registrations/{id}/ticket` | GET | ✓ | ✓ | 需要认证 |
| `/checkin/qrcode/{id}` | POST | ✗ | ✓ | 仅管理员 |
| `/checkin/scan` | POST | ✓ | ✗ | 需要认证 |
| `/checkin/ticket` | POST | ✗ | ✓ | 仅管理员 |
| `/checkin/activity/{id}` | GET | ✗ | ✓ | 仅管理员 |
| `/reviews` | POST | ✓ | ✗ | 需要认证 |
| `/reviews/activity/{id}` | GET | ✓ | ✓ | 公开 |
| `/reviews/my` | GET | ✓ | ✗ | 需要认证 |
| `/statistics/activity/{id}` | GET | ✗ | ✓ | 仅管理员 |
| `/statistics/activity/{id}/export` | GET | ✗ | ✓ | 仅管理员 |
| `/statistics/overview` | GET | ✗ | ✓ | 仅管理员 |