实现统一项目发行版本

以 projectVersion 作为 AGC 唯一用户版本，支持同版本重复提交和版本回退。

保留 publicationRevision 并发校验与旧客户端自动递增兼容。

packages/shared/src/contracts/gameCreationApp.ts

@@ -976,6 +976,42 @@ export interface GameCreationAppPublicationBinding {
   status?: string | null;
 }
 
+/** 项目版本标签的唯一合法形状：正整数，且能安全走 JSON number。 */
+export function isGameCreationAppProjectVersion(value: unknown): value is number {
+  return (
+    typeof value === 'number' &&
+    Number.isSafeInteger(value) &&
+    value > 0
+  );
+}
+
+/** 项目版本标签的建议默认值：没有任何线上记录时的首个版本。 */
+export const GAME_CREATION_APP_FIRST_PROJECT_VERSION = 1;
+
+/**
+ * 项目版本标签的有效值。
+ *
+ * 新清单直接用写下来的 `projectVersion`；旧清单缺这个字段时按发布绑定回填——线上已有版本号
+ * （`latestVersionNumber > 0`）就用它，否则用首版 1。
+ *
+ * `binding` 必须已经按**当前会话**（`accountId` + `apiBaseUrl`）与 `gameId` 隔离：调用方传
+ * 别的账号 / 别的环境的绑定，就会把该项目的版本标签回填成别人的线上版本号。原生回读与发布
+ * 写回都遵守这条隔离，渲染层只消费原生已经隔离过的绑定。
+ */
+export function resolveGameCreationAppProjectVersion(
+  manifest: Pick<GameCreationAppManifest, 'projectVersion'>,
+  binding?: GameCreationAppPublicationBinding | null,
+): number {
+  if (isGameCreationAppProjectVersion(manifest.projectVersion)) {
+    return manifest.projectVersion;
+  }
+  const latest = binding?.latestVersionNumber;
+  if (isGameCreationAppProjectVersion(latest)) {
+    return latest;
+  }
+  return GAME_CREATION_APP_FIRST_PROJECT_VERSION;
+}
+
 export interface GameCreationAppManifest {
   schemaVersion: string;
   projectId: string;
@@ -988,6 +1024,17 @@ export interface GameCreationAppManifest {
   versions?: GameIterationVersion[];
   godotProjectRoot?: string | null;
   cocosProjectRoot?: string | null;
+  /**
+   * 唯一用户发行版本标签（`项目版本 vN`），正整数，不需要递增。
+   *
+   * 同一个 `gameId` 的同一个版本标签可以反复提交：每次具体包/资料/审核提交由不可变
+   * `versionId` 区分，因此这里允许重复与回退（低于线上当前版本）。它**不是**内部编辑迭代
+   * `versions[].projectRevision`，也不是 semver 字符串。
+   *
+   * 旧清单没有这个字段：读取方按当前账号 / origin / gameId 隔离后的发布绑定回填（见
+   * `resolveGameCreationAppProjectVersion`），发布或改版本标签时由原生写回。
+   */
+  projectVersion?: number | null;
   /** 平台发布绑定；缺失即该项目尚未发布过。 */
   publication?: GameCreationAppPublicationBinding | null;
 }

packages/shared/src/contracts/gameDistribution.ts

@@ -169,8 +169,11 @@ export type GameDistributionCreateGameRequest = {
 export type GameDistributionCreateVersionRequest = {
   localProjectId?: string | null;
   /**
-   * 显式目标版本号；缺省时服务端按该游戏已有最大版本号自动 +1。
-   * 必须严格大于当前最大版本号（允许跳号），否则返回 409。
+   * 用户可见的正整数版本标签（AGC 里就是 `projectVersion`）。
+   *
+   * 传入时只要求 `>= 1`：同一 `gameId` 的同一个版本号可以反复提交，每次提交生成新的
+   * `versionId`，允许重复标签与回退到更小的版本号，不与已有最大值比较。
+   * 缺省时保留旧客户端兼容行为：服务端按该游戏已有最大版本号 +1。
    */
   versionNumber?: number | null;
   packageSha256: string;