first commit

.codebuddy/plan/monetization-lite/requirements.md

@@ -0,0 +1,220 @@
+# 需求文档：坦克大战 — 极简商业化
+
+## 引言
+
+本文档基于《坦克大战经典游戏 - 极简商业化方案》，提炼可落地的商业化功能需求。核心原则是 **"轻数值、重体验、做减法"**，坚持不破坏经典坦克大战"一发子弹消灭一个敌人"的爽快感。
+
+商业化策略采用 **IAA（激励广告）+ 极简IAP（内购）** 双轨模式：
+- **唯一货币**：金币（Gold），砍掉钻石、赛季币等复杂体系
+- **核心变现**：复活续关（广告/金币）、局前Buff（金币消耗）、去广告特权（唯一内购）
+- **经济闭环**：玩游戏 → 死亡/想变强 → 看广告赚金币 → 购买复活/Buff → 继续游戏
+
+与之前的复杂商业化方案相比，本方案**砍掉**了：钻石/赛季币货币、体力系统、皮肤商店、战斗通行证、月卡、社交裂变、付费引导等重型系统。
+
+---
+
+## 需求
+
+### 需求 1：金币货币系统
+
+**用户故事：** 作为一名玩家，我希望游戏只有一种简单的货币（金币），以便我能清晰地理解如何获取和使用资源，不被复杂的货币体系困扰。
+
+#### 验收标准
+
+##### 1.1 金币获取
+1. WHEN 玩家完成一局对战（通关或失败结算） THEN 系统 SHALL 根据对局表现发放基础金币奖励（基础值50金币）。
+2. WHEN 玩家在结算界面选择观看广告 THEN 系统 SHALL 将本局金币奖励翻倍（即额外获得与基础奖励等额的金币）。
+3. WHEN 玩家在主界面点击"领金币"按钮并观看广告 THEN 系统 SHALL 发放100金币，每日上限3次。
+
+##### 1.2 金币消耗
+4. WHEN 玩家在死亡时选择金币复活 THEN 系统 SHALL 扣除200金币。
+5. WHEN 玩家在局前购买Buff THEN 系统 SHALL 扣除对应金币（护盾100金币、双倍火力150金币）。
+6. IF 玩家金币余额不足以支付消耗 THEN 系统 SHALL 提示余额不足，并引导至广告赚金币或金币包购买。
+
+##### 1.3 金币持久化
+7. WHEN 金币余额发生变动 THEN 系统 SHALL 通过 StorageManager 持久化金币数据，并同步至云端。
+8. WHEN 玩家换设备登录 THEN 系统 SHALL 从云端恢复金币余额。
+9. 系统 SHALL 设置金币上限为999,999，防止数值溢出。
+
+---
+
+### 需求 2：复活续关系统（核心变现点）
+
+**用户故事：** 作为一名玩家，我希望在坦克被击毁时有机会复活继续游戏，以便不浪费已有的关卡进度。
+
+#### 验收标准
+
+##### 2.1 复活选项
+1. WHEN 玩家坦克被击毁且生命数降为0 THEN 系统 SHALL 弹出复活选择弹窗，提供两个选项：观看广告复活（免费）、花费200金币复活。
+2. WHEN 玩家选择观看广告并完整观看激励视频 THEN 系统 SHALL 立即复活玩家，保留当前关卡进度。
+3. WHEN 玩家选择花费金币复活且余额≥200 THEN 系统 SHALL 扣除200金币并立即复活玩家。
+4. IF 玩家选择放弃复活 THEN 系统 SHALL 正常进入游戏失败结算流程。
+
+##### 2.2 复活限制
+5. WHEN 同一局游戏中玩家已使用过1次复活（无论广告或金币） THEN 系统 SHALL 不再提供复活选项，直接进入失败结算。
+6. IF 广告加载失败 THEN 系统 SHALL 仅展示金币复活选项，隐藏广告复活按钮。
+
+---
+
+### 需求 3：局前Buff系统
+
+**用户故事：** 作为一名玩家，我希望在开局前能购买一次性增益道具，以便在困难关卡中获得额外优势。
+
+#### 验收标准
+
+##### 3.1 Buff商店
+1. WHEN 玩家在关卡加载前（选关/匹配后、正式开局前） THEN 系统 SHALL 展示局前Buff购买界面。
+2. 系统 SHALL 提供以下Buff道具供购买：
+   - **护盾**（100金币）：开局自带一层护盾，可抵挡一次伤害。
+   - **双倍火力**（150金币）：开局10秒内子弹威力翻倍。
+3. WHEN 玩家选择购买Buff且金币余额充足 THEN 系统 SHALL 扣除金币并标记该Buff在本局生效。
+4. WHEN 玩家选择跳过 THEN 系统 SHALL 正常开始游戏，不施加任何Buff。
+
+##### 3.2 Buff生效
+5. WHEN 本局开始且玩家已购买护盾Buff THEN 系统 SHALL 为玩家坦克添加一层护盾效果（视觉+逻辑），受到第一次伤害时消耗护盾而非扣除生命。
+6. WHEN 本局开始且玩家已购买双倍火力Buff THEN 系统 SHALL 在开局10秒内将玩家子弹威力设为2倍，10秒后恢复正常。
+7. WHEN 本局结束（无论胜负） THEN 系统 SHALL 清除所有Buff效果，Buff不跨局保留。
+
+---
+
+### 需求 4：广告系统
+
+**用户故事：** 作为游戏运营方，我希望在合适的场景嵌入广告，以便在不破坏玩家体验的前提下获得广告收入。
+
+#### 验收标准
+
+##### 4.1 激励视频广告
+1. WHEN 关卡加载时 THEN 系统 SHALL 预加载激励视频广告资源，减少玩家等待时间。
+2. WHEN 广告播放完毕 THEN 系统 SHALL 在广告结束瞬间立即发放对应奖励。
+3. WHEN 同一广告场景在15分钟内已展示过 THEN 系统 SHALL 不重复展示相同场景的广告。
+4. IF 广告加载失败 THEN 系统 SHALL 提示"广告暂时不可用"，不阻塞玩家正常流程。
+
+##### 4.2 插屏广告
+5. WHEN 玩家完成一局游戏退出关卡时 THEN 系统 SHALL 检查是否满足插屏广告展示条件。
+6. IF 距离上次插屏广告展示已超过3局 THEN 系统 SHALL 展示一次插屏广告。
+7. IF 玩家已购买"去广告特权" THEN 系统 SHALL 永久跳过所有插屏广告。
+8. WHEN 插屏广告加载失败 THEN 系统 SHALL 静默跳过，不影响玩家正常流程。
+
+##### 4.3 每日领金币广告
+9. WHEN 玩家在主界面点击"领金币"按钮 THEN 系统 SHALL 播放激励视频广告。
+10. WHEN 广告播放完毕 THEN 系统 SHALL 发放100金币。
+11. WHEN 玩家当日已领取3次 THEN 系统 SHALL 将"领金币"按钮置灰，提示"明日再来"。
+
+##### 4.4 双倍结算广告
+12. WHEN 玩家通关进入结算界面 THEN 系统 SHALL 展示"观看广告获得双倍金币"按钮。
+13. WHEN 玩家完整观看激励视频 THEN 系统 SHALL 将本局获得的金币翻倍发放。
+14. IF 广告加载失败 THEN 系统 SHALL 提示"广告暂时不可用"，按正常倍率发放。
+
+---
+
+### 需求 5：去广告特权（唯一内购）
+
+**用户故事：** 作为一名核心玩家，我希望能一次性付费永久去除广告打断，以便获得更流畅的游戏体验。
+
+#### 验收标准
+
+1. WHEN 玩家在设置或商店中购买"去广告特权"（¥18/永久） THEN 系统 SHALL 通过微信支付完成交易。
+2. WHEN 购买成功 THEN 系统 SHALL 永久移除所有插屏广告。
+3. IF 玩家已购买去广告特权 THEN 系统 SHALL 保留激励视频广告入口（复活广告、双倍结算广告、每日领金币广告），因为这些是玩家主动选择观看以获取奖励。
+4. IF 玩家已购买去广告特权且在复活弹窗中 THEN 系统 SHALL 仍然展示"观看广告复活"选项（玩家自愿选择）。
+5. WHEN 购买记录 THEN 系统 SHALL 同步至云端，确保换设备后特权不丢失。
+6. IF 支付过程中网络中断 THEN 系统 SHALL 在网络恢复后自动查询订单状态，补发未到账的特权。
+
+---
+
+### 需求 6：金币包与新手礼包
+
+**用户故事：** 作为一名不想看广告但愿意付费的玩家，我希望能直接购买金币，以便快速获得复活和Buff所需的资源。
+
+#### 验收标准
+
+##### 6.1 金币充值包
+1. WHEN 玩家在商店中购买金币包 THEN 系统 SHALL 按以下规格发放金币：¥6 = 1000金币。
+2. WHEN 购买成功 THEN 系统 SHALL 立即将金币添加到玩家账户。
+3. WHEN 购买记录 THEN 系统 SHALL 同步至云端。
+
+##### 6.2 新手礼包
+4. WHEN 新用户首次进入游戏 THEN 系统 SHALL 在24小时内展示新手礼包购买入口（¥1 = 500金币，相当于送一次复活+一次Buff）。
+5. WHEN 新手礼包倒计时结束（24小时） THEN 系统 SHALL 移除新手礼包购买入口，不再展示。
+6. WHEN 新手礼包购买成功 THEN 系统 SHALL 立即发放500金币。
+
+##### 6.3 支付安全
+7. WHEN 玩家发起内购 THEN 系统 SHALL 通过微信支付（`wx.requestMidasPayment`）完成交易。
+8. IF 支付过程中网络中断 THEN 系统 SHALL 在网络恢复后自动查询订单状态，补发未到账商品。
+9. WHEN 购买虚拟商品 THEN 系统 SHALL 将购买记录同步至云端，确保换设备后不丢失。
+
+---
+
+### 需求 7：主界面商业化入口
+
+**用户故事：** 作为一名玩家，我希望在主界面能方便地找到商店和领金币入口，以便快速获取资源。
+
+#### 验收标准
+
+1. WHEN 玩家进入主菜单 THEN 系统 SHALL 在界面上展示"领金币"按钮，显示今日剩余领取次数（如"3/3"）。
+2. WHEN 玩家进入主菜单 THEN 系统 SHALL 展示"商店"按钮，点击后进入商店界面。
+3. WHEN 玩家进入商店界面 THEN 系统 SHALL 展示以下内容：
+   - 当前金币余额
+   - 去广告特权购买入口（已购买则显示"已拥有"）
+   - 金币充值包购买入口
+   - 新手礼包入口（仅限新用户24小时内可见）
+4. WHEN 玩家金币余额显示 THEN 系统 SHALL 在主界面顶部常驻显示当前金币数量。
+
+---
+
+### 需求 8：合规与安全
+
+**用户故事：** 作为游戏运营方，我希望游戏符合平台合规要求，以便合法运营且风险最低。
+
+#### 验收标准
+
+##### 8.1 基础合规
+1. WHEN 系统识别到未成年用户 THEN 系统 SHALL 限制每日广告展示不超过5次。
+2. WHEN 未成年用户进行消费 THEN 系统 SHALL 限制月消费上限为¥400，单次消费超过¥50时弹出确认提示。
+
+##### 8.2 反作弊
+3. WHEN 系统检测到同一广告源IP短时间内大量请求 THEN 系统 SHALL 触发广告反刷机制。
+4. WHEN 系统检测到异常大额充值行为 THEN 系统 SHALL 触发人工审核标记。
+
+---
+
+## 边界情况与技术约束
+
+### 边界情况
+1. **广告加载失败**：激励视频加载失败时，复活弹窗仅展示金币选项；结算双倍按钮提示稍后重试。
+2. **支付异常**：支付中断后自动查询订单状态并补发商品。
+3. **跨设备同步**：金币余额、去广告特权、购买记录均需云端同步。
+4. **金币溢出**：金币上限999,999，达到上限后不再发放（提示已满）。
+5. **Buff叠加**：护盾和双倍火力可同时购买，互不冲突。
+
+### 技术约束
+1. 微信小游戏内购需通过 `wx.requestMidasPayment` 接口完成。
+2. 广告SDK使用微信小游戏广告组件（`wx.createRewardedVideoAd`、`wx.createInterstitialAd`）。
+3. 金币数据需服务端校验，防止客户端篡改。
+4. 未成年人识别依赖微信平台提供的用户年龄信息接口。
+
+### 成功标准
+1. 激励视频广告转化率 ≥ 8%（复活场景）。
+2. 去广告特权购买率 ≥ 2%。
+3. 广告展示不影响核心游戏体验（玩家满意度 ≥ 4/5）。
+4. 所有内购流程零丢单率。
+
+---
+
+## 与旧方案的差异说明
+
+本极简方案相比之前的复杂商业化方案，**砍掉**了以下系统：
+- ❌ 钻石货币、赛季币货币（仅保留金币）
+- ❌ 体力系统（StaminaManager）
+- ❌ 皮肤商店系统（SkinManager、SkinData、ShopScene中的皮肤部分）
+- ❌ 战斗通行证系统（BattlePassManager、BattlePassData、BattlePassScene）
+- ❌ 月卡系统
+- ❌ 社交裂变系统（ShareManager扩展部分）
+- ❌ 付费引导系统（PromotionManager）
+- ❌ 复杂的合规系统（ComplianceManager大部分功能）
+
+**新增**了以下功能：
+- ✅ 局前Buff系统（护盾、双倍火力）
+- ✅ 每日领金币广告（主界面入口）
+- ✅ 金币复活选项（除广告外的第二复活途径）
+- ✅ 金币充值包（¥6=1000金币）

.codebuddy/plan/monetization-lite/task-item.md

@@ -0,0 +1,128 @@
+# 实施计划：坦克大战 — 极简商业化
+
+> **前置说明**：项目中已存在旧版复杂商业化代码（V1.0~V2.5），本计划需要先清理废弃模块，再重构保留模块，最后新建功能。
+
+## 现有代码盘点
+
+### 需要删除的文件（旧方案废弃）
+- `js/managers/StaminaManager.js` — 体力系统（砍掉）
+- `js/managers/SkinManager.js` — 皮肤管理器（砍掉）
+- `js/managers/BattlePassManager.js` — 战斗通行证（砍掉）
+- `js/managers/PromotionManager.js` — 付费引导（砍掉）
+- `js/managers/ShareManager.js` — 社交裂变扩展（砍掉）
+- `js/data/SkinData.js` — 皮肤数据（砍掉）
+- `js/data/BattlePassData.js` — 通行证数据（砍掉）
+- `js/scenes/BattlePassScene.js` — 通行证场景（砍掉）
+
+### 需要重构的文件（保留但大幅简化）
+- `js/managers/CurrencyManager.js` — 简化为仅金币，去掉钻石/赛季币
+- `js/managers/PaymentManager.js` — 简化为去广告+金币包+新手礼包
+- `js/managers/AdManager.js` — 保留核心逻辑，增加每日领金币广告场景
+- `js/managers/ComplianceManager.js` — 简化为基础合规
+- `js/scenes/ShopScene.js` — 重写为极简商店（去广告+金币包+新手礼包）
+- `js/scenes/GameScene.js` — 调整复活弹窗（增加金币复活选项）、集成Buff生效逻辑
+- `js/scenes/ResultScene.js` — 调整结算金币发放逻辑
+- `js/scenes/TeamResultScene.js` — 同步调整结算金币发放
+- `js/scenes/MenuScene.js` — 调整按钮布局（去掉通行证入口，增加领金币按钮）
+
+### 需要新建的文件
+- `js/managers/BuffManager.js` — 局前Buff管理器（新功能）
+- `js/scenes/BuffSelectScene.js` — 局前Buff选择界面（新功能）
+
+---
+
+## 任务清单
+
+- [ ] 1. 清理废弃模块与引用
+   - 删除以下文件：`StaminaManager.js`、`SkinManager.js`、`BattlePassManager.js`、`PromotionManager.js`、`ShareManager.js`、`SkinData.js`、`BattlePassData.js`、`BattlePassScene.js`
+   - 清理 `game.js` 中对上述模块的 import 和注册代码
+   - 清理 `GameGlobal.js` 中废弃的场景常量（BATTLE_PASS、SHOP 相关的旧定义）
+   - 清理 `MenuScene.js` 中通行证入口按钮的代码
+   - 清理 `GameScene.js` 中体力检查相关代码
+   - 清理 `Tank.js` / `PlayerTank.js` 中皮肤渲染相关代码
+   - 清理 `ResultScene.js` / `TeamResultScene.js` 中通行证任务上报代码
+   - 清理 `zh.js` / `en.js` 中废弃模块的国际化文案
+   - _需求：与旧方案的差异说明_
+
+- [ ] 2. 重构 CurrencyManager — 仅金币货币
+   - 移除钻石（diamond）和赛季币（seasonCoin）相关的所有属性和方法
+   - 保留金币（gold）的 `add`、`spend`、`getBalance` 方法
+   - 设置金币上限 999,999，`add` 时检查溢出
+   - 确保 `spend` 方法在余额不足时返回失败并触发事件
+   - 保留 StorageManager 持久化和云端同步逻辑
+   - _需求：1.1、1.2、1.3_
+
+- [ ] 3. 重构 AdManager — 增加每日领金币广告场景
+   - 保留现有的激励视频（复活、双倍结算）和插屏广告核心逻辑
+   - 新增 `AD_SCENE.DAILY_GOLD` 广告场景枚举
+   - 新增 `showDailyGoldAd()` 方法，播放完毕后触发 `daily_gold_reward` 事件
+   - 新增每日领取次数追踪（每日上限3次，跨天重置）
+   - 新增 `getDailyGoldRemaining()` 方法返回今日剩余次数
+   - 保留15分钟频控和预加载机制
+   - _需求：4.1、4.2、4.3、4.4_
+
+- [ ] 4. 重构 PaymentManager — 极简内购
+   - 移除月卡、钻石包、皮肤礼包等商品配置
+   - 仅保留三个商品：去广告特权（¥18）、金币包（¥6=1000金币）、新手礼包（¥1=500金币）
+   - 去广告特权购买后设置永久标记，通过 StorageManager 持久化
+   - 新手礼包增加24小时倒计时逻辑（首次进入游戏开始计时，超时后不可购买）
+   - 保留微信支付（`wx.requestMidasPayment`）和掉单恢复逻辑
+   - _需求：5.1~5.6、6.1~6.3_
+
+- [ ] 5. 重构 GameScene — 复活弹窗双选项 + Buff生效
+   - 修改复活弹窗：从仅"广告复活"改为"广告复活 + 金币复活（200金币）"双选项
+   - 金币复活调用 CurrencyManager.spend(200)，余额不足时按钮置灰
+   - 保留每局仅限1次复活的限制
+   - 广告加载失败时隐藏广告按钮，仅展示金币复活
+   - 集成 BuffManager：开局时检查已购Buff并施加效果（护盾、双倍火力）
+   - 移除旧的体力检查逻辑（如有）
+   - _需求：2.1~2.2、3.2_
+
+- [ ] 6. 创建 BuffManager — 局前Buff管理器
+   - 定义 Buff 类型枚举：`SHIELD`（护盾，100金币）、`DOUBLE_FIRE`（双倍火力，150金币）
+   - 实现 `purchaseBuff(type)` 方法：检查金币余额 → 扣费 → 标记本局Buff
+   - 实现 `getActiveBuffs()` 返回当前局已购买的Buff列表
+   - 实现 `clearBuffs()` 在每局结束时清除所有Buff
+   - 实现护盾逻辑：为 PlayerTank 添加 `shield` 属性，受击时优先消耗护盾
+   - 实现双倍火力逻辑：开局10秒内子弹威力×2，到期后恢复
+   - _需求：3.1、3.2_
+
+- [ ] 7. 创建 BuffSelectScene — 局前Buff选择界面
+   - 在关卡加载前（GameScene 初始化前）展示Buff选择界面
+   - 展示两个Buff卡片：护盾（100金币）、双倍火力（150金币），显示当前金币余额
+   - 点击购买时调用 BuffManager.purchaseBuff()，余额不足时提示并引导
+   - 提供"跳过"按钮直接进入游戏
+   - 护盾和双倍火力可同时购买
+   - 购买完成或跳过后，切换到 GameScene 开始游戏
+   - _需求：3.1.1~3.1.4、7.4_
+
+- [ ] 8. 重构 ShopScene — 极简商店界面
+   - 重写商店界面，移除皮肤商店相关内容
+   - 顶部显示当前金币余额
+   - 展示三个商品卡片：去广告特权（¥18，已购显示"已拥有"）、金币包（¥6=1000金币）、新手礼包（¥1=500金币，24小时倒计时）
+   - 点击购买调用 PaymentManager 对应方法
+   - 新手礼包超过24小时后自动隐藏
+   - _需求：5.1~5.2、6.1~6.2、7.3_
+
+- [ ] 9. 重构 MenuScene — 主界面商业化入口
+   - 移除通行证入口按钮
+   - 新增"领金币"按钮，显示今日剩余次数（如"🪙 领金币 3/3"），点击调用 AdManager.showDailyGoldAd()
+   - 当日次数用完后按钮置灰，显示"明日再来"
+   - 保留"商店"按钮入口
+   - 顶部常驻显示当前金币数量
+   - 调整按钮布局确保所有按钮可见
+   - _需求：7.1~7.4、4.3_
+
+- [ ] 10. 重构 ResultScene / TeamResultScene — 结算金币发放
+   - 结算时计算基础金币奖励（基础值50，可根据表现浮动）
+   - 展示"观看广告双倍金币"按钮，观看后翻倍发放
+   - 调用 CurrencyManager.add() 发放金币
+   - 移除通行证任务进度上报代码
+   - 保留插屏广告展示逻辑（每3局一次，去广告特权跳过）
+   - _需求：1.1.1~1.1.2、4.4、4.2_
+
+- [ ] 11. 简化 ComplianceManager + 注册管理器 + 国际化
+   - 简化 ComplianceManager：仅保留未成年人广告次数限制（每日≤5次）和消费限制（月≤¥400）
+   - 在 `game.js` 中注册 BuffManager，移除废弃管理器的注册
+   - 更新 `zh.js` / `en.js`：添加局前Buff、领金币、极简商店相关文案，移除废弃文案
+   - _需求：8.1~8.2_