给游戏分发 DTO 门禁补上手拼响应构建器的逐键比对

- 新增 RESPONSE_BUILDERS：解析 api-server 里 game_payload / public_game_payload / private_version_payload / version_summary_payload 的 json! 顶层键与顶层 object.insert，逐键比对 TS 类型 - 发出的键必须都在 TS 类型里，TS 的必需字段必须都发出，公开投影还必须发出被标成可选的 currentVersion - game_payload 的 author / deviceSupport 两个嵌套字面量同样逐键比对 - TS 类型解析同时记录必需字段，供这一层比对使用 - 同步游戏分发里程碑第 6 条的构建器取证与剩余缺口
2026-09-28 18:06:56 +08:00
parent 4c31f50007
commit 4c4e61255e
2 changed files with 288 additions and 8 deletions
@@ -163,4 +163,4 @@
  - 第 1 条（owner 不能由请求伪造；其他账号不能读取私有版本、上传、提交或撤销）：领域侧有 `owner_is_required_for_version_and_package_mutations`；接口侧代码在越权时返回 403/404，但**没有跨账号读/写/撤销的接口级用例**——缺的就是这一层。
  - 第 4 条（一份版本只接受一份已确认内容；同 key 同请求幂等、不同请求冲突；同版本并发上传不混写）：前两半已覆盖——`idempotency_replays_same_snapshot_and_rejects_digest_conflict`、`validation_failure_can_retry_same_confirmed_package`、api-server 的 `idempotency_key_requires_a_bounded_non_empty_header`；**本轮新增** `a_version_accepts_only_one_confirmed_package`（不同摘要或字节数的确认被拒为 `PackageMismatch`，重复确认同一份内容返回同一包身份；变异去掉该守卫后只有它变红）。**仍缺**「同版本并发上传不混写」：串行化在 `spacetime-module` / api-server 的 CAS 那一层，领域服务本身是同步的，需要在那一层写用例。
  - 第 5 条（校验可异步恢复；响应丢失、服务进程退出与客户端重试回到原版本；确定失败与未知结果可区分）：只有 api-server 的 `recovery_action_covers_every_version_status` 覆盖"状态 → 恢复动作"的映射；后两句在 game-distribution 链路没有用例。
-  - 第 6 条（状态/私有查询/错误 envelope 的 Rust 与 TS DTO 一致；新增 schema、迁移、表目录与绑定一致）：后半句有门禁（`npm run lint` 内的 SpacetimeDB schema guard 覆盖 85 张表、生成绑定校验通过）。**本轮新增** `check:game-distribution-dto-parity`（已接进 `npm run lint`）：按显式映射表逐字段/逐变体比对 14 组 Rust `shared-contracts` DTO 与手写 `packages/shared/src/contracts/gameDistribution.ts`，两个方向都做过变异验证——TS 侧把 `name` 改成 `displayName`、Rust 侧给 `GameDistributionAuthor` 加 `extra_field`，各自都让门禁失败并指出缺哪个字段；脚本同时登记了 7 个「服务端逐字段手拼 JSON、没有 Rust 结构体」的 TS 类型。**本轮补齐** `coverObjectKey` / `screenshots` / `publicationRevision` 四个字段进 Rust 结构体（依据是 `game_payload` 与 `private_version_payload` 实际发出的键），并删掉脚本里用来豁免它们的 `TS_ONLY_FIELDS` 白名单：现在任一方向多出字段都会让门禁失败，作者侧响应省略 `currentVersion` 这一条差异改用 TS 可选字段描述。**剩余缺口**：这两个响应仍是 `serde_json::json!` 手拼，Rust 侧没有构建它们的结构体，所以门禁只能保证类型字段一致，不能保证构建器真的按类型发键；要彻底满足这一句，需要先把响应改成结构化构建。
+  - 第 6 条（状态/私有查询/错误 envelope 的 Rust 与 TS DTO 一致；新增 schema、迁移、表目录与绑定一致）：后半句有门禁（`npm run lint` 内的 SpacetimeDB schema guard 覆盖 85 张表、生成绑定校验通过）。**本轮新增** `check:game-distribution-dto-parity`（已接进 `npm run lint`）：按显式映射表逐字段/逐变体比对 14 组 Rust `shared-contracts` DTO 与手写 `packages/shared/src/contracts/gameDistribution.ts`，两个方向都做过变异验证——TS 侧把 `name` 改成 `displayName`、Rust 侧给 `GameDistributionAuthor` 加 `extra_field`，各自都让门禁失败并指出缺哪个字段；脚本同时登记了 7 个「服务端逐字段手拼 JSON、没有 Rust 结构体」的 TS 类型。**本轮补齐** `coverObjectKey` / `screenshots` / `publicationRevision` 四个字段进 Rust 结构体（依据是 `game_payload` 与 `private_version_payload` 实际发出的键），并删掉脚本里用来豁免它们的 `TS_ONLY_FIELDS` 白名单：现在任一方向多出字段都会让门禁失败，作者侧响应省略 `currentVersion` 这一条差异改用 TS 可选字段描述。**本轮再补构建器一层**：门禁新增 `RESPONSE_BUILDERS`，解析 `server-rs/crates/api-server/src/modules/game_distribution.rs` 里 `game_payload` / `public_game_payload` / `private_version_payload` / `version_summary_payload` 的 `json!` 顶层键与顶层 `object.insert(…)`，逐键比对 TS 类型：发出的键必须都在类型里、类型的必需字段必须都发出、`public_game_payload` 还必须发出被 TS 标成可选的 `currentVersion`，`game_payload` 的 `author` / `deviceSupport` 两个嵌套字面量同样逐键比对。变异验证五种改法各自让门禁失败并指出具体键：删掉 `game_payload.publicationRevision`、删掉 `deviceSupport.touch`、把 `author.avatarUrl` 改名、把插入的 `currentVersion` 改名、给 `version_summary_payload` 加一个 TS 没有的键；恢复后通过。**剩余缺口**：门禁比对的是键而不是值的类型，也覆盖不到未登记的嵌套对象与 envelope——成功/失败 envelope 的字段由 TS 侧运行时守卫（`packages/shared/src/http.ts`、`src/services/apiClient.ts`）消费，要彻底类型化得先把这两个响应改成结构化构建。