完成Issue225阶段6验收与交接
更新Issue225实施方案与分阶段验收计划为阶段0至6完成 补充最终门禁、48个定向测试证据与tracking_event落点说明 固化Issue225交付评论和Issue226客户端交接及后续风险记录
This commit is contained in:
@@ -0,0 +1,329 @@
|
||||
# Issue #225：AGC 主站请求标记埋点统计实施方案
|
||||
|
||||
更新时间：2026-09-02
|
||||
关联 Issue：
|
||||
|
||||
- `#225 添加客户端埋点统计`：本文全部实施范围
|
||||
- `#226 添加客户端特殊标识`：客户端侧已完成；本文只接收其固定交接契约，不回改客户端
|
||||
|
||||
当前状态：阶段 0～6 已完成。主站生产代码和定向测试已按阶段提交；阶段 6 仅补充最终门禁、交接与验收文档。未修改 SpacetimeDB schema、OpenAPI 或后台页面。
|
||||
|
||||
## 1. 一句话交付结果
|
||||
|
||||
主站 `api-server` 能识别 AGC 发来的 `X-Genarrative-Client: agc`，并在现有成功路由埋点写入 `tracking_event.metadata_json` 的 `client: "agc"`，同时按真实登录用户或 External API Key 的 `owner_user_id` 归属，后台可以通过现有 tracking 事件查询看到这类请求；不改变鉴权、计费、幂等、响应和现有统计口径。
|
||||
|
||||
## 2. Issue 边界
|
||||
|
||||
### 2.1 本次只做 #225
|
||||
|
||||
本次主改动限定在主站后端：
|
||||
|
||||
- `server-rs/crates/api-server/src/app.rs` 的 tracking middleware 入口。
|
||||
- `server-rs/crates/api-server/src/tracking.rs` 的标记识别、主体归属、metadata 合并和 route tracking 覆盖。
|
||||
- 必要的 `api-server` 定向测试、External v1 路由测试和后台 tracking 读取验证。
|
||||
- 方案、验收、交接文档。
|
||||
|
||||
### 2.2 本次不做 #226 的回改
|
||||
|
||||
不修改：
|
||||
|
||||
- AGC TS 的 `fetchClientHttp` 标记注入。
|
||||
- AGC Rust 主站 Client factory、请求终结器和 redirect policy。
|
||||
- AGC 主站/第三方请求边界、timeout、认证、幂等和请求体语义。
|
||||
|
||||
`#226` 已冻结并合入的客户端契约直接作为本 Issue 的输入。
|
||||
|
||||
### 2.3 明确不做项
|
||||
|
||||
- 不新增 `tracking_event` 列、索引、migration 或生成 bindings；第一阶段复用已有 `metadata_json`。
|
||||
- 不新增平行的 `agc_client_request` 事件、平行表或平行统计口径。
|
||||
- 不改变 `/api/external/v1` 的路由、HTTP 方法、DTO、状态码、鉴权或异步语义，因此不改 OpenAPI 契约。
|
||||
- 不把 `generationInputs.source`、User-Agent、请求体中的 owner 字段当作客户端来源或主体。
|
||||
- 不记录 access token、External API Key 明文、Cookie、签名 URL、项目绝对路径或其他秘密。
|
||||
- 不把 OSS 上传、签名 URL 实际下载、LLM/Codex Provider、受控搜索、loopback、更新下载和任意外部网页请求当成主站业务 tracking。
|
||||
- 不默认把失败响应改造成新的 tracking 事实；先保持现有“成功响应才写 route tracking”语义。
|
||||
- 不默认新增后台筛选控件；后台先复用现有 tracking 原始事件查询展示 `metadata_json`。
|
||||
|
||||
## 3. 当前实现基线与缺口
|
||||
|
||||
### 3.1 现有 tracking 流程
|
||||
|
||||
当前全局链路位于：
|
||||
|
||||
- `server-rs/crates/api-server/src/app.rs`
|
||||
- `server-rs/crates/api-server/src/tracking.rs`
|
||||
|
||||
流程为：
|
||||
|
||||
```text
|
||||
请求进入
|
||||
→ tracking middleware 保存 method/path
|
||||
→ next.run(request)
|
||||
→ 从 response extensions 读取认证主体
|
||||
→ 仅对成功响应解析 RouteTrackingSpec
|
||||
→ 生成 TrackingEventDraft.metadata
|
||||
→ 本机 tracking outbox
|
||||
→ SpacetimeDB tracking_event / tracking_daily_stat
|
||||
```
|
||||
|
||||
现有 `AuthenticatedAccessToken` 和 `ExternalApiPrincipal` 都会在认证 middleware 成功后写入 response extensions；但 tracking middleware 目前只消费前者。
|
||||
|
||||
### 3.2 当前缺口
|
||||
|
||||
- tracking middleware 尚未读取 `X-Genarrative-Client`。
|
||||
- route metadata 尚未写入 `client`。
|
||||
- External API Key 的 `ExternalApiPrincipal.owner_user_id` 尚未接入 route tracking 归属。
|
||||
- `/api/external/v1/*` 没有完整的 route tracking spec。
|
||||
- 账号态实际被 AGC 使用的 `/api/editor`、`/api/assets`、`/api/runtime` 路径也有未覆盖项。
|
||||
|
||||
## 4. 冻结的 #226 交接契约
|
||||
|
||||
### 4.1 Header 识别
|
||||
|
||||
```http
|
||||
X-Genarrative-Client: agc
|
||||
```
|
||||
|
||||
规则：
|
||||
|
||||
- Header 名按 HTTP 规则大小写不敏感。
|
||||
- 值去除首尾空白后，精确等于小写 `agc` 才认定为 AGC。
|
||||
- 缺失、空值、`AGC`、其他未知值均按“未标记”处理。
|
||||
- 未标记请求不被拒绝，也不改变业务行为。
|
||||
- Header 只用于来源审计和统计，不参与鉴权、权限、计费、幂等或账号归属。
|
||||
|
||||
### 4.2 metadata 形态
|
||||
|
||||
第一阶段复用已有 `tracking_event.metadata_json`，在原对象上追加固定键：
|
||||
|
||||
```json
|
||||
{
|
||||
"route": "/api/editor/images/generations",
|
||||
"method": "POST",
|
||||
"status": 202,
|
||||
"operation": "generateExternalEditorImage",
|
||||
"client": "agc"
|
||||
}
|
||||
```
|
||||
|
||||
约定：
|
||||
|
||||
- JSON key 固定为 `client`，值固定为 `agc`。
|
||||
- 有效标记时追加 `client`；未标记时不写 `client`，不写空字符串或 `null`。
|
||||
- 已有 `route`、`method`、`status`、`operation` 以及资产类嵌套 metadata 必须保留。
|
||||
- `route` 使用主站实际收到的 method/path；External v1 不得只记录客户端账本中的内部映射路径。
|
||||
|
||||
### 4.3 认证主体归属
|
||||
|
||||
| 请求类型 | `user_id` | `owner_user_id` | `scope_kind/scope_id` | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| 登录账号态 | 沿用 `AuthenticatedAccessToken.claims().user_id()` | 沿用现有行为，通常与 user_id 相同 | 沿用 route spec；User scope 使用真实用户 | Header 不能覆盖真实认证主体 |
|
||||
| External API Key 态 | 不伪造登录用户，可为空 | `ExternalApiPrincipal.owner_user_id()` | User scope 使用 owner_user_id | 归属 API Key 所属账号 |
|
||||
| 无认证的公开/站点请求 | 为空 | 为空 | 沿用 Site/公开 route spec | 只在已有公开 route spec 时记录 |
|
||||
|
||||
第一阶段不把 API Key 明文写入 metadata。`key_id` 是安全的内部标识，但只有在后续明确需要按单个 Key 统计或审计时才增加 `externalApiKeyId`，不作为本期客户端交接前提。
|
||||
|
||||
### 4.4 成功与失败语义
|
||||
|
||||
本期先保留当前 route tracking 的成功响应语义：
|
||||
|
||||
- 2xx 成功响应按 route spec 写入 tracking。
|
||||
- 3xx、4xx、5xx 和 transport failure 不因为 AGC 标记而自动新增 route 事件。
|
||||
- 生成提交、异步轮询、重试请求使用同一标记；是否落库仍由现有 route tracking 规则决定。
|
||||
|
||||
如果产品后续要求统计失败调用，应另立失败事件的 event key、幂等键、容量和报表口径，不在本期隐式扩展。
|
||||
|
||||
## 5. 推荐实现：扩展现有 route tracking
|
||||
|
||||
本期采用方案一：在现有 route tracking 上追加来源和主体信息，不创建通用 AGC 请求事件。
|
||||
|
||||
```text
|
||||
请求 Header
|
||||
→ tracking middleware 在 next.run 前白名单解析 marker
|
||||
→ next.run(request)
|
||||
→ 从 response extensions 读取 AuthenticatedAccessToken / ExternalApiPrincipal
|
||||
→ 按实际 method + path 解析 RouteTrackingSpec
|
||||
→ 计算 user/owner/scope
|
||||
→ 在现有 metadata 对象追加 client=agc
|
||||
→ 复用现有 outbox、tracking_event、tracking_daily_stat
|
||||
→ 现有后台 tracking 查询读取 metadata_json
|
||||
```
|
||||
|
||||
### 5.1 为什么不新增通用 AGC 事件
|
||||
|
||||
- 不会与现有 route event 重复计数。
|
||||
- 不会改变 `tracking_daily_stat` 的 event key 和历史统计口径。
|
||||
- 仍能看到实际 path、method、status、operation 和 client 的组合。
|
||||
- 继续复用现有 outbox、SpacetimeDB procedure 和后台原始事件查询。
|
||||
- 新增或确认 AGC 路由时只需补齐 route spec 和测试，不需要引入第二套事件系统。
|
||||
|
||||
代价是 route coverage 必须显式审计；因此阶段 3 将以 AGC 客户端调用清单和 External v1 router/OpenAPI 交叉核对，禁止“标记已经发送但主站没有 route spec”的漏项。
|
||||
|
||||
### 5.2 实现边界
|
||||
|
||||
推荐保持最小抽象：
|
||||
|
||||
- `app.rs` 在消费 request 之前解析 marker，并从 response extensions 取两类主体。
|
||||
- `tracking.rs` 提供小型白名单解析函数和主体归属逻辑。
|
||||
- `build_route_tracking_metadata` 只在有效 marker 时追加 `client`，不重写既有字段。
|
||||
- `record_route_tracking_event_after_success` 继续负责 route spec、outbox 和失败日志策略。
|
||||
- 不把 marker 放进 `RequestContext`，除非阶段 1 证明同一请求的其他统一 tracking 入口确实需要它；避免扩大公共上下文结构。
|
||||
|
||||
## 6. Route 覆盖范围
|
||||
|
||||
### 6.1 必须覆盖的账号态路径
|
||||
|
||||
按 AGC 当前扫描清单，至少核对并覆盖：
|
||||
|
||||
- `/api/auth/*`：当前登录用户查询、refresh、登录入口、发送验证码、手机号登录、logout 等实际调用。
|
||||
- `/api/profile/*`：dashboard、recharge center、recharge order/confirm、wallet ledger、API Key 管理。
|
||||
- `/api/assets/*`：direct-upload-tickets、objects/confirm、read-url、read-bytes 以及 AGC 实际使用的资产操作。
|
||||
- `/api/editor/*`：projects、assets/library、assets/folders、项目 resources、图片/编辑/去背景/图集/角色动画/视频/音效/BGM 生成和轮询相关内部路径。
|
||||
- `/api/runtime/external-generation/jobs/{operationId}`：账号态生成任务轮询。
|
||||
|
||||
已有 route spec 的 event key 和 scope 语义保持不变；新增项使用稳定、可读、与路径/operation 对应的 event key。
|
||||
|
||||
### 6.2 必须覆盖的 External API Key 业务路径
|
||||
|
||||
按 `server-rs/crates/api-server/src/modules/external_api.rs` 和实际 AGC 使用情况核对：
|
||||
|
||||
- `/api/external/v1/assets/direct-upload-tickets`
|
||||
- `/api/external/v1/assets/objects/confirm`
|
||||
- `/api/external/v1/assets/read-url`
|
||||
- `/api/external/v1/editor/projects` 及项目读取/资源登记相关路径
|
||||
- `/api/external/v1/editor/assets/library`、folders、asset CRUD 中实际被 AGC 使用的路径
|
||||
- `/api/external/v1/editor/images/generations`
|
||||
- `/api/external/v1/editor/images/edits`
|
||||
- `/api/external/v1/editor/images/background-removals`
|
||||
- `/api/external/v1/editor/icon-spritesheets/generations`
|
||||
- `/api/external/v1/editor/character-animations/generations`
|
||||
- `/api/external/v1/editor/videos/generations`
|
||||
- `/api/external/v1/editor/audios/sound-effects/generations`
|
||||
- `/api/external/v1/editor/audios/background-music/generations`
|
||||
- `/api/external/v1/generations/{operationId}`
|
||||
|
||||
External v1 路由的 tracking 必须记录外部实际 path，不把它改写成 `/api/editor`、`/api/assets` 或 `/api/runtime`。
|
||||
|
||||
### 6.3 明确排除的 External v1 路径
|
||||
|
||||
以下是公开发现或集成协议入口，不属于普通 AGC 主站业务调用，本期不新增普通 route tracking spec：
|
||||
|
||||
- `GET /api/external/v1/openapi.json`
|
||||
- `GET /api/external/v1/agent-integration.json`
|
||||
- `GET /api/external/v1/skill/SKILL.md`
|
||||
- `GET /api/external/v1/skill.zip`
|
||||
- `POST /api/external/v1/mcp`
|
||||
|
||||
如果未来 AGC 明确接入远程 MCP/Skill，再单独定义集成流量的事件语义，不把它们隐式混入普通业务统计。
|
||||
|
||||
## 7. 数据库与后台承接
|
||||
|
||||
### 7.1 数据库
|
||||
|
||||
沿用现有链路：
|
||||
|
||||
```text
|
||||
TrackingEventDraft.metadata
|
||||
→ RuntimeTrackingEventInput.metadata_json
|
||||
→ tracking outbox
|
||||
→ record_tracking_event procedure
|
||||
→ tracking_event.metadata_json
|
||||
```
|
||||
|
||||
不增加字段、不改 migration、不重新生成 bindings。现有 JSON object 校验足以容纳 `client` 键；`tracking_daily_stat` 继续按原 event key/scope/day 聚合，不按 client 另建统计表。
|
||||
|
||||
### 7.2 后台
|
||||
|
||||
现有后台 tracking 查询已经返回 `metadata_json`，第一阶段只做数据可见性验证：
|
||||
|
||||
- 管理员能在原始事件详情中看到 `client: "agc"`。
|
||||
- 原有 event key、scope、user/owner、日期查询不回归。
|
||||
- 不新增客户端筛选器、导出列或新的后台路由。
|
||||
|
||||
如果后续需要高频按 client 筛选，再评估新增结构化列和索引；那将是独立 schema 变更，不应在本期偷偷引入。
|
||||
|
||||
## 8. 安全与兼容性约束
|
||||
|
||||
- 来源 Header 是可伪造的审计标签，不能当作安全边界。
|
||||
- 主体必须来自已验证的 `AuthenticatedAccessToken` 或 `ExternalApiPrincipal`，不能信任请求体 owner、客户端账本或 Header 中的身份。
|
||||
- 不记录 Bearer token、API Key 原文、Cookie、签名 URL 或请求体中的敏感字段。
|
||||
- Header 缺失/未知时继续走原有业务和 tracking 逻辑，只是不追加 `client`。
|
||||
- metadata 合并必须保留既有资产嵌套字段，不得用新对象覆盖旧 metadata。
|
||||
- outbox 入队、SpacetimeDB 写入失败继续只记录 warning，不阻断主业务响应。
|
||||
- 不修改 route normalization、dynamic id 归一化、event id 幂等或 daily stat 聚合规则。
|
||||
|
||||
## 9. 定向测试方案
|
||||
|
||||
### 9.1 Marker 解析
|
||||
|
||||
表驱动测试覆盖：
|
||||
|
||||
- `X-Genarrative-Client: agc` → `Some("agc")`。
|
||||
- Header 名大小写变化 → 仍识别。
|
||||
- 缺失、空值、首尾空白、`AGC`、未知值 → 未标记。
|
||||
|
||||
### 9.2 Metadata 与主体归属
|
||||
|
||||
- 有效 marker 的账号态成功路由：metadata 含 `client: "agc"`，user_id/owner_user_id 保持真实用户。
|
||||
- 有效 marker 的 External v1 成功路由：metadata 含 `client: "agc"`，owner_user_id 等于 `ExternalApiPrincipal.owner_user_id()`，scope_id 不落到 `anonymous`。
|
||||
- 未标记请求：metadata 不含 `client`。
|
||||
- 请求体伪造 owner 或 marker 不改变主体归属。
|
||||
- metadata 原有 route/method/status/operation 和资产嵌套字段仍存在。
|
||||
|
||||
### 9.3 Route 覆盖
|
||||
|
||||
- 当前 AGC 调用清单中的账号态路径全部能解析到 route spec。
|
||||
- 当前 AGC 使用的 External v1 业务路径全部能解析到 route spec。
|
||||
- `/api/external/v1` 发现、Skill 和 MCP 路径不被普通业务 spec 误收录。
|
||||
- dynamic project/asset/operation ID 仍按现有 normalize 规则归一化。
|
||||
|
||||
### 9.4 持久化与后台读取
|
||||
|
||||
- 构造 tracking event input 后，`metadata_json` 是合法 JSON object 且含 `client`。
|
||||
- outbox 入队/回退直写路径不丢失 `client`。
|
||||
- tracking_event 读回及后台 tracking API 解析不丢失 metadata。
|
||||
- 现有 daily stat、event id 幂等和失败不阻断语义保持不变。
|
||||
|
||||
### 9.5 状态码语义
|
||||
|
||||
至少保留一组回归：
|
||||
|
||||
- 2xx 成功响应写入 route tracking。
|
||||
- 4xx/5xx 不因为 marker 自动新增成功 route event。
|
||||
- 认证失败不伪造 ExternalApiPrincipal 或用户归属。
|
||||
|
||||
## 10. 实施顺序
|
||||
|
||||
1. 阶段 0：确认基线、交接契约、路径边界和不做项。
|
||||
2. 阶段 1：加入 marker 白名单解析，并将解析结果传入现有 route tracking。
|
||||
3. 阶段 2：接入 `AuthenticatedAccessToken` / `ExternalApiPrincipal`，完成 owner/user/scope 归属和 metadata 合并。
|
||||
4. 阶段 3：按 AGC 调用清单补齐账号态与 External v1 业务 route spec，明确排除发现/MCP。
|
||||
5. 阶段 4：验证 outbox、SpacetimeDB `tracking_event` 和现有后台原始查询，无 schema 变更。
|
||||
6. 阶段 5：完成 marker、主体、route 覆盖、状态码、安全和持久化定向测试。
|
||||
7. 阶段 6：执行最终门禁，更新交接材料并把结果回传 Issue #225；不要求 #226 回改。
|
||||
|
||||
## 11. 完成判据
|
||||
|
||||
只有同时满足以下条件，#225 才算完成：
|
||||
|
||||
- 主站精确识别 `X-Genarrative-Client: agc`，未知/缺失值不拒绝请求。
|
||||
- 有效标记进入现有 route tracking metadata，写入 `client: "agc"`。
|
||||
- 已有 route、method、status、operation、资产 metadata 和 event key 语义不丢失。
|
||||
- 登录账号态按真实用户归属，External API Key 态按 `owner_user_id` 归属。
|
||||
- 当前 AGC 实际使用的账号态和 External v1 业务路径均有 tracking spec。
|
||||
- External v1 discovery/Skill/MCP、OSS、签名下载、Provider、搜索、loopback、更新下载不被误纳入普通 AGC 业务统计。
|
||||
- outbox、SpacetimeDB 写入、daily stat、幂等和失败不阻断语义无回归。
|
||||
- 后台现有 tracking 查询可以看到 `metadata_json.client`，无需新增 schema 或页面。
|
||||
- 定向测试和必要的格式/编码/空白检查通过。
|
||||
|
||||
## 12. 评审与提交节奏建议
|
||||
|
||||
建议按阶段分组提交或至少在一个 PR 中保持以下逻辑顺序：
|
||||
|
||||
1. 阶段 0 文档与契约冻结。
|
||||
2. marker 解析、metadata 合并和账号态主体接入。
|
||||
3. External API Key 主体接入与 External v1 route spec。
|
||||
4. 持久化/后台读取验证和定向测试。
|
||||
5. 最终文档、交接评论和门禁记录。
|
||||
|
||||
每个阶段先通过自身验收，再进入下一阶段；不需要等待 #226 再次修改，也不需要先新增数据库字段。
|
||||
@@ -0,0 +1,391 @@
|
||||
# Issue #225：AGC 主站请求标记埋点分阶段实施与验收计划
|
||||
|
||||
更新时间：2026-09-02
|
||||
关联 Issue：
|
||||
|
||||
- `#225 添加客户端埋点统计`：本计划全部实施范围
|
||||
- `#226 添加客户端特殊标识`：客户端已完成；仅作为固定交接输入
|
||||
|
||||
当前状态：阶段 0、阶段 1、阶段 2、阶段 3、阶段 4、阶段 5、阶段 6 已完成。阶段 1～5 的实现已提交：`2296f79fd`、`2a23ba657`、`01159a269`、`c75c61521`、`c5170669e`；日登录埋点构造器回归修复为 `0a06b4988`。阶段 6 仅补充最终验收、交接和门禁文档，不新增生产代码。
|
||||
|
||||
## 1. 交付目标
|
||||
|
||||
主站识别有效的：
|
||||
|
||||
```http
|
||||
X-Genarrative-Client: agc
|
||||
```
|
||||
|
||||
并在已有 route tracking 的 `tracking_event.metadata_json` 中记录：
|
||||
|
||||
```json
|
||||
{
|
||||
"client": "agc"
|
||||
}
|
||||
```
|
||||
|
||||
同时按真实认证主体归属：登录账号态使用 `AuthenticatedAccessToken` 的用户，External API Key 态使用 `ExternalApiPrincipal.owner_user_id()`；不新增平行事件体系，不改鉴权、计费、幂等和 API 契约。
|
||||
|
||||
## 2. 固定不做项
|
||||
|
||||
本计划不修改：
|
||||
|
||||
- AGC 客户端 Header 注入和 Rust Client factory。
|
||||
- `tracking_event` schema、migration、bindings 或索引。
|
||||
- `/api/external/v1` OpenAPI、DTO、HTTP 方法、状态码和鉴权。
|
||||
- 失败请求的全新 tracking 事实。
|
||||
- 公开 discovery、Skill、MCP、OSS、签名下载、Provider、搜索、loopback 和更新下载的普通 AGC 业务统计。
|
||||
- 后台新筛选器或报表页面；第一阶段只复用原始 metadata 查询。
|
||||
|
||||
## 3. 阶段总览
|
||||
|
||||
```text
|
||||
阶段 0 现状基线与交接契约冻结（已完成）
|
||||
↓
|
||||
阶段 1 Marker 解析与 tracking 入口接入
|
||||
↓
|
||||
阶段 2 认证主体归属与 metadata 合并
|
||||
↓
|
||||
阶段 3 账号态 / External v1 route coverage
|
||||
↓
|
||||
阶段 4 tracking_event、outbox 与后台读取验证
|
||||
↓
|
||||
阶段 5 定向测试、安全边界与语义回归
|
||||
↓
|
||||
阶段 6 最终门禁与 #226 交接收口
|
||||
```
|
||||
|
||||
每阶段先通过本阶段验收，再进入下一阶段。阶段 1～6 均只改主站或相关测试/文档，不要求 #226 回改。
|
||||
|
||||
## 4. 阶段 0：现状基线与交接契约冻结
|
||||
|
||||
### 4.1 工作内容
|
||||
|
||||
- 确认当前分支、HEAD、工作树和 `origin/master` 关系。
|
||||
- 核对 `app.rs` tracking middleware、`tracking.rs` route spec、outbox 和 `tracking_event` 写入链路。
|
||||
- 核对 `AuthenticatedAccessToken` 和 `ExternalApiPrincipal` 的 response extension 传播。
|
||||
- 读取 AGC 调用清单和 External v1 router，冻结正向/排除路径。
|
||||
- 固定 Header、metadata、未知值行为、主体归属和成功响应语义。
|
||||
|
||||
### 4.2 阶段边界
|
||||
|
||||
- 不修改生产代码。
|
||||
- 不新增 schema 或后台代码。
|
||||
- 不把 Issue226 的客户端实现重新打开。
|
||||
|
||||
### 4.3 验收标准
|
||||
|
||||
- [x] 当前基线和代码缺口已记录。
|
||||
- [x] `X-Genarrative-Client: agc` 的识别规则已固定。
|
||||
- [x] `metadata_json.client = "agc"` 的落库形态已固定。
|
||||
- [x] 账号态与 External API Key 态的主体归属已固定。
|
||||
- [x] External v1 discovery/Skill/MCP 与第三方边界已列明。
|
||||
- [x] 未修改主站生产代码、schema、OpenAPI 或后台。
|
||||
|
||||
### 4.4 阶段产物
|
||||
|
||||
- [【阶段验收】Issue225阶段0现状基线与边界冻结-2026-09-02.md](C:/projects/narrative/Genarrative/local-docs/【阶段验收】Issue225阶段0现状基线与边界冻结-2026-09-02.md)
|
||||
- 本实施方案。
|
||||
- 本分阶段验收计划。
|
||||
|
||||
## 5. 阶段 1：Marker 解析与 tracking 入口接入
|
||||
|
||||
### 5.1 工作内容
|
||||
|
||||
修改范围限定在 `api-server` tracking 入口及定向测试：
|
||||
|
||||
- 在 `record_api_tracking_after_success` 的 `next.run(request)` 之前读取请求 Header。
|
||||
- 增加白名单解析：首尾空白可清理，值必须精确为小写 `agc`。
|
||||
- 将解析结果传入现有 `record_route_tracking_event_after_success`。
|
||||
- 不把原始未知值、完整 Header、token 或请求体写入日志/metadata。
|
||||
|
||||
### 5.2 阶段验收
|
||||
|
||||
定向单元测试必须证明：
|
||||
|
||||
- 有效 `agc` 能被识别。
|
||||
- Header 名大小写变化仍能识别。
|
||||
- 缺失、空值、`AGC`、未知值均按未标记处理。
|
||||
- 未标记请求仍走原有 route tracking 逻辑，不被拒绝。
|
||||
- 认证、响应状态和现有 request context 行为不变。
|
||||
|
||||
### 5.3 阶段完成判据
|
||||
|
||||
- [x] marker 只在统一 tracking 入口解析一次。
|
||||
- [x] 业务 handler 无需逐个读取 Header。
|
||||
- [x] 尚未接入主体归属和 External v1 route 扩展之外，不发生无关改动。
|
||||
|
||||
### 5.4 阶段 1 实现与验证记录
|
||||
|
||||
- `app.rs` 在 `next.run(request)` 前调用统一 marker 解析函数，并把解析结果传入 route tracking。
|
||||
- `tracking.rs` 只接受 Header 名 `X-Genarrative-Client`（HTTP 名称大小写不敏感）和值 `trim` 后精确等于小写 `agc` 的请求。
|
||||
- 解析结果以内部 `TrackingClientMarker::Agc` 保存到 `TrackingEventDraft`，本阶段不改变 metadata 内容；metadata 合并由阶段 2 完成。
|
||||
- 未标记、未知值和无效 Header 值均得到 `None`，不会写入日志，也不会拒绝请求。
|
||||
- 定向测试：`tracking::tests::tracking_client_marker_accepts_only_trimmed_lowercase_agc` 通过。
|
||||
- `cargo fmt --manifest-path server-rs/crates/api-server/Cargo.toml`、`git diff --check` 通过。
|
||||
- 当前未运行完整 `api-server` 测试套件；现有编译过程已通过，完整测试按阶段 5/CI 统一执行。
|
||||
|
||||
## 6. 阶段 2：认证主体归属与 metadata 合并
|
||||
|
||||
### 6.1 工作内容
|
||||
|
||||
- 从最终 response extensions 读取 `AuthenticatedAccessToken`。
|
||||
- 同时读取 `ExternalApiPrincipal`。
|
||||
- 账号态沿用现有 user_id/owner_user_id 语义。
|
||||
- External API Key 态设置 `owner_user_id = principal.owner_user_id()`，User scope 的 scope_id 使用 owner，避免回退到 `anonymous`。
|
||||
- 在 `build_route_tracking_metadata` 原有 JSON object 上追加 `client: "agc"`，保留原字段和资产嵌套 metadata。
|
||||
- 第一阶段不写 API Key 明文；不新增 `externalApiKeyId`，除非评审明确要求单 Key 统计。
|
||||
|
||||
### 6.2 阶段验收
|
||||
|
||||
- 账号态成功请求的 user_id 与现有 access token 用户一致。
|
||||
- External v1 成功请求的 owner_user_id 与 `ExternalApiPrincipal.owner_user_id()` 一致。
|
||||
- Header 不能覆盖、伪造或替换认证主体。
|
||||
- 有效 marker 时 metadata 含 `client: "agc"`；无效/缺失时不含该键。
|
||||
- `route`、`method`、`status`、`operation` 和已有嵌套字段均保留。
|
||||
- token、API Key 明文和签名 URL 不进入 metadata 或日志。
|
||||
|
||||
### 6.3 阶段完成判据
|
||||
|
||||
- [x] route tracking draft 在两类主体下都能生成正确的结构化归属。
|
||||
- [x] metadata 合并逻辑有独立测试，不能只依赖端到端偶然覆盖。
|
||||
- [x] 不改变 event id、outbox 和 daily stat 逻辑。
|
||||
|
||||
### 6.4 阶段 2 实现与验证记录
|
||||
|
||||
- `app.rs` 从最终 response extensions 同时读取 `AuthenticatedAccessToken` 和 `ExternalApiPrincipal`。
|
||||
- `tracking.rs` 优先使用已验证的 External API Key owner；External API Key 请求不伪造 `user_id`，User scope 的 `scope_id` 使用 `owner_user_id`。
|
||||
- 账号态继续使用 access token claims 的 user id，同时写入 `user_id` 和 `owner_user_id`，保持原有语义。
|
||||
- `build_route_tracking_metadata` 只在有效 marker 时追加 `client: "agc"`，保留 route、method、status、operation 和 asset 嵌套 metadata；无 marker 不写 client。
|
||||
- 定向测试覆盖账号态主体、External API Key owner 优先级、User scope owner 和 metadata 字段保留。
|
||||
- 当前未修改 External v1 route spec、schema、OpenAPI、outbox 或后台页面。
|
||||
|
||||
## 7. 阶段 3：账号态与 External v1 Route Coverage
|
||||
|
||||
### 7.1 工作内容
|
||||
|
||||
以 `local-docs/【扫描清单】AGC客户端主站调用与可标记点-2026-09-01.md` 和 `modules/external_api.rs` 为输入，补齐显式 route spec：
|
||||
|
||||
- 账号态 `/api/auth/*`、`/api/profile/*`、`/api/assets/*`、`/api/editor/*`、`/api/runtime/external-generation/jobs/{id}` 的实际 AGC 路径。
|
||||
- External API Key 态 `/api/external/v1/assets/*`、`/editor/*`、`/generations/{id}` 的实际业务路径。
|
||||
- 生成提交、轮询、项目读取/资源登记、素材库、上传凭证、对象确认、换签读取等当前已确认调用。
|
||||
- 每个新增 spec 固定 event key、module key、scope kind 和动态路径归一化方式。
|
||||
|
||||
同时明确不加入：
|
||||
|
||||
- `/api/external/v1/openapi.json`。
|
||||
- `/api/external/v1/agent-integration.json`。
|
||||
- `/api/external/v1/skill/SKILL.md`、`skill.zip`。
|
||||
- `/api/external/v1/mcp`。
|
||||
|
||||
### 7.2 阶段验收
|
||||
|
||||
- AGC 当前实际调用清单中的每个 method + path 都能解析到 spec。
|
||||
- External v1 记录实际外部 path，不被映射为内部 `/api/editor` 等路径。
|
||||
- 发现/MCP 路径不会误进入普通业务 route tracking。
|
||||
- project/asset/operation 动态 ID 仍按现有规则归一化。
|
||||
- 原有 route spec 的 event key、scope 和统计口径不变。
|
||||
|
||||
### 7.3 阶段完成判据
|
||||
|
||||
- [x] 有一张可审计的“AGC 调用清单 → route spec → event key”矩阵。
|
||||
- [x] 新增路径均有 resolver 测试；未确认的 OpenAPI 潜在路径单独记录，不混入已实现范围。
|
||||
- [x] 没有用 catch-all `agc_client_request` 取代显式 route tracking。
|
||||
|
||||
### 7.4 阶段 3 实现与验证记录
|
||||
|
||||
- `tracking.rs` 补齐当前 AGC 实际使用的账号态 `/api/auth`、`/api/profile`、`/api/assets`、`/api/editor`、`/api/runtime/external-generation/jobs/{id}` 路径。
|
||||
- `tracking.rs` 补齐当前 AGC 实际使用的 External v1 资产、项目、素材库、生成提交和任务轮询路径；External v1 使用独立的实际外部 path 进入 metadata，不映射回账号态内部路径。
|
||||
- 上传票据和对象确认已有详细资产事件，route spec 以 `handled_by_existing_event` 标记为复用现有事件，统一 route tracking 不再重复写入；tracking middleware 将有效 marker 放入 request extensions，由共享资产 handler 将 `client: "agc"` 合并到既有资产 metadata，并补齐实际 route/method/status/operation。
|
||||
- 共享资产事件沿用真实主体：账号态写入 user/owner；External API Key 态只写 `owner_user_id`，不伪造登录 `user_id`，User scope 使用 owner。
|
||||
- 扩展动态路径归一化的静态段白名单，使 project、generation、asset 和 external v1 路径按既有 `{id}` 规则正确匹配；未引入 catch-all AGC 事件。
|
||||
- discovery、agent-integration、Skill、skill.zip 和 MCP 路径没有业务 route spec。
|
||||
|
||||
已执行定向验证：
|
||||
|
||||
```text
|
||||
cargo fmt --manifest-path server-rs/crates/api-server/Cargo.toml -- --check
|
||||
cargo check --locked --manifest-path server-rs/Cargo.toml -p api-server
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server tracking::tests:: -- --nocapture
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server assets::tests::asset_tracking_metadata_receives_only_valid_agc_marker -- --nocapture
|
||||
git diff --check
|
||||
```
|
||||
|
||||
结果：tracking 定向测试 13 个通过，资产 marker/route metadata 与 External owner 归属测试 2 个通过，api-server 编译检查通过。
|
||||
|
||||
## 8. 阶段 4：tracking_event、outbox 与后台读取验证
|
||||
|
||||
### 8.1 工作内容
|
||||
|
||||
- 验证 `TrackingEventDraft.metadata` 经 `build_tracking_event_input` 后仍是合法 JSON object。
|
||||
- 验证本机 tracking outbox 入队和 SpacetimeDB 回退直写都保留 `client`。
|
||||
- 验证既有 `tracking_event` 行和 `tracking_daily_stat` 聚合未改变。
|
||||
- 验证现有后台 tracking API 返回 `metadata_json` 中的 `client`。
|
||||
- 不新增 schema/migration/bindings，不修改后台页面。
|
||||
|
||||
### 8.2 阶段验收
|
||||
|
||||
- AGC 成功事件可在 tracking_event 读回 `client: "agc"`。
|
||||
- unmarked 事件不会被补写 `client`。
|
||||
- owner_user_id、user_id、scope_id、event_key 和 occurred_at 不丢失。
|
||||
- 后台原始事件查询和已有 event key 查询不回归。
|
||||
- `npm run check:spacetime-schema` 不因本阶段产生 schema 变更；若未改 schema，可记录为无需运行。
|
||||
|
||||
### 8.3 阶段完成判据
|
||||
|
||||
- 至少有一条账号态和一条 External Key 态从 tracking draft 到后台读取的完整证据。
|
||||
- 已确认第一阶段不需要新增数据库字段。
|
||||
|
||||
### 8.4 阶段 4 实现与验证记录
|
||||
|
||||
- `api-server` tracking 测试分别构造账号态和 External API Key 态输入，验证 `TrackingEventDraft → build_tracking_event_input` 后 metadata 仍是合法 JSON object，`client: "agc"`、route、status、event key、module、scope 和 user/owner 字段均保留；未标记输入不补写 `client`。
|
||||
- tracking outbox 测试使用 External v1 AGC 事件完成 NDJSON 入队和读取 round-trip，验证 `metadata_json.client`、实际 External v1 route、`owner_user_id` 和“不伪造 `user_id`”均保留。
|
||||
- `spacetime-client` active mapper 测试验证送往生成绑定的 `RuntimeTrackingEventInput` 不丢失 `client`、External owner、scope、event key 和 module；module-runtime 的统一输入校验测试验证 metadata 必须是 JSON object，标记对象可正常通过。由于本地未启动 SpacetimeDB，未把确定性 input/mapper 验证扩大解释为真实远端库 E2E。
|
||||
- 后台 tracking SQL response parser 测试分别覆盖账号态与 External API Key 态，并增加 draft/input → SQL row → parser 组合回归，验证管理员现有原始事件读取能保留 `metadata_json.client`、实际 route 和 user/owner 归属。
|
||||
- 未修改 tracking schema、migration、bindings、outbox 失败回退策略、daily stat 聚合逻辑或后台页面；SpacetimeDB 的实际入库仍复用既有 `record_tracking_event` / `record_tracking_events` procedure，未新增字段。
|
||||
|
||||
已执行定向验证：
|
||||
|
||||
```text
|
||||
cargo fmt --manifest-path server-rs/Cargo.toml --all -- --check
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p module-runtime tracking_input_ -- --nocapture
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server tracking::tests:: -- --nocapture
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server tracking_outbox::tests:: -- --nocapture
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server admin::tests::parse_admin_tracking_events_sql_response_ -- --nocapture
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p spacetime-client tracking_input_mapper_preserves_agc_metadata_and_external_owner -- --nocapture
|
||||
```
|
||||
|
||||
结果：module-runtime 2 个、api-server tracking 15 个、tracking outbox 8 个、后台 readback parser 5 个、spacetime-client mapper 1 个定向测试全部通过；格式检查通过。未运行完整工作区测试和 `npm run check:spacetime-schema`，因为本阶段未修改 schema。
|
||||
|
||||
## 9. 阶段 5：定向测试、安全边界与语义回归
|
||||
|
||||
### 9.1 工作内容
|
||||
|
||||
补齐并运行与改动直接相关的测试：
|
||||
|
||||
- marker 解析表驱动测试。
|
||||
- route metadata 合并测试。
|
||||
- 账号态主体归属测试。
|
||||
- ExternalApiPrincipal owner 归属测试。
|
||||
- External v1 route resolver 覆盖测试。
|
||||
- discovery/MCP 排除测试。
|
||||
- 2xx 记录、4xx/5xx 不新增成功 route 事件测试。
|
||||
- outbox/SpacetimeDB input 和后台 tracking readback 测试。
|
||||
|
||||
CI 已覆盖且与本改动无直接关系的全量测试可交给 CI；本阶段仍必须运行能直接证明本 Issue 契约的 targeted tests。
|
||||
|
||||
### 9.2 阶段验收
|
||||
|
||||
- 有效 marker 正向场景全部通过。
|
||||
- 缺失/空值/未知 marker 负向场景全部通过。
|
||||
- 登录账号态和 External Key 态主体归属均通过。
|
||||
- 未发生鉴权、状态码、幂等、请求体或异步轮询回归。
|
||||
- 测试输出不包含 token、API Key 明文、Cookie、签名 URL 或本地私密路径。
|
||||
|
||||
### 9.3 阶段完成判据
|
||||
|
||||
- 测试矩阵覆盖“标记/未标记 × 账号态/External Key 态 × 已覆盖/排除路由”。
|
||||
- 所有失败都能定位到 marker、主体、route、持久化或后台读取中的具体层。
|
||||
|
||||
### 9.4 阶段 5 实现与验证记录
|
||||
|
||||
- `tracking.rs` 抽出 `should_record_route_tracking` 判定，明确只有 2xx 成功响应且不是已有详细资产事件的路由才进入统一成功 route tracking；4xx/5xx 和上传确认等复用事件均不新增重复成功事件。
|
||||
- 新增 2xx、4xx/5xx 状态矩阵测试，覆盖 `OK / CREATED / ACCEPTED / NO_CONTENT` 与认证、权限、客户端、服务端失败状态。
|
||||
- 新增 `app.rs` 路由回归：带有效 `X-Genarrative-Client: agc` 的未认证业务请求仍返回 `401`，marker 不绕过鉴权，也不改变失败状态。
|
||||
- 新增 route metadata 安全边界测试，确认统一 route metadata 只包含既有 route/method/status/operation 和可选 `client`/资产字段，不出现 authorization、token、API Key、Cookie、签名 URL 或 request body 字段。
|
||||
- 阶段 4 的账号态、External API Key、outbox、后台 readback 和 mapper 测试全部复跑；SpacetimeDB 既有 event-id 幂等回归也通过。未修改鉴权、请求体、异步轮询、event id、daily stat 或失败回退实现。
|
||||
|
||||
已执行定向验证：
|
||||
|
||||
```text
|
||||
cargo fmt --manifest-path server-rs/Cargo.toml --all -- --check
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p module-runtime tracking_input_ -- --nocapture
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p spacetime-client tracking_input_mapper_preserves_agc_metadata_and_external_owner -- --nocapture
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server tracking::tests:: -- --nocapture
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server app::tests::agc_marker_does_not_bypass_authentication_or_change_failure_status -- --nocapture
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server assets::tests::asset_tracking_metadata_receives_only_valid_agc_marker -- --nocapture
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server assets::tests::external_asset_tracking_keeps_owner_without_forging_user -- --nocapture
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server tracking_outbox::tests:: -- --nocapture
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server admin::tests::parse_admin_tracking_events_sql_response_ -- --nocapture
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server admin::tests::tracking_inputs_round_trip_to_admin_readback_for_both_subjects -- --nocapture
|
||||
cargo test --locked --manifest-path server-rs/Cargo.toml -p spacetime-module duplicate_tracking_event_ids_are_treated_as_idempotent_replays -- --nocapture
|
||||
```
|
||||
|
||||
结果：module-runtime 2 个、spacetime-client 1 个、api-server tracking 18 个、app 鉴权回归 1 个、资产 marker/owner 2 个、tracking outbox 8 个、后台 readback 5 个、spacetime-module 幂等 1 个定向测试全部通过；格式检查通过。未运行与本 Issue 无直接关系的完整工作区测试，按约定交给 CI。
|
||||
|
||||
## 10. 阶段 6：最终门禁与 #226 交接收口
|
||||
|
||||
### 10.1 工作内容
|
||||
|
||||
- 汇总阶段 1～5 的测试和 readback 证据。
|
||||
- 更新本方案、验收记录和 Issue #225 评论草案。
|
||||
- 复核 #226 交接契约不需要客户端回改。
|
||||
- 检查 diff、编码、格式、敏感信息和无关文件。
|
||||
|
||||
### 10.2 最终门禁
|
||||
|
||||
按实际改动范围运行：
|
||||
|
||||
- `cargo fmt --manifest-path server-rs/Cargo.toml -- --check`。
|
||||
- `cargo test --locked -p api-server` 的 tracking/External v1 定向测试。
|
||||
- 必要时 `cargo check --locked -p api-server`。
|
||||
- `npm run check:encoding`。
|
||||
- `git diff --check`。
|
||||
- `git status --short`，确认没有构建产物、日志、凭据或无关文件。
|
||||
|
||||
未修改 schema 时不运行 schema 生成；若实现阶段意外需要 schema，必须停在阶段 4 重新确认迁移范围，不能顺手修改。
|
||||
|
||||
### 10.3 阶段完成判据
|
||||
|
||||
- 主站可以在现有 tracking_event metadata 中看到 `client: "agc"`。
|
||||
- 两类认证主体归属正确。
|
||||
- 当前 AGC 实际业务路径无漏记，发现/MCP/第三方边界无误记。
|
||||
- 后台现有查询可读，无需新 schema 或新页面。
|
||||
- 所有必要 targeted tests、格式/编码/空白检查通过。
|
||||
- 向 #225 交付固定 Header、metadata、主体归属、路由覆盖和验证证据；不要求 #226 回改。
|
||||
|
||||
### 10.4 阶段 6 实际执行与结果
|
||||
|
||||
阶段 6 以当前分支 `feat/agc_call_rec`、`HEAD=5aa38d9f3` 为基线；该提交已合并最新 `origin/master`（`8932f0b27`）。本阶段未修改 `server-rs`、SpacetimeDB schema、OpenAPI 或后台页面，只更新验收和交接文档。
|
||||
|
||||
最终门禁结果：
|
||||
|
||||
| 验收项 | 命令/证据 | 结果 |
|
||||
|---|---|---|
|
||||
| api-server 编译 | `cargo check --locked --manifest-path server-rs/Cargo.toml -p api-server` | 通过；仅有仓库既有 dead-code warning |
|
||||
| api-server tracking/资产/后台/outbox 定向测试 | `cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server tracking -- --nocapture` | 通过，43 tests passed |
|
||||
| marker 不绕过鉴权回归 | `cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server app::tests::agc_marker_does_not_bypass_authentication_or_change_failure_status -- --nocapture` | 通过，1 test passed |
|
||||
| module-runtime tracking input | `cargo test --locked --manifest-path server-rs/Cargo.toml -p module-runtime tracking_input_ -- --nocapture` | 通过，2 tests passed |
|
||||
| spacetime-client mapper | `cargo test --locked --manifest-path server-rs/Cargo.toml -p spacetime-client tracking_input_mapper_preserves_agc_metadata_and_external_owner -- --nocapture` | 通过，1 test passed |
|
||||
| SpacetimeDB event-id 幂等 | `cargo test --locked --manifest-path server-rs/Cargo.toml -p spacetime-module duplicate_tracking_event_ids_are_treated_as_idempotent_replays -- --nocapture` | 通过，1 test passed |
|
||||
| Rust 格式 | `cargo fmt --manifest-path server-rs/Cargo.toml --all -- --check` | 通过 |
|
||||
| 中文编码 | `npm run check:encoding` | 通过，5662 个文件 |
|
||||
| Diff 空白与分支基线 | `git diff --check`、`git merge-base --is-ancestor origin/master HEAD` | 通过 |
|
||||
|
||||
上述测试合计 48 个与本 Issue 直接相关的测试通过。完整工作区测试按用户约定交由 CI；本阶段未启动真实 SpacetimeDB，也未执行发布环境线上写入，因此最终证据是本地确定性 input/mapper、outbox、后台 parser 和 route tracking 回归，不把本地测试表述为线上 E2E。
|
||||
|
||||
### 10.5 阶段 6 交接结论
|
||||
|
||||
- 主站只对白名单值 `X-Genarrative-Client: agc` 追加 `metadata_json.client = "agc"`；缺失、空值、`AGC` 和未知值按未标记处理，不拒绝请求。
|
||||
- 账号态沿用真实 access token 用户；External API Key 态使用 `ExternalApiPrincipal.owner_user_id()`，不伪造 `user_id`。
|
||||
- 当前 AGC 实际账号态和 External v1 业务路径均有显式 route spec；动态 ID 继续归一化，External v1 保留实际外部 path。
|
||||
- OSS、签名下载、Provider、受控搜索、loopback、更新下载、公开 discovery/Skill/MCP 不进入普通 AGC 业务 route tracking。
|
||||
- 最终记录仍落在现有 SpacetimeDB `tracking_event.metadata_json`，经过本机 `server-rs/.data/tracking-outbox/` 临时缓冲后由既有 tracking procedure 写入；不新增 schema、索引、后台页面或独立事件体系。
|
||||
- `#226` 的客户端标记注入和 origin-safe redirect 契约已满足本 Issue 输入要求，不需要回改 #226 设计。
|
||||
- 另有一个独立于 #225 的客户端后续项：自定义 origin 使用显式默认端口或大写主机名时，`clientHttp.ts` 的字符串与 `URL.origin` 比较可能误判为跨 origin；它只会拒绝合法请求，不会泄漏 marker，应单独在 #226 跟踪。
|
||||
|
||||
阶段 6 详细验收记录与可直接粘贴到 Issue #225 的交付评论见：
|
||||
|
||||
- [【阶段验收】Issue225阶段6最终门禁与交接收口-2026-09-02.md](C:/projects/narrative/Genarrative/local-docs/【阶段验收】Issue225阶段6最终门禁与交接收口-2026-09-02.md)
|
||||
|
||||
## 11. 建议提交分组
|
||||
|
||||
建议按以下逻辑分组提交，便于逐阶段验收：
|
||||
|
||||
1. 阶段 1：marker 解析与 tracking 入口。
|
||||
2. 阶段 2：主体归属与 metadata 合并。
|
||||
3. 阶段 3：route spec 与 External v1 覆盖。
|
||||
4. 阶段 4～5：持久化/后台验证、定向测试和安全回归。
|
||||
5. 阶段 6：验收记录、Issue 交接评论和最终门禁。
|
||||
|
||||
如仓库要求单提交，也应在 PR 描述中按上述五组列出，确保每组都有独立验收标准。
|
||||
@@ -0,0 +1,97 @@
|
||||
# Issue225 阶段 5：定向测试与安全边界
|
||||
|
||||
更新时间：2026-09-02
|
||||
关联分支：`feat/agc_call_rec`
|
||||
|
||||
## 1. 阶段交付结果
|
||||
|
||||
本阶段补齐 Issue #225 直接相关的状态码、鉴权、安全 metadata 和幂等回归，确认 `X-Genarrative-Client: agc` 只是来源审计标签，不改变认证、权限、计费、请求体、异步轮询或成功事件语义。
|
||||
|
||||
## 2. 新增回归
|
||||
|
||||
### 2.1 成功状态语义
|
||||
|
||||
`tracking.rs` 新增 `should_record_route_tracking` 判定测试：
|
||||
|
||||
- `200 / 201 / 202 / 204` 的显式业务 route 可以进入成功 tracking；
|
||||
- `400 / 401 / 403 / 404 / 500 / 502` 即使带 AGC marker，也不会新增成功 route event；
|
||||
- 已由详细资产事件处理的上传票据和对象确认不重复生成统一 route event。
|
||||
|
||||
### 2.2 鉴权边界
|
||||
|
||||
`app.rs` 通过真实 router 发起未认证的：
|
||||
|
||||
```text
|
||||
GET /api/editor/projects
|
||||
X-Genarrative-Client: agc
|
||||
```
|
||||
|
||||
响应仍为 `401 Unauthorized`。marker 不会获得权限，也不会改变失败状态。
|
||||
|
||||
### 2.3 metadata 安全边界
|
||||
|
||||
route metadata 测试确认不会写入：
|
||||
|
||||
```text
|
||||
authorization
|
||||
accessToken
|
||||
token
|
||||
apiKey
|
||||
cookie
|
||||
signature
|
||||
signedUrl
|
||||
requestBody
|
||||
```
|
||||
|
||||
有效 marker 只产生固定的 `client: "agc"`，并保留既有 route/method/status/operation 与资产嵌套字段。
|
||||
|
||||
### 2.4 既有链路复回归
|
||||
|
||||
阶段 4 的以下路径在阶段 5 再次顺序执行：
|
||||
|
||||
- `TrackingEventDraft → RuntimeTrackingEventInput`；
|
||||
- tracking outbox NDJSON round-trip；
|
||||
- `spacetime-client` mapper；
|
||||
- module-runtime metadata object 校验；
|
||||
- 后台 tracking SQL response parser；
|
||||
- 账号态 / External API Key owner 归属；
|
||||
- SpacetimeDB tracking event-id 幂等回归。
|
||||
|
||||
## 3. 验收结果
|
||||
|
||||
- [x] marker 有效值、缺失值、空值、大小写和未知值测试通过。
|
||||
- [x] 账号态 `user_id = owner_user_id` 归属测试通过。
|
||||
- [x] External API Key 态只写真实 `owner_user_id`，不伪造 `user_id`，scope 使用 owner。
|
||||
- [x] 当前账号态和 External v1 业务 route coverage 测试通过。
|
||||
- [x] discovery、Skill、MCP 排除测试通过。
|
||||
- [x] 2xx 成功记录和 4xx/5xx 不新增成功 route event 测试通过。
|
||||
- [x] AGC marker 不绕过鉴权、不改变失败状态。
|
||||
- [x] route metadata 不包含 token、API Key、Cookie、签名 URL 或请求体字段。
|
||||
- [x] outbox、mapper、runtime input 和后台 readback 回归通过。
|
||||
- [x] event-id 幂等回归通过。
|
||||
|
||||
## 4. 定向验证结果
|
||||
|
||||
| 测试范围 | 通过数 |
|
||||
|---|---:|
|
||||
| `module-runtime` tracking input | 2 |
|
||||
| `spacetime-client` tracking mapper | 1 |
|
||||
| `api-server` tracking | 18 |
|
||||
| `api-server` app 鉴权回归 | 1 |
|
||||
| `api-server` 资产 marker / owner | 2 |
|
||||
| `api-server` tracking outbox | 8 |
|
||||
| `api-server` 后台 readback | 5 |
|
||||
| `spacetime-module` event-id 幂等 | 1 |
|
||||
| 合计 | 38 |
|
||||
|
||||
另外通过：
|
||||
|
||||
- `cargo fmt --manifest-path server-rs/Cargo.toml --all -- --check`
|
||||
- `git diff --check`
|
||||
- `npm run check:encoding`
|
||||
|
||||
未运行与本 Issue 无直接关系的完整工作区测试，按约定交给 CI。没有启动真实 SpacetimeDB，因此没有把确定性 procedure input/mapper 和 admin parser 回归扩大解释为远端数据库 E2E。
|
||||
|
||||
## 5. 后续阶段
|
||||
|
||||
阶段 6 汇总阶段 1～5 的证据，复核 #226 交接契约、执行最终门禁并准备 Issue #225 交付说明。阶段 5 代码已提交为 `c5170669e`；日登录埋点构造器回归修复补充提交为 `0a06b4988`。
|
||||
@@ -0,0 +1,144 @@
|
||||
# Issue225 阶段6：最终门禁与 #226 交接收口
|
||||
|
||||
更新时间：`2026-09-02`
|
||||
实施范围：`#225 添加客户端埋点统计`
|
||||
交接输入：`#226 添加客户端特殊标识`
|
||||
|
||||
执行结论：阶段 6 通过，Issue #225 的主站接收、tracking metadata、主体归属、路由覆盖、持久化/后台读取验证和安全语义回归已收口。本阶段没有新增生产功能，没有修改 #226 客户端实现，不需要 #226 回改设计。
|
||||
|
||||
## 1. 阶段边界
|
||||
|
||||
本阶段只完成：
|
||||
|
||||
1. 汇总阶段 1～5 的实现提交、定向测试和 readback 证据。
|
||||
2. 复核 `#226` 交接的 Header、origin、认证和第三方边界。
|
||||
3. 执行与本 Issue 直接相关的最终编译、测试、格式、编码和空白门禁。
|
||||
4. 更新实施方案、分阶段计划和 Issue #225 交付评论草案。
|
||||
|
||||
本阶段明确不做：
|
||||
|
||||
- 不修改 `AGC` 客户端的 `fetchClientHttp`、Rust Client factory、请求终结器或 redirect policy。
|
||||
- 不新增 `tracking_event` 列、索引、migration、生成 bindings 或新的统计表。
|
||||
- 不修改 `/api/external/v1` 的 OpenAPI、DTO、HTTP 方法、状态码、鉴权或异步语义。
|
||||
- 不新增后台筛选器、报表页面或真实发布环境线上写入。
|
||||
|
||||
## 2. 当前仓库基线
|
||||
|
||||
阶段 6 开始时仓库状态：
|
||||
|
||||
| 项目 | 结果 |
|
||||
|---|---|
|
||||
| 分支 | `feat/agc_call_rec` |
|
||||
| HEAD | `5aa38d9f3`（已合并最新 `origin/master`） |
|
||||
| `origin/master` | `8932f0b27` |
|
||||
| 工作树 | 开始阶段 6 时干净；本记录及计划/方案更新属于本阶段待提交文档变更 |
|
||||
|
||||
阶段 1～5 的实现提交：
|
||||
|
||||
| 阶段 | 提交 |
|
||||
|---|---|
|
||||
| 阶段 1：marker 解析与 tracking 入口 | `2296f79fd` |
|
||||
| 阶段 2：主体归属与 metadata | `2a23ba657` |
|
||||
| 阶段 3：路由覆盖 | `01159a269` |
|
||||
| 阶段 4：持久化与后台读取 | `c75c61521` |
|
||||
| 阶段 5：安全与语义回归 | `c5170669e` |
|
||||
| 日登录埋点构造器回归修复 | `0a06b4988` |
|
||||
|
||||
## 3. 最终交付行为
|
||||
|
||||
### 3.1 Marker 与 metadata
|
||||
|
||||
主站识别：
|
||||
|
||||
```http
|
||||
X-Genarrative-Client: agc
|
||||
```
|
||||
|
||||
规则：
|
||||
|
||||
- Header 名按 HTTP 规则大小写不敏感。
|
||||
- Header 值去除首尾空白后，必须精确等于小写 `agc`。
|
||||
- 缺失、空值、`AGC` 或未知值按未标记处理，不拒绝请求。
|
||||
- 有效标记只追加到已有成功 route tracking 的 `tracking_event.metadata_json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"route": "/api/editor/projects",
|
||||
"method": "GET",
|
||||
"status": 200,
|
||||
"operation": "listEditorProjects",
|
||||
"client": "agc"
|
||||
}
|
||||
```
|
||||
|
||||
不写入 Header 原文、token、API Key、Cookie、签名 URL、请求体或项目绝对路径。
|
||||
|
||||
### 3.2 主体归属
|
||||
|
||||
- 登录账号态：使用已验证 access token 的真实用户，保留既有 `user_id`、`owner_user_id` 和 scope 语义。
|
||||
- External API Key 态：使用 `ExternalApiPrincipal.owner_user_id()`；不伪造登录 `user_id`，User scope 的 `scope_id` 使用 owner。
|
||||
- Header 只是来源审计标签，不能绕过认证、权限、计费或替换主体。
|
||||
|
||||
### 3.3 路由覆盖与排除
|
||||
|
||||
已覆盖的实际业务路径：
|
||||
|
||||
- 账号态：`/api/auth/*`、`/api/profile/*`、`/api/assets/*`、`/api/editor/*`、`/api/runtime/*`。
|
||||
- External API Key 态：`/api/external/v1/*` 的当前资产、项目、素材库、生成提交和任务轮询业务路径。
|
||||
- 动态 project/generation/asset ID 继续按显式静态段规则归一化；External v1 metadata 保留实际外部 path。
|
||||
- 上传票据和对象确认沿用已有详细资产事件，不重复生成普通 route event，但会保留有效 AGC metadata。
|
||||
|
||||
明确排除：
|
||||
|
||||
- OSS multipart 上传、签名 URL/OSS 媒体下载。
|
||||
- LLM/Codex Provider、AGC 受控搜索、loopback 工具桥。
|
||||
- 更新清单、更新包下载和任意外部网页请求。
|
||||
- `/api/external/v1/openapi.json`、`agent-integration.json`、Skill 文档/压缩包和 MCP 入口。
|
||||
|
||||
### 3.4 落库与读取位置
|
||||
|
||||
AGC 调用记录最终落在主站 SpacetimeDB 的 `tracking_event` 表，标识位于 `tracking_event.metadata_json.client`。普通 route tracking 默认先进入 api-server 本机：
|
||||
|
||||
```text
|
||||
server-rs/.data/tracking-outbox/active.ndjson
|
||||
server-rs/.data/tracking-outbox/sealed-*.ndjson
|
||||
```
|
||||
|
||||
worker 使用既有 `record_tracking_events_and_return` 批量 procedure 写入 SpacetimeDB；outbox 不可用时沿用同步 `record_tracking_event_and_return` 回退。后台 `GET /admin/api/tracking/events` 读取同一 `tracking_event` 的 `metadata_json`，当前没有单独的 `client=agc` 查询参数，需要从返回 JSON 中识别 `"client": "agc"`。
|
||||
|
||||
## 4. 最终门禁证据
|
||||
|
||||
| 验收项 | 命令 | 结果 |
|
||||
|---|---|---|
|
||||
| api-server 编译 | `cargo check --locked --manifest-path server-rs/Cargo.toml -p api-server` | 通过；仅仓库既有 warning |
|
||||
| api-server tracking/资产/后台/outbox 定向测试 | `cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server tracking -- --nocapture` | 43 passed，0 failed |
|
||||
| marker 不绕过鉴权回归 | `cargo test --locked --manifest-path server-rs/Cargo.toml -p api-server app::tests::agc_marker_does_not_bypass_authentication_or_change_failure_status -- --nocapture` | 1 passed，0 failed |
|
||||
| module-runtime tracking input | `cargo test --locked --manifest-path server-rs/Cargo.toml -p module-runtime tracking_input_ -- --nocapture` | 2 passed，0 failed |
|
||||
| spacetime-client mapper | `cargo test --locked --manifest-path server-rs/Cargo.toml -p spacetime-client tracking_input_mapper_preserves_agc_metadata_and_external_owner -- --nocapture` | 1 passed，0 failed |
|
||||
| SpacetimeDB event-id 幂等 | `cargo test --locked --manifest-path server-rs/Cargo.toml -p spacetime-module duplicate_tracking_event_ids_are_treated_as_idempotent_replays -- --nocapture` | 1 passed，0 failed |
|
||||
| Rust 格式 | `cargo fmt --manifest-path server-rs/Cargo.toml --all -- --check` | 通过 |
|
||||
| 中文编码 | `npm run check:encoding` | 通过，5662 个文件 |
|
||||
| Diff 空白/分支基线 | `git diff --check`、`git merge-base --is-ancestor origin/master HEAD` | 通过 |
|
||||
|
||||
与本 Issue 直接相关的本轮定向测试合计 48 个通过。完整工作区测试不在本地重复运行，按约定交给 CI；本地未启动真实 SpacetimeDB，因此没有把 input/mapper/readback parser 测试表述为线上 E2E。
|
||||
|
||||
## 5. #226 交接复核
|
||||
|
||||
`#226` 已提供并冻结以下输入：
|
||||
|
||||
- 发往当前 Genarrative 主站 origin 的业务请求带 `X-Genarrative-Client: agc`。
|
||||
- OSS、签名下载、Provider、受控搜索、loopback、更新下载和外部网页请求不带该标记。
|
||||
- 同源重定向继续允许；跨 origin 重定向被阻断，避免标记泄漏到第三方 origin。
|
||||
- 请求级同名 Header 不能伪造最终值，主站业务请求最终仍为 `agc`。
|
||||
|
||||
主站 #225 已按上述契约消费 Header；不存在要求 #226 重新设计或回改的接口缺口。
|
||||
|
||||
补充记录一个不属于 #225 的客户端后续项：`clientHttp.ts` 当前把自定义服务器地址的规范化字符串直接与 `URL.origin` 比较；显式默认端口（例如 `https://example.com:443`）或主机名大小写可能导致合法自定义 origin 被误判为跨 origin。该问题表现为请求被客户端拒绝，不会造成 AGC 标记泄漏，也不影响当前 release/dev 默认地址；应作为 #226 的独立客户端修复跟踪，不能在 #225 中偷偷回改客户端设计。
|
||||
|
||||
## 6. 可直接粘贴到 Issue #225 的交付评论
|
||||
|
||||
> `#225` 主站侧已完成并收口：统一识别 `X-Genarrative-Client: agc`，并在现有成功 route tracking 的 `tracking_event.metadata_json` 中追加 `client: "agc"`。账号态按已验证 access token 的真实用户归属，External API Key 态按 `ExternalApiPrincipal.owner_user_id()` 归属，不伪造 `user_id`，不记录 token/API Key/Cookie/签名 URL。当前 AGC 实际使用的账号态 `/api/auth/*`、`/api/profile/*`、`/api/assets/*`、`/api/editor/*`、`/api/runtime/*` 与 External v1 业务路径均有显式 route spec；动态 ID 继续归一化，External v1 保留实际外部 path。OSS/签名下载、Provider、受控搜索、loopback、更新下载、公开 discovery/Skill/MCP 不进入普通 AGC 业务统计。记录最终落在现有 `tracking_event.metadata_json.client`，复用既有 outbox、SpacetimeDB procedure、daily stat、event-id 幂等和后台 `GET /admin/api/tracking/events` 读取，不新增 schema、页面或独立事件体系。阶段 1～5 的定向实现和回归已提交，阶段 6 最终门禁通过：api-server tracking/资产/后台/outbox 43 个、鉴权回归 1 个、module-runtime 2 个、spacetime-client 1 个、spacetime-module 1 个定向测试全部通过，Rust 编译/格式、编码和 diff 检查通过；完整工作区测试按 CI 执行。`#226` 客户端标记、origin-safe redirect 和第三方边界契约无需回改。`
|
||||
|
||||
## 7. 后续发布前事项
|
||||
|
||||
本 Issue 代码和本地确定性验证已完成；发布或联调时由主站环境补做一次真实链路 smoke：使用已部署的 AGC 客户端请求主站业务接口，确认 Header 被接收、`tracking_event.metadata_json.client` 可由后台原始查询读回。该 smoke 是环境验证，不改变本 PR 的设计或代码范围。
|
||||
Reference in New Issue
Block a user