348 lines
11 KiB
Markdown
348 lines
11 KiB
Markdown
# 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 完整封装
|
||
- 非微信环境自动降级
|
||
- 支持分享、登录、震动等
|
||
|