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

2026-04-08 21:34:36 +08:00
parent fe823df01e
commit 447e7a944a
6 changed files with 672 additions and 4 deletions
--- a/QUICK_FILE_REFERENCE.md
+++ b/QUICK_FILE_REFERENCE.md
@@ -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 |
+