# 前后端接口差异对比报告

> 分析时间：2026-03-30
> 前端目录：java-frontend/src/api/
> 后端目录：java-backend/src/main/java/com/lesingle/creation/controller/

---

## 核心问题总结

### 1. 路径前缀不一致（最严重）

| 模块 | 前端路径前缀 | 后端路径前缀 | 差异 |
|:------|:------------|:------------|:-----|
| 竞赛管理 | `/contests` | `/api/contests` | 缺少 `/api` |
| 作业管理 | `/homework/homeworks` | `/api/homeworks` | 路径结构不同 |
| AI 3D | `/ai-3d` | `/api/ai-3d` | 缺少 `/api` |

**影响**：前端所有 API 请求都无法匹配到后端接口

### 2. HTTP 方法不一致

| 模块 | 前端方法 | 后端方法 | 接口 |
|:------|:--------|:--------|:-----|
| 竞赛更新 | PATCH | PUT | `/contests/{id}` |
| 团队更新 | PATCH | PUT | `/contests/teams/{id}` |
| 评审规则更新 | PATCH | PUT | `/contests/review-rules/{id}` |
| 作业更新 | PATCH | PUT | `/homework/homeworks/{id}` |
| AI 3D 重试 | POST | PUT | `/ai-3d/tasks/{id}/retry` |

### 3. 接口路径不一致

| 模块 | 前端路径 | 后端路径 | 说明 |
|:------|:--------|:--------|:-----|
| 作品列表 | `/contests/works` | `/api/contests/works/page` | 后端多了 `/page` |
| 作品提交 | `/contests/works/submit` | `/api/contests/works` | 路径不同 |
| 作业列表 | `/homework/homeworks` | `/api/homeworks/page` | 后端多了 `/page` |
| 作业提交 | `/homework/submissions` | `/api/homeworks/submit` | 路径不同 |
| 作业批改 | `/homework/scores` | `/api/homeworks/review` | 路径不同 |
| AI 3D 创建 | `/ai-3d/generate` | `/api/ai-3d` | 路径不同 |
| AI 3D 列表 | `/ai-3d/tasks` | `/api/ai-3d/page` | 后端多了 `/page` |

---

## 模块详细对比

### 一、竞赛管理模块 (contests.ts)

#### 1.1 活动管理 API

| 前端接口 | 后端接口 | 状态 | 差异说明 |
|:---------|:---------|:-----|:---------|
| GET `/contests/stats` | GET `/api/contests/stats` | ⚠️ | 路径前缀不一致 |
| GET `/contests` | GET `/api/contests` | ⚠️ | 路径前缀不一致 |
| GET `/contests/my-contests` | ❌ | ❌ | **后端缺失** |
| GET `/contests/{id}` | GET `/api/contests/{id}` | ⚠️ | 路径前缀不一致 |
| POST `/contests` | POST `/api/contests` | ⚠️ | 路径前缀不一致 |
| PATCH `/contests/{id}` | PUT `/api/contests/{id}` | ⚠️ | 方法不同 + 路径前缀 |
| PATCH `/contests/{id}/publish` | PATCH `/api/contests/{id}/publish` | ⚠️ | 路径前缀不一致 |
| PATCH `/contests/{id}/finish` | PATCH `/api/contests/{id}/finish` | ⚠️ | 路径前缀不一致 |
| PATCH `/contests/{id}/reopen` | PATCH `/api/contests/{id}/reopen` | ⚠️ | 路径前缀不一致 |
| DELETE `/contests/{id}` | DELETE `/api/contests/{id}` | ⚠️ | 路径前缀不一致 |

#### 1.2 报名管理 API

| 前端接口 | 后端接口 | 状态 | 差异说明 |
|:---------|:---------|:-----|:---------|
| GET `/contests/registrations/stats` | GET `/api/contests/registrations/stats` | ⚠️ | 路径前缀不一致 |
| GET `/contests/registrations` | GET `/api/contests/registrations` | ⚠️ | 路径前缀不一致 |
| GET `/contests/registrations/my/{contestId}` | GET `/api/contests/registrations/my/{contestId}` | ⚠️ | 路径前缀不一致 |
| GET `/contests/registrations/{id}` | GET `/api/contests/registrations/{id}` | ⚠️ | 路径前缀不一致 |
| POST `/contests/registrations` | POST `/api/contests/registrations` | ⚠️ | 路径前缀不一致 |
| POST `/contests/registrations/{id}/teachers` | POST `/api/contests/registrations/{id}/teachers` | ⚠️ | 路径前缀不一致 |
| DELETE `/contests/registrations/{id}/teachers/{teacherUserId}` | ❌ | ❌ | **后端缺失** |
| PATCH `/contests/registrations/{id}/review` | PATCH `/api/contests/registrations/{id}/review` | ⚠️ | 路径前缀不一致 |
| DELETE `/contests/registrations/{id}` | DELETE `/api/contests/registrations/{id}` | ⚠️ | 路径前缀不一致 |

#### 1.3 团队管理 API

| 前端接口 | 后端接口 | 状态 | 差异说明 |
|:---------|:---------|:-----|:---------|
| GET `/contests/teams/contest/{contestId}` | ❌ | ❌ | **后端缺失** |
| GET `/contests/teams/{id}` | GET `/api/contests/teams/{id}` | ⚠️ | 路径前缀不一致 |
| POST `/contests/teams` | POST `/api/contests/teams` | ⚠️ | 路径前缀不一致 |
| PATCH `/contests/teams/{id}` | PUT `/api/contests/teams/{id}` | ⚠️ | 方法不同 + 路径前缀 |
| POST `/contests/teams/{teamId}/members` | POST `/api/contests/teams/{id}/members` | ⚠️ | 参数名不同 + 路径前缀 |
| DELETE `/contests/teams/{teamId}/members/{userId}` | DELETE `/api/contests/teams/{id}/members/{userId}` | ⚠️ | 参数名不同 + 路径前缀 |
| DELETE `/contests/teams/{id}` | DELETE `/api/contests/teams/{id}` | ⚠️ | 路径前缀不一致 |

#### 1.4 作品管理 API

| 前端接口 | 后端接口 | 状态 | 差异说明 |
|:---------|:---------|:-----|:---------|
| GET `/contests/works/stats` | GET `/api/contests/works/stats` | ⚠️ | 路径前缀不一致 |
| GET `/contests/works` | GET `/api/contests/works/page` | ⚠️ | **路径不同** + 前缀 |
| GET `/contests/works/guided` | ❌ | ❌ | **后端缺失** |
| GET `/contests/works/{id}` | GET `/api/contests/works/{id}` | ⚠️ | 路径前缀不一致 |
| POST `/contests/works/submit` | POST `/api/contests/works` | ⚠️ | **路径不同** + 前缀 |
| GET `/contests/works/registration/{id}/versions` | ❌ | ❌ | **后端缺失** |
| DELETE `/contests/works/{id}` | DELETE `/api/contests/works/{id}` | ⚠️ | 路径前缀不一致 |

#### 1.5 评审管理 API

| 前端接口 | 后端接口 | 状态 | 差异说明 |
|:---------|:---------|:-----|:---------|
| POST `/contests/reviews/assign` | POST `/api/contests/reviews/assign` | ⚠️ | 路径前缀不一致 |
| POST `/contests/reviews/batch-assign` | POST `/api/contests/reviews/batch-assign` | ⚠️ | 路径前缀不一致 |
| POST `/contests/reviews/auto-assign` | ❌ | ❌ | **后端缺失** |
| POST `/contests/reviews/score` | POST `/api/contests/reviews/score` | ⚠️ | 路径前缀不一致 |
| PATCH `/contests/reviews/score/{scoreId}` | PUT `/api/contests/reviews/score/{scoreId}` | ⚠️ | 方法不同 + 路径前缀 |
| GET `/contests/reviews/assigned` | GET `/api/contests/reviews/my-assignments` | ⚠️ | **路径不同** + 前缀 |
| GET `/contests/reviews/progress/{contestId}` | ❌ | ❌ | **后端缺失** |
| GET `/contests/reviews/work-status/{contestId}` | ❌ | ❌ | **后端缺失** |
| GET `/contests/reviews/work/{workId}/scores` | GET `/api/contests/reviews/works/{workId}/scores` | ⚠️ | 路径不同 + 前缀 |
| GET `/contests/reviews/work/{workId}/final-score` | ❌ | ❌ | **后端缺失** |
| POST `/contests/reviews/replace-judge` | ❌ | ❌ | **后端缺失** |
| GET `/contests/reviews/judge/contests` | ❌ | ❌ | **后端缺失** |
| GET `/contests/reviews/judge/contests/{contestId}/works` | ❌ | ❌ | **后端缺失** |

#### 1.6 公告管理 API

| 前端接口 | 后端接口 | 状态 | 差异说明 |
|:---------|:---------|:-----|:---------|
| GET `/contests/notices/contest/{contestId}` | GET `/api/contests/notices/contest/{contestId}` | ⚠️ | 路径前缀不一致 |
| GET `/contests/notices` | GET `/api/contests/notices` | ⚠️ | 路径前缀不一致 |
| GET `/contests/notices/{id}` | GET `/api/contests/notices/{id}` | ⚠️ | 路径前缀不一致 |
| POST `/contests/notices` | POST `/api/contests/notices` | ⚠️ | 路径前缀不一致 |
| PATCH `/contests/notices/{id}` | PUT `/api/contests/notices/{id}` | ⚠️ | 方法不同 + 路径前缀 |
| DELETE `/contests/notices/{id}` | DELETE `/api/contests/notices/{id}` | ⚠️ | 路径前缀不一致 |

#### 1.7 评委管理 API

| 前端接口 | 后端接口 | 状态 | 差异说明 |
|:---------|:---------|:-----|:---------|
| GET `/contests/judges/contest/{contestId}` | GET `/api/contests/judges/contest/{contestId}` | ⚠️ | 路径前缀不一致 |
| GET `/contests/judges/{id}` | GET `/api/contests/judges/{id}` | ⚠️ | 路径前缀不一致 |
| POST `/contests/judges` | POST `/api/contests/judges` | ⚠️ | 路径前缀不一致 |
| PATCH `/contests/judges/{id}` | PUT `/api/contests/judges/{id}` | ⚠️ | 方法不同 + 路径前缀 |
| DELETE `/contests/judges/{id}` | DELETE `/api/contests/judges/{id}` | ⚠️ | 路径前缀不一致 |

#### 1.8 评审规则 API

| 前端接口 | 后端接口 | 状态 | 差异说明 |
|:---------|:---------|:-----|:---------|
| GET `/contests/review-rules` | GET `/api/contests/review-rules` | ⚠️ | 路径前缀不一致 |
| GET `/contests/review-rules/select` | GET `/api/contests/review-rules/select` | ⚠️ | 路径前缀不一致 |
| GET `/contests/review-rules/{id}` | GET `/api/contests/review-rules/{id}` | ⚠️ | 路径前缀不一致 |
| POST `/contests/review-rules` | POST `/api/contests/review-rules` | ⚠️ | 路径前缀不一致 |
| PATCH `/contests/review-rules/{id}` | PUT `/api/contests/review-rules/{id}` | ⚠️ | 方法不同 + 路径前缀 |
| DELETE `/contests/review-rules/{id}` | DELETE `/api/contests/review-rules/{id}` | ⚠️ | 路径前缀不一致 |
| POST `/contests/review-rules/dimensions` | POST `/api/contests/review-rules/dimensions` | ⚠️ | 路径前缀不一致 |
| PATCH `/contests/review-rules/dimensions/{id}` | PUT `/api/contests/review-rules/dimensions/{id}` | ⚠️ | 方法不同 + 路径前缀 |
| DELETE `/contests/review-rules/dimensions/{id}` | DELETE `/api/contests/review-rules/dimensions/{id}` | ⚠️ | 路径前缀不一致 |

#### 1.9 成果管理 API

| 前端接口 | 后端接口 | 状态 | 差异说明 |
|:---------|:---------|:-----|:---------|
| POST `/contests/results/{contestId}/calculate-scores` | POST `/api/contests/results/{contestId}/calculate-scores` | ⚠️ | 路径前缀不一致 |
| POST `/contests/results/{contestId}/calculate-rankings` | POST `/api/contests/results/{contestId}/calculate-rankings` | ⚠️ | 路径前缀不一致 |
| PATCH `/contests/results/work/{workId}/award` | PATCH `/api/contests/results/work/{workId}/award` | ⚠️ | 路径前缀不一致 |
| POST `/contests/results/{contestId}/batch-set-awards` | POST `/api/contests/results/{contestId}/batch-set-awards` | ⚠️ | 路径前缀不一致 |
| POST `/contests/results/{contestId}/auto-set-awards` | POST `/api/contests/results/{contestId}/auto-set-awards` | ⚠️ | 路径前缀不一致 |
| POST `/contests/results/{contestId}/publish` | POST `/api/contests/results/{contestId}/publish` | ⚠️ | 路径前缀不一致 |
| POST `/contests/results/{contestId}/unpublish` | POST `/api/contests/results/{contestId}/unpublish` | ⚠️ | 路径前缀不一致 |
| GET `/contests/results/{contestId}` | GET `/api/contests/results/{contestId}` | ⚠️ | 路径前缀不一致 |
| GET `/contests/results/{contestId}/summary` | GET `/api/contests/results/{contestId}/summary` | ⚠️ | 路径前缀不一致 |

---

### 二、作业管理模块 (homework.ts)

#### 2.1 作业管理 API

| 前端接口 | 后端接口 | 状态 | 差异说明 |
|:---------|:---------|:-----|:---------|
| GET `/homework/homeworks` | GET `/api/homeworks/page` | ❌ | **路径结构完全不同** |
| GET `/homework/homeworks/my` | ❌ | ❌ | **后端缺失** |
| GET `/homework/homeworks/{id}` | GET `/api/homeworks/{id}` | ⚠️ | 路径前缀不一致 |
| POST `/homework/homeworks` | POST `/api/homeworks` | ⚠️ | 路径前缀不一致 |
| PATCH `/homework/homeworks/{id}` | PUT `/api/homeworks/{id}` | ⚠️ | 方法不同 + 路径前缀 |
| POST `/homework/homeworks/{id}/publish` | GET `/api/homeworks/{id}/publish` | ❌ | **方法不同** + 路径前缀 |
| POST `/homework/homeworks/{id}/unpublish` | ❌ | ❌ | **后端缺失** |
| DELETE `/homework/homeworks/{id}` | DELETE `/api/homeworks/{id}` | ⚠️ | 路径前缀不一致 |

#### 2.2 提交记录 API

| 前端接口 | 后端接口 | 状态 | 差异说明 |
|:---------|:---------|:-----|:---------|
| GET `/homework/submissions` | ❌ | ❌ | **后端缺失** |
| GET `/homework/submissions/{id}` | ❌ | ❌ | **后端缺失** |
| GET `/homework/submissions/class-tree` | ❌ | ❌ | **后端缺失** |
| GET `/homework/submissions/my/{homeworkId}` | ❌ | ❌ | **后端缺失** |
| POST `/homework/submissions` | POST `/api/homeworks/submit` | ❌ | **路径不同** + 前缀 |

#### 2.3 评审规则 API

| 前端接口 | 后端接口 | 状态 | 差异说明 |
|:---------|:---------|:-----|:---------|
| GET `/homework/review-rules` | GET `/api/homeworks/review-rules` | ⚠️ | 路径前缀不一致 |
| GET `/homework/review-rules/select` | ❌ | ❌ | **后端缺失** |
| GET `/homework/review-rules/{id}` | GET `/api/homeworks/review-rules/{id}` | ⚠️ | 路径前缀不一致 |
| POST `/homework/review-rules` | POST `/api/homeworks/review-rules` | ⚠️ | 路径前缀不一致 |
| PATCH `/homework/review-rules/{id}` | ❌ | ❌ | **后端缺失** |
| DELETE `/homework/review-rules/{id}` | ❌ | ❌ | **后端缺失** |

#### 2.4 评分 API

| 前端接口 | 后端接口 | 状态 | 差异说明 |
|:---------|:---------|:-----|:---------|
| POST `/homework/scores` | POST `/api/homeworks/review` | ❌ | **路径不同** + 前缀 |
| POST `/homework/scores/{submissionId}/violation` | ❌ | ❌ | **后端缺失** |
| POST `/homework/scores/{submissionId}/reset` | ❌ | ❌ | **后端缺失** |

---

### 三、AI 3D 模块 (ai-3d.ts)

| 前端接口 | 后端接口 | 状态 | 差异说明 |
|:---------|:---------|:-----|:---------|
| POST `/ai-3d/generate` | POST `/api/ai-3d` | ❌ | **路径不同** + 前缀 |
| GET `/ai-3d/tasks` | GET `/api/ai-3d/page` | ❌ | **路径不同** + 前缀 |
| GET `/ai-3d/tasks/{id}` | GET `/api/ai-3d/{id}` | ⚠️ | 路径前缀不一致 |
| POST `/ai-3d/tasks/{id}/retry` | PUT `/api/ai-3d/{id}/retry` | ❌ | **方法不同** + 路径前缀 |
| DELETE `/ai-3d/tasks/{id}` | ❌ | ❌ | **后端缺失** |

---

## 缺失接口汇总

### 后端需要补充的接口（按优先级）

#### P0 - 核心功能缺失

1. **竞赛管理**
   - `GET /api/contests/my-contests` - 我参与的活动列表

2. **作品管理**
   - `GET /api/contests/works/guided` - 教师指导的作品列表
   - `GET /api/contests/works/registration/{id}/versions` - 作品版本列表

3. **评审管理**
   - `POST /api/contests/reviews/auto-assign` - 自动分配评委
   - `GET /api/contests/reviews/progress/{contestId}` - 评审进度统计
   - `GET /api/contests/reviews/work-status/{contestId}` - 作品状态统计
   - `GET /api/contests/reviews/work/{workId}/final-score` - 计算最终得分
   - `POST /api/contests/reviews/replace-judge` - 替换评委
   - `GET /api/contests/reviews/judge/contests` - 评委参与的活动列表
   - `GET /api/contests/reviews/judge/contests/{contestId}/works` - 评委的作品列表

4. **作业管理**
   - `GET /api/homeworks/my` - 我的作业列表（学生端）
   - `POST /api/homeworks/homeworks/{id}/unpublish` - 取消发布作业
   - `GET /api/homeworks/submissions` - 提交记录列表
   - `GET /api/homeworks/submissions/{id}` - 提交记录详情
   - `GET /api/homeworks/submissions/class-tree` - 班级树结构
   - `GET /api/homeworks/submissions/my/{homeworkId}` - 我的提交记录
   - `POST /api/homeworks/scores` - 提交评分
   - `POST /api/homeworks/scores/{submissionId}/violation` - 标记违规
   - `POST /api/homeworks/scores/{submissionId}/reset` - 重置评分

5. **评审规则**
   - `GET /api/homeworks/review-rules/select` - 获取可选的评审规则
   - `PUT /api/homeworks/review-rules/{id}` - 更新评审规则
   - `DELETE /api/homeworks/review-rules/{id}` - 删除评审规则

6. **AI 3D**
   - `DELETE /api/ai-3d/tasks/{id}` - 删除任务

#### P1 - 重要功能缺失

1. **报名管理**
   - `DELETE /api/contests/registrations/{id}/teachers/{teacherUserId}` - 移除指导老师

2. **团队管理**
   - `GET /api/contests/teams/contest/{contestId}` - 按活动查询团队列表

#### P2 - 辅助功能缺失

1. **其他缺失模块**（完全未实现）
   - 认证模块 (Auth)
   - 文件上传模块 (Upload)
   - 系统日志模块 (Logs)
   - 公共接口模块 (Public)
   - 评委管理模块 (Judges Management)
   - 学校组织模块 (School/Grade/Class/Department/Teacher/Student)

---

## 修复方案建议

### 方案一：修改前端 API 路径（推荐）

**优点**：
- 后端遵循标准 RESTful 规范（`/api/` 前缀）
- 后端使用 PUT 进行全量更新，符合 REST 惯例
- 前端只需修改 API 客户端文件

**缺点**：
- 需要修改前端所有 API 文件

**修改内容**：
```typescript
// contests.ts - 所有路径添加 /api 前缀
- request.get("/contests/stats")
+ request.get("/api/contests/stats")

// homework.ts - 调整路径结构
- request.get("/homework/homeworks")
+ request.get("/api/homeworks/page")

- request.post("/homework/submissions")
+ request.post("/api/homeworks/submit")

// ai-3d.ts - 所有路径添加 /api 前缀
- request.post("/ai-3d/generate")
+ request.post("/api/ai-3d/generate")
```

### 方案二：修改后端 Controller

**优点**：
- 前端代码无需修改

**缺点**：
- 后端路径规范不统一
- 需要添加额外的路由映射

**修改内容**：
```java
// ContestController.java - 添加额外路由
@RequestMapping("/contests")  // 新增：兼容前端路径
@RequestMapping("/api/contests")  // 保留：标准路径

// HomeworkController.java - 修改路径
@RequestMapping("/homework/homeworks")  // 修改为与前端一致
@RequestMapping("/api/homeworks")

// 修改 HTTP 方法
@PutMapping("/{id}") → @PatchMapping("/{id}")
```

### 方案三：双向调整（推荐）

**分阶段修复**：

1. **阶段一**：后端补充缺失接口（P0 优先级）
2. **阶段二**：前端统一添加 `/api` 前缀
3. **阶段三**：统一 HTTP 方法（更新使用 PUT）

---

## 修改清单

### 前端需要修改的文件

| 文件 | 修改内容 | 行数 |
|:------|:--------|:-----|
| `src/api/contests.ts` | 所有路径添加 `/api` 前缀，共 47 个接口 | ~1400 行 |
| `src/api/homework.ts` | 路径结构调整，共 24 个接口 | ~400 行 |
| `src/api/ai-3d.ts` | 所有路径添加 `/api` 前缀，共 5 个接口 | ~120 行 |

### 后端需要修改的 Controller

| Controller | 修改内容 |
|:----------|:--------|
| `ContestController.java` | 无需修改路径，需保持 `/api/contests` |
| `HomeworkController.java` | 无需修改路径，已使用 `/api/homeworks` |
| `AI3DTaskController.java` | 无需修改路径，已使用 `/api/ai-3d` |

### 后端需要补充的接口

共需补充 **28 个接口**，分布在以下 Controller：

| Controller | 需补充接口数 |
|:----------|:------------|
| `ContestController.java` | 1 |
| `ContestWorkController.java` | 2 |
| `ContestReviewController.java` | 7 |
| `HomeworkController.java` | 11 |
| `HomeworkReviewRuleController.java` | 3 |
| `AI3DTaskController.java` | 1 |
| `ContestRegistrationController.java` | 1 |
| `ContestTeamController.java` | 1 |
| **新增 Controller** | |
| `AuthController.java` | 认证模块（完整） |
| `UploadController.java` | 文件上传（完整） |
| `SysLogController.java` | 系统日志（完整） |
| `PublicController.java` | 公共接口（完整） |
| `SchoolController.java` | 学校组织模块（完整） |

---

## 下一步行动

1. **确认 API 规范**
   - 确认前后端统一使用 `/api/` 前缀
   - 确认更新接口统一使用 PUT 方法

2. **补充缺失接口**（后端）
   - 按优先级分批实现缺失接口
   - 优先补充 P0 核心功能接口

3. **修改前端路径**（前端）
   - 统一添加 `/api` 前缀
   - 调整作业模块路径结构

4. **联调测试**
   - 修复后进行前后端联调
   - 使用 Swagger 文档验证接口

5. **生成 API 文档**
   - 使用 Swagger/OpenAPI 生成标准文档
   - 作为前后端对接的标准