docs(游戏共创): M2b 文档回填两处实现偏差 + 状态改已实现（含 M2b 证据表）
- 技术方案 §3.4：上行路由行按端到端实测补两条按实现为准的细节——① **非作者上传返回 404 而不是 403**（`load_owner_version_or_404` 把 owner 不匹配按「版本不存在」处理，与发行包上行族同口径，不泄露版本存在性、响应不含对象键）；② **阶段门先判「已存在」再判档位**（`ensure_project_bundle_uploadable`：`project_bundle_bytes > 0` → 409 `PROJECT_BUNDLE_ALREADY_EXISTS`，再看 `status` → 409 `PROJECT_BUNDLE_UPLOAD_NOT_ALLOWED`），因此「已公开且已有工程包」返回 `ALREADY_EXISTS`，「已公开但无工程包」才返回 `UPLOAD_NOT_ALLOWED`。证据：`check-game-distribution-project-bundle-e2e` 的 A5 / A5b / A6 及其 NOTE - 技术方案 §3.5.2：AGC 侧「上传」「下载与建项」由「接线待做」改为**已落地**（发布时上传且失败不阻断、按 `source` 分支建项、来源记录 v2 兼容 v1、取件提示按形态措辞），并写明两端规则由 `npm run check-project-bundle-policy-parity` 机器门禁钉住一致 - 技术方案 §3.5.4：路线 B 由「服务端已实现、客户端接线待做」改为**两端均已落地** - 技术方案 §3.7：补 M2b 口径——共创写入仍复用 `game-distribution:publish`（未新增灰度键）；内容下发与工程包上传当前只有 `tracing` 日志，三个结构化埋点事件**仍未接**（待产品定事件口径） - 技术方案新增 §5.2「M2b（工程源包）实施证据」表：三列与契约、校验器（16 条单测 / 上限镜像）、上行路由族（api-server 60 passed）、下行优先与缓存不串味、端到端 `check:game-distribution-project-bundle-e2e` **46/46**、两端规则 parity 门禁、客户端 vitest 1961 passed 与定向 cargo test 17+16；并显式登记「backfill 明确不做」「真实极端边界与结构化埋点待补」 - 里程碑「作品工程源包与一键改造」：Status → `implemented-local`；新增「实现进展（2026-10-05）」列出两端提交 SHA 与证据命令、以及四条未做项及原因；验收标准改为 ✅/⏳/⏭ 三段并有证据指向（阶段门顺序、非作者 404、半包清理等按实测更新）；证据要求补上已落地的命令清单与「真机建项链路仍未跑」的括注 - 门禁：`check:doc-index` 248 份 OK；`check:encoding` 5304 files OK；`git diff --check` 0
This commit is contained in:
@@ -3,7 +3,7 @@
|
||||
| 字段 | 值 |
|
||||
| ----------- | ----------------------------------------------------- |
|
||||
| Version | 1.2 |
|
||||
| Status | in-progress（**服务端已落地**：三列 + 工程包校验器 + 上行/下行路由族；AGC 侧确定性打包器已落地，**上传与建项接线待做**） |
|
||||
| Status | implemented-local（**两端均已落地**：服务端三列 + 校验器 + 上行/下行路由族；AGC 侧打包器 + 上传 + 取件建项 + 来源记录 v2；端到端脚本 46/46、规则 parity 门禁 OK。未跑项见验收标准里的 ⏳） |
|
||||
| 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） |
|
||||
|
||||
@@ -40,23 +40,33 @@
|
||||
- 客户端已有的「从包安装并建项」基座与包内容门禁可直接复用；本里程碑不新建第二套解压或建项路径。
|
||||
- 决策：产品已同意引入工程源包，且**不设**独立的「源码可见性」授权位（口径见文首）。
|
||||
|
||||
## 实现进展（2026-10-05）
|
||||
|
||||
- 服务端：块 A `c6bd2c081`（三列 + 契约 + 绑定）、块 B `9403a47c0`（工程包校验器）、块 C+D `d061b2e37`（上行 5 条路由 + 下行优先 + 缓存资产维度）；文档块 E `3aa145d91`。
|
||||
- 客户端：`4d070dd1a`（规则对齐 + `check-project-bundle-policy-parity` 机器门禁）、`5dd9d1c5d`（发布时上传，失败不阻断）、`72f08c264`（取件按 `source` 分支建项 + 来源记录 v2 兼容 v1）、`da24dd5be`（取件提示按形态如实措辞）；`ff763abe5`（端到端验收脚本）。
|
||||
- 证据：`npm run check:game-distribution-project-bundle-e2e` **46/46**；`npm run check-project-bundle-policy-parity` OK；`cargo test -p module-game-distribution` 69 passed（含校验器 16）；`cargo test -p api-server game_distribution` 60 passed；AGC `vitest` 1961 passed、定向 `cargo test` 17 + 16 passed。
|
||||
- **未做（含原因）**：① 已公开版本的补传（backfill）——按产品口径不做，阶段门与发行包确认一致；② 真实 >200 MiB / 10 001 条目 / 极端半包续传边界——未测（成本高，靠常量单测钉住）；③ AGC 真机取件→建项链路——未跑（需要真机客户端窗口）；④ 结构化埋点事件——未接（待产品定事件口径）。
|
||||
|
||||
## 验收标准
|
||||
|
||||
> 标注：✅ = 服务端已完成并有单测/门禁证据（本地）；⏳ = 待客户端接线或真实栈（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] ✅ 工程包校验器拒绝清单齐备：绝对路径、`..`、盘符、反斜杠、通配符、符号链接、加密条目、嵌套 `.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 条校验器单测 + `check-project-bundle-policy-parity`（客户端打包器与它逐项对齐）。
|
||||
- [x] ✅ 同一版本重复确认同一工程包不产生第二份对象（同内容幂等重放）；换内容重传按冲突拒绝（409 `同一版本已存在不同的工程源包`）。证据：模块事务 + `check-game-distribution-project-bundle-e2e` A4。
|
||||
- [x] ✅ 阶段门：只有 `awaiting_upload` / `upload_failed` 可写；已上传、验证中、待审核、已拒绝、已公开、已撤回、已取消一律拒绝。**顺序按实现**：「已存在工程包」先判（409 `PROJECT_BUNDLE_ALREADY_EXISTS`），故「已公开且已有工程包」返回 `ALREADY_EXISTS`；「已公开但无工程包」才返回 `UPLOAD_NOT_ALLOWED`。证据：e2e A5 / A5b + api-server 单测。
|
||||
- [x] ✅ 非作者上传 → **404**（按「版本不存在」处理，与发行包上行族同口径，不泄露版本存在性），未带 Bearer → 401。证据：e2e A6 + 路由级 401 单测。
|
||||
- [x] ✅ 上行整包 PUT（`application/octet-stream`）+ 服务端独立复核 + 失败 422 `PROJECT_BUNDLE_VALIDATION_FAILED` 且清理半包对象。证据：e2e（整包/校验失败/清理）+ 单测。
|
||||
- [x] ✅ 下行优先级：同一版本同时有两种资产时 `fork-source` 返回 `source: "project"` 且 `downloadPath` 指向 `/fork-source/project`；只有成品包时回落 `package`；「字节数 > 0 但摘要为空」的半写行回落 `package`（失败关闭）；两条下载路径共用同一个校验函数，请求 project 而实际没有工程包时 409 而非静默回落。
|
||||
- [x] ✅ 两种资产的读取缓存不串味（缓存键即对象键，键名分别以 `.zip` / `.project.zip` 结尾）。
|
||||
- [x] ✅ 未上传工程包不阻断发布与审核（上传是独立可选资产，不参与版本状态机）；无工程包的作品仍能拿到成品包。
|
||||
- [ ] ⏳ 上传中断后可按权威偏移续传（分片路由已实现，客户端接线与真实栈验证待做）。
|
||||
- [ ] ⏳ 客户端在真实环境中完成源码工程形态建项：新项目可打开、可编辑源码、可试玩、可重跑构建并发布。
|
||||
- [ ] ⏳ 通过源码路径发布的作品，其来源、代际与根与成品包路径完全一致（服务端共用同一套血缘，真机验证待做）。
|
||||
- [ ] ⏳ 界面如实告知：未上传时改造能力止于「试玩 + 素材参考（不能直接重新发布）」。
|
||||
- [x] ✅ 两种资产的读取缓存不串味（缓存键即对象键，键名分别以 `.zip` / `.project.zip` 结尾）。证据：api-server 单测（对象键互不相等 + `ReleasePackageCache` 双资产各自取回）。
|
||||
- [x] ✅ 未上传工程包不阻断发布与审核（上传是独立可选资产，不参与版本状态机）；无工程包的作品仍能拿到成品包；未上传时面板如实提示「只能被他人试玩与参考」。证据：客户端发布链路改动 + 面板文案测试（真机窗口仍未看，见下条）。
|
||||
- [ ] ⏳ 上传中断后按权威偏移续传的**真实**验证：分片路由与客户端续传逻辑均已落地，但未跑真实断点/乱序场景。
|
||||
- [ ] ⏳ AGC **真机**取件 → 建项链路：客户端按 `source` 分支建项与来源记录 v2 已落地并有单测，但未在真机窗口里跑过「取件 → 解压 → 建项 → 可编辑/可试玩/可发布」整链。
|
||||
- [ ] ⏳ 通过源码路径发布的作品，其来源、代际与根与成品包路径完全一致（服务端本就用同一套血缘，真机验证待做）。
|
||||
- [ ] ⏳ 真实极端边界：>200 MiB 压缩包、>10 001 条目、极端压缩比在**真实上传链路**上的表现（当前靠常量单测与门禁钉住，未在真实栈压测）。
|
||||
- [x] ⏭ 已公开版本的**补传（backfill）**：按产品口径**不做**（阶段门与发行包确认一致，公开后不接受内容写入）。原验收项已从本节移除，改为本行显式记录。
|
||||
|
||||
## 证据要求
|
||||
|
||||
- 自动化：打包排除规则与体积上限的客户端定向测试、上传确认与冲突用例、服务端门禁与鉴权拒绝用例、来源优先级与标注用例、DTO 一致性与 schema 检查、编码与文档索引检查。
|
||||
- 运行时：真实 api-server + 真实对象存储 + 真实客户端跑通「拿到源码 → 改核心逻辑 → 试玩 → 发布 → 溯源与代际正确」，附对比截图或录屏。
|
||||
- 自动化（已落地的命令）：`npm run check:game-distribution-project-bundle-e2e`（**46/46**）、`npm run check-project-bundle-policy-parity`（两端规则一致）、`cargo test -p module-game-distribution`（69 passed，含校验器 16）、`cargo test -p api-server game_distribution`（60 passed）、AGC `npx vitest run apps/ai-game-creator-shell/tests`（1961 passed）与定向 `cargo test -- fork|project_bundle`（17 + 16 passed）、DTO parity 与 schema/编码/文档索引门禁。
|
||||
- 运行时：真实 api-server + 真实对象存储 + 真实客户端跑通「拿到源码 → 改核心逻辑 → 试玩 → 发布 → 溯源与代际正确」，附对比截图或录屏。**（取件 → 建项链路的真机窗口验证仍未跑，见验收标准 ⏳）**
|
||||
- 边界：越权下载、无授权下载、来源已下架、摘要不符、超限包、解压失败、上传中断续传、账号切换后的迟到响应、同版本双来源优先级。
|
||||
|
||||
Reference in New Issue
Block a user