feat: 支持新的关卡数据结构
This commit is contained in:
richarjiang
291
docs/api-changelog-v1.1.0.md
Normal file
291
docs/api-changelog-v1.1.0.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# MemeMind API 变更文档 — 双图关卡 & 体力上限调整
|
||||
|
||||
> **版本**：v1.1.0
|
||||
> **日期**：2026-04-19
|
||||
> **影响范围**：关卡列表、进入关卡、分享挑战、体力系统
|
||||
> **兼容性**：⚠️ Breaking Change — 客户端必须适配后方可上线
|
||||
|
||||
---
|
||||
|
||||
## 一、变更概览
|
||||
|
||||
| 变更项 | 旧值 | 新值 |
|
||||
|--------|------|------|
|
||||
| 关卡图片数量 | 1 张（`imageUrl`） | 2 张（`image1Url` + `image2Url`） |
|
||||
| 图片文本说明 | 无 | 每张图片各有一个 `description` 字段 |
|
||||
| 谐音梗说明 | 无 | 新增 `punchline` 字段 |
|
||||
| 体力上限 | 5 | **50** |
|
||||
| 新用户默认体力 | 5 | **50** |
|
||||
| 体力恢复速率 | 每 10 分钟 1 点 | **不变** |
|
||||
|
||||
---
|
||||
|
||||
## 二、体力系统变更
|
||||
|
||||
### StaminaInfo 结构（不变，数值范围扩大）
|
||||
|
||||
```typescript
|
||||
interface StaminaInfo {
|
||||
current: number; // 0 ~ 50（原 0 ~ 5）
|
||||
max: number; // 固定 50（原 5）
|
||||
nextRecoverAt: string | null;
|
||||
}
|
||||
```
|
||||
|
||||
**客户端注意**：
|
||||
- 体力 UI 需要适配 0–50 的显示范围
|
||||
- 恢复速率不变，满体力恢复时间从 50 分钟变为 500 分钟（约 8.3 小时）
|
||||
- 进入关卡仍消耗 1 点体力，已通关关卡仍免费
|
||||
|
||||
---
|
||||
|
||||
## 三、接口字段变更
|
||||
|
||||
### 3.1 `GET /api/v1/levels` — 获取关卡列表
|
||||
|
||||
**删除字段**：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| ~~`imageUrl`~~ | ~~string~~ | 已删除，替换为下方双图字段 |
|
||||
|
||||
**新增字段**：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `image1Url` | string | 图片1 URL |
|
||||
| `image1Description` | string \| null | 图片1 文本说明 |
|
||||
| `image2Url` | string | 图片2 URL |
|
||||
| `image2Description` | string \| null | 图片2 文本说明 |
|
||||
| `punchline` | string \| null | 谐音梗说明（**仅通关后返回**，未通关为 null） |
|
||||
|
||||
**完整响应示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"levels": [
|
||||
{
|
||||
"id": "level_001",
|
||||
"level": 1,
|
||||
"image1Url": "https://cdn.example.com/levels/001_1.png",
|
||||
"image1Description": "一只猫在看鱼",
|
||||
"image2Url": "https://cdn.example.com/levels/001_2.png",
|
||||
"image2Description": "一条鱼在飞",
|
||||
"answer": "猫和鱼",
|
||||
"punchline": "谐音梗：鱼跃龙门 → 鱼越猫门",
|
||||
"hint1": "这是一个经典的...",
|
||||
"hint2": "和某个动物有关",
|
||||
"hint3": null,
|
||||
"completed": true,
|
||||
"timeSpent": 45
|
||||
},
|
||||
{
|
||||
"id": "level_002",
|
||||
"level": 2,
|
||||
"image1Url": "https://cdn.example.com/levels/002_1.png",
|
||||
"image1Description": "一个人在走路",
|
||||
"image2Url": "https://cdn.example.com/levels/002_2.png",
|
||||
"image2Description": "一辆车在跑",
|
||||
"answer": null,
|
||||
"punchline": null,
|
||||
"hint1": null,
|
||||
"hint2": null,
|
||||
"hint3": null,
|
||||
"completed": false,
|
||||
"timeSpent": null
|
||||
}
|
||||
],
|
||||
"total": 2
|
||||
},
|
||||
"message": null,
|
||||
"timestamp": "2026-04-19T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
> **可见性规则**：`answer`、`punchline`、`hint1`、`hint2`、`hint3` 仅在 `completed: true` 时返回，未通关均为 `null`。`image1Url`、`image1Description`、`image2Url`、`image2Description` 始终返回。
|
||||
|
||||
---
|
||||
|
||||
### 3.2 `POST /api/v1/levels/{id}/enter` — 进入关卡
|
||||
|
||||
**删除字段**：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| ~~`imageUrl`~~ | ~~string~~ | 已删除 |
|
||||
|
||||
**新增字段**：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `image1Url` | string | 图片1 URL |
|
||||
| `image1Description` | string \| null | 图片1 文本说明 |
|
||||
| `image2Url` | string | 图片2 URL |
|
||||
| `image2Description` | string \| null | 图片2 文本说明 |
|
||||
| `punchline` | string \| null | 谐音梗说明 |
|
||||
|
||||
**完整响应示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"id": "level_002",
|
||||
"level": 2,
|
||||
"image1Url": "https://cdn.example.com/levels/002_1.png",
|
||||
"image1Description": "一个人在走路",
|
||||
"image2Url": "https://cdn.example.com/levels/002_2.png",
|
||||
"image2Description": "一辆车在跑",
|
||||
"answer": "人车赛跑",
|
||||
"punchline": "谐音梗：车水马龙 → 车水人龙",
|
||||
"hint1": "第一个线索",
|
||||
"hint2": "第二个线索",
|
||||
"hint3": null,
|
||||
"stamina": {
|
||||
"current": 47,
|
||||
"max": 50,
|
||||
"nextRecoverAt": "2026-04-19T12:10:00.000Z"
|
||||
}
|
||||
},
|
||||
"message": null,
|
||||
"timestamp": "2026-04-19T12:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
> **注意**：进入关卡时 `answer` 和 `punchline` 始终返回（无论是否通关），因为用户已消耗体力进入。
|
||||
|
||||
---
|
||||
|
||||
### 3.3 `POST /api/v1/share/{shareCode}/join` — 加入分享挑战
|
||||
|
||||
分享挑战中的关卡数据同步变更。
|
||||
|
||||
**删除字段**（`levels[]` 中每个关卡）：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| ~~`imageUrl`~~ | ~~string~~ | 已删除 |
|
||||
|
||||
**新增字段**（`levels[]` 中每个关卡）：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `image1Url` | string | 图片1 URL |
|
||||
| `image1Description` | string \| null | 图片1 文本说明 |
|
||||
| `image2Url` | string | 图片2 URL |
|
||||
| `image2Description` | string \| null | 图片2 文本说明 |
|
||||
| `punchline` | string \| null | 谐音梗说明 |
|
||||
|
||||
---
|
||||
|
||||
### 3.4 未变更的接口
|
||||
|
||||
以下接口**无任何变更**，客户端无需修改：
|
||||
|
||||
| 接口 | 说明 |
|
||||
|------|------|
|
||||
| `POST /api/v1/auth/wx-login` | 登录（新用户 stamina 初始为 50，但 login 返回结构不变） |
|
||||
| `GET /api/v1/user/profile` | 用户资料（stamina.max 变为 50，结构不变） |
|
||||
| `GET /api/v1/user/game-data` | 游戏数据（stamina.max 变为 50，结构不变） |
|
||||
| `POST /api/v1/levels/{id}/complete` | 通关上报（结构完全不变） |
|
||||
| `GET /api/v1/game-configs` | 游戏配置（不变） |
|
||||
| `GET /api/v1/game-configs/{key}` | 单个配置（不变） |
|
||||
|
||||
---
|
||||
|
||||
## 四、客户端适配清单
|
||||
|
||||
### 必须修改
|
||||
|
||||
- [ ] 所有使用 `imageUrl` 的地方改为 `image1Url` + `image2Url`
|
||||
- [ ] 关卡详情页展示两张图片，每张图片下方展示 `image1Description` / `image2Description`
|
||||
- [ ] 通关后展示 `punchline`（谐音梗说明）
|
||||
- [ ] 体力 UI 适配 0–50 范围（进度条、数字显示等）
|
||||
- [ ] 更新 TypeScript 接口定义（见下方）
|
||||
|
||||
### 建议修改
|
||||
|
||||
- [ ] 体力恢复倒计时逻辑无需修改（恢复速率不变）
|
||||
- [ ] `punchline` 为 `null` 时不展示（未配置谐音梗的关卡）
|
||||
- [ ] `image2Url` 为空字符串时做兜底处理（历史关卡可能尚未配置第二张图）
|
||||
|
||||
---
|
||||
|
||||
## 五、客户端 TypeScript 接口定义
|
||||
|
||||
直接复制替换旧接口：
|
||||
|
||||
```typescript
|
||||
/** 关卡列表项 */
|
||||
interface LevelListItem {
|
||||
id: string;
|
||||
level: number;
|
||||
image1Url: string;
|
||||
image1Description: string | null;
|
||||
image2Url: string;
|
||||
image2Description: string | null;
|
||||
answer: string | null;
|
||||
punchline: string | null;
|
||||
hint1: string | null;
|
||||
hint2: string | null;
|
||||
hint3: string | null;
|
||||
completed: boolean;
|
||||
timeSpent: number | null;
|
||||
}
|
||||
|
||||
/** 进入关卡响应 */
|
||||
interface EnterLevelResponse {
|
||||
id: string;
|
||||
level: number;
|
||||
image1Url: string;
|
||||
image1Description: string | null;
|
||||
image2Url: string;
|
||||
image2Description: string | null;
|
||||
answer: string;
|
||||
punchline: string | null;
|
||||
hint1: string | null;
|
||||
hint2: string | null;
|
||||
hint3: string | null;
|
||||
stamina: StaminaInfo;
|
||||
}
|
||||
|
||||
/** 体力信息（结构不变，数值范围 0-50） */
|
||||
interface StaminaInfo {
|
||||
current: number;
|
||||
max: number; // 50
|
||||
nextRecoverAt: string | null;
|
||||
}
|
||||
|
||||
/** 分享关卡 */
|
||||
interface ShareLevel {
|
||||
id: string;
|
||||
level: number;
|
||||
image1Url: string;
|
||||
image1Description: string | null;
|
||||
image2Url: string;
|
||||
image2Description: string | null;
|
||||
answer: string;
|
||||
punchline: string | null;
|
||||
hint1: string | null;
|
||||
hint2: string | null;
|
||||
hint3: string | null;
|
||||
sortOrder: number;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、字段映射速查表
|
||||
|
||||
方便全局搜索替换：
|
||||
|
||||
| 旧字段 | 新字段 | 备注 |
|
||||
|--------|--------|------|
|
||||
| `imageUrl` | `image1Url` | 原图片字段，直接重命名 |
|
||||
| — | `image1Description` | 新增，图片1 说明文字 |
|
||||
| — | `image2Url` | 新增，第二张图片 |
|
||||
| — | `image2Description` | 新增，图片2 说明文字 |
|
||||
| — | `punchline` | 新增，谐音梗说明 |
|
||||
| `stamina.max = 5` | `stamina.max = 50` | 数值变更 |
|
||||
Reference in New Issue
Block a user