richard/MemeMind-Server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: 优化关卡排序

Browse Source
This commit is contained in:
richarjiang
2026-05-03 22:27:16 +08:00
parent 1f8db6c473
commit 9185df3567
12 changed files with 439 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

194
.agents/skills/api-doc-maintainer/SKILL.md Normal file
View File

@@ -0,0 +1,194 @@
---
name: api-doc-maintainer
description: >
当用户修改、新增或删除任何 API 接口时，同步更新 docs/api/ 下的 Markdown 文档。
触发场景：修改 Controller、DTO、Service 中的接口逻辑或参数，新增/删除 endpoint，
变更响应结构，添加错误码。只要涉及 src/modules/*/ 下的接口代码改动，都应触发此技能。
---
# API 文档维护技能
## 为什么文档同步如此重要
MemeMind 的客户端是 Cocos Creator 小游戏，客户端开发者依赖 `docs/api/` 下的文档来接入后端接口。文档滞后意味着客户端开发者要去读源码才能对接，这会严重拖慢开发节奏。所以每次接口变更，文档必须同步更新。
## 代码结构索引
在更新文档前，先确认变更涉及哪些文件：
```
src/modules/
├── auth/ # 认证模块：wx-login、user assets、game-data
│ ├── auth.controller.ts
│ ├── dto/
│ └── auth.service.ts
├── wechat-game/ # 游戏模块：levels、configs
│ ├── wechat-game.controller.ts
│ ├── dto/
│ └── wechat-game.service.ts
└── share/ # 分享挑战模块：创建分享、加入、进度上报
├── share.controller.ts
├── dto/
└── share.service.ts
```
Controller 定义了路由和参数，DTO 定义了请求/响应的数据结构，Service 包含业务逻辑。三者共同决定文档内容。
## 文档存放与组织
文档统一放在 `docs/api/` 目录下，按功能模块分文件：
| 模块 | 文档文件 | 对应代码 |
|------|----------|----------|
| 用户认证 | `auth-api.md` | `src/modules/auth/` |
| 游戏关卡 | `game-api.md` | `src/modules/wechat-game/` |
| 分享挑战 | `share-challenge-api.md` | `src/modules/share/` |
| 排行榜 | `leaderboard-api.md` | （预留） |
新增模块时，创建对应的文档文件并在 `docs/api/README.md` 中注册索引。
## 文档结构
每个模块的 API 文档包含以下章节：
```markdown
# 模块名称 API
## Changelog
- YYYY-MM-DD: 变更说明
## 概述
功能说明、前置依赖
## 认证方式
（如需要）说明鉴权方式
## 通用响应格式
（引用统一响应格式即可）
## 接口列表
### 1. 接口名称
（按下方模板）
## 错误码说明
| 错误码 | HTTP 状态码 | 说明 | 触发条件 |
## 接入流程
典型业务场景的调用顺序
## 客户端示例
Cocos Creator TypeScript 调用代码
```
## 接口文档模板
根据接口类型智能选择模板，不需要填写不适用的字段。
### 查询类接口（GET，无请求体）
```markdown
### N. 接口名称
**接口地址**：`GET /api/v1/{module}/{endpoint}`
**是否需要认证**：是/否
**路径参数**（如有）：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
**查询参数**（如有）：
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
**成功响应示例**：
```json
{ "success": true, "data": { ... }, "message": null, "timestamp": "..." }
```
**业务逻辑说明**：
- 规则 1
```
### 写入类接口（POST/PUT/PATCH/DELETE，有请求体）
```markdown
### N. 接口名称
**接口地址**：`POST /api/v1/{module}/{endpoint}`
**是否需要认证**：是/否
**请求体**：
```json
{
"field": "value"
}
```
**字段说明**：
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
**成功响应示例**：
```json
{ "success": true, "data": { ... }, "message": null, "timestamp": "..." }
```
**失败响应示例**（如有特殊错误场景）：
```json
{ "success": false, "data": null, "message": "错误描述", "timestamp": "..." }
```
**业务逻辑说明**：
- 规则 1
```
如果某个字段（如路径参数、查询参数）不适用于当前接口，直接省略该小节。
## 统一响应格式
所有 API 响应使用统一包装：
```typescript
interface ApiResponse<T> {
success: boolean; // 请求是否成功
data: T | null; // 响应数据
message: string | null; // 错误信息（成功时为 null）
timestamp: string; // ISO 8601 时间戳
}
```
## 更新工作流
当接口代码发生变更时，按以下步骤操作：
### 新增接口
1. 在对应模块文档中按模板添加接口章节
2. 从 Controller 读取路由路径和方法，从 DTO 读取参数定义
3. 补充业务逻辑说明（来自 Service）
4. 添加 Cocos Creator 调用示例
5. 更新 Changelog
6. 在 `docs/api/README.md` 索引中确认已注册
### 修改接口
1. 对比代码变更，确定文档中哪些内容需要更新
2. 更新受影响的字段：路径、参数、响应结构、业务逻辑
3. 更新示例响应（确保与实际代码一致）
4. 在 Changelog 中记录变更
### 删除接口
1. 在文档中标记为「已废弃」并注明替代方案，或直接移除
2. 更新索引
3. 在 Changelog 中记录
### 错误码变更
1. 在错误码表中新增/修改/删除条目
2. 注明触发条件
## 完成后输出
文档更新完成后，向用户简要报告：
1. 哪些文档被修改了
2. 具体变更了什么内容
3. 是否有需要客户端配合调整的地方

9
AGENTS.md
View File

@@ -40,3 +40,12 @@
## 配置与部署说明 ## 配置与部署说明
环境变量在 `src/config/env.validation.ts` 中做校验。敏感信息应保存在 `.env.local` 或部署环境专用配置中，不能写入源码。无论本地还是生产环境，API 统一暴露在 `/api` 下，Swagger 暴露在 `/api/docs`。`pnpm run deploy` 会调用 `deploy.sh`、`rsync` 和 PM2，因此执行前需要先检查其中的服务器相关配置。 环境变量在 `src/config/env.validation.ts` 中做校验。敏感信息应保存在 `.env.local` 或部署环境专用配置中，不能写入源码。无论本地还是生产环境，API 统一暴露在 `/api` 下，Swagger 暴露在 `/api/docs`。`pnpm run deploy` 会调用 `deploy.sh`、`rsync` 和 PM2，因此执行前需要先检查其中的服务器相关配置。
<claude-mem-context>
# Memory Context
# $CMEM MemeMind-Server 2026-05-03 10:13pm GMT+8
No previous sessions found.
</claude-mem-context>

210
docs/api/game-api.md
View File

@@ -26,8 +26,11 @@
## Changelog ## Changelog
- **2026-05-03**：
- **变更** 关卡顺序规则：所有下一关、预加载下一关、已通关列表均按 `levels.sort_key` 的应用层字节序排序；响应中的 `level` / `sortOrder` 仍为排序后的连续序号
- **2026-04-30**： - **2026-04-30**：
- **新增** `GET /api/v1/levels/completed`：获取当前用户已通关关卡列表（按 sortOrder 升序，含完整关卡信息 + 通关时长 + 通关时间） - **新增** `GET /api/v1/levels/completed`：获取当前用户已通关关卡列表（含完整关卡信息 + 通关时长 + 通关时间）
- **2026-04-26**： - **2026-04-26**：
- **删除** `GET /api/v1/levels`（关卡列表接口），客户端不再需要拉取全量关卡列表 - **删除** `GET /api/v1/levels`（关卡列表接口），客户端不再需要拉取全量关卡列表
@@ -41,26 +44,26 @@
MemeMind 核心玩法接口分为以下模块： MemeMind 核心玩法接口分为以下模块：
| 模块 | 路由前缀 | 说明 | | 模块 | 路由前缀 | 说明 |
|------|----------|------| | -------- | ---------------------- | -------------------------- |
| 认证 | `/api/v1/auth` | 微信登录、JWT 签发 | | 认证 | `/api/v1/auth` | 微信登录、JWT 签发 |
| 用户 | `/api/v1/user` | 用户资料、体力值、游戏数据 | | 用户 | `/api/v1/user` | 用户资料、体力值、游戏数据 |
| 关卡 | `/api/v1/levels` | 进入关卡、通关上报 | | 关卡 | `/api/v1/levels` | 进入关卡、通关上报 |
| 游戏配置 | `/api/v1/game-configs` | 游戏全局配置 | | 游戏配置 | `/api/v1/game-configs` | 游戏全局配置 |
### 与旧版 API 的变更（⚠️ Breaking Changes） ### 与旧版 API 的变更（⚠️ Breaking Changes）
| 废弃接口 | 替代方案 | | 废弃接口 | 替代方案 |
|----------|---------| | ---------------------------------------------------------- | ------------------------------------------------------------------------ |
| `GET /api/v1/user/assets` | `GET /api/v1/user/profile` | | `GET /api/v1/user/assets` | `GET /api/v1/user/profile` |
| `POST /api/v1/user/assets/consume` | 已删除，体力在「进入关卡」时自动扣减 | | `POST /api/v1/user/assets/consume` | 已删除，体力在「进入关卡」时自动扣减 |
| `POST /api/v1/user/assets/earn` | 已删除，通关不再奖励积分 | | `POST /api/v1/user/assets/earn` | 已删除，通关不再奖励积分 |
| `GET /api/v1/user/game-data`（旧版返回 completedLevelIds） | `GET /api/v1/user/game-data`（新版返回 completedLevelCount + nextLevel） | | `GET /api/v1/user/game-data`（旧版返回 completedLevelIds） | `GET /api/v1/user/game-data`（新版返回 completedLevelCount + nextLevel） |
| `GET /api/v1/levels` | 已删除，下一关数据由 `game-data` / `enter` / `complete` 接口直接返回 | | `GET /api/v1/levels` | 已删除，下一关数据由 `game-data` / `enter` / `complete` 接口直接返回 |
| `GET /api/v1/wechat-game/levels` | 已删除 | | `GET /api/v1/wechat-game/levels` | 已删除 |
| `GET /api/v1/wechat-game/levels/:id` | `POST /api/v1/levels/:id/enter`（需鉴权 + 消耗体力） | | `GET /api/v1/wechat-game/levels/:id` | `POST /api/v1/levels/:id/enter`（需鉴权 + 消耗体力） |
| `GET /api/v1/wechat-game/configs` | `GET /api/v1/game-configs` | | `GET /api/v1/wechat-game/configs` | `GET /api/v1/game-configs` |
| `GET /api/v1/wechat-game/configs/:key` | `GET /api/v1/game-configs/:key` | | `GET /api/v1/wechat-game/configs/:key` | `GET /api/v1/game-configs/:key` |
--- ---
@@ -85,18 +88,18 @@ Authorization: Bearer <token>
```json ```json
{ {
"success": true, "success": true,
"data": { "..." : "..." }, "data": { "...": "..." },
"message": null, "message": null,
"timestamp": "2026-04-10T12:00:00.000Z" "timestamp": "2026-04-10T12:00:00.000Z"
} }
``` ```
| 字段 | 类型 | 说明 | | 字段 | 类型 | 说明 |
|------|------|------| | --------- | -------------- | --------------------------------- |
| success | boolean | 请求是否成功 | | success | boolean | 请求是否成功 |
| data | T \| null | 成功时返回业务数据，失败时为 null | | data | T \| null | 成功时返回业务数据，失败时为 null |
| message | string \| null | 失败时的错误信息，成功时为 null | | message | string \| null | 失败时的错误信息，成功时为 null |
| timestamp | string | 服务器响应时间（ISO 8601） | | timestamp | string | 服务器响应时间（ISO 8601） |
--- ---
@@ -104,13 +107,13 @@ Authorization: Bearer <token>
体力值（stamina）替代了原有的积分系统，用于控制用户进入关卡的频率。 体力值（stamina）替代了原有的积分系统，用于控制用户进入关卡的频率。
| 属性 | 值 | | 属性 | 值 |
|------|-----| | ---------- | ----------------------------- |
| 默认体力 | 50（新用户注册时） | | 默认体力 | 50（新用户注册时） |
| 上限 | 50 | | 上限 | 50 |
| 恢复速度 | 每 **10 分钟** 恢复 1 点 | | 恢复速度 | 每 **10 分钟** 恢复 1 点 |
| 消耗 | 进入**未通关**关卡时消耗 1 点 | | 消耗 | 进入**未通关**关卡时消耗 1 点 |
| 已通关关卡 | 再次进入不消耗体力 | | 已通关关卡 | 再次进入不消耗体力 |
### 体力值数据结构 ### 体力值数据结构
@@ -118,8 +121,8 @@ Authorization: Bearer <token>
```typescript ```typescript
interface StaminaInfo { interface StaminaInfo {
current: number; // 当前体力值（已计算恢复） current: number; // 当前体力值（已计算恢复）
max: number; // 体力上限，固定为 50 max: number; // 体力上限，固定为 50
nextRecoverAt: string | null; // 下一点体力恢复的时间（ISO 8601），满体力时为 null nextRecoverAt: string | null; // 下一点体力恢复的时间（ISO 8601），满体力时为 null
} }
``` ```
@@ -146,22 +149,23 @@ interface StaminaInfo {
```typescript ```typescript
interface NextLevel { interface NextLevel {
id: string; // 关卡 ID id: string; // 关卡 ID
level: number; // 关卡编号（sortOrder） level: number; // 关卡编号（sortOrder）
image1Url: string; // 图片1 URL image1Url: string; // 图片1 URL
image1Description: string | null; // 图片1 文本说明 image1Description: string | null; // 图片1 文本说明
image2Url: string; // 图片2 URL image2Url: string; // 图片2 URL
image2Description: string | null; // 图片2 文本说明 image2Description: string | null; // 图片2 文本说明
answer: string; // 答案 answer: string; // 答案
punchline: string | null; // 谐音梗说明 punchline: string | null; // 谐音梗说明
hint1: string | null; // 线索1 hint1: string | null; // 线索1
hint2: string | null; // 线索2 hint2: string | null; // 线索2
hint3: string | null; // 线索3 hint3: string | null; // 线索3
timeLimit: number | null; // 限时（秒），null 表示不限时 timeLimit: number | null; // 限时（秒），null 表示不限时
} }
``` ```
**出现位置**： **出现位置**：
- `GET /api/v1/user/game-data` → `nextLevel` - `GET /api/v1/user/game-data` → `nextLevel`
- `POST /api/v1/levels/:id/enter` → `preloadNextLevel` - `POST /api/v1/levels/:id/enter` → `preloadNextLevel`
- `POST /api/v1/levels/:id/complete` → `nextLevel` - `POST /api/v1/levels/:id/complete` → `nextLevel`
@@ -186,9 +190,9 @@ interface NextLevel {
} }
``` ```
| 字段 | 类型 | 必填 | 说明 | | 字段 | 类型 | 必填 | 说明 |
|------|------|------|------| | ---- | ------ | ---- | ---------------------------------- |
| code | string | 是 | 微信 `wx.login` 返回的临时登录凭证 | | code | string | 是 | 微信 `wx.login` 返回的临时登录凭证 |
**响应数据**： **响应数据**：
@@ -198,7 +202,7 @@ interface NextLevel {
user: { user: {
id: string; id: string;
nickname: string | null; nickname: string | null;
stamina: number; // 当前体力值（数据库原始值，不含实时恢复计算） stamina: number; // 当前体力值（数据库原始值，不含实时恢复计算）
} }
} }
``` ```
@@ -222,6 +226,7 @@ interface NextLevel {
``` ```
**客户端调用时机**： **客户端调用时机**：
- 小游戏冷启动时 - 小游戏冷启动时
- 缓存的 token 过期后（收到 401 响应时） - 缓存的 token 过期后（收到 401 响应时）
@@ -243,7 +248,7 @@ interface NextLevel {
{ {
id: string; id: string;
nickname: string | null; nickname: string | null;
stamina: StaminaInfo; // 实时体力信息 stamina: StaminaInfo; // 实时体力信息
} }
``` ```
@@ -267,6 +272,7 @@ interface NextLevel {
``` ```
**客户端调用时机**： **客户端调用时机**：
- 需要刷新用户体力显示时 - 需要刷新用户体力显示时
- 从后台切回前台时 - 从后台切回前台时
@@ -289,9 +295,9 @@ interface NextLevel {
user: { user: {
id: string; id: string;
stamina: StaminaInfo; stamina: StaminaInfo;
}; }
completedLevelCount: number; // 已通关的关卡数量 completedLevelCount: number; // 已通关的关卡数量
nextLevel: NextLevel | null; // 下一个待通关的关卡（全部通关时为 null） nextLevel: NextLevel | null; // 下一个待通关的关卡（全部通关时为 null）
} }
``` ```
@@ -349,10 +355,13 @@ interface NextLevel {
``` ```
**业务逻辑**： **业务逻辑**：
- `nextLevel` 为按 `sortOrder` 排序的第一个用户未通关的关卡
- `nextLevel` 为按 `levels.sort_key` 应用层字节序排序后的第一个用户未通关关卡
- 响应中的 `nextLevel.level` 是按当前排序回填的 0-based 连续序号，客户端不需要感知数据库内部的 `sort_key`
- 全部通关时 `nextLevel` 为 `null`，客户端应展示通关庆祝页面 - 全部通关时 `nextLevel` 为 `null`，客户端应展示通关庆祝页面
**客户端调用时机**： **客户端调用时机**：
- 游戏 Loading 页面 - 游戏 Loading 页面
- 进入主页面前 - 进入主页面前
@@ -368,9 +377,9 @@ interface NextLevel {
**路径参数**： **路径参数**：
| 参数 | 类型 | 必填 | 说明 | | 参数 | 类型 | 必填 | 说明 |
|------|------|------|------| | ---- | ------ | ---- | ------- |
| id | string | 是 | 关卡 ID | | id | string | 是 | 关卡 ID |
**请求体**：无 **请求体**：无
@@ -389,7 +398,7 @@ interface NextLevel {
hint1: string | null; hint1: string | null;
hint2: string | null; hint2: string | null;
hint3: string | null; hint3: string | null;
stamina: StaminaInfo; // 消耗后的体力信息 stamina: StaminaInfo; // 消耗后的体力信息
preloadNextLevel: NextLevel | null; // 预加载的下一关数据（无下一关时为 null） preloadNextLevel: NextLevel | null; // 预加载的下一关数据（无下一关时为 null）
} }
``` ```
@@ -438,17 +447,18 @@ interface NextLevel {
**业务逻辑**： **业务逻辑**：
| 场景 | 是否消耗体力 | 说明 | | 场景 | 是否消耗体力 | 说明 |
|------|-------------|------| | --------------------- | ------------ | ----------------- |
| 首次进入未通关关卡 | ✅ 消耗 1 点 | 正常扣减 | | 首次进入未通关关卡 | ✅ 消耗 1 点 | 正常扣减 |
| 再次进入已通关关卡 | ❌ 不消耗 | 直接返回关卡详情 | | 再次进入已通关关卡 | ❌ 不消耗 | 直接返回关卡详情 |
| 体力为 0 且关卡未通关 | ❌ 返回错误 | 返回 401 体力不足 | | 体力为 0 且关卡未通关 | ❌ 返回错误 | 返回 401 体力不足 |
- `preloadNextLevel` 为按 `sortOrder` 排在当前关卡之后的第一个未完成关卡 - `preloadNextLevel` 为按 `sortOrder` 排在当前关卡之后的第一个未完成关卡
- 当前关卡是最后一关时，`preloadNextLevel` 为 `null` - 当前关卡是最后一关时，`preloadNextLevel` 为 `null`
- 客户端可在用户答题时后台预加载 `preloadNextLevel` 中的图片资源 - 客户端可在用户答题时后台预加载 `preloadNextLevel` 中的图片资源
**客户端调用时机**： **客户端调用时机**：
- 用户在关卡选择页面点击某个关卡进入时 - 用户在关卡选择页面点击某个关卡进入时
- **必须**调用此接口获取关卡详情后才能开始游戏 - **必须**调用此接口获取关卡详情后才能开始游戏
- 客户端应在调用前检查体力是否足够，体力不足时提示用户等待恢复 - 客户端应在调用前检查体力是否足够，体力不足时提示用户等待恢复
@@ -465,9 +475,9 @@ interface NextLevel {
**路径参数**： **路径参数**：
| 参数 | 类型 | 必填 | 说明 | | 参数 | 类型 | 必填 | 说明 |
|------|------|------|------| | ---- | ------ | ---- | ------- |
| id | string | 是 | 关卡 ID | | id | string | 是 | 关卡 ID |
**请求体**： **请求体**：
@@ -477,18 +487,18 @@ interface NextLevel {
} }
``` ```
| 字段 | 类型 | 必填 | 说明 | | 字段 | 类型 | 必填 | 说明 |
|------|------|------|------| | --------- | ------ | ---- | ------------------- |
| timeSpent | number | 是 | 通关时长（秒），≥ 0 | | timeSpent | number | 是 | 通关时长（秒），≥ 0 |
**响应数据**： **响应数据**：
```typescript ```typescript
{ {
firstClear: boolean; // 是否为首次通关 firstClear: boolean; // 是否为首次通关
levelId: string; // 关卡 ID levelId: string; // 关卡 ID
timeSpent: number; // 记录的通关时长（秒） timeSpent: number; // 记录的通关时长（秒）
nextLevel: NextLevel | null; // 下一个待通关的关卡（全部通关时为 null） nextLevel: NextLevel | null; // 下一个待通关的关卡（全部通关时为 null）
} }
``` ```
@@ -567,12 +577,14 @@ interface NextLevel {
``` ```
**业务逻辑**： **业务逻辑**：
- 首次通关：记录 `timeSpent`，返回 `firstClear: true` - 首次通关：记录 `timeSpent`，返回 `firstClear: true`
- 重复通关：不覆盖记录，返回首次通关的 `timeSpent`，`firstClear: false` - 重复通关：不覆盖记录，返回首次通关的 `timeSpent`，`firstClear: false`
- `nextLevel` 为通关后按 `sortOrder` 排序的第一个未完成关卡 - `nextLevel` 为通关后按 `sortOrder` 排序的第一个未完成关卡
- 全部通关时 `nextLevel` 为 `null` - 全部通关时 `nextLevel` 为 `null`
**客户端调用时机**： **客户端调用时机**：
- 用户成功回答正确答案后调用 - 用户成功回答正确答案后调用
- 只在通关成功时调用，答错不需要上报 - 只在通关成功时调用，答错不需要上报
- 收到响应后，可直接使用 `nextLevel` 数据进入下一关（调用 `enter` 接口） - 收到响应后，可直接使用 `nextLevel` 数据进入下一关（调用 `enter` 接口）
@@ -668,11 +680,14 @@ interface CompletedLevel {
``` ```
**业务逻辑**： **业务逻辑**：
- 返回列表按关卡顺序（`sortOrder`）升序排列
- 返回列表按 `levels.sort_key` 应用层字节序升序排列
- 响应中的 `level` 是按当前排序回填的 0-based 连续序号，客户端不需要感知数据库内部的 `sort_key`
- `timeSpent` 为**首次通关**时上报的时长，重复通关不会覆盖 - `timeSpent` 为**首次通关**时上报的时长，重复通关不会覆盖
- 每项包含完整关卡信息，客户端可直接在回看页面渲染图片、答案、线索 - 每项包含完整关卡信息，客户端可直接在回看页面渲染图片、答案、线索
**客户端调用时机**： **客户端调用时机**：
- 用户打开「关卡回看 / 成就墙」页面时 - 用户打开「关卡回看 / 成就墙」页面时
- 不建议在 Loading 阶段调用（Loading 使用 `game-data` 即可） - 不建议在 Loading 阶段调用（Loading 使用 `game-data` 即可）
@@ -743,9 +758,9 @@ interface GameConfig {
**路径参数**： **路径参数**：
| 参数 | 类型 | 必填 | 说明 | | 参数 | 类型 | 必填 | 说明 |
|------|------|------|------| | ---- | ------ | ---- | -------- |
| key | string | 是 | 配置键名 | | key | string | 是 | 配置键名 |
**响应数据**： **响应数据**：
@@ -765,15 +780,15 @@ interface GameConfig {
## 错误码说明 ## 错误码说明
| HTTP Status | message | 说明 | | HTTP Status | message | 说明 |
|-------------|---------|------| | ----------- | ------------------------------------ | -------------------------------- |
| 401 | 未提供访问令牌 | 请求头缺少 Authorization | | 401 | 未提供访问令牌 | 请求头缺少 Authorization |
| 401 | 访问令牌无效或已过期 | JWT Token 无效或过期，需重新登录 | | 401 | 访问令牌无效或已过期 | JWT Token 无效或过期，需重新登录 |
| 401 | 微信登录失败，请重试 | 微信 code 无效 | | 401 | 微信登录失败，请重试 | 微信 code 无效 |
| 401 | 用户不存在 | 用户 ID 在数据库中不存在 | | 401 | 用户不存在 | 用户 ID 在数据库中不存在 |
| 401 | 体力不足 | 进入关卡时体力为 0 | | 401 | 体力不足 | 进入关卡时体力为 0 |
| 404 | 关卡 {id} 不存在 | 关卡 ID 不存在 | | 404 | 关卡 {id} 不存在 | 关卡 ID 不存在 |
| 404 | Game config with key "xxx" not found | 配置 key 不存在 | | 404 | Game config with key "xxx" not found | 配置 key 不存在 |
--- ---
@@ -848,13 +863,13 @@ interface GameState {
completedLevelCount: number; completedLevelCount: number;
// 当前关卡 // 当前关卡
currentLevel: NextLevel | null; // 来自 game-data.nextLevel 或 complete.nextLevel currentLevel: NextLevel | null; // 来自 game-data.nextLevel 或 complete.nextLevel
// 预加载的下一关 // 预加载的下一关
preloadedLevel: NextLevel | null; // 来自 enter.preloadNextLevel preloadedLevel: NextLevel | null; // 来自 enter.preloadNextLevel
// 游戏中状态 // 游戏中状态
startTime: number | null; // 开始时间戳，用于计算 timeSpent startTime: number | null; // 开始时间戳，用于计算 timeSpent
} }
``` ```
@@ -879,7 +894,9 @@ function startStaminaTimer(staminaInfo: StaminaInfo) {
if (staminaInfo.current < staminaInfo.max) { if (staminaInfo.current < staminaInfo.max) {
// 继续下一轮倒计时 // 继续下一轮倒计时
staminaInfo.nextRecoverAt = new Date(Date.now() + 10 * 60 * 1000).toISOString(); staminaInfo.nextRecoverAt = new Date(
Date.now() + 10 * 60 * 1000,
).toISOString();
startStaminaTimer(staminaInfo); startStaminaTimer(staminaInfo);
} else { } else {
staminaInfo.nextRecoverAt = null; staminaInfo.nextRecoverAt = null;
@@ -947,7 +964,7 @@ class HttpManager {
async request<T>( async request<T>(
method: 'GET' | 'POST', method: 'GET' | 'POST',
url: string, url: string,
body?: object body?: object,
): Promise<ApiResponse<T>> { ): Promise<ApiResponse<T>> {
return new Promise((resolve, reject) => { return new Promise((resolve, reject) => {
const xhr = new XMLHttpRequest(); const xhr = new XMLHttpRequest();
@@ -980,8 +997,12 @@ class HttpManager {
}); });
} }
get<T>(url: string) { return this.request<T>('GET', url); } get<T>(url: string) {
post<T>(url: string, body?: object) { return this.request<T>('POST', url, body); } return this.request<T>('GET', url);
}
post<T>(url: string, body?: object) {
return this.request<T>('POST', url, body);
}
} }
export const http = new HttpManager(); export const http = new HttpManager();
@@ -1047,7 +1068,9 @@ interface EnterLevelResponse {
} }
async function enterLevel(levelId: string): Promise<EnterLevelResponse> { async function enterLevel(levelId: string): Promise<EnterLevelResponse> {
const resp = await http.post<EnterLevelResponse>(`/v1/levels/${levelId}/enter`); const resp = await http.post<EnterLevelResponse>(
`/v1/levels/${levelId}/enter`,
);
if (resp.success && resp.data) { if (resp.success && resp.data) {
// 更新本地体力状态 // 更新本地体力状态
@@ -1079,11 +1102,11 @@ interface CompleteLevelResponse {
async function completeLevel( async function completeLevel(
levelId: string, levelId: string,
timeSpent: number timeSpent: number,
): Promise<CompleteLevelResponse> { ): Promise<CompleteLevelResponse> {
const resp = await http.post<CompleteLevelResponse>( const resp = await http.post<CompleteLevelResponse>(
`/v1/levels/${levelId}/complete`, `/v1/levels/${levelId}/complete`,
{ timeSpent } { timeSpent },
); );
if (resp.success && resp.data) { if (resp.success && resp.data) {
@@ -1149,7 +1172,6 @@ export class GameEntry extends Component {
// 全部通关 // 全部通关
showCelebration(); showCelebration();
} }
} catch (error) { } catch (error) {
console.error('启动失败:', error); console.error('启动失败:', error);
showRetryDialog(); showRetryDialog();

2
docs/api/share-challenge-api.md
View File

@@ -24,6 +24,7 @@
2. **单关进度上报**：`POST /api/v1/share/progress` 接口，用于上报用户单关通关状态和时间 2. **单关进度上报**：`POST /api/v1/share/progress` 接口，用于上报用户单关通关状态和时间
3. **进度查询**：`reportLevelProgress` 返回是否在时间限制内通过 3. **进度查询**：`reportLevelProgress` 返回是否在时间限制内通过
4. **我创建的挑战列表**：`GET /api/v1/share/created` 接口，用于查询当前用户创建过的分享挑战、参与人数和本人排名 4. **我创建的挑战列表**：`GET /api/v1/share/created` 接口，用于查询当前用户创建过的分享挑战、参与人数和本人排名
5. **关卡排序**：关卡全局顺序按 `levels.sort_key` 的应用层字节序计算，接口中的 `sortOrder` 为排序后的 0-based 连续序号
--- ---
@@ -273,6 +274,7 @@ Content-Type: application/json
**特殊逻辑**： **特殊逻辑**：
- 如果 `userId` 与分享创建者相同，不会创建 `ShareParticipant` 记录 - 如果 `userId` 与分享创建者相同，不会创建 `ShareParticipant` 记录
- `levels` 数组顺序保持分享创建时传入的 `levelIds` 顺序；每个关卡的 `sortOrder` 字段为按 `levels.sort_key` 全局排序后回填的 0-based 连续序号
- 返回的关卡列表按 `levelIds` 创建时的顺序排列 - 返回的关卡列表按 `levelIds` 创建时的顺序排列
**客户端调用场景**： **客户端调用场景**：

8
src/database/migrations/004_add_level_sort_key.sql Normal file
View File

@@ -0,0 +1,8 @@
-- Description: Add fractional-indexing sort key for level ordering.
-- Sort by this field in application code, not with MySQL ORDER BY, because the
-- default utf8mb4 collation is case-insensitive and can misorder keys.
ALTER TABLE levels
ADD COLUMN sort_key VARCHAR(64) NOT NULL DEFAULT 'a0' AFTER hint3;
CREATE INDEX levels_sort_key_idx ON levels (sort_key);

2
src/modules/level/level.controller.ts
View File

@@ -28,7 +28,7 @@ export class LevelController {
@ApiOperation({ @ApiOperation({
summary: '获取已通关关卡列表', summary: '获取已通关关卡列表',
description: description:
'返回当前用户所有已通关的关卡，按关卡顺序（sortOrder）升序排列。每项包含完整关卡信息 + 通关时长 + 通关时间。', '返回当前用户所有已通关的关卡，按关卡顺序（sortKey 字节序）升序排列。每项包含完整关卡信息 + 通关时长 + 通关时间。',
}) })
@ApiResponse({ status: 200, description: '成功' }) @ApiResponse({ status: 200, description: '成功' })
@ApiResponse({ status: 401, description: '未授权' }) @ApiResponse({ status: 401, description: '未授权' })

2
src/modules/level/level.service.ts
View File

@@ -130,7 +130,7 @@ export class LevelService {
} }
/** /**
* 获取用户已通关的关卡列表，按关卡顺序（sortOrder）升序返回 * 获取用户已通关的关卡列表，按关卡顺序（sortKey 字节序）升序返回
*/ */
async getCompletedLevels(userId: string): Promise<CompletedLevelDto[]> { async getCompletedLevels(userId: string): Promise<CompletedLevelDto[]> {
const progressList = const progressList =

2
src/modules/level/next-level.helper.ts
View File

@@ -16,7 +16,7 @@ export function toNextLevelDto(level: Level): NextLevelDto {
} }
/** /**
* Given all levels (sorted by sortOrder ASC) and the set of completed level IDs, * Given all levels (sorted by sortKey byte order) and the set of completed level IDs,
* return the next `count` uncompleted levels. * return the next `count` uncompleted levels.
*/ */
export function findNextUncompletedLevels( export function findNextUncompletedLevels(

1
src/modules/share/share.service.spec.ts
View File

@@ -30,6 +30,7 @@ describe('ShareService', () => {
hint1: `提示${i + 1}`, hint1: `提示${i + 1}`,
hint2: null, hint2: null,
hint3: null, hint3: null,
sortKey: `a${i}`,
sortOrder: i, sortOrder: i,
timeLimit: i === 0 ? 60 : null, timeLimit: i === 0 ? 60 : null,
createdAt: new Date('2026-01-01'), createdAt: new Date('2026-01-01'),

3
src/modules/wechat-game/entities/level.entity.ts
View File

@@ -48,6 +48,9 @@ export class Level {
@Column({ type: 'varchar', length: 191, nullable: true }) @Column({ type: 'varchar', length: 191, nullable: true })
hint3!: string | null; hint3!: string | null;
@Column({ type: 'varchar', length: 64, name: 'sort_key', default: 'a0' })
sortKey!: string;
@Column({ type: 'int', name: 'sort_order', default: 0 }) @Column({ type: 'int', name: 'sort_order', default: 0 })
sortOrder!: number; sortOrder!: number;

74
src/modules/wechat-game/repositories/level.repository.spec.ts Normal file
View File

@@ -0,0 +1,74 @@
import { Repository } from 'typeorm';
import { Level } from '../entities/level.entity';
import { compareSortKey, LevelRepository } from './level.repository';
describe('LevelRepository', () => {
const makeLevel = (
id: string,
sortKey: string,
sortOrder: number,
createdAt: string,
): Level =>
({
id,
image1Url: `https://example.com/${id}_1.png`,
image1Description: null,
image2Url: `https://example.com/${id}_2.png`,
image2Description: null,
answer: id,
punchline: null,
hint1: null,
hint2: null,
hint3: null,
sortKey,
sortOrder,
timeLimit: null,
createdAt: new Date(createdAt),
updatedAt: new Date(createdAt),
}) as Level;
it('compares sortKey with JS byte-order semantics', () => {
expect(compareSortKey('Zz', 'a0')).toBeLessThan(0);
expect(compareSortKey('a0', 'Zz')).toBeGreaterThan(0);
expect(compareSortKey('a0', 'a0')).toBe(0);
});
it('orders levels by sortKey in application code and normalizes sortOrder', async () => {
const rows = [
makeLevel('middle', 'a0', 10, '2026-01-02T00:00:00.000Z'),
makeLevel('first', 'Zz', 20, '2026-01-03T00:00:00.000Z'),
makeLevel('last', 'z0', 30, '2026-01-01T00:00:00.000Z'),
];
const repository = new LevelRepository({
find: jest.fn().mockResolvedValue(rows),
} as unknown as Repository<Level>);
const result = await repository.findAllOrdered();
expect(result.map((level) => level.id)).toEqual([
'first',
'middle',
'last',
]);
expect(result.map((level) => level.sortOrder)).toEqual([0, 1, 2]);
});
it('uses sortOrder and createdAt as deterministic tie breakers', async () => {
const rows = [
makeLevel('third', 'a0', 2, '2026-01-01T00:00:00.000Z'),
makeLevel('second', 'a0', 1, '2026-01-02T00:00:00.000Z'),
makeLevel('first', 'a0', 1, '2026-01-01T00:00:00.000Z'),
];
const repository = new LevelRepository({
find: jest.fn().mockResolvedValue(rows),
} as unknown as Repository<Level>);
const result = await repository.findAllOrdered();
expect(result.map((level) => level.id)).toEqual([
'first',
'second',
'third',
]);
});
});

36
src/modules/wechat-game/repositories/level.repository.ts
View File

@@ -1,9 +1,13 @@
import { Injectable } from '@nestjs/common'; import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm'; import { InjectRepository } from '@nestjs/typeorm';
import { In, Repository } from 'typeorm'; import { Repository } from 'typeorm';
import { Level } from '../entities/level.entity'; import { Level } from '../entities/level.entity';
import { ILevelRepository } from './level.repository.interface'; import { ILevelRepository } from './level.repository.interface';
export function compareSortKey(a: string, b: string): number {
return a < b ? -1 : a > b ? 1 : 0;
}
@Injectable() @Injectable()
export class LevelRepository implements ILevelRepository { export class LevelRepository implements ILevelRepository {
constructor( constructor(
@@ -12,21 +16,39 @@ export class LevelRepository implements ILevelRepository {
) {} ) {}
async findAll(): Promise<Level[]> { async findAll(): Promise<Level[]> {
return this.repository.find(); return this.findAllOrdered();
} }
async findById(id: string): Promise<Level | null> { async findById(id: string): Promise<Level | null> {
return this.repository.findOne({ where: { id } }); const levels = await this.findAllOrdered();
return levels.find((level) => level.id === id) ?? null;
} }
async findByIds(ids: string[]): Promise<Level[]> { async findByIds(ids: string[]): Promise<Level[]> {
if (ids.length === 0) return []; if (ids.length === 0) return [];
return this.repository.find({ where: { id: In(ids) } }); const idSet = new Set(ids);
const levels = await this.findAllOrdered();
return levels.filter((level) => idSet.has(level.id));
} }
async findAllOrdered(): Promise<Level[]> { async findAllOrdered(): Promise<Level[]> {
return this.repository.find({ const levels = await this.repository.find();
order: { sortOrder: 'ASC' }, return this.orderBySortKey(levels);
}); }
private orderBySortKey(levels: Level[]): Level[] {
return levels
.slice()
.sort((a, b) => {
const sortKeyCompare = compareSortKey(a.sortKey, b.sortKey);
if (sortKeyCompare !== 0) return sortKeyCompare;
if (a.sortOrder !== b.sortOrder) return a.sortOrder - b.sortOrder;
return a.createdAt.getTime() - b.createdAt.getTime();
})
.map((level, index) =>
Object.assign(Object.create(Object.getPrototypeOf(level)), level, {
sortOrder: index,
}),
);
} }
} }