docs: mockapi

mock-api-docs.md

@@ -0,0 +1,189 @@
+# 模拟接口 API 文档 (基于 `mockApi`)
+
+本文档提供了当前前端中使用的 `mockApi` 相应的接口定义。通过此文档可以了解各个接口的请求参数格式及对应返回的数据格式，以方便后期后端的开发和前端的对应接口替换。
+
+---
+
+## 基础数据实体
+
+在所有接口中复用的核心数据结构定义：
+
+### User (用户信息)
+```typescript
+{
+  "id": "string",         // 用户唯一ID
+  "username": "string",   // 登录用户名
+  "role": "stu" | "teacher", // 用户角色
+  "name": "string",       // 用户姓名
+  "avatar": "string"      // 头像路径/URL
+}
+```
+
+### MockStudent (学生详细信息)
+```typescript
+{
+  "id": "string",         // 学生学号/ID
+  "name": "string",       // 学生姓名
+  "overall": "number",    // 总分
+  "K": "number",          // 知识覆盖维度大分 (0-100)
+  "A": "number",          // AI交互维度大分 (0-100)
+  "S": "number",          // 代码产出维度大分 (0-100)
+  "D": "number",          // 团队协作维度大分 (0-100)
+  "avatar": "string",     // 头像URL
+  "metricScores": {       // 具体子指标分数映射，如 "K1": 88
+    "[metricId: string]": "number"
+  }
+}
+```
+
+---
+
+## 接口列表
+
+### 1. 登录 (Login)
+* **功能**: 用户使用用户名和密码登录
+* **路径**: `POST /api/auth/login` (建议)
+* **请求格式**: `application/json`
+  ```json
+  {
+    "username": "stu",      // 必填
+    "password": "passwd"    // 必填 (模拟数据密码固定为 passwd)
+  }
+  ```
+* **返回格式**: `200 OK`
+  ```json
+  {
+    "token": "string",      // 签发的 JWT Token 
+    "user": {
+      // User 结构
+      "id": "231250001",
+      "username": "stu",
+      "role": "stu",
+      "name": "李子涵",
+      "avatar": "/images/profile-avatar.png"
+    }
+  }
+  ```
+* **错误响应**: `401 Unauthorized` (密码错误或用户不存在)
+
+---
+
+### 2. 校验会话 (Verify Session)
+* **功能**: 利用现有的 Token 验证用户并获取信息
+* **路径**: `GET /api/auth/verify` (建议)
+* **请求头**: 
+  * `Authorization: Bearer <token>`
+* **返回格式**: `200 OK`
+  ```json
+  {
+    // User 结构 
+  }
+  ```
+  *(注: 在 mock 中如果 token 为空或无效则返回 `null` / `401 Unauthorized`)*
+
+---
+
+### 3. 获取所有学生列表 (Get Students)
+* **功能**: 获取全班学生的简要/详细得分数据集合
+* **路径**: `GET /api/students`
+* **返回格式**: `200 OK`
+  ```json
+  [
+    {
+      // MockStudent 结构
+    },
+    // ...
+  ]
+  ```
+
+---
+
+### 4. 获取指定学生详情 (Get Student By Id)
+* **功能**: 根据学号/ID请求单个具体学生的数据
+* **路径**: `GET /api/students/:id`
+* **参数**: 
+  * 路径参数 `id`: 目标学生ID
+* **返回格式**: `200 OK`
+  ```json
+  {
+    // MockStudent 结构
+  }
+  ```
+* **错误响应**: `404 Not Found` (未找到对应学生)
+
+---
+
+### 5. 获取指定学生子指标分数 (Get Student Metrics)
+* **功能**: 仅获取某个学生的详细二级指标分数（如果不想拉取全量学生信息的话，用来绘制雷达图等使用）
+* **路径**: `GET /api/students/:id/metrics`
+* **返回格式**: `200 OK`
+  ```json
+  {
+    "K1": 85,
+    "K2": 90,
+    "A1": 77
+    // [metricId: string]: number
+  }
+  ```
+
+---
+
+### 6. 获取班级统计信息 (Get Class Stats)
+* **功能**: 获取当前班级的整体统计报表（如平均分、四大指标对应的分布区间）
+* **路径**: `GET /api/class/stats`
+* **返回格式**: `200 OK`
+  ```json
+  {
+    "averages": {
+      "K": 82,
+      "A": 81,
+      "S": 82,
+      "D": 82
+    },
+    "distributions": {
+      "K": [
+        { "tier": "优秀 (90+)", "count": 10, "percent": "25%" },
+        { "tier": "良好 (80-89)", "count": 20, "percent": "50%" },
+        { "tier": "一般 (70-79)", "count": 5, "percent": "12%" },
+        { "tier": "需改进 (<70)", "count": 5, "percent": "12%" }
+      ],
+      "A": [ /* ... */ ],
+      "S": [ /* ... */ ],
+      "D": [ /* ... */ ]
+    }
+  }
+  ```
+
+---
+
+### 7. 获取排行榜 (Get Leaderboard)
+* **功能**: 返回学生总分排行榜数据
+* **路径**: `GET /api/leaderboard`
+* **请求参数 (Query)**:
+  * `limit` (选填): 默认值为 5，控制请求返回前N名
+* **返回格式**: `200 OK`
+  ```json
+  [
+    {
+      "id": "231250005",
+      "name": "刘星雨",
+      "score": 92,
+      "avatar": "/images/profile-avatar.png",
+      "bestAt": "K (知识覆盖)" // 计算所得的最高维度提示
+    }
+    // ...共 limit 条
+  ]
+  ```
+
+---
+
+### 8. 获取"我的"个人数据 (Get My Profile)
+* **功能**: 面向学生端使用的快捷接口，获取当前登录用户的档案（无需手动传ID参数）
+* **路径**: `GET /api/me`
+* **请求头**: 需要携带凭据 (如 `Authorization: Bearer <token>`)
+* **返回数据格式**: `200 OK`
+  ```json
+  {
+    // MockStudent 结构
+  }
+  ```