feat: wire bark battle platform loop

2026-05-14 18:20:46 +08:00
parent 8c6ec9e6e4
commit 1d7ef7e4b6
73 changed files with 7933 additions and 107 deletions
--- a/.hermes/plans/BARK_BATTLE_PHASE2_PLATFORM_WORK_LOOP_PLAN.md
+++ b/.hermes/plans/BARK_BATTLE_PHASE2_PLATFORM_WORK_LOOP_PLAN.md
@@ -0,0 +1,549 @@
+# Bark Battle Phase 2 Platform Work Loop Implementation Plan
+
+> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
+
+**Goal:** 将 `bark-battle` 从内部试玩 demo 升级为 Genarrative 正式 play type，打通轻创作配置、发布态作品、正式 runtime、run start / finish、后端裁决、个人历史、作品统计和最小排行榜闭环。
+
+**Architecture:** 先冻结 shared contracts 与 `module-bark-battle` 纯领域规则，再落 SpacetimeDB 表/reducer、`spacetime-client` facade 和 `api-server` BFF，随后接前端最小纵切，最后补排行榜/个人历史/作品统计投影体验。前端只承接表现、交互和临时 UI 状态，正式业务真相由后端裁决。
+
+**Tech Stack:** React + TypeScript + Vite, server-rs + Axum, SpacetimeDB Rust module, shared-contracts, Vitest, Cargo tests, npm scripts.
+
+---
+
+## 0. 已确认决策
+
+1. “有效叫声”统一为 **有效声浪触发**：当前采样响度达到有效阈值且满足 `minBarkGapMs` 冷却即触发；不再要求 `minBarkDurationMs` / `maxBarkDurationMs`，也不等待响度回落。
+2. Phase 2 范围是 **Bark Battle 平台作品闭环**，不是单纯玩法表现深化。
+3. 作品形态是 **轻创作配置作品**：标题、描述、主题/背景预设、狗狗皮肤预设、难度预设、排行榜开关。
+4. 难度预设只影响 AI 对手行为；不影响有效阈值、冷却、时长、分数公式或反作弊阈值。
+5. 排行榜按 `workId + difficultyPreset + rulesetVersion` 分榜。
+6. 后端裁决正式单局结果；前端只提交派生指标，`clientResult` 只用于 debug/对账。
+7. 排行榜只收录 `serverResult = player_win` 且未被反作弊拒绝的单局结果，排序以 `finalEnergy` 优先。
+8. 作品统计使用最小后端投影：start、finish、win/draw/loss、flagged、leaderboard、best/avg energy。
+9. 个人历史成绩 = 最近记录列表 + 个人最佳摘要；仅本人可见。
+10. 正式入口闭环覆盖创作入口、作品详情 CTA、广场/作品卡片、我的作品、稳定作品 ID runtime 路由和 `work_play_start`。
+11. 创作编辑形态是单页轻配置表单 + 预览卡片。
+12. 实施顺序固定为：契约与领域规则 → SpacetimeDB 表/reducer 与 api-server BFF → 最小前端纵切 → 投影与列表体验 → 收口验证。
+
+---
+
+## 1. 必读文档与约束
+
+实施前先读：
+
+- `AGENTS.md`
+- `CONTEXT.md`
+- `docs/prd/BARK_BATTLE_BDD_2026-05-11.md`
+- `docs/technical/BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md`
+- `docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md`
+- `docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`
+- `docs/technical/SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md`
+- `.codex/skills/spacetimedb-cli/SKILL.md`
+- `.codex/skills/spacetimedb-rust/SKILL.md`
+- `.codex/skills/spacetimedb-concepts/SKILL.md`
+- `.codex/skills/spacetimedb-typescript/SKILL.md`
+
+关键约束：
+
+- 后端路线固定 `server-rs + Axum + SpacetimeDB`。
+- 领域规则进 `module-bark-battle`，SpacetimeDB 表和事务编排进 `spacetime-module`。
+- HTTP/SSE/BFF 留在 `api-server`。
+- 前后端 DTO 留在 `shared-contracts`。
+- 数据库表结构更改必须同步 `migration.rs` 和生成绑定。
+- 人工命令/文档示例禁止继续使用 `spacetime --root-dir`。
+- 修改中文文件后必须跑 `npm run check:encoding`。
+
+---
+
+## 2. 阶段一：契约与领域规则
+
+### Task 1.1: 新增 Rust shared-contracts 模块
+
+**Objective:** 定义 Bark Battle Phase 2 的 Rust DTO 边界。
+
+**Files:**
+- Create: `server-rs/crates/shared-contracts/src/bark_battle.rs`
+- Modify: `server-rs/crates/shared-contracts/src/lib.rs`
+- Test: `server-rs/crates/shared-contracts/src/bark_battle.rs`
+
+**Steps:**
+1. 新增枚举：`BarkBattleDifficultyPreset { Easy, Normal, Hard }`、`BarkBattleServerResult { PlayerWin, OpponentWin, Draw }`、`BarkBattleFinishStatus { Accepted, AcceptedWithFlags, Rejected }`。
+2. 新增配置 DTO：`BarkBattleDraftConfig`、`BarkBattlePublishedConfig`、`BarkBattleRuntimeConfig`。
+3. 新增 run DTO：`BarkBattleRunStartRequest/Response`、`BarkBattleRunFinishRequest/Response`。
+4. 新增派生指标 DTO：`BarkBattleDerivedMetrics`，字段包含 `trigger_count`、`max_volume`、`average_volume`、`final_energy`、`combo_max`。
+5. 新增排行榜/历史/统计 DTO：`BarkBattleLeaderboardEntry`、`BarkBattlePersonalHistoryItem`、`BarkBattlePersonalBestSummary`、`BarkBattleWorkStats`。
+6. 在 `lib.rs` 导出 `pub mod bark_battle;`。
+
+**Verification:**
+
+```bash
+cargo test -p shared-contracts bark_battle
+```
+
+Expected: contracts tests pass.
+
+### Task 1.2: 新增 TypeScript shared contracts mirror
+
+**Objective:** 让前端获得与 Rust DTO 对齐的类型。
+
+**Files:**
+- Create: `packages/shared/src/contracts/barkBattle.ts`
+- Modify: `packages/shared/src/contracts/index.ts`
+- Test: `packages/shared/src/contracts/barkBattle.test.ts`
+
+**Steps:**
+1. 定义 `BarkBattleDifficultyPreset = 'easy' | 'normal' | 'hard'`。
+2. 定义 `BarkBattleServerResult = 'player_win' | 'opponent_win' | 'draw'`。
+3. 定义 draft / published / runtime config 类型。
+4. 定义 start / finish request response 类型。
+5. 定义 leaderboard / personal history / work stats 类型。
+6. 写最小序列化/fixture 测试，确保字段命名采用前端约定 camelCase，并在 API client 层做必要映射。
+
+**Verification:**
+
+```bash
+npm test -- --run packages/shared/src/contracts/barkBattle.test.ts
+npx tsc -p tsconfig.typecheck-guardrails.json --noEmit --pretty false
+```
+
+### Task 1.3: 新建 module-bark-battle crate
+
+**Objective:** 将正式裁决规则放入纯领域 crate。
+
+**Files:**
+- Create: `server-rs/crates/module-bark-battle/Cargo.toml`
+- Create: `server-rs/crates/module-bark-battle/src/lib.rs`
+- Create: `server-rs/crates/module-bark-battle/src/domain.rs`
+- Create: `server-rs/crates/module-bark-battle/src/scoring.rs`
+- Modify: `server-rs/Cargo.toml`
+
+**Steps:**
+1. 在 workspace 中注册 `module-bark-battle`。
+2. 定义 `RulesetVersion`，首版固定如 `bark-battle-ruleset-v1`。
+3. 定义 `BarkBattleRuleset`，包含标准局时长 30s、`min_bark_gap_ms`、合法音量/能量/连击范围、duration tolerance。
+4. 实现 `validate_finish_metrics()`。
+5. 实现 `adjudicate_result()`：以后端 `final_energy` 和 draw threshold 生成 `serverResult`。
+6. 实现 `compute_leaderboard_score()`：只允许胜利局入榜，排序因子为 `finalEnergy`、`triggerCount`、`maxVolume`、duration 接近度、`finishedAt`。
+
+**Verification:**
+
+```bash
+cargo test -p module-bark-battle
+```
+
+### Task 1.4: 领域规则单测覆盖作弊边界
+
+**Objective:** 防止前端伪造 finish 直接刷榜。
+
+**Files:**
+- Modify: `server-rs/crates/module-bark-battle/src/scoring.rs`
+
+**Test cases:**
+- 28s-35s 合法窗口内可接受。
+- 1s / 300s 应 rejected 或 flagged。
+- `triggerCount > durationMs / minBarkGapMs + tolerance` 应 flagged。
+- `finalEnergy` 越界应 rejected。
+- 平/负不生成 leaderboard entry。
+- easy/normal/hard 不改变阈值、冷却、分数公式，只改变 AI preset key。
+
+**Verification:**
+
+```bash
+cargo test -p module-bark-battle -- --nocapture
+```
+
+---
+
+## 3. 阶段二：SpacetimeDB 表/reducer 与 api-server BFF
+
+### Task 2.1: 设计 SpacetimeDB 表目录
+
+**Objective:** 新增 Bark Battle 表并与 migration 对齐。
+
+**Files:**
+- Create: `server-rs/crates/spacetime-module/src/bark_battle/mod.rs`
+- Create: `server-rs/crates/spacetime-module/src/bark_battle/types.rs`
+- Create: `server-rs/crates/spacetime-module/src/bark_battle/tables.rs`
+- Modify: `server-rs/crates/spacetime-module/src/lib.rs`
+- Modify: `server-rs/crates/spacetime-module/src/migration.rs`
+
+**Tables:**
+- `bark_battle_draft_config`
+- `bark_battle_published_config`
+- `bark_battle_runtime_run`
+- `bark_battle_score_record`
+- `bark_battle_leaderboard_entry`
+- `bark_battle_work_stats_projection`
+- `bark_battle_personal_best_projection`
+
+**Pitfalls:**
+- 表结构不要 derive `SpacetimeType`。
+- reducer 使用 `&ReducerContext`。
+- 授权身份来自 `ctx.sender()`。
+- 需要公开订阅的表才加 `public`。
+
+**Verification:**
+
+```bash
+cargo test -p spacetime-module
+```
+
+### Task 2.2: 实现草稿/发布 reducer
+
+**Objective:** 支持轻配置草稿保存和发布态 config 固化。
+
+**Reducers:**
+- `create_bark_battle_draft`
+- `update_bark_battle_draft_config`
+- `publish_bark_battle_work`
+- `get_bark_battle_runtime_config` 如仓库约定使用 reducer/procedure 查询则按现有 pattern 实现。
+
+**Rules:**
+- 草稿配置只允许标题、描述、主题/背景预设、狗狗皮肤预设、难度预设、排行榜开关。
+- 发布生成稳定作品 ID / config version。
+- 发布态 config 包含 `rulesetVersion`。
+
+**Verification:**
+
+```bash
+cargo test -p spacetime-module bark_battle
+```
+
+### Task 2.3: 实现 run start / finish reducer
+
+**Objective:** 打通正式运行态后端事务。
+
+**Reducers:**
+- `start_bark_battle_run`
+- `finish_bark_battle_run`
+- `get_bark_battle_run`
+
+**Rules:**
+- start 创建 `run_id` 和一次性 `run_token`。
+- start 记录 work/config/ruleset/difficulty 快照。
+- finish 必须校验 run token、未 finish、work/config/ruleset/difficulty 一致。
+- finish 调用 `module-bark-battle` 裁决结果。
+- accepted 写 score record。
+- `serverResult = player_win` 且排行榜开启且未 rejected 时写 leaderboard entry。
+- accepted / accepted_with_flags 更新 work stats 和 personal best projection。
+
+**Verification:**
+
+```bash
+cargo test -p spacetime-module bark_battle_run
+```
+
+### Task 2.4: 更新 migration 与生成绑定
+
+**Objective:** 让 SpacetimeDB 表结构变更可发布。
+
+**Files:**
+- Modify: `server-rs/crates/spacetime-module/src/migration.rs`
+- Generated: `server-rs/crates/spacetime-client/src/module_bindings/*bark*`
+
+**Commands:**
+按仓库现有脚本优先；不要手改 generated bindings。
+
+```bash
+npm run spacetime:build
+npm run spacetime:generate
+```
+
+若脚本名不同，先查 `package.json` 和 `server-rs` README。
+
+### Task 2.5: 实现 spacetime-client facade
+
+**Objective:** api-server 不直接操作 generated bindings。
+
+**Files:**
+- Create: `server-rs/crates/spacetime-client/src/bark_battle.rs`
+- Modify: `server-rs/crates/spacetime-client/src/lib.rs`
+
+**Methods:**
+- `create_bark_battle_draft`
+- `save_bark_battle_draft_config`
+- `publish_bark_battle_work`
+- `get_bark_battle_runtime_config`
+- `start_bark_battle_run`
+- `finish_bark_battle_run`
+- `list_bark_battle_leaderboard`
+- `list_my_bark_battle_history`
+- `get_my_bark_battle_best_summary`
+- `get_bark_battle_work_stats`
+
+**Verification:**
+
+```bash
+cargo test -p spacetime-client bark_battle
+```
+
+### Task 2.6: 实现 api-server BFF 路由
+
+**Objective:** 暴露前端需要的 HTTP API。
+
+**Files:**
+- Create: `server-rs/crates/api-server/src/bark_battle.rs`
+- Modify: `server-rs/crates/api-server/src/app.rs`
+
+**Routes:**
+- `POST /api/bark-battle/drafts`
+- `PATCH /api/bark-battle/drafts/:draftId`
+- `POST /api/bark-battle/drafts/:draftId/publish`
+- `GET /api/bark-battle/works/:workId/runtime-config`
+- `POST /api/bark-battle/runs/start`
+- `POST /api/bark-battle/runs/:runId/finish`
+- `GET /api/bark-battle/works/:workId/leaderboard`
+- `GET /api/bark-battle/me/history`
+- `GET /api/bark-battle/me/best-summary`
+- `GET /api/bark-battle/works/:workId/stats`
+
+**Verification:**
+
+```bash
+cargo test -p api-server bark_battle
+npm run api-server
+curl -f http://127.0.0.1:<api-port>/healthz
+```
+
+---
+
+## 4. 阶段三：最小前端纵切
+
+### Task 3.1: 新增前端 service client
+
+**Files:**
+- Create: `src/services/bark-battle/barkBattleClient.ts`
+- Test: `src/services/bark-battle/barkBattleClient.test.ts`
+
+**Methods:** 与 BFF routes 一一对应。
+
+**Verification:**
+
+```bash
+npm test -- --run src/services/bark-battle/barkBattleClient.test.ts
+```
+
+### Task 3.2: 接入创作入口与 SelectionStage
+
+**Files:**
+- Modify: `src/config/newWorkEntryConfig.ts`
+- Modify: `src/components/platform-entry/platformEntryCreationTypes.ts`
+- Modify: `src/components/platform-entry/platformEntryTypes.ts`
+- Modify: `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+
+**Rules:**
+- 新增 `bark-battle` play type。
+- 入口打开单页轻配置表单，不走复杂 agent workspace。
+- 移动端入口布局不能溢出。
+
+### Task 3.3: 实现单页轻配置表单 + 预览卡片
+
+**Files:**
+- Create: `src/components/bark-battle-creation/BarkBattleConfigEditor.tsx`
+- Create: `src/components/bark-battle-creation/BarkBattlePreviewCard.tsx`
+- Test: `src/components/bark-battle-creation/BarkBattleConfigEditor.test.tsx`
+
+**UI fields:**
+- 标题必填
+- 简介选填
+- 主题/背景预设
+- 狗狗皮肤预设
+- 难度预设，默认 `normal`
+- 排行榜开关，默认开启
+
+**UI constraints:**
+- 不堆大段玩法说明。
+- 按现有游戏 UI 风格设计。
+- 移动端优先。
+
+### Task 3.4: 发布后进入作品详情
+
+**Files:**
+- Modify: `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+- Modify: `src/components/platform-entry/PlatformWorkDetailView.tsx`
+- Modify: `src/components/custom-world-home/CustomWorldCreationHub.tsx`
+- Modify: `src/components/custom-world-home/creationWorkShelf.ts`
+
+**Rules:**
+- 发布成功刷新 works/gallery/shelf。
+- 跳作品详情。
+- 详情 CTA 可以进入正式 runtime。
+
+### Task 3.5: runtime 拉发布态 config 并 start / finish
+
+**Files:**
+- Modify: `src/games/bark-battle/*`
+- Modify: `src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx`
+- Create/Modify: `src/components/bark-battle-runtime/BarkBattleRuntimeRoute.tsx` 如需要
+
+**Rules:**
+- runtime 通过稳定 `workId` 拉 `BarkBattleRuntimeConfig`。
+- 开始正式局时调用 start run。
+- 结束时提交 finish 派生指标。
+- 结算展示 `serverResult`、`scoreSummary`、`antiCheatFlags`、leaderboard entry。
+- 麦克风原始音频不上传。
+
+**Verification:**
+
+```bash
+npm test -- --run src/games/bark-battle/domain/__tests__/BarkDetector.test.ts src/games/bark-battle/application/__tests__/BarkBattleController.test.ts src/games/bark-battle/ui/__tests__/BarkBattleRuntimeShell.test.tsx
+```
+
+---
+
+## 5. 阶段四：投影与列表体验
+
+### Task 4.1: 排行榜 UI
+
+**Files:**
+- Create: `src/components/bark-battle-leaderboard/BarkBattleLeaderboardPanel.tsx`
+- Test: `src/components/bark-battle-leaderboard/BarkBattleLeaderboardPanel.test.tsx`
+- Modify: `src/components/platform-entry/PlatformWorkDetailView.tsx`
+
+**Rules:**
+- 查询维度 `workId + difficultyPreset + rulesetVersion`。
+- 只展示胜利入榜成绩。
+- 不展示平/负/flagged 历史。
+
+### Task 4.2: 个人历史最近记录 + 最佳摘要 UI
+
+**Files:**
+- Create: `src/components/bark-battle-history/BarkBattlePersonalHistoryPanel.tsx`
+- Test: `src/components/bark-battle-history/BarkBattlePersonalHistoryPanel.test.tsx`
+
+**Rules:**
+- 默认最近 20 条。
+- 仅本人可见。
+- 可按 workId / difficultyPreset 过滤。
+- flagged 只做轻提示，不展示详细反作弊原因。
+
+### Task 4.3: 作品统计展示
+
+**Files:**
+- Create: `src/components/bark-battle-stats/BarkBattleWorkStatsPanel.tsx`
+- Test: `src/components/bark-battle-stats/BarkBattleWorkStatsPanel.test.tsx`
+
+**Fields:**
+- `playStartCount`
+- `finishCount`
+- `winCount`
+- `drawCount`
+- `lossCount`
+- `flaggedCount`
+- `leaderboardEntryCount`
+- `bestLeaderboardScore`
+- `bestFinalEnergy`
+- `averageFinalEnergy`
+- `updatedAt`
+
+### Task 4.4: 广场卡片/我的作品适配
+
+**Files:**
+- Modify: `src/components/custom-world-home/creationWorkShelf.ts`
+- Modify: `src/components/custom-world-home/CustomWorldCreationHub.tsx`
+- Modify: `src/components/rpg-entry/rpgEntryWorldPresentation.ts`
+- Modify: `src/services/publicWorkCode.ts` 如分享码需要支持
+
+**Rules:**
+- Bark Battle 作品能展示、打开详情、开始游玩。
+- 不新增独立 Bark Battle 专区。
+
+---
+
+## 6. 阶段五：收口验证
+
+### Task 5.1: 自动测试清单
+
+```bash
+cargo test -p shared-contracts bark_battle
+cargo test -p module-bark-battle
+cargo test -p spacetime-module bark_battle
+cargo test -p spacetime-client bark_battle
+cargo test -p api-server bark_battle
+npm test -- --run packages/shared/src/contracts/barkBattle.test.ts
+npm test -- --run src/services/bark-battle/barkBattleClient.test.ts
+npm test -- --run src/components/bark-battle-creation/BarkBattleConfigEditor.test.tsx
+npm test -- --run src/games/bark-battle/domain/__tests__/BarkDetector.test.ts src/games/bark-battle/application/__tests__/BarkBattleController.test.ts src/games/bark-battle/ui/__tests__/BarkBattleRuntimeShell.test.tsx
+npx tsc -p tsconfig.typecheck-guardrails.json --noEmit --pretty false
+npm run check:encoding
+git diff --check
+```
+
+### Task 5.2: 后端 smoke
+
+1. 按项目脚本启动 SpacetimeDB + api-server，优先使用 `npm run api-server`，不要使用旧命令。
+2. 确认 `/healthz`。
+3. smoke 流程：创建草稿 → 保存配置 → 发布 → 拉 runtime config → start run → finish run → 查询 leaderboard/history/stats。
+
+### Task 5.3: 人工验收路径
+
+1. 进入创作入口/玩法选择，选择 Bark Battle。
+2. 在单页轻配置表单中填写标题，选择主题、狗狗皮肤、难度，保持排行榜开启。
+3. 保存草稿。
+4. 发布作品。
+5. 发布后自动进入作品详情。
+6. 点击开始游玩进入正式 runtime。
+7. 授权麦克风，完成 30 秒单局。
+8. 结算页显示后端 `serverResult` 和 score summary。
+9. 若胜利，排行榜出现本局成绩。
+10. 我的记录显示最近记录和个人最佳摘要。
+11. 作品详情/作者视角能看到作品统计。
+12. 广场/作品卡片和我的作品入口都能再次进入详情和 runtime。
+
+---
+
+## 7. 不做范围
+
+- 不做实时多人。
+- 不做 ghost replay。
+- 不做 AI 狗叫识别。
+- 不保存原始音频、PCM、waveform 或可还原语音内容。
+- 不做独立 Bark Battle 专区/活动页。
+- 不做挑战分享、好友邀请、多人数房间。
+- 不做复杂编辑器、多步骤向导、规则参数编辑、AI 生成配置。
+- 不做 DAU/留存、按小时统计曲线、好友对比。
+
+---
+
+## 8. 三人并行建议
+
+### 开发者 A：后端契约与领域规则
+
+负责 Task 1.1、1.3、1.4。先提交 contracts 与 `module-bark-battle`，为后续后端/前端提供稳定类型和裁决规则。
+
+### 开发者 B：SpacetimeDB + api-server
+
+负责 Task 2.1 到 2.6。必须等开发者 A 的 DTO/领域规则基本稳定后开始，或先基于计划字段开分支实现表结构。
+
+### 开发者 C：前端纵切与 UI
+
+负责 Task 3.x 与 4.x。开始时可先做组件空态和 service client 类型，真正联调等 B 的 BFF ready。
+
+---
+
+## 9. 推荐提交节奏
+
+1. `feat: add bark battle contracts and domain rules`
+2. `feat: add bark battle spacetime tables and reducers`
+3. `feat: add bark battle api server routes`
+4. `feat: add bark battle creation editor`
+5. `feat: connect bark battle runtime to server results`
+6. `feat: add bark battle leaderboard history stats`
+7. `docs: finalize bark battle phase2 verification guide`
+
+---
+
+## 10. 完成定义
+
+Phase 2 完成必须同时满足：
+
+- Bark Battle 可以从正式创作入口创建轻配置作品。
+- 作品可以发布为稳定 workId。
+- 作品详情/广场/我的作品可以发现并进入正式 runtime。
+- runtime 从后端发布态 config 拉配置。
+- start run 写 `work_play_start`。
+- finish 只上传派生指标。
+- 后端裁决 `serverResult` / `scoreSummary` / `leaderboardScore` / `antiCheatFlags`。
+- 胜利局进入按 `workId + difficultyPreset + rulesetVersion` 分榜的排行榜。
+- 个人历史和作品统计可查询。
+- 自动测试、encoding、typecheck、diff check 和人工验收路径通过。