63 lines
7.8 KiB
Markdown
63 lines
7.8 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
这是一个 Cocos Creator 3.8.8 项目，用于开发小游戏/可玩广告。
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
assets/
|
||
├── main.ts # 主入口脚本
|
||
├── main.scene # 主场景
|
||
├── PageLoading.ts # 页面加载组件
|
||
├── PageLoading.prefab # 预制体
|
||
├── scripts/
|
||
│ └── utils/
|
||
│ └── BackgroundScaler.ts # 背景缩放工具组件
|
||
└── resources/
|
||
└── images/ # 图片资源
|
||
```
|
||
|
||
## Development Commands
|
||
|
||
此项目使用 Cocos Creator 编辑器进行开发：
|
||
|
||
- **打开项目**: 使用 Cocos Creator 3.8.8 打开此目录
|
||
- **运行预览**: 在 Cocos Creator 编辑器中点击 "Play" 按钮
|
||
- **构建**: 使用编辑器菜单 `Project > Build` 或快捷键 `Cmd+B`
|
||
|
||
## TypeScript Coding
|
||
|
||
遵循 Cocos Creator 3.x 组件系统架构：
|
||
|
||
- 使用 `@ccclass` 装饰器声明组件
|
||
- 继承 `cc.Component` 基类
|
||
- 生命周期方法: `onLoad` -> `start` -> `update` -> `onDestroy`
|
||
- 使用 `cc.` 命名空间访问引擎 API（如 `cc.view`, `cc.Node`, `cc.Component` 等）
|
||
|
||
## Friend Share Challenge Flow
|
||
|
||
当前项目里的好友分享挑战链路不是普通闯关的变体，而是一条单独的模式切换链路。
|
||
|
||
1. 发起入口在首页 `PageHome` 的 `PK` 按钮，点击后进入 `PageWriteLevels` 进行选题，而不是从普通关卡页直接发起。[assets/prefabs/PageHome.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageHome.ts#L153)
|
||
2. `PageWriteLevels` 只允许从当前用户“已通关关卡”中选题，数据来自 `CompletedLevelsManager.fetch()`；当前产品规则要求必须选满 `6` 关。[assets/prefabs/PageWriteLevels.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageWriteLevels.ts#L140) [assets/prefabs/PageWriteLevels.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageWriteLevels.ts#L507)
|
||
3. 预览只是本地页面跳转：`PageWriteLevels` 把 `selectedIndices + shareTitle` 传给 `PagePreviewLevels`，后者再从 `CompletedLevelsManager` 当前缓存里按索引读答案、提示和封面图，不会请求后端。[assets/prefabs/PageWriteLevels.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageWriteLevels.ts#L525) [assets/prefabs/PagePreviewLevels.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PagePreviewLevels.ts#L108)
|
||
4. 正式分享时，`PageWriteLevels` 会把选中的索引转成 `levelIds`，调用 `ShareManager.createShare(title, levelIds)`，命中 `POST /share` 创建挑战并拿到 `shareCode`。[assets/prefabs/PageWriteLevels.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageWriteLevels.ts#L536) [assets/scripts/utils/ShareManager.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/scripts/utils/ShareManager.ts#L53)
|
||
5. 创建成功后，前端会尝试上传一次发起者头像昵称，再调用 `WxSDK.shareAppMessage` 发微信卡片；关键 query 只有 `shareCode`，好友侧是靠这个码重新拉题单。[assets/prefabs/PageWriteLevels.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageWriteLevels.ts#L563) [assets/scripts/utils/ShareManager.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/scripts/utils/ShareManager.ts#L219)
|
||
6. 好友从微信卡片打开小游戏时，启动页 `PageLoading` 会从 `WxSDK.getShareCodeFromLaunch()` 读取启动参数；只要拿到 `shareCode` 且登录成功，就会调用 `ShareManager.joinShare(code)`，然后跳过首页，直接以 `shareMode=true` 打开 `PageLevel`。[assets/PageLoading.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/PageLoading.ts#L82) [assets/scripts/utils/WxSDK.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/scripts/utils/WxSDK.ts#L302)
|
||
7. `ShareManager.joinShare()` 会把后端返回的分享关卡列表转成内存里的 `RuntimeLevelConfig[]`，首关图立即预加载，后续关卡按需懒加载；这条链路不会走普通模式的 `AuthManager.nextLevel`、`LevelDataManager`、`enterLevel`。[assets/scripts/utils/ShareManager.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/scripts/utils/ShareManager.ts#L73) [assets/scripts/utils/ShareManager.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/scripts/utils/ShareManager.ts#L150)
|
||
8. `PageLevel` 进入分享模式后，当前题数据直接来自 `ShareManager.ensureShareLevelReady(index)`，不会调用 `StaminaManager.enterLevel()`，因此分享挑战不消耗体力，也不依赖 enter 接口补答案和提示。[assets/prefabs/PageLevel.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageLevel.ts#L258) [assets/prefabs/PageLevel.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageLevel.ts#L330)
|
||
9. 作答判定仍在 `PageLevel.onSubmitAnswer()` 本地完成，本质就是把用户输入和 `config.answer` 做字符串比较；答对后显示通关链路并切到下一题，答错则弹错误弹窗。[assets/prefabs/PageLevel.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageLevel.ts#L1504)
|
||
10. 分享模式下只有答对时会调用 `ShareManager.reportLevelProgress(levelId, true, timeSpent)` 上报 `POST /share/progress`。当前没有把答错或超时作为失败事件上报，所以服务端拿到的是“成功进度”，不是完整挑战行为流。[assets/prefabs/PageLevel.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageLevel.ts#L1566) [assets/scripts/utils/ShareManager.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/scripts/utils/ShareManager.ts#L187)
|
||
11. 分享模式下切下一题只会 `_shareLevelIndex++`；全部做完后清空分享态并回首页。超时弹窗点回首页时也会先清理分享态，避免脏状态残留。[assets/prefabs/PageLevel.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageLevel.ts#L1831) [assets/prefabs/PageLevel.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageLevel.ts#L1880)
|
||
|
||
## Current Gaps
|
||
|
||
1. 分享模式标题展示的是分享内序号 `第 1 关 / 第 2 关`，不是题库真实关卡号。[assets/prefabs/PageLevel.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageLevel.ts#L1004)
|
||
2. `PassModal` 和 `TimeoutModal` 内部的分享按钮发的是普通 `level=...` query，不是好友挑战 `shareCode`，所以它们目前不属于这条好友分享挑战链路。[assets/prefabs/PassModal.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PassModal.ts#L453) [assets/prefabs/TimeoutModal.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/TimeoutModal.ts#L136)
|
||
3. `ShareManager.joinShare()` 当前没有把后端题目的 `timeLimit` 写入 `RuntimeLevelConfig`，而 `PageLevel` 会用 `config.timeLimit ?? 60` 兜底，因此分享题默认统一 60 秒。[assets/scripts/utils/ShareManager.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/scripts/utils/ShareManager.ts#L91) [assets/prefabs/PageLevel.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageLevel.ts#L416)
|
||
4. 选题页和预览页通过 `selectedIndices` 对同一份 completed list 建立映射，若列表在页面间发生刷新或顺序变化，存在按索引错位的风险；更稳妥的传参应该是 `levelIds` 或完整快照。[assets/prefabs/PageWriteLevels.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PageWriteLevels.ts#L528) [assets/prefabs/PagePreviewLevels.ts](/Users/richard/Documents/code/cocosProject/mp-xieyingeng/assets/prefabs/PagePreviewLevels.ts#L192)
|