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

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

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 |
+

assets/prefabs/PageLevel.ts

@@ -688,12 +688,15 @@ export class PageLevel extends BaseView {
         // 播放成功音效
         this.playSuccessSound();
 
-        // 通关奖励：分享模式下不增加积分
-        if (!this._isShareMode) {
         const levelId = this._currentConfig?.id ?? '';
         const timeSpent = 60 - this._countdown;
+
+        if (!this._isShareMode) {
             await UserAssetsManager.instance.earnPoint(levelId, timeSpent);
             this.updatePointsLabel();
+        } else {
+            // fire-and-forget: errors are logged inside reportLevelProgress
+            void ShareManager.instance.reportLevelProgress(levelId, true, timeSpent);
         }
 
         // 显示通关弹窗

assets/scripts/config/ApiConfig.ts

@@ -15,6 +15,7 @@ export const API_ENDPOINTS = {
     USER_GAME_DATA: `${API_BASE}/user/game-data`,
     LEVELS: `${API_BASE}/wechat-game/levels`,
     SHARE_CREATE: `${API_BASE}/share`,
+    SHARE_PROGRESS: `${API_BASE}/share/progress`,
     USER_INFO: `${API_BASE}/user/info`,
 } as const;
 

assets/scripts/types/ApiTypes.ts

@@ -55,3 +55,10 @@ export interface JoinShareData {
     title: string;
     levels: ShareLevelData[];
 }
+
+/** 上报关卡进度响应 */
+export interface ReportProgressData {
+    passed: boolean;
+    timeLimit: number | null;
+    withinTimeLimit: boolean;
+}

assets/scripts/utils/ShareManager.ts

@@ -2,7 +2,7 @@ import { SpriteFrame, Texture2D, ImageAsset, assetManager } from 'cc';
 import { HttpUtil } from './HttpUtil';
 import { WxSDK } from './WxSDK';
 import { API_ENDPOINTS, getShareJoinUrl, API_TIMEOUT } from '../config/ApiConfig';
-import { ApiEnvelope, CreateShareData, JoinShareData, ShareLevelData } from '../types/ApiTypes';
+import { ApiEnvelope, CreateShareData, JoinShareData, ReportProgressData, ShareLevelData } from '../types/ApiTypes';
 import { RuntimeLevelConfig } from '../types/LevelTypes';
 
 /**
@@ -127,6 +127,44 @@ export class ShareManager {
         return this._shareLevels?.length ?? 0;
     }
 
+    /**
+     * 上报单关通关进度
+     * @param levelId 关卡 ID
+     * @param passed 是否通过
+     * @param timeSpent 用时（秒）
+     */
+    async reportLevelProgress(
+        levelId: string,
+        passed: boolean,
+        timeSpent: number,
+    ): Promise<ReportProgressData | null> {
+        if (!this._shareCode) {
+            console.warn('[ShareManager] reportLevelProgress: 无分享码，跳过上报');
+            return null;
+        }
+
+        try {
+            const response = await HttpUtil.post<ApiEnvelope<ReportProgressData>>(
+                API_ENDPOINTS.SHARE_PROGRESS,
+                { shareCode: this._shareCode, levelId, passed, timeSpent },
+                API_TIMEOUT.DEFAULT,
+            );
+
+            if (!response.success || !response.data) {
+                console.error('[ShareManager] 上报进度失败:', response.message);
+                return null;
+            }
+
+            console.log(
+                `[ShareManager] 上报成功: passed=${response.data.passed}, withinTimeLimit=${response.data.withinTimeLimit}`,
+            );
+            return response.data;
+        } catch (err) {
+            console.error('[ShareManager] 上报进度异常:', err);
+            return null;
+        }
+    }
+
     triggerWxShare(title: string, shareCode: string): void {
         WxSDK.shareAppMessage({
             title: title || '来挑战我出的谐音梗吧！',