给游戏分发 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 条的构建器取证与剩余缺口

scripts/check-game-distribution-dto-parity.mjs

@@ -6,12 +6,16 @@
 //   - 映射表同时是「哪些 Rust DTO 必须在 TS 里有对应类型」的清单；
 //   - `TS_ONLY_TYPES` 是「服务端手拼 JSON、没有 Rust 结构体」的说明清单；
 //   - 两侧字段必须逐一对齐，任一方向多出字段都会失败（没有白名单）。
+//   - 服务端手拼响应的构建器（`json!` / `object.insert`）单独比对顶层键：
+//     类型字段一致只说明契约写得对，这一层才有证据说明构建器真的按契约发键。
 // 任何一处没有分类的新类型、新字段都会让检查失败，避免静默漂移。
 
 import fs from 'node:fs';
 
 const RUST_FILE = 'server-rs/crates/shared-contracts/src/game_distribution.rs';
 const TS_FILE = 'packages/shared/src/contracts/gameDistribution.ts';
+const API_MODULE_FILE =
+  'server-rs/crates/api-server/src/modules/game_distribution.rs';
 
 // [Rust 类型名, TS 类型名]
 const PAIRS = [
@@ -52,6 +56,29 @@ const TS_ONLY_TYPES = [
   'GameDistributionCancelVersionResponse',
 ];
 
+// 服务端逐字段手拼 JSON 的响应构建器：把「这个函数真的会发出的顶层键」与 TS 类型逐键比对。
+// - `base`：该构建器在另一个已登记构建器的结果上追加键（公开投影 = 作者投影 + currentVersion）；
+// - `mustEmit`：TS 类型为了同时描述两种形状把该键标成可选，但这条路径必须发出。
+// 只解析顶层键；需要一并比对的嵌套对象用 `nested` 显式登记，没登记的嵌套对象不在证据范围内。
+const RESPONSE_BUILDERS = [
+  {
+    fn: 'game_payload',
+    ts: 'GameDistributionGame',
+    nested: [
+      { key: 'author', ts: 'GameDistributionAuthor' },
+      { key: 'deviceSupport', ts: 'GameDistributionDeviceSupport' },
+    ],
+  },
+  {
+    fn: 'public_game_payload',
+    ts: 'GameDistributionGame',
+    base: 'game_payload',
+    mustEmit: ['currentVersion'],
+  },
+  { fn: 'private_version_payload', ts: 'GameDistributionPrivateVersion' },
+  { fn: 'version_summary_payload', ts: 'GameDistributionVersionSummary' },
+];
+
 function camelCase(value) {
   return value.replace(/_([a-z0-9])/g, (_, char) => char.toUpperCase());
 }
@@ -98,12 +125,15 @@ function tsDefinitions(source) {
     /export type (GameDistribution\w+) = \{([\s\S]*?)\n\};/g;
   let match;
   while ((match = objectPattern.exec(source))) {
-    result.set(match[1], {
-      kind: 'struct',
-      members: [...match[2].matchAll(/^ {2}(\w+)\??:/gm)].map(
-        (item) => item[1],
-      ),
-    });
+    const members = [];
+    const required = [];
+    for (const line of match[2].split('\n')) {
+      const member = /^ {2}(\w+)(\??):/.exec(line);
+      if (!member) continue;
+      members.push(member[1]);
+      if (member[2] !== '?') required.push(member[1]);
+    }
+    result.set(match[1], { kind: 'struct', members, required });
   }
   const unionPattern = /export type (GameDistribution\w+) =\s*([^;]+);/g;
   while ((match = unionPattern.exec(source))) {
@@ -121,6 +151,152 @@ function difference(left, right) {
   return left.filter((value) => !rightSet.has(value));
 }
 
+// 跳过 Rust 字符串字面量，返回结束引号的下标。
+function skipString(source, start) {
+  let index = start + 1;
+  while (index < source.length) {
+    if (source[index] === '\\') {
+      index += 2;
+      continue;
+    }
+    if (source[index] === '"') return index;
+    index += 1;
+  }
+  return source.length - 1;
+}
+
+// 取顶层函数的函数体文本；找不到函数或括号不闭合时返回 null。
+function functionBody(source, name) {
+  const signature = new RegExp(`\\nfn ${name}\\(`).exec(source);
+  if (!signature) return null;
+  const open = source.indexOf('{', signature.index + signature[0].length);
+  if (open < 0) return null;
+  let depth = 0;
+  for (let index = open; index < source.length; index += 1) {
+    const char = source[index];
+    if (char === '"') {
+      index = skipString(source, index);
+      continue;
+    }
+    if (char === "'") {
+      const charLiteral = /^'(?:\\.|[^'\\])'/.exec(source.slice(index));
+      if (charLiteral) index += charLiteral[0].length - 1;
+      continue;
+    }
+    if (char === '{') depth += 1;
+    else if (char === '}') {
+      depth -= 1;
+      if (depth === 0) return source.slice(open + 1, index);
+    }
+  }
+  return null;
+}
+
+// 取第一个 `json!({ ... })` 字面量文本；没有则返回 null。
+function firstJsonLiteral(body) {
+  const marker = 'json!({';
+  const start = body.indexOf(marker);
+  if (start < 0) return null;
+  const open = start + marker.length - 1;
+  let depth = 0;
+  for (let index = open; index < body.length; index += 1) {
+    const char = body[index];
+    if (char === '"') {
+      index = skipString(body, index);
+      continue;
+    }
+    if (char === '{' || char === '[' || char === '(') depth += 1;
+    else if (char === '}' || char === ']' || char === ')') {
+      depth -= 1;
+      if (depth === 0) return body.slice(open, index + 1);
+    }
+  }
+  return null;
+}
+
+// 取括号对的结束下标；不闭合返回 -1。
+function matchingBracket(text, open) {
+  let depth = 0;
+  for (let index = open; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === '"') {
+      index = skipString(text, index);
+      continue;
+    }
+    if (char === '{' || char === '[' || char === '(') depth += 1;
+    else if (char === '}' || char === ']' || char === ')') {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return -1;
+}
+
+// 取对象字面量的直接键：只有上一个有效字符是 `{` 或 `,` 且下一字符是 `:`
+// 的字符串才算键，因此嵌套对象的键与作为值的字符串不会混进来。
+function objectKeys(text) {
+  const keys = [];
+  let inner = 0;
+  let previous = '';
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === '"') {
+      const close = skipString(text, index);
+      if (
+        inner === 1 &&
+        (previous === '{' || previous === ',') &&
+        text[close + 1] === ':'
+      ) {
+        keys.push(text.slice(index + 1, close));
+        previous = ':';
+        index = close;
+        continue;
+      }
+      previous = '"';
+      index = close;
+      continue;
+    }
+    if (char === '{' || char === '[' || char === '(') inner += 1;
+    else if (char === '}' || char === ']' || char === ')') inner -= 1;
+    if (!/\s/.test(char)) previous = char;
+  }
+  return keys;
+}
+
+// 取对象字面量里某个直接键对应的嵌套对象字面量文本；该键不是对象字面量时返回 null。
+function nestedObjectText(text, wanted) {
+  let inner = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === '"') {
+      const close = skipString(text, index);
+      if (inner === 1 && text.slice(index + 1, close) === wanted) {
+        let cursor = close + 1;
+        while (cursor < text.length && /\s/.test(text[cursor])) cursor += 1;
+        if (text[cursor] === ':') {
+          let open = cursor + 1;
+          while (open < text.length && /\s/.test(text[open])) open += 1;
+          if (text[open] !== '{') return null;
+          const end = matchingBracket(text, open);
+          return end < 0 ? null : text.slice(open, end + 1);
+        }
+      }
+      index = close;
+      continue;
+    }
+    if (char === '{' || char === '[' || char === '(') inner += 1;
+    else if (char === '}' || char === ']' || char === ')') inner -= 1;
+  }
+  return null;
+}
+
+// 取函数体里顶层追加的键：`object.insert("key".to_string(), ...)`。
+function insertedKeys(body) {
+  return [...body.matchAll(/object\.insert\(\s*"([^"]+)"/g)].map(
+    (item) => item[1],
+  );
+}
+
 const rust = rustDefinitions(fs.readFileSync(RUST_FILE, 'utf8'));
 const ts = tsDefinitions(fs.readFileSync(TS_FILE, 'utf8'));
 const failures = [];
@@ -162,6 +338,108 @@ for (const name of rust.keys()) {
     failures.push(`Rust 新增 DTO ${name} 没有登记进映射表（TS 侧必须同步）`);
   }
 }
+
+const apiSource = fs.readFileSync(API_MODULE_FILE, 'utf8');
+const emittedByBuilder = new Map();
+for (const builder of RESPONSE_BUILDERS) {
+  const tsDefinition = ts.get(builder.ts);
+  if (!tsDefinition) {
+    failures.push(`响应构建器 ${builder.fn} 的 TS 类型不存在：${builder.ts}`);
+    continue;
+  }
+  const body = functionBody(apiSource, builder.fn);
+  if (body === null) {
+    failures.push(`响应构建器 ${builder.fn} 在 ${API_MODULE_FILE} 里找不到`);
+    continue;
+  }
+  const literal = firstJsonLiteral(body);
+  const literalKeys = literal ? objectKeys(literal) : [];
+  const ownKeys = [...new Set([...literalKeys, ...insertedKeys(body)])];
+  let emitted = ownKeys;
+  if (builder.base) {
+    if (literalKeys.length > 0) {
+      failures.push(
+        `${builder.fn} 声明了 base=${builder.base}，却自己也有 json! 字面量；两者只能取其一`,
+      );
+      continue;
+    }
+    if (ownKeys.length === 0) {
+      failures.push(
+        `${builder.fn} 声明了 base=${builder.base}，但没有解析到任何顶层 object.insert("…")`,
+      );
+      continue;
+    }
+    const baseKeys = emittedByBuilder.get(builder.base);
+    if (!baseKeys) {
+      failures.push(
+        `${builder.fn} 的 base=${builder.base} 必须登记在它前面，才能复用已解析的键`,
+      );
+      continue;
+    }
+    emitted = [...new Set([...baseKeys, ...ownKeys])];
+  } else if (literalKeys.length === 0) {
+    failures.push(`${builder.fn} 没有解析到任何 json!({ … }) 顶层键`);
+    continue;
+  }
+  emittedByBuilder.set(builder.fn, emitted);
+
+  const unknown = difference(emitted, tsDefinition.members);
+  if (unknown.length > 0) {
+    failures.push(
+      `${builder.fn} 发出 ${builder.ts} 没有的键：${unknown.join(', ')}（TS 类型必须同步）`,
+    );
+  }
+  const missing = difference(tsDefinition.required ?? [], emitted);
+  if (missing.length > 0) {
+    failures.push(
+      `${builder.fn} 没有发出 ${builder.ts} 的必需字段：${missing.join(', ')}`,
+    );
+  }
+  const mustEmit = difference(builder.mustEmit ?? [], emitted);
+  if (mustEmit.length > 0) {
+    failures.push(`${builder.fn} 必须发出的键缺失：${mustEmit.join(', ')}`);
+  }
+  for (const nested of builder.nested ?? []) {
+    const nestedDefinition = ts.get(nested.ts);
+    if (!nestedDefinition) {
+      failures.push(
+        `${builder.fn} 的嵌套对象 ${nested.key} 对应的 TS 类型不存在：${nested.ts}`,
+      );
+      continue;
+    }
+    const nestedText = literal ? nestedObjectText(literal, nested.key) : null;
+    if (!nestedText) {
+      failures.push(
+        `${builder.fn} 的 ${nested.key} 不是对象字面量，无法与 ${nested.ts} 比对`,
+      );
+      continue;
+    }
+    const nestedKeys = objectKeys(nestedText);
+    const nestedUnknown = difference(nestedKeys, nestedDefinition.members);
+    if (nestedUnknown.length > 0) {
+      failures.push(
+        `${builder.fn} 的 ${nested.key} 发出 ${nested.ts} 没有的键：${nestedUnknown.join(', ')}`,
+      );
+    }
+    const nestedMissing = difference(
+      nestedDefinition.required ?? [],
+      nestedKeys,
+    );
+    if (nestedMissing.length > 0) {
+      failures.push(
+        `${builder.fn} 的 ${nested.key} 没有发出 ${nested.ts} 的必需字段：${nestedMissing.join(', ')}`,
+      );
+    }
+  }
+}
+for (const builder of RESPONSE_BUILDERS) {
+  if (!emittedByBuilder.has(builder.fn)) {
+    failures.push(
+      `响应构建器 ${builder.fn} 的键没有解析成功，无法证明与 TS 一致`,
+    );
+  }
+}
+
 for (const name of ts.keys()) {
   if (!mappedTs.has(name) && !TS_ONLY_TYPES.includes(name)) {
     failures.push(
@@ -176,5 +454,7 @@ if (failures.length > 0) {
   process.exit(1);
 }
 console.log(
-  `[check:game-distribution-dto-parity] OK：${PAIRS.length} 组 Rust/TS 类型一致，${TS_ONLY_TYPES.length} 个手拼响应类型已登记`,
+  `[check:game-distribution-dto-parity] OK：${PAIRS.length} 组 Rust/TS 类型一致，` +
+    `${RESPONSE_BUILDERS.length} 个手拼响应构建器键一致，` +
+    `${TS_ONLY_TYPES.length} 个手拼响应类型已登记`,
 );