项目快照按渠道分区，后台项目工程支持渠道筛选与游标分页

项目快照对象键升级为 agc/project-snapshots/v2/{channel}/{user}/{project}/，渠道取部署配置 GENARRATIVE_AGC_PROJECT_SNAPSHOT_CHANNEL（缺省沿用客户端下载渠道），非法渠道在写入处失败关闭后台新增渠道列表接口，项目工程列表与下载接受 channel，游标绑定渠道并拒绝跨渠道复用后台项目工程用户列改为素材查询口径：昵称 + 陶泥号 + 用户详情入口，由 api-server 解析作者信息后台项目工程改为游标分页：每页 20/50/100、上一页/下一页与当前页提示，翻页失败保留当前页部署环境示例补充快照渠道配置，并同步运维、技术方案、里程碑与决策记录文档
2026-09-21 16:57:16 +08:00
parent 8520b50c81
commit 4951b71d71
20 changed files with 874 additions and 140 deletions
@@ -23,7 +23,7 @@

 - [ ] 正式项目窗口可被同步调度识别；周期与关闭触发保持有界，失败有项目级诊断。
 - [ ] 未单独配置快照目标时仍使用 agc-dev，只复用资源存储凭据；显式快照目标保持有效，不迁移现存对象。
- [ ] 后台列表显示项目名/ID、用户 ID、同步时间、文件数、体积和完整性，支持刷新与分页。
+- [ ] 后台列表按部署渠道查询，显示项目名/ID、用户（昵称 + 陶泥号）、同步时间、文件数、体积和完整性，支持刷新与游标分页（每页 20/50/100 + 上一页/下一页）。
 - [ ] ZIP 按清单还原相对路径；不含对象存储摘要目录；空文件可上传与导出。
 - [ ] 清单名称/完整性变化在无内容差异时也提交，partial 可恢复 ready，历史缺字段不冒充 ready。
 - [ ] 缺失、损坏、越界路径和非完整清单失败关闭；历史未声明完整性的清单明确标记，允许导出已有文件但不称为完整工程。
@@ -1,5 +1,16 @@
 # 决策记录

+## 2026-09-21 项目快照按部署渠道分区，后台按渠道查看并按素材查询口径展示用户
+
+- 背景：AGC 项目快照此前统一写在 `agc/project-snapshots/v1/{user}/{project}/`，而开发与正式两套部署共用同一个 bucket（都默认 `agc-dev`）。结果是渠道混在一层前缀里：正式后台会列出开发渠道上传的项目，列表上也看不出项目属于哪个渠道；同时“项目工程”列表只有裸用户 ID，且用“加载更多”逐段追加，翻页与定位都困难。
+- 决策（存储）：对象键升级为 `agc/project-snapshots/v2/{channel}/{user}/{project}/`。渠道是**部署渠道**，由服务端 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_CHANNEL` 决定（缺省沿用 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL`，当前缺省 `dev`），客户端不上报渠道、也不需要发新版；渠道名必须是小写字母开头的 `[a-z0-9-]{1,32}`，非法值在上传与后台查询处失败关闭（`503`/`400`），不悄悄回落。正式部署必须在 api-server 环境里显式写 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_CHANNEL=release`。
+- 决策（后台）：新增 `GET /admin/api/project-snapshots/channels` 返回本部署渠道与远端已存在渠道的并集；列表与下载接口都接受 `channel`（缺省本部署渠道），游标里带上渠道并在解码时校验一致，跨渠道复用游标一律 400。页面顶部提供“渠道”选择框，切换渠道回到第 1 页。
+- 决策（列表形态）：“用户 ID”列改为与“素材查询”同口径的“用户”列——昵称 + 陶泥号 + 用户详情入口，昵称/陶泥号由 api-server 用 `resolve_work_author_by_user_id` 解析（账号不可读时回退占位作者），原始 `userId` 不再直接铺在列里；“加载更多”改为游标分页（每页 20/50/100 + 上一页/下一页 + 当前页），前端按页记录游标链，换令牌或换每页条数从第 1 页重来；翻页失败保留当前页。
+- 原因：渠道属于“这套部署服务哪个客户端渠道”，客户端正式包按构建渠道连接不同平台服务（release → 正式站，dev → 开发站），所以服务端是唯一可靠的渠道来源；把渠道放进对象键第一层，既不需要迁移历史对象就能让两套部署互不可见，也让后台的渠道维度天然对齐存储布局。
+- 影响范围：`server-rs/crates/platform-oss/src/{lib.rs,project_snapshots.rs,template_library.rs,examples/agc_project_snapshot_live_smoke.rs}`、`server-rs/crates/api-server/src/{config.rs,project_snapshots.rs,admin_project_snapshots.rs,modules/admin.rs}`、`server-rs/crates/shared-contracts/src/admin.rs`、`apps/admin-web/src/{api/adminApiClient.ts,api/adminApiTypes.ts,pages/AdminProjectSnapshotsPage.tsx,pages/AdminProjectSnapshotsPage.test.tsx,styles/admin.css}`、`deploy/env/api-server.env.example` 与本仓运维/技术文档。
+- 未迁移的历史对象：`agc/project-snapshots/v1/` 下现存对象（只读核对过的两份历史清单）保留在 OSS，但不再写入、不再进入后台列表；需要取回时按旧前缀在 OSS 侧直接读取，确实要在后台看到时再单独开一个只读兼容视图。
+- 验证方式：`cargo test -p platform-oss snapshot` 7 passed（渠道校验、键布局、v2 根渠道枚举、v1 历史键仍必须私有）；`cargo test -p api-server project_snapshot` 18 passed/1 ignored（渠道失败关闭、游标跨渠道拒绝、用户昵称/陶泥号解析、归档与配额回归）；`cargo test -p api-server protected_route_matrix`、`route_contract` 通过（新路由纳入后台鉴权矩阵）；`npm run admin-web:typecheck` 与 `npx vitest run apps/admin-web/src` 202 passed。
+
 ## 2026-09-21 模板正文目录门禁：CLI 打包与后台上传同一份段名单

 - 背景：模板包组织指南把 `.agent/`、`.git/`、`node_modules/`、根目录 `dist/` 等列为「不要放进 ZIP」，但两条发布路径此前只校验路径安全与 `entry` 是否存在，放进去的东西会跟着建到用户项目里（模板自带 `.agent/` 会让新项目继承一个陌生身份）。这条约定只靠作者自觉。
@@ -1783,7 +1783,7 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 - 本地索引是增量对比的唯一依据：`<AppData>/project-snapshots/<projectId>/index.json` 保存上次成功同步的相对路径、校验和、字节数和修改时间。项目根使用现有 manifest 的稳定 `project_id` 作为远端身份，路径不再作为身份。
 - 可观测性按产品口径收敛到本机日志：同步结果、失败分类、延后与跳过计数只写入 AppData 诊断日志（`project_snapshot.sync.*` 前缀），客户端界面不暴露上传状态、时间线或入口按钮。`read_local_project_snapshot_state` 与 `sync_local_project_snapshot` 两条命令仅作为 native-only 的排障与联调入口登记，不在渲染层调用。
 - 远端写入经 `api-server`，客户端只持平台登录态 Access Token。两条登录态路由：`POST /api/agc/project-snapshots/files`（单文件，正文为原始字节，元数据走查询串）与 `POST /api/agc/project-snapshots/manifest`（本次同步后的完整清单）。
- 对象键与清单由服务端决定：文件键为 `agc/project-snapshots/v1/{userId}/{projectId}/files/{sizeBytes}-{checksumDigest}/{relPath}`，清单键为 `agc/project-snapshots/v1/{userId}/{projectId}/manifest.json`。键里带字节数与摘要，因此"对象已存在且长度一致"可以作为内容一致的判据；路径按原始大小写保留，不走 `put_object` 的低位规范化。`agc` 前缀继续是服务端专用私有前缀，通用对象键解析与客户端直传票据都不覆盖它。
+- 对象键与清单由服务端决定：文件键为 `agc/project-snapshots/v2/{channel}/{userId}/{projectId}/files/{sizeBytes}-{checksumDigest}/{relPath}`，清单键为 `agc/project-snapshots/v2/{channel}/{userId}/{projectId}/manifest.json`；`channel` 是本部署渠道（`GENARRATIVE_AGC_PROJECT_SNAPSHOT_CHANNEL`，缺省沿用 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL`），同一 bucket 因此天然按渠道分区，开发与正式部署互不可见对方项目。键里带字节数与摘要，因此"对象已存在且长度一致"可以作为内容一致的判据；路径按原始大小写保留，不走 `put_object` 的低位规范化。`agc` 前缀（含历史无渠道的 `agc/project-snapshots/v1/`）继续是服务端专用私有前缀，通用对象键解析与客户端直传票据都不覆盖它。后台“项目工程”按渠道查询与下载，渠道名非法时失败关闭，历史 v1 对象不再列出。
 - 目标 bucket 使用独立配置 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_BUCKET` / `_ENDPOINT` / `_ACCESS_KEY_ID` / `_ACCESS_KEY_SECRET`，默认 `agc-dev` + `oss-rg-china-mainland.aliyuncs.com`。只允许凭据回退 `ALIYUN_OSS_ACCESS_KEY_ID` / `_ACCESS_KEY_SECRET`；bucket 与 endpoint 不跟随资源存储的 `ALIYUN_OSS_BUCKET` / `_ENDPOINT`，避免默认写入其它 bucket。显式快照目标配置继续优先；不自动搬迁其它 bucket 的现存数据。

 ### 正常、失败、重试与幂等行为
@@ -552,7 +552,7 @@ curl -fsS --max-time 5 http://127.0.0.1/api/editor/showcase/resources >/dev/null

 ### AGC 项目快照上传目标

-后台“项目工程”（`/admin/#project-snapshots`）按项目列出远端快照。完整快照提供“下载完整工程”，按原始目录返回 ZIP；未完成同步的项目暂不可下载，旧清单缺少完整性声明时显示“完整性未知”，只能“下载已存文件”。不要直接把 OSS 的 `files/{size}-{digest}/` 目录下载当成工程。
+后台“项目工程”（`/admin/#project-snapshots`）按项目列出远端快照，默认只看本部署渠道，顶部“渠道”选择框可切换远端已存在的其它渠道；列表按游标分页（每页 20/50/100，上一页复用已取得的游标，远端不给总数所以只显示当前页）。完整快照提供“下载完整工程”，按原始目录返回 ZIP；未完成同步的项目暂不可下载，旧清单缺少完整性声明时显示“完整性未知”，只能“下载已存文件”。“用户”列与“素材查询”同口径展示昵称与陶泥号，并可点开用户详情；不要直接把 OSS 的 `files/{size}-{digest}/` 目录下载当成工程。

 自动上传以原生登记的活动工程为准：打开即首传、每 300 秒周期同步、切换/关闭补传。排障同时核对 AppData `project-snapshots` 索引、`project_snapshot.sync.*` 日志和远端清单；只有测试项目的历史清单不能证明现役项目同步生效。前端在同一窗口内切项目时必须登记生命周期，不能只检查 URL 是否包含 `projectPath`。

@@ -561,15 +561,23 @@ curl -fsS --max-time 5 http://127.0.0.1/api/editor/showcase/resources >/dev/null
 AGC 客户端按周期与项目关闭时机把用户项目增量上传到 `agc-dev`。客户端只持有平台登录态 Access
 Token，经 `POST /api/agc/project-snapshots/files`（单文件原始字节）与
 `POST /api/agc/project-snapshots/manifest`（本次同步清单）交给 `api-server`，由服务端写入私有前缀
-`agc/project-snapshots/v1/{user}/{project}/`；客户端不直连 OSS，也不持有 OSS 凭据。
+`agc/project-snapshots/v2/{channel}/{user}/{project}/`；`channel` 是本部署渠道，客户端不上报渠道、也不直连 OSS，
+因此同一 bucket 可以由开发与正式两套部署分别落在 `dev/` 与 `release/` 下。

 ```env
 GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_BUCKET=agc-dev
 GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ENDPOINT=oss-rg-china-mainland.aliyuncs.com
 GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ACCESS_KEY_ID=
 GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_ACCESS_KEY_SECRET=
+GENARRATIVE_AGC_PROJECT_SNAPSHOT_CHANNEL=dev
 ```

+`GENARRATIVE_AGC_PROJECT_SNAPSHOT_CHANNEL` 未配置时沿用 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL`（缺省 `dev`）；
+正式部署必须显式设成 `release`，否则正式上传会写进 `dev/` 渠道。渠道名必须是小写字母开头的
+小写字母 / 数字 / 连字符（≤32 字符），非法时上传与后台查询都返回 `503`/`400`，不会回落到别的渠道。
+历史无渠道前缀 `agc/project-snapshots/v1/` 只保留对象、不再写入也不再进入后台列表；需要取回历史对象时
+按旧前缀直接在 OSS 侧读取。
+
 专用凭据为空时回退 `ALIYUN_OSS_ACCESS_KEY_ID` / `ALIYUN_OSS_ACCESS_KEY_SECRET`，bucket 与 endpoint
 仍默认指向 AGC 发行 bucket，因此回退凭据必须具备目标 bucket 该前缀的 `PutObject` / `GetObject` /
 `DeleteObject` 权限；`api-server` 启动时会打印一行 `AGC 项目快照 OSS 客户端已启用`（含 bucket、
@@ -578,7 +586,7 @@ endpoint 与凭据来源，不含密钥），凭据缺失或只配一半则跳

 远端占用按当前清单收敛：每次清单写入成功后，服务端用上一版清单反推不再被引用的对象键并删除，单次最多
 回收 2000 个，上一版清单不可读时整轮跳过（不会误删）。因此不需要额外配置 bucket 生命周期来防止无界
-增长；`agc/project-snapshots/v1/` 下同一路径只保留当前内容，历史版本不保留。配额口径：单文件 64 MiB、
+增长；`agc/project-snapshots/v2/{channel}/` 下同一路径只保留当前内容，历史版本不保留。配额口径：单文件 64 MiB、
 单次同步上传预算 512 MiB、单项目常驻 2 GiB；超限分别表现为跳过/延后/413。服务端另有进程内小时配额
 （文件 3000 次、清单 120 次）与同一项目 5 秒最小清单间隔，超限返回 `429` 并带 `Retry-After`。