合并master并保留双侧最新决策记录
合入主站 AGC 请求头归属与项目命名链路改动。 保留本分支 Direct 过程卡决策记录。 保留主站登录归属、workspace 边界与 Native shell 决策记录。
This commit is contained in:
@@ -0,0 +1,328 @@
|
||||
# Issue225 登录成功 AGC 用户归属修复方案
|
||||
|
||||
状态：已实现（2026-09-03）
|
||||
|
||||
## 1. 一句话交付目标
|
||||
|
||||
对带有合法 `X-Genarrative-Client: agc` 的登录成功请求，将现有登录 route tracking event 归属到登录成功后的真实用户；保持 `daily_login` 原有的“用户 + 北京时间业务日”幂等语义，不解析 access token，不新增数据库表、事件体系或状态机。
|
||||
|
||||
## 2. Issue 边界
|
||||
|
||||
### 2.1 本次只做 #225
|
||||
|
||||
本方案只修改主站 `api-server` 的登录成功埋点归属链路。
|
||||
|
||||
`#226` 已冻结并合入的客户端 Header 注入、主站 client factory、同源重定向和第三方请求边界作为本方案输入，不在本次修改。
|
||||
|
||||
### 2.2 本次解决
|
||||
|
||||
- AGC 密码登录成功 route event 的真实用户归属。
|
||||
- AGC 手机号登录成功 route event 的真实用户归属。
|
||||
- tracking middleware 与登录 handler 之间的可信主体传递。
|
||||
- 方案文档、测试和验收口径与实际登录阶段保持一致。
|
||||
|
||||
### 2.3 明确不做
|
||||
|
||||
- 不修改 access token、refresh token、Cookie、登录响应体或认证协议。
|
||||
- 不从响应体、Cookie 或 Header 解析用户身份。
|
||||
- 不把 `X-Genarrative-Client` 当作认证或授权边界。
|
||||
- 不修改 `daily_login` 的 event key、幂等键、业务日算法或 daily stat 语义。
|
||||
- 不新增 `agc_login_success` 平行事件。
|
||||
- 不新增 SpacetimeDB 表、字段、migration、binding 或后台页面。
|
||||
- 不改变未标记请求的既有 route tracking 统计口径。
|
||||
- 不在 `RequestContext` 中增加一次性登录主体状态。
|
||||
|
||||
## 3. 修复前行为与根因
|
||||
|
||||
当前登录链路大致如下：
|
||||
|
||||
```text
|
||||
请求进入
|
||||
→ tracking middleware 读取 AGC marker
|
||||
→ 登录 handler 校验密码/验证码
|
||||
→ 创建 session 和 access token
|
||||
→ handler 手工记录 daily_login
|
||||
→ 返回 access token / Cookie
|
||||
→ tracking middleware 读取 response extensions
|
||||
→ 写入登录 route event
|
||||
```
|
||||
|
||||
当前 `tracking` middleware 只从 response extensions 读取：
|
||||
|
||||
- `AuthenticatedAccessToken`；
|
||||
- `ExternalApiPrincipal`。
|
||||
|
||||
登录请求进入时还没有 `AuthenticatedAccessToken`。虽然
|
||||
`phone_auth.rs` 和 `password_entry.rs` 的 handler 在认证成功后已经拥有可信的
|
||||
`result.user.id`，但目前没有把这个主体传给 tracking middleware。
|
||||
|
||||
因此会出现：
|
||||
|
||||
- `auth_password_login_success` / `auth_phone_login_success` route event 带有 `client=agc`，但 `user_id`、`owner_user_id` 为空，`scope_id` 为 `anonymous`；
|
||||
- `daily_login` 有真实用户 ID，但没有 AGC 来源信息。
|
||||
|
||||
这不是认证失败或用户身份校验错误，而是“认证成功发生在 handler 内部，通用 middleware 无法看到 handler 内部认证结果”的传递缺口。
|
||||
|
||||
## 4. 设计决策
|
||||
|
||||
### 4.1 route event 作为 AGC 登录来源的权威记录
|
||||
|
||||
本次不把 `daily_login` 改造成 AGC 来源事件，而是让现有登录 route event 同时承载：
|
||||
|
||||
- 本次成功登录请求的 route、method、status；
|
||||
- `client=agc` 来源标记；
|
||||
- 认证成功后的真实用户归属。
|
||||
|
||||
这样可以直接回答“哪些用户通过 AGC 成功登录”，并且保留现有 route event 的每请求事件语义。
|
||||
|
||||
### 4.2 `daily_login` 保持原有语义
|
||||
|
||||
`daily_login` 使用按用户和业务日生成的稳定 event id：
|
||||
|
||||
```text
|
||||
daily-login:{user_id}:{beijing_day_key}
|
||||
```
|
||||
|
||||
同一用户一天内的第二次登录会被幂等去重。如果把 `client=agc` 写进该事件，会出现来源丢失或误标记：
|
||||
|
||||
- 先网页登录、后 AGC 登录：AGC 来源可能被第二次幂等跳过；
|
||||
- 先 AGC 登录、后网页登录：当天事件会永久看起来像 AGC 登录；
|
||||
- 同一天不同来源无法表达多次登录事实。
|
||||
|
||||
因此 `daily_login` 继续只表示“该用户当天已完成登录”，不承担 AGC 来源归因。需要按用户查询 AGC 登录时，查询带 `metadata.client = "agc"` 的登录 route event。
|
||||
|
||||
### 4.3 使用一次性 response extension，不引入状态机
|
||||
|
||||
增加一个仅在本次 HTTP 请求内存在的内部主体类型，例如：
|
||||
|
||||
```rust
|
||||
TrackingLoginSubject {
|
||||
user_id: String,
|
||||
}
|
||||
```
|
||||
|
||||
它只保存认证服务已经确认的用户 ID，不保存 token，不落库，不跨请求复用，也不引入新的生命周期状态。
|
||||
|
||||
## 5. 目标链路
|
||||
|
||||
```text
|
||||
AGC marker
|
||||
→ tracking middleware 解析并放入 request extensions
|
||||
→ 登录 handler 完成密码/验证码校验
|
||||
→ 从 result.user.id 构造 TrackingLoginSubject
|
||||
→ 将主体放入 response extensions
|
||||
→ tracking middleware 读取主体
|
||||
→ 现有 identity resolver 生成 user/owner/scope
|
||||
→ 现有 route tracking metadata/outbox/SpacetimeDB 链路
|
||||
```
|
||||
|
||||
## 6. 具体实现约定
|
||||
|
||||
### 6.1 登录 handler
|
||||
|
||||
涉及：
|
||||
|
||||
- `server-rs/crates/api-server/src/phone_auth.rs`
|
||||
- `server-rs/crates/api-server/src/password_entry.rs`
|
||||
|
||||
处理顺序：
|
||||
|
||||
1. 保持现有密码/验证码校验、session 创建、Cookie 设置和响应 body 不变。
|
||||
2. 只有当前请求的 marker 精确解析为 `TrackingClientMarker::Agc` 时，才附加 `TrackingLoginSubject`。
|
||||
3. `user_id` 只能来自认证服务返回的 `result.user.id`。
|
||||
4. 仅在认证和 session 创建成功后附加主体；任何失败路径都不附加。
|
||||
5. 通过响应转换 helper 写入 response extensions，不能改变 HTTP status、headers 或 JSON body。
|
||||
|
||||
Header 只参与“是否进行 AGC 来源归因”的判断，不能提供用户身份。即使调用方伪造 Header，最终写入的用户 ID 仍来自后端已验证的登录结果。
|
||||
|
||||
### 6.2 tracking middleware
|
||||
|
||||
涉及：
|
||||
|
||||
- `server-rs/crates/api-server/src/app.rs`
|
||||
- `server-rs/crates/api-server/src/tracking.rs`
|
||||
|
||||
在现有主体来源之外增加登录主体兜底：
|
||||
|
||||
```text
|
||||
ExternalApiPrincipal
|
||||
→ AuthenticatedAccessToken
|
||||
→ TrackingLoginSubject
|
||||
```
|
||||
|
||||
其中：
|
||||
|
||||
- `ExternalApiPrincipal` 和 `AuthenticatedAccessToken` 的现有优先级和行为不变；
|
||||
- `TrackingLoginSubject` 只用于合法 AGC marker 的登录 route；
|
||||
- `TrackingLoginSubject` 的 `user_id` 和 `owner_user_id` 由同一个已验证用户 ID 填充；
|
||||
- User scope 的 `scope_id` 解析为真实用户，不再回退到 `anonymous`。
|
||||
|
||||
### 6.3 route 策略边界
|
||||
|
||||
当前分支的 route policy 必须保持：
|
||||
|
||||
- `/api/auth/entry` 使用 AGC-only route spec；没有合法 marker 时不产生 route event，但登录业务本身不被拒绝；
|
||||
- `/api/auth/phone/login` 继续使用既有全客户端 route tracking 语义；带合法 marker 时新增真实用户归属，未标记时保持既有匿名 route event 语义。
|
||||
|
||||
本方案不把手机号登录改造成 AGC-only，也不扩大 #225 的 route coverage。
|
||||
|
||||
### 6.4 可选鉴权的资产读取路由
|
||||
|
||||
`/api/assets/read-url` 和 `/api/assets/read-bytes` 同时支持匿名公开素材读取与已登录用户读取，
|
||||
因此不能直接挂接 `require_bearer_auth`。这两个 handler 会继续使用
|
||||
`optional_access_token_from_headers` 完成 Bearer 校验和素材权限判断；如果校验成功，
|
||||
则把同一个已验证的 `AuthenticatedAccessToken` 放入成功响应 extensions，供外层 tracking
|
||||
middleware 读取真实用户主体。
|
||||
|
||||
该传递只发生在当前响应内：
|
||||
|
||||
- 匿名公开读取不附加认证主体，仍按 `anonymous` 记录；
|
||||
- 无效 Bearer 仍返回 `401`，不产生成功 route event；
|
||||
- External API Key 和管理员资产读取继续使用各自的 `ExternalApiPrincipal` / 管理员审计链路；
|
||||
- 不把 Authorization Header、access token、refresh token 或 Cookie 写入埋点。
|
||||
|
||||
## 7. 事件结果示例
|
||||
|
||||
### 7.1 AGC 密码登录成功
|
||||
|
||||
```text
|
||||
event_key = auth_password_login_success
|
||||
metadata.client = agc
|
||||
user_id = user-xxx
|
||||
owner_user_id = user-xxx
|
||||
scope_kind = user
|
||||
scope_id = user-xxx
|
||||
```
|
||||
|
||||
### 7.2 AGC 手机号登录成功
|
||||
|
||||
```text
|
||||
event_key = auth_phone_login_success
|
||||
metadata.client = agc
|
||||
user_id = user-xxx
|
||||
owner_user_id = user-xxx
|
||||
scope_kind = user
|
||||
scope_id = user-xxx
|
||||
```
|
||||
|
||||
### 7.3 `daily_login`
|
||||
|
||||
```text
|
||||
event_key = daily_login
|
||||
user_id = user-xxx
|
||||
event_id = daily-login:user-xxx:{beijing_day_key}
|
||||
metadata = 保持现有 operation/loginMethod 等字段，不承担 AGC 来源归因
|
||||
```
|
||||
|
||||
## 8. 不采用的方案
|
||||
|
||||
### 8.1 只给 `daily_login` 追加 `client`
|
||||
|
||||
不采用。它会受到用户当天首次登录来源和幂等去重顺序影响，不能准确表达 AGC 登录事实。
|
||||
|
||||
### 8.2 从响应体或 Cookie 解析 access token
|
||||
|
||||
不采用。会让埋点 middleware 依赖认证响应格式，扩大敏感凭据处理边界，且没有必要。
|
||||
|
||||
### 8.3 新增 `agc_login_success` 事件
|
||||
|
||||
不采用。现有登录 route event 已经有 route、method、status、event key 和 metadata 承载能力，再增加事件会产生第二套统计口径和后台查询约定。
|
||||
|
||||
### 8.4 让 Header 直接决定 user_id
|
||||
|
||||
不采用。Header 是可伪造的来源标签，不能成为身份事实。
|
||||
|
||||
### 8.5 修改已有 `daily_login` 事件的重复记录行为
|
||||
|
||||
不采用。这样会改变每日任务、daily stat 和事件幂等语义，超出本次登录来源归因问题。
|
||||
|
||||
## 9. 测试与验收
|
||||
|
||||
### 9.1 middleware 成功链路
|
||||
|
||||
通过现有 `build_router` 和隔离 tracking outbox，验证：
|
||||
|
||||
```text
|
||||
HTTP request
|
||||
→ marker middleware
|
||||
→ 登录 handler
|
||||
→ response extension
|
||||
→ tracking middleware
|
||||
→ outbox
|
||||
```
|
||||
|
||||
断言：
|
||||
|
||||
- 登录响应 status、headers、body 与原行为一致；
|
||||
- AGC 密码登录 route event 有 `metadata.client = "agc"`；
|
||||
- AGC 手机登录 route event 有 `metadata.client = "agc"`；
|
||||
- `user_id`、`owner_user_id`、`scope_id` 为真实用户；
|
||||
- outbox metadata 不包含 access token、refresh token、Cookie、密码或验证码。
|
||||
|
||||
资产读取的成功链路还必须满足：
|
||||
|
||||
- AGC + 有效 Bearer 的 `/api/assets/read-url` 和 `/api/assets/read-bytes`，route event 的
|
||||
`user_id`、`owner_user_id`、`scope_id` 均为 Bearer 对应的真实用户；
|
||||
- AGC + 无 Bearer 的公开素材读取仍保持匿名归属；
|
||||
- 资产读取权限判断和 tracking 主体传递复用同一次 Bearer 校验结果，不重复解析或自行构造身份。
|
||||
|
||||
### 9.2 未标记回归
|
||||
|
||||
- 未标记手机号登录继续保持既有 route tracking 语义；
|
||||
- 未标记密码登录不产生 AGC route event；
|
||||
- `/api/auth/entry` 缺少 marker 时仍不放行 route tracking，但不改变登录业务响应；
|
||||
- Header 伪造不会改变最终 user_id。
|
||||
|
||||
### 9.3 `daily_login` 回归
|
||||
|
||||
- `daily_login` 仍使用真实用户；
|
||||
- event id 仍按用户 + 北京时间业务日生成；
|
||||
- 同一用户同一天重复登录仍幂等；
|
||||
- 本次修复不要求从 `daily_login` 查询 AGC 来源。
|
||||
|
||||
### 9.4 常规验证
|
||||
|
||||
按修改范围运行：
|
||||
|
||||
- api-server 相关定向 Rust 测试；
|
||||
- `cargo check --locked --manifest-path server-rs/Cargo.toml -p api-server`；
|
||||
- `cargo fmt --check`；
|
||||
- `npm run check:encoding`；
|
||||
- `git diff --check`。
|
||||
|
||||
CI 已覆盖的全量测试不要求本地重复运行。
|
||||
|
||||
## 10. 数据和发布边界
|
||||
|
||||
- 不做历史数据回填。旧登录 route event 没有足够可信的信息安全补写用户归属。
|
||||
- 不修改 tracking schema、migration、SpacetimeDB bindings 或后台 readback API。
|
||||
- 新代码上线后产生的 AGC 登录 route event 才保证用户归属完整。
|
||||
- 认证主链路、登录响应和埋点失败不阻断业务的既有语义全部保留。
|
||||
|
||||
## 11. 实施顺序
|
||||
|
||||
1. 在 `tracking.rs` 增加内部 `TrackingLoginSubject` 和身份解析兜底。
|
||||
2. 在密码/手机号登录成功响应中附加主体 extension。
|
||||
3. 在 `app.rs` tracking middleware 读取主体并传入 route tracking。
|
||||
4. 增加真实 middleware 链路及未标记回归测试。
|
||||
5. 更新 Issue225 现有方案和阶段验收文档中的登录归属表述。
|
||||
6. 完成定向验证后再提交代码。
|
||||
|
||||
## 12. 最终判断
|
||||
|
||||
推荐使用“登录 handler 传递一次性可信主体，route event 负责 AGC 登录归因，`daily_login` 保持原语义”的方案。
|
||||
|
||||
该方案只增加一个单字段、请求级的内部传递对象，不引入新的持久化状态或状态机；同时避免了把每日幂等事件错误地当作来源审计事件，最终代码边界和后台查询口径都更容易维护。
|
||||
|
||||
## 13. 实现记录
|
||||
|
||||
本方案已在当前分支落地：
|
||||
|
||||
- `server-rs/crates/api-server/src/tracking.rs` 增加 `TrackingLoginSubject`，并将其作为登录主体的最后兜底来源；既有 `ExternalApiPrincipal`、`AuthenticatedAccessToken` 优先级保持不变。
|
||||
- `server-rs/crates/api-server/src/password_entry.rs` 和 `server-rs/crates/api-server/src/phone_auth.rs` 在认证与 session 创建成功后，仅对合法 AGC marker 请求向 response extensions 附加真实用户主体。
|
||||
- `server-rs/crates/api-server/src/app.rs` 只在合法 AGC marker 存在时读取该主体并交给 route tracking；未标记请求不使用该新主体来源。
|
||||
- `server-rs/crates/api-server/src/assets.rs` 保留两个资产读取路由的可选鉴权语义，并在有效 Bearer 成功读取时把已验证主体放入响应 extensions，补齐 AGC 资产读取事件的用户归属；匿名读取和 External API Key/Admin 路由边界未改变。
|
||||
- `daily_login` helper、event id 幂等、认证响应和 Cookie 语义未修改。
|
||||
- 已增加密码登录、手机号登录、资产读取主体传递和主体解析测试；登录链路与资产读取主体传递均验证通过。
|
||||
|
||||
本次实现没有修改 SpacetimeDB schema、migration、bindings、OpenAPI 或后台页面，也没有新增事件 key。
|
||||
@@ -1,5 +1,12 @@
|
||||
# AI 游戏创作智能体 App 实施计划
|
||||
|
||||
## 2026-09-02 项目名称显示与自动提炼
|
||||
|
||||
- `.agent/manifest.json` 的 `name` 仍是本地项目显示名唯一事实源；项目组页行尾更多菜单提供行内重命名，保存必须走 Tauri 受控命令、项目写锁、manifest 写锁与既有 ACL/权限校验。重命名只更新 manifest，不改变项目目录、`projectId`、项目类型、任务、资源、版本或远端同步状态；保存成功后当前项目上下文、窗口标题和最近项目检查结果必须回读新 manifest 并保持一致。
|
||||
- 项目名称统一 trim 后非空、最多 80 个字符且不得包含控制字符。空名称、超长、控制字符或未初始化项目必须失败关闭，原 manifest 保持可用；失败提示只展示安全错误，不泄露宿主路径之外的新内部信息。
|
||||
- 首页自动创建工作区前允许一次受限 LLM 名称提炼：输入只包含用户文本需求和附件元数据摘要，输出只允许一个简短中文项目名。Rust 侧统一规范化并在空值、控制字符、超长或多行格式时返回失败；前端把有效名称传给自动建项命令，失败时继续使用现有 `GameAgent 项目 {短ID}` 默认名并照常进入创作，不重试、不阻断、不额外消耗 Provider 请求。
|
||||
- 手动“新建项目”继续默认使用所选文件夹名，不额外调用 LLM；项目创建后用户可通过项目组页重命名修正显示名。自动建项命令的自定义名称必须走同一校验，未提供名称时保持现有默认名，保证旧调用与失败回退路径不变。
|
||||
|
||||
## 2026-09-02 客户端会话恢复可观测性与超时兜底
|
||||
|
||||
- AGC 客户端启动恢复按“读取本地凭据 → 刷新会话（无 token 或失效时）→ 读取当前用户 → Tauri 本地运行时会话安装”阶段执行。界面必须展示当前阶段和已等待时间；不能以无期限的单一 loading 文案隐藏网络或 Runner 故障。
|
||||
|
||||
Reference in New Issue
Block a user