修复AGC资产读取埋点用户归属

资产读取路由保留可选鉴权并传递已验证 Bearer 主体到响应扩展

补充资产读取主体传递与匿名边界测试

同步 Issue225 技术方案和项目决策记录

docs/project-memory/shared-memory/decision-log.md

@@ -20,9 +20,10 @@
 - 背景：登录请求进入时尚未拥有 `AuthenticatedAccessToken`，通用 tracking middleware 无法从响应 extensions 归属登录成功用户；将 AGC marker 直接写入按用户/业务日幂等的 `daily_login` 又会受到不同来源登录顺序影响。
 - 决策：密码登录和手机号登录 handler 在认证及 session 创建成功后，仅对合法 AGC marker 请求向响应 extensions 附加一次性 `TrackingLoginSubject`。tracking middleware 在现有 `ExternalApiPrincipal`、`AuthenticatedAccessToken` 之后使用该主体生成登录 route event 的 `user_id`、`owner_user_id` 和 User scope。`daily_login` 保持原有 event key、幂等键、业务日和 metadata 语义，不承担 AGC 来源归因。
 - 安全边界：主体只来自后端认证服务返回的用户 ID；Header 仅决定是否进行 AGC 来源归因，不参与身份计算；不解析、不记录 access token、refresh token 或 Cookie。
-- 影响范围：`api-server` 登录 handler、tracking middleware、Issue225 技术方案和定向集成测试；不修改 SpacetimeDB schema、migration、bindings、OpenAPI、后台页面或认证响应协议。
-- 验证方式：密码/手机号登录真实 `build_router` 链路分别验证 AGC route event 的 marker、真实用户归属和 outbox 落盘；tracking identity 单测、`cargo check --locked -p api-server`、`cargo test --locked -p api-server agc_`、格式、编码和 diff 检查通过。
-- 关联文档：`docs/technical/【后端架构】Issue225登录成功AGC用户归属修复方案-2026-09-03.md`、Issue #225、`server-rs/crates/api-server/src/tracking.rs`、`server-rs/crates/api-server/src/app.rs`。
+- 影响范围：`api-server` 登录 handler、资产读取 handler、tracking middleware、Issue225 技术方案和定向集成测试；不修改 SpacetimeDB schema、migration、bindings、OpenAPI、后台页面或认证响应协议。
+- 资产读取边界：`/api/assets/read-url` 和 `/api/assets/read-bytes` 继续支持匿名公开读取；有效 Bearer 复用同一次可选鉴权结果，在成功响应 extensions 中传递 `AuthenticatedAccessToken`，供 AGC route tracking 归属用户。External API Key/Admin 路由继续使用各自主体和审计链路。
+- 验证方式：密码/手机号登录真实 `build_router` 链路分别验证 AGC route event 的 marker、真实用户归属和 outbox 落盘；资产读取主体保留、响应 extension 与匿名不附加单测；tracking identity 单测、`cargo check --locked -p api-server`、相关 `cargo test --locked -p api-server`、格式、编码和 diff 检查通过。
+- 关联文档：`docs/technical/【后端架构】Issue225登录成功AGC用户归属修复方案-2026-09-03.md`、Issue #225、`server-rs/crates/api-server/src/tracking.rs`、`server-rs/crates/api-server/src/app.rs`、`server-rs/crates/api-server/src/assets.rs`。
 
 ## 2026-09-02 GDD 审批卡的后台 hydrate 不抢占已加载决定
 

docs/technical/【后端架构】Issue225登录成功AGC用户归属修复方案-2026-09-03.md

@@ -166,6 +166,21 @@ ExternalApiPrincipal
 
 本方案不把手机号登录改造成 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 密码登录成功
@@ -244,6 +259,13 @@ HTTP request
 - `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 语义；
@@ -299,7 +321,8 @@ CI 已覆盖的全量测试不要求本地重复运行。
 - `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 语义未修改。
-- 已增加密码登录、手机号登录和主体解析测试；两条真实 `build_router → 登录 handler → response extension → tracking middleware → outbox` 链路均验证通过。
+- 已增加密码登录、手机号登录、资产读取主体传递和主体解析测试；登录链路与资产读取主体传递均验证通过。
 
 本次实现没有修改 SpacetimeDB schema、migration、bindings、OpenAPI 或后台页面，也没有新增事件 key。