diff --git a/docs/adr/【ADR】游戏分发版本以versionNumber为对外身份-2026-10-07.md b/docs/adr/【ADR】游戏分发版本以versionNumber为对外身份-2026-10-07.md index 2efda202d..6750c58b7 100644 --- a/docs/adr/【ADR】游戏分发版本以versionNumber为对外身份-2026-10-07.md +++ b/docs/adr/【ADR】游戏分发版本以versionNumber为对外身份-2026-10-07.md @@ -39,26 +39,26 @@ URL 里那串随机 UUID 既不可读，客户端也无法在提交前独立构 对外（作者 / 公开）版本一律用 `{version_number}`；后台与内部（`/admin/...`、收据、媒体命名空间） 继续用 `{version_id}`。完整端点表： -| 方法 | 路径 | 请求 | 响应 | 鉴权 / 头 | -|-------------------------------|---------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|---------------------------------------| -| POST | `/api/game-distribution/games` | multipart：`metadata` = `NewGameVersionRequest`（JSON），`cover` / `screenshot` 二进制 part | `GameDistributionPublishVersionResponse` | Bearer + `Idempotency-Key` + 发布灰度 | -| POST | `/api/game-distribution/games/{game_id}/versions/{version_number}` | 同上；body 不含 `gameId` / `versionNumber`，身份全部取自路径 | `GameDistributionPublishVersionResponse` | Bearer + `Idempotency-Key` + 发布灰度 | -| GET | `/api/game-distribution/games/{game_id}/versions/{version_number}` | – | 版本详情（`GameDistributionPrivateVersion` + 作品上下文） | Bearer | -| PATCH（未落地） | `/api/game-distribution/games/{game_id}/versions/{version_number}` | JSON：`GameMetadata` + `expectedPublicationRevision` CAS | 版本详情 | Bearer + `Idempotency-Key` | -| PUT | `…/versions/{version_number}/package` | `application/octet-stream` | 上传 ack | Bearer + `Idempotency-Key` | -| GET | `…/versions/{version_number}/package/upload-state` | – | 上传状态 | Bearer | -| PUT | `…/versions/{version_number}/package/chunk` | `application/octet-stream` + 偏移头 | 分片 ack | Bearer | -| POST | `…/versions/{version_number}/package/complete` | JSON | ack | Bearer + `Idempotency-Key` | -| POST | `…/versions/{version_number}/package/reset` | JSON | ack | Bearer | +| 方法 | 路径 | 请求 | 响应 | 鉴权 / 头 | +|-------------------------------|-----------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|---------------------------------------| +| POST | `/api/game-distribution/games` | multipart：`metadata` = `NewGameVersionRequest`（JSON），`cover` / `screenshot` 二进制 part | `GameDistributionPublishVersionResponse` | Bearer + `Idempotency-Key` + 发布灰度 | +| POST | `/api/game-distribution/games/{game_id}/versions/{version_number}` | 同上；body 不含 `gameId` / `versionNumber`，身份全部取自路径 | `GameDistributionPublishVersionResponse` | Bearer + `Idempotency-Key` + 发布灰度 | +| GET | `/api/game-distribution/games/{game_id}/versions/{version_number}` | – | 版本详情（`GameDistributionPrivateVersion` + 作品上下文） | Bearer | +| PATCH（未落地） | `/api/game-distribution/games/{game_id}/versions/{version_number}` | JSON：`GameMetadata` + `expectedPublicationRevision` CAS | 版本详情 | Bearer + `Idempotency-Key` | +| PUT | `…/versions/{version_number}/package` | `application/octet-stream` | 上传 ack | Bearer + `Idempotency-Key` | +| GET | `…/versions/{version_number}/package/upload-state` | – | 上传状态 | Bearer | +| PUT | `…/versions/{version_number}/package/chunk` | `application/octet-stream` + 偏移头 | 分片 ack | Bearer | +| POST | `…/versions/{version_number}/package/complete` | JSON | ack | Bearer + `Idempotency-Key` | +| POST | `…/versions/{version_number}/package/reset` | JSON | ack | Bearer | | PUT / GET / PUT / POST / POST | `…/versions/{version_number}/project-bundle`（`/upload-state` `/chunk` `/complete` `/reset`） | 与发行包族逐条对齐 | 同发行包族 | Bearer（幂等键同族） | -| POST | `…/versions/{version_number}/submit` | JSON：`expectedPublicationRevision` | 版本详情 | Bearer + `Idempotency-Key` | -| POST | `…/versions/{version_number}/cancel` | JSON：`CancelVersionRequest` | 版本详情 | Bearer + `Idempotency-Key` | -| PATCH | `/api/game-distribution/my-games/{game_id}` | multipart：`metadata` = `GameDistributionUpdateGameMetadataRequest`（并入 `forkAuthorization`）+ 媒体 part | `{ game, replayed }` | Bearer + `Idempotency-Key` | -| DELETE | `/api/game-distribution/my-games/{game_id}` | – | 软删 ack | Bearer | -| GET | `/api/game-distribution/games/{game_id}/forks` | – | `GameDistributionForksResponse` | 公开（原 `/derived` 改名） | -| GET | `/api/game-distribution/games/{game_id}/network` | – | `GameDistributionNetworkResponse`（整棵改编树） | 公开（原 `/lineage` 改名） | -| GET | `/api/game-distribution/games/{game_id}/source`（`/package` `/project`） | – | `GameDistributionSourceResponse` / 二进制 | Bearer（原路径改名） | -| GET | `/api/game-distribution/games/{game_id}/network/stats` | – | `GameDistributionNetworkStatsResponse`（子树归集） | Bearer（原路径改名） | +| POST | `…/versions/{version_number}/submit` | JSON：`expectedPublicationRevision` | 版本详情 | Bearer + `Idempotency-Key` | +| POST | `…/versions/{version_number}/cancel` | JSON：`CancelVersionRequest` | 版本详情 | Bearer + `Idempotency-Key` | +| PATCH | `/api/game-distribution/my-games/{game_id}` | multipart：`metadata` = `GameDistributionUpdateGameMetadataRequest`（并入 `forkAuthorization`）+ 媒体 part | `{ game, replayed }` | Bearer + `Idempotency-Key` | +| DELETE | `/api/game-distribution/my-games/{game_id}` | – | 软删 ack | Bearer | +| GET | `/api/game-distribution/games/{game_id}/forks` | – | `GameDistributionForksResponse` | 公开（原 `/derived` 改名） | +| GET | `/api/game-distribution/games/{game_id}/network` | – | `GameDistributionNetworkResponse`（整棵改编树） | 公开（原 `/lineage` 改名） | +| GET | `/api/game-distribution/games/{game_id}/source`（`/package` `/project`） | – | `GameDistributionSourceResponse` / 二进制 | Bearer（原路径改名） | +| GET | `/api/game-distribution/games/{game_id}/network/stats` | – | `GameDistributionNetworkStatsResponse`（子树归集） | Bearer（原路径改名） | - `POST /games` 首次发布只强制 `project_key`，`game_id` 由 `derive_game_distribution_game_id(owner, project_key)` 派生； **首版号固定为 `1`**（版本身份只在