Genarrative/docs/technical/BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md

bark-battle 后端 DDD 技术方案（2026-05-11）

1. 背景、范围与非目标

1.1 背景

bark-battle / “汪汪声浪大作战”是一个浏览器 2D 声控狗叫对战玩法。玩家通过麦克风发出狗叫声，浏览器 runtime 根据音量峰值、有效叫声次数与节奏推动顶部红蓝能量条；每局默认 30 秒；结束后按能量条偏向判定胜负或平局。

现有前端方案 docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md 已覆盖 Phaser / TypeScript / Vite / Web Audio / DOM HUD 的 runtime 落地方式，并明确不覆盖后端表结构、成绩持久化、作品发布、广场接入与实时多人协议。因此需要单独补充后端 DDD 技术方案，避免前端 runtime 在接入平台作品、正式游玩埋点、成绩、排行榜和发布闭环时承接不属于表现层的业务真相。

本方案遵循当前 Genarrative 后端路线：server-rs + Axum + SpacetimeDB。DDD 边界保持为：

• module-*：纯领域规则与 use case 约束。
• spacetime-module：SpacetimeDB 表、reducer、migration。
• spacetime-client：SpacetimeDB 绑定调用 facade。
• api-server：HTTP / SSE / BFF 门面与权限校验入口。
• shared-contracts：前后端共享 DTO、请求、响应、错误码与 schema 约束。
• platform-*：作品、发布、广场、埋点等平台能力的领域边界。

1.2 本文范围

本文覆盖后端方案，不实现代码：

1. bark-battle 玩法接入级别建议。
2. 后端 DDD 分层与职责边界。
3. shared contracts 草案。
4. SpacetimeDB 数据模型草案。
5. HTTP API / facade 草案。
6. SpacetimeDB migration 与绑定生成策略。
7. 安全、隐私与反作弊约束。
8. TDD / 验收顺序与可执行命令。
9. 与现有前端方案和 BDD 文档的关系。

1.3 非目标

MVP 明确不做：

• 不保存原始麦克风音频、音频片段、可还原语音内容的 waveform 或频谱明细。
• 不做实时多人在线对战；首版只支持本地 runtime + 后端记录派生结果。
• 不做复杂 AI 声纹识别、狗叫语义识别、身份声纹比对或真人/动物声纹分类。
• 不由前端直接写正式成绩、排行榜或作品发布状态。
• 不把 Phaser / Web Audio / DOM HUD 逻辑迁入后端。
• 不在本方案中实现代码、建表或生成绑定。

2. 玩法接入级别建议

2.1 推荐首版闭环

建议先支持“本地 runtime + 可发布配置化作品 + 单局结果记录 / 可选排行榜”的闭环：

1. 创作者创建 bark-battle 草稿，配置标题、描述、狗狗主题、背景、难度、单局时长、音量阈值、AI 对手参数和排行榜开关。
2. 发布为稳定作品 ID，playTypeId = "bark-battle"。
3. 玩家从作品页或广场进入 runtime，前端获取发布态 runtime config。
4. 玩家授权麦克风后在本地完成 30 秒声控对战。
5. 前端提交单局 finish 请求，只上传派生指标，例如峰值、有效叫声次数、节奏命中、最终能量、客户端结果摘要等。
6. 后端校验 work、config version、run token、时长、分数范围和权限后，生成服务端认可的 run result / score summary。
7. 若作品开启排行榜，则写入可投影的 leaderboard 记录。
8. 正式作品级游玩埋点统一写 work_play_start，其中 scope_kind=work，scope_id=稳定作品 ID，metadata 包含 playType、workId、sourceRoute、userId。

2.2 后续增强路径

后续再考虑多人实时：

• Phase 2：排行榜、挑战分享、个人历史成绩、作品统计面板。
• Phase 3：异步影子对手 / ghost replay，但仍不保存原始音频，只保存低维派生曲线或聚合指标。
• Phase 4：实时多人对战协议，需要独立同步模型、房间服务、延迟补偿、断线恢复与更严格反作弊；不应混入 MVP。

3. DDD 分层设计

3.1 总体分层

frontend/runtime
  -> api-server HTTP BFF
    -> shared-contracts DTO
    -> spacetime-client facade
      -> generated SpacetimeDB bindings
        -> spacetime-module reducers / tables / migration.rs
    -> module-bark-battle pure domain
    -> platform-work / platform-publish / platform-tracking / platform-leaderboard

3.2 module-bark-battle 职责

建议新增 server-rs/crates/module-bark-battle/，只放纯领域规则，不依赖 Axum、SpacetimeDB SDK、HTTP、数据库绑定或前端类型。

职责：

• 校验 bark-battle 配置合法性。
• 定义配置版本兼容规则。
• 计算提交结果的派生分数区间与胜负判定是否自洽。
• 计算 ScoreSummary、排行榜排序分数、统计指标。
• 定义反作弊基础规则：时长范围、有效叫声次数上限、峰值范围、能量范围、提交窗口、run 状态机。

不职责：

• 不访问数据库。
• 不处理 HTTP 请求。
• 不生成 SpacetimeDB 表。
• 不处理麦克风音频采样。

3.3 shared-contracts 职责

建议新增 server-rs/crates/shared-contracts/src/bark_battle.rs，并在前端共享契约生成流程中对齐同名 DTO。

职责：

• 定义草稿、发布态 runtime config、work summary、run start、run finish、run result、score summary、leaderboard DTO。
• 定义 request / response / error code。
• 保持字段命名、枚举值、时间单位和数值范围稳定。

约束：

• DTO 可以表达业务数据，但不承载领域算法。
• 前端不得手写与后端不一致的正式契约；如果存在 TypeScript mirror，需要由契约生成或测试保证一致。

3.4 spacetime-module 职责

建议在现有 SpacetimeDB 模块边界内新增 bark-battle 表与 reducer，或按当前仓库约定新增独立模块文件。职责：

• 定义表：作品配置、发布版本、runtime run、score/stat、leaderboard entry。
• 定义 reducer / procedure：保存草稿、发布版本、开始 run、结束 run、写排行榜、查询投影所需索引。
• 维护 migration。

必须明确：

• 所有表结构变更进入 migration.rs。
• SpacetimeDB 绑定通过既有生成命令生成。
• 不手改生成物，不手改 generated bindings。

3.5 spacetime-client 职责

职责：

• 封装 generated bindings，向 api-server 提供稳定 facade。
• 隐藏 reducer 名称、表订阅细节和绑定类型差异。
• 将 SpacetimeDB 错误转换为后端内部错误模型。

不职责：

• 不放业务规则主逻辑。
• 不绕过 module-bark-battle 做胜负和分数裁决。

3.6 api-server 职责

Axum HTTP / BFF 门面职责：

• 鉴权、用户上下文、work 权限、发布态读取权限。
• 解析请求、调用 domain 校验、调用 spacetime-client facade。
• 将内部错误映射成 HTTP status + shared error code。
• 负责正式作品级游玩埋点入口，统一写 work_play_start。
• 为前端 runtime 提供一次性 start token / run id，避免匿名 finish 直接刷榜。

3.7 platform-* 职责

• platform-work：稳定作品 ID、作品所有权、作品摘要、作品状态。
• platform-publish：草稿到发布态版本、config version、发布可见性。
• platform-tracking：统一埋点，尤其 work_play_start。
• platform-leaderboard：若已有通用排行榜能力，bark-battle 只提供 score projection，不重复建设平台级排名系统。

3.8 frontend/runtime 职责边界

前端只做：

• Phaser / DOM HUD 表现。
• Web Audio 采样、环境噪声校准和本地即时反馈。
• 本地临时 UI 状态：权限、倒计时、动画、结算展示。
• 调用 start / finish / leaderboard API。

前端不得承接正式业务真相：

• 不直接决定正式排行榜结果。
• 不直接写作品发布状态。
• 不绕过后端写成绩。
• 不上传原始麦克风音频。

4. shared contracts 设计草案

以下为字段草案，具体 Rust / TypeScript 命名按仓库契约规范落地。

4.1 BarkBattleDraft

BarkBattleDraft {
  draftId: string
  ownerUserId: string
  playTypeId: "bark-battle"
  title: string
  description?: string
  theme: BarkBattleTheme
  runtimeConfig: BarkBattleRuntimeConfigDraft
  leaderboardEnabled: boolean
  visibility: "private" | "unlisted" | "public"
  createdAt: string
  updatedAt: string
}

4.2 BarkBattleRuntimeConfig

BarkBattleRuntimeConfig {
  workId: string
  configVersion: number
  playTypeId: "bark-battle"
  durationMs: number               // MVP 默认 30000
  energyMin: number                // 默认 -100
  energyMax: number                // 默认 100
  winEnergyThreshold: number        // 可选：低于阈值可平局
  barkThreshold: number             // 归一化 0..1
  peakWeight: number
  barkCountWeight: number
  rhythmWeight: number
  opponent: {
    difficulty: "easy" | "normal" | "hard"
    basePower: number
    variance: number
  }
  theme: {
    playerDogSkin: string
    opponentDogSkin: string
    stageId: string
    soundPackId?: string
  }
  leaderboardEnabled: boolean
  publishedAt: string
}

4.3 WorkSummary

BarkBattleWorkSummary {
  workId: string
  playTypeId: "bark-battle"
  title: string
  description?: string
  coverAssetId?: string
  authorUserId: string
  authorDisplayName?: string
  configVersion: number
  leaderboardEnabled: boolean
  totalPlayCount: number
  publishedAt: string
  updatedAt: string
}

4.4 RunStart

BarkBattleRunStartRequest {
  workId: string
  configVersion: number
  sourceRoute?: string
  clientRuntimeVersion?: string
}

BarkBattleRunStartResponse {
  runId: string
  runToken: string
  workId: string
  configVersion: number
  serverStartedAt: string
  expiresAt: string
  runtimeConfig: BarkBattleRuntimeConfig
}

4.5 RunFinish

BarkBattleRunFinishRequest {
  runId: string
  runToken: string
  workId: string
  configVersion: number
  clientStartedAt?: string
  clientFinishedAt?: string
  elapsedMs: number
  finalEnergy: number
  clientWinner: "player" | "opponent" | "draw"
  metrics: BarkBattleDerivedMetrics
  clientRuntimeVersion?: string
}

BarkBattleDerivedMetrics {
  peakVolumeMax: number             // 0..1
  peakVolumeAvg: number             // 0..1
  validBarkCount: number
  rhythmHitCount: number
  longestCombo: number
  sampleWindowCount?: number
  calibrationNoiseFloor?: number    // 0..1
}

4.6 RunResult

BarkBattleRunResult {
  runId: string
  workId: string
  userId?: string
  configVersion: number
  accepted: boolean
  serverWinner: "player" | "opponent" | "draw"
  finalEnergy: number
  score: number
  scoreSummary: BarkBattleScoreSummary
  leaderboardEntry?: BarkBattleLeaderboardEntry
  antiCheatFlags: string[]
  finishedAt: string
}

4.7 ScoreSummary

BarkBattleScoreSummary {
  score: number
  grade: "S" | "A" | "B" | "C" | "D"
  finalEnergy: number
  winMargin: number
  validBarkCount: number
  peakVolumeMax: number
  rhythmHitCount: number
  longestCombo: number
  elapsedMs: number
}

4.8 Leaderboard 可选类型

BarkBattleLeaderboardQuery {
  workId: string
  configVersion?: number
  period: "all" | "daily" | "weekly"
  limit: number
  cursor?: string
}

BarkBattleLeaderboardEntry {
  rank?: number
  runId: string
  workId: string
  userId?: string
  displayName?: string
  score: number
  scoreSummary: BarkBattleScoreSummary
  createdAt: string
}

BarkBattleLeaderboardResponse {
  workId: string
  entries: BarkBattleLeaderboardEntry[]
  viewerBest?: BarkBattleLeaderboardEntry
  nextCursor?: string
}

5. 数据模型草案

5.1 作品配置表

建议表：bark_battle_work_config。

字段草案：

• work_id：稳定作品 ID，关联平台作品。
• draft_id：草稿 ID，可选。
• owner_user_id：创作者。
• play_type_id：固定 bark-battle。
• config_version：发布配置版本。
• title、description、cover_asset_id。
• runtime_config_json：发布态 runtime 配置 JSON；字段需由 shared contracts 校验。
• leaderboard_enabled。
• status：draft / published / archived。
• created_at、updated_at、published_at。

约束：

• 同一 work_id + config_version 不可变；新发布生成新版本。
• runtime 请求只读发布态配置。

5.2 runtime run 表

建议表：bark_battle_runtime_run。

字段草案：

• run_id。
• run_token_hash：保存 token hash，不保存明文 token。
• work_id。
• config_version。
• user_id：匿名时可空或使用匿名会话 ID。
• source_route。
• status：started / finished / rejected / expired。
• server_started_at、server_finished_at、expires_at。
• client_elapsed_ms。
• final_energy。
• client_winner、server_winner。
• anti_cheat_flags_json。
• client_runtime_version。

5.3 score / stat 表

建议表：bark_battle_score_record。

字段草案：

• score_id。
• run_id。
• work_id。
• config_version。
• user_id。
• score。
• grade。
• final_energy。
• valid_bark_count。
• peak_volume_max。
• peak_volume_avg。
• rhythm_hit_count。
• longest_combo。
• elapsed_ms。
• metrics_json：只保存派生聚合指标。
• created_at。

明确禁止：

• 不保存原始麦克风音频。
• 不保存可还原语音的 PCM、Opus、MP3、WAV、base64 音频、逐帧 waveform。
• 不保存高精度声纹向量。

5.4 leaderboard 表

若平台已有通用排行榜，优先复用平台 leaderboard 投影；否则可新增 bark_battle_leaderboard_entry：

• entry_id。
• work_id。
• config_version。
• run_id。
• user_id。
• score。
• tie_breaker_energy。
• tie_breaker_elapsed_ms。
• created_at。

排序建议：

1. score 降序。
2. final_energy / winMargin 降序。
3. elapsed_ms 更接近配置时长者优先，避免异常短局刷分。
4. created_at 升序或按平台既有规则。

6. API 草案

路径仅为草案，落地时按 api-server 当前路由命名规范调整。

6.1 创建 / 保存草稿

POST /api/bark-battle/drafts
PUT  /api/bark-battle/drafts/{draftId}
GET  /api/bark-battle/drafts/{draftId}

职责：

• 仅创作者可创建和保存。
• 校验 playTypeId = bark-battle。
• 调用 module-bark-battle 校验 runtime config 范围。

6.2 发布 / 获取作品

POST /api/bark-battle/drafts/{draftId}/publish
GET  /api/works/{workId}/bark-battle
GET  /api/bark-battle/works/{workId}/runtime-config

职责：

• 发布生成稳定 workId 和递增 configVersion。
• 获取作品只返回发布态配置与展示摘要。
• 未发布或无权限作品返回明确错误。

6.3 start runtime

POST /api/bark-battle/runs/start

请求：BarkBattleRunStartRequest。响应：BarkBattleRunStartResponse。

职责：

• 校验作品存在、发布态、可游玩。
• 校验 config version，必要时返回最新版本。
• 创建 run_id 与一次性 run_token。
• 写正式作品级游玩埋点：work_play_start。

埋点要求：

event_key: work_play_start
scope_kind: work
scope_id: <稳定作品 ID>
metadata: {
  playType: "bark-battle",
  workId: "<workId>",
  sourceRoute: "<sourceRoute>",
  userId: "<userId or anonymous>"
}

6.4 finish runtime

POST /api/bark-battle/runs/{runId}/finish

请求：BarkBattleRunFinishRequest。响应：BarkBattleRunResult。

职责：

• 校验 run token。
• 校验 run 仍处于 started 且未过期。
• 校验 work_id + config_version 与 start 时一致。
• 校验时长、finalEnergy、metrics 范围。
• 使用 module-bark-battle 生成服务端认可的 serverWinner、score、ScoreSummary、antiCheatFlags。
• 写 bark_battle_runtime_run finish 状态与 bark_battle_score_record。
• 如开启 leaderboard 且结果 accepted，写排行榜。

6.5 作品级游玩埋点

start runtime 内部必须触发统一埋点；不建议前端单独调用一个 bark-battle 专用埋点 API。若平台已有通用 tracking API，则 api-server 内部调用 platform tracking facade：

track_event(
  event_key = "work_play_start",
  scope_kind = "work",
  scope_id = workId,
  metadata = { playType, workId, sourceRoute, userId }
)

6.6 可选排行榜

GET /api/bark-battle/works/{workId}/leaderboard?period=all&limit=50&cursor=...
GET /api/bark-battle/works/{workId}/leaderboard/me

职责：

• 只读已接受成绩。
• 支持分页。
• 支持匿名用户时隐藏或弱化身份展示。
• 若作品关闭排行榜，返回空投影或明确 disabled 状态。

7. SpacetimeDB 与 migration 策略

7.1 表 / reducer / procedure 边界

SpacetimeDB 侧只承载持久化、索引、reducer 原子写入和可查询投影，不承载 HTTP 鉴权或前端表现。

建议 reducer / procedure：

• bark_battle_save_draft_config：保存草稿配置。
• bark_battle_publish_work_config：发布配置版本。
• bark_battle_start_run：创建 runtime run。
• bark_battle_finish_run：结束 run 并写 score。
• bark_battle_upsert_leaderboard_entry：写排行榜投影。
• bark_battle_get_work_runtime_config：读取发布态配置。
• bark_battle_get_leaderboard：读取排行榜投影。

如当前架构要求 reducer 仅由 spacetime-client 调用，则 api-server 不直接操作 SpacetimeDB SDK。

7.2 migration.rs

所有表结构变更必须进入 migration.rs：

• 新增 bark-battle 表时写显式 migration。
• 新增索引、唯一约束或版本字段时写 migration。
• 从草稿 JSON 拆字段时写数据迁移说明。
• 不允许只改 Rust struct 而不补 migration。

7.3 绑定生成

涉及 SpacetimeDB schema / reducer 变更后：

1. 运行仓库既有 SpacetimeDB 绑定生成命令。
2. 检查 generated bindings 变化。
3. spacetime-client 只引用生成物，不手改生成物。
4. shared contracts 与 generated bindings 的差异通过 facade 消化，不让前端直接依赖数据库绑定。

明确要求：不手改生成物，不手改 generated bindings，不用临时复制粘贴类型绕过生成流程。

7.4 api-server facade

api-server 通过 spacetime-client facade 调用 SpacetimeDB：

BarkBattleService
  -> BarkBattleDomainPolicy
  -> BarkBattleSpacetimeClient
  -> generated bindings

这样可以保证：

• HTTP 层易测试。
• domain 纯函数可独立测试。
• SpacetimeDB 绑定变更不会扩散到 route handler。

8. 安全、隐私与反作弊

8.1 隐私

• 不上传原始音频。
• 不保存原始音频。
• 不保存可还原用户声音的高精度采样曲线。
• 只保存派生指标：峰值、均值、有效叫声次数、节奏命中、最终能量、分数、耗时。
• 前端权限文案必须说明麦克风只用于本地玩法输入，MVP 不上传原始声音。

8.2 不信任前端胜负

后端不能直接信任：

• clientWinner。
• score。
• finalEnergy。
• elapsedMs。
• validBarkCount。

后端必须校验并重算服务端认可结果。MVP 因不上传音频，无法完全证明声音真实性，但仍需做边界反作弊。

8.3 校验规则

必须校验：

• run token 是否匹配且未使用。
• run 是否未过期。
• work_id + config_version 是否与 start 时一致。
• 用户是否有权限游玩该 work。
• 提交时长是否接近配置时长，例如 30 秒局允许少量网络 / 页面调度误差。
• finalEnergy 是否在配置范围。
• peakVolumeMax、peakVolumeAvg 是否在 0..1。
• validBarkCount、rhythmHitCount、longestCombo 是否在物理合理上限。
• clientStartedAt / clientFinishedAt 与服务端时间窗口是否合理。
• 同一用户 / 匿名会话的频率限制。

8.4 反作弊处理

建议结果状态：

• accepted：写 score，可进入排行榜。
• accepted_with_flags：写 score，但标记异常，默认不入榜或降低可信度。
• rejected：不入榜，只记录 run 失败原因。

常见 flags：

• elapsed_too_short
• elapsed_too_long
• metric_out_of_range
• config_version_mismatch
• token_invalid
• duplicate_finish
• rate_limited
• impossible_bark_count

9. BDD 行为场景、TDD 落地顺序与验收命令

本任务只写方案，不执行代码实现。后续落地必须先用 BDD 锁定可观察行为，再按 TDD 做 RED-GREEN-REFACTOR。没有先失败的测试，不进入生产代码实现。

9.1 BDD 场景清单

以下场景用于约束后端行为，场景标题应映射到后续 Rust 测试名、API 测试名或 smoke 用例名。

功能: bark-battle 发布态作品运行配置

功能: bark-battle 发布态作品运行配置
  为了让玩家进入稳定的声控狗叫对战作品
  作为已发布作品的玩家
  我希望后端只返回发布态且版本一致的运行配置

  背景:
    假如平台中存在 playTypeId 为 "bark-battle" 的作品配置

  场景: 玩家请求已发布作品的 runtime config
    假如作品处于 published 状态
    而且请求携带的 configVersion 与当前发布版本一致
    当玩家请求 bark-battle runtime config
    那么后端应返回 BarkBattleRuntimeConfig
    而且响应中的 workId 应为稳定作品 ID
    而且响应中的 playTypeId 应为 "bark-battle"
    而且响应不应包含草稿态配置或创作者私有字段

  场景: 玩家请求未发布作品的 runtime config
    假如作品处于 draft 状态
    当玩家请求 bark-battle runtime config
    那么后端应返回不可游玩的错误
    而且不应创建 runtime run

  场景: 玩家携带过期配置版本进入 runtime
    假如作品已发布 configVersion 为 3 的版本
    当玩家使用 configVersion 为 2 的请求开始 runtime
    那么后端应拒绝开始本局或返回最新版本提示
    而且不应写入正式成绩

功能: bark-battle runtime start 与统一游玩埋点

功能: bark-battle runtime start 与统一游玩埋点
  为了统计正式作品游玩行为
  作为数据分析人员
  我希望玩家开始 bark-battle 正式游玩时写入统一 work_play_start 事件

  场景: 玩家成功开始已发布作品运行态
    假如存在一个已发布的 bark-battle 作品
    而且玩家有权限游玩该作品
    当玩家调用 start runtime
    那么后端应创建状态为 started 的 run
    而且应返回 runId、一次性 runToken 与 runtimeConfig
    而且应写入 work_play_start 事件
    而且事件 scope_kind 应为 work
    而且事件 scope_id 应为稳定作品 ID
    而且 metadata 应包含 playType、workId、sourceRoute 和 userId

  场景: 无权限玩家尝试开始运行态
    假如作品不可被当前玩家访问
    当玩家调用 start runtime
    那么后端应返回权限错误
    而且不应创建 run
    而且不应写入 work_play_start 事件

功能: bark-battle runtime finish 派生成绩提交

功能: bark-battle runtime finish 派生成绩提交
  为了保护用户隐私并保证成绩可信
  作为后端服务
  我只接受派生指标并重新裁决正式结果

  场景: 玩家完成一局并提交合法派生指标
    假如玩家已经成功 start runtime
    而且 run 处于 started 状态
    而且提交的 runToken 与 start 返回一致
    当玩家提交 elapsedMs、finalEnergy 和 BarkBattleDerivedMetrics
    那么后端应校验派生指标范围
    而且应重新计算 serverWinner、score 和 ScoreSummary
    而且应把 run 状态改为 finished
    而且响应中的 accepted 应为 true
    而且请求与持久化记录中不应包含原始麦克风音频

  场景: 玩家重复提交同一个 run 的 finish
    假如某个 run 已经处于 finished 状态
    当玩家再次提交 finish
    那么后端应拒绝重复提交
    而且不应重复写入成绩
    而且不应重复写入排行榜

  场景: 玩家提交不合理的时长
    假如作品配置 durationMs 为 30000
    当玩家提交 elapsedMs 明显短于配置时长
    那么后端应返回 rejected 或 accepted_with_flags
    而且 antiCheatFlags 应包含 elapsed_too_short
    而且该结果默认不应进入排行榜

  场景: 玩家提交超出范围的声音指标
    假如玩家已经成功 start runtime
    当玩家提交 peakVolumeMax 大于 1 或 validBarkCount 超过物理合理上限
    那么后端应拒绝或打 flag
    而且 antiCheatFlags 应包含 metric_out_of_range 或 impossible_bark_count

功能: bark-battle 排行榜投影

功能: bark-battle 排行榜投影
  为了让玩家比较同一作品内的有效成绩
  作为玩家
  我希望排行榜只展示被后端接受的成绩

  场景: 作品开启排行榜且成绩被接受
    假如作品 leaderboardEnabled 为 true
    而且玩家提交的 finish 结果 accepted 为 true
    当后端完成成绩写入
    那么后端应写入或更新该作品的排行榜投影
    而且排行榜排序应优先按 score 降序

  场景: 作品关闭排行榜
    假如作品 leaderboardEnabled 为 false
    当玩家完成一局合法成绩
    那么后端应记录 run 与 score
    而且不应写入排行榜 entry

  场景: 带反作弊 flag 的成绩不进入默认榜单
    假如玩家提交的结果为 accepted_with_flags
    当后端处理排行榜投影
    那么默认排行榜不应展示该成绩
    而且该 run 的反作弊标记应可供后台审计

功能: bark-battle 隐私边界

功能: bark-battle 隐私边界
  为了保护玩家声音隐私
  作为平台
  我不能上传或保存原始麦克风音频

  场景: finish 请求包含原始音频字段
    假如前端误传 audio、audioBase64、waveform 或 pcmSamples 字段
    当后端解析 finish 请求
    那么后端应拒绝请求或忽略并记录非法字段
    而且持久化记录中不应出现可还原声音的数据

  场景: 正常 finish 只提交派生聚合指标
    假如玩家完成一局 bark-battle
    当玩家提交 finish 请求
    那么请求体应只包含峰值、均值、有效叫声次数、节奏命中、最终能量和耗时等派生指标
    而且后端只保存这些派生指标与裁决结果

9.2 BDD 到测试映射

BDD 场景	测试层级	建议目标文件	RED 期望
玩家请求已发布作品的 runtime config	contract + API	server-rs/crates/shared-contracts/src/bark_battle.rs、server-rs/crates/api-server/src/bark_battle.rs	新 DTO / route 不存在导致编译或断言失败
玩家请求未发布作品的 runtime config	domain + API	server-rs/crates/module-bark-battle/src/domain.rs、server-rs/crates/api-server/src/bark_battle.rs	未发布状态未被拒绝
玩家携带过期配置版本进入 runtime	domain	server-rs/crates/module-bark-battle/src/domain.rs	configVersion mismatch 未返回错误
玩家成功开始已发布作品运行态	API + integration	server-rs/crates/api-server/src/bark_battle.rs	start 未返回 runToken 或未写 tracking draft
无权限玩家尝试开始运行态	API	server-rs/crates/api-server/src/bark_battle.rs	无权限仍创建 run 或写埋点
玩家完成一局并提交合法派生指标	domain + facade	server-rs/crates/module-bark-battle/src/domain.rs、server-rs/crates/spacetime-client/src/bark_battle.rs	score / serverWinner 未由后端计算
玩家重复提交同一个 run 的 finish	SpacetimeDB reducer / facade	server-rs/crates/spacetime-module/src/...、server-rs/crates/spacetime-client/src/bark_battle.rs	duplicate finish 被接受
玩家提交不合理的时长	domain	server-rs/crates/module-bark-battle/src/domain.rs	未产生 elapsed_too_short flag
玩家提交超出范围的声音指标	domain	server-rs/crates/module-bark-battle/src/domain.rs	未产生 metric_out_of_range / impossible_bark_count
作品开启排行榜且成绩被接受	domain + projection	server-rs/crates/module-bark-battle/src/domain.rs、SpacetimeDB reducer 测试	accepted 成绩未生成 leaderboard projection
作品关闭排行榜	domain + projection	server-rs/crates/module-bark-battle/src/domain.rs、SpacetimeDB reducer 测试	leaderboardEnabled=false 仍写榜
带反作弊 flag 的成绩不进入默认榜单	domain	server-rs/crates/module-bark-battle/src/domain.rs	flagged 成绩仍进入默认榜
finish 请求包含原始音频字段	contract + API	server-rs/crates/shared-contracts/src/bark_battle.rs、API 反序列化测试	DTO 接受或持久化原始音频字段
正常 finish 只提交派生聚合指标	contract	server-rs/crates/shared-contracts/src/bark_battle.rs	DTO 缺字段或包含隐私风险字段

9.3 TDD RED-GREEN-REFACTOR 切片

每个切片必须先写失败测试并运行到预期失败，再写最小实现。

Slice 1: shared contracts 固定请求/响应形状

RED：

cd server-rs
cargo test -p shared-contracts bark_battle_contract_uses_camel_case --no-default-features

先新增测试，断言：

• BarkBattleRunStartRequest 序列化为 workId、configVersion、sourceRoute。
• BarkBattleRunFinishRequest 只包含 runId、runToken、workId、configVersion、elapsedMs、finalEnergy、clientWinner、metrics。
• metrics 只包含派生聚合字段，不包含 audio、audioBase64、waveform、pcmSamples。

GREEN：新增 shared-contracts/src/bark_battle.rs 与 lib.rs 导出，让测试通过。

REFACTOR：统一枚举命名、字段注释和默认值策略。

Slice 2: domain 校验 runtime config 与 finish metrics

RED：

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

先新增测试，断言：

• playTypeId 必须为 bark-battle。
• durationMs、energyMin、energyMax、barkThreshold 必须在合法范围。
• peakVolumeMax、peakVolumeAvg 必须在 0..1。
• 过短时长产生 elapsed_too_short。
• 不可能叫声次数产生 impossible_bark_count。

GREEN：新增 module-bark-battle 纯领域类型与校验函数。

REFACTOR：把常量收敛为领域常量，避免 magic number 分散。

Slice 3: domain 重新裁决成绩与排行榜资格

RED：

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

先新增测试，断言：

• 后端根据 finalEnergy 重算 serverWinner，不直接信任 clientWinner。
• 合法胜利生成 accepted=true 与稳定 ScoreSummary。
• 带 flag 的结果默认 leaderboardEligible=false。
• leaderboardEnabled=false 时不生成榜单投影。

GREEN：补 score_finish_result(...)、is_leaderboard_eligible(...) 等纯函数。

REFACTOR：拆分 score、winner、anti-cheat、leaderboard 四组小函数。

Slice 4: SpacetimeDB 表、reducer 与 migration

RED：

cd server-rs
cargo check -p spacetime-module --no-default-features
cargo test -p spacetime-client bark_battle_facade_maps_run_records --no-default-features

先新增 facade / mapper 测试或编译断言，预期因绑定、表或 reducer 缺失失败。

GREEN：新增表、reducer/procedure、migration.rs、生成绑定、spacetime-client facade。

REFACTOR：确保 api-server 不直接依赖 generated bindings，mapper 命名与现有玩法一致。

Slice 5: api-server start / finish BFF

RED：

cd server-rs
cargo test -p api-server bark_battle_start_records_work_play_start --no-default-features
cargo test -p api-server bark_battle_finish_rejects_duplicate_or_invalid_metrics --no-default-features

先新增 API 测试，断言：

• start 成功返回 runId、runToken、runtimeConfig。
• start 成功后主动补写 work_play_start，不只依赖 route-level 兜底。
• finish 重复提交被拒绝。
• finish 不接受非法 metrics。

GREEN：新增 Axum route、handler、错误映射、tracking 调用。

REFACTOR：handler 只做编排，把规则留在 domain，把持久化留在 facade。

Slice 6: 前端 contract 对齐

RED：

npm run test -- bark-battle
npm run typecheck

先新增前端 contract / client 测试，预期因 TS 类型或 client 缺失失败。

GREEN：补前端共享 contract mirror、runtime client 调用 start / finish。

REFACTOR：删除重复类型，保持后端 DTO 为事实源。

9.4 后端验收命令

按切片逐步运行，不要等全部实现后一次性补测：

cd server-rs
cargo test -p shared-contracts bark_battle --no-default-features
cargo test -p module-bark-battle --no-default-features
cargo check -p spacetime-module --no-default-features
cargo check -p spacetime-client --no-default-features
cargo test -p api-server bark_battle --no-default-features

如涉及 API smoke：

npm run api-server
# 另开终端执行对应 bark-battle start / finish smoke 或项目既有 API 测试脚本

每次表结构变更后必须同步：

1. 更新 migration.rs。
2. 重新生成 SpacetimeDB bindings。
3. 检查 generated bindings 变更只来自生成命令。
4. 运行 cargo check -p spacetime-module -p spacetime-client --no-default-features。

9.5 前端 contract 对齐验收

前端只在后端 contract 稳定后接入：

npm run typecheck
npm test -- bark-battle
npm run build

验收：

• runtime start / finish 请求字段与 shared contracts 一致。
• 前端 result panel 展示后端 RunResult。
• 前端本地结算只作为即时反馈，正式结果以后端返回为准。

9.6 手工验收清单

• 可以创建并保存 bark-battle 草稿。
• 可以发布成稳定作品 ID，playTypeId = bark-battle。
• runtime start 返回 config、runId、runToken。
• start 写入 work_play_start，scope 与 metadata 符合要求。
• finish 不上传音频，只上传派生指标。
• finish 返回服务端认可的 result。
• 异常时长、重复提交、config version mismatch 会被拒绝或打 flag。
• 排行榜关闭时不写榜；开启时只写 accepted 结果。

10. 与现有前端方案和 BDD 文档的关系

10.1 依赖文档

• 前端 runtime 方案：docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md。
• BDD / DDD / TDD 总计划：.hermes/plans/2026-05-11_144229-bark-battle-2d-game-bdd-ddd-tdd-plan.md。
• 当前后端实现基线：docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md。
• SpacetimeDB 表结构变更约束：docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md。

10.2 与前端方案的对齐点

• 前端方案负责 Phaser / Web Audio / DOM HUD；本文负责作品、成绩、排行榜、发布和埋点。
• 前端 BarkBattleSnapshot 可用于本地即时表现，但正式 RunResult 以后端返回为准。
• 前端不上传原始音频，只上传 BarkBattleDerivedMetrics。
• 前端本地 config 应来自后端发布态 BarkBattleRuntimeConfig，不能在生产游玩中使用未发布临时配置。
• 前端 result panel 应能展示后端返回的 score、grade、antiCheatFlags 与 leaderboard entry。

10.3 与 BDD 的对齐点

后续 BDD 场景应覆盖：

• 玩家从作品页进入 bark-battle runtime。
• 玩家授权麦克风后开始 30 秒对战。
• 玩家完成单局后看到后端确认结果。
• 未授权麦克风时可以看到降级说明，但不写正式成绩。
• 作品关闭排行榜时不展示排名入口。
• 作品开启排行榜时展示当前作品排名。
• 重复 finish / 过期 run / 配置版本不一致时返回可解释错误。

10.4 后端落地顺序建议

1. 先只做 contract + domain，固定 playTypeId = bark-battle 与配置 schema。
2. 再做草稿 / 发布态作品配置读写。
3. 再做 start / finish run 与 work_play_start 埋点。
4. 最后做排行榜投影。
5. 实时多人协议另起方案，不与 MVP 混做。