GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity
Files
hermes/hermes-1e775b03
Genarrative/.hermes/plans/2026-05-11_170028-bark-battle-three-phase-browser-ai-db-plan.md

28 KiB
Raw Permalink Blame History

bark-battle 三阶段实施计划：浏览器原型 → AI 创作入口 → 数据库落地

For Hermes: Use subagent-driven-development skill to implement this plan task-by-task.

Goal: 按“三阶段”推进 bark-battle / 汪汪声浪大作战：第一阶段先做纯浏览器可运行游戏原型并验证玩法跑通；第二阶段接入 Genarrative 创作入口，用 AI 生成可试玩内容；第三阶段再打通后端数据库、发布、成绩和作品闭环。

Architecture: 第一阶段只在前端 runtime 内闭环，优先落 src/games/bark-battle/ 与直达路由，不依赖后端和 SpacetimeDB。第二阶段在已有创作入口、Agent flow controller、结果页和 runtime shell 上接入 bark-battle，AI 只生成配置化草稿，不承接正式业务真相。第三阶段按 server-rs + Axum + SpacetimeDB DDD 分层落库，前端只展示后端投影和调用后端 API。

Tech Stack: React 19、TypeScript、Vite、Vitest、Testing Library；第一阶段优先 DOM/Canvas 原型，可在验证玩法后再引入 Phaser 3；后端阶段使用 server-rs、Axum、SpacetimeDB、shared-contracts。

0. 当前上下文 / 假设

  • 现有需求与技术文档：
    • docs/prd/BARK_BATTLE_BDD_2026-05-11.md
    • docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md
    • docs/technical/BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md
  • 用户明确要求阶段顺序：
    1. 第一阶段：先制作纯浏览器运行的游戏原型，需要测试游戏功能是否能跑通。
    2. 第二阶段：打通创作入口，使用 AI 赋能游戏内容创作。
    3. 第三阶段：最后打通数据库落地。
  • 因此本计划调整原技术方案中的落地优先级：
    • 第一阶段不新增后端表、不接发布、不接作品架。
    • 第一阶段可以用 mock / local draft 配置与直达路由 /bark-battle 完成 playable prototype。
    • 第一阶段若 Phaser 依赖尚未安装，优先用 React DOM + Canvas/CSS 2D 原型跑通功能；待核心规则验证后再决定是否引入 Phaser，避免第一阶段被依赖安装和素材管线阻塞。
  • 当前仓库 package.json 还没有 phaser 依赖；如实现者选择 Phaser，需要单独评估依赖引入、包体和测试影响。
  • 本计划只写计划，不直接实现代码。

1. 总体分阶段验收口径

Phase 1：纯浏览器游戏原型

目标：打开本地前端路由即可玩到一局 bark-battle，并通过自动测试确认核心规则跑通。

必须满足：

  • 可从 /bark-battle 进入独立原型页面。
  • 不登录、不请求后端、不依赖数据库。
  • 支持开发 mock input：点击/按键/按钮可模拟音量峰值；有真实麦克风时可走 Web Audio。
  • 能完成：权限/开始 → 校准或 mock 准备 → 倒计时 → 30 秒 playing → 结算 → 再来一局。
  • 低于阈值输入不计数；有效叫声计数；能量条向玩家或对手移动；结算胜/负/平。
  • 移动端至少能看到能量条、倒计时、双方狗狗、主要按钮和结算。

Phase 2：AI 创作入口

目标：创作者能从创作中心选择 bark-battle，用 AI 生成玩法配置草稿，并进入结果页试玩。

必须满足：

  • 后端入口配置中出现 bark-battle，按开关展示/可点击。
  • 前端类型分流、SelectionStage、工作台、结果页、runtime 入口齐全。
  • AI 生成内容仅限配置化草稿：标题、主题、狗狗外观描述、背景风格、难度、局长、AI 对手参数、提示文案 key 等。
  • 生成结果可在本地 runtime 中试玩。
  • 未落库前可先用 session/local state 保存草稿，但要清楚标识为“未发布草稿”。

Phase 3：数据库落地与正式作品闭环

目标：bark-battle 草稿、发布态配置、runtime start/finish、成绩和作品级游玩埋点都进入后端 DDD / SpacetimeDB 链路。

必须满足：

  • shared-contracts、module-bark-battle、spacetime-module、spacetime-client、api-server 分层清晰。
  • 发布为稳定作品 ID，runtime 从后端读取发布态 config。
  • start 成功写 work_play_start：scope_kind=work、scope_id=稳定作品 ID、metadata 包含 playType/workId/sourceRoute/userId。
  • finish 只上传派生指标，不保存原始麦克风音频、波形或可还原语音内容。
  • 作品架/广场/分享/排行榜如启用，均来自后端投影。

2. Phase 1：纯浏览器运行游戏原型

Task 1.1：补齐阶段边界文档

Objective: 在现有技术方案中明确“先浏览器原型，后 AI 创作，最后数据库”的落地顺序，避免实现时过早接后端。

Files:

  • Modify: docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md
  • Modify: docs/prd/BARK_BATTLE_BDD_2026-05-11.md

Steps:

  1. 在 runtime 技术方案中新增“三阶段落地顺序”小节。
  2. 明确 Phase 1 不接后端、不接数据库、不接创作入口事实源。
  3. 在 BDD 中补充“浏览器原型 smoke”验收场景。
  4. 运行： 
    npm run check:encoding -- docs/prd/BARK_BATTLE_BDD_2026-05-11.md docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md
git diff --check

Expected: 编码检查和 diff 空白检查通过。

Task 1.2：建立 Phase 1 目录骨架和类型

Objective: 建立不依赖 React/DOM/Web Audio 的核心类型，后续所有测试和 UI 都围绕这些类型。

Files:

  • Create: src/games/bark-battle/domain/BarkBattleTypes.ts
  • Create: src/games/bark-battle/application/BarkBattleConfig.ts

Key design:

  • BarkBattlePhase = 'permission' | 'calibration' | 'countdown' | 'playing' | 'finished' | 'unavailable'
  • MicrophoneFailureReason 覆盖已有文档中的 9 类失败原因。
  • BarkBattleSnapshot 包含 phase/uiState/errorReason/statusMessageKey/remainingMs/energy/player/opponent/winner/result/lastEvents。
  • BarkBattleConfig 包含 roundDurationMs/drawThreshold/minBarkGapMs/minBarkDurationMs/maxBarkDurationMs/balanceFactor/calibrationMaxWaitMs。

Tests:

  • 本任务可先不写运行时逻辑，但需要让 typecheck 能引用这些类型。

Validation:

npm run typecheck
npm run check:encoding -- src/games/bark-battle/domain/BarkBattleTypes.ts src/games/bark-battle/application/BarkBattleConfig.ts

Task 1.3：TDD 实现叫声检测 BarkDetector

Objective: 用纯函数/纯类把音频样本转换为有效叫声事件。

Files:

  • Create: src/games/bark-battle/domain/BarkDetector.ts
  • Create: src/games/bark-battle/domain/__tests__/BarkDetector.test.ts

Test cases:

  1. 超过阈值、持续时长合规、间隔足够时计为一次有效叫声。
  2. 持续噪音不在每个 tick 无限计数。
  3. 低于阈值的背景噪音不计数。
  4. minBarkGapMs 内连续峰值不重复计数。
  5. 过短脉冲不计数；过长持续声削弱为单段输入。

Validation:

npm run test -- --run src/games/bark-battle/domain/__tests__/BarkDetector.test.ts
npm run typecheck

Task 1.4：TDD 实现能量条 EnergyTugOfWar

Objective: 验证玩家/对手推动力能稳定改变 energy，并 clamp 到 -100..100。

Files:

  • Create: src/games/bark-battle/domain/EnergyTugOfWar.ts
  • Create: src/games/bark-battle/domain/__tests__/EnergyTugOfWar.test.ts

Test cases:

  1. 玩家 power 高于对手时 energy 增加。
  2. 对手 power 高于玩家时 energy 减少。
  3. energy 不超过 100。
  4. energy 不低于 -100。
  5. power 相等时变化不超过浮点误差。

Validation:

npm run test -- --run src/games/bark-battle/domain/__tests__/EnergyTugOfWar.test.ts
npm run typecheck

Task 1.5：TDD 实现单局状态机 BarkBattleSession

Objective: 跑通 permission/calibration/countdown/playing/finished/unavailable 状态流转和结算。

Files:

  • Create: src/games/bark-battle/domain/BarkBattleSession.ts
  • Create: src/games/bark-battle/domain/BarkBattleScoring.ts
  • Create: src/games/bark-battle/domain/OpponentStrategy.ts
  • Create: src/games/bark-battle/domain/__tests__/BarkBattleSession.test.ts
  • Create: src/games/bark-battle/domain/__tests__/BarkBattleScoring.test.ts

Test cases:

  1. 校准完成后进入 countdown。
  2. countdown 结束后进入 playing。
  3. playing 中 remainingMs 随 tick 递减。
  4. remainingMs <= 0 后进入 finished。
  5. energy > drawThreshold 判定玩家胜。
  6. energy < -drawThreshold 判定对手胜。
  7. abs(energy) <= drawThreshold 判定平局。
  8. finished 后新输入不再改变本局计数和能量。

Validation:

npm run test -- --run src/games/bark-battle/domain/__tests__/BarkBattleSession.test.ts src/games/bark-battle/domain/__tests__/BarkBattleScoring.test.ts
npm run typecheck

Task 1.6：实现 mock-first Application Controller

Objective: 不依赖真实麦克风，先用 mock audio sample 驱动完整 snapshot。

Files:

  • Create: src/games/bark-battle/application/BarkBattleController.ts
  • Create: src/games/bark-battle/application/BarkBattleSnapshotStore.ts
  • Create: src/games/bark-battle/application/__tests__/BarkBattleController.test.ts

Behavior:

  • startWithMockInput() 进入校准完成或直接 countdown。
  • submitMockSample(sample) 更新玩家输入。
  • tick(deltaMs) 推进对手、能量条、倒计时。
  • restart() 重置状态。
  • failMicrophone(reason) 进入 phase: 'unavailable'，并设置 errorReason/statusMessageKey。

Test cases:

  1. mock start 后能进入 countdown/playing。
  2. 提交 mock 峰值后 bark count 增加。
  3. tick 后 energy 可变化。
  4. finish 后生成 result。
  5. failMicrophone('permission-denied') 不进入 playing。

Validation:

npm run test -- --run src/games/bark-battle/application/__tests__/BarkBattleController.test.ts
npm run typecheck

Task 1.7：实现浏览器原型 UI Shell（不接平台）

Objective: 提供 /bark-battle 可访问的 playable prototype。

Files:

  • Create: src/BarkBattlePlaygroundApp.tsx
  • Create: src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx
  • Create: src/games/bark-battle/ui/BarkBattleHud.tsx
  • Create: src/games/bark-battle/ui/BarkBattleResultPanel.tsx
  • Create: src/games/bark-battle/ui/BarkBattleHud.css
  • Modify: src/routing/appRoutes.tsx

Behavior:

  • 新增路由匹配：/bark-battle。
  • 首屏只有清爽开始面板，不常驻大段规则。
  • 提供开发原型按钮：开始、模拟叫声、模拟对手增强、再来一局。
  • playing 画面展示：顶部能量条、倒计时、玩家/对手狗狗、叫声次数、麦克风/mock 状态。
  • 结算面板独立居中，不追加在当前面板下方。

UI constraints:

  • 移动端优先。
  • 正常 playing 阶段不在 playfield 常驻规则说明。
  • 大动效不遮挡顶部能量条和倒计时。

Validation:

npm run test -- --run src/games/bark-battle/ui/**/*.test.tsx
npm run typecheck
npm run dev:web
# 手动 smoke: 访问 /bark-battle → 开始 → 模拟叫声 → energy 变化 → 结算 → 再来一局

Task 1.8：实现 HUD 组件测试

Objective: 自动验证核心 UI 状态，不只依赖人工试玩。

Files:

  • Create: src/games/bark-battle/ui/__tests__/BarkBattleHud.test.tsx
  • Create: src/games/bark-battle/ui/__tests__/BarkBattleResultPanel.test.tsx

Test cases:

  1. playing 阶段展示倒计时和能量条。
  2. energy 正值时玩家侧占比更大。
  3. energy 负值时对手侧占比更大。
  4. permission-denied 展示重试授权入口。
  5. unsupported 不展示开始声控按钮。
  6. finished 展示胜负、叫声次数、再来一局。

Validation:

npm run test -- --run src/games/bark-battle/ui/__tests__/BarkBattleHud.test.tsx src/games/bark-battle/ui/__tests__/BarkBattleResultPanel.test.tsx
npm run typecheck

Task 1.9：接入真实 Web Audio（可晚于 mock 原型）

Objective: 在支持麦克风的浏览器中真实采样并驱动 controller，同时保留 mock fallback 便于测试。

Files:

  • Create: src/games/bark-battle/infrastructure/BrowserMicrophoneInput.ts
  • Create: src/games/bark-battle/infrastructure/AudioAnalyserSampler.ts
  • Create: src/games/bark-battle/infrastructure/MicrophonePermission.ts
  • Create: src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts
  • Create: src/games/bark-battle/infrastructure/__tests__/AudioAnalyserSampler.test.ts

Behavior:

  • 用户点击开始后才请求麦克风。
  • 用户手势后创建/resume AudioContext。
  • 输出归一化 BarkAudioSample。
  • 捕获并映射：unsupported、permission-denied、non-secure-context、not-found、not-readable、audio-context-blocked、unknown。
  • stop/restart/page unload 时停止 tracks。

Validation:

npm run test -- --run src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts src/games/bark-battle/infrastructure/__tests__/AudioAnalyserSampler.test.ts
npm run typecheck
npm run dev:web
# 手动 smoke: 真实麦克风授权 → 校准 → 发声 → 结算

Task 1.10：Phase 1 收口验证

Objective: 确认“纯浏览器原型”已经可以交给产品/测试试玩。

Commands:

npm run test -- --run src/games/bark-battle/domain/**/*.test.ts src/games/bark-battle/application/**/*.test.ts src/games/bark-battle/infrastructure/**/*.test.ts src/games/bark-battle/ui/**/*.test.tsx
npm run typecheck
npm run lint:eslint
npm run check:encoding
npm run dev:web

Manual smoke checklist:

  • /bark-battle 能打开。
  • mock 模式可完整完成一局。
  • 真实麦克风模式可授权、校准、发声、结算。
  • 拒绝权限后不会进入 playing。
  • 移动端窄屏能看到核心信息并能点击主要按钮。
  • 再来一局不会继承上一局 energy/barkCount/result。

3. Phase 2：打通创作入口，用 AI 赋能内容创作

Task 2.1：定义 bark-battle 草稿契约（前端本地版）

Objective: 在接后端前，先定义 AI 可生成的 runtime draft shape。

Files:

  • Create: packages/shared/src/contracts/barkBattle.ts（临时前端共享类型，后端阶段再对齐 Rust shared-contracts）
  • Create: src/services/bark-battle-creation/barkBattleDraftDefaults.ts
  • Create: src/services/bark-battle-creation/barkBattleDraftValidation.ts

Draft fields:

  • title
  • description
  • themePrompt
  • playerDogName
  • opponentDogName
  • backgroundStyle
  • difficulty
  • roundDurationMs
  • drawThreshold
  • opponentConfig
  • audioSensitivityPreset
  • visualStyle

Validation:

npm run test -- --run src/services/bark-battle-creation/**/*.test.ts
npm run typecheck

Task 2.2：新增创作入口配置

Objective: 让 bark-battle 出现在创作中心入口中，但可通过后端入口配置开关控制。

Files likely to change:

  • server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs
  • server-rs/crates/module-runtime/src/domain.rs
  • server-rs/crates/module-runtime/src/application.rs
  • server-rs/crates/shared-contracts/src/creation_entry_config.rs
  • src/components/platform-entry/platformEntryCreationTypes.ts
  • src/components/platform-entry/platformEntryCreationTypes.test.ts

Plan:

  1. 在入口 seed 中新增 bark-battle，首轮可设：visible: true、open: true（若需要灰度则 open: false）。
  2. 前端展示派生只消费 API 返回，不恢复旧静态入口事实源。
  3. 更新排序和锁定态测试。

Validation:

npm run test -- src/components/platform-entry/platformEntryCreationTypes.test.ts
npm run typecheck
cd server-rs && cargo check -p api-server -p spacetime-module --no-default-features

Task 2.3：扩展 SelectionStage 与流程分流

Objective: 点击 bark-battle 入口后进入对应创作工作台。

Files likely to change:

  • src/components/platform-entry/platformEntryTypes.ts
  • src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
  • src/components/platform-entry/usePlatformCreationAgentFlowController.ts（如复用通用 agent flow）

Stages:

  • bark-battle-agent-workspace
  • bark-battle-generating（可选）
  • bark-battle-result
  • bark-battle-runtime

Validation:

npm run test -- src/components/platform-entry/**/*.test.tsx src/components/platform-entry/**/*.test.ts
npm run typecheck

Task 2.4：实现 AI 创作工作台

Objective: 用对话式或表单式输入生成 BarkBattleDraft。

Files:

  • Create: src/components/bark-battle-creation/BarkBattleAgentWorkspace.tsx
  • Create: src/services/bark-battle-creation/barkBattleCreationClient.ts
  • Create: src/services/bark-battle-creation/barkBattlePromptBuilder.ts
  • Create: src/services/bark-battle-creation/__tests__/barkBattlePromptBuilder.test.ts

Behavior:

  • 用户输入一句主题，例如“柴犬在赛博公园比谁叫得响”。
  • AI 返回结构化草稿。
  • 前端校验并填默认值，不让非法 roundDuration/difficulty 进入 runtime。
  • 错误时保留用户输入和已生成草稿。

Validation:

npm run test -- --run src/services/bark-battle-creation/**/*.test.ts
npm run typecheck

Task 2.5：实现结果页与试玩入口

Objective: AI 草稿生成后可查看、返回编辑、进入 Phase 1 runtime 试玩。

Files:

  • Create: src/components/bark-battle-result/BarkBattleResultView.tsx
  • Create: src/components/bark-battle-result/BarkBattleResultView.test.tsx
  • Modify: src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx（允许传入 draft config）

Behavior:

  • 展示标题、主题、狗狗名、背景风格、难度、局长。
  • 提供“返回编辑”“试玩”按钮。
  • 暂不展示发布按钮，或发布按钮显示为后端阶段能力。

Validation:

npm run test -- --run src/components/bark-battle-result/BarkBattleResultView.test.tsx
npm run typecheck
npm run dev:web
# 手动 smoke: 创作入口 → AI 草稿 → 结果页 → 试玩 → 返回编辑

Task 2.6：Phase 2 收口验证

Commands:

npm run test -- src/components/platform-entry/platformEntryCreationTypes.test.ts src/components/bark-battle-result/BarkBattleResultView.test.tsx src/services/bark-battle-creation/**/*.test.ts src/games/bark-battle/**/*.test.ts src/games/bark-battle/**/*.test.tsx
npm run typecheck
npm run lint:eslint
npm run check:encoding

Manual smoke checklist:

  • 创作中心展示 bark-battle。
  • 点击入口进入工作台。
  • AI 可生成草稿。
  • 草稿结果页可展示并返回编辑。
  • 试玩使用草稿配置影响 runtime 表现。
  • 未接数据库前不会假装发布成功。

4. Phase 3：数据库落地与正式作品闭环

Task 3.1：补齐 shared contracts

Objective: 前后端共享 bark-battle DTO，避免前端手写正式契约漂移。

Files likely to change:

  • server-rs/crates/shared-contracts/src/bark_battle.rs
  • server-rs/crates/shared-contracts/src/lib.rs
  • packages/shared/src/contracts/barkBattle.ts

DTO:

  • BarkBattleDraft
  • BarkBattlePublishedConfig
  • CreateBarkBattleSessionRequest/Response
  • BarkBattleRuntimeStartRequest/Response
  • BarkBattleRuntimeFinishRequest/Response
  • BarkBattleRunResult
  • BarkBattleScoreSummary
  • BarkBattleLeaderboardEntry

Validation:

npm run typecheck
cd server-rs && cargo check -p shared-contracts --no-default-features

Task 3.2：新增 module-bark-battle 纯领域模块

Objective: 后端正式分数、配置校验、提交合法性不写在 api-server handler 里。

Files:

  • Create: server-rs/crates/module-bark-battle/
  • Modify: server-rs/Cargo.toml

Responsibilities:

  • 配置合法性校验。
  • run start/finish 状态约束。
  • 派生指标范围校验。
  • 分数与排行榜排序分计算。
  • 不接 Axum、不接 SpacetimeDB、不接 HTTP。

Validation:

cd server-rs && cargo test -p module-bark-battle --no-default-features
cd server-rs && cargo check -p module-bark-battle --no-default-features

Task 3.3：SpacetimeDB 表、reducer、migration

Objective: 保存草稿、发布态配置、run、result、leaderboard 投影。

Files likely to change:

  • server-rs/crates/spacetime-module/src/runtime/bark_battle.rs（或按现有模块目录命名）
  • server-rs/crates/spacetime-module/src/migration.rs
  • server-rs/crates/spacetime-module/src/lib.rs
  • 生成绑定目录（通过命令生成，不手改生成物）

Tables draft:

  • bark_battle_draft
  • bark_battle_published_config
  • bark_battle_run
  • bark_battle_run_result
  • bark_battle_leaderboard_entry

Reducers/procedures:

  • create_bark_battle_draft
  • publish_bark_battle_config
  • start_bark_battle_run
  • finish_bark_battle_run
  • list_bark_battle_leaderboard

Validation:

npm run spacetime:generate
cd server-rs && cargo check -p spacetime-module --no-default-features
npm run check:server-rs-ddd

Task 3.4：spacetime-client facade

Objective: api-server 通过 facade 调用 SpacetimeDB，不直接散落 reducer 细节。

Files likely to change:

  • server-rs/crates/spacetime-client/src/runtime.rs
  • server-rs/crates/spacetime-client/src/mapper.rs
  • server-rs/crates/spacetime-client/src/lib.rs

Validation:

cd server-rs && cargo check -p spacetime-client --no-default-features

Task 3.5：api-server BFF 路由

Objective: 提供创作、发布态 runtime start/finish、leaderboard API。

Files likely to change:

  • server-rs/crates/api-server/src/bark_battle.rs
  • server-rs/crates/api-server/src/main.rs 或路由注册文件

Routes draft:

  • POST /api/bark-battle/sessions
  • GET /api/bark-battle/sessions/:sessionId
  • POST /api/bark-battle/runtime/start
  • POST /api/bark-battle/runtime/finish
  • GET /api/bark-battle/works/:workId/runtime-config
  • GET /api/bark-battle/works/:workId/leaderboard

Tracking:

  • runtime start 成功后主动写 work_play_start。
  • scope_kind=work。
  • scope_id=稳定作品 ID。
  • metadata 包含 playType=bark-battle、workId、sourceRoute、userId。

Validation:

npm run api-server
# 另一个终端检查 /healthz，并执行对应 API smoke
cd server-rs && cargo check -p api-server --no-default-features

Task 3.6：前端正式 client 与 runtime 切换

Objective: runtime 从本地草稿模式升级为可读取后端发布态 config，并提交正式派生结果。

Files likely to change:

  • Create: src/services/bark-battle-runtime/barkBattleRuntimeClient.ts
  • Create: src/services/bark-battle-works/barkBattleWorksClient.ts
  • Modify: src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx
  • Modify: src/components/bark-battle-result/BarkBattleResultView.tsx
  • Modify: src/components/custom-world-home/creationWorkShelf.ts
  • Modify: src/components/custom-world-home/CustomWorldCreationHub.tsx
  • Modify: src/services/publicWorkCode.ts

Behavior:

  • 本地 preview 仍可使用 draft config。
  • 正式作品 runtime 必须先调用 start API，拿 run token/session。
  • finish 只提交派生 metrics。
  • 发布后刷新作品架/广场。

Validation:

npm run test -- src/services/bark-battle-runtime/**/*.test.ts src/games/bark-battle/**/*.test.ts src/games/bark-battle/**/*.test.tsx
npm run typecheck
npm run check:encoding

Task 3.7：Phase 3 收口验证

Commands:

npm run test -- src/games/bark-battle/**/*.test.ts src/games/bark-battle/**/*.test.tsx src/services/bark-battle-runtime/**/*.test.ts src/services/bark-battle-creation/**/*.test.ts
npm run typecheck
npm run lint:eslint
npm run check:encoding
npm run check:server-rs-ddd
cd server-rs && cargo test -p module-bark-battle --no-default-features
cd server-rs && cargo check -p api-server -p spacetime-module -p spacetime-client -p shared-contracts --no-default-features
npm run api-server

Manual smoke checklist:

  • 创作者生成并发布 bark-battle 作品。
  • 玩家从作品页进入 runtime。
  • start API 成功并写 work_play_start。
  • 浏览器本地完成一局。
  • finish API 只上传派生指标。
  • 成绩/排行榜/作品架刷新来自后端投影。
  • 拒绝麦克风权限时不会创建非法 finished result。

5. 文件清单总览

Phase 1 likely files

  • src/routing/appRoutes.tsx
  • src/BarkBattlePlaygroundApp.tsx
  • src/games/bark-battle/domain/BarkBattleTypes.ts
  • src/games/bark-battle/domain/BarkDetector.ts
  • src/games/bark-battle/domain/EnergyTugOfWar.ts
  • src/games/bark-battle/domain/BarkBattleSession.ts
  • src/games/bark-battle/domain/BarkBattleScoring.ts
  • src/games/bark-battle/domain/OpponentStrategy.ts
  • src/games/bark-battle/application/BarkBattleConfig.ts
  • src/games/bark-battle/application/BarkBattleController.ts
  • src/games/bark-battle/application/BarkBattleSnapshotStore.ts
  • src/games/bark-battle/infrastructure/BrowserMicrophoneInput.ts
  • src/games/bark-battle/infrastructure/AudioAnalyserSampler.ts
  • src/games/bark-battle/infrastructure/MicrophonePermission.ts
  • src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx
  • src/games/bark-battle/ui/BarkBattleHud.tsx
  • src/games/bark-battle/ui/BarkBattleResultPanel.tsx
  • src/games/bark-battle/ui/BarkBattleHud.css

Phase 2 likely files

  • packages/shared/src/contracts/barkBattle.ts
  • src/components/platform-entry/platformEntryTypes.ts
  • src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
  • src/components/platform-entry/platformEntryCreationTypes.ts
  • src/components/bark-battle-creation/BarkBattleAgentWorkspace.tsx
  • src/components/bark-battle-result/BarkBattleResultView.tsx
  • src/services/bark-battle-creation/*

Phase 3 likely files

  • server-rs/crates/shared-contracts/src/bark_battle.rs
  • server-rs/crates/module-bark-battle/*
  • server-rs/crates/spacetime-module/src/runtime/bark_battle.rs
  • server-rs/crates/spacetime-module/src/migration.rs
  • server-rs/crates/spacetime-client/src/runtime.rs
  • server-rs/crates/spacetime-client/src/mapper.rs
  • server-rs/crates/api-server/src/bark_battle.rs
  • src/services/bark-battle-runtime/*
  • src/services/bark-battle-works/*
  • src/components/custom-world-home/creationWorkShelf.ts
  • src/services/publicWorkCode.ts

6. 风险、取舍与开放问题

风险

  1. 麦克风权限和移动端 AudioContext 差异大。 需要 mock input 保底，否则自动化和本地开发会被真实设备阻塞。
  2. 第一阶段过早引入 Phaser 可能拖慢验证。 当前仓库没有 phaser 依赖；建议先用 DOM/Canvas 跑通玩法，再决定是否引入 Phaser。
  3. AI 草稿和正式发布配置容易漂移。 Phase 2 临时 TS 类型必须在 Phase 3 与 Rust shared-contracts 对齐。
  4. 不能保存原始音频。 后端阶段只能保存派生指标，任何音频片段、波形、频谱明细都不应落库。
  5. 入口配置事实源在后端/SpacetimeDB。 Phase 2 接入口时不要恢复旧前端静态入口配置。

取舍

  • Phase 1 先把“游戏是否好玩、功能是否跑通”作为第一目标，不追求正式作品闭环。
  • Phase 2 让 AI 生成内容配置，而不是让 AI 直接生成任意代码或不受控规则。
  • Phase 3 再把正式业务真相交给后端，避免前端 runtime 先背上发布、成绩、排行榜的复杂度。

开放问题

  1. Phase 1 是否必须使用 Phaser？如果只是验证玩法，可先使用 DOM/CSS/Canvas 原型，后续再替换 renderer。
  2. bark-battle 的正式中文名是否固定为“汪汪声浪大作战”？如果名称要改，需先统一文档、入口配置和分享标题。
  3. AI 创作阶段是否需要生成图片/狗狗视觉资产，还是只生成风格描述和使用占位素材？
  4. 是否需要排行榜作为 Phase 3 必选，还是作为数据库落地后的增强项？
  5. 真实麦克风 smoke 需要哪些目标设备：Chrome 桌面、Android Chrome、iOS Safari 是否都纳入首批验收？

7. 建议执行方式

  1. 先按 Phase 1 执行，且每个 domain/application task 坚持 TDD：先失败测试，再实现。
  2. Phase 1 合并前不要接数据库，不要新增后端表，不要把入口配置切到 open。
  3. Phase 1 验证通过后，让产品/团队试玩 /bark-battle，确认玩法数值和 UI 方向。
  4. 再进入 Phase 2，把 AI 创作工作台接到同一个 runtime draft config。
  5. 最后进入 Phase 3，按后端 DDD 文档做数据库、发布、成绩和追踪闭环。
Reference in New Issue View Git Blame Copy Permalink