Genarrative/local-docs/【阶段验收】Issue226阶段6交接与最终门禁-2026-09-02.md

Issue #226 阶段 6：#225 交接与最终门禁验收记录

更新时间：2026-09-02 实施范围：#226 添加客户端特殊标识 交接范围：#225 添加客户端埋点统计 执行结论：阶段 6 通过；#226 客户端实现、跨 origin 重定向安全复审、边界回归、交接材料和最终门禁已收口。未修改 #225 主站代码、数据库、OpenAPI 或后台实现。

1. 阶段边界

本阶段只完成：

1. 复核并固定交给 #225 的 Header、tracking metadata、认证主体和路径边界。
2. 汇总阶段 1～5 的正向、负向和语义回归证据。
3. 执行最终定向测试、编码/格式/空白检查和工作树检查。
4. 更新实施方案与分阶段计划的完成状态。

本阶段明确不做：

• 不修改 server-rs、主站 tracking middleware、route tracking 或后台。
• 不修改 SpacetimeDB tracking_event schema、migration、bindings 或索引。
• 不修改 External v1 OpenAPI、DTO 或请求响应语义。
• 不执行真实发布环境线上写入或埋点验证。

2. 当前仓库状态

阶段 6 开始时：

项目	结果
分支	feat/agc_call_header
HEAD	8059bbcb5（已合并最新 origin/master）
工作树	干净
origin/master	4a2f5be6c，同步 AGC 更新下载域名门禁

阶段 0～5 的提交保持不变，本阶段只补充交接/验收文档。

3. 给 #225 的固定交接契约

3.1 客户端请求标记

X-Genarrative-Client: agc

• Header 名大小写不敏感；值精确为小写 agc 时识别为 AGC。
• 缺失、空值或未知值按未标记处理，不拒绝请求，也不改变业务行为。
• Header 只用于来源审计和统计，不参与鉴权、权限、计费或账号归属。
• 不记录 access token、API Key 明文、签名 URL、项目绝对路径、用户隐私或客户端版本号。

3.2 tracking metadata

第一阶段复用现有 tracking metadata_json，固定 JSON key/value：

{
  "route": "/api/editor/images/generations",
  "method": "POST",
  "status": 202,
  "operation": "generateExternalEditorImage",
  "client": "agc"
}

约定：

• client key 固定；AGC 值固定为 agc。
• Header 缺失时不写 client 空字符串。
• 记录主站实际收到的 method/path，不只记录客户端账本中的 External v1 endpoint。
• /api/external/v1/* 不能因为缺少完整 route spec 而漏记。

3.3 认证主体

• 登录账号态：沿用主站现有 access token 解析出的用户维度。
• External API Key 态：使用 ExternalApiPrincipal.owner_user_id，必要时保留 key_id 维度。
• Header 与认证主体独立处理；不能用 Header 代替认证，也不能从 generationInputs.source 推导客户端标记。

3.4 路由和边界

应识别的主站请求：

• 账号态 /api/auth/*、/api/profile/*、/api/assets/*、/api/editor/*、/api/runtime/*。
• External API Key 态 /api/external/v1/*。
• 生成提交、异步轮询、项目/素材/资源登记和 /api/assets/read-url 换签。

明确不应识别为 AGC 主站业务请求：

• OSS multipart 上传。
• 签名 URL/OSS 媒体下载。
• LLM/Codex Provider。
• AGC 受控搜索。
• loopback 工具桥。
• 更新清单、更新包下载和任意外部网页请求。

4. 最终门禁结果

验收项	命令/证据	结果
TS 统一出口正向测试	npm exec vitest run apps/ai-game-creator-shell/tests/clientHttp.test.ts	通过，14 tests passed
AGC TS 类型和配置检查	npm run ai-game-creator-shell:typecheck	通过；skill-pack/config 检查通过
Rust 主站 Client factory、请求终结器与 origin-safe redirect policy	cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml http_client -- --nocapture	通过，8 tests passed；同源跟随、跨 origin 阻断、链式重定向、显式 Policy::none() 和请求级同名 Header 覆盖均覆盖
第三方请求负向矩阵	cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml omits_agc_marker -- --nocapture	通过，4 tests passed
loopback 认证/请求边界	cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml loopback_proxy_strips_false_codex_limit_headers_and_requires_bearer -- --nocapture	通过，1 test passed
账号态主站请求捕获	cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml background_agent_runtime_can_generate_platform_art_asset -- --nocapture	通过，1 test passed
External Key 态和自定义 origin	cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml sync_canvas_project_assets_with_developer_key_uses_external_route_and_marker -- --nocapture	通过，1 test passed
read-url 与签名下载边界	cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml sync_canvas_project_assets_downloads_external_resources -- --nocapture	通过，1 test passed
结果未知/幂等语义	cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml generation_submit_response_loss_is_not_retried -- --nocapture	通过，1 test passed
Rust 格式	cargo fmt --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -- --check	通过
中文编码	npm run check:encoding	通过，5653 个文件
Diff 空白	git diff --check	通过

Rust 测试输出包含仓库既有的 unused/dead-code warning；本任务相关测试均无 error 或 failure。

5. 发布环境限制与后续交接

本阶段没有执行真实发布环境线上 smoke。账号态和 External Key 态的路径、Header、认证/幂等语义来自本地 mock/custom apiBaseUrl fixture；OSS/签名 URL/Provider/搜索/loopback/更新下载边界来自本地请求捕获；跨 origin 重定向来自双 listener 和链式重定向 fixture。发布前或 #225 联调时，应由主站侧补做真实环境 Header 接收、tracking metadata 写入和后台查询验证，不要求客户端回改本次设计。

6. 可直接粘贴到 #225 的评论

#226 客户端侧已完成并冻结交接契约：AGC 主站业务请求统一发送 X-Genarrative-Client: agc。账号态 /api/auth/*、/api/profile/*、/api/assets/*、/api/editor/*、/api/runtime/* 与 External API Key 态 /api/external/v1/* 均覆盖；OSS/签名下载、Provider、受控搜索、loopback、更新下载和外部网页请求不带该标记。主站可按实际 method/path 读取 Header，并在现有 tracking metadata_json 中写入 client: "agc"；Header 缺失/空值/未知值按未标记处理且不拒绝请求。登录态按真实用户维度记录，External Key 态按 owner_user_id（必要时 key_id）记录，不记录 token/API Key 明文或签名 URL。客户端正向、负向、账号态、External Key 态和幂等回归均已通过，#225 不需要让 #226 回改设计。`