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