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

feat: 支持分享关卡通关上报

Browse Source
This commit is contained in:
richarjiang
2026-04-08 21:34:36 +08:00
parent fe823df01e
commit 447e7a944a
6 changed files with 672 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

347
PROJECT_EXPLORATION_REPORT.md Normal file
View File

@@ -0,0 +1,347 @@
# mp-xieyingeng 项目完整探索报告
## 📋 项目概述
**项目名称**: 写英语谐音梗小游戏 (mp-xieyingeng)
**引擎**: Cocos Creator 3.x (TypeScript)
**平台**: 微信小游戏
**架构**: 分布式页面管理系统 + 单例工具类
---
## 📁 完整目录结构
```
assets/
├── main.ts # 主入口脚本，初始化 ViewManager
├── PageLoading.ts # 加载页面，处理登录、资源预加载、分享码检测
├── prefabs/ # 页面预制体和组件
│ ├── PageHome.ts # 首页
│ ├── PageLevel.ts # 关卡页面（核心游戏逻辑）
│ ├── PageWriteLevels.ts # 写关卡页面（创建/编辑关卡）
│ ├── PagePreviewLevels.ts # 预览关卡页面
│ ├── PagePKData.ts # 挑战数据页面
│ ├── PagePKDetail.ts # 挑战详情页面
│ ├── PassModal.ts # 通关弹窗
│ └── Toast.ts # Toast 提示组件
├── scripts/
│ ├── config/
│ │ └── ApiConfig.ts # API 配置（端点、超时时间等）
│ ├── core/
│ │ ├── BaseView.ts # 页面基类（生命周期管理）
│ │ └── ViewManager.ts # 页面管理器（单例，栈管理）
│ ├── types/
│ │ ├── LevelTypes.ts # 关卡数据类型定义
│ │ └── ApiTypes.ts # API 响应类型定义
│ └── utils/ # 工具类（单例）
│ ├── HttpUtil.ts # HTTP 请求工具（GET/POST + JWT 认证）
│ ├── ShareManager.ts # 分享管理器（创建分享、加入分享）
│ ├── LevelDataManager.ts # 关卡数据管理器（API 拉取、缓存、图片加载）
│ ├── UserAssetsManager.ts # 用户资产管理器（积分同步）
│ ├── AuthManager.ts # 认证管理器（微信登录、Token 管理）
│ ├── StorageManager.ts # 本地存储管理器（进度、积分、Token）
│ ├── WxSDK.ts # 微信 SDK 封装（登录、分享、震动等）
│ ├── ToastManager.ts # Toast 管理器
│ └── [其他工具类...]
└── resources/ # 游戏资源
├── audios/ # 音效文件
├── images/
│ ├── level/ # 关卡图片
│ ├── pageHome/ # 首页图片
│ ├── pageLevel/ # 关卡页面图片
│ └── pageLoading/ # 加载页面图片
```
---
## 🎯 所有 TypeScript 文件列表
### 核心入口
- `assets/main.ts` - 主脚本，注册所有页面到 ViewManager
- `assets/PageLoading.ts` - 加载页面，并行执行登录 + 资源加载
### 页面组件（每个继承 BaseView）
- `assets/prefabs/PageHome.ts` - 首页
- `assets/prefabs/PageLevel.ts` - **核心游戏逻辑**
- `assets/prefabs/PageWriteLevels.ts` - 写关卡
- `assets/prefabs/PagePreviewLevels.ts` - 预览关卡
- `assets/prefabs/PagePKData.ts` - PK 数据展示
- `assets/prefabs/PagePKDetail.ts` - PK 详情
- `assets/prefabs/PassModal.ts` - 通关弹窗
- `assets/prefabs/Toast.ts` - Toast 提示
### 核心框架
- `assets/scripts/core/BaseView.ts` - 页面基类（onViewLoad、onViewShow、onViewHide、onViewDestroy）
- `assets/scripts/core/ViewManager.ts` - 页面管理器（栈管理、缓存、生命周期调用）
### 配置
- `assets/scripts/config/ApiConfig.ts` - API 端点 + 超时配置
### 类型定义
- `assets/scripts/types/ApiTypes.ts` - API 响应类型
- `assets/scripts/types/LevelTypes.ts` - 关卡数据类型
### 工具类（单例）
- `assets/scripts/utils/HttpUtil.ts` - **HTTP 请求**（GET/POST + JWT）
- `assets/scripts/utils/ShareManager.ts` - **分享系统**
- `assets/scripts/utils/LevelDataManager.ts` - **关卡数据管理**
- `assets/scripts/utils/UserAssetsManager.ts` - 积分管理
- `assets/scripts/utils/AuthManager.ts` - **认证 + 登录**
- `assets/scripts/utils/StorageManager.ts` - 本地存储
- `assets/scripts/utils/WxSDK.ts` - 微信 SDK 封装
- `assets/scripts/utils/ToastManager.ts` - Toast 管理
- 其他：RoundedRectMask、BackgroundScaler 等
---
## 💾 关卡通关逻辑核心
### 1. 通关判定（PageLevel.ts 第 660-673 行）
```typescript
onSubmitAnswer(): void {
const userAnswer = this.getAnswer();
if (userAnswer === this._currentConfig.answer) {
this.showSuccess();
} else {
this.showError();
}
}
```
### 2. 通关奖励（PageLevel.ts 第 679-701 行）
```typescript
private async showSuccess(): Promise<void> {
// 停止倒计时
this.stopCountdown();
// 非分享模式才增加积分
if (!this._isShareMode) {
const levelId = this._currentConfig?.id;
const timeSpent = 60 - this._countdown;
await UserAssetsManager.instance.earnPoint(levelId, timeSpent);
}
// 显示通关弹窗
this._showPassModal();
}
```
### 3. 进度保存（PageLevel.ts 第 785-816 行）
```typescript
private async nextLevel(): Promise<void> {
// 非分享模式才保存进度
if (!this._isShareMode) {
StorageManager.onLevelCompleted(this.currentLevelIndex);
}
this.currentLevelIndex++;
// 检查是否全部通关
const totalLevels = this._isShareMode
? ShareManager.instance.getShareLevelCount()
: LevelDataManager.instance.getLevelCount();
if (this.currentLevelIndex >= totalLevels) {
// 全部通关，返回首页
ViewManager.instance.back();
} else {
// 加载下一关
await this.initLevel();
this.startCountdown();
}
}
```
### 4. 已通关关卡同步（PageLoading.ts 第 115-139 行）
```typescript
private _syncProgressFromServer(): void {
// 服务端返回的已通关关卡 ID
const completedIds = AuthManager.instance.completedLevelIds;
// 转换为本地索引
const maxCompletedIndex = LevelDataManager.instance.getMaxCompletedIndex(completedIds);
// 取较大值，防止进度回退
if (maxCompletedIndex > localMax) {
StorageManager.onLevelCompleted(maxCompletedIndex);
}
}
```
---
## 🔗 API 端点一览
### 已配置的 API（ApiConfig.ts）
```
API_BASE = 'https://ilookai.cn/api/v1'
端点：
- POST /auth/wx-login # 微信登录
- GET /user/assets # 获取用户积分
- POST /user/assets/consume # 消耗积分（解锁线索）
- POST /user/assets/earn # 获得积分（通关奖励）
- GET /user/game-data # 获取用户数据（进度 + 积分）
- GET /wechat-game/levels # 获取所有关卡
- POST /share # 创建分享
- POST /share/{code}/join # 加入分享
- GET /user/info # 获取用户信息
```
---
## 🏗️ 架构特点
### 1. 单例模式
- `ViewManager` - 页面管理
- `LevelDataManager` - 关卡数据
- `ShareManager` - 分享管理
- `UserAssetsManager` - 积分管理
- `AuthManager` - 认证
- `StorageManager` - 本地存储（全静态）
- `ToastManager` - Toast 管理
- `WxSDK` - 微信 SDK（全静态）
- `HttpUtil` - HTTP 工具（全静态）
### 2. 页面栈管理
- `ViewManager` 维护页面栈
- `open()` - 打开页面，压栈
- `back()` - 返回上一页，出栈
- `replace()` - 替换当前页，不压栈
### 3. 生命周期
每个页面 4 个阶段：
- `onViewLoad()` - 首次创建时调用
- `onViewShow()` - 每次显示时调用
- `onViewHide()` - 隐藏时调用
- `onViewDestroy()` - 销毁时调用
---
## 🎯 关键发现
### ✅ 已有的工具类
#### HTTP 请求
- **HttpUtil.ts** - GET/POST + JWT 认证
- 支持自定义超时时间
- 自动添加 Authorization 头
- 泛型支持
#### 数据管理
- **LevelDataManager.ts** - 关卡数据 + 图片缓存
- API 请求重试机制
- 图片懒加载（预加载下一关）
- URL -> SpriteFrame 缓存
- **UserAssetsManager.ts** - 积分管理
- 消耗积分（解锁线索）
- 获得积分（通关奖励）
- 自动降级本地处理
- **AuthManager.ts** - 认证 + 登录
- 微信登录流程
- Token 恢复与验证
- 获取通关进度
- **StorageManager.ts** - 本地存储
- 积分、Token、进度、用户信息
- 全静态工具类
#### 游戏逻辑
- **ShareManager.ts** - 分享系统
- 创建分享、加入分享
- 独立数据管理，不影响正常进度
- **ViewManager.ts** - 页面管理
- 栈管理
- 缓存机制
- 生命周期管理
- **WxSDK.ts** - 微信 API 封装
- 登录、分享、震动
- 隐私授权、用户信息
- 非微信环境自动降级
---
## 📊 游戏流程图
### 正常模式
```
启动 → PageLoading
├─ 并行加载：登录 + 关卡数据
├─ 检测分享码（无）
└─ 打开 PageHome
├─ 开始游戏 → PageLevel
│ ├─ 加载关卡
│ ├─ 倒计时 60s
│ ├─ 提交答案
│ ├─ 判定成功/失败
│ ├─ 通关 → PassModal
│ │ ├─ earnPoint()（加积分）
│ │ ├─ onLevelCompleted()（保存进度）
│ │ └─ nextLevel()
│ └─ 重复 2-7
└─ PK → PageWriteLevels
```
### 分享模式
```
微信分享链接（含 shareCode）
↓
PageLoading
├─ 检测到分享码
└─ ShareManager.joinShare(code)
↓
PageLevel（shareMode=true）
├─ 从 ShareManager 加载关卡
├─ 不增加积分
├─ 不保存本地进度
└─ 全部通关 → 返回首页
```
---
## 💡 核心要点
1. **HTTP 工具** ✅
- HttpUtil.ts 已完整实现
- 支持 JWT 认证
- 可配置超时
2. **关卡数据** ✅
- LevelDataManager 从 API 拉取
- 支持图片缓存 + 懒加载
- 支持重试机制
3. **通关逻辑** ✅
- 判定：字符串比对（PageLevel.ts:660）
- 奖励：earnPoint()（PageLevel.ts:679）
- 进度：StorageManager.onLevelCompleted()（PageLevel.ts:785）
- 服务端同步：PageLoading.ts:115
4. **分享系统** ✅
- 创建 + 加入完全独立
- 不影响正常游戏进度
- 懒加载关卡数据
5. **页面管理** ✅
- ViewManager 栈管理
- 4 个生命周期回调
- 缓存机制
6. **认证系统** ✅
- 微信登录 + Token 恢复
- 自动添加授权头
- 获取用户通关记录
7. **本地存储** ✅
- StorageManager 集中管理
- 支持进度 + 积分 + Token
- 带有默认值和数据校验
8. **微信 API** ✅
- WxSDK 完整封装
- 非微信环境自动降级
- 支持分享、登录、震动等

272
QUICK_FILE_REFERENCE.md Normal file
View File

@@ -0,0 +1,272 @@
# 快速文件参考指南
## 🚀 最重要的 5 个文件
### 1. **PageLevel.ts** - 核心游戏逻辑
位置：`assets/prefabs/PageLevel.ts`
```
关键方法：
- onViewLoad() → 初始化关卡
- onSubmitAnswer() → 第 660 行，提交答案判定
- showSuccess() → 第 679 行，通关逻辑
- nextLevel() → 第 785 行，进度保存
```
### 2. **HttpUtil.ts** - HTTP 请求工具
位置：`assets/scripts/utils/HttpUtil.ts`
```
关键方法：
- get<T>(url, timeout) → GET 请求
- post<T>(url, data, timeout) → POST 请求
- setAuthToken(token) → 设置 JWT
```
### 3. **LevelDataManager.ts** - 关卡数据管理
位置：`assets/scripts/utils/LevelDataManager.ts`
```
关键方法：
- initialize(onProgress) → API 加载 + 预加载第一关
- ensureLevelReady(index) → 按需加载关卡
- preloadNextLevel(index) → 静默预加载下一关
- getMaxCompletedIndex(ids) → 获取已通关索引
```
### 4. **ShareManager.ts** - 分享系统
位置：`assets/scripts/utils/ShareManager.ts`
```
关键方法：
- createShare(title, levelIds) → 创建分享
- joinShare(code) → 加入分享
- triggerWxShare(title, code) → 触发分享
- isShareMode → 判断是否分享模式
```
### 5. **AuthManager.ts** - 认证管理
位置：`assets/scripts/utils/AuthManager.ts`
```
关键方法：
- initialize() → 初始化（恢复 token 或微信登录）
- wxLogin() → 微信登录
- validateToken() → 验证 token 有效性
```
---
## 📝 TypeScript 文件快速导航
### 文件位置速查表
| 文件名 | 路径 | 用途 |
|------|------|------|
| main.ts | assets/ | 主入口，初始化 ViewManager |
| PageLoading.ts | assets/ | 加载页面，登录 + 资源加载 |
| PageHome.ts | assets/prefabs/ | 首页 |
| PageLevel.ts | assets/prefabs/ | 关卡页面 **⭐** |
| PageWriteLevels.ts | assets/prefabs/ | 写关卡页面 |
| PagePreviewLevels.ts | assets/prefabs/ | 预览关卡 |
| PassModal.ts | assets/prefabs/ | 通关弹窗 |
| Toast.ts | assets/prefabs/ | Toast 提示 |
| BaseView.ts | assets/scripts/core/ | 页面基类 |
| ViewManager.ts | assets/scripts/core/ | 页面管理器 |
| ApiConfig.ts | assets/scripts/config/ | API 配置 |
| ApiTypes.ts | assets/scripts/types/ | API 类型定义 |
| LevelTypes.ts | assets/scripts/types/ | 关卡类型定义 |
| HttpUtil.ts | assets/scripts/utils/ | HTTP 工具 **⭐** |
| ShareManager.ts | assets/scripts/utils/ | 分享管理 **⭐** |
| LevelDataManager.ts | assets/scripts/utils/ | 关卡数据 **⭐** |
| UserAssetsManager.ts | assets/scripts/utils/ | 积分管理 |
| AuthManager.ts | assets/scripts/utils/ | 认证管理 **⭐** |
| StorageManager.ts | assets/scripts/utils/ | 本地存储 |
| WxSDK.ts | assets/scripts/utils/ | 微信 SDK |
| ToastManager.ts | assets/scripts/utils/ | Toast 管理 |
---
## 🔧 API 端点速查
```
基础地址：https://ilookai.cn/api/v1
认证相关：
- POST /auth/wx-login 微信登录
用户资产：
- GET /user/assets 获取积分
- POST /user/assets/consume 消耗积分（解锁线索）
- POST /user/assets/earn 获得积分（通关）
- GET /user/game-data 获取用户数据
关卡相关：
- GET /wechat-game/levels 获取所有关卡
分享相关：
- POST /share 创建分享
- POST /share/{code}/join 加入分享
用户相关：
- GET /user/info 获取用户信息
```
---
## 💾 关键数据结构
### 关卡配置
```typescript
interface RuntimeLevelConfig {
id: string;
name: string;
spriteFrame: SpriteFrame | null;
clue1: string;
clue2: string;
clue3: string;
answer: string;
}
```
### API 响应
```typescript
interface ApiEnvelope<T> {
success: boolean;
data: T | null;
message: string | null;
}
```
### 用户进度
```typescript
interface UserProgress {
currentLevelIndex: number; // 当前关卡（0-based）
maxUnlockedLevelIndex: number; // 最高已解锁
}
```
---
## 🎮 游戏流程关键代码位置
| 步骤 | 文件 | 行数 | 描述 |
|-----|------|------|------|
| 初始化 | main.ts | 34-90 | 注册页面 |
| 加载 | PageLoading.ts | 27-90 | 并行登录 + 加载关卡 |
| 分享检测 | PageLoading.ts | 61-77 | 检测分享码 |
| 进度同步 | PageLoading.ts | 115-139 | 服务端进度同步 |
| 加载关卡 | PageLevel.ts | 175-197 | 初始化关卡 |
| 倒计时 | PageLevel.ts | 593-641 | 60 秒计时 |
| 提交答案 | PageLevel.ts | 660-673 | 判定答案 |
| 通关处理 | PageLevel.ts | 679-701 | 播放音效 + 加积分 + 弹窗 |
| 进度保存 | PageLevel.ts | 785-816 | 下一关 + 进度保存 |
---
## 🔗 工具类单例调用方式
```typescript
// HTTP 请求
HttpUtil.get<T>(url, timeout)
HttpUtil.post<T>(url, data, timeout)
HttpUtil.setAuthToken(token)
// 关卡数据
LevelDataManager.instance.initialize(onProgress)
LevelDataManager.instance.ensureLevelReady(index)
LevelDataManager.instance.getLevelCount()
// 用户资产
UserAssetsManager.instance.fetchPoints()
UserAssetsManager.instance.consumePoint(levelId, hintIndex)
UserAssetsManager.instance.earnPoint(levelId, timeSpent)
// 认证
AuthManager.instance.initialize()
AuthManager.instance.isLoggedIn
AuthManager.instance.userId
// 本地存储
StorageManager.getPoints()
StorageManager.setPoints(points)
StorageManager.getCurrentLevelIndex()
StorageManager.onLevelCompleted(index)
// 分享
ShareManager.instance.createShare(title, levelIds)
ShareManager.instance.joinShare(code)
ShareManager.instance.isShareMode
// 微信 API
WxSDK.isWechat()
WxSDK.login()
WxSDK.shareAppMessage(config)
// 页面管理
ViewManager.instance.open(viewId, options)
ViewManager.instance.back()
ViewManager.instance.replace(viewId, options)
```
---
## 📊 优先级指南（修改时参考）
### 优先级 A（核心，谨慎修改）
- `PageLevel.ts` - 游戏逻辑
- `HttpUtil.ts` - HTTP 请求
- `LevelDataManager.ts` - 数据加载
- `ViewManager.ts` - 页面管理
### 优先级 B（重要）
- `ShareManager.ts` - 分享系统
- `AuthManager.ts` - 认证系统
- `StorageManager.ts` - 本地存储
- `UserAssetsManager.ts` - 积分管理
### 优先级 C（可选）
- `WxSDK.ts` - 微信 API
- `ToastManager.ts` - 提示管理
- 其他 UI 文件
---
## 🎯 常见修改清单
### 修改 API 端点
→ `assets/scripts/config/ApiConfig.ts`
### 修改通关逻辑
→ `assets/prefabs/PageLevel.ts`（第 660-816 行）
### 修改关卡数据加载
→ `assets/scripts/utils/LevelDataManager.ts`
### 修改积分系统
→ `assets/scripts/utils/UserAssetsManager.ts`
### 修改分享流程
→ `assets/scripts/utils/ShareManager.ts`
### 修改页面流转
→ `assets/scripts/core/ViewManager.ts`
### 修改本地存储
→ `assets/scripts/utils/StorageManager.ts`
---
## 📞 快速查找
**如果要找 xxx 功能：**
| 功能 | 查看 |
|-----|------|
| HTTP 请求 | HttpUtil.ts |
| 关卡加载 | LevelDataManager.ts |
| 通关判定 | PageLevel.ts:660 |
| 通关奖励 | PageLevel.ts:679 |
| 进度保存 | PageLevel.ts:785 |
| 分享功能 | ShareManager.ts |
| 登录流程 | AuthManager.ts |
| 本地数据 | StorageManager.ts |
| 页面跳转 | ViewManager.ts |
| 微信功能 | WxSDK.ts |
| Toast 提示 | ToastManager.ts |

9
assets/prefabs/PageLevel.ts
View File

@@ -688,12 +688,15 @@ export class PageLevel extends BaseView {
// 播放成功音效
this.playSuccessSound();
// 通关奖励：分享模式下不增加积分
const levelId = this._currentConfig?.id ?? '';
const timeSpent = 60 - this._countdown;
if (!this._isShareMode) {
const levelId = this._currentConfig?.id ?? '';
const timeSpent = 60 - this._countdown;
await UserAssetsManager.instance.earnPoint(levelId, timeSpent);
this.updatePointsLabel();
} else {
// fire-and-forget: errors are logged inside reportLevelProgress
void ShareManager.instance.reportLevelProgress(levelId, true, timeSpent);
}
// 显示通关弹窗

1
assets/scripts/config/ApiConfig.ts
View File

@@ -15,6 +15,7 @@ export const API_ENDPOINTS = {
USER_GAME_DATA: `${API_BASE}/user/game-data`,
LEVELS: `${API_BASE}/wechat-game/levels`,
SHARE_CREATE: `${API_BASE}/share`,
SHARE_PROGRESS: `${API_BASE}/share/progress`,
USER_INFO: `${API_BASE}/user/info`,
} as const;

7
assets/scripts/types/ApiTypes.ts
View File

@@ -55,3 +55,10 @@ export interface JoinShareData {
title: string;
levels: ShareLevelData[];
}
/** 上报关卡进度响应 */
export interface ReportProgressData {
passed: boolean;
timeLimit: number | null;
withinTimeLimit: boolean;
}

40
assets/scripts/utils/ShareManager.ts
View File

@@ -2,7 +2,7 @@ import { SpriteFrame, Texture2D, ImageAsset, assetManager } from 'cc';
import { HttpUtil } from './HttpUtil';
import { WxSDK } from './WxSDK';
import { API_ENDPOINTS, getShareJoinUrl, API_TIMEOUT } from '../config/ApiConfig';
import { ApiEnvelope, CreateShareData, JoinShareData, ShareLevelData } from '../types/ApiTypes';
import { ApiEnvelope, CreateShareData, JoinShareData, ReportProgressData, ShareLevelData } from '../types/ApiTypes';
import { RuntimeLevelConfig } from '../types/LevelTypes';
/**
@@ -127,6 +127,44 @@ export class ShareManager {
return this._shareLevels?.length ?? 0;
}
/**
* 上报单关通关进度
* @param levelId 关卡 ID
* @param passed 是否通过
* @param timeSpent 用时（秒）
*/
async reportLevelProgress(
levelId: string,
passed: boolean,
timeSpent: number,
): Promise<ReportProgressData | null> {
if (!this._shareCode) {
console.warn('[ShareManager] reportLevelProgress: 无分享码，跳过上报');
return null;
}
try {
const response = await HttpUtil.post<ApiEnvelope<ReportProgressData>>(
API_ENDPOINTS.SHARE_PROGRESS,
{ shareCode: this._shareCode, levelId, passed, timeSpent },
API_TIMEOUT.DEFAULT,
);
if (!response.success || !response.data) {
console.error('[ShareManager] 上报进度失败:', response.message);
return null;
}
console.log(
`[ShareManager] 上报成功: passed=${response.data.passed}, withinTimeLimit=${response.data.withinTimeLimit}`,
);
return response.data;
} catch (err) {
console.error('[ShareManager] 上报进度异常:', err);
return null;
}
}
triggerWxShare(title: string, shareCode: string): void {
WxSDK.shareAppMessage({
title: title || '来挑战我出的谐音梗吧！',