Files

完成内容:
- 5个完整的UI页面（登录、评分列表、评分详情、多场地列表、修改评分）
- 完整的Mock数据展示
- 完整的业务逻辑实现
- 文档体系建立（2000+行文档）

文档包含:
- 项目概述.md
- 页面功能说明.md
- API接口设计.md (17个接口)
- 数据结构设计.md (17个接口定义)
- 功能模块划分.md
- 后端实现对比报告.md
- 数据可行性分析报告.md (95分评估)
- 保护Mock版本的实施方案.md (4层保护机制)
- API对接完成度检查报告.md

此版本为Mock原型版本，所有UI功能完整，数据为硬编码Mock数据。

2025-12-11 13:22:19 +08:00

29 KiB

Raw Blame History

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

项目概述

项目结构

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

关键发现

martial-admin-mini（当前项目）是纯前端原型，没有对接任何后端API
martial-mini 项目已经实现了后端API对接
martial-master 后端项目已经实现了大部分API接口
后端使用 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验证

后端实现:

// 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             # 获取我的评分记录

后端实现:

// 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}    # 获取选手详情

后端实现:

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

对比结果: ✅ 基本匹配，功能更丰富

文档中的查询接口可以通过 /list 实现（通过参数筛选）
后端额外提供了签到、完成、状态更新等功能

场地管理模块

文档定义:

GET /api/venues                 # 获取场地列表

后端实现:

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

对比结果: ✅ 完全覆盖

项目管理模块

文档定义:

GET /api/projects               # 获取项目列表
GET /api/projects/{projectId}   # 获取项目详情

后端实现:

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

对比结果: ✅ 完全覆盖

扣分项管理模块

文档定义:

GET /api/deductions             # 获取扣分项列表

后端实现:

// 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):

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):

@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)

文档定义:

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'
}

后端实现:

@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)

文档定义:

interface Venue {
  venueId: string
  venueName: string
  matchId: string
  order: number
  athleteCount: number
  scoredCount: number
  status: 'active' | 'completed' | 'paused'
}

后端实现:

@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)

文档定义:

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'
}

后端实现:

@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)

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

后端实现:

@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)

文档定义:

interface Deduction {
  deductionId: string
  projectId: string
  text: string
  score: number              // 负数
  category?: string
  order: number
}

后端实现:

@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}

全局数据存储:

getApp().globalData = {
  userRole: 'pub' | 'admin',
  matchCode: string,
  token: string
}

4.2 后端实现

认证方式: Blade-Auth Token

Token格式:

Blade-Auth: Bearer {token}

实现代码 (martial-mini项目):

// 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 文档定义

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

6.2 后端实现（BladeX框架）

成功响应:

{
  "code": 200,
  "success": true,
  "data": {},
  "msg": "操作成功"
}

分页响应:

{
  "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

@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 项目:

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

创建 config/api.config.js:

export default {
  baseURL: '/martial',  // 或配置代理
  timeout: 30000
}

创建 api/ 目录:

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

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

3. Token处理

统一改为 Blade-Auth:

header: {
  'Blade-Auth': `Bearer ${token}`
}

9.2 中期方案（2-4周）

完善数据结构
- 在 VO 类中添加文档要求的字段
- 创建专门的小程序VO类
实现统计分析功能
- 创建 MartialStatisticsController
- 实现比赛统计、评委统计等接口
WebSocket实时推送
- 集成 Spring WebSocket
- 实现评分实时更新推送
完善权限控制
- 基于角色的访问控制
- 接口级别的权限验证

9.3 长期方案（1-2月）

API版本管理
- /api/v1/... 路径规范
- 向后兼容处理
性能优化
- Redis缓存
- 数据库查询优化
- 分页优化
监控和日志
- 接口调用监控
- 异常日志记录
- 性能分析

十、数据库表设计

已有的表

根据Entity类推断的表结构：

-- 评分记录表
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,             -- 排序
    -- 审计字段...
);

十一、总结

✅ 优点

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

⚠️ 问题

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

📋 需要开发的内容

后端（1-2周工作量）

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

前端（2-3周工作量）

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

🎯 推荐方案

最快对接方案（1周）:

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

完整方案（3-4周）:

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

十二、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)

29 KiB Raw Blame History Unescape Escape

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

项目概述

项目结构

关键发现

一、后端技术栈

技术框架

项目结构

二、API接口对比

2.1 已实现的Controller

2.2 接口对比详情

认证模块

评分管理模块

选手管理模块

场地管理模块

项目管理模块

扣分项管理模块

统计分析模块

三、数据结构对比

3.1 评分记录 (Score)

3.2 选手信息 (Athlete)

3.3 场地信息 (Venue)

3.4 项目信息 (Project)

3.5 裁判邀请码 (JudgeInvite)

3.6 扣分项 (Deduction)

四、认证机制对比

4.1 文档设计

4.2 后端实现

五、API路径规范对比

5.1 文档定义

5.2 后端实现

六、响应格式对比

6.1 文档定义

6.2 后端实现（BladeX框架）

七、数据类型映射

八、缺失的接口

8.1 小程序登录专用接口

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

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

8.4 统计分析接口

九、对接建议

9.1 短期方案（1-2周）

1. 创建小程序专用Controller

2. 前端适配

3. Token处理

9.2 中期方案（2-4周）

9.3 长期方案（1-2月）

十、数据库表设计

已有的表

十一、总结

✅ 优点

⚠️ 问题

📋 需要开发的内容

后端（1-2周工作量）

前端（2-3周工作量）

🎯 推荐方案

十二、martial-mini 项目参考

附录：快速对接检查清单

后端检查

前端检查

联调测试

29 KiB

Raw Blame History