docs(游戏共创): M2b 文档按实现收敛（块 E）

- 技术方案 §3.2.3：三列语义改为与实现一致；删掉原「保留一次补齐机会」的规则（**已公开版本的补传未实现**，本期不做），改为「只在 `awaiting_upload` / `upload_failed` 可写一次、写入后换内容 409、不做版本回溯」；补产品口径（不做独立「源码可见性」开关、作者不传即产物级改编、`nonCommercial` 约束力属平台规则层面）；对象键改为实现值 `…/{version_id}.project.zip` - 技术方案 §2.3：把「公开后可补传一次工程源包」的表述改为如实口径（公开后不接受补传，只能走试玩 + 素材） - 技术方案 §3.3：version 行的 `project_bundle_*` 迁移规则改为「只在未公开时可写一次」 - 技术方案 §3.4：`PUT /versions/{versionId}/project-bundle` 从「规划」改为**已实现**（整包 + 4 条分片族路由、作者限定、阶段门、无既有工程包、服务端派生对象键）；「登录用户」小节把取件接口从两个改为三个并说明 `source` 可能是 `project`（优先）或 `package`，新增 `/fork-source/project` 本体行（失败关闭、缓存含资产维度） - 技术方案 §3.5.2：打包/服务端复核/上传/下载建项/优先级五条按实现重写——写明服务端 `validate_project_bundle_zip` 的完整拒绝清单与与发行包逐项相等的上限（200 MiB / 500 MiB / 64 MiB / 10 000 / 100，理由：共用同一上传链路且反代按 200 MiB 校准），以及「打包器已落地、上传与建项接线待做」 - 技术方案 §3.5.4：记录产品已采纳推荐口径（A 默认继续服务未上传工程包的作品、B 服务端已实现、C 不做） - 里程碑「作品工程源包与一键改造」：Status → in-progress（服务端已落地 / 客户端接线待做）、Version 1.2；范围去掉「是否公开工程」选项（不存在独立开关）；不在范围内新增「已公开版本补传」；两条前置依赖标注已落地并写清 512 MiB 与 200 MiB 的对齐口径（客户端须按服务端上限预检）；验收标准改为带 ✅/⏳ 标注、删掉两条 backfill 验收、补阶段门与半写行回落等已实现项 - 门禁：`check:doc-index` 248 份 OK；`check:encoding` 5301 files OK；`git diff --check` 0
2026-10-05 15:28:07 +08:00
parent 9403a47c01
commit 3aa145d918
2 changed files with 45 additions and 35 deletions
@@ -2,12 +2,14 @@

 | 字段        | 值                                                    |
 | ----------- | ----------------------------------------------------- |
-| Version     | 1.1                                                   |
-| Status      | proposed（**正解路径**；未拍板前不得实现，见依赖与前置条件） |
-| Date        | 2026-10-03（2026-10-04 标注为正解路径并补前置依赖）    |
-| Parent Spec | `docs/【技术方案】游戏共创与作品Fork-2026-10-03.md`（口径见 §2.5、§3.5.1、§3.5.2、§3.5.4） |
+| Version     | 1.2                                                   |
+| Status      | in-progress（**服务端已落地**：三列 + 工程包校验器 + 上行/下行路由族；AGC 侧确定性打包器已落地，**上传与建项接线待做**） |
+| Date        | 2026-10-03（2026-10-04 标注为正解路径；2026-10-05 按实现更新范围与验收） |
+| Parent Spec | `docs/【技术方案】游戏共创与作品Fork-2026-10-03.md`（口径见 §2.5、§3.2.3、§3.4、§3.5.1、§3.5.2、§3.5.4） |

 > **定位（2026-10-04）**：只读侦察证明成品包路径只能试玩、不能重新发布（见「成品包改造闭环」里程碑的「事实依据」），因此**本里程碑是「一键复刻完整工程」的唯一正解路径**：只有拿到作者随版本上传的工程源包，用户才可能在不重写工程的前提下改核心逻辑并重新发布。技术方案 §3.5.4 的推荐是「路线 A（参考式改编）先行验证需求，路线 B（本里程碑）作为正解排后续」。
+>
+> **产品口径（2026-10-05 已拍板，§3.2.3/§3.5.4）**：**不做**独立的「源码可见性」开关——作品授权非 `forbidden` 时，工程源包与成品包走同一道取件鉴权；作者不想给源码就是**不上传**，「上传与否」本身就是开关。`nonCommercial` 的约束力是**平台规则层面**（源码被取走后无法从技术上阻止商用）。上传与发布/审核解耦：未上传不影响发布。

 ## 目标

@@ -15,15 +17,16 @@

 ## 范围

- 工程源包作为发行版本的可选伴随资产：上传、确认、只读回读与对象存储生命周期。
- 工程源包的内容门禁（与模板包同一套排除规则与体积上限），服务端独立复核。
+- 工程源包作为发行版本的可选伴随资产：上传（整包或分片续传）、确认、只读回读与对象存储生命周期。
+- 工程源包的内容门禁：服务端**独立恢复**（不信任客户端）——与发行包同级的体积/条目上限 + 源码场景项（凭据与隐私文件、依赖与 VCS 目录、根级构建产物与 IDE 目录、嵌套压缩包、符号链接、加密条目）。
 - 改造内容下发入口的来源优先级：同一版本同时存在工程源包与成品包时优先下发工程源包，并如实标注来源类型。
- 客户端：源码工程打包 → 上传（含中断续传）；下载 → 校验摘要 → 解压 → 以源码工程形态建项。
- 发布面板中「是否公开工程」的选择与后果说明（默认不公开）。
+- 客户端：源码工程确定性打包（条目排序 + 固定时间戳）→ 上传（含中断续传）；下载 → 校验摘要 → 解压 → 以源码工程形态建项。
+- 发布面板的工程包上传入口与后果说明：**上传与否是作者唯一的开关**（不做独立的「源码可见性」授权位）；未上传时如实提示「只能被他人试玩与参考」。

 ## 不在范围内

 - 成品包路径的「试玩 + 素材参考」闭环（见「成品包改造闭环」里程碑；本里程碑复用其内容下发入口、血缘声明与建项基座）。
+- **已公开版本的补传（backfill）**：原方案曾设想「公开后可给当前公开版本补传一次工程包」，本期**不做**——上传阶段门与发行包确认一致（只允许 `awaiting_upload` / `upload_failed`），公开后不接受任何内容写入。若产品要这条，需要单独设计（它会是「版本不可变」的例外）。
 - 工程源包的版本回溯（历史版本没有工程包时不为它补做）。
 - 网页端上传工程源码包（首期只支持客户端）。
 - 相似度比对与低改动度判定、收益分成。
@@ -32,23 +35,25 @@

 - 「游戏共创授权与血缘」里程碑已通过验收。
 - 「成品包改造闭环」里程碑已通过验收（内容下发入口、客户端建项基座、发布携带来源、授权面板均在那一里程碑落地）。
- **新增前置依赖 ①（当前不存在，必须在本里程碑内新建）：「工程包下载/授权」接口。** 平台今天**没有**任何「按版本取包」的下载通道——作者侧路由只有 create/upload/chunk/complete/reset/submit/get_owner_version/cancel，作者侧 payload 不回对象键或下载地址（`server-rs/crates/api-server/src/modules/game_distribution.rs:3029-3041`）；对外只有公开发行网关**逐文件**读取且只服务当前已公开版本（`:395-421`、`:800-863`），扩展名受限（`server-rs/crates/module-game-distribution/src/release.rs:36-64`）。工程源包含 `.ts`/`.vue`/`package.json` 等不在白名单内的文件，**无法**靠发行网关拼出来，必须新做受鉴权下载（并设计 Range/续传或分片，现状两侧都是整包进内存：服务端 `:926-958`、客户端 `src-tauri/src/template_library.rs:564-591`）。
- **新增前置依赖 ②：包内禁项必须先定义清楚。** 服务端已拒绝 `node_modules`、`.git`、`.agent`、`.env*`、`*.map`、`*.pem`、`*.key` 与嵌套 `.zip`（`server-rs/crates/module-game-distribution/src/package.rs:135-142`、`:170-176`），且 `node_modules` 不能进包意味着用户拿到源包后仍需本机 `npm install`；本地导出上限 512 MiB 与平台 200 MiB 的上限并不对齐，需要在本里程碑内定口径。
+- **前置依赖 ①「工程包下载/授权」接口——已落地（2026-10-05）**：`GET /games/{gameId}/fork-source` 在有工程包时返回 `source: "project"`，本体的独立路径 `GET /games/{gameId}/fork-source/project` 与成品包共用同一套鉴权与校验函数（不重复实现），**不下发对象键**、只服务当前公开版本、`no-store`。读取复用现役 OSS 读路径，**缓存键含资产维度**（对象键 `…/{version_id}.project.zip` 与 `…/{version_id}.zip` 不同），两份资产不串味。
+- **前置依赖 ②包内禁项与规模上限——已定稿（2026-10-05）**：服务端 `module-game-distribution/src/project_bundle.rs` 的 `validate_project_bundle_zip` 独立复核，拒绝清单与上限见技术方案 §3.5.2。**512 MiB（客户端打包上限）与 200 MiB（服务端/反代放行量）的不对齐按下述口径收敛**：服务端上限与发行包逐项相等（200 MiB / 展开 500 MiB / 单文件 64 MiB / 条目 10 000 / 压缩比 100），因此**客户端在上传前必须按服务端上限预检**（客户端打包器的 512 MiB 只是本机护栏），超限包应在本地就被拦下而不是上传到一半被拒——这一条属客户端待办。
 - 客户端已有的「从包安装并建项」基座与包内容门禁可直接复用；本里程碑不新建第二套解压或建项路径。
- 决策：本里程碑成立的前提是产品同意引入工程源包；若否决，本里程碑取消，改编能力止于「试玩 + 素材」（见「成品包改造闭环」里程碑）。
+- 决策：产品已同意引入工程源包，且**不设**独立的「源码可见性」授权位（口径见文首）。

 ## 验收标准

- [ ] 授权为「禁止共创」时不产生任何工程包上传，也不出现可被他人下载的工程地址。
- [ ] 含被排除目录（版本控制、依赖目录、编辑器与构建产物）或含绝对路径、上级路径、盘符、反斜杠、符号链接、超出条目数或体积上限的工程包在上传确认阶段被拒绝，且不产生任何对象或残留。
- [ ] 同一版本重复确认同一工程包不产生第二份对象；换内容重传按冲突拒绝。
- [ ] 上传中断后可按权威偏移续传，不重放整包、不跳段。
- [ ] 同一版本同时存在两种来源时，下发入口优先返回工程源包并如实标注来源类型；未上传工程包时仍能拿到成品包。
- [ ] 客户端在真实环境中完成源码工程形态建项：新项目可打开、可编辑源码、可试玩、可重跑构建并发布。
- [ ] 通过源码路径发布的作品，其来源、代际与根与成品包路径完全一致，不产生第二套血缘语义。
- [ ] 工程包未上传或上传失败不阻断发布，但界面必须明确告知改造能力被降到「试玩 + 素材参考」（成品包路径，不能直接重新发布）。
- [ ] 作品公开后提升授权，可对**当前公开版本**补传工程包一次；补齐后改造路径升级为源码级，无需作者发新版本。
- [ ] 再次补传、换内容重传被拒绝；目标版本不是当前公开版本、或作品授权仍为禁止时，补传同样被拒绝；历史版本不会被补齐。
+> 标注：✅ = 服务端已完成并有单测/门禁证据（本地）；⏳ = 待客户端接线或真实栈（dev 栈端到端）验证。
+
+- [x] ✅ 工程包校验器拒绝清单齐备：绝对路径、`..`、盘符、反斜杠、通配符、符号链接、加密条目、嵌套 `.zip`、完全重复/大小写折叠重复路径、任意层级 `node_modules` / `.git` / `.svn` / `.agent`、根级 `dist` / `build` / `library` / `temp` / `local` / `.idea` / `.vscode`、凭据与隐私文件（`.env*`、`*.pem`、`*.key`、`*.p12`、`*.pfx`、`.npmrc`、`.netrc`、`.git-credentials`、`id_rsa*`、`id_ed25519*`、`*.map`）、单文件/累计/压缩比超限；合法源码包（**不含** `index.html`）通过。证据：`module-game-distribution` 16 条校验器单测。
+- [x] ✅ 同一版本重复确认同一工程包不产生第二份对象（同内容幂等重放）；换内容重传按冲突拒绝（409 `同一版本已存在不同的工程源包`）。
+- [x] ✅ 阶段门：只有 `awaiting_upload` / `upload_failed` 可写；已上传、验证中、待审核、已拒绝、已公开、已撤回、已取消一律拒绝；已公开版本的**补传不做**（见「不在范围内」）。
+- [x] ✅ 下行优先级：同一版本同时有两种资产时 `fork-source` 返回 `source: "project"` 且 `downloadPath` 指向 `/fork-source/project`；只有成品包时回落 `package`；「字节数 > 0 但摘要为空」的半写行回落 `package`（失败关闭）；两条下载路径共用同一个校验函数，请求 project 而实际没有工程包时 409 而非静默回落。
+- [x] ✅ 两种资产的读取缓存不串味（缓存键即对象键，键名分别以 `.zip` / `.project.zip` 结尾）。
+- [x] ✅ 未上传工程包不阻断发布与审核（上传是独立可选资产，不参与版本状态机）；无工程包的作品仍能拿到成品包。
+- [ ] ⏳ 上传中断后可按权威偏移续传（分片路由已实现，客户端接线与真实栈验证待做）。
+- [ ] ⏳ 客户端在真实环境中完成源码工程形态建项：新项目可打开、可编辑源码、可试玩、可重跑构建并发布。
+- [ ] ⏳ 通过源码路径发布的作品，其来源、代际与根与成品包路径完全一致（服务端共用同一套血缘，真机验证待做）。
+- [ ] ⏳ 界面如实告知：未上传时改造能力止于「试玩 + 素材参考（不能直接重新发布）」。

 ## 证据要求