martial-admin-mini/doc/后端实现对比报告.md

# 后端实现与前端文档对比报告

## 项目概述

### 项目结构

```
D:\workspace\31.比赛项目\project\
├── martial-admin-mini    # 前端原型项目（纯Mock，无API对接）
├── martial-mini          # 另一个小程序项目（已对接后端API）
├── martial-master        # 后端项目（Spring Boot + MyBatis Plus）
└── martial-web          # Web前端项目
```

### 关键发现

1. **martial-admin-mini**（当前项目）是纯前端原型，没有对接任何后端API
2. **martial-mini** 项目已经实现了后端API对接
3. **martial-master** 后端项目已经实现了大部分API接口
4. 后端使用 **BladeX** 框架（基于Spring Boot）

---

## 一、后端技术栈

### 技术框架

| 技术 | 版本/说明 |
|------|----------|
| **基础框架** | Spring Boot |
| **ORM框架** | MyBatis Plus |
| **架构框架** | BladeX 4.0.1.RELEASE |
| **Java版本** | JDK 17 |
| **API文档** | Swagger 3 (OpenAPI) |
| **数据库** | MySQL (推测) |
| **认证方式** | Blade-Auth Token |

### 项目结构

```
martial-master/
├── src/main/java/org/springblade/
│   ├── common/                    # 通用工具类
│   ├── modules/
│   │   ├── auth/                  # 认证模块
│   │   └── martial/               # 武术评分核心模块
│   │       ├── controller/        # 控制器层
│   │       ├── service/           # 服务层
│   │       ├── mapper/            # 数据访问层
│   │       └── pojo/              # 数据对象
│   │           ├── entity/        # 实体类
│   │           ├── vo/            # 视图对象
│   │           └── dto/           # 数据传输对象
│   └── job/                       # 定时任务模块
└── database/                       # 数据库脚本
```

---

## 二、API接口对比

### 2.1 已实现的Controller

| Controller | 路径 | 功能 | 文档要求 | 实现状态 |
|-----------|------|------|---------|---------|
| **MartialJudgeInviteController** | `/martial/judgeInvite` | 裁判邀请码管理 | ✅ | ✅ 已实现 |
| **MartialScoreController** | `/martial/score` | 评分记录管理 | ✅ | ✅ 已实现 |
| **MartialAthleteController** | `/martial/athlete` | 参赛选手管理 | ✅ | ✅ 已实现 |
| **MartialVenueController** | `/martial/venue` | 场地信息管理 | ✅ | ✅ 已实现 |
| **MartialProjectController** | `/martial/project` | 比赛项目管理 | ✅ | ✅ 已实现 |
| **MartialDeductionItemController** | `/martial/deductionItem` | 扣分项配置 | ✅ | ✅ 已实现 |
| **MartialJudgeController** | `/martial/judge` | 评委管理 | ✅ | ✅ 已实现 |
| **MartialJudgeProjectController** | `/martial/judgeProject` | 评委项目关系 | ✅ | ✅ 已实现 |
| **MartialCompetitionController** | `/martial/competition` | 比赛管理 | ✅ | ✅ 已实现 |
| **MartialScheduleController** | `/martial/schedule` | 赛程管理 | - | ✅ 已实现（额外功能） |

### 2.2 接口对比详情

#### 认证模块

**文档定义**:
```
POST /api/auth/login          # 用户登录
POST /api/auth/logout         # 退出登录
GET  /api/auth/verify         # Token验证
```

**后端实现**:
```java
// MartialJudgeInviteController.java
@RequestMapping("/martial/judgeInvite")
- GET  /detail        # 获取邀请码详情
- GET  /list          # 邀请码列表
- POST /submit        # 创建/更新邀请码
- POST /remove        # 删除邀请码
```

**对比结果**: ⚠️ **接口路径不匹配**
- 文档要求: `/api/auth/login`
- 后端实现: `/martial/judgeInvite` (管理接口)
- **缺少**: 小程序专用的登录验证接口

---

#### 评分管理模块

**文档定义**:
```
POST /api/scores                        # 提交评分
GET  /api/scores/{athleteId}            # 获取评分详情
PUT  /api/scores/{athleteId}/modify     # 修改评分（裁判长）
GET  /api/scores/my-records             # 获取我的评分记录
```

**后端实现**:
```java
// MartialScoreController.java
@RequestMapping("/martial/score")
- GET  /detail                  # 评分详情
- GET  /list                    # 评分列表（分页）
- POST /submit                  # 新增或修改评分
- POST /remove                  # 删除评分
- GET  /anomalies               # 获取异常评分列表
- POST /validate                # 批量验证评分
```

**对比结果**: ⚠️ **接口设计不同**
- **共同点**: 都有评分提交、查询、修改功能
- **差异**:
  - 文档使用 RESTful 风格 (POST/GET/PUT)
  - 后端使用统一的 `/submit` 接口
  - 后端多了异常评分和验证功能
- **缺少**:
  - 专门的 `/my-records` 接口
  - 裁判长修改评分的专用接口

---

#### 选手管理模块

**文档定义**:
```
GET /api/athletes                # 获取选手列表（普通评委）
GET /api/athletes/all            # 获取选手列表（裁判长）
GET /api/athletes/{athleteId}    # 获取选手详情
```

**后端实现**:
```java
// MartialAthleteController.java
@RequestMapping("/martial/athlete")
- GET  /detail                  # 选手详情
- GET  /list                    # 选手列表（分页，含VO）
- POST /submit                  # 新增或修改选手
- POST /remove                  # 删除选手
- POST /checkin                 # 选手签到
- POST /complete                # 完成比赛
- POST /status                  # 更新比赛状态
```

**对比结果**: ✅ **基本匹配，功能更丰富**
- 文档中的查询接口可以通过 `/list` 实现（通过参数筛选）
- 后端额外提供了签到、完成、状态更新等功能

---

#### 场地管理模块

**文档定义**:
```
GET /api/venues                 # 获取场地列表
```

**后端实现**:
```java
// MartialVenueController.java
@RequestMapping("/martial/venue")
- GET  /detail                  # 场地详情
- GET  /list                    # 场地列表（分页）
- POST /submit                  # 新增或修改场地
- POST /remove                  # 删除场地
```

**对比结果**: ✅ **完全覆盖**

---

#### 项目管理模块

**文档定义**:
```
GET /api/projects               # 获取项目列表
GET /api/projects/{projectId}   # 获取项目详情
```

**后端实现**:
```java
// MartialProjectController.java
@RequestMapping("/martial/project")
- GET  /detail                  # 项目详情
- GET  /list                    # 项目列表（分页）
- POST /submit                  # 新增或修改项目
- POST /remove                  # 删除项目
```

**对比结果**: ✅ **完全覆盖**

---

#### 扣分项管理模块

**文档定义**:
```
GET /api/deductions             # 获取扣分项列表
```

**后端实现**:
```java
// MartialDeductionItemController.java
@RequestMapping("/martial/deductionItem")
- GET  /detail                  # 扣分项详情
- GET  /list                    # 扣分项列表
- POST /submit                  # 新增或修改扣分项
- POST /remove                  # 删除扣分项
```

**对比结果**: ✅ **完全覆盖**

---

#### 统计分析模块

**文档定义**:
```
GET /api/statistics/match/{matchId}    # 比赛统计
GET /api/statistics/judges             # 评委统计
```

**后端实现**: ❌ **未找到对应Controller**

**对比结果**: ❌ **缺少统计接口**

---

## 三、数据结构对比

### 3.1 评分记录 (Score)

**文档定义 (TypeScript)**:
```typescript
interface Score {
  scoreId: string
  matchId: string
  athleteId: string
  judgeId: string
  projectId: string
  venueId: string
  score: number               // 5.000-10.000
  deductions: Deduction[]     // 扣分项数组
  note?: string
  scoreTime: string
}
```

**后端实现 (Java)**:
```java
@TableName("martial_score")
public class MartialScore extends TenantEntity {
    private Long competitionId;     // ✅ 对应 matchId
    private Long athleteId;         // ✅
    private Long projectId;         // ✅
    private Long scheduleId;        // ⚠️ 文档中没有
    private Long venueId;           // ✅
    private Long judgeId;           // ✅
    private String judgeName;       // ⚠️ 文档中没有
    private BigDecimal score;       // ✅
    private BigDecimal originalScore;  // ⚠️ 用于记录修改前的分数
    private String deductionItems;  // ✅ JSON数组格式
    private String note;            // ✅
    private String modifyReason;    // ⚠️ 修改原因
    private LocalDateTime scoreTime;// ✅
    private LocalDateTime modifyTime;  // ⚠️ 修改时间
    private String ipAddress;       // ⚠️ IP地址记录
}
```

**对比结果**: ✅ **匹配度: 95%**
- **类型映射**: `string` → `Long`, `number` → `BigDecimal`
- **额外字段**: 后端多了 `scheduleId`, `judgeName`, `originalScore`, `modifyReason`, `modifyTime`, `ipAddress`
- **优点**: 后端设计更完善，支持审计和追溯

---

### 3.2 选手信息 (Athlete)

**文档定义**:
```typescript
interface Athlete {
  athleteId: string
  name: string
  gender: 'male' | 'female'
  age?: number
  idCard: string
  team: string
  number: string
  order: number
  projectId: string
  venueId: string
  matchId: string
  photo?: string
  defaultScore?: number
  status: 'waiting' | 'performing' | 'finished'
}
```

**后端实现**:
```java
@TableName("martial_athlete")
public class MartialAthlete extends TenantEntity {
    private Long orderId;           // ⚠️ 订单ID（报名相关）
    private Long competitionId;     // ✅ matchId
    private Long projectId;         // ✅
    private String playerName;      // ✅ name
    private String playerNo;        // ✅ number
    private Integer gender;         // ✅ (1-男, 2-女)
    private Integer age;            // ✅
    private String idCard;          // ✅
    private Integer idCardType;     // ⚠️ 证件类型
    private LocalDate birthDate;    // ⚠️ 出生日期
    private String nation;          // ⚠️ 民族
    private String contactPhone;    // ⚠️ 联系电话
    private String organization;    // ✅ team (单位)
    private Integer organizationType;  // ⚠️ 单位类别
    private String teamName;        // ✅ team
    private String category;        // ⚠️ 组别
    private Integer orderNum;       // ✅ order
    private String introduction;    // ⚠️ 简介
    private String attachments;     // ⚠️ 附件
    private String photoUrl;        // ✅ photo
    private Integer registrationStatus;  // ⚠️ 报名状态
    private Integer competitionStatus;   // ✅ status (0-待出场,1-进行中,2-已完成)
    private BigDecimal totalScore;  // ⚠️ 总分
    private Integer ranking;        // ⚠️ 排名
    private String remark;          // ⚠️ 备注
}
```

**对比结果**: ✅ **匹配度: 90%**
- 核心字段完全匹配
- 后端包含了更多的报名和管理字段
- 状态值映射: `'waiting'` → `0`, `'performing'` → `1`, `'finished'` → `2`

---

### 3.3 场地信息 (Venue)

**文档定义**:
```typescript
interface Venue {
  venueId: string
  venueName: string
  matchId: string
  order: number
  athleteCount: number
  scoredCount: number
  status: 'active' | 'completed' | 'paused'
}
```

**后端实现**:
```java
@TableName("martial_venue")
public class MartialVenue extends TenantEntity {
    private Long competitionId;     // ✅ matchId
    private String venueName;       // ✅
    private String venueCode;       // ⚠️ 场地编码
    private Integer capacity;       // ⚠️ 容纳人数
    private String location;        // ⚠️ 位置
    private String facilities;      // ⚠️ 场地设施
    private Integer status;         // ✅ (0-禁用, 1-启用)
}
```

**对比结果**: ⚠️ **匹配度: 60%**
- **缺少**: `order`, `athleteCount`, `scoredCount` (需要通过查询计算)
- **状态不同**: 文档定义3种状态，后端只有启用/禁用

---

### 3.4 项目信息 (Project)

**文档定义**:
```typescript
interface Project {
  projectId: string
  projectName: string
  matchId: string
  category: string
  order: number
  athleteCount: number
  minScore: 5.0
  maxScore: 10.0
  scoreStep: 0.001
  status: 'upcoming' | 'ongoing' | 'completed'
}
```

**后端实现**:
```java
@TableName("martial_project")
public class MartialProject extends TenantEntity {
    private Long competitionId;         // ✅ matchId
    private String projectName;         // ✅
    private String projectCode;         // ⚠️ 项目编码
    private String category;            // ✅ 组别
    private Integer type;               // ⚠️ 类型(个人/双人/集体)
    private Integer minParticipants;    // ⚠️ 最少参赛人数
    private Integer maxParticipants;    // ⚠️ 最多参赛人数
    private Integer minAge;             // ⚠️ 最小年龄
    private Integer maxAge;             // ⚠️ 最大年龄
    private Integer genderLimit;        // ⚠️ 性别限制
    private Integer estimatedDuration;  // ⚠️ 预估时长
    private BigDecimal price;           // ⚠️ 报名费用
    private BigDecimal difficultyCoefficient;  // ⚠️ 难度系数
    private LocalDateTime registrationDeadline;  // ⚠️ 报名截止时间
    private String description;         // ⚠️ 项目描述
    private Integer sortOrder;          // ✅ order
}
```

**对比结果**: ⚠️ **匹配度: 65%**
- **缺少**: `minScore`, `maxScore`, `scoreStep`, `athleteCount`, `status`
- 后端侧重于项目的报名和管理配置
- 评分范围等信息可能在其他地方配置

---

### 3.5 裁判邀请码 (JudgeInvite)

**文档定义**: 无明确定义，但登录需要邀请码

**后端实现**:
```java
@TableName("martial_judge_invite")
public class MartialJudgeInvite extends TenantEntity {
    private Long competitionId;         // 赛事ID
    private Long judgeId;               // 裁判ID
    private String inviteCode;          // 邀请码
    private String role;                // 角色 (judge/chief_judge)
    private Long venueId;               // 分配场地ID
    private String projects;            // 分配项目(JSON数组)
    private LocalDateTime expireTime;   // 过期时间
    private Integer isUsed;             // 是否已使用
    private LocalDateTime useTime;      // 使用时间
    private String deviceInfo;          // 设备信息
    private String loginIp;             // 登录IP
    private String accessToken;         // 访问令牌
    private LocalDateTime tokenExpireTime;  // token过期时间
}
```

**对比结果**: ✅ **设计完善**
- 支持邀请码验证
- **角色映射**: `'judge'` 对应文档的 `'pub'`, `'chief_judge'` 对应 `'admin'`
- 包含了Token管理和安全审计功能

---

### 3.6 扣分项 (Deduction)

**文档定义**:
```typescript
interface Deduction {
  deductionId: string
  projectId: string
  text: string
  score: number              // 负数
  category?: string
  order: number
}
```

**后端实现**:
```java
@TableName("martial_deduction_item")
public class MartialDeductionItem extends TenantEntity {
    private String itemName;            // ✅ text
    private String itemCode;            // ⚠️ 扣分项编码
    private BigDecimal deductionPoint;  // ✅ score
    private String category;            // ✅
    private String applicableProjects;  // ✅ projectId (JSON数组)
    private String description;         // ⚠️ 描述
    private Integer sortOrder;          // ✅ order
}
```

**对比结果**: ✅ **匹配度: 95%**

---

## 四、认证机制对比

### 4.1 文档设计

**认证方式**: JWT Token

**Token格式**:
```
Authorization: Bearer {token}
```

**全局数据存储**:
```javascript
getApp().globalData = {
  userRole: 'pub' | 'admin',
  matchCode: string,
  token: string
}
```

### 4.2 后端实现

**认证方式**: Blade-Auth Token

**Token格式**:
```
Blade-Auth: Bearer {token}
```

**实现代码** (martial-mini项目):
```javascript
// utils/request.js
getHeaders(customHeader = {}) {
  const token = uni.getStorageSync('token') || ''
  return {
    'Content-Type': 'application/json',
    'Blade-Auth': token ? `Bearer ${token}` : '',
    ...customHeader
  }
}
```

**对比结果**: ⚠️ **Token头名称不同**
- 文档: `Authorization`
- 后端: `Blade-Auth`
- **建议**: 前端需要改为 `Blade-Auth`

---

## 五、API路径规范对比

### 5.1 文档定义

```
/api/auth/login
/api/matches/{matchId}
/api/venues
/api/projects
/api/athletes
/api/scores
/api/deductions
/api/statistics/match/{matchId}
```

### 5.2 后端实现

```
/martial/judgeInvite
/martial/competition
/martial/venue
/martial/project
/martial/athlete
/martial/score
/martial/deductionItem
(统计接口未实现)
```

**对比结果**: ❌ **路径前缀不同**
- 文档: `/api/`
- 后端: `/martial/`
- **影响**: 前端需要修改所有API路径

---

## 六、响应格式对比

### 6.1 文档定义

```json
{
  "code": 200,
  "message": "成功",
  "data": {}
}
```

### 6.2 后端实现（BladeX框架）

**成功响应**:
```json
{
  "code": 200,
  "success": true,
  "data": {},
  "msg": "操作成功"
}
```

**分页响应**:
```json
{
  "code": 200,
  "success": true,
  "data": {
    "records": [],        // 数据列表
    "total": 100,         // 总记录数
    "size": 20,           // 每页大小
    "current": 1,         // 当前页
    "pages": 5            // 总页数
  }
}
```

**对比结果**: ⚠️ **格式略有不同**
- 多了 `success` 字段
- 字段名 `message` vs `msg`
- 分页格式不同（MyBatis Plus标准格式）

---

## 七、数据类型映射

| 前端文档 (TypeScript) | 后端实现 (Java) | 说明 |
|---------------------|----------------|------|
| `string` | `Long` | ID类型 |
| `string` | `String` | 普通字符串 |
| `number` | `BigDecimal` | 分数（精确小数） |
| `number` | `Integer` | 整数 |
| `boolean` | `Integer` | 0/1表示 |
| `string` (ISO 8601) | `LocalDateTime` | 时间类型 |
| `Array<T>` | `String` (JSON) | 数组存储为JSON字符串 |
| `'male' | 'female'` | `Integer` (1/2) | 枚举映射 |

---

## 八、缺失的接口

### 8.1 小程序登录专用接口

**需要**:
```
POST /api/auth/login
请求: { matchCode, inviteCode }
响应: { token, userRole, matchId, ... }
```

**建议实现**: 创建新的Controller `MartialMiniAuthController`

### 8.2 选手列表（带评分状态）

**需要**:
```
GET /api/athletes
- 返回当前评委的选手列表
- 包含 myScore, totalScore, scored 字段
```

**建议**: 在 `MartialAthleteController` 中添加新方法

### 8.3 评分修改（裁判长专用）

**需要**:
```
PUT /api/scores/{athleteId}/modify
- 只有裁判长可以调用
- 记录修改历史
```

**建议**: 在 `MartialScoreController` 中添加专用方法

### 8.4 统计分析接口

**需要**:
```
GET /api/statistics/match/{matchId}
GET /api/statistics/judges
```

**建议**: 创建新的 `MartialStatisticsController`

---

## 九、对接建议

### 9.1 短期方案（1-2周）

#### 1. 创建小程序专用Controller

```java
@RestController
@RequestMapping("/api/mini")
public class MartialMiniController {

    /**
     * 小程序登录
     */
    @PostMapping("/login")
    public R<LoginVO> login(@RequestBody LoginDTO dto) {
        // 验证邀请码
        // 生成Token
        // 返回用户信息和权限
    }

    /**
     * 获取评委的选手列表（带评分状态）
     */
    @GetMapping("/athletes")
    public R<List<AthleteScoreVO>> getMyAthletes(
        @RequestParam Long judgeId,
        @RequestParam Long venueId,
        @RequestParam Long projectId
    ) {
        // 查询选手列表
        // 关联评分状态
        // 返回 myScore, totalScore 等
    }

    /**
     * 提交评分
     */
    @PostMapping("/score/submit")
    public R submitScore(@RequestBody ScoreDTO dto) {
        // 验证评分范围
        // 保存评分
        // 计算总分
    }

    /**
     * 修改评分（裁判长）
     */
    @PutMapping("/score/modify")
    public R modifyScore(@RequestBody ModifyScoreDTO dto) {
        // 验证权限
        // 修改评分
        // 记录日志
    }
}
```

#### 2. 前端适配

**修改 martial-admin-mini 项目**:

1. **创建 `utils/request.js`**（参考 martial-mini 项目）

2. **创建 `config/api.config.js`**:
   ```javascript
   export default {
     baseURL: '/martial',  // 或配置代理
     timeout: 30000
   }
   ```

3. **创建 `api/` 目录**:
   ```
   api/
   ├── auth.js         # 登录相关
   ├── athlete.js      # 选手相关
   ├── score.js        # 评分相关
   ├── venue.js        # 场地相关
   ├── project.js      # 项目相关
   └── deduction.js    # 扣分项相关
   ```

4. **修改页面代码**，替换Mock数据为API调用

#### 3. Token处理

**统一改为 `Blade-Auth`**:
```javascript
header: {
  'Blade-Auth': `Bearer ${token}`
}
```

### 9.2 中期方案（2-4周）

1. **完善数据结构**
   - 在 VO 类中添加文档要求的字段
   - 创建专门的小程序VO类

2. **实现统计分析功能**
   - 创建 `MartialStatisticsController`
   - 实现比赛统计、评委统计等接口

3. **WebSocket实时推送**
   - 集成 Spring WebSocket
   - 实现评分实时更新推送

4. **完善权限控制**
   - 基于角色的访问控制
   - 接口级别的权限验证

### 9.3 长期方案（1-2月）

1. **API版本管理**
   - `/api/v1/...` 路径规范
   - 向后兼容处理

2. **性能优化**
   - Redis缓存
   - 数据库查询优化
   - 分页优化

3. **监控和日志**
   - 接口调用监控
   - 异常日志记录
   - 性能分析

---

## 十、数据库表设计

### 已有的表

根据Entity类推断的表结构：

```sql
-- 评分记录表
CREATE TABLE martial_score (
    id BIGINT PRIMARY KEY,
    competition_id BIGINT,      -- 赛事ID
    athlete_id BIGINT,          -- 选手ID
    project_id BIGINT,          -- 项目ID
    schedule_id BIGINT,         -- 赛程ID
    venue_id BIGINT,            -- 场地ID
    judge_id BIGINT,            -- 裁判ID
    judge_name VARCHAR(50),     -- 裁判姓名
    score DECIMAL(5,3),         -- 评分
    original_score DECIMAL(5,3),-- 原始评分
    deduction_items TEXT,       -- 扣分项(JSON)
    note VARCHAR(500),          -- 备注
    modify_reason VARCHAR(500), -- 修改原因
    score_time DATETIME,        -- 评分时间
    modify_time DATETIME,       -- 修改时间
    ip_address VARCHAR(50),     -- IP地址
    -- 其他审计字段
    created_by BIGINT,
    create_time DATETIME,
    updated_by BIGINT,
    update_time DATETIME,
    is_deleted INT DEFAULT 0
);

-- 选手表
CREATE TABLE martial_athlete (
    id BIGINT PRIMARY KEY,
    order_id BIGINT,            -- 订单ID
    competition_id BIGINT,      -- 赛事ID
    project_id BIGINT,          -- 项目ID
    player_name VARCHAR(50),    -- 选手姓名
    player_no VARCHAR(50),      -- 参赛编号
    gender INT,                 -- 性别
    age INT,                    -- 年龄
    id_card VARCHAR(20),        -- 身份证号
    id_card_type INT,           -- 证件类型
    birth_date DATE,            -- 出生日期
    nation VARCHAR(20),         -- 民族
    contact_phone VARCHAR(20),  -- 联系电话
    organization VARCHAR(100),  -- 所属单位
    organization_type INT,      -- 单位类别
    team_name VARCHAR(100),     -- 队伍名称
    category VARCHAR(50),       -- 组别
    order_num INT,              -- 出场顺序
    introduction TEXT,          -- 选手简介
    attachments TEXT,           -- 附件(JSON)
    photo_url VARCHAR(500),     -- 照片URL
    registration_status INT,    -- 报名状态
    competition_status INT,     -- 比赛状态
    total_score DECIMAL(5,3),   -- 总分
    ranking INT,                -- 排名
    remark VARCHAR(500),        -- 备注
    -- 审计字段...
);

-- 场地表
CREATE TABLE martial_venue (
    id BIGINT PRIMARY KEY,
    competition_id BIGINT,      -- 赛事ID
    venue_name VARCHAR(50),     -- 场地名称
    venue_code VARCHAR(50),     -- 场地编码
    capacity INT,               -- 容纳人数
    location VARCHAR(200),      -- 位置
    facilities TEXT,            -- 场地设施
    status INT,                 -- 状态
    -- 审计字段...
);

-- 项目表
CREATE TABLE martial_project (
    id BIGINT PRIMARY KEY,
    competition_id BIGINT,          -- 赛事ID
    project_name VARCHAR(100),      -- 项目名称
    project_code VARCHAR(50),       -- 项目编码
    category VARCHAR(50),           -- 组别
    type INT,                       -- 类型
    min_participants INT,           -- 最少参赛人数
    max_participants INT,           -- 最多参赛人数
    min_age INT,                    -- 最小年龄
    max_age INT,                    -- 最大年龄
    gender_limit INT,               -- 性别限制
    estimated_duration INT,         -- 预估时长
    price DECIMAL(10,2),            -- 报名费用
    difficulty_coefficient DECIMAL(4,2),  -- 难度系数
    registration_deadline DATETIME, -- 报名截止时间
    description TEXT,               -- 项目描述
    sort_order INT,                 -- 排序
    -- 审计字段...
);

-- 裁判邀请码表
CREATE TABLE martial_judge_invite (
    id BIGINT PRIMARY KEY,
    competition_id BIGINT,      -- 赛事ID
    judge_id BIGINT,            -- 裁判ID
    invite_code VARCHAR(50),    -- 邀请码
    role VARCHAR(20),           -- 角色
    venue_id BIGINT,            -- 分配场地ID
    projects TEXT,              -- 分配项目(JSON)
    expire_time DATETIME,       -- 过期时间
    is_used INT,                -- 是否已使用
    use_time DATETIME,          -- 使用时间
    device_info VARCHAR(500),   -- 设备信息
    login_ip VARCHAR(50),       -- 登录IP
    access_token VARCHAR(500),  -- 访问令牌
    token_expire_time DATETIME, -- token过期时间
    -- 审计字段...
);

-- 扣分项表
CREATE TABLE martial_deduction_item (
    id BIGINT PRIMARY KEY,
    item_name VARCHAR(100),     -- 扣分项名称
    item_code VARCHAR(50),      -- 扣分项编码
    deduction_point DECIMAL(4,3),  -- 扣分值
    category VARCHAR(50),       -- 分类
    applicable_projects TEXT,   -- 适用项目(JSON)
    description VARCHAR(500),   -- 描述
    sort_order INT,             -- 排序
    -- 审计字段...
);
```

---

## 十一、总结

### ✅ 优点

1. **后端架构完整**：基于成熟的BladeX框架
2. **数据库设计合理**：字段完善，支持审计
3. **代码规范**：使用Swagger文档，代码结构清晰
4. **功能丰富**：比文档要求的功能更多

### ⚠️ 问题

1. **API路径不匹配**：`/martial/` vs `/api/`
2. **接口设计差异**：后端使用统一的 `/submit` 而不是 RESTful 风格
3. **缺少小程序专用接口**：登录、评分等需要定制
4. **Token头名称不同**：`Blade-Auth` vs `Authorization`
5. **响应格式略有差异**：多了 `success` 字段

### 📋 需要开发的内容

#### 后端（1-2周工作量）

- [ ] 创建 `MartialMiniController` 或 `MartialMiniAuthController`
- [ ] 实现小程序登录接口
- [ ] 实现获取评委选手列表接口（带评分状态）
- [ ] 实现评分提交接口（简化版）
- [ ] 实现评分修改接口（裁判长专用）
- [ ] 创建小程序专用的VO类
- [ ] （可选）创建统计分析Controller

#### 前端（2-3周工作量）

- [ ] 创建 `utils/request.js` 请求封装
- [ ] 创建 `api/` 目录和所有API文件
- [ ] 修改所有页面，替换Mock数据为API调用
- [ ] 实现Token存储和管理
- [ ] 实现登录流程
- [ ] 实现评分提交流程
- [ ] 实现评分修改流程
- [ ] 实现错误处理和loading状态
- [ ] （可选）实现WebSocket实时更新

### 🎯 推荐方案

**最快对接方案**（1周）:

1. **后端**：在现有Controller基础上添加小程序专用方法
2. **前端**：直接复用 martial-mini 项目的 `utils/request.js` 和 `api/` 文件
3. **适配**：调整API路径和数据格式映射

**完整方案**（3-4周）:

1. 按照上面的对接建议，分阶段实现
2. 编写接口文档和测试用例
3. 进行完整的联调测试

---

## 十二、martial-mini 项目参考

`martial-mini` 项目已经成功对接了后端，可以作为参考：

**文件结构**:
```
martial-mini/
├── api/                    # API接口定义
│   ├── athlete.js
│   ├── competition.js
│   ├── info.js
│   ├── registration.js
│   ├── result.js
│   └── user.js
├── config/
│   └── api.config.js      # API配置
└── utils/
    └── request.js         # 请求封装
```

**建议**: 直接复制 `martial-mini` 项目的这些文件到 `martial-admin-mini`，然后根据需要调整。

---

## 附录：快速对接检查清单

### 后端检查

- [ ] 确认后端服务已启动
- [ ] 确认数据库已初始化
- [ ] 确认Swagger文档可访问（通常在 `/doc.html`）
- [ ] 创建测试用的邀请码数据
- [ ] 测试各个接口是否正常

### 前端检查

- [ ] 复制 `request.js` 文件
- [ ] 复制 `api.config.js` 文件
- [ ] 创建各个API文件
- [ ] 修改登录页面对接API
- [ ] 修改评分列表页面对接API
- [ ] 修改评分详情页面对接API
- [ ] 测试完整流程

### 联调测试

- [ ] 登录功能测试
- [ ] 获取选手列表测试
- [ ] 评分提交测试
- [ ] 评分修改测试（裁判长）
- [ ] 场地切换测试
- [ ] 项目切换测试
- [ ] 扣分项加载测试
- [ ] Token过期处理测试

---

**报告生成时间**: 2025-12-11
**文档版本**: v1.0
**后端项目**: martial-master (BladeX 4.0.1)
**前端项目**: martial-admin-mini (UniApp)