Mock API 层

31个RESTful接口，按模块分类 | 文件位于 web/src/mock/

---

架构概览

mock/
├── index.ts              ← 入口文件（注册所有 Mock 拦截）
├── data/
│   └── index.ts          ← 共享数据（JSON导入 + 用户状态管理 + 游戏进度）
└── modules/
    ├── user/
    │   ├── profile.ts    ← 用户信息
    │   ├── exp-points.ts ← 经验值/积分
    │   └── badges.ts     ← 徽章管理
    ├── character/
    │   └── list.ts       ← 汉字列表/分类
    ├── game/
    │   ├── config.ts     ← 游戏配置
    │   ├── progress.ts   ← 游戏进度
    │   └── powerups.ts   ← 道具管理
    ├── achievement/
    │   ├── level.ts      ← 段位信息
    │   └── badges.ts     ← 徽章定义
    ├── shop/
    │   ├── rewards.ts    ← 奖励管理
    │   ├── redeem.ts     ← 兑换操作
    │   └── password.ts   ← 密码管理
    └── planet/
        └── list.ts       ← 星球列表

---

入口文件 (mock/index.ts)

文件: web/src/mock/index.ts

职责

• 导入所有 Mock 模块以注册 mockjs 拦截
• 设置全局 Mock 配置（200-400ms 网络延迟）
• 自动持久化：页面关闭时保存 + 每10秒自动保存

启动条件

// main.ts
// Mock 在所有环境（开发/生产）无条件加载，确保无后端时数据正常
await import("./mock");

注册的模块

// 用户模块
import "./modules/user/profile";
import "./modules/user/exp-points";
import "./modules/user/badges";

// 汉字模块
import "./modules/character/list";

// 游戏模块
import "./modules/game/config";
import "./modules/game/progress";
import "./modules/game/powerups";

// 成就模块
import "./modules/achievement/level";
import "./modules/achievement/badges";

// 商店模块
import "./modules/shop/rewards";
import "./modules/shop/redeem";
import "./modules/shop/password";

// 星球模块
import "./modules/planet/list";

---

统一响应格式

interface ApiResponse<T> {
  code: number    // 0 = 成功, 非0 = 失败
  msg: string     // 提示信息
  data: T         // 响应数据
}

interface PaginatedData<T> {
  list: T[]       // 数据列表
  total: number   // 总数
  page: number    // 当前页
  pageSize: number // 每页条数
}

核心函数

函数	说明
success(data, msg)	成功响应 { code: 0, msg: "ok", data }
fail(msg, code)	失败响应 { code: 400, msg, data: null }
genId(prefix)	生成唯一 ID
parseUrlParams(url, pattern)	从 URL 提取路径参数
parsePagination(searchParams)	解析分页参数（pageSize 上限 1000）
paginate(list, page, pageSize)	分页包装

---

共享数据 (mock/data/index.ts)

文件: web/src/mock/data/index.ts

职责

• 从本地 JSON 导入数据（汉字、分类、游戏、星球）
• 管理用户状态（MockUser）
• 管理游戏进度（gameProgressMap + powerUpMap）
• localStorage 持久化（tzxq_mock_db key）

数据来源

import characterData from "@/data/character.json";   // 500 汉字
import categoriesData from "@/data/categories.json";   // 6 分类
import gamesData from "@/data/games.json";             // 3 游戏
import planetsData from "@/data/planets.json";         // 6 星球

用户状态管理

函数	说明
getCurrentUser()	获取/初始化当前用户
loadMockDb()	从 localStorage 恢复数据
saveMockDb()	保存数据到 localStorage

---

接口清单

用户模块 (3个文件，8个接口)

方法	路径	说明	文档
GET	/api/v1/users/me	获取当前用户信息	profile
PUT	/api/v1/users/me	更新用户信息	profile
GET	/api/v1/users/me/exp	获取经验值	exp-points
POST	/api/v1/users/me/exp	增加经验值	exp-points
GET	/api/v1/users/me/points	获取积分	exp-points
POST	/api/v1/users/me/points	增加积分	exp-points
GET	/api/v1/users/me/badges	获取我的徽章列表	badges
POST	/api/v1/users/me/badges/:badgeId	解锁徽章	badges

汉字模块 (1个文件，4个接口)

方法	路径	说明	文档
GET	/api/v1/characters	获取汉字列表（分页+筛选）	list
GET	/api/v1/characters/:char	获取单个汉字详情	list
GET	/api/v1/characters/categories	获取分类列表	list
GET	/api/v1/characters/categories/:id/chars	获取分类下的汉字	list

游戏模块 (3个文件，7个接口)

方法	路径	说明	文档
GET	/api/v1/games	获取游戏配置列表	config
GET	/api/v1/games/:id	获取单个游戏配置	config
GET	/api/v1/games/data	获取游戏进度数据	config
PUT	/api/v1/games/data	同步游戏进度	config
POST	/api/v1/games/:gameId/levels/:levelId/result	提交关卡结果	progress
POST	/api/v1/games/:gameId/power-ups/:type/use	使用道具	powerups
POST	/api/v1/games/:gameId/power-ups/:type/add	添加道具	powerups

成就模块 (2个文件，2个接口)

方法	路径	说明	文档
GET	/api/v1/achievements/levels	获取段位体系	level
GET	/api/v1/achievements/badges	获取徽章定义	badges

商店模块 (3个文件，9个接口)

方法	路径	说明	文档
GET	/api/v1/shop/rewards	获取奖励列表	rewards
POST	/api/v1/shop/rewards	创建自定义奖励	rewards
PUT	/api/v1/shop/rewards/:id	更新奖励	rewards
DELETE	/api/v1/shop/rewards/:id	删除奖励	rewards
PUT	/api/v1/shop/rewards/:id/toggle	启用/禁用奖励	rewards
POST	/api/v1/shop/rewards/:rewardId/redeem	兑换奖励	redeem
GET	/api/v1/shop/history	获取兑换历史	redeem
POST	/api/v1/shop/password/verify	验证密码	password
PUT	/api/v1/shop/password	设置密码	password

星球模块 (1个文件，1个接口)

方法	路径	说明	文档
GET	/api/v1/planets	获取星球列表	list

---

数据流

main.ts (DEV环境)
  ↓ await import("./mock")
mock/index.ts
  ↓ 导入所有模块
Mock.js 拦截 axios 请求
  ↓ 匹配 URL + Method
模块处理函数
  ↓ 读写 mock/data/index.ts
localStorage (tzxq_mock_db)
  ↓
Pinia Store → api-service → Mock API
  │
  ├─ UserStore        → /users/me, /users/me/exp, /users/me/points, /users/me/badges
  ├─ CharacterStore   → /characters, /characters/categories, /planets
  ├─ GameStore        → /games, /games/data, /games/:id/levels/:id/result, /games/:id/power-ups
  ├─ AchievementStore → /achievements/levels, /achievements/badges
  └─ ShopStore        → /shop/rewards, /shop/history, /shop/password

---

设计原则

1. RESTful 风格: 资源路径 + HTTP 方法
2. 统一响应格式: { code, msg, data }
3. 模块化: 每个功能独立文件，按模块分类
4. 数据持久化: localStorage 自动保存，页面关闭/定时保存
5. 模拟延迟: 200-400ms 网络延迟，模拟真实 API 体验
6. 条件加载: 仅 DEV 环境启用，生产构建不包含 Mock 代码