mp-xieyingeng/QUICK_FILE_REFERENCE.md

# 快速文件参考指南

## 🚀 最重要的 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 |