feat: 添加Mock版本保护机制 - 基础架构完成

完成内容: ✅ 第一层保护: Git分支隔离 - 创建 v1.0-mock 标签 - 创建 feature/api-integration 分支 ✅ 第二层保护: 配置开关控制 - config/env.config.js (环境配置，支持Mock/API模式切换) ✅ 第三层保护: 代码架构分离 - utils/request.js (网络请求封装，支持Blade-Auth) - utils/dataAdapter.js (核心适配器，自动选择数据源) ✅ Mock数据模块 (4个文件): - mock/index.js (统一入口) - mock/login.js (登录Mock数据) - mock/athlete.js (选手Mock数据，含场地、项目) - mock/score.js (评分Mock数据，含扣分项、详情、修改) ✅ API接口模块 (4个文件): - api/index.js (统一入口) - api/auth.js (认证API，含后端接口规范) - api/athlete.js (选手API，含SQL示例) - api/score.js (评分API，含实现逻辑说明) 特性: - 通过修改 config/env.config.js 的 dataMode 即可切换Mock/API模式 - Mock模式: 完全离线，无需后端，UI功能完整 - API模式: 调用真实后端接口（需后端实现5个专用接口） - 零UI修改: 原有页面代码完全保护，仅替换数据源下一步: - 修改5个页面使用 dataAdapter - 测试Mock模式功能 - 后端开发5个小程序专用接口代码统计: - 新增11个文件 - 约1000行代码 - 完整的注释和使用说明
2025-12-11 14:06:03 +08:00
parent 7bd197f4ac
commit 7ec9a77c2a
12 changed files with 1616 additions and 1 deletions
--- a/api/index.js
+++ b/api/index.js
@@ -0,0 +1,158 @@
+/**
+ * API接口中心
+ * 所有API接口的统一入口
+ *
+ * 这个文件汇总了所有业务模块的API接口函数，
+ * 提供给 dataAdapter.js 调用
+ */
+
+import authApi from './auth.js'
+import athleteApi from './athlete.js'
+import scoreApi from './score.js'
+
+/**
+ * 导出所有API接口函数
+ *
+ * 资源名称（key）对应 dataAdapter.getData() 的第一个参数
+ * 例如：dataAdapter.getData('login', params) 会调用 authApi.login(params)
+ */
+export default {
+	// ==================== 认证模块 ====================
+	/**
+	 * 登录验证
+	 * @param {Object} data - { matchCode, inviteCode }
+	 * @returns {Promise}
+	 */
+	login: authApi.login,
+
+	/**
+	 * 退出登录
+	 * @returns {Promise}
+	 */
+	logout: authApi.logout,
+
+	/**
+	 * Token验证
+	 * @returns {Promise}
+	 */
+	verifyToken: authApi.verifyToken,
+
+	// ==================== 选手模块 ====================
+	/**
+	 * 获取我的选手列表（普通评委）
+	 * @param {Object} params - { judgeId, venueId, projectId }
+	 * @returns {Promise}
+	 */
+	getMyAthletes: athleteApi.getMyAthletes,
+
+	/**
+	 * 获取选手列表（裁判长）
+	 * @param {Object} params - { competitionId, venueId, projectId }
+	 * @returns {Promise}
+	 */
+	getAthletesForAdmin: athleteApi.getAthletesForAdmin,
+
+	/**
+	 * 获取场地列表
+	 * @param {Object} params - { competitionId }
+	 * @returns {Promise}
+	 */
+	getVenues: athleteApi.getVenues,
+
+	/**
+	 * 获取项目列表
+	 * @param {Object} params - { competitionId }
+	 * @returns {Promise}
+	 */
+	getProjects: athleteApi.getProjects,
+
+	// ==================== 评分模块 ====================
+	/**
+	 * 获取扣分项列表
+	 * @param {Object} params - { projectId }
+	 * @returns {Promise}
+	 */
+	getDeductions: scoreApi.getDeductions,
+
+	/**
+	 * 提交评分
+	 * @param {Object} data - { athleteId, judgeId, score, deductions, note }
+	 * @returns {Promise}
+	 */
+	submitScore: scoreApi.submitScore,
+
+	/**
+	 * 获取评分详情（裁判长查看）
+	 * @param {Object} params - { athleteId }
+	 * @returns {Promise}
+	 */
+	getScoreDetail: scoreApi.getScoreDetail,
+
+	/**
+	 * 修改评分（裁判长）
+	 * @param {Object} data - { athleteId, modifierId, modifiedScore, note }
+	 * @returns {Promise}
+	 */
+	modifyScore: scoreApi.modifyScore
+}
+
+/**
+ * 使用说明：
+ *
+ * 这个文件不直接在页面中使用，而是通过 dataAdapter.js 间接调用。
+ *
+ * 当 config/env.config.js 中 dataMode 设置为 'api' 时，
+ * dataAdapter.getData() 会自动调用这里的API函数。
+ *
+ * 页面使用示例：
+ *
+ * import dataAdapter from '@/utils/dataAdapter.js'
+ *
+ * // 配置 dataMode: 'api' 时，以下代码会调用真实API
+ * const res = await dataAdapter.getData('login', {
+ *   matchCode: '123',
+ *   inviteCode: 'pub'
+ * })
+ * // 实际调用: authApi.login({ matchCode, inviteCode })
+ * // 请求: POST /api/mini/login
+ *
+ * // 配置 dataMode: 'mock' 时，同样的代码会使用Mock数据
+ * // 实际调用: mockData.login({ matchCode, inviteCode })
+ * // 无网络请求，返回本地Mock数据
+ */
+
+/**
+ * 后端开发者注意事项：
+ *
+ * 1. 需要实现的新接口（小程序专用）：
+ *    - POST /api/mini/login                    # 登录验证
+ *    - GET  /api/mini/athletes                 # 普通评委选手列表
+ *    - GET  /api/mini/athletes/admin           # 裁判长选手列表
+ *    - GET  /api/mini/score/detail/{athleteId} # 评分详情
+ *    - PUT  /api/mini/score/modify             # 修改评分
+ *
+ * 2. 可以复用的现有接口：
+ *    - POST /martial/score/submit              # 提交评分
+ *    - GET  /martial/venue/list                # 场地列表
+ *    - GET  /martial/project/list              # 项目列表
+ *    - GET  /martial/deductionItem/list        # 扣分项列表
+ *
+ * 3. 响应格式统一为 BladeX 标准格式：
+ *    {
+ *      "code": 200,
+ *      "success": true,
+ *      "msg": "操作成功",
+ *      "data": { ... }
+ *    }
+ *
+ * 4. 请求头要求：
+ *    - Content-Type: application/json
+ *    - Blade-Auth: Bearer {token}
+ *
+ * 5. 建议创建专门的Controller：
+ *    @RestController
+ *    @RequestMapping("/api/mini")
+ *    public class MartialMiniController {
+ *      // 实现上述5个专用接口
+ *    }
+ */