# 汪汪声浪大作战 / bark-battle BDD 验收场景 ## 背景 - 需求来源：用户提供的视频 `C:\Users\DSK\Videos\一款双方比狗叫的游戏 - 1.一款双方比狗叫的游戏(Av116504192360177,P1).mp4`，并已在 `.hermes/plans/2026-05-11_144229-bark-battle-2d-game-bdd-ddd-tdd-plan.md` 中完成抽帧分析和玩法方案整理。 - 玩法定位：浏览器 2D 声控狗叫对战小游戏，暂定中文名 `汪汪声浪大作战`，英文代号与 play type ID 建议为 `bark-battle`。 - 核心玩法：双方狗狗在 30 秒限时内通过麦克风输入“狗叫声”进行声浪拔河；系统依据声音强度、有效叫声次数和叫声节奏计算推动力，实时推动顶部红蓝能量条；倒计时结束后按能量条位置判定胜负或平局。 - 文档目的：为产品、测试、前端、后端在编码前统一可验证验收口径；本文只定义 PRD/BDD 级行为与测试映射，不实现工程代码。 ## 角色与目标 ### 主要角色 - 浏览器玩家：进入 `bark-battle` 玩法，用麦克风发声参与对战。 - 移动端玩家：在手机浏览器中进入玩法，需要看到核心游戏信息并完成授权、对战、结算。 - 无麦克风或无 API 支持玩家：设备或浏览器不支持声控输入时，需要得到明确降级反馈并可返回。 - 测试人员：依据本文场景验证权限、校准、叫声识别、能量条、胜负结算和布局兼容。 - 前端实现人员：依据本文拆分 Web Audio 输入、领域规则、Phaser/DOM HUD 表现和自动化测试。 ### 用户目标 - 玩家可以在开局前完成麦克风授权和环境噪音校准。 - 玩家发出有效狗叫时，能看到叫声计数、狗狗动画、拟声词/冲击波以及能量条变化。 - 低于阈值的背景噪音不会被误计为有效叫声。 - 单局在 30 秒后给出明确胜负、平局和关键数据。 - 移动端和不支持麦克风的环境不会进入不可操作状态。 ### 非目标 - MVP 不要求识别“是否真实狗叫”，不引入机器学习声纹/物种分类；有效输入以音量阈值、峰值间隔、持续时间和校准结果为准。 - MVP 不要求实时联机对战；可先按“玩家 vs AI 对手”完成单机浏览器 runtime。 - MVP 不要求成绩持久化、作品发布、作品架、广场和排行榜；若后续接入 Genarrative 作品闭环，需要另补玩法类型集成 PRD/技术文档。 - MVP 不要求在 UI 中长期展示大段规则说明；游戏界面应保持倒计时、能量条、狗狗、麦克风状态和结算信息为主。 - MVP 不处理竞技级反作弊；播放录音、拍桌、喊叫等非狗叫输入只作为后续公平性风险记录。 ## 业务规则口径 - 单局时长：默认 30 秒，从正式进入 `playing` 阶段开始计时。 - 能量条：使用 `-100` 到 `100` 的连续值表示，负数偏对手侧，正数偏玩家侧，`0` 为中线。 - 平局阈值：倒计时结束时，若能量条绝对值小于或等于 `drawThreshold`，判定平局；具体数值由实现配置，但测试需可注入固定阈值。 - 有效叫声：一次有效叫声至少满足：音量超过校准后的有效阈值、与上一次有效峰值间隔不小于 `minBarkGapMs`、持续时长在 `minBarkDurationMs` 到 `maxBarkDurationMs` 之间。 - 背景噪音：校准阶段采集到的环境声用于计算动态阈值；低于阈值的输入不得增加叫声次数，也不得让能量条出现可见推进。 - 推动力：玩家推动力由音量分数、有效叫声频率和连击加成组成；能量条按玩家推动力与对手推动力差值移动，并被限制在 `-100` 到 `100`。 - UI 反馈：有效叫声应触发可观察反馈，包括玩家侧狗狗张嘴/吠叫动画、拟声词或冲击波；反馈不应遮挡倒计时和顶部能量条。 ## 中文 Gherkin 场景 ### 功能: 麦克风授权与开局准备 ```gherkin 功能: 狗叫对战麦克风准备 为了让玩家能用声音参与对战 作为浏览器玩家 我希望游戏在正式开局前请求麦克风权限并完成环境校准 背景: 假如玩家进入 bark-battle 玩法页面 而且浏览器支持 navigator.mediaDevices.getUserMedia 场景: 玩家允许麦克风权限后进入环境噪音校准 当玩家同意浏览器麦克风授权 那么系统应进入环境噪音校准阶段 而且游戏不应在校准完成前进入 playing 阶段 而且界面应显示麦克风已授权的可观察状态 场景: 校准完成后进入开局倒计时 假如玩家已允许麦克风权限 而且系统已采集足够的环境噪音样本 当校准计算出有效叫声阈值 那么系统应进入开局倒计时阶段 而且倒计时结束后应进入 30 秒对战阶段 而且初始能量条应位于中线 场景: 玩家拒绝麦克风权限后不能开始声控对战 当玩家拒绝浏览器麦克风授权 那么系统应停留在无法声控游玩的状态 而且应提供重新授权或返回入口 而且不应进入校准、倒计时或 playing 阶段 ``` ### 功能: 环境噪音校准 ```gherkin 功能: 环境噪音校准 为了减少背景噪音误触发 作为浏览器玩家 我希望游戏在开局前根据当前环境设置有效叫声阈值 场景: 安静环境生成低但非零的有效阈值 假如校准阶段采集到的环境噪音 RMS 稳定低于默认噪音基线 当系统完成校准 那么有效叫声阈值应高于环境噪音平均值 而且阈值不应低于系统配置的最小阈值 场景: 嘈杂环境生成更高的有效阈值 假如校准阶段采集到的环境噪音 RMS 高于默认噪音基线 当系统完成校准 那么有效叫声阈值应随环境噪音上调 而且低于该阈值的后续输入不应计为有效叫声 场景: 校准期间无法获得有效音频样本 假如麦克风授权成功但音频样本持续为空或不可读 当校准超过系统配置的最长等待时间 那么系统应展示麦克风输入不可用状态 而且应提供重试校准入口 而且不应直接开始对战 ``` ### 功能: 有效叫声计数 ```gherkin 功能: 有效叫声计数 为了把玩家的狗叫行为转换为可计分输入 作为玩家 我希望每次符合规则的短促叫声只被计数一次 背景: 假如游戏处于 30 秒 playing 阶段 而且系统已完成环境噪音校准 场景: 单次超过阈值且间隔足够的叫声计数加一 假如玩家当前叫声次数为 0 而且上一次有效叫声时间早于 minBarkGapMs 当麦克风输入出现一次超过有效阈值且持续时长合规的峰值 那么玩家叫声次数应变为 1 而且玩家侧应出现一次吠叫动画反馈 而且画面应出现一次拟声词或冲击波反馈 场景: 持续噪音不会被无限计数 假如玩家当前叫声次数为 1 当麦克风输入持续超过阈值但没有新的峰值间隔 那么玩家叫声次数不应在每个 tick 中持续增加 而且系统最多只应记录当前连续声音段内的一次有效叫声 场景: 间隔过短的连续峰值不重复计数 假如玩家刚刚产生一次有效叫声 当麦克风输入在 minBarkGapMs 内再次出现峰值 那么玩家叫声次数不应增加 而且连击或推动力不应因该峰值重复加成 ``` ### 功能: 声音大小和连续叫声推动能量条 ```gherkin 功能: 声浪推动能量条 为了复刻双方比狗叫的核心体验 作为玩家 我希望更响、更连续的有效叫声能把顶部能量条推向自己一侧 背景: 假如游戏处于 30 秒 playing 阶段 而且能量条当前位于中线 场景: 玩家推动力高于对手时能量条向玩家侧移动 假如玩家在短时间窗口内产生多次有效叫声 而且玩家推动力高于对手推动力 当系统推进一个 simulation tick 那么能量条数值应向玩家侧增加 而且顶部红蓝能量条的玩家侧占比应变大 场景: 连续大声叫声触发更强反馈 假如玩家连续产生多次高于强叫声阈值的有效叫声 当系统计算玩家连击加成 那么玩家侧推动力应高于单次普通叫声推动力 而且玩家侧声浪或冲击波反馈应比普通叫声更明显 但是反馈不应遮挡倒计时和能量条 场景: 能量条到达边界后不会越界 假如能量条已经接近玩家侧最大值 而且玩家推动力仍高于对手推动力 当系统推进多个 simulation tick 那么能量条数值不应超过 100 而且界面不应显示超出容器范围的能量条 场景: 对手推动力高于玩家时能量条向对手侧移动 假如对手推动力高于玩家推动力 当系统推进一个 simulation tick 那么能量条数值应向对手侧减少 而且顶部红蓝能量条的对手侧占比应变大 ``` ### 功能: 低噪音和无效输入过滤 ```gherkin 功能: 背景噪音过滤 为了避免环境声替玩家自动得分 作为玩家 我希望低于阈值或不合规的声音不会被当作有效狗叫 背景: 假如游戏处于 30 秒 playing 阶段 而且系统已完成环境噪音校准 场景: 低于阈值的背景噪音不计数 当麦克风只接收到低于有效叫声阈值的背景噪音 那么玩家叫声次数不应增加 而且玩家侧不应播放吠叫动画 而且能量条不应因为该背景噪音出现可见推进 场景: 过短脉冲不计为有效叫声 假如麦克风输入峰值超过有效阈值 但是持续时长短于 minBarkDurationMs 当系统完成该声音段判定 那么玩家叫声次数不应增加 而且不应触发连击加成 场景: 过长持续声被削弱为单段输入 假如麦克风输入持续超过有效阈值 但是持续时长长于 maxBarkDurationMs 当系统完成该声音段判定 那么系统不应按多个叫声重复计数 而且该声音段的推动力应按持续噪音削弱规则处理 ``` ### 功能: 倒计时与胜负结算 ```gherkin 功能: 狗叫对战胜负结算 为了让单局对抗有明确目标 作为玩家 我希望 30 秒倒计时结束后根据能量条位置得到胜负或平局 背景: 假如游戏已经进入 30 秒 playing 阶段 场景: 倒计时每秒递减并在归零时停止对战输入 当系统时间从 30 秒推进到 0 秒 那么界面应显示倒计时归零 而且系统应进入 finished 结算阶段 而且归零后的麦克风输入不应再改变本局能量条和叫声次数 场景: 玩家侧占优时判定玩家胜利 假如倒计时归零时能量条数值大于 drawThreshold 当系统进入结算阶段 那么系统应判定玩家胜利 而且结算面板应展示玩家叫声次数、最大音量和声浪评分 而且应提供再来一局入口 场景: 对手侧占优时判定玩家失败 假如倒计时归零时能量条数值小于 -drawThreshold 当系统进入结算阶段 那么系统应判定对手胜利 而且结算面板应展示玩家叫声次数、最大音量和声浪评分 而且应提供再来一局入口 场景: 能量条接近平衡时判定平局 假如倒计时归零时能量条数值位于 -drawThreshold 到 drawThreshold 之间 当系统进入结算阶段 那么系统应判定为平局 而且结算面板应展示双方接近平衡的结果 而且应提供再来一局入口 ``` ### 功能: 再来一局与状态重置 ```gherkin 功能: 对战重开 为了让玩家快速再次挑战 作为玩家 我希望结算后可以开始新的一局且旧状态不会污染新局 场景: 结算后点击再来一局重置本局状态 假如系统处于 finished 结算阶段 而且结算面板展示上一局结果 当玩家选择再来一局 那么系统应重置剩余时间为 30 秒 而且能量条应回到中线 而且玩家叫声次数、最大音量、连击和胜负结果应清零 而且系统应重新进入校准或开局倒计时流程 场景: 结算后返回玩法入口 假如系统处于 finished 结算阶段 当玩家选择返回入口 那么系统应离开当前对战运行态 而且不应继续采集麦克风输入 ``` ### 功能: 移动端布局 ```gherkin 功能: 移动端 bark-battle 布局 为了让手机浏览器玩家可以完成声控对战 作为移动端玩家 我希望核心信息在窄屏中保持可见且可操作 场景: 移动端进入对战页面时核心元素可见 假如玩家使用宽度不超过 430px 的移动端视口 当玩家进入 bark-battle 页面 那么顶部能量条应完整显示在首屏可见区域内 而且倒计时应可见 而且双方狗狗主体不应被权限、设置或说明面板长期遮挡 而且非关键设置应收起到菜单或次级入口中 场景: 移动端授权和开始必须由用户手势触发 假如玩家使用移动端浏览器 当玩家点击开始或授权入口 那么系统才应请求麦克风权限并激活音频上下文 而且不应在页面自动加载时直接启动 AudioContext 场景: 移动端结算面板不遮挡主要操作 假如玩家在移动端完成一局对战 当系统展示结算面板 那么胜负结果、再来一局和返回入口应在不横向滚动的情况下可见 而且结算面板不应要求玩家阅读大段规则说明才能继续 ``` ### 功能: 无 getUserMedia 或不可用环境降级 ```gherkin 功能: 无麦克风 API 降级 为了避免不支持设备进入卡死状态 作为无麦克风或无 API 支持玩家 我希望系统明确告知无法声控游玩并提供退出路径 场景: 当前浏览器不支持 getUserMedia 假如玩家设备不支持 navigator.mediaDevices.getUserMedia 当玩家进入 bark-battle 页面 那么系统应显示设备或浏览器不支持麦克风输入的状态 而且应提供返回入口 而且不应展示可开始声控对战的按钮 场景: getUserMedia 调用失败但浏览器 API 存在 假如浏览器支持 getUserMedia 但是请求麦克风时返回 NotFoundError 或 NotReadableError 当系统接收到失败结果 那么系统应展示麦克风不可用状态 而且应提供重试授权或返回入口 而且不应进入 playing 阶段 场景: 非安全上下文导致麦克风不可用 假如页面运行在浏览器不允许麦克风的非安全上下文 当玩家进入 bark-battle 页面 那么系统应展示当前环境无法使用麦克风的状态 而且应提示使用受支持的安全环境或返回 而且不应开始对战倒计时 ``` ### 功能: 刷新与退出时释放麦克风资源 ```gherkin 功能: 麦克风资源释放 为了保护用户隐私并避免浏览器资源泄漏 作为浏览器玩家 我希望离开对战时麦克风采集被停止 场景: 对战中离开页面停止采集 假如玩家已经授权麦克风并处于 playing 阶段 当玩家离开 bark-battle 页面或运行态卸载 那么系统应停止当前 MediaStream 的所有音轨 而且不应继续推进本局 simulation tick 场景: 刷新页面后不沿用旧局临时状态 假如玩家在 playing 阶段刷新页面 当页面重新加载 bark-battle 那么系统应重新进入权限检查或授权准备状态 而且不应沿用刷新前的剩余时间、能量条和叫声次数作为新局结果 ``` ## 测试映射 | 场景 | 测试层级 | 建议目标文件 | 自动化状态 | | --- | --- | --- | --- | | 玩家允许麦克风权限后进入环境噪音校准 | application/component | `src/games/bark-battle/application/BarkBattleController.test.ts`, `src/games/bark-battle/ui/BarkBattlePermissionPanel.test.tsx` | planned | | 校准完成后进入开局倒计时 | application/unit | `src/games/bark-battle/application/BarkBattleController.test.ts`, `src/games/bark-battle/domain/BarkBattleSession.test.ts` | planned | | 玩家拒绝麦克风权限后不能开始声控对战 | application/component | `src/games/bark-battle/application/BarkBattleController.test.ts`, `src/games/bark-battle/ui/BarkBattlePermissionPanel.test.tsx` | planned | | 安静环境生成低但非零的有效阈值 | unit | `src/games/bark-battle/domain/BarkNoiseCalibration.test.ts` | planned | | 嘈杂环境生成更高的有效阈值 | unit | `src/games/bark-battle/domain/BarkNoiseCalibration.test.ts` | planned | | 校准期间无法获得有效音频样本 | application/component | `src/games/bark-battle/application/BarkBattleController.test.ts`, `src/games/bark-battle/ui/BarkBattlePermissionPanel.test.tsx` | planned | | 单次超过阈值且间隔足够的叫声计数加一 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned | | 持续噪音不会被无限计数 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned | | 间隔过短的连续峰值不重复计数 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned | | 玩家推动力高于对手时能量条向玩家侧移动 | unit | `src/games/bark-battle/domain/EnergyTugOfWar.test.ts` | planned | | 连续大声叫声触发更强反馈 | unit/integration/component | `src/games/bark-battle/domain/BarkBattleScoring.test.ts`, `src/games/bark-battle/ui/BarkBattleHud.test.tsx` | planned | | 能量条到达边界后不会越界 | unit | `src/games/bark-battle/domain/EnergyTugOfWar.test.ts` | planned | | 对手推动力高于玩家时能量条向对手侧移动 | unit | `src/games/bark-battle/domain/EnergyTugOfWar.test.ts` | planned | | 低于阈值的背景噪音不计数 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned | | 过短脉冲不计为有效叫声 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned | | 过长持续声被削弱为单段输入 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned | | 倒计时每秒递减并在归零时停止对战输入 | unit/application | `src/games/bark-battle/domain/BarkBattleSession.test.ts`, `src/games/bark-battle/application/BarkBattleController.test.ts` | planned | | 玩家侧占优时判定玩家胜利 | unit/component | `src/games/bark-battle/domain/BarkBattleSession.test.ts`, `src/games/bark-battle/ui/BarkBattleResultPanel.test.tsx` | planned | | 对手侧占优时判定玩家失败 | unit/component | `src/games/bark-battle/domain/BarkBattleSession.test.ts`, `src/games/bark-battle/ui/BarkBattleResultPanel.test.tsx` | planned | | 能量条接近平衡时判定平局 | unit/component | `src/games/bark-battle/domain/BarkBattleSession.test.ts`, `src/games/bark-battle/ui/BarkBattleResultPanel.test.tsx` | planned | | 结算后点击再来一局重置本局状态 | application/component | `src/games/bark-battle/application/BarkBattleController.test.ts`, `src/games/bark-battle/ui/BarkBattleResultPanel.test.tsx` | planned | | 结算后返回玩法入口 | integration/smoke | `src/games/bark-battle/application/BarkBattleController.test.ts`, Playwright 或人工 smoke 清单 | planned | | 移动端进入对战页面时核心元素可见 | component/visual/smoke | `src/games/bark-battle/ui/BarkBattleHud.test.tsx`, Playwright 移动端视口 smoke | planned | | 移动端授权和开始必须由用户手势触发 | infrastructure/application/e2e-smoke | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/application/__tests__/BarkBattleController.test.ts`, Playwright 移动端 smoke | planned | | 移动端结算面板不遮挡主要操作 | component/visual/smoke | `src/games/bark-battle/ui/__tests__/BarkBattleResultPanel.test.tsx`, Playwright 移动端视口 smoke | planned | | 当前浏览器不支持 getUserMedia | infrastructure/component | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/ui/__tests__/BarkBattlePermissionPanel.test.tsx` | planned | | getUserMedia 调用失败但浏览器 API 存在 | infrastructure/application/component | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/application/__tests__/BarkBattleController.test.ts`, `src/games/bark-battle/ui/__tests__/BarkBattlePermissionPanel.test.tsx` | planned | | 非安全上下文导致麦克风不可用 | infrastructure/application/component | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/application/__tests__/BarkBattleController.test.ts`, `src/games/bark-battle/ui/__tests__/BarkBattlePermissionPanel.test.tsx` | planned | | 对战中离开页面停止采集 | infrastructure/application/integration | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/application/__tests__/BarkBattleController.test.ts` | planned | | 刷新页面后不沿用旧局临时状态 | integration/smoke | Playwright 或人工 smoke 清单 | planned | ## 验收清单 - [ ] 权限允许、拒绝、非安全上下文、API 不支持、麦克风未找到/不可读、AudioContext 被拦截、校准超时或样本不可读均有明确状态，且不会误进入 playing。 - [ ] 校准阶段会影响有效叫声阈值，低噪音不会增加叫声计数。 - [ ] 有效叫声计数具备阈值、峰值间隔、持续时长约束。 - [ ] 能量条根据双方推动力差值双向移动，并限制在 `-100` 到 `100`。 - [ ] 30 秒归零后停止本局输入影响，并按玩家胜利、对手胜利、平局三类结果结算。 - [ ] 移动端核心元素可见，非关键设置收起，不在主画面堆叠长规则说明。 - [ ] 离开页面或返回入口时停止麦克风采集。 - [ ] 每个编码依据场景已在测试映射中标注测试层级和建议文件。 ## 开放问题 1. MVP 是否确认只做“玩家 vs AI”，还是第一版需要双人同屏或联机对战？ 2. `drawThreshold`、`minBarkGapMs`、`minBarkDurationMs`、`maxBarkDurationMs` 的首版默认值由产品/调参阶段确认，还是先采用开发可配置默认值？ 3. 是否允许无麦克风设备提供键盘/点击备用输入？若允许，需要另补非声控模式场景；若不允许，当前降级只提供返回入口。 4. 是否需要在结算中记录或上报成绩、最高音量、叫声次数和声浪评分？若需要，需补埋点/后端持久化场景。 5. bark-battle 是否作为 Genarrative 正式 play type 接入创作入口、作品发布和广场，还是先作为独立 runtime 原型验证？ 6. 狗狗、背景、拟声词和冲击波素材来源是临时占位、AI 生成，还是复用项目现有素材管线？