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

2026-04-08 21:34:36 +08:00
parent fe823df01e
commit 447e7a944a
6 changed files with 672 additions and 4 deletions
--- a/PROJECT_EXPLORATION_REPORT.md
+++ b/PROJECT_EXPLORATION_REPORT.md
@@ -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 完整封装
+   - 非微信环境自动降级
+   - 支持分享、登录、震动等
+