发布 v0.8.3

新增活跃会话管理与通行密钥、钱包登录
发布 v0.8.2
2026-07-30 12:44:14 +08:00 · 2026-07-30 12:23:05 +08:00 · 2026-07-22 22:15:23 +08:00 · 2026-07-22 19:38:14 +08:00 · 2026-07-22 17:10:58 +08:00 · 2026-07-22 16:51:23 +08:00
138 changed files with 19755 additions and 1047 deletions
@@ -1 +1 @@
-0.6.6
+0.6.10
@@ -0,0 +1,132 @@
 # Auth Login Methods(登录方式接入契约)
 > 面板现有登录方式:密码(+可选 TOTP)、OIDC / GitHub(OAuth)、通行密钥(Passkey / WebAuthn)、Web3 钱包(EIP-4361)。
 > 新增或修改任何登录方式时,以下契约是安全红线,缺一不可。
 ## 1. 登录守卫(防爆破)
 公开登录端点的失败必须计入 `loginGuard`:`guardKey(clientIP, <账号标识>)`,账号未知用固定占位名(如 passkey 的 `__passkey__`),已知用其标识(如钱包地址小写)。锁定检查在校验之前;失败经 `auth.failLogin`(自带阈值转锁定与告警推送),成功 `guard.success`。阈值/时长取安全设置,不硬编码。
 ## 2. 系统日志留痕
 公开登录端点不经系统日志中间件,handler 必须显式 `logs.Record` 成败(参考 `authHandler.recordLogin` / `passkeyHandler.recordLogin` / `walletHandler.recordWallet`);登录失败是安全关键事件,不允许无痕。JWT 组内的绑定/解绑由中间件自动留痕,无需额外埋点。
 ## 3. 令牌版本(TokenVersion)
 绑定、解绑、凭据及认证因子变更均属敏感变更:必须在事务内
 `bumpTokenVersionTx`(或 `RevokeSessions`)使旧 JWT 失效，并按第 6 节携带
 `TokenProof`、接续操作者会话。因子写入与版本递增不得拆成两个独立提交。
 ## 4. 「至少一种登录方式」不变量
 密码登录禁用要求至少一种在当前 `EffectiveAppURL` 下**可实际登录**的免密方式
 (`usablePasswordlessTx`);地址为空时 Passkey、钱包和 OAuth 均不可用。禁用期间移除
 最后一种免密方式被拒:解绑身份走 `ensureNotLastLogin`,删通行密钥走对称检查。
 这些检查都在事务内先 `lockUserForAuthChange` 锁用户行,防并发绕过。新登录方式要
 明确决策如何参与该不变量:
 - **复用 `UserIdentity` 表**(如钱包,provider+subject 唯一)→ 走 `identityCountTx` 自动参与,零改动;
 - **独立表**(如 Passkey 的 `UserPasskey`)→ 参照 `passkeyCountTx` 增加计数入口,并在开启门槛(`hasAnyPasswordless`)与两个 `ensureNot*` 检查里对称接入;api 层把 `ErrLastIdentity` 映射 409。
 ## 5. 挑战/状态的一次性消费
 挑战-响应类流程(OAuth state、WebAuthn challenge、SIWE nonce)一律进程内 `map + mutex + TTL + gc`,取用即删(参考 `oauthPending` / `passkeyPending` / `walletPending`);不落库、不引 Redis。TTL 5-10 分钟。
 ## 6. 场景：已鉴权敏感事务的提交屏障
 ### 1. Scope / Trigger
 凡请求先通过 JWT 中间件、随后仍会读取 body、等待外部回调或写入认证/安全配置，
 都必须防止请求处理期间的 Logout、定点撤销或撤销全部会话被旧请求绕过。
 ### 2. Signatures
 ```go
 type TokenProof struct {
    Ver uint
    Jti string
 }
 func tokenProofOf(c *gin.Context) service.TokenProof
 func (s *AuthService) ensureTokenCurrentTx(
    tx *gorm.DB, user *model.User, proof TokenProof,
 ) error
 func (s *AuthService) RenewToken(
    ctx context.Context, username, oldToken string, meta SessionMeta,
 ) (string, time.Time, error)
 ```
 持久化契约使用 `user_sessions.token_id` 表示逻辑会话；敏感换发不改变该 JTI。
 ### 3. Contracts
 - `RequireAuth` 必须把本次请求实际观察到的 `TokenVersion + JTI` 写入 Context，
  Handler 不得事后只按用户名读取“最新版本”代替 proof。
 - 敏感事务、`RevokeSession` 与 Logout 的数据库路径统一先锁用户行，再检查/更新
  会话行；持锁后调用 `ensureTokenCurrentTx`。
 - proof 通过后，认证因子写入、版本递增及事务内换发必须同成同败。需要在 Handler
  末尾换发的旧接口，`RenewToken` 也须重新锁用户并确认当前版本恰为
  `oldClaims.Ver + 1`。
 - 换发沿用旧 JWT 的合法 JTI；有旧会话行时只接续未撤销行，存在但已撤销或更新
  失败必须关闭。兼容期无行 Token 可建行，但仍沿用旧 JTI，因此 Logout 的
  tombstone 能同时撤销换发前后的 JWT。
 - Logout 持久撤销须按 JTI 会话行解析稳定的 `user_id`，不得只按旧 JWT 的可变
  username/subject 找用户；JTI tombstone 至少保留“旧 JWT 剩余寿命 +
  一个完整 `tokenTTL`”，兜住 legacy 无行换发、改名提交和持久化撤销之间的
  窄窗口。
 - 外部身份登录须在用户锁内重查身份仍绑定；OAuth 登录还须在最终签发事务内重查
  Provider 当前可用。
 - proof 不二次检查自然到期：请求在 JWT 未过期时通过中间件即取得本次请求的认证
  边界；不得为此额外引入长事务、分布式锁或持久状态机。
 ### 4. Validation & Error Matrix
 | 条件 | 结果 |
 | --- | --- |
 | `user.TokenVersion != proof.Ver` | `ErrTokenStale` → HTTP 401 |
 | JTI tombstone 命中或会话行已撤销 | `ErrTokenStale` → HTTP 401 |
 | 旧会话行存在但接续命中 0 行 | 失败关闭，不得 fallback 创建 |
 | 已验签当前版本的兼容 Token 确无会话行 | 沿用原 JTI 创建会话行 |
 | 改名后用换发前 JWT Logout | 按 JTI/user_id 撤销新旧 JWT；旧 subject 不参与归属 |
 | Handler 分段换发时版本不是 `oldVer + 1` | `ErrTokenStale`，前端重新登录 |
 | 登录签发前身份已解绑 / Provider 已不可用 | 拒绝登录，不签发 JWT |
 ### 5. Good / Base / Bad Cases
 - Good：TOTP 激活事务内依次锁用户、验 proof、写因子、递增版本、沿用 JTI 换发。
 - Base：无会话行的存量 JWT 可完成一次合法变更，但换发后的 JWT 与旧 JWT 共用
  JTI，后到 Logout 可同时撤销。
 - Bad：proof 普通查询通过后释放锁，定点撤销完成，再把旧行更新失败当“无行”创建
  新会话；这会复活已撤销 Token。
 ### 6. Tests Required
 - TOTP 激活 × 撤销全部：旧 proof 返回 `ErrTokenStale`，因子与版本均不改变。
 - proof check → 定点撤销 → renew：撤销后的行不得被新建替代。
 - recorded 与 legacy 无行会话各测一次“改名后 old-token Logout”：换发 JWT
  必须随同失效；recorded 行写入 `revoked_at`，legacy tombstone 覆盖 fresh expiry。
 - OAuth/钱包登录在最终事务前删除身份：不得签发会话；OAuth 禁用同理。
 - Security/OAuth PATCH 使用已撤销 proof：返回 `ErrTokenStale` 且设置不落库。
 ### 7. Wrong vs Correct
 ```go
 // Wrong：只按最新用户状态改因子，随后无条件签最新版本 JWT。
 saveFactor()
 bumpTokenVersion()
 return IssueToken(ctx, username)
 // Correct：请求 proof、因子写入、版本递增和会话接续共享事务与用户锁。
 return db.Transaction(func(tx *gorm.DB) error {
    user, err := lockUserForAuthChange(tx, username)
    if err != nil { return err }
    if err := auth.ensureTokenCurrentTx(tx, user, proof); err != nil { return err }
    return changeFactorAndRenewTx(tx, user, oldToken)
 })
 ```
 ## 其他约定
 - 面板地址依赖:RP ID / 回调 / SIWE domain 均派生自 `settings.EffectiveAppURL()`,为空时返回引导错误(文案对齐 `ErrOAuthNoAppURL`),不得回退猜测。
 - 登录失败对外文案统一、不透出内部细节(防探测);错误变量集中定义在对应 service 文件头部。
 - 新端点全量 swagger 中文注释并重新生成 docs/;providers 公开端点(`/auth/oauth/providers`)按需追加 `<method>Login` 可用性布尔,供登录页渲染入口。
@@ -27,3 +27,35 @@ go func() {
 - 服务暴露 `Wait()`(内部 `wg.Wait()`);常驻循环(如清理 ticker)额外接收 ctx,`select` 响应退出。
 - cmd/server 装配的 defer 顺序必须是「先停生产者、再等消费者」(LIFO):`defer notifier.Wait()` / `defer systemLogs.Wait()` 写在 `defer tasks.Stop()` / `defer stopCleanup()` **之前**。
 - 陷阱:`cron.Stop()` 返回的 context 要等(`<-s.cron.Stop().Done()`),否则仍在执行的任务尚未 `wg.Add` 时 `Wait()` 会提前返回,goroutine 泄漏且违反 WaitGroup 的 Add/Wait happens-before 约束。
 ## HTTP 处理器不得同步执行长任务
 **问题**:`POST /tasks/:id/run` 曾在处理器内同步跑完整个任务(AI 探测挂上模型验证后单次 24~90s),前端点击后长时间零反馈;且执行入口无并发防护,双击/与 cron 重叠会真跑两次。
 **约定**(task.go `TriggerTask` 为范例):
 - 可能超过 1~2s 的执行,API 只做「异步触发」:校验存在 → 抢占执行权 → 挂 WaitGroup 的 goroutine 执行 → 立即 202;结果落任务日志/通知,由前端轮询呈现。
 - 在飞防重用 `map[uint]bool` + 专属 mutex(`beginRun`/`endRun`):手动重复触发返回哨兵错误(API 映射 409),cron 重叠触发静默跳过。执行权的获取必须在触发方同步完成,不能移进 goroutine(否则有双触发窗口)。
 - 后台执行 goroutine 一律纳入服务的 WaitGroup,`Stop()` 里 `cron.Stop()` 之后追加 `runWG.Wait()` 收尾。
 ## 上游 HTTP 超时:流式/长调用禁用 http.Client.Timeout 总超时
 **问题**(2026-07 responses 直通 60s 断流):`http.Client.Timeout` 覆盖单次请求全生命周期(发起→响应头→**body 读完**)。OCI SDK 默认 60s(`common/client.go` defaultTimeout),对 SSE 流式(读 body 无上限)与 multi-agent/搜索类慢模型(>60s 才回响应头)必然掐断;且超时被 `switchable` 判为可重试,还会误伤渠道熔断计数。
 **约定**(genai_responses.go 为范例):
 - 非流式长调用:`dispatcherWithTimeout` 值拷贝 client 换总超时(保留 Transport,代理链路不受影响),预算走设置项(`ai_upstream_wait_seconds`,缺省 300s)。
 - 流式:总超时必须为 0;等待响应头预算用 `callWithHeaderBudget`(`context.WithCancel` + `time.AfterFunc(wait, cancel)`,响应头到达即 `timer.Stop()`),返回 `cancelReadCloser` 保证流 Close 时取消派生 ctx。流建立后的生命周期交由请求方 ctx(客户端断开自动取消)。
 - SDK 的 Transport 是 `OciHTTPTransportWrapper`,**不是** `*http.Transport`,设不了 `ResponseHeaderTimeout`——用 ctx 定时取消模拟,勿依赖类型断言 Transport。
 - 经租户出口的**所有** HTTP 外呼(不只 SDK 调用,含 SAML 元数据抓取这类裸 http.Client)都必须复用该租户代理;代理配置非法时**失败关闭**报错,不得静默直连暴露服务器 IP(2026-07-22 审查 #7,federation.go `metadataHTTPClient`)。
 - 自建代理 Transport(proxyhttp.go)必须补阶段超时(Dial 30s / TLS 握手 10s,对齐 SDK 直连模板);`http.Transport` 零值这些字段=无超时,总超时一旦去掉就会裸奔。
 ## 出站连接复用与批量删除(2026-07 删桶超时复盘)
 **问题**:每个 OCI 操作都新建 SDK client,代理路径连带每次 new 一个 `http.Transport`——连接零复用,每请求付整条 TCP+SOCKS5+TLS 握手(经代理 3+ RTT ≈ 1s+);且对象存储每操作先远程取一次 namespace,单条 PAR 删除被放大到 ~2.3s,几千条串行删除撑爆 30 分钟 purge 窗口。用完即弃的 Transport 未设 `IdleConnTimeout`(零值=客户端永不关),空闲连接堆到远端 ~65s 超时才断,代理侧稳态挂着几十条连接。
 **约定**:
 - 代理出站 `http.Client` 一律经 proxyhttp.go 的包级 `proxyClients` 缓存(按 ProxySpec 值复用),不得在调用点新建 per-request Transport;共享实例只可包装(dispatcher wrap),不得改写其字段。连接池参数集中在 `pooledTransport()`:`MaxIdleConnsPerHost` 须 ≥ 批量并发数。
 - 租户常量(对象存储 namespace 等)在 `RealClient` 用 `sync.Map` 进程内缓存(照 `limitDefs`/`shapes` 模式),不逐操作远程取。
 - 批量逐条调用统一走 service 层 `forEachConcurrently` + `bulkDeleteWorkers`(16);对应的 SDK 删除请求带 `bulkRetryPolicy`(429/5xx 退避),并发提速与限流保护成对出现,二者缺一不可。
@@ -1,54 +1,32 @@
-# Database Guidelines
+# 数据库规范
-> Database patterns and conventions for this project.
+> GORM + SQLite(可选 MySQL/PostgreSQL)实战约定;模型在 `internal/model/`,连接与 AutoMigrate 在 `internal/database/`。
---
+## 租户级数据删除
-## Overview
+- 租户主体与本地关联数据必须在同一 GORM transaction 中按“子记录→父记录”删除,每步错误用 `%w` 返回,不得忽略。
 - JSON payload/Setting 键等非外键引用要显式枚举并改写;不能只依赖 `AutoMigrate` 或 ORM association 推断级联范围。
 - 与后台任务、Webhook、解析器等并发写入交叉时,先定义全局一致的行锁顺序,并在写入前重新确认父记录存在。
 - 进程内 cron/缓存只在事务提交后同步;客户端取消不应中断已提交删除的必需运行时对齐。
 - 批量删除/清理遇到**无法解析的 JSON payload** 时记 `log.Printf` 警告并跳过该行(原样保留),不 fail-closed 阻断整个流程——坏数据不应把删除逼到手工修库(tenantdelete.go `logSkippedTask`)。
-<!--
+## 大集合谓词用子查询,禁止展开 IN 列表
 Document your project's database conventions here.
-Questions to answer:
+- 行数无上界的集合(日志事件、调用日志等)做关联删除/查询时,一律 `WHERE x IN (SELECT …)` 子查询,**不要**先 Pluck ID 再 `IN ?` 展开:绑定变量有硬上限(modernc SQLite 32766,MySQL/PG 65535),数万行即失败且重试无解。
- What ORM/query library do you use?
+- GORM 写法:把 `tx.Model(&T{}).Select("id").Where(...)` 作为参数传入 `Where("x IN (?)", sub)`(见 tenantdelete.go `deleteAlertHits` / `alertHitRuleIDs`)。
- How are migrations managed?
+- 例外:**同表自删**(删除条件子查询引用被删表)MySQL 报 1093,改按主键排序的固定批次循环删(aigateway.go `cleanupTable`,每批 10000,单批失败记日志退出)。
- What are the naming conventions for tables/columns?
+- 若原本的 Pluck 兼有 `FOR UPDATE` 锁定语义,保留锁定 SELECT 本身,只是不再把结果拼进后续 SQL(`lockTenantEventRows`)。
- How do you handle transactions?
+- 行数有小上界的集合(渠道、规则等配置类)可以继续用内存 ID 列表。
 -->
-(To be filled by the team)
+## Common Mistake: 用 `Save` 持久化在途任务的陈旧快照
---
+**Symptom**:一条记录已被另一事务删除,在途任务随后执行 `Save` 却把该行重新插入,或覆盖并发更新后的 payload。
-## Query Patterns
+**Cause**:GORM `Save` 在 `UPDATE` 零命中时会回退到 `CREATE`/upsert,不适合持久化长时运行开始时读取的快照。
-<!-- How should queries be written? Batch operations? -->
+**Fix**:用 `WHERE id = ? AND updated_at = ?` 的条件 `Updates`,并严格要求 `RowsAffected == 1`;零命中表示记录已删除或版本已变,不得补做 `Create`。
-(To be filled by the team)
+## Common Mistake: gorm 读 NULL 列到已有值的结构体字段不会清零
 ---
 ## Migrations
 <!-- How to create and run migrations -->
 (To be filled by the team)
 ---
 ## Naming Conventions
 <!-- Table names, column names, index names -->
 (To be filled by the team)
 ---
 ## Common Mistakes
 <!-- Database-related mistakes your team has made -->
 ### Common Mistake: gorm 读 NULL 列到已有值的结构体字段不会清零
 **Symptom**:UPDATE 把可空列(如 `*time.Time`)写成 NULL 后,用**同一个结构体变量**再次 `First()` 读回,该字段仍是旧值;而新变量读取正常。断言/返回值出现「幽灵旧值」。
@@ -58,7 +36,7 @@ Questions to answer:
 **Prevention**:凡「UPDATE 后回读返回」的服务方法,都声明新变量接收;测试中多次 `First` 同一行也各用独立变量。另:map Updates 写 NULL 用 `gorm.Expr("NULL")` 最稳(无类型 `nil` 在部分路径下不生效)。
-### Common Mistake: 需要"条件更新多列含 NULL"时的写法
+## Common Mistake: 需要"条件更新多列含 NULL"时的写法
 ```go
 // 正确:零写库条件 + 显式 NULL
@@ -66,3 +44,23 @@ db.Model(&model.AiChannel{}).
    Where("id = ? AND (fail_count > 0 OR disabled_until IS NOT NULL)", id).
    Updates(map[string]any{"fail_count": 0, "disabled_until": gorm.Expr("NULL")})
 ```
 ## `serializer:json` 字段走 map Updates 时手动 marshal
 - 切片/结构体字段用 `gorm:"serializer:json;type:text"` 声明(如 `AiKey.Models []string`),Create/First/struct 路径自动序列化;
 - 但 `Updates(map[string]any{...})` 路径不要依赖 GORM 对 map 值应用 serializer——把值 `json.Marshal` 成 string 放进 map(见 aigateway.go `UpdateKey`),行为版本无关且可测;
 - 存储格式与 serializer 一致(JSON 文本),读回仍走自动反序列化;`nil` 切片 marshal 为 `null`,读回 nil,天然表达「空 = 不限」语义。
 ## Common Mistake: 进程内缓存键漏掉查询维度
 **Symptom**:多区间(compartment)租户在前端切换区间后,实例/卷/VCN 列表短暂显示上一个区间的数据(TTL 窗口内)。
 **Cause**:`internal/oci/cached.go` 的 `ckey` 只拼了租户 OCID+资源名+region,而底层查询按 `cred.EffectiveCompartment()` 过滤——影响结果的维度没有全部进键,不同参数命中同一条缓存。
 **Fix**:键值加入 `cred.CompartmentID`(空 = 租户根,天然区分)。
 **Prevention**:缓存键必须覆盖影响回源结果的**全部**输入维度(租户、区间、区域、过滤参数);给 Credentials/查询结构体新增会改变结果的字段时,同步检查 `ckey` 调用点;隔离行为写进 `cached_test.go` 的 isolation 用例。
 ## GORM 列名与 map 更新
 - GORM 默认命名把连续大写按公共缩写拆分:`UserOCID` → `user_oc_id`、`TenancyOCID` → `tenancy_oc_id`(不是 `user_ocid`)。用 `Updates(map[string]any{...})` 写裸列名前先确认真实列名(`schema.Parse` 或查建表 SQL),SQLite 下写错列名报 "no such column" 才暴露,MySQL/PG 同错。零值字段(如清空 `passphrase_enc`)必须走 map 更新,struct 更新会忽略零值。(2026-07-23 activate-api-key 切换签名用户)
@@ -1,6 +1,6 @@
 # 后端目录结构
-> Go 后端工程的目录职责与代码组织约定。
+> Go 后端工程(`oci-portal/`)的目录职责与代码组织约定。
 ## 目录职责
@@ -30,3 +30,5 @@ oci-portal/
 - `defer` 紧跟资源获取语句,成对管理释放。
 - 结构体初始化写字段名;已知容量的 slice/map 用 `make(T, 0, n)` 预分配。
 - 注释解释"为什么"而非"是什么";导出符号写以名字开头的 godoc 注释。
 - 路由参数:资源 id 可能含 `/` 等 URL 保留字符时(如 OCI PAR id),一律经 query 传递而非路径参数 —— gin 路径段不匹配 `%2F`,会直接 404(2026-07 round6 教训)。
 - OSP Gateway(账单/发票,`internal/oci/billing.go`):服务只在租户主区域提供,每个请求都带 `ospHomeRegion` 且客户端 `SetRegion` 到主区域 —— 主区域公共名经测活 `HomeRegionKey` + `RegionByKey` 解析,勿用凭据 region 直连;SDK 金额是 `*float32`,输出前经 `money()` 四舍五入抹掉 float64 转换噪音;`PayInvoice` 的 `Email` 是 API 必填(付款回执),service 层校验后透传。
@@ -31,3 +31,17 @@ func sanitizeURLError(err error) error {
 ```
 **预防**:凡外发 HTTP 且 URL/头中含凭据(token、签名、secret 路径段)的客户端,错误必须先脱敏再包装;新增此类客户端时补一条「错误不含凭据」的回归测试(参照 internal/service/notify_test.go 的 TestNotifierSendErrorHidesToken)。
 ## OCI 错误按语义分类,不要只看 HTTP 状态码
 **问题**:OCI 同一状态码承载多种语义,按状态码一刀切会误判。已踩过的案例(GenAI 网关):
 - **404 双义**:`NotAuthorizedOrNotFound`(消息 "Authorization failed or requested resource not found")是**租户级**无权限/无策略;"Entity with key … not found" 是**模型级**——该模型 OCID 在此区域无按需供给。前者应定论渠道无配额,后者应剔除该模型换下一个候选。
 - **400 微调基座**:"Not allowed to call finetune base model …, use Endpoint: false" 表示模型在该区域仅作微调基座(dedicated 供给),同样是模型级不可用,不是请求参数错误。
 - `ListModels` **没有字段**能事先区分 on-demand / dedicated 供给,只能在调用报错时习得;持久剔除依赖用户维护的模型黑名单(ai_model_blacklists,按模型名全局过滤,同步/探测不入库),错误消息应带模型名提示用户拉黑。
 **约定**:识别特定语义一律走 `internal/oci/errors.go` 的判定函数(`IsModelUnavailable` / `IsEntityNotFound` / `IsOnDemandUnsupported`),用 `errors.As` 取 `common.ServiceError` 后按 状态码+消息片段 匹配;调用方(探测/网关路由)据此决定「定论、换候选、换渠道、是否计熔断」,不得在业务层散落字符串匹配。
 ## 外部响应体必须限长,超限报错而非静默截断
 读上游/外部响应体一律 `io.LimitReader(max+1)` 再判长度:恰好读到 max+1 说明超限,返回带上限值的错误;不得截断后当成功继续(截断的 JSON/流式响应会以 200 返回坏数据,2026-07-22 审查 #13,genai_responses.go `readCompatBody`)。
@@ -0,0 +1,91 @@
 # IdP 图标上传与清理契约
 ## 1. Scope / Trigger
 - 适用于创建 SAML IdP 前,先把图标上传到 Identity Domains 公共图片存储的流程。
 - 上传先于 IdP 创建,图片在创建成功前是临时远端资源;前端做**尽力清理**,
  孤儿(自己租户里一张无入口小图)可接受,不为它建所有权状态机。
 ## 2. Signatures
 ```text
 POST   /api/v1/oci-configs/{id}/idp-icons?domainId=<optional>
 DELETE /api/v1/oci-configs/{id}/idp-icons?domainId=<optional>&fileName=<required>
 ```
 ```typescript
 uploadIdpIcon(id: number, file: File, domainId?: string): Promise<IdpIconUpload>
 deleteIdpIcon(id: number, fileName: string, domainId?: string): Promise<void>
 interface IdpIconUpload {
  url: string      // 写入 IdP iconUrl 的公网地址
  fileName: string // 仅用于清理的存储标识
 }
 ```
 上游 Identity Domains 契约(SDK 未覆盖,走 BaseClient 裸调):
 ```text
 POST   /storage/v1/Images       multipart: file + fileName
 DELETE /storage/v1/Images       query: fileName
 ```
 ## 3. Contracts
 - POST 的 `file` 是唯一文件字段;文件本体最大 `1 MiB`,由 service 精确限制;
  路由级 body limit 为 multipart 封装开销另留余量,两者不是同一契约。
 - 客户端原始文件名只用于取扩展名。真正上传名由服务端随机生成
  `idp-icon-<32 lowercase hex><lowercase ext>`:既避免并发/迟到响应下同名互相
  覆盖,又让存储名成为不可猜测的清理凭据。
 - 内容校验只做**扩展名白名单 + 文件头魔数嗅探**(png/jpg/jpeg/gif/webp/ico/svg),
  不做深度解码与结构校验:图标由管理员为自己租户上传、由 Oracle 域名托管,
  传错内容只会让自己登录页图标裂开,深度校验的复杂度与误伤承担不起
  (2026-07 曾过度实现完整解码套件后精简)。
 - DELETE 只接受单层 `images/idp-icon-<32 lowercase hex>.<allowed ext>`,
  不得因共享 `images/` 前缀删除其他域资产;上游 404 视为幂等成功,返回 204。
 - 前端上传成功时保存 `{cfgId, domainId, url, fileName}` 原始元组作 pendingIcon,
  用请求序号丢弃迟到响应;替换、放弃表单或提交未引用它时按元组尽力删除,
  失败静默。创建请求引用了它且返回 2xx(含 `201 + setupWarning`)即视为已采用。
 - IdP 创建是多步远端事务:创建后 JIT 映射失败先回滚删除刚创建的禁用 IdP;
  回滚成功按普通失败,回滚失败/无法确认返回 `201` 和
  `setupWarning{code: JIT_SETUP_INCOMPLETE, resourceCreated, requestId}`;
  内部原因只按 requestId 写服务端日志,不进响应。
 - 前端在身份设置加载完成前禁用提交;后端创建前再次读取域设置,
  `primaryEmailRequired=true` 强制 JIT 邮箱映射,查询失败时不创建 IdP。
 ## 4. Validation & Error Matrix
 | 条件 | HTTP |
 | --- | --- |
 | 缺少 multipart `file`、文件为空或文件名非法 | 400 |
 | 文件本体超过 1 MiB | 413 |
 | 扩展名不支持或与文件头魔数不符 | 415 |
 | DELETE 缺少 `fileName` 或不是本服务生成的图标名 | 400 |
 | 上游 DELETE 返回 404 | 204 |
 | IdP 创建后 JIT 失败且回滚无法确认 | 201 + `setupWarning` |
 | 其余上游/内部错误 | 统一错误边界,不泄露上游响应正文 |
 ## 5. Tests / Verification Required
 - 完整路由:恰好 1 MiB → 200、1 MiB+1 → 413、空文件 → 400、伪造扩展名 → 415。
 - 存储名:相同原始名连续上传得到不同随机名;熵源失败不调用上游;
  DELETE 拒绝非 IdP 前缀、子目录、错误 token 长度/大小写与非允许扩展。
 - 魔数:各允许格式最小样本通过,扩展名与内容不符、未知扩展名被拒。
 - 多步创建:初始创建失败、JIT 失败且回滚成功、回滚失败/ID 缺失三分支;
  后两者分别锁定普通失败与 `setupWarning` 契约,响应不泄露底层 cause。
 - 域设置:主邮箱必填强制映射、设置查询失败零创建、关闭 JIT 跳过查询。
 ## 6. Wrong vs Correct
 ```typescript
 // Wrong:用清理时的 props 删旧图标——弹窗可能已切到别的租户/域。
 onBeforeUnmount(() => deleteIdpIcon(props.cfgId, uploaded.fileName, props.domainId))
 // Correct:上传时捕获原始元组,清理只按元组走,失败静默。
 pendingIcon = { ...uploaded, cfgId, domainId }
 void deleteIdpIcon(pendingIcon.cfgId, pendingIcon.fileName, pendingIcon.domainId).catch(() => {})
 ```
 反例(勿复现):为图标这种低价值临时资源实现「冻结所有权 + 结果未知协议 +
 卸载钩子」的完整状态机,或对上传内容做完整解码/结构/主动内容校验——
 复杂度与威胁模型不匹配,已于 2026-07 精简移除。
@@ -1,6 +1,6 @@
 # Backend Development Guidelines(oci-portal 后端规范)
-> Go 后端(`oci-portal/`)编码规范入口。规范提炼自 Google / Uber Go Style Guide、Effective Go 与 Go 官方模块布局指南,按本项目裁剪;条目与项目约定冲突时,以本 spec 为准。
+> Go 后端(`oci-portal/`)编码规范入口。
 ---
@@ -19,9 +19,10 @@ Gin + GORM + SQLite(纯 Go 驱动 `glebarez/sqlite`,免 CGO;默认与推荐)+ AE
 | [Quality Guidelines](./quality-guidelines.md) | 工具链检查与命名规范 | 已填 |
 | [Concurrency](./concurrency.md) | goroutine 生命周期与 context 传递 | 已填 |
 | [Testing](./testing.md) | table-driven 测试要求 | 已填 |
-| [Database Guidelines](./database-guidelines.md) | ORM 模式、查询、迁移 | 待填 |
+| [IdP Icon Upload](./idp-icon-upload.md) | IdP 公共图标上传、校验与清理契约 | 已填 |
 | [Database Guidelines](./database-guidelines.md) | GORM 实战约定与常见坑 | 已填 |
 | [OCI Audit](./oci-audit.md) | 审计事件双通道数据源、检索语义与预算纪律 | 已填 |
-| [Logging Guidelines](./logging-guidelines.md) | 结构化日志、日志级别 | 待填 |
+| [Auth Login Methods](./auth-login-methods.md) | 登录方式接入契约(守卫/留痕/令牌版本/不变量/一次性挑战) | 已填 |
 ---
@@ -32,7 +33,7 @@ Gin + GORM + SQLite(纯 Go 驱动 `glebarez/sqlite`,免 CGO;默认与推荐)+ AE
 - [ ] 读过 [Directory Structure](./directory-structure.md),新代码放对了包(云请求只出现在 `internal/oci/`)
 - [ ] 阻塞 / 远程调用函数第一个参数是 `ctx context.Context`(见 [Concurrency](./concurrency.md))
 - [ ] 错误按 [Error Handling](./error-handling.md) 用 `%w` 包装向上返回
- [ ] 复用已有封装,不重复造轮子(见 `../guides/code-reuse-thinking-guide.md`)
+- [ ] 复用已有封装,不重复造轮子(动手前先 grep 相似函数 / 常量 / 模式)
 ## Quality Check
@@ -1,51 +0,0 @@
 # Logging Guidelines
 > How logging is done in this project.
 ---
 ## Overview
 <!--
 Document your project's logging conventions here.
 Questions to answer:
 - What logging library do you use?
 - What are the log levels and when to use each?
 - What should be logged?
 - What should NOT be logged (PII, secrets)?
 -->
 (To be filled by the team)
 ---
 ## Log Levels
 <!-- When to use each level: debug, info, warn, error -->
 (To be filled by the team)
 ---
 ## Structured Logging
 <!-- Log format, required fields -->
 (To be filled by the team)
 ---
 ## What to Log
 <!-- Important events to log -->
 (To be filled by the team)
 ---
 ## What NOT to Log
 <!-- Sensitive data, PII, secrets -->
 (To be filled by the team)
@@ -17,3 +17,10 @@
 - 单批双预算:页数(`maxAuditPages`)+ 时间(`auditBatchTimeBudget`≈20s)。全文检索命中稀疏时大窗扫描单页可达十余秒,没有时间预算会出现 3 分钟级单请求。
 - 空窗按倍增扩窗(上限受 14 天查询窗约束);响应回传 `scannedThrough` 供前端展示回溯进度,前端自动补批必须封顶,由用户显式继续。
 ## 日志回传链路(logrelay)资源命名与描述纪律
 - **命名派生**:Topic 前缀、IAM Policy 名、SCH Connector DisplayName 一律由 `relayResourceNames(tenancyOCID)`(见 `internal/oci/logrelay_names.go`)基于 `SHA-256(tenancyOCID)[:4]` 派生 `<8hex>-audit` / `<8hex>-audit-p`。**不得在 `logrelay.go` 里再引入品牌明文**(`oci-portal` / `ociportal` / `logs` 等),否则跨租户恒定字面量会成为 Oracle 内部风控识别「共用同一套 oci-portal」的强指纹;背景与证据分档见工作区任务归档 `.trellis/tasks/archive/2026-07/07-22-research-oci-caller-info/research/oci-sdk-caller-fingerprint.md`。
 - **描述文本**:Topic 与 Policy 的 `Description` 用集中常量 `relayTopicDescNew` / `relayPolicyDescNew`(中性英文),不允许写 `oci-portal 日志回传:...` 等品牌/中文明文;SCH Connector 干脆不设 `Description`,避免恒定文案。
 - **向后兼容 legacy 命名**:`findRelayTopic` / `findRelayPolicy` / `findRelayConnector` 支持传入多前缀/多名称,顺序为「新命名 → legacy 命名」;新增查找需求要沿用变参签名,不要单独硬编码 legacy 常量到业务函数里。命中 legacy 资源时,`refreshRelayTopicDesc` / `refreshRelayPolicyDesc` 会尽力刷新描述为中性文案,失败不阻塞主流程(权限/服务限流等场景直接忽略)。
 - **测试**:命名派生、legacy 常量值、描述中性性由 `logrelay_names_test.go` table-driven 锁定;若必须调整 legacy 常量,先评估是否会让存量租户找不到既有资源导致重复创建。
@@ -16,3 +16,18 @@
 - Getter 不加 `Get` 前缀:`user.Name()` 而非 `user.GetName()`。
 - 方法接收者 1~2 个字母且同一类型内保持一致,如 `func (s *InstanceService)`。
 - 错误变量:导出 sentinel 用 `ErrXxx`,包内用 `errXxx`;自定义错误类型以 `Error` 结尾。
 ## JSON 联合类型与内容留档保真(2026-07 内容日志失真教训)
 - aiwire 里兼容多形态的联合类型(如 `RespInput` string|数组)**必须成对实现**
  `UnmarshalJSON` 与 `MarshalJSON`:只写 Unmarshal 时,任何再序列化(内容日志、
  测试快照)都会退化成 Go 字段名形态(`{"Text":"","Items":[...],"IsArray":true}`),
  排障者复制它复现会直接 400。参考 `aiwire/openai.go Content` 的保形写法,
  往返用 table-driven 测试锁定(`aiwire/responses_test.go`)。
 - 留档「客户端请求正文」优先存**原始字节**(`json.RawMessage(raw)`),不要存解析
  后的结构体:直通端点未建模字段会被结构体序列化悄悄丢掉。`json.Marshal` 对
  RawMessage 会 compact(去空白),字段顺序与内容保持原样,符合保真要求。
 ## 多字段设置接口用字段级 PATCH,不用全量 PUT
 「改一存一」交互的设置面板(安全设置、OAuth provider 等)服务端用字段级 PATCH:DTO 全指针字段,nil=沿用现值,只落库出现的字段(合并到现值后整体校验);全量 PUT 下并发编辑各自基于旧快照,后到请求会回滚他人字段、复活已清空配置(2026-07-22 审查 #18,security.go `SecurityPatch` / oauthconfig.go `UpdateOAuthInput`)。
@@ -6,6 +6,26 @@
 - 断言失败时输出 `got/want` 对比,便于定位。
 - 辅助函数标注 `t.Helper()`,清理动作用 `t.Cleanup()`。
 ## 上传接口边界测试
 - “文件最大 N 字节”与 HTTP 请求体上限不是同一个契约:multipart boundary、
  part header 和文件名会额外占空间。路由级 body limit 必须为封装开销留余量,
  service 再对文件字节数执行精确上限。
 - 新增或修改上传接口时,完整路由测试至少覆盖:恰好 N 字节成功、N+1 返回
  413、空文件返回 400、伪造扩展名返回 415。
 - 内容校验深度与威胁模型匹配:管理员向自己租户上传、由上游域名托管的低价值
  资源,扩展名白名单 + 魔数嗅探即可,不引入完整解码/结构校验
  (2026-07 IdP 图标曾过度实现后精简,见 idp-icon-upload.md)。
 - 临时远端资源使用服务端随机名,测试相同客户端文件名不会复用上游对象;清理接口
  只接受该功能生成的不可猜测标识,不能因共享 `images/` 前缀删除其他业务资产。
 ## 多步远端写入测试
 - `创建 A → 配置 B` 这类流程至少覆盖:创建失败、B 失败且 A 回滚成功、B 失败且
  A 回滚失败/状态未知。只有确认回滚成功才能返回普通失败。
 - 部分成功响应必须有稳定机器码和关联 ID,前端据此保留已被 A 引用的临时资源;
  底层上游错误只进服务端日志,测试断言不会泄露到 HTTP body。
 ## 常见坑:`:memory:` SQLite 每个连接是独立库
 **症状**:被测代码里有异步 goroutine 写库(如日志异步落库)时,测试偶发 `no such table: xxx`。
@@ -20,4 +40,3 @@ sqlDB.SetMaxOpenConns(1) // :memory: 每连接独立库,异步写复用同一连
 ```
 **预防**:测试涉及「后台 goroutine 写库」时一律加此设置(参照 internal/api/router_test.go 与 internal/service 各测试 helper);异步写路径同时拆出同步内核函数(如 `record` / `Record`)供测试直调断言。
@@ -1,223 +0,0 @@
 # Code Reuse Thinking Guide
 > **Purpose**: Stop and think before creating new code - does it already exist?
 ---
 ## The Problem
 **Duplicated code is the #1 source of inconsistency bugs.**
 When you copy-paste or rewrite existing logic:
 - Bug fixes don't propagate
 - Behavior diverges over time
 - Codebase becomes harder to understand
 ---
 ## Before Writing New Code
 ### Step 1: Search First
 ```bash
 # Search for similar function names
 grep -r "functionName" .
 # Search for similar logic
 grep -r "keyword" .
 ```
 ### Step 2: Ask These Questions
 | Question | If Yes... |
 |----------|-----------|
 | Does a similar function exist? | Use or extend it |
 | Is this pattern used elsewhere? | Follow the existing pattern |
 | Could this be a shared utility? | Create it in the right place |
 | Am I copying code from another file? | **STOP** - extract to shared |
 ---
 ## Common Duplication Patterns
 ### Pattern 1: Copy-Paste Functions
 **Bad**: Copying a validation function to another file
 **Good**: Extract to shared utilities, import where needed
 ### Pattern 2: Similar Components
 **Bad**: Creating a new component that's 80% similar to existing
 **Good**: Extend existing component with props/variants
 ### Pattern 3: Repeated Constants
 **Bad**: Defining the same constant in multiple files
 **Good**: Single source of truth, import everywhere
 ### Pattern 4: Repeated Payload Field Extraction
 **Bad**: Multiple consumers cast the same JSON/event fields locally:
 ```typescript
 const description = (ev as { description?: string }).description;
 const context = (ev as { context?: ContextEntry[] }).context;
 ```
 This is duplicated contract logic even when the code is only two lines. Each
 consumer now has its own definition of what a valid payload means.
 **Good**: Put the decoder, type guard, or projection next to the data owner:
 ```typescript
 if (isThreadEvent(ev)) {
  renderThreadEvent(ev);
 }
 ```
 **Rule**: If the same untyped payload field is read in 2+ places, create a
 shared type guard / normalizer / projection before adding a third reader.
 ---
 ## When to Abstract
 **Abstract when**:
 - Same code appears 3+ times
 - Logic is complex enough to have bugs
 - Multiple people might need this
 **Don't abstract when**:
 - Only used once
 - Trivial one-liner
 - Abstraction would be more complex than duplication
 ---
 ## After Batch Modifications
 When you've made similar changes to multiple files:
 1. **Review**: Did you catch all instances?
 2. **Search**: Run grep to find any missed
 3. **Consider**: Should this be abstracted?
 ### Reducers Should Use Exhaustive Structure
 When state is derived from action-like values (`action`, `kind`, `status`,
 `phase`), prefer a reducer with one `switch` over scattered `if/else` updates.
 ```typescript
 // BAD - action-specific state transitions are hard to audit
 if (action === "opened") { ... }
 else if (action === "comment") { ... }
 else if (action === "status") { ... }
 // GOOD - one reducer owns the transition table
 switch (event.action) {
  case "opened":
    ...
    return;
  case "comment":
    ...
    return;
 }
 ```
 This matters when the event log is the source of truth. A reducer is the
 documented replay model; display code and commands should not duplicate pieces
 of that replay model.
 ---
 ## Checklist Before Commit
 - [ ] Searched for existing similar code
 - [ ] No copy-pasted logic that should be shared
 - [ ] No repeated untyped payload field extraction outside a shared decoder
 - [ ] Constants defined in one place
 - [ ] Similar patterns follow same structure
 - [ ] Reducer/action transitions live in one reducer or command dispatcher
 ---
 ## Gotcha: Python if/elif/else Exhaustive Check
 **Problem**: Python's if/elif/else chains have no compile-time exhaustive check. When you add a new value to a `Literal` type (e.g., `Platform`), existing if/elif/else chains silently fall through to `else` with wrong defaults.
 **Symptom**: New platform works partially — some methods return Claude defaults instead of platform-specific values. No error is raised.
 **Example** (`cli_adapter.py`):
 ```python
 # BAD: "gemini" falls through to else, returns "claude"
@property
 def cli_name(self) -> str:
    if self.platform == "opencode":
        return "opencode"
    else:
        return "claude"  # gemini silently gets "claude"!
 # GOOD: explicit branch for every platform
@property
 def cli_name(self) -> str:
    if self.platform == "opencode":
        return "opencode"
    elif self.platform == "gemini":
        return "gemini"
    else:
        return "claude"
 ```
 **Prevention**: When adding a new value to a Python `Literal` type, search for ALL if/elif/else chains that switch on that type and add explicit branches. Don't rely on `else` being correct for new values.
 ---
 ## Gotcha: Asymmetric Mechanisms Producing Same Output
 **Problem**: When two different mechanisms must produce the same file set (e.g., recursive directory copy for init vs. manual `files.set()` for update), structural changes (renaming, moving, adding subdirectories) only propagate through the automatic mechanism. The manual one silently drifts.
 **Symptom**: Init works perfectly, but update creates files at wrong paths or misses files entirely.
 **Prevention**:
 - **Best**: Eliminate the asymmetry — have the manual path call the automatic one (e.g., `collectTemplateFiles()` calls `getAllScripts()` instead of maintaining its own list)
 - **If asymmetry is unavoidable**: Add a regression test that compares outputs from both mechanisms
 - When migrating directory structures, search for ALL code paths that reference the old structure
 **Real example**: `trellis update` had a manual `files.set()` list for 11 scripts that `getAllScripts()` already tracked. Fix: replaced the manual list with a `for..of getAllScripts()` loop. See `update.ts` refactor in v0.4.0-beta.3.
 ---
 ## Template File Registration (Trellis-specific)
 When adding new files to `src/templates/trellis/scripts/`:
 **Single registration point**: `src/templates/trellis/index.ts`
 1. Add `export const xxxScript = readTemplate("scripts/path/file.py");`
 2. Add to `getAllScripts()` Map
 That's it. `commands/update.ts` uses `getAllScripts()` directly — no manual sync needed.
 **Why this matters**: Without registration in `getAllScripts()`, `trellis update` won't sync the file to user projects. Bug fixes and features won't propagate.
 **History**: Before v0.4.0-beta.3, `update.ts` had its own hand-maintained file list that frequently fell out of sync with `getAllScripts()`. This caused 11 Python files to be silently skipped during `trellis update`. The fix was to eliminate the duplicate list and use `getAllScripts()` as the single source of truth.
 ### Quick Checklist for New Scripts
 ```bash
 # After adding a new .py file, verify it's in getAllScripts():
 grep -l "newFileName" src/templates/trellis/index.ts  # Should match
 ```
 ### Template Sync Convention
 `.trellis/scripts/` (dogfooded) and `packages/cli/src/templates/trellis/scripts/` (template) must stay identical. After editing `.trellis/scripts/`, always sync:
 ```bash
 rsync -av --delete --exclude='__pycache__' .trellis/scripts/ packages/cli/src/templates/trellis/scripts/
 ```
 **Gotcha**: Running rsync with wrong source/destination paths can create nested garbage directories (e.g., `.trellis/scripts/packages/cli/...`). Always double-check paths before running.
@@ -183,7 +183,7 @@ Complex task: ask the user if you can create a Trellis task and enter the planni
 - 1.0 Create task `[required · once]` (only after task-creation consent)
 - 1.1 Requirement exploration `[required · repeatable]` (`prd.md`; complex tasks also need `design.md` + `implement.md`)
 - 1.2 Research `[optional · repeatable]`
- 1.3 Configure context `[required · once]` — Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Reasonix (sub-agent-dispatch platforms only; inline platforms skip)
+- 1.3 Configure context `[required · once]` — Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Grok, Kimi Code (sub-agent-dispatch platforms only; inline platforms skip)
 - 1.4 Activate task `[required · once]` (review gate, then `task.py start`; status → in_progress)
 - 1.5 Completion criteria
@@ -220,7 +220,7 @@ Inline mode: skip jsonl curation; Phase 2 reads artifacts/specs via `trellis-bef
     therefore must cover every required step from implementation through
     commit, including Phase 3.3 spec update and Phase 3.4 commit. -->
-Sub-agent dispatch protocol applies to all platforms and all sub-agents, including class-2 Codex/Gemini/Qoder/Copilot/ZCode/Reasonix/Trae and `trellis-research`: every dispatch prompt starts with `Active task: <task path from task.py current>` before role-specific instructions.
+Sub-agent dispatch protocol applies to all platforms and all sub-agents, including native Codex `SubagentStart` context injection with child-side pull fallback, class-2 Gemini/Qoder/Copilot/Reasonix/Trae/Grok/Kimi Code, hook-backed ZCode/Snow, and `trellis-research`: every dispatch prompt starts with `Active task: <task path from task.py current>` before role-specific instructions. On Grok Build, use `spawn_subagent` with `subagent_type` set to the Trellis agent name (e.g. `trellis-implement`). On Kimi Code, dispatch the built-in `coder` / `explore` sub-agent with the matching `.kimi-code/skills/trellis-<role>/SKILL.md` instructions.
 [workflow-state:in_progress]
 Tools: `trellis-implement` / `trellis-research` are sub-agent types only (Task/Agent tool, NOT Skill; there is no skill by these names). `trellis-update-spec` is a skill. `trellis-check` exists as both; prefer the Agent form when verifying after code changes.
@@ -272,13 +272,13 @@ Code committed. Run `/trellis:finish-work`; if dirty, return to Phase 3.4 first.
 When a user request matches one of these intents inside an active task, route first, then load the detailed phase step if needed.
-[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Reasonix, Trae]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
 - Planning or unclear requirements -> `trellis-brainstorm`.
 - `in_progress` implementation/check -> dispatch `trellis-implement` / `trellis-check`.
 - Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`.
-[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Reasonix, Trae]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
 [codex-inline, Kilo, Antigravity, Devin]
@@ -353,7 +353,7 @@ Return to this step whenever requirements change and revise the relevant artifac
 Research can happen at any time during requirement exploration. It isn't limited to local code — you can use any available tool (MCP servers, skills, web search, etc.) to look up external information, including third-party library docs, industry practices, API references, etc.
-[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Reasonix, Trae]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
 Spawn the research sub-agent:
@@ -361,11 +361,11 @@ Spawn the research sub-agent:
 - **Task description**: Research <specific question>
 - **Key requirement**: Research output MUST be persisted to `{TASK_DIR}/research/`
-[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Reasonix, Trae]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
 [codex-inline, Kilo, Antigravity, Devin]
-Do the research in the main session directly and write findings into `{TASK_DIR}/research/`. (For `codex-inline` this avoids the `fork_turns="none"` isolation that prevents `trellis-research` sub-agents from resolving the active task path.)
+Do the research in the main session directly and write findings into `{TASK_DIR}/research/`. `codex-inline` is the explicit mode that keeps work in the main session.
 [/codex-inline, Kilo, Antigravity, Devin]
@@ -380,7 +380,7 @@ Brainstorm and research can interleave freely — pause to research a technical
 #### 1.3 Configure context `[required · once]`
-[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Reasonix, Trae]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
 Curate `implement.jsonl` and `check.jsonl` so the Phase 2 sub-agents get the right spec/research context. These files were seeded on `task create` with a single self-describing `_example` line; your job here is to fill in real entries.
@@ -425,7 +425,7 @@ Ready gate: both `implement.jsonl` and `check.jsonl` must contain at least one r
 Skip this step only when both files already have real curated entries.
-[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Reasonix, Trae]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
 [codex-inline, Kilo, Antigravity, Devin]
@@ -458,11 +458,11 @@ If `task.py start` errors with a session-identity message (no context key from h
 | `design.md` exists (complex tasks) | ✅ |
 | `implement.md` exists (complex tasks) | ✅ |
-[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Reasonix, Trae]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
 | `implement.jsonl` and `check.jsonl` each contain at least one real curated entry (seed row does not count) | ✅ |
-[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Reasonix, Trae]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
 ---
@@ -472,21 +472,22 @@ Goal: turn reviewed planning artifacts into code that passes quality checks.
 #### 2.1 Implement `[required · repeatable]`
-[Claude Code, Cursor, OpenCode, CodeBuddy, Droid, Pi, Oh My Pi]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, CodeBuddy, Droid, Pi, ZCode, Snow, Oh My Pi]
 Spawn the implement sub-agent:
 - **Agent type**: `trellis-implement`
 - **Task description**: Implement the reviewed task artifacts, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-implement` sub-agent and must implement directly, not spawn another `trellis-implement` / `trellis-check`.
+- **Dispatch prompt guard**: The prompt MUST start with `Active task: <task path>`, then tell the spawned agent it is already the `trellis-implement` sub-agent and must implement directly, not spawn another `trellis-implement` / `trellis-check`.
 The platform hook/plugin auto-handles:
 - Reads `implement.jsonl` and injects referenced spec/research files into the agent prompt
 - Injects `prd.md`, `design.md` if present, and `implement.md` if present
 - For Codex, `SubagentStart` supplies native context injection; the agent profile keeps child-side loading as the fallback
-[/Claude Code, Cursor, OpenCode, CodeBuddy, Droid, Pi, Oh My Pi]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, CodeBuddy, Droid, Pi, ZCode, Snow, Oh My Pi]
-[codex-sub-agent, Gemini, Qoder, Copilot, ZCode, Reasonix, Trae]
+[Gemini, Qoder, Copilot, Reasonix, Trae, Grok, Kimi Code]
 Spawn the implement sub-agent:
@@ -498,7 +499,7 @@ The pull-based sub-agent definition auto-handles the context load requirement:
 - Resolves the active task with `task.py current --source`, then reads `prd.md`, `design.md` if present, and `implement.md` if present
 - Reads `implement.jsonl` and requires the agent to load each referenced spec/research file before coding
-[/codex-sub-agent, Gemini, Qoder, Copilot, ZCode, Reasonix, Trae]
+[/Gemini, Qoder, Copilot, Reasonix, Trae, Grok, Kimi Code]
 [Kiro]
@@ -526,13 +527,13 @@ The platform prelude auto-handles the context load requirement:
 #### 2.2 Quality check `[required · repeatable]`
-[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Reasonix, Trae]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
 Spawn the check sub-agent:
 - **Agent type**: `trellis-check`
 - **Task description**: Review all code changes against specs and task artifacts; fix any findings directly; ensure lint and type-check pass
- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-check` sub-agent and must review/fix directly, not spawn another `trellis-check` / `trellis-implement`.
+- **Dispatch prompt guard**: The prompt MUST start with `Active task: <task path>`, then tell the spawned agent it is already the `trellis-check` sub-agent and must review/fix directly, not spawn another `trellis-check` / `trellis-implement`.
 The check agent's job:
 - Review code changes against specs
@@ -540,7 +541,7 @@ The check agent's job:
 - Auto-fix issues it finds
 - Run lint and typecheck to verify
-[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Reasonix, Trae]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
 [codex-inline, Kilo, Antigravity, Devin]
@@ -2,6 +2,89 @@
 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)（版本段不记日期），版本号遵循语义化版本。
 ## [0.8.3]
 ### Added
 - 新增通行密钥（Passkey / WebAuthn）注册、管理与免用户名登录，要求验证器完成用户验证；新增 Web3 钱包绑定与 EIP-4361 签名登录，支持浏览器注入的 EOA 钱包
 - 新增活跃会话管理：按登录方式、客户端 IP、User-Agent 与最近活跃时间查看当前账号会话，可定点撤销其他会话；敏感变更换发令牌时接续原会话，升级前签发的存量令牌保持兼容
 ### Changed
 - 租户 API Key 激活接口支持切换到租户内其他 IAM 用户，验证新密钥可用后同步更新面板签名用户与凭据
 - 禁用密码登录时将通行密钥计入可用免密方式，并阻止删除最后一种可用登录方式，避免账号自锁
 ### Fixed
 - 同一实例的终止与电源操作增加飞行期互斥，重复请求稳定返回 409，避免并发执行相互冲突的生命周期操作
 ## [0.8.2]
 ### Added
 - 租户 IAM 用户新增 API Key 管理：支持列出密钥并标注当前签名凭据、提供 OCI CLI 配置模板、由服务端生成 RSA-2048 密钥对并上传公钥（私钥仅在创建响应中返回），以及按指纹删除单把密钥；新密钥可在验证 OCI 可用后启用为面板签名凭据并加密保存，旧密钥保留，当前在用密钥禁止直接删除
 ### Changed
 - 升级 OCI Go SDK 至 v65.121.1
 ## [0.8.1]
 ### Added
 - 身份提供商管理新增图标上传与删除：支持 PNG / JPEG / GIF / SVG / WebP / ICO，限制 1 MB，并校验扩展名与文件内容；图片存入身份域公共存储，返回可用于 `iconUrl` 的地址及后续清理所需的 `fileName`
 ### Changed
 - 安全设置与 OAuth Provider 配置接口由全量 `PUT` 改为字段级 `PATCH`，仅更新请求中出现的字段，避免并发编辑时回滚其他设置；密钥字段仍支持缺省沿用、空串清除
 - 对象存储桶级 PAR 新增只读 `AnyObjectRead` 与只写 `AnyObjectWrite`，有效期上限由 30 天放宽到 100 年；仅含读取能力的桶级链接开放对象列举，非法类型或有效期稳定返回 400
 ### Fixed
 - 修复总览将不同币种成本直接相加；响应新增按币种拆分的 `series`，顶层字段保持主币种兼容口径
 - 修复抢机任务编辑把剩余台数误当目标台数、丢失已完成进度或鉴权失败计数；任务更新增加乐观并发保护，状态已变化时返回 409 而不覆盖执行结果
 - 修复对象内容保存实际受统一 1 MB 请求体限制、无法达到声明的 5 MB 上限；非空桶后台删除现会中止未完成分片上传，并合并同桶重复清空请求
 - 修复 SAML IdP 创建与启用边界：域要求主邮箱时自动补邮箱映射，JIT 后置配置失败会尝试回滚并在无法确认时返回 `setupWarning`，首次 IdP 可正确加入默认登录策略，免 MFA 规则补齐 OCI consent 字段
 - 修复 AI 网关超大非流式响应被截断后仍按成功返回、内容日志关闭后在途请求仍写入正文，以及大量 AI 日志清理 / 租户删除可能触发数据库参数上限
 ### Security
 - 日志回传 Topic / Policy / Connector 改为按租户派生的中性名称并移除品牌描述，降低跨租户固定指纹；旧命名资源仍可识别复用
 - 租户导入在首次 OCI 请求前即校验并应用指定代理，SAML 元数据下载同样复用租户代理且非法配置失败关闭；禁用密码登录与解绑外部身份改为事务串行校验，防止并发操作导致账号失去全部登录方式
 ## [0.8.0]
 ### Added
 - 新增对象存储管理：支持按区域 / 区间创建存储桶（可选可见性、存储层和版本控制），后续可更新可见性 / 版本控制；对象支持按虚拟目录分页浏览、删除、重命名、查看元数据和取回 Archive，非空桶可转后台清空全部对象版本与 PAR 后删除
 - 新增对象内容中转接口：小文件预览与编辑不再签发 PAR，读取上限 20 MB、写入上限 5 MB，保存支持 `If-Match` 并发保护；上传、下载和分享继续使用 PAR 直连
 - 新增对象存储 PAR 管理：支持对象级只读 / 只写 / 读写链接和桶级读写（`AnyObjectReadWrite`）链接、自定义有效期、游标分页、单条 / 全部删除；桶级链接允许列举对象
 - 新增账单管理（OSP Gateway，仅主区域）：按自然年查询发票、查看费用明细、下载 PDF、查看付款方式，并可使用默认付款方式提交在线支付
 - 新增保留公网 IP 管理：支持按区间列出、创建、绑定 / 解绑和删除；创建实例或附加 VNIC 时可在资源就绪后自动绑定，并新增指定 VNIC 更换临时公网 IP
 ### Changed
 - 成本 / 用量查询新增 `HOURLY` 粒度和双维度分组（如 `service,skuName`），响应通过 `subValue` 返回第二维，支持「今天」小时视图与服务下的 SKU 明细
 - 主网卡或次要 VNIC 更换公网 IP 时，如原地址为保留 IP，改为自动解绑并保留该地址，再分配新的临时 IP（此前会拒绝操作）
 - 对象存储 namespace 与代理出站客户端改为进程内复用，对象版本 / PAR 清理由固定并发执行，显著降低大量对象或分享链接场景下的删桶耗时与连接开销
 ### Fixed
 - 修复 `HOURLY` 成本查询因 OCI Usage API 将起点下扩到 UTC 当日而夹带窗口外数据；服务端现严格按 `[startTime, endTime)` 过滤返回行
 - 修复 VCN 级联删除遗漏网络安全组（NSG），导致其他资源已清理后仍因关联关系返回 409
 - 修复区间缓存未保存 / 返回 `parentId`，导致多层区间在前端被平铺；旧缓存检测到层级缺失时会自动实时刷新并回写
 ## [0.7.3]
 ### Changed
 - `LaunchInstance` 移出回传关键事件清单（Connector 过滤条件与「云端事件」告警白名单共用）：创建以面板自身（手动 / 抢机反复尝试）发起为主，回传即噪声（高频抢机可在一两天内刷掉 2 万条存量上限）；终止与电源操作等外部风险信号保留。链路幂等创建新增过滤条件对账，存量链路在租户详情点「一键创建」即原地更新条件，无需拆除重建
 - 实例规格清单（ListShapes）透传 OCI `quotaNames`（与 compute limits 配额名同名），供前端数据驱动配额与可用域可用性判定
 ### Fixed
 - 修复「云端事件」实例生命周期通知从未生效：Audit v2 计算类事件类型带 `.begin` / `.end` 阶段后缀（如 `…ComputeApi.LaunchInstance.end`），事件短名取末段得到 `begin` / `end`，不在关键事件集合内而被跳过。现剥离阶段后缀判定，成对事件只推 `.begin`（携带操作者 / IP / 成败；`.end` 无操作者且信息重复）；`X failed with response 'Err'` 形态消息判为失败并提取引号内错误码作告警补充说明；告警资源名在 `resourceName` 缺失时回退外层 `source`（实例名）
 ## [0.7.2]
 ### Added
@@ -1 +1 @@
-v0.7.2
+v0.8.3
@@ -13,12 +13,10 @@
 [界面预览](#界面预览) · [核心能力](#核心能力) · [快速开始](#快速开始) · [生产部署](#生产部署) · [AI 网关](#ai-网关) · [开发](#开发)
-[AI 网关文档](docs/AI网关.md) · [OpenAPI](docs/swagger.yaml) · [更新日志](CHANGELOG.md) · [前端仓库](https://github.com/wangdefaa/oci-portal-dash)
+[AI 网关文档](docs/AI网关.md) · [OCI 调用者指纹评估](docs/OCI调用者指纹评估.md) · [OpenAPI](docs/swagger.yaml) · [更新日志](CHANGELOG.md) · [前端仓库](https://github.com/wangdefaa/oci-portal-dash)
 </div>
 OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和 OCI GenAI 渠道集中到一个管理界面。Vue 前端通过 `go:embed` 嵌入 Go 服务，Release 以单个二进制和多架构容器镜像交付。
 本仓库为后端与发行仓库；前端源码位于 [oci-portal-dash](https://github.com/wangdefaa/oci-portal-dash)。
 ## 界面预览
@@ -48,11 +46,13 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和
 | 能力域 | 覆盖范围 |
 | --- | --- |
-| **租户与云资源** | 多 OCI API Key、分组、批量测活、账户画像、订阅区域缓存与切换；实例创建与电源操作、VNIC、公网 IP、IPv6、VCN、安全列表、引导卷、块存储挂载、限额与成本查询 |
+| **租户与云资源** | 多 OCI API Key、分组、批量测活、账户画像、订阅区域缓存与切换；实例创建与电源操作、VNIC、公网 IP、保留 IP、IPv6、VCN、安全列表（规则行内编辑）、引导卷、块存储挂载、对象存储（桶 / 对象、在线预览编辑、PAR 直传分享）与限额查询 |
 | **成本与账单** | 成本 / 用量查询（小时、日、月粒度，支持服务 / SKU 复合分组）；发票列表与费用明细、PDF 预览下载、付款方式查询及在线支付 |
 | **自动化与控制台** | 抢机、租户测活、成本同步、AI 渠道探测；执行日志、重叠防护、熔断与结果通知；xterm 串行终端、noVNC 和 OCI 控制台连接两跳 SSH 隧道 |
 | **身份与审计** | IAM 用户、MFA、API Key、密码策略、SAML、通知收件人与多 Identity Domain；通过 Service Connector Hub 与 Notifications 接收并分类推送 OCI Audit 事件 |
-| **通知与安全** | Telegram、Webhook、ntfy、Bark、SMTP；AES-256-GCM、JWT、bcrypt、TOTP、OIDC / GitHub 登录、登录锁定、IP 限速、会话撤销和操作审计 |
+| **通知与安全** | Telegram、Webhook、ntfy、Bark、SMTP；AES-256-GCM、JWT、bcrypt、TOTP、OIDC / GitHub 登录、通行密钥（Passkey / WebAuthn，需 HTTPS 且换域名后需重新注册）、Web3 钱包签名登录（EIP-4361,仅注入钱包与 EOA）、登录锁定、IP 限速、活跃会话管理（按设备查看与定点撤销）和操作审计 |
 | **AI 网关** | OpenAI Responses、Chat Completions、Embeddings 与 Anthropic Messages；渠道分组、加权路由、熔断探测、模型治理、密钥管理和调用日志 |
 | **跨端体验** | 桌面与移动端响应式布局，移动端底部导航与卡片列表；PWA 可安装到主屏幕并自动更新，静态资源缓存不拦截 `/api/*`、`/ai/*` 实时请求 |
 ## 运行形态
@@ -306,6 +306,10 @@ go tool swag init -g cmd/server/main.go -o docs --parseInternal --parseDependenc
 - 前端开发与构建：[oci-portal-dash](https://github.com/wangdefaa/oci-portal-dash)
 - 版本变更：[`CHANGELOG.md`](CHANGELOG.md)
 ## 致谢
 感谢 [Yohann0617/oci-helper](https://github.com/Yohann0617/oci-helper) 为本项目提供思路。
 ## License
 [MIT](LICENSE)
@@ -31,7 +31,7 @@ import (
 )
 // @title OCI Portal API
-// @version 0.0.1
+// @version 0.8.3
 // @description 自托管 OCI 多租户管理面板 API。业务接口用 JWT(Bearer);AI 网关端点(/ai/v1/*)用独立网关密钥(Authorization: Bearer 或 x-api-key)。
 // @BasePath /
 // @securityDefinitions.apikey BearerAuth
@@ -110,6 +110,7 @@ func run() error {
 	}
 	ociClient := oci.NewCachedClient(oci.NewClient())
 	ociConfigs := service.NewOciConfigService(db, cipher, ociClient)
 	defer ociConfigs.Stop()
 	settings := service.NewSettingService(db, cipher)
 	settings.SetEnvPublicURL(cfg.PublicURL)
 	if err := settings.ReloadSecurity(context.Background()); err != nil {
@@ -118,17 +119,21 @@ func run() error {
 	notifier := service.NewNotifier(settings)
 	auth.SetNotifier(notifier, settings)
 	oauth := service.NewOAuthService(db, settings, auth)
 	passkeys := service.NewPasskeyService(db, settings, auth)
 	wallets := service.NewWalletService(db, settings, auth)
 	systemLogs := service.NewSystemLogService(db)
 	logEvents := service.NewLogEventService(db)
 	logEvents.SetRelayDeps(ociConfigs, ociClient, cfg.PublicURL)
 	logEvents.SetNotifier(notifier, settings)
 	cleanupCtx, stopCleanup := context.WithCancel(context.Background())
 	systemLogs.StartCleanup(cleanupCtx)
 	auth.StartSessionCleanup(cleanupCtx)
 	logEvents.StartParser(cleanupCtx)
 	logEvents.StartCleanup(cleanupCtx)
 	aiGateway := service.NewAiGatewayService(db, ociConfigs, ociClient)
 	aiGateway.StartCleanup(cleanupCtx)
 	// defer 为 LIFO：先停调度与清理，再等在途通知与日志写完
 	defer auth.WaitSessionCleanup()
 	defer logEvents.Wait()
 	defer systemLogs.Wait()
 	defer notifier.Wait()
@@ -149,7 +154,7 @@ func run() error {
 	defer proxies.Wait()
 	// 「关于」页存储指标需知数据库形态
 	api.SetAboutRuntime(cfg.DBDriver, cfg.DBPath)
-	router := api.NewRouter(auth, oauth, ociConfigs, tasks, console, settings, notifier, systemLogs, logEvents, proxies, aiGateway)
+	router := api.NewRouter(auth, oauth, passkeys, wallets, ociConfigs, tasks, console, settings, notifier, systemLogs, logEvents, proxies, aiGateway)
 	return serveHTTP(cfg.Addr, router)
 }
@@ -196,7 +196,9 @@ Codex 工具兼容现状：
 > 同一请求改为非流式实测可正常完成；单独扩大 `input` 未触发该限制。
 该问题于 2026-07-13 通过字节级二分定位，2026-07-16 在 Chicago 复测仍存在：
-`70.4 KB` 断流、`59.7 KB` 正常，API Key 与签名鉴权表现一致。本文及设置页中的
+`70.4 KB` 断流、`59.7 KB` 正常，API Key 与签名鉴权表现一致。2026-07-21
 再次复测（Chicago 签名路径）仍未修复：`70,463 B` 两次均在数个推理 delta 后纯
 EOF，同时段 `59,651 B` 对照正常 `completed`。本文及设置页中的
 `KB` 均按 `1024 B` 计算。
 | 协议 | 网关保护 | 客户端表现 |
@@ -218,6 +220,29 @@ Responses 合成的最小事件序列为：`response.created` →
 </details>
 ### `multi-agent` 加密推理内容流式断流
 > [!WARNING]
 > `xai.grok-4.20-multi-agent` 请求同时启用 `stream: true` 与
 > `include: ["reasoning.encrypted_content"]` 时，上游高概率在序列化大体量
 > `encrypted_content` 事件期间静默断开连接，不返回 `error` 或终态事件。
 > 断点常见于 `output_index: 8` 附近（第三次搜索结束后的大加密推理块），
 > 也观测到更早（推理起始阶段）与更晚（15 块之后的文本输出阶段）断开。
 2026-07-21 复测仍存在，并进一步定界：
 - 网关(Phoenix 渠道 API Key)四次全断：两次断于 `output_index: 8` 搜索阶段
  （此前 8 块加密内容累计约 `364 KB`），一次收满 15 块约 `762 KB` 后断于文本
  输出；Chicago 签名直发同样可断（亦有一次仅 2 块 `35 KB` 的小规模会话正常
  完成）——与区域、鉴权方式无关，与加密块规模相关。
 - 该模型单块 `encrypted_content` 约 `47 KB`，比 `xai.grok-4.3`（约
  `2-10 KB`）大一个量级；`grok-4.3` + `web_search` + 同 `include` 在累计
  `148 KB` 加密内容、`output_index: 15` 下流式完整——断流特定于
  `multi-agent` 模型的大加密块序列化。
 - 对照：同请求仅改 `include: ["web_search_call.action.sources"]`（不含加密
  推理）正常完成。规避方式：该模型流式时不请求
  `reasoning.encrypted_content`。
 ### ZDR 与文件输入
 Responses 的 `input_file` 内容块（`file_url` / `file_data`）实测会被上游拒绝：
@@ -0,0 +1,117 @@
 <a id="top"></a>
 <div align="center">
 <img src="assets/logo.svg" width="88" alt="OCI Portal logo">
 # OCI 调用者指纹评估
 **OCI Portal 请求暴露面与多租户关联风险**
 ![OCI SDK](https://img.shields.io/badge/OCI-Go%20SDK-F80000?logo=oracle&logoColor=white)
 ![Auth](https://img.shields.io/badge/Auth-API%20Key-2563EB)
 ![Scope](https://img.shields.io/badge/Scope-Multi--tenant-0F9D58)
 [结论速览](#summary) · [请求暴露面](#request-signals) · [项目指纹](#portal-signals) · [关联评估](#assessment) · [核验依据](#evidence)
 </div>
 > [!NOTE]
 > 本文面向架构与隐私评估，说明 OCI Portal 调用 OCI Public API 时 Oracle
 > 可见的信息及跨租户关联风险。结论基于当前源码，不代表 Oracle 实际采用的
 > 风控规则。
 <a id="summary"></a>
 ## 结论速览
 > [!IMPORTANT]
 > OCI Portal 的每次 API Key 请求都会在签名的 `keyId` 中携带
 > `tenancy OCID / user OCID / fingerprint`。这能准确识别云身份，但不能单凭
 > 一次请求证明调用方是 OCI Portal。
 | 问题 | 结论 |
 | --- | --- |
 | Oracle 能识别单次请求的租户和用户吗？ | **能。**签名身份、源 IP、目标服务、操作与时间均可见 |
 | 通用 SDK 请求头能识别 OCI Portal 吗？ | **不能。**默认 User-Agent、签名算法和 Go TLS 特征被大量客户端共享 |
 | Oracle 能关联多个租户共用同一实例吗？ | **具备能力。**需组合出口 IP、资源元数据、固定文本和调用序列 |
 | 外部第三方能完成同等关联吗？ | **通常不能。**其无法取得 Oracle 网关日志和租户内部资源元数据 |
 <a id="request-signals"></a>
 ## 单次请求暴露面
 当前项目统一通过 `common.NewRawConfigurationProvider` 使用 API Key：
 ```text
 Authorization: Signature version="1",
  keyId="<tenancyOCID>/<userOCID>/<fingerprint>",
  algorithm="rsa-sha256", ...
 ```
 | 信号 | 默认形态 | 区分度 |
 | --- | --- | :---: |
 | 签名身份 | `tenancy / user / fingerprint` 明文位于 `keyId` | 身份强，软件弱 |
 | User-Agent | 大多数 SDK 请求为 `Oracle-GoSDK/<版本> (...)` | 弱 |
 | SDK 客户端信息 | SDK 生成的服务请求通常带 `opc-client-info: Oracle-GoSDK/<版本>` | 弱 |
 | 请求元数据 | `Date`、`Host`、`request-target`；写请求另含 body 摘要 | 通用 |
 | 网络特征 | 源 IP、TLS / ALPN、HTTP/2 行为 | 单次弱，跨租户组合后增强 |
 | OCI 遥测头 | 显式启用 `OCI_INCLUDE_REQUEST_TELEMETRY_DATA=true` 时，SDK 操作可写 service / operation；直通请求未必携带 | 可选 |
 项目没有构造 Instance Principal、Resource Principal 或 Session Token
 鉴权，也没有主动覆盖 User-Agent 或为 `opc-request-id` 设置固定前缀。
 `opc-client-info` 由 SDK 请求构造器写入，不含 OCI Portal 标记；手工构造的
 请求可能不带该字段。少量手工签名请求绕过 `BaseClient.prepareRequest`，
 使用 Go `net/http` 的默认 User-Agent。
 <a id="portal-signals"></a>
 ## OCI Portal 增量指纹
 | 信号 | 当前行为 | 关联强度 |
 | --- | --- | :---: |
 | 出口 IP | 无租户级或全局代理时，走部署环境默认出口 / NAT | **强旁证（命中时）** |
 | 日志回传资源名 | 按 tenancy 派生为 `<8hex>-audit*`，描述使用中性文案 | 弱 |
 | GenAI Responses 请求头 | 同时写入 `CompartmentId` 与 `opc-compartment-id` | 中 / 弱 |
 | API 调用序列 | 测活、账户画像、区域与资源查询存在稳定组合 | 辅助 |
 SDK 默认 User-Agent、`opc-client-info` 与固定签名格式只说明“使用 OCI Go
 SDK”，不是项目专属信号。
 <a id="assessment"></a>
 ## 多租户关联评估
 | 观察视角 | 结论 | 主要依据 |
 | --- | --- | --- |
 | Oracle 内部，跨租户数据 | **中** | 固定文本、出口 IP 与调用序列可组合比对 |
 | Oracle 内部，单租户数据 | **低** | 能识别实现痕迹，但难证明多个租户共用同一实例 |
 | 仅看 SDK 请求头 | **低** | 可识别云身份和 SDK 类型，不能可靠识别具体应用 |
 | 外部第三方 | **通常不可行** | 缺少 OCI 网关日志、Sign-on Policy 与租户资源元数据 |
 这些等级表达的是“可关联性”，不是 Oracle 已执行关联或据此采取处置。
 同一出口 IP 也可能来自 NAT、代理或共享基础设施，必须与其他信号联合判断。
 <a id="evidence"></a>
 ## 核验依据
 ### OCI 与 SDK
 - [OCI Request Signatures](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/signingrequests.htm)
 - [OCI API Signing Key](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm)
 - [OCI Go SDK client.go（v65.121.0）](https://github.com/oracle/oci-go-sdk/blob/v65.121.0/common/client.go)
 - [OCI Go SDK http_signer.go（v65.121.0）](https://github.com/oracle/oci-go-sdk/blob/v65.121.0/common/http_signer.go)
 - [OCI Go SDK configuration.go（v65.121.0）](https://github.com/oracle/oci-go-sdk/blob/v65.121.0/common/configuration.go)
 ### 项目源码
 - [API Key provider](../internal/oci/client.go#L237-L246)
 - [手工签名请求](../internal/oci/account.go#L83-L97)
 - [租户出站代理](../internal/oci/proxyhttp.go#L45-L65)
 - [日志回传资源命名](../internal/oci/logrelay_names.go#L20-L55)
 - [GenAI Responses 请求头](../internal/oci/genai_responses.go#L27-L38)
 - [MFA justification](../internal/oci/signon.go#L223-L236)
 - [审计与日志回传约束](../.trellis/spec/backend/oci-audit.md)
 <p align="right"><a href="#top">返回顶部 ↑</a></p>
@@ -4,11 +4,13 @@ go 1.26.5
 require (
 	github.com/coreos/go-oidc/v3 v3.19.0
 	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1
 	github.com/gin-gonic/gin v1.12.0
 	github.com/glebarez/sqlite v1.11.0
 	github.com/go-webauthn/webauthn v0.17.4
 	github.com/golang-jwt/jwt/v5 v5.3.1
 	github.com/gorilla/websocket v1.5.3
-	github.com/oracle/oci-go-sdk/v65 v65.121.0
+	github.com/oracle/oci-go-sdk/v65 v65.122.0
 	github.com/pquerna/otp v1.5.0
 	github.com/robfig/cron/v3 v3.0.1
 	github.com/swaggo/files v1.0.1
@@ -35,6 +37,7 @@ require (
 	github.com/cloudwego/base64x v0.1.6 // indirect
 	github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/fxamacker/cbor/v2 v2.9.2 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.12 // indirect
 	github.com/gin-contrib/sse v1.1.0 // indirect
 	github.com/glebarez/go-sqlite v1.21.2 // indirect
@@ -47,10 +50,13 @@ require (
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-playground/validator/v10 v10.30.1 // indirect
 	github.com/go-sql-driver/mysql v1.8.1 // indirect
 	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
 	github.com/go-webauthn/x v0.2.6 // indirect
 	github.com/goccy/go-json v0.10.5 // indirect
 	github.com/goccy/go-yaml v1.19.2 // indirect
 	github.com/gofrs/flock v0.10.0 // indirect
-	github.com/google/uuid v1.3.0 // indirect
+	github.com/google/go-tpm v0.9.8 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/pgx/v5 v5.9.2 // indirect
@@ -66,15 +72,18 @@ require (
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
 	github.com/philhofer/fwd v1.2.0 // indirect
 	github.com/quic-go/qpack v0.6.0 // indirect
 	github.com/quic-go/quic-go v0.59.1 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
 	github.com/russross/blackfriday/v2 v2.0.1 // indirect
 	github.com/shurcooL/sanitized_anchor_name v1.0.0 // indirect
 	github.com/sony/gobreaker/v2 v2.4.0 // indirect
 	github.com/tinylib/msgp v1.6.4 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.3.1 // indirect
 	github.com/urfave/cli/v2 v2.3.0 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
 	github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 // indirect
 	go.mongodb.org/mongo-driver/v2 v2.5.0 // indirect
 	golang.org/x/arch v0.22.0 // indirect
@@ -25,8 +25,14 @@ github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ3
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/decred/dcrd/crypto/blake256 v1.1.0 h1:zPMNGQCm0g4QTY27fOCorQW7EryeQ/U0x++OzVrdms8=
 github.com/decred/dcrd/crypto/blake256 v1.1.0/go.mod h1:2OfgNZ5wDpcsFmHmCK5gZTPcCXqlm2ArzUIkw9czNJo=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 h1:5RVFMOWjMyRy8cARdy79nAmgYw3hK/4HUq48LQ6Wwqo=
 github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/fxamacker/cbor/v2 v2.9.2 h1:X4Ksno9+x3cz0TZv69ec1hxP/+tymuR8PXQJyDwfh78=
 github.com/fxamacker/cbor/v2 v2.9.2/go.mod h1:vM4b+DJCtHn+zz7h3FFp/hDAI9WNWCsZj23V5ytsSxQ=
 github.com/gabriel-vasile/mimetype v1.4.12 h1:e9hWvmLYvtp846tLHam2o++qitpguFiYCKbn0w9jyqw=
 github.com/gabriel-vasile/mimetype v1.4.12/go.mod h1:d+9Oxyo1wTzWdyVUPMmXFvp4F9tea18J8ufA774AB3s=
 github.com/gin-contrib/gzip v0.0.6 h1:NjcunTcGAj5CO1gn4N8jHOSIeRFHIbn51z6K+xaN4d4=
@@ -61,6 +67,12 @@ github.com/go-playground/validator/v10 v10.30.1 h1:f3zDSN/zOma+w6+1Wswgd9fLkdwy0
 github.com/go-playground/validator/v10 v10.30.1/go.mod h1:oSuBIQzuJxL//3MelwSLD5hc2Tu889bF0Idm9Dg26cM=
 github.com/go-sql-driver/mysql v1.8.1 h1:LedoTUt/eveggdHS9qUFC1EFSa8bU2+1pZjSRpvNJ1Y=
 github.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg=
 github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPEgAXnvj1Ro=
 github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
 github.com/go-webauthn/webauthn v0.17.4 h1:KFTSz3R2RYDiUn/0cDi3XTJgFenSG74eKTTHlqWhlxk=
 github.com/go-webauthn/webauthn v0.17.4/go.mod h1:pZk63EE/BdztlmyS4Yc+9H5g4a8blNlbtGmdHQHbZX8=
 github.com/go-webauthn/x v0.2.6 h1:TEyDuQAIiEgYpx60nKiBJIX/5nSUC8LxNbH+uf5U9uk=
 github.com/go-webauthn/x v0.2.6/go.mod h1:45bA7YEqyQhRcQJ/TiBb46Ww8yqHBGvgEhQ3WWF0aDo=
 github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
 github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
@@ -71,11 +83,15 @@ github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63Y
 github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/go-tpm v0.9.8 h1:slArAR9Ft+1ybZu0lBwpSmpwhRXaa85hWtMinMyRAWo=
 github.com/google/go-tpm v0.9.8/go.mod h1:h9jEsEECg7gtLis0upRBQU+GhYVH6jMjrFxI8u6bVUY=
 github.com/google/go-tpm-tools v0.3.13-0.20230620182252-4639ecce2aba h1:qJEJcuLzH5KDR0gKc0zcktin6KSAwL7+jWKBYceddTc=
 github.com/google/go-tpm-tools v0.3.13-0.20230620182252-4639ecce2aba/go.mod h1:EFYHy8/1y2KfgTAsx7Luu7NGhoxtuVHnNo8jE7FikKc=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
 github.com/google/pprof v0.0.0-20221118152302-e6195bd50e26 h1:Xim43kblpZXfIBQsbuBVKCudVG457BR2GZFIz3uw3hQ=
 github.com/google/pprof v0.0.0-20221118152302-e6195bd50e26/go.mod h1:dDKJzRmX4S37WGHujM7tX//fmj1uioxKzKxz3lo4HJo=
-github.com/google/uuid v1.3.0 h1:t6JiXgmwXMjEs8VusXIJk2BXHsn+wx8BZdTaoZ5fu7I=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
-github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
@@ -119,10 +135,12 @@ github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJ
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
 github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
-github.com/oracle/oci-go-sdk/v65 v65.121.0 h1:1J+5ARgrodrx8kzFy/hxznaoUzz43jr0EestCzEaOHw=
+github.com/oracle/oci-go-sdk/v65 v65.122.0 h1:yB587yZUGe/syyyp1CHlW74EXo38Rfye5vD3Ox4Cdq4=
-github.com/oracle/oci-go-sdk/v65 v65.121.0/go.mod h1:Pzy+BpgkDesvGZXEHgslwhIYobHCPHg6wRta1mWnlqQ=
+github.com/oracle/oci-go-sdk/v65 v65.122.0/go.mod h1:Pzy+BpgkDesvGZXEHgslwhIYobHCPHg6wRta1mWnlqQ=
 github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
 github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/philhofer/fwd v1.2.0 h1:e6DnBTl7vGY+Gz322/ASL4Gyp1FspeMvx1RNDoToZuM=
 github.com/philhofer/fwd v1.2.0/go.mod h1:RqIHx9QI14HlwKwm98g9Re5prTQ6LdeRQn+gXJFxsJM=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pquerna/otp v1.5.0 h1:NMMR+WrmaqXU4EzdGJEE1aUUI0AMRzsp96fFFWNPwxs=
@@ -164,12 +182,16 @@ github.com/swaggo/gin-swagger v1.6.1 h1:Ri06G4gc9N4t4k8hekMigJ9zKTFSlqj/9paAQCQs
 github.com/swaggo/gin-swagger v1.6.1/go.mod h1:LQ+hJStHakCWRiK/YNYtJOu4mR2FP+pxLnILT/qNiTw=
 github.com/swaggo/swag v1.16.6 h1:qBNcx53ZaX+M5dxVyTrgQ0PJ/ACK+NzhwcbieTt+9yI=
 github.com/swaggo/swag v1.16.6/go.mod h1:ngP2etMK5a0P3QBizic5MEwpRmluJZPHjXcMoj4Xesg=
 github.com/tinylib/msgp v1.6.4 h1:mOwYbyYDLPj35mkA2BjjYejgJk9BuHxDdvRnb6v2ZcQ=
 github.com/tinylib/msgp v1.6.4/go.mod h1:RSp0LW9oSxFut3KzESt5Voq4GVWyS+PSulT77roAqEA=
 github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY=
 github.com/ugorji/go/codec v1.3.1/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4=
 github.com/urfave/cli/v2 v2.3.0 h1:qph92Y649prgesehzOrQjdWyxFOp/QVM+6imKHad91M=
 github.com/urfave/cli/v2 v2.3.0/go.mod h1:LJmUH05zAU44vOAcrfzZQKsZbVcdbOG8rtL3/XcUArI=
 github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
 github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=
 github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 h1:ilQV1hzziu+LLM3zUTJ0trRztfwgjqKnBWNtSRkbmwM=
 github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78/go.mod h1:aL8wCCfTfSfmXjznFBSZNN13rSJjlIOI1fUNAtF7rmI=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
@@ -141,7 +141,7 @@ func (h *aiAdminHandler) updateKeyContentLog(c *gin.Context) {
 //
 // @Summary  分页查询内容日志
 // @Tags     AI 管理
-// @Success  200 {object} pagedResponse[model.AiCallLog]
+// @Success  200 {object} pagedResponse[model.AiContentLog]
 // @Security BearerAuth
 // @Router   /api/v1/ai-content-logs [get]
 func (h *aiAdminHandler) listContentLogs(c *gin.Context) {
@@ -400,7 +400,7 @@ func (h *aiAdminHandler) removeBlacklist(c *gin.Context) {
 // @Summary  AI 调用日志列表
 // @Tags     AI 管理
-// @Success  200 {object} pagedResponse[model.AiContentLog]
+// @Success  200 {object} pagedResponse[model.AiCallLog]
 // @Security BearerAuth
 // @Router   /api/v1/ai-logs [get]
 func (h *aiAdminHandler) listLogs(c *gin.Context) {
@@ -12,6 +12,7 @@ import (
 	"gorm.io/gorm"
 	"oci-portal/internal/model"
 	"oci-portal/internal/service"
 )
 // seedGatewayModel 直插启用渠道与模型缓存,绕过云同步。
@@ -29,7 +30,7 @@ func seedGatewayModel(t *testing.T, db *gorm.DB, name string) {
 func TestAiGatewayKeyModelRestrict(t *testing.T) {
 	r, auth, _, db := newTestRouterDB(t)
-	token, _, err := auth.Login(context.Background(), "admin", "pass123", "127.0.0.1", "")
+	token, _, err := auth.Login(context.Background(), "admin", "pass123", "", service.SessionMeta{ClientIP: "127.0.0.1"})
 	if err != nil {
 		t.Fatalf("login: %v", err)
 	}
@@ -125,7 +126,7 @@ func TestAiGatewayKeyModelRestrict(t *testing.T) {
 func TestAiGatewayModelsFilteredByKey(t *testing.T) {
 	r, auth, _, db := newTestRouterDB(t)
-	token, _, err := auth.Login(context.Background(), "admin", "pass123", "127.0.0.1", "")
+	token, _, err := auth.Login(context.Background(), "admin", "pass123", "", service.SessionMeta{ClientIP: "127.0.0.1"})
 	if err != nil {
 		t.Fatalf("login: %v", err)
 	}
@@ -172,7 +173,7 @@ func TestAiGatewayModelsFilteredByKey(t *testing.T) {
 func TestAiKeyModelsUpdateRoundTrip(t *testing.T) {
 	r, auth, _, _ := newTestRouterDB(t)
-	token, _, err := auth.Login(context.Background(), "admin", "pass123", "127.0.0.1", "")
+	token, _, err := auth.Login(context.Background(), "admin", "pass123", "", service.SessionMeta{ClientIP: "127.0.0.1"})
 	if err != nil {
 		t.Fatalf("login: %v", err)
 	}
@@ -10,7 +10,8 @@ import (
 // ---- 实例 IP ----
-// @Summary  ---- 实例 IP ----
+// @Summary  更换实例主网卡临时公网 IP
 // @Description 旧临时 IP 删除、旧保留 IP 自动解绑(资源保留在账户),随后分配新临时 IP
 // @Tags     计算
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
@@ -35,6 +36,32 @@ func (h *ociConfigHandler) changePublicIP(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"publicIp": ip})
 }
 // @Summary  更换 VNIC 临时公网 IP
 // @Description 旧临时 IP 删除、旧保留 IP 自动解绑(资源保留在账户),随后分配新临时 IP
 // @Tags     计算
 // @Param    id path int true "配置 ID"
 // @Param    vnicId path string true "VNIC OCID"
 // @Param    body body object true "请求体:region"
 // @Success  200 {object} publicIpResponse
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/vnics/{vnicId}/change-public-ip [post]
 func (h *ociConfigHandler) changeVnicPublicIP(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	var req struct {
 		Region string `json:"region"`
 	}
 	_ = c.ShouldBindJSON(&req)
 	ip, err := h.svc.ChangeVnicPublicIP(c.Request.Context(), id, req.Region, c.Param("vnicId"))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"publicIp": ip})
 }
 // @Summary  实例添加 IPv6 地址
 // @Tags     计算
 // @Param    id path int true "配置 ID"
@@ -3,7 +3,6 @@ package api
 import (
 	"errors"
 	"net/http"
 	"strings"
 	"time"
 	"github.com/gin-gonic/gin"
@@ -34,7 +33,9 @@ type loginRequest struct {
 // @Param    body body loginRequest true "登录凭据"
 // @Success  200 {object} tokenResponse "token 与 expiresAt"
 // @Failure  401 {object} errorResponse "凭据错误"
 // @Failure  403 {object} errorResponse "密码登录已禁用"
 // @Failure  428 {object} totpRequiredResponse "需要两步验证码(totpRequired=true)"
 // @Failure  429 {object} errorResponse "登录守卫锁定(无 code);全局 IP 限流时 code=RateLimited"
 // @Router   /api/v1/auth/login [post]
 func (h *authHandler) login(c *gin.Context) {
 	var req loginRequest
@@ -43,7 +44,7 @@ func (h *authHandler) login(c *gin.Context) {
 		return
 	}
 	start := time.Now()
-	token, expires, err := h.svc.Login(c.Request.Context(), req.Username, req.Password, requestIP(c), req.TotpCode)
+	token, expires, err := h.svc.Login(c.Request.Context(), req.Username, req.Password, req.TotpCode, sessionMetaOf(c))
 	if errors.Is(err, service.ErrTotpRequired) {
 		// 密码已通过,引导前端弹出二次验证输入;不算失败不留痕
 		c.JSON(http.StatusPreconditionRequired, gin.H{"error": err.Error(), "totpRequired": true})
@@ -80,9 +81,8 @@ func (h *authHandler) login(c *gin.Context) {
 // @Security BearerAuth
 // @Router   /api/v1/auth/logout [post]
 func (h *authHandler) logout(c *gin.Context) {
-	token, ok := strings.CutPrefix(c.GetHeader("Authorization"), "Bearer ")
+	if token := bearerToken(c); token != "" {
-	if ok && token != "" {
+		h.svc.Logout(c.Request.Context(), token)
 		h.svc.Logout(token)
 	}
 	c.Status(http.StatusNoContent)
 }
@@ -16,9 +16,11 @@ import (
 // authxHandler 处理两步验证与外部身份(OAuth)接口。
 type authxHandler struct {
-	auth  *service.AuthService
+	auth     *service.AuthService
-	oauth *service.OAuthService
+	oauth    *service.OAuthService
-	logs  *service.SystemLogService
+	passkeys *service.PasskeyService
 	wallets  *service.WalletService
 	logs     *service.SystemLogService
 }
 // ---- TOTP(JWT 组内) ----
@@ -65,7 +67,8 @@ func (h *authxHandler) totpSetup(c *gin.Context) {
 // @Summary  激活两步验证
 // @Tags     认证
 // @Param    body body object true "{code: 6 位验证码}"
-// @Success  204 "已启用"
+// @Success  200 {object} tokenResponse "已启用,返回换发的新 token"
 // @Failure  401 {object} errorResponse "请求处理期间会话已撤销"
 // @Security BearerAuth
 // @Router   /api/v1/auth/totp/activate [post]
 func (h *authxHandler) totpActivate(c *gin.Context) {
@@ -76,7 +79,9 @@ func (h *authxHandler) totpActivate(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
-	err := h.auth.ActivateTotp(c.Request.Context(), c.GetString(usernameKey), req.Code)
+	token, expires, err := h.auth.ActivateTotp(
 		c.Request.Context(), c.GetString(usernameKey), req.Code,
 		bearerToken(c), sessionMetaOf(c), tokenProofOf(c))
 	if err != nil {
 		if errors.Is(err, service.ErrTotpInvalid) || errors.Is(err, service.ErrTotpNotSetup) {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
@@ -85,7 +90,7 @@ func (h *authxHandler) totpActivate(c *gin.Context) {
 		respondError(c, err)
 		return
 	}
-	h.respondFreshToken(c)
+	c.JSON(http.StatusOK, gin.H{"token": token, "expiresAt": expires})
 }
 // totpDisable 停用两步验证;需当前验证码或登录密码任一确认。
@@ -93,7 +98,8 @@ func (h *authxHandler) totpActivate(c *gin.Context) {
 // @Summary  停用两步验证
 // @Tags     认证
 // @Param    body body object true "{password 或 code 任一确认}"
-// @Success  204 "已停用"
+// @Success  200 {object} tokenResponse "已停用,返回换发的新 token"
 // @Failure  401 {object} errorResponse "请求处理期间会话已撤销"
 // @Security BearerAuth
 // @Router   /api/v1/auth/totp/disable [post]
 func (h *authxHandler) totpDisable(c *gin.Context) {
@@ -105,7 +111,9 @@ func (h *authxHandler) totpDisable(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
-	err := h.auth.DisableTotp(c.Request.Context(), c.GetString(usernameKey), req.Password, req.Code)
+	token, expires, err := h.auth.DisableTotp(
 		c.Request.Context(), c.GetString(usernameKey), req.Password, req.Code,
 		bearerToken(c), sessionMetaOf(c), tokenProofOf(c))
 	if err != nil {
 		if errors.Is(err, service.ErrTotpConfirm) {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
@@ -114,13 +122,14 @@ func (h *authxHandler) totpDisable(c *gin.Context) {
 		respondError(c, err)
 		return
 	}
-	h.respondFreshToken(c)
+	c.JSON(http.StatusOK, gin.H{"token": token, "expiresAt": expires})
 }
 // respondFreshToken 敏感变更后为操作者签发新令牌返回(版本已递增,
-// 旧令牌全部失效);签发失败降级 204,前端按会话失效走重新登录。
+// 旧令牌全部失效);旧令牌的会话行接续到新令牌,列表中当前设备保持连续。
-func (h *authxHandler) respondFreshToken(c *gin.Context) {
+// 签发失败降级 204,前端按会话失效走重新登录。
-	token, expires, err := h.auth.IssueToken(c.Request.Context(), c.GetString(usernameKey))
+func respondFreshToken(c *gin.Context, auth *service.AuthService) {
 	token, expires, err := auth.RenewToken(c.Request.Context(), c.GetString(usernameKey), bearerToken(c), sessionMetaOf(c))
 	if err != nil {
 		c.Status(http.StatusNoContent)
 		return
@@ -136,7 +145,7 @@ func (h *authxHandler) respondFreshToken(c *gin.Context) {
 // @Security BearerAuth
 // @Router   /api/v1/auth/revoke-sessions [post]
 func (h *authxHandler) revokeSessions(c *gin.Context) {
-	token, expires, err := h.auth.RevokeSessions(c.Request.Context(), c.GetString(usernameKey))
+	token, expires, err := h.auth.RevokeSessions(c.Request.Context(), c.GetString(usernameKey), bearerToken(c), sessionMetaOf(c), tokenProofOf(c))
 	if err != nil {
 		respondError(c, err)
 		return
@@ -170,7 +179,8 @@ func (h *authxHandler) getCredentials(c *gin.Context) {
 // @Summary  修改登录凭据
 // @Tags     认证
 // @Param    body body service.UpdateCredentialsInput true "新凭据(当前密码必验)"
-// @Success  204 "已更新,请重新登录"
+// @Success  200 {object} tokenResponse "已更新,返回换发的新 token"
 // @Success  204 "已更新但新 token 签发失败,需重新登录"
 // @Failure  401 {object} errorResponse "当前密码错误"
 // @Security BearerAuth
 // @Router   /api/v1/auth/credentials [put]
@@ -180,7 +190,7 @@ func (h *authxHandler) updateCredentials(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
-	finalName, err := h.auth.UpdateCredentials(c.Request.Context(), c.GetString(usernameKey), req)
+	finalName, err := h.auth.UpdateCredentials(c.Request.Context(), c.GetString(usernameKey), req, tokenProofOf(c))
 	if errors.Is(err, service.ErrCredentialConfirm) {
 		c.JSON(http.StatusUnauthorized, gin.H{"error": err.Error()})
 		return
@@ -194,7 +204,7 @@ func (h *authxHandler) updateCredentials(c *gin.Context) {
 		return
 	}
 	c.Set(usernameKey, finalName)
-	h.respondFreshToken(c)
+	respondFreshToken(c, h.auth)
 }
 // updatePasswordLogin 保存密码登录禁用开关;开启需至少绑定一个外部身份。
@@ -202,7 +212,8 @@ func (h *authxHandler) updateCredentials(c *gin.Context) {
 // @Summary  密码登录开关
 // @Tags     认证
 // @Param    body body object true "{disabled: bool}"
-// @Success  204 "已保存"
+// @Success  200 {object} tokenResponse "已保存,返回换发的新 token"
 // @Success  204 "已保存但新 token 签发失败,需重新登录"
 // @Failure  409 {object} errorResponse "未绑定外部身份"
 // @Security BearerAuth
 // @Router   /api/v1/auth/password-login [put]
@@ -214,7 +225,7 @@ func (h *authxHandler) updatePasswordLogin(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
-	err := h.auth.SetPasswordLoginDisabled(c.Request.Context(), c.GetString(usernameKey), *req.Disabled)
+	err := h.auth.SetPasswordLoginDisabled(c.Request.Context(), c.GetString(usernameKey), *req.Disabled, tokenProofOf(c))
 	if errors.Is(err, service.ErrNeedIdentity) {
 		c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
 		return
@@ -223,26 +234,31 @@ func (h *authxHandler) updatePasswordLogin(c *gin.Context) {
 		respondError(c, err)
 		return
 	}
-	h.respondFreshToken(c)
+	respondFreshToken(c, h.auth)
 }
 // ---- OAuth ----
 // oauthProviders 返回已配置的 provider 列表(公开,登录页展示按钮),
-// 并附带密码登录禁用开关:开启且存在可用外部身份时,登录页隐藏密码表单;
+// 并附带密码登录禁用开关与通行密钥登录可用性:开关开启且存在可用外部身份时,
-// provider 清空时不下发禁用,保证界面始终留有登录入口(后端 Login 仍会拒绝)。
+// 登录页隐藏密码表单;provider 清空时不下发禁用,保证界面始终留有登录入口
 // (后端 Login 仍会拒绝)。
 //
 // @Summary  外部登录 provider 列表
 // @Tags     认证
-// @Success  200 {object} oauthProvidersResponse "providers 与 passwordLoginDisabled"
+// @Success  200 {object} oauthProvidersResponse "providers、passwordLoginDisabled 与 passkeyLogin"
 // @Router   /api/v1/auth/oauth/providers [get]
 func (h *authxHandler) oauthProviders(c *gin.Context) {
 	providers := h.oauth.Providers(c.Request.Context())
 	passkey := h.passkeys != nil && h.passkeys.HasAny(c.Request.Context())
 	wallet := h.wallets != nil && h.wallets.HasAny(c.Request.Context())
 	disabled := false
-	if off, err := h.auth.PasswordLoginDisabled(c.Request.Context()); err == nil && off && len(providers) > 0 {
+	// 有任一免密入口(OAuth/通行密钥/钱包)才如实下发禁用状态;全部缺席时隐藏,
 	// 保证登录页始终留有入口(后端 Login 仍会拒绝)
 	if off, err := h.auth.PasswordLoginDisabled(c.Request.Context()); err == nil && off && (len(providers) > 0 || passkey || wallet) {
 		disabled = true
 	}
-	c.JSON(http.StatusOK, gin.H{"providers": providers, "passwordLoginDisabled": disabled})
+	c.JSON(http.StatusOK, gin.H{"providers": providers, "passwordLoginDisabled": disabled, "passkeyLogin": passkey, "walletLogin": wallet})
 }
 // oauthAuthorize 返回授权跳转 URL;mode=bind 需有效 JWT(绑定到当前账号),login 公开。
@@ -252,6 +268,9 @@ func (h *authxHandler) oauthProviders(c *gin.Context) {
 // @Param    provider path string true "oidc / github"
 // @Param    mode query string false "bind=绑定当前账号(需 Bearer),缺省登录"
 // @Success  200 {object} urlResponse "url"
 // @Failure  401 {object} errorResponse "bind 模式未携带有效 Bearer"
 // @Failure  404 {object} errorResponse "未知 provider"
 // @Failure  409 {object} errorResponse "provider 未配置 / 面板地址缺失 / 已禁用"
 // @Router   /api/v1/auth/oauth/{provider}/authorize [get]
 func (h *authxHandler) oauthAuthorize(c *gin.Context) {
 	provider := c.Param("provider")
@@ -268,7 +287,7 @@ func (h *authxHandler) oauthAuthorize(c *gin.Context) {
 		}
 		mode, username = "bind", name
 	}
-	authURL, err := h.oauth.AuthorizeURL(c.Request.Context(), provider, mode, username)
+	authURL, err := h.oauth.AuthorizeURL(c.Request.Context(), provider, mode, username, bearerToken(c))
 	if err != nil {
 		if errors.Is(err, service.ErrOAuthNotConfigured) || errors.Is(err, service.ErrOAuthNoAppURL) || errors.Is(err, service.ErrOAuthDisabled) {
 			c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
@@ -306,7 +325,7 @@ func (h *authxHandler) oauthCallback(c *gin.Context) {
 	start := time.Now()
 	provider := c.Param("provider")
 	token, username, mode, err := h.oauth.HandleCallback(
-		c.Request.Context(), provider, c.Query("state"), c.Query("code"))
+		c.Request.Context(), provider, c.Query("state"), c.Query("code"), sessionMetaOf(c))
 	if err != nil {
 		h.recordOauth(c, username, http.StatusUnauthorized, oauthErrText(err), start)
 		target := "/login"
@@ -375,7 +394,8 @@ func (h *authxHandler) identities(c *gin.Context) {
 // @Summary  解绑外部身份
 // @Tags     认证
 // @Param    id path int true "身份 ID"
-// @Success  204 "已解绑"
+// @Success  200 {object} tokenResponse "已解绑,返回换发的新 token"
 // @Success  204 "已解绑但新 token 签发失败,需重新登录"
 // @Failure  409 {object} errorResponse "最后一个身份不可解绑"
 // @Security BearerAuth
 // @Router   /api/v1/auth/identities/{id} [delete]
@@ -385,7 +405,7 @@ func (h *authxHandler) unbindIdentity(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
 		return
 	}
-	if err := h.oauth.Unbind(c.Request.Context(), c.GetString(usernameKey), uint(id)); err != nil {
+	if err := h.oauth.Unbind(c.Request.Context(), c.GetString(usernameKey), uint(id), tokenProofOf(c)); err != nil {
 		if errors.Is(err, service.ErrLastIdentity) {
 			c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
 			return
@@ -393,7 +413,7 @@ func (h *authxHandler) unbindIdentity(c *gin.Context) {
 		respondError(c, err)
 		return
 	}
-	h.respondFreshToken(c)
+	respondFreshToken(c, h.auth)
 }
 // ---- OAuth provider 设置(JWT 组内) ----
@@ -414,21 +434,31 @@ func (h *authxHandler) getOAuthSettings(c *gin.Context, settings *service.Settin
 	c.JSON(http.StatusOK, view)
 }
-// updateOAuthSettings 保存 provider 配置;secret 缺省沿用、空串清除。
+// updateOAuthSettings 部分更新 provider 配置;缺省字段沿用现值,
 // secret 传空串清除、缺省沿用。
 //
-// @Summary  保存 OAuth provider 配置
+// @Summary  部分更新 OAuth provider 配置
 // @Tags     设置
-// @Param    body body service.UpdateOAuthInput true "provider 配置"
+// @Param    body body service.UpdateOAuthInput true "出现的字段才会被更新"
 // @Success  200 {object} service.OAuthProvidersView
 // @Failure  400 {object} errorResponse "请求体非法"
 // @Failure  401 {object} errorResponse "请求处理期间会话已撤销"
 // @Failure  409 {object} errorResponse "密码登录禁用期间,该变更将移除最后可用登录方式"
 // @Security BearerAuth
-// @Router   /api/v1/settings/oauth [put]
+// @Router   /api/v1/settings/oauth [patch]
 func (h *authxHandler) updateOAuthSettings(c *gin.Context, settings *service.SettingService) {
 	var req service.UpdateOAuthInput
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
-	if err := settings.UpdateOAuth(c.Request.Context(), req); err != nil {
+	err := settings.UpdateOAuthAuthenticated(
 		c.Request.Context(), req, h.auth, c.GetString(usernameKey), tokenProofOf(c))
 	if err != nil {
 		if errors.Is(err, service.ErrProviderLastLogin) {
 			c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
 			return
 		}
 		respondError(c, err)
 		return
 	}
@@ -0,0 +1,139 @@
 package api
 import (
 	"fmt"
 	"net/http"
 	"strconv"
 	"strings"
 	"github.com/gin-gonic/gin"
 	_ "oci-portal/internal/oci" // swagger 注解引用
 )
 // payInvoiceRequest 是付款请求体;email 接收 OSP 付款回执。
 type payInvoiceRequest struct {
 	Email string `json:"email" binding:"required"`
 }
 // @Summary  发票列表
 // @Tags     账单
 // @Param    id path int true "配置 ID"
 // @Param    year query int false "自然年过滤(按开票时间);缺省全量"
 // @Success  200 {array} oci.Invoice
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/invoices [get]
 func (h *ociConfigHandler) invoices(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	year, _ := strconv.Atoi(c.Query("year"))
 	list, err := h.svc.Invoices(c.Request.Context(), id, year)
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, list)
 }
 // @Summary  发票费用明细
 // @Tags     账单
 // @Param    id path int true "配置 ID"
 // @Param    internalId path string true "发票内部 ID"
 // @Success  200 {array} oci.InvoiceLine
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/invoices/{internalId}/lines [get]
 func (h *ociConfigHandler) invoiceLines(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	lines, err := h.svc.InvoiceLines(c.Request.Context(), id, c.Param("internalId"))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, lines)
 }
 // @Summary  发票 PDF 下载
 // @Tags     账单
 // @Param    id path int true "配置 ID"
 // @Param    internalId path string true "发票内部 ID"
 // @Param    number query string false "发票号(用作下载文件名)"
 // @Success  200 {file} binary "PDF 原文"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/invoices/{internalId}/pdf [get]
 func (h *ociConfigHandler) invoicePdf(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	data, err := h.svc.InvoicePdf(c.Request.Context(), id, c.Param("internalId"))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.Header("Content-Disposition", fmt.Sprintf("attachment; filename=%q", pdfFileName(c.Query("number"), c.Param("internalId"))))
 	c.Data(http.StatusOK, "application/pdf", data)
 }
 // pdfFileName 生成下载文件名:优先发票号,剔除引号/路径分隔等不安全字符。
 func pdfFileName(number, internalID string) string {
 	name := strings.TrimSpace(number)
 	if name == "" {
 		name = internalID
 	}
 	name = strings.Map(func(r rune) rune {
 		if r == '"' || r == '/' || r == '\\' || r < 0x20 {
 			return '_'
 		}
 		return r
 	}, name)
 	return name + ".pdf"
 }
 // @Summary  支付发票
 // @Tags     账单
 // @Param    id path int true "配置 ID"
 // @Param    internalId path string true "发票内部 ID"
 // @Param    body body payInvoiceRequest true "回执邮箱"
 // @Success  200 {object} map[string]string
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/invoices/{internalId}/pay [post]
 func (h *ociConfigHandler) payInvoice(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	var req payInvoiceRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
 	if err := h.svc.PayInvoice(c.Request.Context(), id, c.Param("internalId"), req.Email); err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"status": "submitted"})
 }
 // @Summary  付款方式列表
 // @Tags     账单
 // @Param    id path int true "配置 ID"
 // @Success  200 {array} oci.PaymentMethod
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/payment-methods [get]
 func (h *ociConfigHandler) paymentMethods(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	methods, err := h.svc.PaymentMethods(c.Request.Context(), id)
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, methods)
 }
@@ -1,13 +1,121 @@
 package api
 import (
 	"errors"
 	"io"
 	"log"
 	"net/http"
 	"github.com/gin-gonic/gin"
 	"oci-portal/internal/oci"
 	"oci-portal/internal/service"
 )
 // idpIconResponse 是图标上传响应;fileName 为域存储内标识,留作后续清理。
 type idpIconResponse struct {
 	URL      string `json:"url"`
 	FileName string `json:"fileName"`
 }
 type idpSetupWarning struct {
 	Code            string `json:"code"`
 	Message         string `json:"message"`
 	ResourceCreated bool   `json:"resourceCreated"`
 	RequestID       string `json:"requestId"`
 }
 type createIdpResponse struct {
 	oci.IdentityProviderInfo
 	SetupWarning *idpSetupWarning `json:"setupWarning,omitempty"`
 }
 // @Summary  上传身份提供商图标
 // @Description 上传到身份域公共图片存储(/storage/v1/Images),返回可填入 iconUrl 的公网地址
 // @Tags     租户 IAM
 // @Accept   multipart/form-data
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
 // @Param    file formData file true "图标文件(png/jpg/jpeg/gif/svg/webp/ico,≤1MB)"
 // @Success  200 {object} idpIconResponse
 // @Failure  400 {object} map[string]string "缺文件字段、文件为空或文件名非法"
 // @Failure  413 {object} map[string]string "文件超过 1MB"
 // @Failure  415 {object} map[string]string "扩展名不支持或与文件内容不符"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/idp-icons [post]
 func (h *ociConfigHandler) uploadIdpIcon(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	file, header, err := c.Request.FormFile("file")
 	if err != nil {
 		status, msg := iconFormStatus(err)
 		c.JSON(status, gin.H{"error": msg})
 		return
 	}
 	defer file.Close()
 	data, err := io.ReadAll(file) // 请求体总量由路由级 bodyLimit 兜底
 	if err != nil {
 		status, msg := iconFormStatus(err)
 		c.JSON(status, gin.H{"error": msg})
 		return
 	}
 	url, fileName, err := h.svc.UploadIdpIcon(c.Request.Context(), id, c.Query("domainId"), header.Filename, data)
 	if err != nil {
 		respondIdpIconErr(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, idpIconResponse{URL: url, FileName: fileName})
 }
 // @Summary  删除身份提供商图标
 // @Description 使用上传响应中的 fileName 删除身份域公开图片;404 按已删除处理
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
 // @Param    fileName query string true "上传响应返回的 IdP 图标存储标识(images/idp-icon-<32hex>.<ext>)"
 // @Success  204 "无内容"
 // @Failure  400 {object} map[string]string "fileName 缺失或不是本服务生成的 IdP 图标标识"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/idp-icons [delete]
 func (h *ociConfigHandler) deleteIdpIcon(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	if err := h.svc.DeleteIdpIcon(c.Request.Context(), id, c.Query("domainId"), c.Query("fileName")); err != nil {
 		respondIdpIconErr(c, err)
 		return
 	}
 	c.Status(http.StatusNoContent)
 }
 // iconFormStatus 区分请求体超限(413)与表单缺失/损坏(400)。
 func iconFormStatus(err error) (int, string) {
 	var mbe *http.MaxBytesError
 	if errors.As(err, &mbe) {
 		return http.StatusRequestEntityTooLarge, "请求体超出上限(图标最大 1MB)"
 	}
 	return http.StatusBadRequest, "缺少文件字段 file"
 }
 // respondIdpIconErr 把图标校验哨兵错误映射为语义状态码,其余走统一错误边界。
 func respondIdpIconErr(c *gin.Context, err error) {
 	switch {
 	case errors.Is(err, service.ErrIdpIconTooLarge):
 		c.JSON(http.StatusRequestEntityTooLarge, gin.H{"error": "图标不能超过 1MB"})
 	case errors.Is(err, service.ErrIdpIconBadType):
 		c.JSON(http.StatusUnsupportedMediaType, gin.H{"error": "扩展名不支持或与文件内容不符"})
 	case errors.Is(err, service.ErrIdpIconEmpty):
 		c.JSON(http.StatusBadRequest, gin.H{"error": "文件为空"})
 	case errors.Is(err, service.ErrIdpIconBadName):
 		c.JSON(http.StatusBadRequest, gin.H{"error": "图标文件名非法"})
 	default:
 		respondError(c, err)
 	}
 }
 // ---- Federation：SAML IdP 与 sign-on 免 MFA ----
 // createIdpRequest 的映射 / JIT 字段全部可缺省：布尔用指针区分「未传」，
@@ -58,11 +166,12 @@ func (h *ociConfigHandler) listIdentityProviders(c *gin.Context) {
 }
 // @Summary  创建身份提供商(SAML)
 // @Description 创建禁用态 IdP；若 IdP 已创建但 JIT 后置配置失败且回滚无法确认，仍返回 201，并在 setupWarning 中标明部分成功
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    domainId query string false "身份域 OCID(缺省 Default 域)"
 // @Param    body body createIdpRequest true "请求体"
-// @Success  201 {object} oci.IdentityProviderInfo
+// @Success  201 {object} createIdpResponse
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/identity-providers [post]
 func (h *ociConfigHandler) createIdentityProvider(c *gin.Context) {
@@ -89,11 +198,37 @@ func (h *ociConfigHandler) createIdentityProvider(c *gin.Context) {
 		JitAssignAdminGroup: boolOr(req.JitAssignAdminGroup, true),
 		JitMapEmail:         req.JitMapEmail,
 	})
-	if err != nil {
+	respondCreateIdpResult(c, idp, err)
 }
 func respondCreateIdpResult(c *gin.Context, idp oci.IdentityProviderInfo, err error) {
 	if err == nil {
 		c.JSON(http.StatusCreated, createIdpResponse{IdentityProviderInfo: idp})
 		return
 	}
 	var partial *oci.PartialIdentityProviderCreateError
 	if !errors.As(err, &partial) {
 		respondError(c, err)
 		return
 	}
-	c.JSON(http.StatusCreated, idp)
+	requestID := logPartialIdpCreate(c, partial)
 	c.JSON(http.StatusCreated, createIdpResponse{
 		IdentityProviderInfo: partial.IdentityProvider,
 		SetupWarning: &idpSetupWarning{
 			Code: oci.IdpSetupWarningCode, Message: "JIT 配置未完成，自动回滚状态无法确认，请刷新列表检查",
 			ResourceCreated: true, RequestID: requestID,
 		},
 	})
 }
 func logPartialIdpCreate(c *gin.Context, partial *oci.PartialIdentityProviderCreateError) string {
 	requestID := newRequestID()
 	detail := errors.Unwrap(partial)
 	if detail == nil {
 		detail = partial
 	}
 	log.Printf("[WARN %s] %s %s: partial IdP create: %v", requestID, c.Request.Method, requestPath(c), detail)
 	return requestID
 }
 // @Summary  激活身份提供商
@@ -0,0 +1,217 @@
 package api
 import (
 	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
 	"mime/multipart"
 	"net/http"
 	"net/http/httptest"
 	"net/url"
 	"strconv"
 	"strings"
 	"testing"
 	"github.com/gin-gonic/gin"
 	"gorm.io/gorm"
 	"oci-portal/internal/crypto"
 	"oci-portal/internal/model"
 	"oci-portal/internal/oci"
 	"oci-portal/internal/service"
 )
 func newIconTestRouter(t *testing.T) (*gin.Engine, string, uint, *service.SystemLogService) {
 	t.Helper()
 	router, auth, logs, db := newTestRouterDB(t)
 	id := seedIconConfig(t, db)
 	token, _, err := auth.Login(context.Background(), "admin", "pass123", "", service.SessionMeta{ClientIP: "127.0.0.1"})
 	if err != nil {
 		t.Fatalf("login: %v", err)
 	}
 	return router, token, id, logs
 }
 func seedIconConfig(t *testing.T, db *gorm.DB) uint {
 	t.Helper()
 	cipher, err := crypto.NewCipher("test-key")
 	if err != nil {
 		t.Fatalf("new cipher: %v", err)
 	}
 	key, err := cipher.EncryptString("-----BEGIN PRIVATE KEY-----\nfake\n-----END PRIVATE KEY-----")
 	if err != nil {
 		t.Fatalf("encrypt key: %v", err)
 	}
 	cfg := model.OciConfig{Alias: "icons", TenancyOCID: "ocid1.tenancy.oc1..t", UserOCID: "ocid1.user.oc1..u",
 		Fingerprint: "aa:bb", Region: "us-ashburn-1", HomeRegionKey: "IAD", PrivateKeyEnc: key}
 	if err := db.Create(&cfg).Error; err != nil {
 		t.Fatalf("create config: %v", err)
 	}
 	return cfg.ID
 }
 func iconSVG(t *testing.T, size int) []byte {
 	t.Helper()
 	data := []byte(`<svg xmlns="http://www.w3.org/2000/svg"/>`)
 	if len(data) > size {
 		t.Fatalf("svg size %d exceeds target %d", len(data), size)
 	}
 	return append(data, bytes.Repeat([]byte(" "), size-len(data))...)
 }
 func sendIconUpload(t *testing.T, router *gin.Engine, token, path, fileName string, data []byte) *httptest.ResponseRecorder {
 	t.Helper()
 	var body bytes.Buffer
 	writer := multipart.NewWriter(&body)
 	part, err := writer.CreateFormFile("file", fileName)
 	if err != nil {
 		t.Fatalf("create form file: %v", err)
 	}
 	_, _ = part.Write(data)
 	_ = writer.Close()
 	req := httptest.NewRequest(http.MethodPost, path, &body)
 	req.Header.Set("Content-Type", writer.FormDataContentType())
 	req.Header.Set("Authorization", "Bearer "+token)
 	rec := httptest.NewRecorder()
 	router.ServeHTTP(rec, req)
 	return rec
 }
 func TestIdpIconMultipartSizeBoundary(t *testing.T) {
 	router, token, id, logs := newIconTestRouter(t)
 	t.Cleanup(logs.Wait)
 	path := "/api/v1/oci-configs/" + strconv.FormatUint(uint64(id), 10) + "/idp-icons"
 	cases := []struct {
 		name, fileName string
 		data           []byte
 		want           int
 	}{
 		{"exactly 1MiB", "icon.svg", iconSVG(t, 1<<20), http.StatusOK},
 		{"one byte over", "icon.svg", iconSVG(t, 1<<20+1), http.StatusRequestEntityTooLarge},
 		{"empty", "icon.png", nil, http.StatusBadRequest},
 		{"spoofed png", "icon.png", []byte("not an image"), http.StatusUnsupportedMediaType},
 	}
 	for _, tc := range cases {
 		rec := sendIconUpload(t, router, token, path, tc.fileName, tc.data)
 		if rec.Code != tc.want {
 			t.Errorf("%s status = %d, want %d, body %s", tc.name, rec.Code, tc.want, rec.Body.String())
 		}
 	}
 }
 func TestDeleteIdpIconRoute(t *testing.T) {
 	router, token, id, logs := newIconTestRouter(t)
 	t.Cleanup(logs.Wait)
 	base := "/api/v1/oci-configs/" + strconv.FormatUint(uint64(id), 10) + "/idp-icons"
 	fileName := "images/idp-icon-" + strings.Repeat("ab", 16) + ".png"
 	query := url.Values{"fileName": {fileName}}
 	rec := doRequest(t, router, http.MethodDelete, base+"?"+query.Encode(), token, "")
 	if rec.Code != http.StatusNoContent {
 		t.Errorf("delete status = %d, want 204, body %s", rec.Code, rec.Body.String())
 	}
 	rec = doRequest(t, router, http.MethodDelete, base+"?fileName=images/company-brand.png", token, "")
 	if rec.Code != http.StatusBadRequest {
 		t.Errorf("invalid delete status = %d, want 400", rec.Code)
 	}
 }
 func assertResponderStatus(t *testing.T, name string, err error, want int, responder func(*gin.Context, error)) {
 	t.Helper()
 	rec := httptest.NewRecorder()
 	ctx, _ := gin.CreateTestContext(rec)
 	ctx.Request = httptest.NewRequest(http.MethodPost, "/", nil)
 	responder(ctx, err)
 	if rec.Code != want {
 		t.Errorf("%s status = %d, want %d", name, rec.Code, want)
 	}
 }
 func TestIdpIconErrorResponder(t *testing.T) {
 	cases := []struct {
 		name string
 		err  error
 		want int
 	}{
 		{"empty icon", service.ErrIdpIconEmpty, 400},
 		{"bad icon name", service.ErrIdpIconBadName, 400},
 		{"large icon", service.ErrIdpIconTooLarge, 413},
 		{"bad icon type", service.ErrIdpIconBadType, 415},
 	}
 	for _, tc := range cases {
 		assertResponderStatus(t, tc.name, tc.err, tc.want, respondIdpIconErr)
 	}
 }
 func TestCreateIdpOrdinaryErrorHasNoPartialSemantics(t *testing.T) {
 	rec, body := callCreateIdpResponder(t, oci.IdentityProviderInfo{}, errors.New("create failed"))
 	if rec.Code != http.StatusInternalServerError {
 		t.Fatalf("status = %d, want 500; body %s", rec.Code, rec.Body.String())
 	}
 	if _, ok := body["setupWarning"]; ok || bytes.Contains(rec.Body.Bytes(), []byte("resourceCreated")) {
 		t.Errorf("ordinary error unexpectedly carries partial semantics: %s", rec.Body.String())
 	}
 }
 func TestCreateIdpPartialErrorReturnsStableWarning(t *testing.T) {
 	partial := &oci.PartialIdentityProviderCreateError{
 		IdentityProvider: oci.IdentityProviderInfo{ID: "idp-1", Name: "test-idp"},
 	}
 	rec, body := callCreateIdpResponder(t, oci.IdentityProviderInfo{}, errors.Join(errors.New("raw secret"), partial))
 	warning, ok := body["setupWarning"].(map[string]interface{})
 	if rec.Code != http.StatusCreated || !ok {
 		t.Fatalf("status = %d, warning = %#v; body %s", rec.Code, body["setupWarning"], rec.Body.String())
 	}
 	requestID, _ := warning["requestId"].(string)
 	if warning["code"] != oci.IdpSetupWarningCode || warning["resourceCreated"] != true || requestID == "" {
 		t.Errorf("warning = %#v, want stable partial-create contract", warning)
 	}
 	if bytes.Contains(rec.Body.Bytes(), []byte("secret")) {
 		t.Errorf("partial response leaks internal cause: %s", rec.Body.String())
 	}
 }
 func callCreateIdpResponder(t *testing.T, idp oci.IdentityProviderInfo, err error) (*httptest.ResponseRecorder, map[string]interface{}) {
 	t.Helper()
 	rec := httptest.NewRecorder()
 	ctx, _ := gin.CreateTestContext(rec)
 	ctx.Request = httptest.NewRequest(http.MethodPost, "/identity-providers", nil)
 	respondCreateIdpResult(ctx, idp, err)
 	body := map[string]interface{}{}
 	if decodeErr := json.Unmarshal(rec.Body.Bytes(), &body); decodeErr != nil {
 		t.Fatalf("decode response: %v", decodeErr)
 	}
 	return rec, body
 }
 func TestPARErrorResponder(t *testing.T) {
 	cases := []struct {
 		name string
 		err  error
 	}{
 		{"bad PAR type", service.ErrPARInvalidAccessType},
 		{"bad PAR expiry", service.ErrPARInvalidExpiration},
 	}
 	for _, tc := range cases {
 		assertResponderStatus(t, tc.name, tc.err, http.StatusBadRequest, respondPARError)
 	}
 }
 func TestCreatePARValidationReturns400(t *testing.T) {
 	router, token, id, logs := newIconTestRouter(t)
 	t.Cleanup(logs.Wait)
 	path := "/api/v1/oci-configs/" + strconv.FormatUint(uint64(id), 10) + "/buckets/b/pars"
 	cases := []struct {
 		name, body string
 	}{
 		{"bad access type", `{"accessType":"BucketRead","expiresHours":24}`},
 		{"zero expiration", `{"accessType":"ObjectRead","expiresHours":0}`},
 		{"excessive expiration", `{"accessType":"ObjectRead","expiresHours":876001}`},
 	}
 	for _, tc := range cases {
 		rec := doRequest(t, router, http.MethodPost, path, token, tc.body)
 		if rec.Code != http.StatusBadRequest {
 			t.Errorf("%s status = %d, want 400, body %s", tc.name, rec.Code, rec.Body.String())
 		}
 	}
 }
@@ -2,6 +2,7 @@ package api
 import (
 	"net/http"
 	"sync"
 	"github.com/gin-gonic/gin"
@@ -44,6 +45,7 @@ type createInstanceRequest struct {
 	BootVolumeVpusPerGB  int64   `json:"bootVolumeVpusPerGB"`
 	SubnetID             string  `json:"subnetId"` // 为空时自动创建 VCN 与子网
 	AssignPublicIP       bool    `json:"assignPublicIp"`
 	ReservedPublicIPID   string  `json:"reservedPublicIpId"` // 非空时不分配临时 IP,实例就绪后自动绑定该保留 IP
 	AssignIpv6           bool    `json:"assignIpv6"`
 	SSHPublicKey         string  `json:"sshPublicKey"`
 	RootPassword         string  `json:"rootPassword"`
@@ -118,6 +120,7 @@ func (h *ociConfigHandler) createInstance(c *gin.Context) {
 		BootVolumeVpusPerGB:  req.BootVolumeVpusPerGB,
 		SubnetID:             req.SubnetID,
 		AssignPublicIP:       req.AssignPublicIP,
 		ReservedPublicIPID:   req.ReservedPublicIPID,
 		AssignIpv6:           req.AssignIpv6,
 		SSHPublicKey:         req.SSHPublicKey,
 		RootPassword:         req.RootPassword,
@@ -200,6 +203,7 @@ func (h *ociConfigHandler) updateInstance(c *gin.Context) {
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
 // @Success  204 "无内容"
 // @Failure  409 {object} errorResponse "该实例的生命周期操作正在处理中"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId} [delete]
 func (h *ociConfigHandler) terminateInstance(c *gin.Context) {
@@ -207,20 +211,43 @@ func (h *ociConfigHandler) terminateInstance(c *gin.Context) {
 	if !ok {
 		return
 	}
 	instanceID := c.Param("instanceId")
 	if !beginInstanceLifecycleOperation(instanceID) {
 		respondInstanceLifecycleBusy(c)
 		return
 	}
 	defer endInstanceLifecycleOperation(instanceID)
 	preserve := c.Query("preserveBootVolume") == "true"
-	if err := h.svc.TerminateInstance(c.Request.Context(), id, c.Query("region"), c.Param("instanceId"), preserve); err != nil {
+	if err := h.svc.TerminateInstance(c.Request.Context(), id, c.Query("region"), instanceID, preserve); err != nil {
 		respondError(c, err)
 		return
 	}
 	c.Status(http.StatusNoContent)
 }
 // instanceLifecycleGuard 按实例 OCID 互斥 HTTP 请求飞行期内的终止与电源操作。
 var instanceLifecycleGuard sync.Map
 func beginInstanceLifecycleOperation(instanceID string) bool {
 	_, busy := instanceLifecycleGuard.LoadOrStore(instanceID, struct{}{})
 	return !busy
 }
 func endInstanceLifecycleOperation(instanceID string) {
 	instanceLifecycleGuard.Delete(instanceID)
 }
 func respondInstanceLifecycleBusy(c *gin.Context) {
 	c.JSON(http.StatusConflict, gin.H{"error": "该实例的生命周期操作正在处理中"})
 }
 // @Summary  实例电源操作(启停/重启)
 // @Tags     计算
 // @Param    id path int true "配置 ID"
 // @Param    instanceId path string true "instanceId"
 // @Param    body body instanceActionRequest true "请求体"
 // @Success  200 {object} oci.Instance
 // @Failure  409 {object} errorResponse "该实例的生命周期操作正在处理中"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/instances/{instanceId}/action [post]
 func (h *ociConfigHandler) instanceAction(c *gin.Context) {
@@ -233,7 +260,13 @@ func (h *ociConfigHandler) instanceAction(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
-	instance, err := h.svc.InstanceAction(c.Request.Context(), id, req.Region, c.Param("instanceId"), req.Action)
+	instanceID := c.Param("instanceId")
 	if !beginInstanceLifecycleOperation(instanceID) {
 		respondInstanceLifecycleBusy(c)
 		return
 	}
 	defer endInstanceLifecycleOperation(instanceID)
 	instance, err := h.svc.InstanceAction(c.Request.Context(), id, req.Region, instanceID, req.Action)
 	if err != nil {
 		respondError(c, err)
 		return
@@ -0,0 +1,78 @@
 package api
 import (
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"sync"
 	"testing"
 	"github.com/gin-gonic/gin"
 )
 func countLifecycleWinners(instanceID string, workers int) int {
 	start := make(chan struct{})
 	results := make(chan bool, workers)
 	var wg sync.WaitGroup
 	for range workers {
 		wg.Add(1)
 		go func() {
 			defer wg.Done()
 			<-start
 			results <- beginInstanceLifecycleOperation(instanceID)
 		}()
 	}
 	close(start)
 	wg.Wait()
 	close(results)
 	winners := 0
 	for won := range results {
 		if won {
 			winners++
 		}
 	}
 	return winners
 }
 func TestBeginInstanceLifecycleOperationSingleFlight(t *testing.T) {
 	instanceID := "ocid1.instance.oc1..single-flight"
 	instanceLifecycleGuard.Delete(instanceID)
 	t.Cleanup(func() { instanceLifecycleGuard.Delete(instanceID) })
 	if got, want := countLifecycleWinners(instanceID, 16), 1; got != want {
 		t.Errorf("winners = %d, want %d", got, want)
 	}
 }
 func instanceOperationRouter() *gin.Engine {
 	h := &ociConfigHandler{}
 	r := gin.New()
 	r.DELETE("/oci-configs/:id/instances/:instanceId", h.terminateInstance)
 	r.POST("/oci-configs/:id/instances/:instanceId/action", h.instanceAction)
 	return r
 }
 func TestInstanceLifecycleOperationRejectsLaterRequest(t *testing.T) {
 	gin.SetMode(gin.TestMode)
 	instanceID := "ocid1.instance.oc1..same-physical-instance"
 	instanceLifecycleGuard.Store(instanceID, struct{}{})
 	t.Cleanup(func() { instanceLifecycleGuard.Delete(instanceID) })
 	r := instanceOperationRouter()
 	tests := []struct {
 		name, method, path, body string
 	}{
 		{"action先占位时跨配置terminate被拒", http.MethodDelete, "/oci-configs/2/instances/" + instanceID, ""},
 		{"terminate先占位时action被拒", http.MethodPost, "/oci-configs/1/instances/" + instanceID + "/action", `{"action":"STOP"}`},
 		{"action先占位时第二个action被拒", http.MethodPost, "/oci-configs/3/instances/" + instanceID + "/action", `{"action":"RESET"}`},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			req := httptest.NewRequest(tt.method, tt.path, strings.NewReader(tt.body))
 			req.Header.Set("Content-Type", "application/json")
 			w := httptest.NewRecorder()
 			r.ServeHTTP(w, req)
 			if got, want := w.Code, http.StatusConflict; got != want {
 				t.Errorf("status = %d, want %d, body %s", got, want, w.Body.String())
 			}
 		})
 	}
 }
@@ -5,6 +5,7 @@ import (
 	"net/http"
 	"strings"
 	"time"
 	"unicode/utf8"
 	"github.com/gin-gonic/gin"
@@ -12,11 +13,17 @@ import (
 	"oci-portal/internal/service"
 )
-// usernameKey 是鉴权通过后写入 gin.Context 的用户名键。
+// usernameKey 是鉴权通过后写入 gin.Context 的用户名键;
-const usernameKey = "username"
+// tokenVerKey/tokenJtiKey 是鉴权时观察到的令牌快照,敏感事务提交前复核。
 const (
 	usernameKey = "username"
 	tokenVerKey = "tokenVer"
 	tokenJtiKey = "tokenJti"
 )
 // RequireAuth 校验 Authorization: Bearer 令牌（签名、有效期与令牌版本），
-// 通过后把用户名放进上下文。
+// 通过后把用户名与令牌快照(版本/jti)放进上下文——快照供敏感事务在
 // 行锁下复核,防「请求挂起期间令牌被撤销,恢复后仍完成变更」的在途绕过。
 func RequireAuth(auth *service.AuthService) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		token, ok := strings.CutPrefix(c.GetHeader("Authorization"), "Bearer ")
@@ -24,16 +31,25 @@ func RequireAuth(auth *service.AuthService) gin.HandlerFunc {
 			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing bearer token"})
 			return
 		}
-		username, err := auth.ParseToken(c.Request.Context(), token)
+		username, proof, err := auth.ParseTokenProof(c.Request.Context(), token)
 		if err != nil {
 			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid or expired token"})
 			return
 		}
 		c.Set(usernameKey, username)
 		c.Set(tokenVerKey, proof.Ver)
 		c.Set(tokenJtiKey, proof.Jti)
 		c.Next()
 	}
 }
 // tokenProofOf 取出鉴权时的令牌快照,交给敏感 service 事务复核。
 func tokenProofOf(c *gin.Context) service.TokenProof {
 	v, _ := c.Get(tokenVerKey)
 	ver, _ := v.(uint)
 	return service.TokenProof{Ver: ver, Jti: c.GetString(tokenJtiKey)}
 }
 // bodyLimit 给请求体套上限(S-03):超限读取由 MaxBytesReader 截断报错,
 // 绑定失败返回 400;webhook 入口另有独立 256KiB 自限,不经此中间件。
 func bodyLimit(n int64) gin.HandlerFunc {
@@ -45,7 +61,7 @@ func bodyLimit(n int64) gin.HandlerFunc {
 	}
 }
-// systemLogMiddleware 把写请求（POST/PUT/DELETE）异步记入系统日志，只读请求跳过。
+// systemLogMiddleware 把写请求（POST/PUT/PATCH/DELETE）异步记入系统日志，只读请求跳过。
 // 只记方法、路径等元数据，绝不读请求体——请求体可能含私钥 / 口令等敏感数据。
 func systemLogMiddleware(logs *service.SystemLogService) gin.HandlerFunc {
 	return func(c *gin.Context) {
@@ -101,17 +117,23 @@ func errMsgOf(status int, head []byte) string {
 	return truncateLogField(body.Error, 256)
 }
-// truncateLogField 按字节截断留痕字段,防超长 UA / 错误串撑爆列宽。
+// truncateLogField 按字节截断留痕字段,防超长 UA / 错误串撑爆列宽;
 // 截断点回退到 rune 边界,避免产生非法 UTF-8(严格 MySQL/PG 会拒写整行)。
 func truncateLogField(s string, max int) string {
 	if len(s) <= max {
 		return s
 	}
 	for max > 0 && !utf8.RuneStart(s[max]) {
 		max--
 	}
 	return s[:max]
 }
-// isWriteMethod 判断是否需要留痕的写方法。
+// isWriteMethod 判断是否需要留痕的写方法;PATCH 承载 OAuth / 安全设置等
 // 敏感配置变更,必须与 POST/PUT/DELETE 一样进入审计。
 func isWriteMethod(m string) bool {
-	return m == http.MethodPost || m == http.MethodPut || m == http.MethodDelete
+	return m == http.MethodPost || m == http.MethodPut ||
 		m == http.MethodPatch || m == http.MethodDelete
 }
 // requestPath 优先取注册的路由模板（含 :id 占位符，避免把敏感 query 记入日志），
@@ -0,0 +1,55 @@
 package api
 import (
 	"net/http"
 	"strings"
 	"testing"
 	"unicode/utf8"
 )
 // PATCH 承载 OAuth / 安全设置变更,必须纳入审计;只读方法不留痕。
 func TestIsWriteMethod(t *testing.T) {
 	tests := []struct {
 		method string
 		want   bool
 	}{
 		{http.MethodPost, true},
 		{http.MethodPut, true},
 		{http.MethodPatch, true},
 		{http.MethodDelete, true},
 		{http.MethodGet, false},
 		{http.MethodHead, false},
 	}
 	for _, tt := range tests {
 		if got := isWriteMethod(tt.method); got != tt.want {
 			t.Errorf("isWriteMethod(%s) = %v, want %v", tt.method, got, tt.want)
 		}
 	}
 }
 func TestTruncateLogField(t *testing.T) {
 	tests := []struct {
 		name string
 		in   string
 		max  int
 		want string
 	}{
 		{name: "短串原样", in: "abc", max: 10, want: "abc"},
 		{name: "ASCII 截断", in: "abcdef", max: 4, want: "abcd"},
 		{name: "中文边界回退", in: "中文日志", max: 4, want: "中"},
 		{name: "恰好落在边界", in: "中文", max: 3, want: "中"},
 		{name: "emoji 拦腰", in: "a😀b", max: 3, want: "a"},
 		{name: "超长 UA 不产非法序列", in: strings.Repeat("界", 200), max: 255, want: strings.Repeat("界", 85)},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			got := truncateLogField(tt.in, tt.max)
 			if got != tt.want {
 				t.Errorf("truncateLogField(%q, %d) = %q, want %q", tt.in, tt.max, got, tt.want)
 			}
 			if !utf8.ValidString(got) {
 				t.Errorf("result %q is not valid UTF-8", got)
 			}
 		})
 	}
 }
@@ -0,0 +1,464 @@
 package api
 import (
 	"errors"
 	"io"
 	"net/http"
 	"strconv"
 	"github.com/gin-gonic/gin"
 	"oci-portal/internal/oci"
 	"oci-portal/internal/service"
 )
 // ---- 对象存储 ----
 // @Summary  对象存储 namespace
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    region query string false "区域"
 // @Success  200 {object} map[string]string
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/object-storage/namespace [get]
 func (h *ociConfigHandler) osNamespace(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	ns, err := h.svc.ObjectStorageNamespace(c.Request.Context(), id, c.Query("region"))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"namespace": ns})
 }
 // @Summary  存储桶列表
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    region query string false "区域"
 // @Param    compartmentId query string false "区间 OCID,空为生效区间"
 // @Success  200 {array} oci.Bucket
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/buckets [get]
 func (h *ociConfigHandler) listBuckets(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	buckets, err := h.svc.Buckets(c.Request.Context(), id, c.Query("region"), c.Query("compartmentId"))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, buckets)
 }
 type createBucketRequest struct {
 	Region        string `json:"region"`
 	CompartmentID string `json:"compartmentId"`
 	Name          string `json:"name" binding:"required"`
 	PublicRead    bool   `json:"publicRead"`
 	StorageTier   string `json:"storageTier"` // Standard / Archive
 	VersioningOn  bool   `json:"versioningOn"`
 }
 // @Summary  创建存储桶
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    body body createBucketRequest true "请求体"
 // @Success  201 {object} oci.Bucket
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/buckets [post]
 func (h *ociConfigHandler) createBucket(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	var req createBucketRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
 	bucket, err := h.svc.CreateBucket(c.Request.Context(), id, req.Region, oci.CreateBucketInput{
 		Name: req.Name, CompartmentID: req.CompartmentID,
 		PublicRead: req.PublicRead, StorageTier: req.StorageTier, VersioningOn: req.VersioningOn,
 	})
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusCreated, bucket)
 }
 type updateBucketRequest struct {
 	Region       string `json:"region"`
 	PublicRead   *bool  `json:"publicRead"`
 	VersioningOn *bool  `json:"versioningOn"`
 }
 // @Summary  更新存储桶(可见性/版本控制)
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    bucket path string true "桶名"
 // @Param    body body updateBucketRequest true "请求体"
 // @Success  200 {object} oci.Bucket
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/buckets/{bucket} [put]
 func (h *ociConfigHandler) updateBucket(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	var req updateBucketRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
 	bucket, err := h.svc.UpdateBucket(c.Request.Context(), id, req.Region, c.Param("bucket"), oci.UpdateBucketInput{
 		PublicRead: req.PublicRead, VersioningOn: req.VersioningOn,
 	})
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, bucket)
 }
 // @Summary  删除存储桶(非空桶后台清空后删除)
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    bucket path string true "桶名"
 // @Param    region query string false "区域"
 // @Success  200 {object} map[string]bool "queued=true 表示已转后台清空删除"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/buckets/{bucket} [delete]
 func (h *ociConfigHandler) deleteBucket(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	queued, err := h.svc.DeleteBucket(c.Request.Context(), id, c.Query("region"), c.Param("bucket"))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"queued": queued})
 }
 // @Summary  对象列表(前缀模式分页)
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    bucket path string true "桶名"
 // @Param    region query string false "区域"
 // @Param    prefix query string false "前缀(虚拟目录)"
 // @Param    startWith query string false "上页 nextStartWith 游标"
 // @Param    limit query int false "每页数量,默认 100"
 // @Success  200 {object} oci.ListObjectsResult
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/buckets/{bucket}/objects [get]
 func (h *ociConfigHandler) listObjects(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	limit, _ := strconv.Atoi(c.Query("limit"))
 	result, err := h.svc.Objects(c.Request.Context(), id, c.Query("region"),
 		c.Param("bucket"), c.Query("prefix"), c.Query("startWith"), limit)
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, result)
 }
 // @Summary  删除对象
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    bucket path string true "桶名"
 // @Param    region query string false "区域"
 // @Param    object query string true "对象名(完整 key)"
 // @Success  204 "删除成功"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/buckets/{bucket}/objects [delete]
 func (h *ociConfigHandler) deleteObject(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	err := h.svc.DeleteObject(c.Request.Context(), id, c.Query("region"), c.Param("bucket"), c.Query("object"))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.Status(http.StatusNoContent)
 }
 // @Summary  重命名对象
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    bucket path string true "桶名"
 // @Param    body body object true "请求体:region、source、newName"
 // @Success  204 "重命名成功"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/buckets/{bucket}/objects/rename [post]
 func (h *ociConfigHandler) renameObject(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	var req struct {
 		Region  string `json:"region"`
 		Source  string `json:"source" binding:"required"`
 		NewName string `json:"newName" binding:"required"`
 	}
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
 	err := h.svc.RenameObject(c.Request.Context(), id, req.Region, c.Param("bucket"), req.Source, req.NewName)
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.Status(http.StatusNoContent)
 }
 // @Summary  取回 Archive 对象
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    bucket path string true "桶名"
 // @Param    body body object true "请求体:region、object、hours(可下载时长,默认 24)"
 // @Success  202 "取回已提交,约 1 小时后可下载"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/buckets/{bucket}/objects/restore [post]
 func (h *ociConfigHandler) restoreObject(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	var req struct {
 		Region string `json:"region"`
 		Object string `json:"object" binding:"required"`
 		Hours  int    `json:"hours"`
 	}
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
 	err := h.svc.RestoreObject(c.Request.Context(), id, req.Region, c.Param("bucket"), req.Object, req.Hours)
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.Status(http.StatusAccepted)
 }
 // @Summary  对象元数据
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    bucket path string true "桶名"
 // @Param    region query string false "区域"
 // @Param    object query string true "对象名(完整 key)"
 // @Success  200 {object} oci.ObjectDetail
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/buckets/{bucket}/objects/detail [get]
 func (h *ociConfigHandler) objectDetail(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	detail, err := h.svc.ObjectDetail(c.Request.Context(), id, c.Query("region"), c.Param("bucket"), c.Query("object"))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, detail)
 }
 // maxPutContentBody 是保存对象内容的请求体上限(与 service 层 5MB 限制一致)。
 const maxPutContentBody = 5 << 20
 // respondContentError 对象内容中转专属错误:超限映射 413,其余走通用处理。
 func respondContentError(c *gin.Context, err error) {
 	if errors.Is(err, oci.ErrObjectTooLarge) {
 		c.JSON(http.StatusRequestEntityTooLarge, gin.H{"error": "对象超出面板中转大小上限"})
 		return
 	}
 	respondError(c, err)
 }
 // @Summary  读取对象内容(面板中转)
 // @Description 预览/编辑用小文件直读(上限 20MB),不签发 PAR;响应体为原始字节,ETag 经响应头返回
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    bucket path string true "桶名"
 // @Param    region query string false "区域"
 // @Param    object query string true "对象名(完整 key)"
 // @Success  200 {string} string "对象原始内容"
 // @Failure  413 {object} map[string]string "对象超出中转上限"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/buckets/{bucket}/objects/content [get]
 func (h *ociConfigHandler) getObjectContent(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	content, err := h.svc.ObjectContent(c.Request.Context(), id, c.Query("region"), c.Param("bucket"), c.Query("object"))
 	if err != nil {
 		respondContentError(c, err)
 		return
 	}
 	ct := content.ContentType
 	if ct == "" {
 		ct = "application/octet-stream"
 	}
 	c.Header("ETag", content.Etag)
 	c.Data(http.StatusOK, ct, content.Data)
 }
 // @Summary  保存对象内容(面板中转)
 // @Description 文本编辑保存(上限 5MB),请求体为原始字节;If-Match 请求头做并发保护,冲突返回 412
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    bucket path string true "桶名"
 // @Param    region query string false "区域"
 // @Param    object query string true "对象名(完整 key)"
 // @Success  200 {object} map[string]string "etag=新 ETag"
 // @Failure  412 {object} map[string]string "If-Match 不匹配,对象已被并发修改"
 // @Failure  413 {object} map[string]string "请求体超出上限"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/buckets/{bucket}/objects/content [put]
 func (h *ociConfigHandler) putObjectContent(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, maxPutContentBody)
 	data, err := io.ReadAll(c.Request.Body)
 	if err != nil {
 		c.JSON(http.StatusRequestEntityTooLarge, gin.H{"error": "请求体超出 5MB 上限"})
 		return
 	}
 	etag, err := h.svc.PutObjectContent(c.Request.Context(), id, c.Query("region"), c.Param("bucket"),
 		c.Query("object"), data, c.ContentType(), c.GetHeader("If-Match"))
 	if err != nil {
 		respondContentError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"etag": etag})
 }
 type createPARRequest struct {
 	Region       string `json:"region"`
 	Name         string `json:"name"`
 	ObjectName   string `json:"objectName"` // 空 = 桶级
 	AccessType   string `json:"accessType" binding:"required"`
 	ExpiresHours int    `json:"expiresHours"`
 }
 // @Summary  签发临时链接(PAR)
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    bucket path string true "桶名"
 // @Param    body body createPARRequest true "请求体"
 // @Success  201 {object} oci.PAR "fullUrl 仅创建响应返回,请立即保存"
 // @Failure  400 {object} map[string]string "accessType 或 expiresHours 非法"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/buckets/{bucket}/pars [post]
 func (h *ociConfigHandler) createPAR(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	var req createPARRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
 	par, err := h.svc.CreatePAR(c.Request.Context(), id, req.Region, c.Param("bucket"), oci.CreatePARInput{
 		Name: req.Name, ObjectName: req.ObjectName, AccessType: req.AccessType, ExpiresHours: req.ExpiresHours,
 	})
 	if err != nil {
 		respondPARError(c, err)
 		return
 	}
 	c.JSON(http.StatusCreated, par)
 }
 func respondPARError(c *gin.Context, err error) {
 	switch {
 	case errors.Is(err, service.ErrPARInvalidAccessType):
 		c.JSON(http.StatusBadRequest, gin.H{"error": "accessType 不受支持"})
 	case errors.Is(err, service.ErrPARInvalidExpiration):
 		c.JSON(http.StatusBadRequest, gin.H{"error": "expiresHours 必须在 1-876000 范围内"})
 	default:
 		respondError(c, err)
 	}
 }
 // parPage 是 PAR 游标分页响应;nextPage 空串表示已到末页。
 type parPage struct {
 	Items    []oci.PAR `json:"items"`
 	NextPage string    `json:"nextPage"`
 }
 // @Summary  临时链接列表
 // @Description 游标分页:page 传上次响应的 nextPage,nextPage 为空表示已到末页
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    bucket path string true "桶名"
 // @Param    region query string false "区域"
 // @Param    page query string false "分页游标(上次响应的 nextPage,空取首页)"
 // @Param    limit query int false "每页条数,默认 100,上限 1000"
 // @Success  200 {object} parPage
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/buckets/{bucket}/pars [get]
 func (h *ociConfigHandler) listPARs(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	limit, _ := strconv.Atoi(c.Query("limit"))
 	items, next, err := h.svc.PARsPage(c.Request.Context(), id, c.Query("region"), c.Param("bucket"), c.Query("page"), limit)
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, parPage{Items: items, NextPage: next})
 }
 // @Summary  删除临时链接
 // @Description all=1 时删除桶内全部 PAR 并返回 {"deleted": n};否则按 parId 删单条
 // @Tags     对象存储
 // @Param    id path int true "配置 ID"
 // @Param    bucket path string true "桶名"
 // @Param    parId query string false "PAR ID(可含 / 等字符,故经 query 传递)"
 // @Param    all query string false "为 1 时删除全部"
 // @Param    region query string false "区域"
 // @Success  200 {object} map[string]int "all=1 时返回 {deleted: n}"
 // @Success  204 "按 parId 删单条成功,链接立即失效"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/buckets/{bucket}/pars [delete]
 func (h *ociConfigHandler) deletePAR(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	if c.Query("all") == "1" {
 		n, err := h.svc.DeleteAllPARs(c.Request.Context(), id, c.Query("region"), c.Param("bucket"))
 		if err != nil {
 			respondError(c, err)
 			return
 		}
 		c.JSON(http.StatusOK, gin.H{"deleted": n})
 		return
 	}
 	err := h.svc.DeletePAR(c.Request.Context(), id, c.Query("region"), c.Param("bucket"), c.Query("parId"))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.Status(http.StatusNoContent)
 }
@@ -277,6 +277,12 @@ func respondError(c *gin.Context, err error) {
 		c.JSON(http.StatusNotFound, gin.H{"error": "资源不存在"})
 		return
 	}
 	// 请求处理期间令牌已失效(撤销/注销/并发敏感操作后到):按未认证处理,
 	// 前端「发送时令牌==当前令牌」快照决定是否登出
 	if errors.Is(err, service.ErrTokenStale) {
 		c.JSON(http.StatusUnauthorized, gin.H{"error": err.Error()})
 		return
 	}
 	id := newRequestID()
 	log.Printf("[ERR %s] %s %s: %v", id, c.Request.Method, requestPath(c), err)
 	c.JSON(http.StatusInternalServerError, gin.H{"error": "服务器内部错误", "requestId": id})
@@ -0,0 +1,196 @@
 package api
 import (
 	"bytes"
 	"encoding/json"
 	"errors"
 	"net/http"
 	"strconv"
 	"time"
 	"github.com/gin-gonic/gin"
 	"oci-portal/internal/model"
 	"oci-portal/internal/service"
 )
 // passkeyHandler 处理通行密钥(WebAuthn)注册、登录与凭据管理接口。
 type passkeyHandler struct {
 	svc  *service.PasskeyService
 	auth *service.AuthService
 	logs *service.SystemLogService
 }
 // registerBegin 生成注册 options;sessionId 需原样带回 finish。
 //
 // @Summary  发起通行密钥注册
 // @Tags     认证
 // @Success  200 {object} passkeyOptionsResponse "sessionId 与 WebAuthn options"
 // @Failure  409 {object} errorResponse "面板地址未设置或数量达上限"
 // @Security BearerAuth
 // @Router   /api/v1/auth/passkey/register/begin [post]
 func (h *passkeyHandler) registerBegin(c *gin.Context) {
 	sid, opts, err := h.svc.BeginRegister(c.Request.Context(), c.GetString(usernameKey))
 	if err != nil {
 		if errors.Is(err, service.ErrPasskeyNoAppURL) || errors.Is(err, service.ErrPasskeyLimit) {
 			c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
 			return
 		}
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"sessionId": sid, "options": opts})
 }
 // passkeyFinishRequest 是注册/登录 finish 的请求体;credential 为浏览器
 // navigator.credentials 返回的 WebAuthn JSON,原样透传后端解析。
 type passkeyFinishRequest struct {
 	SessionId  string          `json:"sessionId" binding:"required,max=64"`
 	Name       string          `json:"name" binding:"max=64"`
 	Credential json.RawMessage `json:"credential" binding:"required"`
 }
 // registerFinish 校验注册响应并保存凭据;属敏感变更,换发新令牌。
 //
 // @Summary  完成通行密钥注册
 // @Tags     认证
 // @Param    body body passkeyFinishRequest true "sessionId、名称与凭据响应"
 // @Success  200 {object} tokenResponse "已注册,返回换发的新 token"
 // @Success  204 "已注册但新 token 签发失败,需重新登录"
 // @Failure  400 {object} errorResponse "请求体非法、会话过期或凭据校验失败"
 // @Security BearerAuth
 // @Router   /api/v1/auth/passkey/register/finish [post]
 func (h *passkeyHandler) registerFinish(c *gin.Context) {
 	var req passkeyFinishRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
 	err := h.svc.FinishRegister(c.Request.Context(), c.GetString(usernameKey),
 		req.SessionId, req.Name, bytes.NewReader(req.Credential), tokenProofOf(c))
 	if err != nil {
 		if errors.Is(err, service.ErrPasskeySession) || errors.Is(err, service.ErrPasskeyVerify) {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
 		respondError(c, err)
 		return
 	}
 	respondFreshToken(c, h.auth)
 }
 // list 列出当前账号的通行密钥。
 //
 // @Summary  通行密钥列表
 // @Tags     认证
 // @Success  200 {object} itemsResponse[model.UserPasskey] "items"
 // @Security BearerAuth
 // @Router   /api/v1/auth/passkeys [get]
 func (h *passkeyHandler) list(c *gin.Context) {
 	items, err := h.svc.List(c.Request.Context(), c.GetString(usernameKey))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"items": items})
 }
 // remove 删除通行密钥;属敏感变更,换发新令牌。
 // 密码登录禁用期间,最后一个免密登录方式不可删除(防自锁)。
 //
 // @Summary  删除通行密钥
 // @Tags     认证
 // @Param    id path int true "凭据 ID"
 // @Success  200 {object} tokenResponse "已删除,返回换发的新 token"
 // @Success  204 "已删除但新 token 签发失败,需重新登录"
 // @Failure  409 {object} errorResponse "密码登录已禁用且这是最后一个免密登录方式"
 // @Security BearerAuth
 // @Router   /api/v1/auth/passkeys/{id} [delete]
 func (h *passkeyHandler) remove(c *gin.Context) {
 	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
 	if err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
 		return
 	}
 	if err := h.svc.Remove(c.Request.Context(), c.GetString(usernameKey), uint(id), tokenProofOf(c)); err != nil {
 		if errors.Is(err, service.ErrLastIdentity) {
 			c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
 			return
 		}
 		respondError(c, err)
 		return
 	}
 	respondFreshToken(c, h.auth)
 }
 // loginBegin 生成登录断言 options(公开;无凭据也正常下发,不泄露账号状态)。
 //
 // @Summary  发起通行密钥登录
 // @Tags     认证
 // @Success  200 {object} passkeyOptionsResponse "sessionId 与 WebAuthn options"
 // @Failure  409 {object} errorResponse "面板地址未设置"
 // @Router   /api/v1/auth/passkey/login/begin [post]
 func (h *passkeyHandler) loginBegin(c *gin.Context) {
 	sid, opts, err := h.svc.BeginLogin(c.Request.Context())
 	if err != nil {
 		if errors.Is(err, service.ErrPasskeyNoAppURL) {
 			c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
 			return
 		}
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"sessionId": sid, "options": opts})
 }
 // loginFinish 校验断言并签发 JWT;凭 UV 豁免 TOTP。
 //
 // @Summary  完成通行密钥登录
 // @Tags     认证
 // @Param    body body passkeyFinishRequest true "sessionId 与断言响应(name 忽略)"
 // @Success  200 {object} tokenResponse "token 与 expiresAt"
 // @Failure  400 {object} errorResponse "请求体非法"
 // @Failure  401 {object} errorResponse "校验失败"
 // @Failure  429 {object} errorResponse "连续失败已锁定"
 // @Router   /api/v1/auth/passkey/login/finish [post]
 func (h *passkeyHandler) loginFinish(c *gin.Context) {
 	var req passkeyFinishRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
 	start := time.Now()
 	token, expires, username, err := h.svc.FinishLogin(
 		c.Request.Context(), req.SessionId, sessionMetaOf(c), bytes.NewReader(req.Credential))
 	if errors.Is(err, service.ErrLoginLocked) {
 		h.recordLogin(c, username, http.StatusTooManyRequests, "连续失败已锁定", start)
 		c.JSON(http.StatusTooManyRequests, gin.H{"error": err.Error()})
 		return
 	}
 	if err != nil {
 		// 统一 401 文案,不区分会话过期/校验失败,防探测
 		h.recordLogin(c, username, http.StatusUnauthorized, service.ErrPasskeyVerify.Error(), start)
 		c.JSON(http.StatusUnauthorized, gin.H{"error": service.ErrPasskeyVerify.Error()})
 		return
 	}
 	h.recordLogin(c, username, http.StatusOK, "", start)
 	c.JSON(http.StatusOK, gin.H{"token": token, "expiresAt": expires})
 }
 // recordLogin 记录通行密钥登录成败——公开端点不经系统日志中间件,
 // 登录失败是安全关键事件,必须留痕;失败时账号未知,username 为空。
 func (h *passkeyHandler) recordLogin(c *gin.Context, username string, status int, errMsg string, start time.Time) {
 	if h.logs == nil {
 		return
 	}
 	h.logs.Record(model.SystemLog{
 		Username:   username,
 		Method:     http.MethodPost,
 		Path:       requestPath(c),
 		Status:     status,
 		DurationMs: time.Since(start).Milliseconds(),
 		ClientIP:   requestIP(c),
 		UserAgent:  truncateLogField(c.Request.UserAgent(), 256),
 		ErrMsg:     errMsg,
 	})
 }
@@ -77,7 +77,9 @@ func IPRateMiddleware(settings *service.SettingService) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		sec := settings.SecurityCached()
 		if !lm.get(requestIP(c), sec.IPRateRPS, sec.IPRateBurst).Allow() {
-			c.AbortWithStatusJSON(http.StatusTooManyRequests, gin.H{"error": "rate limit exceeded"})
+			// code 供前端区分全局 IP 限流与登录守卫锁定(后者不带 code,留在表单内提示)
 			c.AbortWithStatusJSON(http.StatusTooManyRequests,
 				gin.H{"error": "rate limit exceeded", "code": "RateLimited"})
 			return
 		}
 		c.Next()
@@ -0,0 +1,110 @@
 package api
 import (
 	"net/http"
 	"github.com/gin-gonic/gin"
 	"oci-portal/internal/oci"
 )
 // swag 解析 @Success 里的 oci.ReservedIP 需要本文件持有该包导入
 var _ = oci.ReservedIP{}
 // ---- 保留公网 IP ----
 // @Summary  保留 IP 列表
 // @Tags     网络
 // @Param    id path int true "配置 ID"
 // @Param    region query string false "区域,空为主区域"
 // @Param    compartmentId query string false "区间 OCID,空为生效区间"
 // @Success  200 {array} oci.ReservedIP
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/reserved-ips [get]
 func (h *ociConfigHandler) listReservedIPs(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	ips, err := h.svc.ReservedIPs(c.Request.Context(), id, c.Query("region"), c.Query("compartmentId"))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, ips)
 }
 // @Summary  创建保留 IP
 // @Tags     网络
 // @Param    id path int true "配置 ID"
 // @Param    body body object true "请求体:region、compartmentId、displayName"
 // @Success  201 {object} oci.ReservedIP
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/reserved-ips [post]
 func (h *ociConfigHandler) createReservedIP(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	var req struct {
 		Region        string `json:"region"`
 		CompartmentID string `json:"compartmentId"`
 		DisplayName   string `json:"displayName"`
 	}
 	_ = c.ShouldBindJSON(&req)
 	ip, err := h.svc.CreateReservedIP(c.Request.Context(), id, req.Region, req.CompartmentID, req.DisplayName)
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusCreated, ip)
 }
 // @Summary  绑定/解绑保留 IP
 // @Description vnicId 非空时绑到该网卡,否则绑 instanceId 主网卡(两者都空为解绑);目标已有公网 IP 时自动释放/解绑
 // @Tags     网络
 // @Param    id path int true "配置 ID"
 // @Param    publicIpId path string true "保留 IP OCID"
 // @Param    body body object true "请求体:region、instanceId、vnicId"
 // @Success  204 "绑定成功"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/reserved-ips/{publicIpId} [put]
 func (h *ociConfigHandler) assignReservedIP(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	var req struct {
 		Region     string `json:"region"`
 		InstanceID string `json:"instanceId"`
 		VnicID     string `json:"vnicId"`
 	}
 	_ = c.ShouldBindJSON(&req)
 	err := h.svc.AssignReservedIP(c.Request.Context(), id, req.Region, c.Param("publicIpId"), req.InstanceID, req.VnicID)
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.Status(http.StatusNoContent)
 }
 // @Summary  删除保留 IP
 // @Tags     网络
 // @Param    id path int true "配置 ID"
 // @Param    publicIpId path string true "保留 IP OCID"
 // @Param    region query string false "区域"
 // @Success  204 "删除成功"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/reserved-ips/{publicIpId} [delete]
 func (h *ociConfigHandler) deleteReservedIP(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	err := h.svc.DeleteReservedIP(c.Request.Context(), id, c.Query("region"), c.Param("publicIpId"))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.Status(http.StatusNoContent)
 }
@@ -10,7 +10,7 @@ import (
 // NewRouter 组装 HTTP 路由骨架:中间件链、公开/鉴权分组与各域注册;
 // 具体路由按域拆在 routes_*.go。/auth/login 公开,业务路由要求 JWT。
-func NewRouter(auth *service.AuthService, oauth *service.OAuthService, ociConfigs *service.OciConfigService, tasks *service.TaskService, console *service.ConsoleService, settings *service.SettingService, notifier *service.Notifier, systemLogs *service.SystemLogService, logEvents *service.LogEventService, proxies *service.ProxyService, aiGateway *service.AiGatewayService) *gin.Engine {
+func NewRouter(auth *service.AuthService, oauth *service.OAuthService, passkeys *service.PasskeyService, wallets *service.WalletService, ociConfigs *service.OciConfigService, tasks *service.TaskService, console *service.ConsoleService, settings *service.SettingService, notifier *service.Notifier, systemLogs *service.SystemLogService, logEvents *service.LogEventService, proxies *service.ProxyService, aiGateway *service.AiGatewayService) *gin.Engine {
 	r := gin.New()
 	// 禁用 gin 内置代理信任:真实 IP 统一由 RealIPMiddleware 按安全设置解析
 	_ = r.SetTrustedProxies(nil)
@@ -23,17 +23,24 @@ func NewRouter(auth *service.AuthService, oauth *service.OAuthService, ociConfig
 	// 面板 API 请求体统一 1MB 上限(S-03);AI 网关按对话体量单独 10MB
 	v1 := r.Group("/api/v1", bodyLimit(1<<20))
-	registerAuthPublic(v1, auth, oauth, systemLogs)
+	registerAuthPublic(v1, auth, oauth, passkeys, wallets, systemLogs)
 	// AI 网关对外端点:独立密钥鉴权,挂在全局 Use 之后,仍受 IP 限速与 Recovery 保护
 	registerAiGateway(r, aiGateway)
 	// 系统日志中间件挂在鉴权之后,写请求自动留痕(webconsole ws 为 GET,天然跳过)
 	secured := v1.Group("", RequireAuth(auth), systemLogMiddleware(systemLogs))
-	registerAuthSecured(secured, auth, oauth, settings, systemLogs)
+	registerAuthSecured(secured, auth, oauth, passkeys, settings, systemLogs)
 	registerConsole(v1, secured, console, auth)
-	registerSettings(secured, settings, notifier, systemLogs, proxies)
+	registerSettings(secured, auth, settings, notifier, systemLogs, proxies)
 	registerTasksAndLogs(secured, tasks, logEvents)
 	registerOci(secured, ociConfigs)
 	// 上传类接口独立成组:文件本体上限 1MB,multipart 边界与字段头另占空间,
 	// 留在统一 1MB 的 v1 组里恰好 1MB 的文件会被截断;超限由 handler 映射 413
 	uploads := r.Group("/api/v1", bodyLimit(1<<20+64<<10), RequireAuth(auth), systemLogMiddleware(systemLogs))
 	registerOciUploads(uploads, ociConfigs)
 	// 对象内容中转 PUT:5MB 文件上限 + 封装余量,精确上限由 handler/service 执行
 	contentUploads := r.Group("/api/v1", bodyLimit(5<<20+64<<10), RequireAuth(auth), systemLogMiddleware(systemLogs))
 	registerOciContentUploads(contentUploads, ociConfigs)
 	registerAiAdmin(secured, aiGateway)
 	registerSwagger(r)
@@ -56,6 +56,14 @@ func (nullClient) GetSubscription(context.Context, oci.Credentials, string) (oci
 	return oci.SubscriptionDetail{}, nil
 }
 func (nullClient) UploadDomainImage(_ context.Context, _ oci.Credentials, _, _, fileName string, _ []byte) (string, string, error) {
 	return "https://images.example/" + fileName, "images/generated/" + fileName, nil
 }
 func (nullClient) DeleteDomainImage(context.Context, oci.Credentials, string, string, string) error {
 	return nil
 }
 func newTestRouter(t *testing.T) (*gin.Engine, *service.AuthService, *service.SystemLogService) {
 	t.Helper()
 	r, auth, systemLogs, _ := newTestRouterDB(t)
@@ -78,7 +86,7 @@ func newTestRouterDB(t *testing.T) (*gin.Engine, *service.AuthService, *service.
 		t.Fatalf("db handle: %v", err)
 	}
 	sqlDB.SetMaxOpenConns(1)
-	if err := db.AutoMigrate(&model.User{}, &model.OciConfig{}, &model.Task{}, &model.TaskLog{}, &model.Setting{}, &model.SystemLog{}, &model.LogEvent{}, &model.Proxy{}, &model.AiKey{}, &model.AiChannel{}, &model.AiModelCache{}, &model.AiCallLog{}); err != nil {
+	if err := db.AutoMigrate(&model.User{}, &model.UserPasskey{}, &model.UserSession{}, &model.OciConfig{}, &model.Task{}, &model.TaskLog{}, &model.Setting{}, &model.SystemLog{}, &model.LogEvent{}, &model.Proxy{}, &model.AiKey{}, &model.AiChannel{}, &model.AiModelCache{}, &model.AiCallLog{}); err != nil {
 		t.Fatalf("auto migrate: %v", err)
 	}
 	cipher, err := crypto.NewCipher("test-key")
@@ -96,7 +104,9 @@ func newTestRouterDB(t *testing.T) (*gin.Engine, *service.AuthService, *service.
 	systemLogs := service.NewSystemLogService(db)
 	logEvents := service.NewLogEventService(db)
 	oauth := service.NewOAuthService(db, settings, auth)
-	r := NewRouter(auth, oauth, ociConfigs, tasks, service.NewConsoleService(ociConfigs), settings, notifier, systemLogs, logEvents, service.NewProxyService(db, cipher), service.NewAiGatewayService(db, ociConfigs, nullClient{}))
+	passkeys := service.NewPasskeyService(db, settings, auth)
 	wallets := service.NewWalletService(db, settings, auth)
 	r := NewRouter(auth, oauth, passkeys, wallets, ociConfigs, tasks, service.NewConsoleService(ociConfigs), settings, notifier, systemLogs, logEvents, service.NewProxyService(db, cipher), service.NewAiGatewayService(db, ociConfigs, nullClient{}))
 	return r, auth, systemLogs, db
 }
@@ -138,7 +148,7 @@ func TestLoginEndpoint(t *testing.T) {
 func TestSecuredRoutesRequireToken(t *testing.T) {
 	r, auth, _ := newTestRouter(t)
-	token, _, err := auth.Login(context.Background(), "admin", "pass123", "127.0.0.1", "")
+	token, _, err := auth.Login(context.Background(), "admin", "pass123", "", service.SessionMeta{ClientIP: "127.0.0.1"})
 	if err != nil {
 		t.Fatalf("login: %v", err)
 	}
@@ -163,7 +173,7 @@ func TestSecuredRoutesRequireToken(t *testing.T) {
 func TestSystemLogsEndpoint(t *testing.T) {
 	r, auth, logs := newTestRouter(t)
-	token, _, err := auth.Login(context.Background(), "admin", "pass123", "127.0.0.1", "")
+	token, _, err := auth.Login(context.Background(), "admin", "pass123", "", service.SessionMeta{ClientIP: "127.0.0.1"})
 	if err != nil {
 		t.Fatalf("login: %v", err)
 	}
@@ -6,23 +6,44 @@ import (
 	"oci-portal/internal/service"
 )
-// registerAuthPublic 公开登录/OAuth 路由(不经 JWT)。
+// registerAuthPublic 公开登录/OAuth/通行密钥/钱包路由(不经 JWT)。
-func registerAuthPublic(v1 *gin.RouterGroup, auth *service.AuthService, oauth *service.OAuthService, systemLogs *service.SystemLogService) {
+func registerAuthPublic(v1 *gin.RouterGroup, auth *service.AuthService, oauth *service.OAuthService, passkeys *service.PasskeyService, wallets *service.WalletService, systemLogs *service.SystemLogService) {
 	ah := &authHandler{svc: auth, logs: systemLogs}
 	v1.POST("/auth/login", ah.login)
 	// 外部身份登录:provider 列表 / 授权跳转(bind 模式 handler 内校验 JWT)/ 回调
-	ax := &authxHandler{auth: auth, oauth: oauth, logs: systemLogs}
+	ax := &authxHandler{auth: auth, oauth: oauth, passkeys: passkeys, wallets: wallets, logs: systemLogs}
 	v1.GET("/auth/oauth/providers", ax.oauthProviders)
 	v1.GET("/auth/oauth/:provider/authorize", ax.oauthAuthorize)
 	v1.GET("/auth/oauth/:provider/callback", ax.oauthCallback)
 	// 通行密钥登录:断言 options 公开下发,finish 内部接入登录守卫
 	pk := &passkeyHandler{svc: passkeys, auth: auth, logs: systemLogs}
 	v1.POST("/auth/passkey/login/begin", pk.loginBegin)
 	v1.POST("/auth/passkey/login/finish", pk.loginFinish)
 	// 钱包登录/绑定:挑战-签名两段式(bind 模式 handler 内校验 JWT)
 	wl := &walletHandler{svc: wallets, auth: auth, logs: systemLogs}
 	v1.POST("/auth/wallet/challenge", wl.challenge)
 	v1.POST("/auth/wallet/verify", wl.verify)
 }
-// registerAuthSecured 登出、两步验证、外部身份管理(JWT 组内)。
+// registerAuthSecured 登出、两步验证、外部身份与通行密钥管理(JWT 组内)。
-func registerAuthSecured(secured *gin.RouterGroup, auth *service.AuthService, oauth *service.OAuthService, settings *service.SettingService, systemLogs *service.SystemLogService) {
+func registerAuthSecured(secured *gin.RouterGroup, auth *service.AuthService, oauth *service.OAuthService, passkeys *service.PasskeyService, settings *service.SettingService, systemLogs *service.SystemLogService) {
 	ah := &authHandler{svc: auth, logs: systemLogs}
 	secured.POST("/auth/logout", ah.logout)
 	pk := &passkeyHandler{svc: passkeys, auth: auth}
 	secured.POST("/auth/passkey/register/begin", pk.registerBegin)
 	secured.POST("/auth/passkey/register/finish", pk.registerFinish)
 	secured.GET("/auth/passkeys", pk.list)
 	secured.DELETE("/auth/passkeys/:id", pk.remove)
 	// 活跃会话:查看与定点撤销
 	sh := &sessionHandler{auth: auth}
 	secured.GET("/auth/sessions", sh.list)
 	secured.DELETE("/auth/sessions/:id", sh.revoke)
 	ax := &authxHandler{auth: auth, oauth: oauth}
 	secured.GET("/auth/totp", ax.totpStatus)
 	secured.POST("/auth/totp/setup", ax.totpSetup)
@@ -35,5 +56,5 @@ func registerAuthSecured(secured *gin.RouterGroup, auth *service.AuthService, oa
 	secured.DELETE("/auth/identities/:id", ax.unbindIdentity)
 	secured.POST("/auth/revoke-sessions", ax.revokeSessions)
 	secured.GET("/settings/oauth", func(c *gin.Context) { ax.getOAuthSettings(c, settings) })
-	secured.PUT("/settings/oauth", func(c *gin.Context) { ax.updateOAuthSettings(c, settings) })
+	secured.PATCH("/settings/oauth", func(c *gin.Context) { ax.updateOAuthSettings(c, settings) })
 }
@@ -16,6 +16,7 @@ func registerOci(secured *gin.RouterGroup, ociConfigs *service.OciConfigService)
 	registerOciCompute(secured, h)
 	registerOciNetwork(secured, h)
 	registerOciStorage(secured, h)
 	registerOciObjectStorage(secured, h)
 	registerOciCost(secured, h)
 	registerOciTenantIAM(secured, h)
 }
@@ -37,6 +38,13 @@ func registerOciConfig(g *gin.RouterGroup, h *ociConfigHandler) {
 	g.GET("/oci-configs/:id/limits/services", h.limitServices)
 	g.GET("/oci-configs/:id/subscriptions", h.subscriptions)
 	g.GET("/oci-configs/:id/subscriptions/:subscriptionId", h.subscriptionDetail)
 	// 账单:发票与付款方式(OSP Gateway,仅主区域)
 	g.GET("/oci-configs/:id/invoices", h.invoices)
 	g.GET("/oci-configs/:id/invoices/:internalId/lines", h.invoiceLines)
 	g.GET("/oci-configs/:id/invoices/:internalId/pdf", h.invoicePdf)
 	g.POST("/oci-configs/:id/invoices/:internalId/pay", h.payInvoice)
 	g.GET("/oci-configs/:id/payment-methods", h.paymentMethods)
 	g.GET("/oci-configs/:id/shapes", h.shapes)
 	g.GET("/oci-configs/:id/images", h.images)
 	g.GET("/oci-configs/:id/images/:imageId", h.getImage)
@@ -61,6 +69,7 @@ func registerOciCompute(g *gin.RouterGroup, h *ociConfigHandler) {
 	g.POST("/oci-configs/:id/instances/:instanceId/vnics", h.attachVnic)
 	g.DELETE("/oci-configs/:id/vnic-attachments/:attachmentId", h.detachVnic)
 	g.POST("/oci-configs/:id/vnics/:vnicId/ipv6-addresses", h.addVnicIpv6)
 	g.POST("/oci-configs/:id/vnics/:vnicId/change-public-ip", h.changeVnicPublicIP)
 	g.GET("/oci-configs/:id/instances/:instanceId/traffic", h.instanceTraffic)
 }
@@ -77,6 +86,10 @@ func registerOciNetwork(g *gin.RouterGroup, h *ociConfigHandler) {
 	g.GET("/oci-configs/:id/subnets/:subnetId", h.getSubnet)
 	g.PUT("/oci-configs/:id/subnets/:subnetId", h.updateSubnet)
 	g.DELETE("/oci-configs/:id/subnets/:subnetId", h.deleteSubnet)
 	g.GET("/oci-configs/:id/reserved-ips", h.listReservedIPs)
 	g.POST("/oci-configs/:id/reserved-ips", h.createReservedIP)
 	g.PUT("/oci-configs/:id/reserved-ips/:publicIpId", h.assignReservedIP)
 	g.DELETE("/oci-configs/:id/reserved-ips/:publicIpId", h.deleteReservedIP)
 	g.GET("/oci-configs/:id/security-lists", h.listSecurityLists)
 	g.POST("/oci-configs/:id/security-lists", h.createSecurityList)
 	g.GET("/oci-configs/:id/security-lists/:securityListId", h.getSecurityList)
@@ -100,6 +113,35 @@ func registerOciStorage(g *gin.RouterGroup, h *ociConfigHandler) {
 	g.DELETE("/oci-configs/:id/volume-attachments/:attachmentId", h.detachVolume)
 }
 // registerOciObjectStorage 对象存储:namespace、桶、对象、临时链接。
 func registerOciObjectStorage(g *gin.RouterGroup, h *ociConfigHandler) {
 	g.GET("/oci-configs/:id/object-storage/namespace", h.osNamespace)
 	g.GET("/oci-configs/:id/buckets", h.listBuckets)
 	g.POST("/oci-configs/:id/buckets", h.createBucket)
 	g.PUT("/oci-configs/:id/buckets/:bucket", h.updateBucket)
 	g.DELETE("/oci-configs/:id/buckets/:bucket", h.deleteBucket)
 	g.GET("/oci-configs/:id/buckets/:bucket/objects", h.listObjects)
 	g.DELETE("/oci-configs/:id/buckets/:bucket/objects", h.deleteObject)
 	g.POST("/oci-configs/:id/buckets/:bucket/objects/rename", h.renameObject)
 	g.POST("/oci-configs/:id/buckets/:bucket/objects/restore", h.restoreObject)
 	g.GET("/oci-configs/:id/buckets/:bucket/objects/detail", h.objectDetail)
 	// 小文件中转:预览/编辑直读直写,不签发 PAR
 	g.GET("/oci-configs/:id/buckets/:bucket/objects/content", h.getObjectContent)
 	g.GET("/oci-configs/:id/buckets/:bucket/pars", h.listPARs)
 	g.POST("/oci-configs/:id/buckets/:bucket/pars", h.createPAR)
 	// parId 经 query 传递:OCI PAR id 含 "/" 等字符,路径参数无法匹配
 	g.DELETE("/oci-configs/:id/buckets/:bucket/pars", h.deletePAR)
 }
 // registerOciUploads 挂需放宽请求体上限的上传接口;router 侧以独立组绕开
 // v1 统一 1MB bodyLimit(multipart 除文件本体外还有边界与字段头开销)。
 // idp-icons 用独立路径,避免与 /identity-providers/:idpId 同段静态/参数混排。
 func registerOciUploads(g *gin.RouterGroup, ociConfigs *service.OciConfigService) {
 	h := &ociConfigHandler{svc: ociConfigs}
 	g.POST("/oci-configs/:id/idp-icons", h.uploadIdpIcon)
 	g.DELETE("/oci-configs/:id/idp-icons", h.deleteIdpIcon)
 }
 // registerOciCost 成本快照。
 func registerOciCost(g *gin.RouterGroup, h *ociConfigHandler) {
 	g.GET("/oci-configs/:id/costs", h.costs)
@@ -118,6 +160,10 @@ func registerOciTenantIAM(g *gin.RouterGroup, h *ociConfigHandler) {
 	g.POST("/oci-configs/:id/users/:userId/reset-password", h.resetTenantUserPassword)
 	g.DELETE("/oci-configs/:id/users/:userId/mfa-devices", h.deleteTenantUserMfa)
 	g.DELETE("/oci-configs/:id/users/:userId/api-keys", h.deleteTenantUserApiKeys)
 	g.GET("/oci-configs/:id/users/:userId/api-keys", h.listTenantUserApiKeys)
 	g.POST("/oci-configs/:id/users/:userId/api-keys", h.addTenantUserApiKey)
 	g.DELETE("/oci-configs/:id/users/:userId/api-keys/:fingerprint", h.deleteTenantUserApiKey)
 	g.POST("/oci-configs/:id/activate-api-key", h.activateApiKey)
 	g.GET("/oci-configs/:id/notification-recipients", h.getNotificationRecipients)
 	g.PUT("/oci-configs/:id/notification-recipients", h.updateNotificationRecipients)
 	g.GET("/oci-configs/:id/password-policies", h.listPasswordPolicies)
@@ -133,3 +179,11 @@ func registerOciTenantIAM(g *gin.RouterGroup, h *ociConfigHandler) {
 	g.POST("/oci-configs/:id/sign-on-exemptions", h.createMfaExemption)
 	g.DELETE("/oci-configs/:id/sign-on-exemptions/:ruleId", h.deleteMfaExemption)
 }
 // registerOciContentUploads 挂对象内容保存接口(编辑器直写,5MB 文件上限);
 // 必须留在独立的大 body limit 组:统一 1MB 组会先截断请求,handler 的 5MB
 // 上限与 swagger 声明就成了空话(2026-07 全量审查 #11)。
 func registerOciContentUploads(g *gin.RouterGroup, ociConfigs *service.OciConfigService) {
 	h := &ociConfigHandler{svc: ociConfigs}
 	g.PUT("/oci-configs/:id/buckets/:bucket/objects/content", h.putObjectContent)
 }
@@ -7,11 +7,11 @@ import (
 )
 // registerSettings 挂载 /settings/* 与 /about,以及系统日志与代理管理。
-func registerSettings(secured *gin.RouterGroup, settings *service.SettingService, notifier *service.Notifier, systemLogs *service.SystemLogService, proxies *service.ProxyService) {
+func registerSettings(secured *gin.RouterGroup, auth *service.AuthService, settings *service.SettingService, notifier *service.Notifier, systemLogs *service.SystemLogService, proxies *service.ProxyService) {
 	secured.GET("/about", about)
 	secured.GET("/system-logs", (&systemLogHandler{svc: systemLogs}).list)
-	st := &settingsHandler{svc: settings, notifier: notifier}
+	st := &settingsHandler{svc: settings, auth: auth, notifier: notifier}
 	secured.GET("/settings/telegram", st.getTelegram)
 	secured.PUT("/settings/telegram", st.updateTelegram)
 	secured.POST("/settings/telegram/test", st.testTelegram)
@@ -26,7 +26,7 @@ func registerSettings(secured *gin.RouterGroup, settings *service.SettingService
 	secured.GET("/settings/task", st.getTaskSettings)
 	secured.PUT("/settings/task", st.updateTaskSettings)
 	secured.GET("/settings/security", st.getSecurity)
-	secured.PUT("/settings/security", st.updateSecurity)
+	secured.PATCH("/settings/security", st.updateSecurity)
 	px := &proxyHandler{svc: proxies}
 	secured.GET("/proxies", px.list)
@@ -0,0 +1,85 @@
 package api
 import (
 	"errors"
 	"net/http"
 	"strconv"
 	"strings"
 	"github.com/gin-gonic/gin"
 	"gorm.io/gorm"
 	"oci-portal/internal/service"
 )
 // sessionHandler 处理活跃会话查看与定点撤销接口。
 type sessionHandler struct {
 	auth *service.AuthService
 }
 // bearerToken 取 Authorization 头中的原始令牌串;不存在返回空串。
 func bearerToken(c *gin.Context) string {
 	token, ok := strings.CutPrefix(c.GetHeader("Authorization"), "Bearer ")
 	if !ok {
 		return ""
 	}
 	return token
 }
 // sessionMetaOf 采集会话登记所需的客户端上下文;登录方式由 service 层填写。
 func sessionMetaOf(c *gin.Context) service.SessionMeta {
 	return service.SessionMeta{
 		ClientIP:  requestIP(c),
 		UserAgent: truncateLogField(c.Request.UserAgent(), 256),
 	}
 }
 // list 列出当前账号的活跃会话,最近活跃在前,当前会话带 current 标记。
 //
 // @Summary  活跃会话列表
 // @Tags     认证
 // @Success  200 {object} itemsResponse[service.SessionInfo] "items"
 // @Security BearerAuth
 // @Router   /api/v1/auth/sessions [get]
 func (h *sessionHandler) list(c *gin.Context) {
 	items, err := h.auth.ListSessions(c.Request.Context(), c.GetString(usernameKey), bearerToken(c))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"items": items})
 }
 // revoke 定点撤销一个其他会话;该会话令牌随即失效,不影响其余会话。
 //
 // @Summary  撤销单个会话
 // @Tags     认证
 // @Param    id path int true "会话 ID"
 // @Success  204 "已撤销"
 // @Failure  400 {object} errorResponse "id 非法"
 // @Failure  404 {object} errorResponse "会话不存在"
 // @Failure  409 {object} errorResponse "不能撤销当前会话"
 // @Security BearerAuth
 // @Router   /api/v1/auth/sessions/{id} [delete]
 func (h *sessionHandler) revoke(c *gin.Context) {
 	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
 	if err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid id"})
 		return
 	}
 	err = h.auth.RevokeSession(c.Request.Context(), c.GetString(usernameKey), bearerToken(c), uint(id))
 	if errors.Is(err, service.ErrSessionCurrent) {
 		c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
 		return
 	}
 	if errors.Is(err, gorm.ErrRecordNotFound) {
 		c.JSON(http.StatusNotFound, gin.H{"error": "会话不存在或已失效"})
 		return
 	}
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.Status(http.StatusNoContent)
 }
@@ -12,6 +12,7 @@ import (
 // settingsHandler 处理系统设置（Telegram 通知）相关请求。
 type settingsHandler struct {
 	svc      *service.SettingService
 	auth     *service.AuthService
 	notifier *service.Notifier
 }
@@ -316,25 +317,35 @@ func (h *settingsHandler) getSecurity(c *gin.Context) {
 	c.JSON(http.StatusOK, view)
 }
-// updateSecurity 保存安全设置并返回最新值;越界或非法返回 400,保存后立即生效。
+// updateSecurity 部分更新安全设置并返回最新值;只落库请求中出现的字段,
 // 越界或非法返回 400,保存后立即生效。
 //
-// @Summary  保存安全设置并返回最新值
+// @Summary  部分更新安全设置并返回最新值
 // @Tags     设置
-// @Param    body body service.SecuritySettings true "请求体"
+// @Param    body body service.SecurityPatch true "出现的字段才会被更新"
 // @Success  200 {object} service.SecuritySettings
 // @Failure  400 {object} errorResponse "字段越界或非法"
 // @Failure  401 {object} errorResponse "请求处理期间会话已撤销"
 // @Failure  409 {object} errorResponse "密码登录禁用期间,面板地址变更将移除最后可用登录方式"
 // @Security BearerAuth
-// @Router   /api/v1/settings/security [put]
+// @Router   /api/v1/settings/security [patch]
 func (h *settingsHandler) updateSecurity(c *gin.Context) {
-	var req service.SecuritySettings
+	var req service.SecurityPatch
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
-	if err := h.svc.UpdateSecurity(c.Request.Context(), req); err != nil {
+	err := h.svc.UpdateSecurityAuthenticated(
 		c.Request.Context(), req, h.auth, c.GetString(usernameKey), tokenProofOf(c))
 	if err != nil {
 		if errors.Is(err, service.ErrInvalidSecurity) {
 			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 			return
 		}
 		if errors.Is(err, service.ErrProviderLastLogin) {
 			c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
 			return
 		}
 		respondError(c, err)
 		return
 	}
@@ -15,6 +15,9 @@ import (
 // errorResponse 是统一错误响应外壳。
 type errorResponse struct {
 	Error string `json:"error"`
 	// Code 是机器可读错误码,多数错误不携带;当前仅全局 IP 限流的 429
 	// 返回 "RateLimited",前端据此与登录守卫的 429(无 code)区分
 	Code string `json:"code,omitempty"`
 }
 // itemsResponse 是 {"items": [...]} 列表外壳。
@@ -71,6 +74,20 @@ type credentialsResponse struct {
 type oauthProvidersResponse struct {
 	Providers             []service.ProviderInfo `json:"providers"`
 	PasswordLoginDisabled bool                   `json:"passwordLoginDisabled"`
 	PasskeyLogin          bool                   `json:"passkeyLogin"`
 	WalletLogin           bool                   `json:"walletLogin"`
 }
 // walletChallengeResponse 是钱包签名挑战响应;message 需原样 personal_sign。
 type walletChallengeResponse struct {
 	Nonce   string `json:"nonce"`
 	Message string `json:"message"`
 }
 // passkeyOptionsResponse 是 WebAuthn 仪式 options 响应;sessionId 需原样带回 finish。
 type passkeyOptionsResponse struct {
 	SessionId string          `json:"sessionId"`
 	Options   json.RawMessage `json:"options"`
 }
 // urlResponse 是跳转地址响应。
@@ -157,6 +174,11 @@ type deletedApiKeysResponse struct {
 	DeletedApiKeys int `json:"deletedApiKeys"`
 }
 // userApiKeysResponse 是用户 API 签名 key 列表。
 type userApiKeysResponse struct {
 	Items []service.UserApiKeyInfo `json:"items"`
 }
 // createInstancesResponse 是批量创建实例结果;部分成功仍 201,errors 为逐台失败信息。
 type createInstancesResponse struct {
 	Instances []oci.Instance `json:"instances"`
@@ -92,8 +92,10 @@ func (h *taskHandler) get(c *gin.Context) {
 // @Summary  更新任务
 // @Tags     任务与日志回传
 // @Param    id path int true "任务 ID"
-// @Param    body body updateTaskRequest true "可更新字段"
+// @Param    body body updateTaskRequest true "可更新字段;抢机 payload 的 count 语义为目标台数"
 // @Success  200 {object} model.Task
 // @Failure  400 {object} errorResponse "参数非法或抢机目标不大于已完成数量"
 // @Failure  409 {object} errorResponse "任务被并发修改,须刷新重试"
 // @Security BearerAuth
 // @Router   /api/v1/tasks/{id} [put]
 func (h *taskHandler) update(c *gin.Context) {
@@ -113,12 +115,24 @@ func (h *taskHandler) update(c *gin.Context) {
 		Status:   req.Status,
 	})
 	if err != nil {
-		respondError(c, err)
+		respondUpdateTaskErr(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, task)
 }
 // respondUpdateTaskErr 把任务编辑的哨兵错误映射为语义状态码,其余走统一错误边界。
 func respondUpdateTaskErr(c *gin.Context, err error) {
 	switch {
 	case errors.Is(err, service.ErrTaskConflict):
 		c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
 	case errors.Is(err, service.ErrSnatchTargetTooLow):
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 	default:
 		respondError(c, err)
 	}
 }
 // @Summary  删除任务
 // @Tags     任务与日志回传
 // @Param    id path int true "任务 ID"
@@ -38,6 +38,11 @@ func (h *ociConfigHandler) instanceTraffic(c *gin.Context) {
 // @Summary  配置成本快照
 // @Tags     成本
 // @Param    id path int true "配置 ID"
 // @Param    startTime query string false "起始时间 RFC3339,缺省为 endTime-30 天;返回行严格限于 [startTime, endTime) 窗口(Usage API HOURLY 粒度会把起点下扩到 UTC 日零点,越界行已在服务端过滤)"
 // @Param    endTime query string false "结束时间 RFC3339,缺省为当前时刻"
 // @Param    granularity query string false "HOURLY / DAILY / MONTHLY,缺省 DAILY"
 // @Param    queryType query string false "COST / USAGE,缺省 COST"
 // @Param    groupBy query string false "分组维度,单维或复合(如 service,skuName),缺省 service"
 // @Success  200 {array} oci.CostItem
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/costs [get]
@@ -366,6 +371,102 @@ func (h *ociConfigHandler) deleteTenantUserApiKeys(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"deletedApiKeys": deleted})
 }
 // @Summary  列出用户 API Key
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    userId path string true "userId"
 // @Success  200 {object} userApiKeysResponse
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/users/{userId}/api-keys [get]
 func (h *ociConfigHandler) listTenantUserApiKeys(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	keys, err := h.svc.TenantUserApiKeys(c.Request.Context(), id, c.Param("userId"))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"items": keys})
 }
 // @Summary  为用户新增 API Key
 // @Description  后端生成 RSA-2048 密钥对并上传公钥;私钥仅本次响应返回,不落库。
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    userId path string true "userId"
 // @Success  200 {object} service.CreatedApiKey
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/users/{userId}/api-keys [post]
 func (h *ociConfigHandler) addTenantUserApiKey(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	created, err := h.svc.AddTenantUserApiKey(c.Request.Context(), id, c.Param("userId"))
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, created)
 }
 // @Summary  删除用户单把 API Key
 // @Description  当前配置正在使用的 key 拒删(409),避免面板失联。
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    userId path string true "userId"
 // @Param    fingerprint path string true "key 指纹"
 // @Success  204 "无内容"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/users/{userId}/api-keys/{fingerprint} [delete]
 func (h *ociConfigHandler) deleteTenantUserApiKey(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	err := h.svc.DeleteTenantUserApiKey(c.Request.Context(), id, c.Param("userId"), c.Param("fingerprint"))
 	if errors.Is(err, service.ErrCurrentApiKey) {
 		c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
 		return
 	}
 	if err != nil {
 		respondError(c, err)
 		return
 	}
 	c.Status(http.StatusNoContent)
 }
 // @Summary  启用 API Key 为面板签名凭据
 // @Description  将刚创建的 key 设为本配置签名凭据:验证可用后落库,不删除旧 key;私钥为创建时下发的那份回传。userId 给定且异于当前签名用户时,一并把签名用户切换为该用户。
 // @Tags     租户 IAM
 // @Param    id path int true "配置 ID"
 // @Param    body body object true "请求体:fingerprint 与 privateKey,可选 userId(切换签名用户)"
 // @Success  204 "无内容"
 // @Security BearerAuth
 // @Router   /api/v1/oci-configs/{id}/activate-api-key [post]
 func (h *ociConfigHandler) activateApiKey(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
 		return
 	}
 	var req struct {
 		UserID      string `json:"userId"`
 		Fingerprint string `json:"fingerprint"`
 		PrivateKey  string `json:"privateKey"`
 	}
 	if err := c.ShouldBindJSON(&req); err != nil || req.Fingerprint == "" || req.PrivateKey == "" {
 		c.JSON(http.StatusBadRequest, gin.H{"error": "fingerprint 与 privateKey 必填"})
 		return
 	}
 	if err := h.svc.ActivateApiKey(c.Request.Context(), id, req.UserID, req.Fingerprint, req.PrivateKey); err != nil {
 		respondError(c, err)
 		return
 	}
 	c.Status(http.StatusNoContent)
 }
 // ---- 域通知收件人与密码策略 ----
 // @Summary  ---- 域通知收件人与密码策略 ----
@@ -0,0 +1,161 @@
 package api
 import (
 	"errors"
 	"net/http"
 	"time"
 	"github.com/gin-gonic/gin"
 	"oci-portal/internal/model"
 	"oci-portal/internal/service"
 )
 // walletHandler 处理钱包(SIWE)签名挑战与校验接口。
 type walletHandler struct {
 	svc  *service.WalletService
 	auth *service.AuthService
 	logs *service.SystemLogService
 }
 // walletChallengeRequest 是签名挑战请求;mode=bind 需有效 Bearer(绑定到当前账号)。
 type walletChallengeRequest struct {
 	Address string `json:"address" binding:"required,max=64"`
 	Mode    string `json:"mode" binding:"omitempty,oneof=login bind"`
 }
 // challenge 下发 EIP-4361 消息与一次性 nonce;前端对消息原样 personal_sign。
 //
 // @Summary  发起钱包签名挑战
 // @Tags     认证
 // @Param    body body walletChallengeRequest true "钱包地址与模式(bind 需 Bearer)"
 // @Success  200 {object} walletChallengeResponse "nonce 与待签名消息"
 // @Failure  400 {object} errorResponse "地址格式不正确"
 // @Failure  401 {object} errorResponse "bind 模式未登录"
 // @Failure  409 {object} errorResponse "面板地址未设置"
 // @Router   /api/v1/auth/wallet/challenge [post]
 func (h *walletHandler) challenge(c *gin.Context) {
 	var req walletChallengeRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
 	mode, username := "login", ""
 	if req.Mode == "bind" {
 		name, ok := (&authxHandler{auth: h.auth}).bearerUser(c)
 		if !ok {
 			c.JSON(http.StatusUnauthorized, gin.H{"error": "绑定需要先登录"})
 			return
 		}
 		mode, username = "bind", name
 	}
 	nonce, message, err := h.svc.Challenge(c.Request.Context(), req.Address, mode, username, bearerToken(c))
 	if err != nil {
 		h.respondChallengeErr(c, err)
 		return
 	}
 	c.JSON(http.StatusOK, gin.H{"nonce": nonce, "message": message})
 }
 // respondChallengeErr 映射挑战阶段错误。
 func (h *walletHandler) respondChallengeErr(c *gin.Context, err error) {
 	if errors.Is(err, service.ErrWalletAddress) {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
 	if errors.Is(err, service.ErrWalletNoAppURL) {
 		c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
 		return
 	}
 	respondError(c, err)
 }
 // walletVerifyRequest 是签名校验请求;signature 为 65 字节 r||s||v 的 hex。
 type walletVerifyRequest struct {
 	Nonce     string `json:"nonce" binding:"required,max=64"`
 	Signature string `json:"signature" binding:"required,max=200"`
 }
 // verify 校验签名:login 模式签发 JWT,bind 模式绑定后换发新令牌。
 //
 // @Summary  校验钱包签名
 // @Tags     认证
 // @Param    body body walletVerifyRequest true "nonce 与签名"
 // @Success  200 {object} tokenResponse "token 与 expiresAt(bind 模式为换发的新 token)"
 // @Failure  400 {object} errorResponse "挑战无效已过期,或 bind 模式签名校验失败"
 // @Failure  401 {object} errorResponse "签名校验失败(login 模式)"
 // @Failure  403 {object} errorResponse "地址未绑定账号"
 // @Failure  409 {object} errorResponse "地址已绑定过"
 // @Failure  429 {object} errorResponse "连续失败已锁定"
 // @Router   /api/v1/auth/wallet/verify [post]
 func (h *walletHandler) verify(c *gin.Context) {
 	var req walletVerifyRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
 		return
 	}
 	start := time.Now()
 	res, err := h.svc.Verify(c.Request.Context(), req.Nonce, req.Signature, sessionMetaOf(c))
 	if err != nil {
 		status := walletErrStatus(err)
 		// bind 是已登录流程:验签失败不可回 401,否则前端全局拦截会误登出有效会话
 		if res.Mode == "bind" && status == http.StatusUnauthorized {
 			status = http.StatusBadRequest
 		}
 		h.recordWallet(c, res.Username, status, err, start)
 		c.JSON(status, gin.H{"error": walletErrText(err)})
 		return
 	}
 	h.recordWallet(c, res.Username, http.StatusOK, nil, start)
 	// login 与 bind 同构响应;bind 的 token 为版本递增后换发的新会话
 	c.JSON(http.StatusOK, gin.H{"token": res.Token, "expiresAt": res.ExpiresAt})
 }
 // walletErrStatus 映射校验阶段错误码。
 func walletErrStatus(err error) int {
 	switch {
 	case errors.Is(err, service.ErrLoginLocked):
 		return http.StatusTooManyRequests
 	case errors.Is(err, service.ErrWalletChallenge):
 		return http.StatusBadRequest
 	case errors.Is(err, service.ErrWalletNotBound):
 		return http.StatusForbidden
 	case errors.Is(err, service.ErrWalletBound):
 		return http.StatusConflict
 	case errors.Is(err, service.ErrWalletSig):
 		return http.StatusUnauthorized
 	default:
 		return http.StatusInternalServerError
 	}
 }
 // walletErrText 把流程错误转为用户可读文案;内部错误不透出细节。
 func walletErrText(err error) string {
 	for _, known := range []error{service.ErrLoginLocked, service.ErrWalletChallenge, service.ErrWalletNotBound, service.ErrWalletBound, service.ErrWalletSig} {
 		if errors.Is(err, known) {
 			return known.Error()
 		}
 	}
 	return "校验失败,请重试"
 }
 // recordWallet 记录钱包登录/绑定结果——公开端点不经系统日志中间件,须显式留痕。
 func (h *walletHandler) recordWallet(c *gin.Context, username string, status int, err error, start time.Time) {
 	if h.logs == nil {
 		return
 	}
 	errMsg := ""
 	if err != nil {
 		errMsg = walletErrText(err)
 	}
 	h.logs.Record(model.SystemLog{
 		Username:   username,
 		Method:     http.MethodPost,
 		Path:       requestPath(c),
 		Status:     status,
 		DurationMs: time.Since(start).Milliseconds(),
 		ClientIP:   requestIP(c),
 		UserAgent:  truncateLogField(c.Request.UserAgent(), 256),
 		ErrMsg:     errMsg,
 	})
 }
@@ -64,7 +64,7 @@ func buildDialector(driver, dsn, path string) (gorm.Dialector, error) {
 func autoMigrate(db *gorm.DB) error {
 	return db.AutoMigrate(
-		&model.User{}, &model.UserIdentity{}, &model.OciConfig{}, &model.Task{}, &model.TaskLog{},
+		&model.User{}, &model.UserIdentity{}, &model.UserPasskey{}, &model.UserSession{}, &model.OciConfig{}, &model.Task{}, &model.TaskLog{},
 		&model.CheckSnapshot{}, &model.CostSnapshot{},
 		&model.RegionCache{}, &model.CompartmentCache{}, &model.Setting{},
 		&model.SystemLog{}, &model.LogEvent{}, &model.Proxy{},
@@ -86,6 +86,45 @@ type UserIdentity struct {
 	CreatedAt time.Time `json:"createdAt"`
 }
 // UserPasskey 是账号绑定的 WebAuthn 通行密钥;公钥非敏感,凭据整段 JSON 明文落库。
 type UserPasskey struct {
 	ID     uint   `gorm:"primaryKey" json:"id"`
 	UserID uint   `gorm:"index" json:"-"`
 	Name   string `gorm:"size:64" json:"name"`
 	// 凭据 ID(base64url)原文:规范允许原始 ID 达 1023 字节、编码后逾千字符,
 	// 存 text 不设索引;唯一约束与登录反查走下方定长哈希列
 	CredentialID string `gorm:"type:text" json:"-"`
 	// 凭据 ID 的 SHA-256 hex(定长 64):唯一索引防同一验证器重复注册
 	CredentialIDHash string `gorm:"size:64;uniqueIndex" json:"-"`
 	// 注册时的 WebAuthn origin(scheme://host):面板地址变更后按它判定
 	// 该凭据是否仍可登录(RP ID / origin 绑定注册时域名)
 	Origin string `gorm:"size:255" json:"-"`
 	// webauthn.Credential 完整 JSON(公钥/signCount/flags);attestation 可上 KB,
 	// 显式 text 防 MySQL DefaultStringSize 截断;校验后 signCount 有更新,整段重写
 	Credential string     `gorm:"type:text" json:"-"`
 	CreatedAt  time.Time  `json:"createdAt"`
 	LastUsedAt *time.Time `json:"lastUsedAt"`
 }
 // UserSession 是一次已签发登录会话(JWT)的落地记录;
 // 「活跃」判定 = 未撤销 && 未过期 && token_ver == 账号当前版本。
 // 升级前签发的存量令牌无对应行,校验时放行(兼容),仅不可见/不可定点撤销。
 type UserSession struct {
 	ID     uint `gorm:"primaryKey" json:"id"`
 	UserID uint `gorm:"index" json:"-"`
 	// JWT jti;敏感变更换发时同行更新(会话接续),不产生新条目
 	TokenID  string `gorm:"size:64;uniqueIndex" json:"-"`
 	TokenVer uint   `json:"-"`
 	// 登录方式:password / oidc / github / passkey / wallet;接续换发保留原值
 	Method     string     `gorm:"size:16" json:"method"`
 	ClientIP   string     `gorm:"size:64" json:"clientIp"`
 	UserAgent  string     `gorm:"size:256" json:"userAgent"`
 	CreatedAt  time.Time  `json:"createdAt"`
 	LastSeenAt time.Time  `json:"lastSeenAt"`
 	ExpiresAt  time.Time  `json:"expiresAt"`
 	RevokedAt  *time.Time `json:"-"`
 }
 // 任务类型取值。
 const (
 	TaskTypeHealthCheck = "health_check" // 定时测活
@@ -229,6 +268,7 @@ type CompartmentCache struct {
 	OciConfigID uint      `gorm:"index;uniqueIndex:idx_comp_cache" json:"-"`
 	OCID        string    `gorm:"size:128;uniqueIndex:idx_comp_cache" json:"id"`
 	Name        string    `gorm:"size:128" json:"name"`
 	ParentOCID  string    `gorm:"size:128" json:"parentId"`
 	State       string    `gorm:"size:16" json:"lifecycleState"`
 	UpdatedAt   time.Time `json:"updatedAt"`
 }
@@ -0,0 +1,320 @@
 package oci
 import (
 	"context"
 	"fmt"
 	"io"
 	"math"
 	"strings"
 	"time"
 	"github.com/oracle/oci-go-sdk/v65/common"
 	"github.com/oracle/oci-go-sdk/v65/ospgateway"
 )
 // 账单能力封装 OSP Gateway(发票列表/明细/PDF/付款与订阅付款方式)。
 // 该服务只在租户主区域提供,所有请求都要携带 ospHomeRegion 并发往主区域。
 // Invoice 是一张发票的摘要(InvoiceSummary 的面板投影)。
 type Invoice struct {
 	ID              string     `json:"id"`
 	InternalID      string     `json:"internalId"`
 	Number          string     `json:"number"`
 	Type            string     `json:"type"`
 	Status          string     `json:"status"`
 	IsPaid          bool       `json:"isPaid"`
 	IsPayable       bool       `json:"isPayable"`
 	IsPaymentFailed bool       `json:"isPaymentFailed"`
 	Amount          float64    `json:"amount"`
 	AmountDue       float64    `json:"amountDue"`
 	Currency        string     `json:"currency"`
 	TimeInvoice     *time.Time `json:"timeInvoice"`
 	TimeDue         *time.Time `json:"timeDue"`
 }
 // InvoiceLine 是发票内一行费用明细。
 type InvoiceLine struct {
 	Product   string     `json:"product"`
 	OrderNo   string     `json:"orderNo"`
 	Quantity  float64    `json:"quantity"`
 	UnitPrice float64    `json:"unitPrice"`
 	Total     float64    `json:"total"`
 	Currency  string     `json:"currency"`
 	TimeStart *time.Time `json:"timeStart"`
 	TimeEnd   *time.Time `json:"timeEnd"`
 }
 // PaymentMethod 是订阅上登记的一种付款方式,按 method 分信用卡/PayPal 两形态。
 type PaymentMethod struct {
 	Method           string     `json:"method"` // CREDIT_CARD / PAYPAL
 	CardType         string     `json:"cardType,omitempty"`
 	LastDigits       string     `json:"lastDigits,omitempty"`
 	NameOnCard       string     `json:"nameOnCard,omitempty"`
 	TimeExpiration   *time.Time `json:"timeExpiration,omitempty"`
 	Email            string     `json:"email,omitempty"`
 	PayerName        string     `json:"payerName,omitempty"`
 	BillingAgreement string     `json:"billingAgreement,omitempty"`
 }
 // ospHomeRegion 解析租户主区域公共名(经测活拿三字码再查区域表);
 // 主区域是租户常量,按 tenancy 进程内缓存,免去每次账单调用先付一次远程测活。
 func (c *RealClient) ospHomeRegion(ctx context.Context, cred Credentials) (string, error) {
 	if v, ok := c.homeRegions.Load(cred.TenancyOCID); ok {
 		return v.(string), nil
 	}
 	info, err := c.ValidateKey(ctx, cred)
 	if err != nil {
 		return "", fmt.Errorf("resolve osp home region: %w", err)
 	}
 	r, ok := RegionByKey(info.HomeRegionKey)
 	if !ok {
 		return "", fmt.Errorf("resolve osp home region: unknown region key %q", info.HomeRegionKey)
 	}
 	if cred.TenancyOCID != "" {
 		c.homeRegions.Store(cred.TenancyOCID, r.Name)
 	}
 	return r.Name, nil
 }
 // ospInvoiceClient 构造发票服务客户端并指向主区域;region 同时用于请求参数。
 func (c *RealClient) ospInvoiceClient(ctx context.Context, cred Credentials) (ospgateway.InvoiceServiceClient, string, error) {
 	region, err := c.ospHomeRegion(ctx, cred)
 	if err != nil {
 		return ospgateway.InvoiceServiceClient{}, "", err
 	}
 	ic, err := ospgateway.NewInvoiceServiceClientWithConfigurationProvider(provider(cred))
 	if err != nil {
 		return ospgateway.InvoiceServiceClient{}, "", fmt.Errorf("new invoice client: %w", err)
 	}
 	applyProxy(&ic.BaseClient, cred)
 	ic.SetRegion(region)
 	return ic, region, nil
 }
 // ListInvoices 实现 Client:分页列出租户发票;year>0 时只取该自然年
 // (按 timeInvoice 窗口过滤),为 0 拉全量。
 func (c *RealClient) ListInvoices(ctx context.Context, cred Credentials, year int) ([]Invoice, error) {
 	ic, region, err := c.ospInvoiceClient(ctx, cred)
 	if err != nil {
 		return nil, err
 	}
 	req := ospgateway.ListInvoicesRequest{
 		OspHomeRegion: &region,
 		CompartmentId: &cred.TenancyOCID,
 		Limit:         common.Int(ospPageLimit),
 	}
 	if year > 0 {
 		req.TimeInvoiceStart = &common.SDKTime{Time: time.Date(year, 1, 1, 0, 0, 0, 0, time.UTC)}
 		req.TimeInvoiceEnd = &common.SDKTime{Time: time.Date(year+1, 1, 1, 0, 0, 0, 0, time.UTC)}
 	}
 	var out []Invoice
 	for {
 		resp, err := ic.ListInvoices(ctx, req)
 		if err != nil {
 			return nil, fmt.Errorf("list invoices: %w", err)
 		}
 		for _, item := range resp.Items {
 			out = append(out, toInvoice(item))
 		}
 		if resp.OpcNextPage == nil {
 			return orEmpty(out), nil
 		}
 		req.Page = resp.OpcNextPage
 	}
 }
 // ospPageLimit 是 OSP 网关列表接口的每页条数;不传时服务端默认页极小,
 // 几百行发票明细要串行翻几十页(实测单请求被拖到 40s+)。
 const ospPageLimit = 100
 // ListInvoiceLines 实现 Client:分页列出一张发票的全部费用行。
 func (c *RealClient) ListInvoiceLines(ctx context.Context, cred Credentials, internalInvoiceID string) ([]InvoiceLine, error) {
 	ic, region, err := c.ospInvoiceClient(ctx, cred)
 	if err != nil {
 		return nil, err
 	}
 	var out []InvoiceLine
 	var page *string
 	for {
 		resp, err := ic.ListInvoiceLines(ctx, ospgateway.ListInvoiceLinesRequest{
 			OspHomeRegion:     &region,
 			CompartmentId:     &cred.TenancyOCID,
 			InternalInvoiceId: &internalInvoiceID,
 			Page:              page,
 			Limit:             common.Int(ospPageLimit),
 		})
 		if err != nil {
 			return nil, fmt.Errorf("list invoice lines: %w", err)
 		}
 		for _, item := range resp.Items {
 			out = append(out, toInvoiceLine(item))
 		}
 		if resp.OpcNextPage == nil {
 			return orEmpty(out), nil
 		}
 		page = resp.OpcNextPage
 	}
 }
 // DownloadInvoicePdf 实现 Client:整读发票 PDF,超出 maxBytes 视为异常。
 func (c *RealClient) DownloadInvoicePdf(ctx context.Context, cred Credentials, internalInvoiceID string, maxBytes int64) ([]byte, error) {
 	ic, region, err := c.ospInvoiceClient(ctx, cred)
 	if err != nil {
 		return nil, err
 	}
 	resp, err := ic.DownloadPdfContent(ctx, ospgateway.DownloadPdfContentRequest{
 		OspHomeRegion:     &region,
 		CompartmentId:     &cred.TenancyOCID,
 		InternalInvoiceId: &internalInvoiceID,
 	})
 	if err != nil {
 		return nil, fmt.Errorf("download invoice pdf: %w", err)
 	}
 	defer resp.Content.Close()
 	data, err := io.ReadAll(io.LimitReader(resp.Content, maxBytes+1))
 	if err != nil {
 		return nil, fmt.Errorf("download invoice pdf: %w", err)
 	}
 	if int64(len(data)) > maxBytes {
 		return nil, fmt.Errorf("download invoice pdf: exceeds %d bytes", maxBytes)
 	}
 	return data, nil
 }
 // PayInvoice 实现 Client:按订阅当前默认付款方式支付发票,email 接收回执。
 func (c *RealClient) PayInvoice(ctx context.Context, cred Credentials, internalInvoiceID, email string) error {
 	ic, region, err := c.ospInvoiceClient(ctx, cred)
 	if err != nil {
 		return err
 	}
 	_, err = ic.PayInvoice(ctx, ospgateway.PayInvoiceRequest{
 		OspHomeRegion:     &region,
 		CompartmentId:     &cred.TenancyOCID,
 		InternalInvoiceId: &internalInvoiceID,
 		PayInvoiceDetails: ospgateway.PayInvoiceDetails{Email: &email},
 	})
 	if err != nil {
 		return fmt.Errorf("pay invoice: %w", err)
 	}
 	return nil
 }
 // ListPaymentMethods 实现 Client:汇总各订阅上登记的全部付款方式。
 func (c *RealClient) ListPaymentMethods(ctx context.Context, cred Credentials) ([]PaymentMethod, error) {
 	region, err := c.ospHomeRegion(ctx, cred)
 	if err != nil {
 		return nil, err
 	}
 	sc, err := ospgateway.NewSubscriptionServiceClientWithConfigurationProvider(provider(cred))
 	if err != nil {
 		return nil, fmt.Errorf("new osp subscription client: %w", err)
 	}
 	applyProxy(&sc.BaseClient, cred)
 	sc.SetRegion(region)
 	var out []PaymentMethod
 	var page *string
 	for {
 		resp, err := sc.ListSubscriptions(ctx, ospgateway.ListSubscriptionsRequest{
 			OspHomeRegion: &region,
 			CompartmentId: &cred.TenancyOCID,
 			Page:          page,
 		})
 		if err != nil {
 			return nil, fmt.Errorf("list payment methods: %w", err)
 		}
 		for _, sub := range resp.Items {
 			out = appendPaymentMethods(out, sub.PaymentOptions)
 		}
 		if resp.OpcNextPage == nil {
 			return orEmpty(out), nil
 		}
 		page = resp.OpcNextPage
 	}
 }
 func toInvoice(v ospgateway.InvoiceSummary) Invoice {
 	inv := Invoice{
 		ID:          deref(v.InvoiceId),
 		InternalID:  deref(v.InternalInvoiceId),
 		Number:      deref(v.InvoiceNumber),
 		Type:        string(v.InvoiceType),
 		Status:      string(v.InvoiceStatus),
 		Amount:      money(v.InvoiceAmount),
 		AmountDue:   money(v.InvoiceAmountDue),
 		TimeInvoice: sdkTime(v.TimeInvoice),
 		TimeDue:     sdkTime(v.TimeInvoiceDue),
 	}
 	if v.IsPaid != nil {
 		inv.IsPaid = *v.IsPaid
 	}
 	if v.IsPayable != nil {
 		inv.IsPayable = *v.IsPayable
 	}
 	if v.IsPaymentFailed != nil {
 		inv.IsPaymentFailed = *v.IsPaymentFailed
 	}
 	if v.Currency != nil {
 		inv.Currency = deref(v.Currency.CurrencyCode)
 	}
 	return inv
 }
 func toInvoiceLine(v ospgateway.InvoiceLineSummary) InvoiceLine {
 	line := InvoiceLine{
 		Product:   deref(v.Product),
 		OrderNo:   deref(v.OrderNo),
 		Quantity:  money(v.Quantity),
 		UnitPrice: money(v.NetUnitPrice),
 		Total:     money(v.TotalPrice),
 		TimeStart: sdkTime(v.TimeStart),
 		TimeEnd:   sdkTime(v.TimeEnd),
 	}
 	if v.Currency != nil {
 		line.Currency = deref(v.Currency.CurrencyCode)
 	}
 	return line
 }
 func appendPaymentMethods(out []PaymentMethod, opts []ospgateway.PaymentOption) []PaymentMethod {
 	for _, opt := range opts {
 		switch v := opt.(type) {
 		case ospgateway.CreditCardPaymentOption:
 			out = append(out, creditCardMethod(v))
 		case *ospgateway.CreditCardPaymentOption:
 			out = append(out, creditCardMethod(*v))
 		case ospgateway.PaypalPaymentOption:
 			out = append(out, paypalMethod(v))
 		case *ospgateway.PaypalPaymentOption:
 			out = append(out, paypalMethod(*v))
 		}
 	}
 	return out
 }
 func creditCardMethod(v ospgateway.CreditCardPaymentOption) PaymentMethod {
 	return PaymentMethod{
 		Method:         "CREDIT_CARD",
 		CardType:       string(v.CreditCardType),
 		LastDigits:     deref(v.LastDigits),
 		NameOnCard:     deref(v.NameOnCard),
 		TimeExpiration: sdkTime(v.TimeExpiration),
 	}
 }
 func paypalMethod(v ospgateway.PaypalPaymentOption) PaymentMethod {
 	return PaymentMethod{
 		Method:           "PAYPAL",
 		Email:            deref(v.EmailAddress),
 		PayerName:        strings.TrimSpace(deref(v.FirstName) + " " + deref(v.LastName)),
 		BillingAgreement: deref(v.ExtBillingAgreementId),
 	}
 }
 // money 把 SDK 的 float32 金额转为 float64 输出;四舍五入到 4 位小数,
 // 抹掉精度转换产生的二进制噪音(如 603.53 变 603.5300293)。
 func money(p *float32) float64 {
 	if p == nil {
 		return 0
 	}
 	return math.Round(float64(*p)*10000) / 10000
 }
@@ -32,8 +32,10 @@ func NewCachedClient(inner Client) *CachedClient {
 }
 // ckey 组缓存键;租户 OCID 在最前,写失效按前缀一锅端。
 // compartment 必须参与键值:列表查询按 EffectiveCompartment 过滤,
 // 同租户切换区间时若共用键会串到上一个区间的缓存结果。
 func ckey(cred Credentials, parts ...string) string {
-	return cred.TenancyOCID + "|" + strings.Join(parts, "|")
+	return cred.TenancyOCID + "|" + cred.CompartmentID + "|" + strings.Join(parts, "|")
 }
 // bust 写操作成功后失效该租户全部读缓存。
@@ -49,6 +49,13 @@ func TestCachedClientHitAndIsolation(t *testing.T) {
 	if inner.instCalls != 3 {
 		t.Errorf("跨租户/区域回源 %d 次, want 3", inner.instCalls)
 	}
 	// 同租户不同 compartment 各自回源,不得共用缓存
 	inCompartment := testCred("t1")
 	inCompartment.CompartmentID = "ocid1.compartment.a"
 	_, _ = c.ListInstances(ctx, inCompartment, "r1")
 	if inner.instCalls != 4 {
 		t.Errorf("跨 compartment 回源 %d 次, want 4", inner.instCalls)
 	}
 }
 func TestCachedClientWriteBusts(t *testing.T) {
@@ -50,6 +50,13 @@ type Client interface {
 	ListSubscriptions(ctx context.Context, cred Credentials) ([]SubscriptionInfo, error)
 	// GetSubscription 查询单个订阅的完整信息。
 	GetSubscription(ctx context.Context, cred Credentials, subscriptionID string) (SubscriptionDetail, error)
 	// 账单(OSP Gateway,仅主区域):发票列表/明细/PDF/付款与订阅付款方式。
 	// ListInvoices 的 year>0 时按自然年过滤(timeInvoice 窗口),0 为全量。
 	ListInvoices(ctx context.Context, cred Credentials, year int) ([]Invoice, error)
 	ListInvoiceLines(ctx context.Context, cred Credentials, internalInvoiceID string) ([]InvoiceLine, error)
 	DownloadInvoicePdf(ctx context.Context, cred Credentials, internalInvoiceID string, maxBytes int64) ([]byte, error)
 	PayInvoice(ctx context.Context, cred Credentials, internalInvoiceID, email string) error
 	ListPaymentMethods(ctx context.Context, cred Credentials) ([]PaymentMethod, error)
 	// ListShapes 列出租户在目标区域可用的实例规格（带缓存）。
 	ListShapes(ctx context.Context, cred Credentials, region, availabilityDomain string) ([]ComputeShape, error)
 	// ListImages 列出可用的实例镜像。
@@ -91,6 +98,36 @@ type Client interface {
 	DeleteBootVolume(ctx context.Context, cred Credentials, region, bootVolumeID string) error
 	// 实例 IP：更换主 VNIC 临时公网 IP、添加与取消分配 IPv6 地址。
 	ChangeInstancePublicIP(ctx context.Context, cred Credentials, region, instanceID string) (string, error)
 	ChangeVnicPublicIP(ctx context.Context, cred Credentials, region, vnicID string) (string, error)
 	// 对象存储:namespace、桶 CRUD、对象列表/删除/重命名/取回/元数据、预签名请求(PAR)。
 	GetObjectStorageNamespace(ctx context.Context, cred Credentials, region string) (string, error)
 	ListBuckets(ctx context.Context, cred Credentials, region, compartmentID string) ([]Bucket, error)
 	CreateBucket(ctx context.Context, cred Credentials, region string, in CreateBucketInput) (Bucket, error)
 	UpdateBucket(ctx context.Context, cred Credentials, region, name string, in UpdateBucketInput) (Bucket, error)
 	DeleteBucket(ctx context.Context, cred Credentials, region, name string) error
 	// AbortAllMultipartUploads 中止桶内全部未完成分片上传(清空删桶前置步骤,404 幂等)
 	AbortAllMultipartUploads(ctx context.Context, cred Credentials, region, bucket string) error
 	ListObjects(ctx context.Context, cred Credentials, region, bucket, prefix, startWith string, limit int) (ListObjectsResult, error)
 	ListObjectVersions(ctx context.Context, cred Credentials, region, bucket, page string) ([]ObjectVersion, string, error)
 	DeleteObjectVersion(ctx context.Context, cred Credentials, region, bucket, object, versionID string) error
 	DeleteObject(ctx context.Context, cred Credentials, region, bucket, object string) error
 	RenameObject(ctx context.Context, cred Credentials, region, bucket, src, dst string) error
 	RestoreObject(ctx context.Context, cred Credentials, region, bucket, object string, hours int) error
 	HeadObject(ctx context.Context, cred Credentials, region, bucket, object string) (ObjectDetail, error)
 	// 小文件中转:预览/编辑经面板直读直写,不签发 PAR;PutObject ifMatch 做并发保护。
 	GetObject(ctx context.Context, cred Credentials, region, bucket, object string, maxBytes int64) (ObjectContent, error)
 	PutObject(ctx context.Context, cred Credentials, region, bucket, object string, data []byte, contentType, ifMatch string) (string, error)
 	CreatePAR(ctx context.Context, cred Credentials, region, bucket string, in CreatePARInput) (PAR, error)
 	ListPARs(ctx context.Context, cred Credentials, region, bucket string) ([]PAR, error)
 	// ListPARsPage 单页列出 PAR:page 为上页游标(空取首页),返回下一页游标(空为末页)。
 	ListPARsPage(ctx context.Context, cred Credentials, region, bucket, page string, limit int) ([]PAR, string, error)
 	DeletePAR(ctx context.Context, cred Credentials, region, bucket, parID string) error
 	// 保留公网 IP:列出 / 创建 / 绑定(instanceID 空为解绑) / 删除。
 	ListReservedIPs(ctx context.Context, cred Credentials, region, compartmentID string) ([]ReservedIP, error)
 	CreateReservedIP(ctx context.Context, cred Credentials, region, compartmentID, displayName string) (ReservedIP, error)
 	AssignReservedIP(ctx context.Context, cred Credentials, region, publicIPID, instanceID string) error
 	AssignReservedIPToVnic(ctx context.Context, cred Credentials, region, publicIPID, vnicID string) error
 	DeleteReservedIP(ctx context.Context, cred Credentials, region, publicIPID string) error
 	AddInstanceIpv6(ctx context.Context, cred Credentials, region, instanceID, address string) (string, error)
 	DeleteInstanceIpv6(ctx context.Context, cred Credentials, region, instanceID, address string) error
 	// VNIC 管理:列出实例网卡、附加次要网卡、分离(主网卡由 OCI 拒绝)、按网卡加 IPv6。
@@ -152,6 +189,10 @@ type Client interface {
 	ResetTenantUserPassword(ctx context.Context, cred Credentials, homeRegion, domainID, userID string) (string, error)
 	DeleteTenantUserMfaDevices(ctx context.Context, cred Credentials, homeRegion, domainID, userID string) (int, error)
 	DeleteTenantUserApiKeys(ctx context.Context, cred Credentials, homeRegion, userID string, includeCurrent bool) (int, error)
 	// 用户 API 签名 key 管理:列出(标注当前使用)、上传公钥(返回指纹)、按指纹删单把。
 	ListTenantUserApiKeys(ctx context.Context, cred Credentials, homeRegion, userID string) ([]TenantUserApiKey, error)
 	UploadTenantUserApiKey(ctx context.Context, cred Credentials, homeRegion, userID, publicKeyPEM string) (string, error)
 	DeleteTenantUserApiKey(ctx context.Context, cred Credentials, homeRegion, userID, fingerprint string) error
 	// 域设置：通知收件人、密码策略、身份设置。
 	GetNotificationRecipients(ctx context.Context, cred Credentials, region, domainID string) (NotificationRecipients, error)
 	UpdateNotificationRecipients(ctx context.Context, cred Credentials, region, domainID string, emails []string) (NotificationRecipients, error)
@@ -165,6 +206,10 @@ type Client interface {
 	SetIdentityProviderEnabled(ctx context.Context, cred Credentials, region, domainID, idpID string, enabled bool) (IdentityProviderInfo, error)
 	DeleteIdentityProvider(ctx context.Context, cred Credentials, region, domainID, idpID string) error
 	DownloadDomainSamlMetadata(ctx context.Context, cred Credentials, region, domainID string) ([]byte, error)
 	// UploadDomainImage 上传公开图片到身份域存储(IdP 图标用),返回公网 URL 与存储内文件名。
 	UploadDomainImage(ctx context.Context, cred Credentials, region, domainID, fileName string, data []byte) (string, string, error)
 	// DeleteDomainImage 按存储内文件名删除身份域公开图片。
 	DeleteDomainImage(ctx context.Context, cred Credentials, region, domainID, fileName string) error
 	ListConsoleSignOnRules(ctx context.Context, cred Credentials, region, domainID string) ([]SignOnRuleInfo, error)
 	CreateMfaExemptionRule(ctx context.Context, cred Credentials, region, domainID, idpID, ruleName string) (SignOnRuleInfo, error)
 	DeleteMfaExemptionRule(ctx context.Context, cred Credentials, region, domainID, ruleID string) error
@@ -184,8 +229,10 @@ type Client interface {
 // RealClient 基于官方 SDK 实现 Client。
 type RealClient struct {
-	limitDefs sync.Map // tenancy|region|service → limitDefEntry，配额定义预筛缓存
+	limitDefs   sync.Map // tenancy|region|service → limitDefEntry，配额定义预筛缓存
-	shapes    sync.Map // tenancy|region|ad → shapeCacheEntry，shape 清单缓存
+	shapes      sync.Map // tenancy|region|ad → shapeCacheEntry，shape 清单缓存
 	namespaces  sync.Map // tenancy → 对象存储 namespace,租户常量不过期
 	homeRegions sync.Map // tenancy → 主区域公共名,租户常量不过期(OSP 账单用)
 }
 // NewClient 返回生产使用的真实客户端。
@@ -14,15 +14,16 @@ import (
 type CostQuery struct {
 	StartTime   time.Time
 	EndTime     time.Time
-	Granularity string // DAILY / MONTHLY
+	Granularity string // HOURLY / DAILY / MONTHLY
 	QueryType   string // COST / USAGE
-	GroupBy     string // service / skuName / region 等维度
+	GroupBy     string // 单维度(service / skuName / region 等),或逗号分隔的复合维度(如 "service,skuName",主+子)
 }
 // CostItem 是一个时间桶内某分组维度的成本或用量。
 type CostItem struct {
 	TimeStart        *time.Time `json:"timeStart"`
 	GroupValue       string     `json:"groupValue"`
 	SubValue         string     `json:"subValue,omitempty"` // 复合分组的第二维取值(如 service 下的 skuName)
 	ComputedAmount   float32    `json:"computedAmount"`
 	ComputedQuantity float32    `json:"computedQuantity"`
 	Currency         string     `json:"currency"`
@@ -75,11 +76,37 @@ func buildUsageDetails(tenancyOCID string, q CostQuery) (usageapi.RequestSummari
 		TimeUsageEnded:   &common.SDKTime{Time: q.EndTime},
 		Granularity:      granularity,
 		QueryType:        queryType,
-		GroupBy:          []string{q.GroupBy},
+		GroupBy:          splitGroupBy(q.GroupBy),
 	}, nil
 }
-// toCostItem 把响应条目转为本地 DTO，分组值按 groupBy 维度取对应字段。
+// splitGroupBy 把 "service,skuName" 复合维度拆成 Usage API 的 groupBy 列表。
 func splitGroupBy(groupBy string) []string {
 	parts := strings.Split(groupBy, ",")
 	out := make([]string, 0, len(parts))
 	for _, p := range parts {
 		if p = strings.TrimSpace(p); p != "" {
 			out = append(out, p)
 		}
 	}
 	return out
 }
 // dimValue 按维度名取响应条目上的分组值。
 func dimValue(item usageapi.UsageSummary, dim string) string {
 	switch strings.ToLower(strings.TrimSpace(dim)) {
 	case "skuname":
 		return deref(item.SkuName)
 	case "region":
 		return deref(item.Region)
 	case "compartmentname":
 		return deref(item.CompartmentName)
 	default:
 		return deref(item.Service)
 	}
 }
 // toCostItem 把响应条目转为本地 DTO;首维进 GroupValue,复合分组的次维进 SubValue。
 func toCostItem(item usageapi.UsageSummary, groupBy string) CostItem {
 	out := CostItem{
 		Currency: deref(item.Currency),
@@ -94,15 +121,13 @@ func toCostItem(item usageapi.UsageSummary, groupBy string) CostItem {
 	if item.ComputedQuantity != nil {
 		out.ComputedQuantity = *item.ComputedQuantity
 	}
-	switch strings.ToLower(groupBy) {
+	dims := splitGroupBy(groupBy)
-	case "skuname":
+	if len(dims) == 0 {
-		out.GroupValue = deref(item.SkuName)
+		dims = []string{"service"}
-	case "region":
+	}
-		out.GroupValue = deref(item.Region)
+	out.GroupValue = dimValue(item, dims[0])
-	case "compartmentname":
+	if len(dims) > 1 {
-		out.GroupValue = deref(item.CompartmentName)
+		out.SubValue = dimValue(item, dims[1])
 	default:
 		out.GroupValue = deref(item.Service)
 	}
 	return out
 }
@@ -0,0 +1,157 @@
 package oci
 import (
 	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
 	"io"
 	"mime/multipart"
 	"net/http"
 	"net/url"
 	"strings"
 )
 // domainImagesPath 是身份域公开图片上传端点(品牌 / IdP 图标),SDK 未覆盖该操作。
 const domainImagesPath = "/storage/v1/Images"
 // UploadDomainImage 实现 Client:上传公开图片到身份域存储,返回公网 fileUrl
 // 与域存储内文件名(后者留作后续精确清理)。借 domainsClient 的 BaseClient
 // 发裸 multipart 请求,OCI 签名与代理配置直接复用。
 func (c *RealClient) UploadDomainImage(ctx context.Context, cred Credentials, region, domainID, fileName string, data []byte) (string, string, error) {
 	dc, err := c.domainsClient(ctx, cred, region, domainID)
 	if err != nil {
 		return "", "", err
 	}
 	req, err := newDomainImageUploadRequest(ctx, dc.Endpoint(), fileName, data)
 	if err != nil {
 		return "", "", err
 	}
 	resp, callErr := dc.BaseClient.Call(ctx, req)
 	return parseImageUploadResponse(resp, callErr)
 }
 // DeleteDomainImage 实现 Client:按响应 fileName 精确删除公开图片,404 视为幂等成功。
 func (c *RealClient) DeleteDomainImage(ctx context.Context, cred Credentials, region, domainID, fileName string) error {
 	dc, err := c.domainsClient(ctx, cred, region, domainID)
 	if err != nil {
 		return err
 	}
 	req, err := newDomainImageDeleteRequest(ctx, dc.Endpoint(), fileName)
 	if err != nil {
 		return err
 	}
 	resp, callErr := dc.BaseClient.Call(ctx, req)
 	return finishDomainImageDelete(resp, callErr)
 }
 func newDomainImageUploadRequest(ctx context.Context, endpoint, fileName string, data []byte) (*http.Request, error) {
 	body, contentType, err := imageMultipart(fileName, data)
 	if err != nil {
 		return nil, err
 	}
 	req, err := http.NewRequestWithContext(ctx, http.MethodPost, strings.TrimRight(endpoint, "/")+domainImagesPath, bytes.NewReader(body))
 	if err != nil {
 		return nil, fmt.Errorf("build image upload request: %w", err)
 	}
 	req.Header.Set("Content-Type", contentType)
 	return req, nil
 }
 func newDomainImageDeleteRequest(ctx context.Context, endpoint, fileName string) (*http.Request, error) {
 	u, err := url.Parse(strings.TrimRight(endpoint, "/") + domainImagesPath)
 	if err != nil {
 		return nil, fmt.Errorf("build image delete URL: %w", err)
 	}
 	query := u.Query()
 	query.Set("fileName", fileName)
 	u.RawQuery = query.Encode()
 	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, u.String(), nil)
 	if err != nil {
 		return nil, fmt.Errorf("build image delete request: %w", err)
 	}
 	return req, nil
 }
 // imageMultipart 组装上传请求体:file(二进制)与 fileName 两个 part(官方文档要求)。
 func imageMultipart(fileName string, data []byte) ([]byte, string, error) {
 	var buf bytes.Buffer
 	w := multipart.NewWriter(&buf)
 	fw, err := w.CreateFormFile("file", fileName)
 	if err != nil {
 		return nil, "", fmt.Errorf("build image multipart: %w", err)
 	}
 	if _, err := fw.Write(data); err != nil {
 		return nil, "", fmt.Errorf("build image multipart: %w", err)
 	}
 	if err := w.WriteField("fileName", fileName); err != nil {
 		return nil, "", fmt.Errorf("build image multipart: %w", err)
 	}
 	if err := w.Close(); err != nil {
 		return nil, "", fmt.Errorf("build image multipart: %w", err)
 	}
 	return buf.Bytes(), w.FormDataContentType(), nil
 }
 // parseImageUploadResponse 解析上传响应,并确保任何返回路径都关闭响应体。
 func parseImageUploadResponse(resp *http.Response, callErr error) (string, string, error) {
 	if resp != nil && resp.Body != nil {
 		defer drainAndClose(resp.Body)
 	}
 	if callErr != nil {
 		return "", "", fmt.Errorf("upload domain image: %w", callErr)
 	}
 	if resp == nil || resp.Body == nil {
 		return "", "", fmt.Errorf("upload domain image: empty response")
 	}
 	if resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusOK {
 		return "", "", fmt.Errorf("upload domain image: HTTP %d", resp.StatusCode)
 	}
 	b, err := io.ReadAll(io.LimitReader(resp.Body, (1<<20)+1))
 	if err != nil {
 		return "", "", fmt.Errorf("read image upload response: %w", err)
 	}
 	if len(b) > 1<<20 {
 		return "", "", fmt.Errorf("upload domain image: response exceeds 1MB")
 	}
 	return decodeImageUploadResponse(b)
 }
 func decodeImageUploadResponse(data []byte) (string, string, error) {
 	var out struct {
 		FileURL  string `json:"fileUrl"`
 		FileName string `json:"fileName"`
 	}
 	if err := json.Unmarshal(data, &out); err != nil {
 		return "", "", fmt.Errorf("parse image upload response: %w", err)
 	}
 	if out.FileURL == "" || out.FileName == "" {
 		return "", "", fmt.Errorf("upload domain image: response missing fileUrl or fileName")
 	}
 	return out.FileURL, out.FileName, nil
 }
 func finishDomainImageDelete(resp *http.Response, callErr error) error {
 	if resp != nil && resp.Body != nil {
 		defer drainAndClose(resp.Body)
 	}
 	if resp != nil && resp.StatusCode == http.StatusNotFound {
 		return nil
 	}
 	if callErr != nil {
 		return fmt.Errorf("delete domain image: %w", callErr)
 	}
 	if resp == nil {
 		return fmt.Errorf("delete domain image: empty response")
 	}
 	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusNoContent {
 		return fmt.Errorf("delete domain image: HTTP %d", resp.StatusCode)
 	}
 	return nil
 }
 // drainAndClose 读完小响应以便 HTTP 连接复用;超大异常响应限制为 64KiB。
 func drainAndClose(body io.ReadCloser) {
 	_, _ = io.Copy(io.Discard, io.LimitReader(body, 64<<10))
 	_ = body.Close()
 }
@@ -0,0 +1,143 @@
 package oci
 import (
 	"context"
 	"errors"
 	"io"
 	"mime"
 	"mime/multipart"
 	"net/http"
 	"strings"
 	"testing"
 )
 type trackingReadCloser struct {
 	io.Reader
 	closed bool
 }
 type testMultipartFile struct {
 	name string
 	data []byte
 }
 func (r *trackingReadCloser) Close() error {
 	r.closed = true
 	return nil
 }
 func testImageResponse(status int, body string) (*http.Response, *trackingReadCloser) {
 	reader := &trackingReadCloser{Reader: strings.NewReader(body)}
 	return &http.Response{StatusCode: status, Body: reader}, reader
 }
 func readMultipartFields(t *testing.T, body []byte, contentType string) (map[string]string, map[string]testMultipartFile) {
 	t.Helper()
 	_, params, err := mime.ParseMediaType(contentType)
 	if err != nil {
 		t.Fatalf("parse content type: %v", err)
 	}
 	reader := multipart.NewReader(strings.NewReader(string(body)), params["boundary"])
 	fields, files := map[string]string{}, map[string]testMultipartFile{}
 	for {
 		part, err := reader.NextPart()
 		if errors.Is(err, io.EOF) {
 			break
 		}
 		if err != nil {
 			t.Fatalf("next part: %v", err)
 		}
 		data, _ := io.ReadAll(part)
 		if part.FileName() == "" {
 			fields[part.FormName()] = string(data)
 		} else {
 			files[part.FormName()] = testMultipartFile{name: part.FileName(), data: data}
 		}
 	}
 	return fields, files
 }
 func TestImageMultipartIncludesFileAndName(t *testing.T) {
 	fileName := "idp-icon-00112233445566778899aabbccddeeff.png"
 	body, contentType, err := imageMultipart(fileName, []byte("image-data"))
 	if err != nil {
 		t.Fatalf("imageMultipart: %v", err)
 	}
 	fields, files := readMultipartFields(t, body, contentType)
 	if got := fields["fileName"]; got != fileName {
 		t.Errorf("fileName = %q, want %q", got, fileName)
 	}
 	file := files["file"]
 	if file.name != fileName || string(file.data) != "image-data" {
 		t.Errorf("file part = %q, %q; want %q, image-data", file.name, file.data, fileName)
 	}
 }
 func TestParseImageUploadResponse(t *testing.T) {
 	cases := []struct {
 		name, body, wantURL, wantName string
 		status                        int
 		callErr                       error
 		wantErr                       bool
 	}{
 		{"complete", `{"fileUrl":"https://img/x","fileName":"images/x.png"}`, "https://img/x", "images/x.png", 201, nil, false},
 		{"missing name", `{"fileUrl":"https://img/x"}`, "", "", 201, nil, true},
 		{"missing url", `{"fileName":"images/x.png"}`, "", "", 200, nil, true},
 		{"bad json", `{`, "", "", 200, nil, true},
 		{"http error hides body", `secret-body`, "", "", 400, nil, true},
 		{"call error", `{}`, "", "", 500, errors.New("upstream"), true},
 	}
 	for _, tc := range cases {
 		resp, body := testImageResponse(tc.status, tc.body)
 		gotURL, gotName, err := parseImageUploadResponse(resp, tc.callErr)
 		if gotURL != tc.wantURL || gotName != tc.wantName || (err != nil) != tc.wantErr {
 			t.Errorf("result = %q, %q, %v; want %q, %q, err=%v", gotURL, gotName, err, tc.wantURL, tc.wantName, tc.wantErr)
 		}
 		if !body.closed {
 			t.Error("response body was not closed")
 		}
 		if err != nil && strings.Contains(err.Error(), "secret-body") {
 			t.Errorf("error leaked response body: %v", err)
 		}
 	}
 }
 func TestDomainImageDeleteRequestEncodesFileName(t *testing.T) {
 	fileName := "images/folder/a b+%.png"
 	req, err := newDomainImageDeleteRequest(context.Background(), "https://id.example/", fileName)
 	if err != nil {
 		t.Fatalf("newDomainImageDeleteRequest: %v", err)
 	}
 	if req.Method != http.MethodDelete || req.URL.Path != domainImagesPath {
 		t.Errorf("request = %s %s, want DELETE %s", req.Method, req.URL.Path, domainImagesPath)
 	}
 	if got := req.URL.Query().Get("fileName"); got != fileName {
 		t.Errorf("decoded fileName = %q, want %q", got, fileName)
 	}
 	if strings.Contains(req.URL.RawQuery, " ") || strings.Contains(req.URL.RawQuery, "/") {
 		t.Errorf("raw query is not encoded: %q", req.URL.RawQuery)
 	}
 }
 func TestFinishDomainImageDelete(t *testing.T) {
 	cases := []struct {
 		name    string
 		status  int
 		callErr error
 		wantErr bool
 	}{
 		{"deleted", http.StatusNoContent, nil, false},
 		{"already gone", http.StatusNotFound, errors.New("not found"), false},
 		{"upstream failure", http.StatusInternalServerError, errors.New("upstream"), true},
 	}
 	for _, tc := range cases {
 		resp, body := testImageResponse(tc.status, "response")
 		err := finishDomainImageDelete(resp, tc.callErr)
 		if (err != nil) != tc.wantErr {
 			t.Errorf("err = %v, wantErr %v", err, tc.wantErr)
 		}
 		if !body.closed {
 			t.Error("response body was not closed")
 		}
 	}
 }
@@ -3,6 +3,7 @@ package oci
 import (
 	"context"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -22,6 +23,11 @@ const samlMetadataPath = "/fed/v1/metadata"
 // idpSchema 是 IdentityProvider 资源的 SCIM schema。
 const idpSchema = "urn:ietf:params:scim:schemas:oracle:idcs:IdentityProvider"
 const idpCreateRollbackWait = 15 * time.Second
 // IdpSetupWarningCode 是 IdP 已创建但 JIT 后置配置未完成的稳定机器码。
 const IdpSetupWarningCode = "JIT_SETUP_INCOMPLETE"
 // IdentityProviderInfo 是一个外部身份提供者的关键字段。
 type IdentityProviderInfo struct {
 	ID                string     `json:"id"`
@@ -33,6 +39,27 @@ type IdentityProviderInfo struct {
 	TimeCreated       *time.Time `json:"timeCreated,omitempty"`
 }
 // PartialIdentityProviderCreateError 表示 IdP 已创建且回滚无法确认。
 // Error 只返回固定文案；Cause 仅保留在内部错误链，不得直接写入 HTTP 响应。
 type PartialIdentityProviderCreateError struct {
 	IdentityProvider IdentityProviderInfo
 	cause            error
 }
 func (e *PartialIdentityProviderCreateError) Error() string {
 	return "identity provider was created but JIT setup is incomplete"
 }
 func (e *PartialIdentityProviderCreateError) Unwrap() error { return e.cause }
 type federationDomainsClient interface {
 	ListGroups(context.Context, identitydomains.ListGroupsRequest) (identitydomains.ListGroupsResponse, error)
 	CreateIdentityProvider(context.Context, identitydomains.CreateIdentityProviderRequest) (identitydomains.CreateIdentityProviderResponse, error)
 	GetIdentityProvider(context.Context, identitydomains.GetIdentityProviderRequest) (identitydomains.GetIdentityProviderResponse, error)
 	PatchMappedAttribute(context.Context, identitydomains.PatchMappedAttributeRequest) (identitydomains.PatchMappedAttributeResponse, error)
 	DeleteIdentityProvider(context.Context, identitydomains.DeleteIdentityProviderRequest) (identitydomains.DeleteIdentityProviderResponse, error)
 }
 // CreateIdpInput 是创建 SAML IdP 的输入；零值即控制台默认行为：
 // 名称 ID 格式「无」、SAML 断言名称 ID 映射到用户名、JIT 开启建用户不更新、
 // 静态分配 Administrators 组（service 层负责把缺省字段填成这些默认值）。
@@ -75,13 +102,19 @@ func (c *RealClient) ListIdentityProviders(ctx context.Context, cred Credentials
 	return idps, nil
 }
-// CreateSamlIdentityProvider 实现 Client：按输入创建禁用态 SAML IdP 并配置 JIT。
+// CreateSamlIdentityProvider 实现 Client：按输入创建禁用态 SAML IdP 并配置 JIT；
 // JIT 失败时尝试回滚，回滚无法确认则返回 PartialIdentityProviderCreateError。
 func (c *RealClient) CreateSamlIdentityProvider(ctx context.Context, cred Credentials, region, domainID string, in CreateIdpInput) (IdentityProviderInfo, error) {
 	dc, err := c.domainsClient(ctx, cred, region, domainID)
 	if err != nil {
 		return IdentityProviderInfo{}, err
 	}
 	return createSamlIdentityProvider(ctx, dc, in)
 }
 func createSamlIdentityProvider(ctx context.Context, dc federationDomainsClient, in CreateIdpInput) (IdentityProviderInfo, error) {
 	var adminGroup *identitydomains.IdentityProviderJitUserProvAssignedGroups
 	var err error
 	if in.JitEnabled && in.JitAssignAdminGroup {
 		if adminGroup, err = adminGroupRef(ctx, dc); err != nil {
 			return IdentityProviderInfo{}, err
@@ -93,12 +126,31 @@ func (c *RealClient) CreateSamlIdentityProvider(ctx context.Context, cred Creden
 	if err != nil {
 		return IdentityProviderInfo{}, fmt.Errorf("create identity provider %s: %w", in.Name, err)
 	}
-	if in.JitEnabled {
+	info := toIdpInfo(resp.IdentityProvider)
-		if err := ensureJitAttributeMappings(ctx, dc, resp.IdentityProvider, jitMappings(in)); err != nil {
+	if !in.JitEnabled {
-			return toIdpInfo(resp.IdentityProvider), err
+		return info, nil
 		}
 	}
-	return toIdpInfo(resp.IdentityProvider), nil
+	if err := ensureJitAttributeMappings(ctx, dc, resp.IdentityProvider, jitMappings(in)); err != nil {
 		return rollbackIncompleteIdp(ctx, dc, info, err)
 	}
 	return info, nil
 }
 func rollbackIncompleteIdp(ctx context.Context, dc federationDomainsClient, info IdentityProviderInfo, setupErr error) (IdentityProviderInfo, error) {
 	if info.ID == "" {
 		cause := errors.Join(setupErr, errors.New("created IdP response has no ID; rollback unavailable"))
 		return info, &PartialIdentityProviderCreateError{IdentityProvider: info, cause: cause}
 	}
 	rollbackCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), idpCreateRollbackWait)
 	defer cancel()
 	_, rollbackErr := dc.DeleteIdentityProvider(rollbackCtx, identitydomains.DeleteIdentityProviderRequest{
 		IdentityProviderId: &info.ID,
 	})
 	if rollbackErr == nil {
 		return IdentityProviderInfo{}, fmt.Errorf("configure JIT mappings; created IdP rolled back: %w", setupErr)
 	}
 	cause := errors.Join(setupErr, fmt.Errorf("delete created IdP during rollback: %w", rollbackErr))
 	return info, &PartialIdentityProviderCreateError{IdentityProvider: info, cause: cause}
 }
 // buildSamlIdp 按输入组装 SAML IdP（创建为禁用态，启用走 activate 接口）。
@@ -141,7 +193,7 @@ func buildSamlIdp(in CreateIdpInput, adminGroup *identitydomains.IdentityProvide
 // adminGroupRef 查询域内管理员组作为 JIT 静态分配与用户授权目标;
 // 按 adminGroupNames 优先序取第一个存在的组,都不存在返回 nil。
-func adminGroupRef(ctx context.Context, dc identitydomains.IdentityDomainsClient) (*identitydomains.IdentityProviderJitUserProvAssignedGroups, error) {
+func adminGroupRef(ctx context.Context, dc federationDomainsClient) (*identitydomains.IdentityProviderJitUserProvAssignedGroups, error) {
 	filter := fmt.Sprintf("displayName eq %q or displayName eq %q", adminGroupNames[0], adminGroupNames[1])
 	count := len(adminGroupNames)
 	resp, err := dc.ListGroups(ctx, identitydomains.ListGroupsRequest{
@@ -180,7 +232,7 @@ func jitMappings(in CreateIdpInput) []interface{} {
 }
 // ensureJitAttributeMappings 把 IdP 自动生成的 JIT 属性映射替换为给定映射。
-func ensureJitAttributeMappings(ctx context.Context, dc identitydomains.IdentityDomainsClient, idp identitydomains.IdentityProvider, mappings []interface{}) error {
+func ensureJitAttributeMappings(ctx context.Context, dc federationDomainsClient, idp identitydomains.IdentityProvider, mappings []interface{}) error {
 	ref := idp.JitUserProvAttributes
 	if ref == nil || ref.Value == nil {
 		got, err := dc.GetIdentityProvider(ctx, identitydomains.GetIdentityProviderRequest{IdentityProviderId: idp.Id})
@@ -302,12 +354,15 @@ func updateLoginPageIdps(ctx context.Context, dc identitydomains.IdentityDomains
 }
 // rebuildSamlIdpsReturn 重建规则 return 数组，增删 SamlIDPs 中的目标 IdP。
 // 从未分配过 SAML IdP 的域,规则 return 里没有 SamlIDPs 项,添加时须补建,
 // 否则静默跳过——IdP 启用了却始终不进 Default Identity Provider Policy。
 func rebuildSamlIdpsReturn(items []identitydomains.RuleReturn, idpID string, show bool) ([]interface{}, bool, error) {
-	returns := make([]interface{}, 0, len(items))
+	returns := make([]interface{}, 0, len(items)+1)
-	changed := false
+	changed, seen := false, false
 	for _, item := range items {
 		name, value := deref(item.Name), deref(item.Value)
 		if name == "SamlIDPs" {
 			seen = true
 			next, ok, err := toggleJSONList(value, idpID, show)
 			if err != nil {
 				return nil, false, fmt.Errorf("parse SamlIDPs %q: %w", value, err)
@@ -316,6 +371,10 @@ func rebuildSamlIdpsReturn(items []identitydomains.RuleReturn, idpID string, sho
 		}
 		returns = append(returns, map[string]string{"name": name, "value": value})
 	}
 	if !seen && show {
 		returns = append(returns, map[string]string{"name": "SamlIDPs", "value": jsonList(idpID)})
 		changed = true
 	}
 	return returns, changed, nil
 }
@@ -356,7 +415,7 @@ func (c *RealClient) DownloadDomainSamlMetadata(ctx context.Context, cred Creden
 	if err != nil {
 		return nil, err
 	}
-	body, status, err := fetchSamlMetadata(ctx, url)
+	body, status, err := fetchSamlMetadata(ctx, cred, url)
 	if err != nil {
 		return nil, err
 	}
@@ -366,7 +425,7 @@ func (c *RealClient) DownloadDomainSamlMetadata(ctx context.Context, cred Creden
 	if err := c.enableSigningCertPublicAccess(ctx, cred, region, domainID); err != nil {
 		return nil, err
 	}
-	body, status, err = fetchSamlMetadata(ctx, url)
+	body, status, err = fetchSamlMetadata(ctx, cred, url)
 	if err != nil {
 		return nil, err
 	}
@@ -376,24 +435,53 @@ func (c *RealClient) DownloadDomainSamlMetadata(ctx context.Context, cred Creden
 	return body, nil
 }
-// fetchSamlMetadata 匿名请求元数据端点；该端点只支持公开访问，不接受 OCI 签名。
+// samlMetadataTimeout / samlMetadataMaxBytes 约束匿名元数据请求:限时限量,
-func fetchSamlMetadata(ctx context.Context, url string) ([]byte, int, error) {
+// 防异常缓慢或超大响应长期占住请求与内存。
 const (
 	samlMetadataTimeout  = 30 * time.Second
 	samlMetadataMaxBytes = 4 << 20
 )
 // fetchSamlMetadata 匿名请求元数据端点;该端点只支持公开访问,不接受 OCI 签名,
 // 但仍须走租户代理链路,防止本应经代理的流量直连泄露真实出口。
 func fetchSamlMetadata(ctx context.Context, cred Credentials, url string) ([]byte, int, error) {
 	client, err := metadataHTTPClient(cred)
 	if err != nil {
 		return nil, 0, err
 	}
 	ctx, cancel := context.WithTimeout(ctx, samlMetadataTimeout)
 	defer cancel()
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url+samlMetadataPath, nil)
 	if err != nil {
 		return nil, 0, fmt.Errorf("build metadata request: %w", err)
 	}
-	resp, err := http.DefaultClient.Do(req)
+	resp, err := client.Do(req)
 	if err != nil {
 		return nil, 0, fmt.Errorf("download saml metadata: %w", err)
 	}
 	defer resp.Body.Close()
-	body, err := io.ReadAll(resp.Body)
+	body, err := io.ReadAll(io.LimitReader(resp.Body, samlMetadataMaxBytes+1))
 	if err != nil {
 		return nil, 0, fmt.Errorf("read saml metadata: %w", err)
 	}
 	if len(body) > samlMetadataMaxBytes {
 		return nil, 0, fmt.Errorf("saml metadata exceeds %d bytes", samlMetadataMaxBytes)
 	}
 	return body, resp.StatusCode, nil
 }
 // metadataHTTPClient 选取元数据请求的客户端:未配代理直连;配了代理但配置非法时
 // 报错而非静默直连(失败关闭)。
 func metadataHTTPClient(cred Credentials) (*http.Client, error) {
 	if cred.Proxy == nil {
 		return http.DefaultClient, nil
 	}
 	if hc := HTTPClientFor(cred.Proxy); hc != nil {
 		return hc, nil
 	}
 	return nil, errors.New("download saml metadata: invalid proxy config")
 }
 // enableSigningCertPublicAccess 开启域设置「访问签名证书」公开访问。
 func (c *RealClient) enableSigningCertPublicAccess(ctx context.Context, cred Credentials, region, domainID string) error {
 	dc, err := c.domainsClient(ctx, cred, region, domainID)
@@ -0,0 +1,196 @@
 package oci
 import (
 	"bytes"
 	"context"
 	"errors"
 	"net/http"
 	"net/http/httptest"
 	"strings"
 	"testing"
 	"github.com/oracle/oci-go-sdk/v65/common"
 	"github.com/oracle/oci-go-sdk/v65/identitydomains"
 )
 type federationCreateStub struct {
 	created      identitydomains.IdentityProvider
 	createErr    error
 	patchErr     error
 	deleteErr    error
 	patchCalls   int
 	deletedID    string
 	deleteCtxErr error
 }
 func (s *federationCreateStub) ListGroups(context.Context, identitydomains.ListGroupsRequest) (identitydomains.ListGroupsResponse, error) {
 	return identitydomains.ListGroupsResponse{}, nil
 }
 func (s *federationCreateStub) CreateIdentityProvider(context.Context, identitydomains.CreateIdentityProviderRequest) (identitydomains.CreateIdentityProviderResponse, error) {
 	return identitydomains.CreateIdentityProviderResponse{IdentityProvider: s.created}, s.createErr
 }
 func (s *federationCreateStub) GetIdentityProvider(context.Context, identitydomains.GetIdentityProviderRequest) (identitydomains.GetIdentityProviderResponse, error) {
 	return identitydomains.GetIdentityProviderResponse{IdentityProvider: s.created}, nil
 }
 func (s *federationCreateStub) PatchMappedAttribute(context.Context, identitydomains.PatchMappedAttributeRequest) (identitydomains.PatchMappedAttributeResponse, error) {
 	s.patchCalls++
 	return identitydomains.PatchMappedAttributeResponse{}, s.patchErr
 }
 func (s *federationCreateStub) DeleteIdentityProvider(ctx context.Context, request identitydomains.DeleteIdentityProviderRequest) (identitydomains.DeleteIdentityProviderResponse, error) {
 	s.deletedID = deref(request.IdentityProviderId)
 	s.deleteCtxErr = ctx.Err()
 	return identitydomains.DeleteIdentityProviderResponse{}, s.deleteErr
 }
 func createdJitIdp(id string) identitydomains.IdentityProvider {
 	return identitydomains.IdentityProvider{
 		Id: idPtr(id), PartnerName: common.String("test-idp"), Type: identitydomains.IdentityProviderTypeSaml,
 		JitUserProvEnabled: common.Bool(true), JitUserProvAttributes: &identitydomains.IdentityProviderJitUserProvAttributes{Value: common.String("mapping-1")},
 	}
 }
 func idPtr(value string) *string {
 	if value == "" {
 		return nil
 	}
 	return common.String(value)
 }
 func testJitInput() CreateIdpInput {
 	return CreateIdpInput{Name: "test-idp", JitEnabled: true, IconURL: "https://img.example/icon.png"}
 }
 func TestCreateSamlIdentityProviderCreateFailure(t *testing.T) {
 	createErr := errors.New("create rejected")
 	stub := &federationCreateStub{createErr: createErr}
 	got, err := createSamlIdentityProvider(context.Background(), stub, testJitInput())
 	if !errors.Is(err, createErr) {
 		t.Fatalf("err = %v, want create error", err)
 	}
 	if got.ID != "" || stub.patchCalls != 0 || stub.deletedID != "" {
 		t.Errorf("got = %+v, patchCalls = %d, deletedID = %q", got, stub.patchCalls, stub.deletedID)
 	}
 }
 func TestCreateSamlIdentityProviderJitFailureRollbackSuccess(t *testing.T) {
 	patchErr := errors.New("patch rejected")
 	stub := &federationCreateStub{created: createdJitIdp("idp-1"), patchErr: patchErr}
 	ctx, cancel := context.WithCancel(context.Background())
 	cancel()
 	got, err := createSamlIdentityProvider(ctx, stub, testJitInput())
 	var partial *PartialIdentityProviderCreateError
 	if !errors.Is(err, patchErr) || errors.As(err, &partial) {
 		t.Fatalf("err = %v, want ordinary wrapped patch error", err)
 	}
 	if got.ID != "" || stub.deletedID != "idp-1" || stub.deleteCtxErr != nil {
 		t.Errorf("got.ID = %q, deletedID = %q, deleteCtxErr = %v", got.ID, stub.deletedID, stub.deleteCtxErr)
 	}
 }
 func TestCreateSamlIdentityProviderPartialCreateContract(t *testing.T) {
 	cases := []struct {
 		name, id   string
 		deleteErr  error
 		wantDelete bool
 	}{
 		{"rollback fails", "idp-1", errors.New("rollback secret detail"), true},
 		{"created id missing", "", nil, false},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) { assertPartialCreate(t, tc.id, tc.deleteErr, tc.wantDelete) })
 	}
 }
 func assertPartialCreate(t *testing.T, id string, deleteErr error, wantDelete bool) {
 	t.Helper()
 	stub := &federationCreateStub{created: createdJitIdp(id), patchErr: errors.New("patch secret detail"), deleteErr: deleteErr}
 	got, err := createSamlIdentityProvider(context.Background(), stub, testJitInput())
 	var partial *PartialIdentityProviderCreateError
 	if !errors.As(err, &partial) || partial.IdentityProvider.ID != id {
 		t.Fatalf("got = %+v, err = %v, partial = %+v", got, err, partial)
 	}
 	if strings.Contains(err.Error(), "secret") || (stub.deletedID != "") != wantDelete {
 		t.Errorf("unsafe err = %q or deletedID = %q, wantDelete = %v", err, stub.deletedID, wantDelete)
 	}
 }
 func ruleReturn(name, value string) identitydomains.RuleReturn {
 	return identitydomains.RuleReturn{Name: common.String(name), Value: common.String(value)}
 }
 type rebuildIdpReturnCase struct {
 	name    string
 	items   []identitydomains.RuleReturn
 	show    bool
 	changed bool
 	want    string
 }
 func TestRebuildSamlIdpsReturn(t *testing.T) {
 	local := ruleReturn("LocalIDPs", `["UserNamePassword"]`)
 	cases := []rebuildIdpReturnCase{
 		{"无SamlIDPs项时添加须补建", []identitydomains.RuleReturn{local}, true, true, `["idp-1"]`},
 		{"无SamlIDPs项时移除无变化", []identitydomains.RuleReturn{local}, false, false, ""},
 		{"已有其他IdP时追加", []identitydomains.RuleReturn{local, ruleReturn("SamlIDPs", `["other"]`)}, true, true, `["other","idp-1"]`},
 		{"已在列表中再添加无变化", []identitydomains.RuleReturn{ruleReturn("SamlIDPs", `["idp-1"]`)}, true, false, `["idp-1"]`},
 		{"移除目标IdP", []identitydomains.RuleReturn{ruleReturn("SamlIDPs", `["idp-1","other"]`)}, false, true, `["other"]`},
 		{"空值项添加", []identitydomains.RuleReturn{ruleReturn("SamlIDPs", "")}, true, true, `["idp-1"]`},
 	}
 	assertRebuildIdpReturns(t, cases)
 }
 func assertRebuildIdpReturns(t *testing.T, cases []rebuildIdpReturnCase) {
 	t.Helper()
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
 			returns, changed, err := rebuildSamlIdpsReturn(tc.items, "idp-1", tc.show)
 			if err != nil {
 				t.Fatalf("rebuildSamlIdpsReturn: %v", err)
 			}
 			if changed != tc.changed {
 				t.Errorf("changed = %v, want %v", changed, tc.changed)
 			}
 			got := ""
 			for _, r := range returns {
 				m := r.(map[string]string)
 				if m["name"] == "SamlIDPs" {
 					got = m["value"]
 				}
 			}
 			if got != tc.want {
 				t.Errorf("SamlIDPs = %q, want %q", got, tc.want)
 			}
 		})
 	}
 }
 func TestRebuildSamlIdpsReturnBadJSON(t *testing.T) {
 	items := []identitydomains.RuleReturn{ruleReturn("SamlIDPs", "not-json")}
 	if _, _, err := rebuildSamlIdpsReturn(items, "idp-1", true); err == nil {
 		t.Fatal("坏 JSON 应报错而非静默覆盖")
 	}
 }
 // TestFetchSamlMetadataLimitsBody 锁定匿名元数据请求的响应体上限:超限报错而非吞下。
 func TestFetchSamlMetadataLimitsBody(t *testing.T) {
 	huge := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		_, _ = w.Write(bytes.Repeat([]byte("x"), samlMetadataMaxBytes+1))
 	}))
 	defer huge.Close()
 	if _, _, err := fetchSamlMetadata(context.Background(), Credentials{}, huge.URL); err == nil ||
 		!strings.Contains(err.Error(), "exceeds") {
 		t.Fatalf("err = %v, want 超限错误", err)
 	}
 	ok := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		_, _ = w.Write([]byte("<EntityDescriptor/>"))
 	}))
 	defer ok.Close()
 	body, status, err := fetchSamlMetadata(context.Background(), Credentials{}, ok.URL)
 	if err != nil || status != http.StatusOK || string(body) != "<EntityDescriptor/>" {
 		t.Fatalf("fetch = %q, %d, %v; want 正常返回", body, status, err)
 	}
 }
@@ -60,9 +60,9 @@ func (c *RealClient) GenAiCompatResponses(ctx context.Context, cred Credentials,
 		return nil, err
 	}
 	defer response.Body.Close()
-	payload, err := io.ReadAll(io.LimitReader(response.Body, compatResponsesLimit))
+	payload, err := readCompatBody(response.Body, compatResponsesLimit, "compat responses")
 	if err != nil {
-		return nil, fmt.Errorf("read compat responses body: %w", err)
+		return nil, err
 	}
 	return payload, nil
 }
@@ -121,3 +121,16 @@ func (c *RealClient) GenAiCompatResponsesStream(ctx context.Context, cred Creden
 	}
 	return callWithHeaderBudget(ctx, client, request, wait)
 }
 // readCompatBody 读取上游响应体并施加上限;读 limit+1 判超报错——
 // 静默截断的 JSON/音频配 200 会被下游当完整成功记账。
 func readCompatBody(body io.Reader, limit int64, tag string) ([]byte, error) {
 	payload, err := io.ReadAll(io.LimitReader(body, limit+1))
 	if err != nil {
 		return nil, fmt.Errorf("read %s body: %w", tag, err)
 	}
 	if int64(len(payload)) > limit {
 		return nil, fmt.Errorf("%s body exceeds %d bytes", tag, limit)
 	}
 	return payload, nil
 }
@@ -1,6 +1,7 @@
 package oci
 import (
 	"bytes"
 	"context"
 	"errors"
 	"io"
@@ -139,3 +140,31 @@ func TestCallWithHeaderBudget(t *testing.T) {
 		}
 	})
 }
 // TestReadCompatBodyRejectsOversize 锁定上游响应上限:恰好达限通过,超限报错,
 // 不允许静默截断配 200 让下游当完整成功。
 func TestReadCompatBodyRejectsOversize(t *testing.T) {
 	cases := []struct {
 		name    string
 		size    int64
 		wantErr bool
 	}{
 		{"under limit", 15, false},
 		{"exactly limit", 16, false},
 		{"over limit", 17, true},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
 			payload, err := readCompatBody(bytes.NewReader(make([]byte, tc.size)), 16, "test")
 			if tc.wantErr {
 				if err == nil || !strings.Contains(err.Error(), "exceeds") {
 					t.Fatalf("err = %v, want 超限错误", err)
 				}
 				return
 			}
 			if err != nil || int64(len(payload)) != tc.size {
 				t.Fatalf("payload = %d bytes, %v; want %d", len(payload), err, tc.size)
 			}
 		})
 	}
 }
@@ -4,7 +4,6 @@ import (
 	"bytes"
 	"context"
 	"fmt"
 	"io"
 	"net/http"
 	"github.com/oracle/oci-go-sdk/v65/common"
@@ -36,9 +35,9 @@ func (c *RealClient) GenAiCompatSpeech(ctx context.Context, cred Credentials, re
 		return nil, "", err
 	}
 	defer response.Body.Close()
-	payload, err := io.ReadAll(io.LimitReader(response.Body, compatSpeechLimit))
+	payload, err := readCompatBody(response.Body, compatSpeechLimit, "compat speech")
 	if err != nil {
-		return nil, "", fmt.Errorf("read compat speech body: %w", err)
+		return nil, "", err
 	}
 	return payload, response.Header.Get("Content-Type"), nil
 }
@@ -49,6 +49,7 @@ type CreateInstanceInput struct {
 	BootVolumeVpusPerGB  int64  // 引导卷性能，10 均衡 / 20 高性能，仅镜像启动源生效
 	SubnetID             string // 为空时自动创建 VCN 与子网
 	AssignPublicIP       bool
 	ReservedPublicIPID   string // 非空时不分配临时公网 IP,实例就绪后由 service 层绑定该保留 IP
 	AssignIpv6           bool
 	SSHPublicKey         string            // 与 RootPassword 互斥
 	RootPassword         string            // 与 SSHPublicKey 互斥，非空时生成开启 root 密码登录的 cloud-init
@@ -189,6 +190,10 @@ func (c *RealClient) LaunchInstance(ctx context.Context, cred Credentials, in Cr
 }
 func buildLaunchDetails(compartmentID string, in CreateInstanceInput) (core.LaunchInstanceDetails, error) {
 	// 保留 IP 不能在 launch 时直接绑定:先不分配临时公网 IP,就绪后由 service 层换绑
 	if in.ReservedPublicIPID != "" {
 		in.AssignPublicIP = false
 	}
 	details := core.LaunchInstanceDetails{
 		CompartmentId:      &compartmentID,
 		AvailabilityDomain: &in.AvailabilityDomain,
@@ -2,8 +2,6 @@ package oci
 import (
 	"context"
 	"crypto/rand"
 	"encoding/hex"
 	"fmt"
 	"strings"
 	"time"
@@ -14,14 +12,11 @@ import (
 	"github.com/oracle/oci-go-sdk/v65/sch"
 )
-// 日志回传链路(方案A)在租户侧的固定资源命名,按名幂等查找与创建;
+// 日志回传链路(方案A)在租户侧的资源命名与描述由 logrelay_names.go 集中派生;
 // 资源建在凭据默认区域,Audit 日志组含子 compartment。
 // Topic 删除后名称有保留期(同名重建长时间 409 Conflict),故 Topic 用
 // 前缀+随机后缀命名、按前缀幂等查找,销毁重建不受保留期阻塞。
 const (
 	relayTopicPrefix   = "ociportal-logs"
 	relayPolicyName    = "ociportal-logs-sch"
 	relayConnectorName = "ociportal-logs"
 	relayAuditLogGroup = "_Audit_Include_Subcompartment"
 	relayTopicPages    = 5 // 按前缀查找 Topic 的翻页上限
 )
@@ -83,24 +78,36 @@ func (c *RealClient) schClient(cred Credentials) (sch.ServiceConnectorClient, er
 	return sc, nil
 }
-// EnsureRelayTopic 实现 Client:按前缀返回既有 Topic 或以随机后缀新建。
+// EnsureRelayTopic 实现 Client:按新命名前缀返回既有 Topic,fallback 到 legacy 前缀;
 // 未命中则以新前缀 + 随机后缀新建。命中旧命名时顺手把描述刷新为中性文案。
 func (c *RealClient) EnsureRelayTopic(ctx context.Context, cred Credentials) (RelayResource, error) {
 	cp, err := c.onsControlClient(cred)
 	if err != nil {
 		return RelayResource{}, err
 	}
-	if res, ok, err := findRelayTopic(ctx, cp, cred.TenancyOCID); err != nil || ok {
+	names := relayResourceNames(cred.TenancyOCID)
-		return res, err
+	res, ok, err := findRelayTopic(ctx, cp, cred.TenancyOCID, names.TopicPrefix, legacyRelayTopicPrefix)
 	if err != nil {
 		return RelayResource{}, err
 	}
-	name, err := relayTopicNewName()
+	if ok {
 		refreshRelayTopicDesc(ctx, cp, res.ID)
 		return res, nil
 	}
 	return createRelayTopic(ctx, cp, cred.TenancyOCID, names.TopicPrefix)
 }
 // createRelayTopic 以指定前缀 + 4 字节随机后缀新建 ONS Topic,描述使用中性文案。
 func createRelayTopic(ctx context.Context, cp ons.NotificationControlPlaneClient, tenancy, prefix string) (RelayResource, error) {
 	name, err := relayTopicNewName(prefix)
 	if err != nil {
 		return RelayResource{}, err
 	}
 	created, err := cp.CreateTopic(ctx, ons.CreateTopicRequest{
 		CreateTopicDetails: ons.CreateTopicDetails{
 			Name:          &name,
-			CompartmentId: &cred.TenancyOCID,
+			CompartmentId: &tenancy,
-			Description:   common.String("oci-portal 日志回传:关键审计事件经 Connector 投递到面板"),
+			Description:   common.String(relayTopicDescNew),
 		},
 	})
 	if err != nil {
@@ -109,28 +116,17 @@ func (c *RealClient) EnsureRelayTopic(ctx context.Context, cred Credentials) (Re
 	return RelayResource{ID: deref(created.TopicId), State: string(created.LifecycleState), Created: true}, nil
 }
-// relayTopicNewName 生成带随机后缀的 Topic 名,规避删除名称保留期。
+// findRelayTopic 依次按传入的前缀列表在租户范围内查找存活 Topic;第一个命中即返回。
-func relayTopicNewName() (string, error) {
+// 支持传入新命名前缀与 legacy 前缀,实现向后兼容存量资源。
-	buf := make([]byte, 4)
+func findRelayTopic(ctx context.Context, cp ons.NotificationControlPlaneClient, tenancy string, prefixes ...string) (RelayResource, bool, error) {
 	if _, err := rand.Read(buf); err != nil {
 		return "", fmt.Errorf("topic name suffix: %w", err)
 	}
 	return relayTopicPrefix + "-" + hex.EncodeToString(buf), nil
 }
 // findRelayTopic 按名称前缀查找存活 Topic;未找到时 ok 为 false。
 func findRelayTopic(ctx context.Context, cp ons.NotificationControlPlaneClient, tenancy string) (RelayResource, bool, error) {
 	req := ons.ListTopicsRequest{CompartmentId: &tenancy}
 	for page := 0; page < relayTopicPages; page++ {
 		list, err := cp.ListTopics(ctx, req)
 		if err != nil {
 			return RelayResource{}, false, fmt.Errorf("list ons topics: %w", err)
 		}
-		for _, t := range list.Items {
+		if res, ok := matchRelayTopic(list.Items, prefixes); ok {
-			if strings.HasPrefix(deref(t.Name), relayTopicPrefix) &&
+			return res, true, nil
 				t.LifecycleState == ons.NotificationTopicSummaryLifecycleStateActive {
 				return RelayResource{ID: deref(t.TopicId), State: string(t.LifecycleState)}, true, nil
 			}
 		}
 		if list.OpcNextPage == nil {
 			break
@@ -140,6 +136,35 @@ func findRelayTopic(ctx context.Context, cp ons.NotificationControlPlaneClient,
 	return RelayResource{}, false, nil
 }
 // matchRelayTopic 在一页 Topic 中挑出第一个命名前缀命中且处于 ACTIVE 的资源。
 func matchRelayTopic(items []ons.NotificationTopicSummary, prefixes []string) (RelayResource, bool) {
 	for _, t := range items {
 		if t.LifecycleState != ons.NotificationTopicSummaryLifecycleStateActive {
 			continue
 		}
 		name := deref(t.Name)
 		for _, p := range prefixes {
 			if strings.HasPrefix(name, p) {
 				return RelayResource{ID: deref(t.TopicId), State: string(t.LifecycleState)}, true
 			}
 		}
 	}
 	return RelayResource{}, false
 }
 // refreshRelayTopicDesc 尽力把 Topic 描述改为中性文案;失败不阻塞主流程(权限不足等场景直接忽略)。
 func refreshRelayTopicDesc(ctx context.Context, cp ons.NotificationControlPlaneClient, topicID string) {
 	if topicID == "" {
 		return
 	}
 	_, _ = cp.UpdateTopic(ctx, ons.UpdateTopicRequest{
 		TopicId: &topicID,
 		TopicAttributesDetails: ons.TopicAttributesDetails{
 			Description: common.String(relayTopicDescNew),
 		},
 	})
 }
 // EnsureRelaySubscription 实现 Client:按 endpoint 返回既有 CUSTOM_HTTPS 订阅或新建;
 // 新建订阅处于 PENDING,待 ONS 向 endpoint 投递确认消息、面板回访后转 ACTIVE。
 func (c *RealClient) EnsureRelaySubscription(ctx context.Context, cred Credentials, topicID, endpoint string) (RelayResource, error) {
@@ -196,28 +221,50 @@ func (c *RealClient) GetRelaySubscription(ctx context.Context, cred Credentials,
 	return RelayResource{ID: deref(resp.Id), State: string(resp.LifecycleState)}, nil
 }
-// EnsureRelayPolicy 实现 Client:按名返回既有 IAM policy 或新建;
+// EnsureRelayPolicy 实现 Client:按新命名返回既有 IAM policy,fallback 到 legacy 命名;
-// 写操作必须发往 home region,授权 Service Connector 发布消息到 Topic。
+// 未命中则以新命名创建。写操作必须发往 home region,授权 Service Connector 发布消息到 Topic。
 func (c *RealClient) EnsureRelayPolicy(ctx context.Context, cred Credentials, homeRegion string) (RelayResource, error) {
 	ic, err := c.identityClientAt(cred, homeRegion)
 	if err != nil {
 		return RelayResource{}, err
 	}
-	list, err := ic.ListPolicies(ctx, identity.ListPoliciesRequest{
+	names := relayResourceNames(cred.TenancyOCID)
-		CompartmentId: &cred.TenancyOCID, Name: common.String(relayPolicyName),
+	res, ok, err := findRelayPolicy(ctx, ic, cred.TenancyOCID, names.PolicyName, legacyRelayPolicyName)
 	})
 	if err != nil {
-		return RelayResource{}, fmt.Errorf("list policies: %w", err)
+		return RelayResource{}, err
 	}
-	if len(list.Items) > 0 {
+	if ok {
-		return RelayResource{ID: deref(list.Items[0].Id), State: string(list.Items[0].LifecycleState)}, nil
+		refreshRelayPolicyDesc(ctx, ic, res.ID)
 		return res, nil
 	}
-	stmt := fmt.Sprintf("Allow any-user to use ons-topics in tenancy where all {request.principal.type='serviceconnector', request.principal.compartment.id='%s'}", cred.TenancyOCID)
+	return createRelayPolicy(ctx, ic, cred.TenancyOCID, names.PolicyName)
 }
 // findRelayPolicy 依次按传入的名称列表在租户范围内查找 IAM Policy;第一个命中即返回。
 func findRelayPolicy(ctx context.Context, ic identity.IdentityClient, tenancy string, names ...string) (RelayResource, bool, error) {
 	for _, name := range names {
 		list, err := ic.ListPolicies(ctx, identity.ListPoliciesRequest{
 			CompartmentId: &tenancy, Name: common.String(name),
 		})
 		if err != nil {
 			return RelayResource{}, false, fmt.Errorf("list policies: %w", err)
 		}
 		if len(list.Items) > 0 {
 			it := list.Items[0]
 			return RelayResource{ID: deref(it.Id), State: string(it.LifecycleState)}, true, nil
 		}
 	}
 	return RelayResource{}, false, nil
 }
 // createRelayPolicy 以中性描述与派生名称新建 Policy,statement 允许 Service Connector 发布消息到租户内 Topic。
 func createRelayPolicy(ctx context.Context, ic identity.IdentityClient, tenancy, name string) (RelayResource, error) {
 	stmt := fmt.Sprintf("Allow any-user to use ons-topics in tenancy where all {request.principal.type='serviceconnector', request.principal.compartment.id='%s'}", tenancy)
 	created, err := ic.CreatePolicy(ctx, identity.CreatePolicyRequest{
 		CreatePolicyDetails: identity.CreatePolicyDetails{
-			CompartmentId: &cred.TenancyOCID,
+			CompartmentId: &tenancy,
-			Name:          common.String(relayPolicyName),
+			Name:          common.String(name),
-			Description:   common.String("oci-portal 日志回传:允许 Service Connector 发布到 ONS Topic"),
+			Description:   common.String(relayPolicyDescNew),
 			Statements:    []string{stmt},
 		},
 	})
@@ -227,21 +274,45 @@ func (c *RealClient) EnsureRelayPolicy(ctx context.Context, cred Credentials, ho
 	return RelayResource{ID: deref(created.Id), State: string(created.LifecycleState), Created: true}, nil
 }
-// EnsureRelayConnector 实现 Client:按名返回既有 Connector 或新建(_Audit 含子区间 → Topic,
+// refreshRelayPolicyDesc 尽力把 Policy 描述改为中性文案;失败不阻塞主流程。
-// 按 condition 过滤);新建后轮询至 ACTIVE,超时返回错误但保留 Created 供上层回滚。
+func refreshRelayPolicyDesc(ctx context.Context, ic identity.IdentityClient, id string) {
 	if id == "" {
 		return
 	}
 	_, _ = ic.UpdatePolicy(ctx, identity.UpdatePolicyRequest{
 		PolicyId: &id,
 		UpdatePolicyDetails: identity.UpdatePolicyDetails{
 			Description: common.String(relayPolicyDescNew),
 		},
 	})
 }
 // EnsureRelayConnector 实现 Client:按新命名返回既有 Connector,fallback 到 legacy DisplayName;
 // 命中时对齐 Log Filter 条件,未命中则以新命名新建并轮询至 ACTIVE。
 func (c *RealClient) EnsureRelayConnector(ctx context.Context, cred Credentials, topicID, condition string) (RelayResource, error) {
 	sc, err := c.schClient(cred)
 	if err != nil {
 		return RelayResource{}, err
 	}
-	if res, ok, err := findRelayConnector(ctx, sc, cred.TenancyOCID); err != nil || ok {
+	names := relayResourceNames(cred.TenancyOCID)
-		return res, err
+	res, ok, err := findRelayConnector(ctx, sc, cred.TenancyOCID, names.ConnectorName, legacyRelayConnectorName)
 	if err != nil {
 		return RelayResource{}, err
 	}
 	if ok {
 		return res, reconcileRelayCondition(ctx, sc, res.ID, condition)
 	}
 	return createRelayConnector(ctx, sc, cred.TenancyOCID, names.ConnectorName, topicID, condition)
 }
 // createRelayConnector 以派生名称新建 Service Connector(_Audit 含子区间 → Topic,按 condition 过滤),
 // 新建后轮询至 ACTIVE,超时返回错误但保留 Created 供上层回滚。Connector 不设 Description,避免恒定文案指纹。
 func createRelayConnector(ctx context.Context, sc sch.ServiceConnectorClient, tenancy, name, topicID, condition string) (RelayResource, error) {
 	details := sch.CreateServiceConnectorDetails{
-		DisplayName:   common.String(relayConnectorName),
+		DisplayName:   common.String(name),
-		CompartmentId: &cred.TenancyOCID,
+		CompartmentId: &tenancy,
 		Source: sch.LoggingSourceDetails{LogSources: []sch.LogSource{{
-			CompartmentId: &cred.TenancyOCID,
+			CompartmentId: &tenancy,
 			LogGroupId:    common.String(relayAuditLogGroup),
 		}}},
 		Target: sch.NotificationsTargetDetails{TopicId: &topicID},
@@ -254,27 +325,69 @@ func (c *RealClient) EnsureRelayConnector(ctx context.Context, cred Credentials,
 	}); err != nil {
 		return RelayResource{}, fmt.Errorf("create service connector: %w", err)
 	}
-	return waitRelayConnector(ctx, sc, cred.TenancyOCID)
+	return waitRelayConnector(ctx, sc, tenancy, name)
 }
-// findRelayConnector 按名查找存活 Connector。
+// reconcileRelayCondition 对齐存量 Connector 的过滤条件:关键事件清单变更
-func findRelayConnector(ctx context.Context, sc sch.ServiceConnectorClient, tenancy string) (RelayResource, bool, error) {
+// (如去除 LaunchInstance)后,已建链路经「一键创建」幂等调用原地更新,无需拆除重建。
-	list, err := sc.ListServiceConnectors(ctx, sch.ListServiceConnectorsRequest{
+func reconcileRelayCondition(ctx context.Context, sc sch.ServiceConnectorClient, id, condition string) error {
-		CompartmentId: &tenancy, DisplayName: common.String(relayConnectorName),
+	got, err := sc.GetServiceConnector(ctx, sch.GetServiceConnectorRequest{ServiceConnectorId: &id})
 	if err != nil {
 		return fmt.Errorf("get service connector: %w", err)
 	}
 	if !relayConditionDiffers(got.Tasks, condition) {
 		return nil
 	}
 	details := sch.UpdateServiceConnectorDetails{Tasks: []sch.TaskDetails{}}
 	if condition != "" {
 		details.Tasks = []sch.TaskDetails{sch.LogRuleTaskDetails{Condition: &condition}}
 	}
 	_, err = sc.UpdateServiceConnector(ctx, sch.UpdateServiceConnectorRequest{
 		ServiceConnectorId: &id, UpdateServiceConnectorDetails: details,
 	})
 	if err != nil {
-		return RelayResource{}, false, fmt.Errorf("list service connectors: %w", err)
+		return fmt.Errorf("update service connector condition: %w", err)
 	}
-	for _, item := range list.Items {
+	return nil
-		if item.LifecycleState != sch.LifecycleStateDeleted && item.LifecycleState != sch.LifecycleStateDeleting {
+}
-			return RelayResource{ID: deref(item.Id), State: string(item.LifecycleState)}, true, nil
+
 // relayConditionDiffers 判断现有任务集与期望条件是否不一致:
 // 期望形态是单条 LogRule 条件;任务数、类型或条件文本不同均视为漂移。
 func relayConditionDiffers(tasks []sch.TaskDetailsResponse, want string) bool {
 	if want == "" {
 		return len(tasks) > 0
 	}
 	if len(tasks) != 1 {
 		return true
 	}
 	rule, ok := tasks[0].(sch.LogRuleTaskDetailsResponse)
 	if !ok || rule.Condition == nil {
 		return true
 	}
 	return *rule.Condition != want
 }
 // findRelayConnector 依次按传入的 DisplayName 列表在租户范围内查找存活 Connector;第一个命中即返回。
 func findRelayConnector(ctx context.Context, sc sch.ServiceConnectorClient, tenancy string, names ...string) (RelayResource, bool, error) {
 	for _, name := range names {
 		list, err := sc.ListServiceConnectors(ctx, sch.ListServiceConnectorsRequest{
 			CompartmentId: &tenancy, DisplayName: common.String(name),
 		})
 		if err != nil {
 			return RelayResource{}, false, fmt.Errorf("list service connectors: %w", err)
 		}
 		for _, item := range list.Items {
 			if item.LifecycleState != sch.LifecycleStateDeleted && item.LifecycleState != sch.LifecycleStateDeleting {
 				return RelayResource{ID: deref(item.Id), State: string(item.LifecycleState)}, true, nil
 			}
 		}
 	}
 	return RelayResource{}, false, nil
 }
 // waitRelayConnector 轮询新建 Connector 直至 ACTIVE;超时带回已建资源信息。
-func waitRelayConnector(ctx context.Context, sc sch.ServiceConnectorClient, tenancy string) (RelayResource, error) {
+// 只按新命名查找(新建资源用的就是新命名)。
 func waitRelayConnector(ctx context.Context, sc sch.ServiceConnectorClient, tenancy, name string) (RelayResource, error) {
 	last := RelayResource{Created: true}
 	for i := 0; i < relayConnectorPollLimit; i++ {
 		select {
@@ -282,7 +395,7 @@ func waitRelayConnector(ctx context.Context, sc sch.ServiceConnectorClient, tena
 			return last, ctx.Err()
 		case <-time.After(relayConnectorPollTick):
 		}
-		res, ok, err := findRelayConnector(ctx, sc, tenancy)
+		res, ok, err := findRelayConnector(ctx, sc, tenancy, name)
 		if err != nil {
 			return last, err
 		}
@@ -303,7 +416,8 @@ func (c *RealClient) RelayState(ctx context.Context, cred Credentials, endpoint
 	if err != nil {
 		return st, err
 	}
-	if st.Topic, _, err = findRelayTopic(ctx, cp, cred.TenancyOCID); err != nil {
+	names := relayResourceNames(cred.TenancyOCID)
 	if st.Topic, _, err = findRelayTopic(ctx, cp, cred.TenancyOCID, names.TopicPrefix, legacyRelayTopicPrefix); err != nil {
 		return st, err
 	}
 	if st.Topic.ID != "" {
@@ -318,27 +432,22 @@ func (c *RealClient) RelayState(ctx context.Context, cred Credentials, endpoint
 	return c.relayControlState(ctx, cred, st)
 }
-// relayControlState 补齐 Connector 与 Policy 两项状态。
+// relayControlState 补齐 Connector 与 Policy 两项状态,双路径兼容 legacy 命名。
 func (c *RealClient) relayControlState(ctx context.Context, cred Credentials, st RelayState) (RelayState, error) {
 	sc, err := c.schClient(cred)
 	if err != nil {
 		return st, err
 	}
-	if st.Connector, _, err = findRelayConnector(ctx, sc, cred.TenancyOCID); err != nil {
+	names := relayResourceNames(cred.TenancyOCID)
 	if st.Connector, _, err = findRelayConnector(ctx, sc, cred.TenancyOCID, names.ConnectorName, legacyRelayConnectorName); err != nil {
 		return st, err
 	}
 	ic, err := c.identityClientAt(cred, "")
 	if err != nil {
 		return st, err
 	}
-	list, err := ic.ListPolicies(ctx, identity.ListPoliciesRequest{
+	if st.Policy, _, err = findRelayPolicy(ctx, ic, cred.TenancyOCID, names.PolicyName, legacyRelayPolicyName); err != nil {
-		CompartmentId: &cred.TenancyOCID, Name: common.String(relayPolicyName),
+		return st, err
 	})
 	if err != nil {
 		return st, fmt.Errorf("list policies: %w", err)
 	}
 	if len(list.Items) > 0 {
 		st.Policy = RelayResource{ID: deref(list.Items[0].Id), State: string(list.Items[0].LifecycleState)}
 	}
 	return st, nil
 }
@@ -0,0 +1,53 @@
 package oci
 import (
 	"crypto/rand"
 	"crypto/sha256"
 	"encoding/hex"
 	"fmt"
 )
 // 日志回传链路资源命名与描述文案的集中定义。
 // 目标:让每租户派生互异的中性资源名,避免跨租户恒定字面量成为「共用同一套 oci-portal」的指纹。
 // relayNames 是按 tenancy 派生的一组资源名。
 type relayNames struct {
 	TopicPrefix   string // 例: "c3f2a1b0-audit",Topic 最终名再加短随机后缀
 	PolicyName    string // 例: "c3f2a1b0-audit-p"
 	ConnectorName string // 例: "c3f2a1b0-audit"
 }
 // relayResourceNames 由 tenancyOCID 派生一组稳定的中性资源名。
 // SHA-256 前 4 字节做前缀,同 tenancy 每次调用结果一致(幂等查找依赖此性质)。
 func relayResourceNames(tenancyOCID string) relayNames {
 	sum := sha256.Sum256([]byte(tenancyOCID))
 	prefix := hex.EncodeToString(sum[:4])
 	return relayNames{
 		TopicPrefix:   prefix + "-audit",
 		PolicyName:    prefix + "-audit-p",
 		ConnectorName: prefix + "-audit",
 	}
 }
 // relayTopicNewName 按给定前缀 + 4 字节随机后缀生成 Topic 名,规避 ONS 删除保留期。
 func relayTopicNewName(prefix string) (string, error) {
 	buf := make([]byte, 4)
 	if _, err := rand.Read(buf); err != nil {
 		return "", fmt.Errorf("topic name suffix: %w", err)
 	}
 	return prefix + "-" + hex.EncodeToString(buf), nil
 }
 // 描述文案:中性英文,不含品牌明文;集中于此便于后续再调整。
 const (
 	relayTopicDescNew  = "Audit event relay endpoint"
 	relayPolicyDescNew = "Allow Service Connector to publish audit events to notification topic"
 )
 // legacyRelay* 仅用于识别旧版本(硬编码 ociportal-logs*)创建的存量资源,不用于新建。
 // 新租户完全走 relayResourceNames 派生;存量租户 fallback 命中后描述会一次性刷新为中性文案。
 const (
 	legacyRelayTopicPrefix   = "ociportal-logs"
 	legacyRelayPolicyName    = "ociportal-logs-sch"
 	legacyRelayConnectorName = "ociportal-logs"
 )
@@ -0,0 +1,115 @@
 package oci
 import (
 	"regexp"
 	"strings"
 	"testing"
 )
 func TestRelayResourceNames_Deterministic(t *testing.T) {
 	tenancy := "ocid1.tenancy.oc1..aaaaexampletenant"
 	a := relayResourceNames(tenancy)
 	b := relayResourceNames(tenancy)
 	if a != b {
 		t.Fatalf("同 tenancy 派生不一致: %+v vs %+v", a, b)
 	}
 }
 func TestRelayResourceNames_DistinctTenancies(t *testing.T) {
 	cases := []string{
 		"ocid1.tenancy.oc1..aaaaaaaaaa",
 		"ocid1.tenancy.oc1..bbbbbbbbbb",
 		"ocid1.tenancy.oc1..cccccccccc",
 	}
 	seen := map[string]string{}
 	for _, tenancy := range cases {
 		n := relayResourceNames(tenancy)
 		if got, ok := seen[n.TopicPrefix]; ok {
 			t.Fatalf("前缀冲突: %s 与 %s 同为 %s", tenancy, got, n.TopicPrefix)
 		}
 		seen[n.TopicPrefix] = tenancy
 		assertNoBrandLeak(t, tenancy, n)
 	}
 }
 // assertNoBrandLeak 断言派生结果不含品牌明文,以及格式符合预期。
 func assertNoBrandLeak(t *testing.T, tenancy string, n relayNames) {
 	t.Helper()
 	banned := []string{"oci-portal", "ociportal", "logs", "portal"}
 	fields := []struct {
 		name  string
 		value string
 	}{
 		{"TopicPrefix", n.TopicPrefix},
 		{"PolicyName", n.PolicyName},
 		{"ConnectorName", n.ConnectorName},
 	}
 	for _, f := range fields {
 		lower := strings.ToLower(f.value)
 		for _, b := range banned {
 			if strings.Contains(lower, b) {
 				t.Errorf("tenancy %s: %s=%q 含品牌明文 %q", tenancy, f.name, f.value, b)
 			}
 		}
 		if !regexp.MustCompile(`^[0-9a-f]{8}-audit(-p)?$`).MatchString(f.value) {
 			t.Errorf("tenancy %s: %s=%q 不符合 <8hex>-audit(-p)? 格式", tenancy, f.name, f.value)
 		}
 	}
 }
 func TestRelayTopicNewName_Suffix(t *testing.T) {
 	tests := []struct {
 		name   string
 		prefix string
 	}{
 		{name: "标准前缀", prefix: "c3f2a1b0-audit"},
 		{name: "legacy 前缀兼容", prefix: legacyRelayTopicPrefix},
 	}
 	pat := regexp.MustCompile(`^[0-9a-f]{8}$`)
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			got, err := relayTopicNewName(tt.prefix)
 			if err != nil {
 				t.Fatalf("生成失败: %v", err)
 			}
 			if !strings.HasPrefix(got, tt.prefix+"-") {
 				t.Errorf("前缀不符: got=%q, prefix=%q", got, tt.prefix)
 			}
 			suffix := strings.TrimPrefix(got, tt.prefix+"-")
 			if !pat.MatchString(suffix) {
 				t.Errorf("后缀非 8 hex: got=%q, suffix=%q", got, suffix)
 			}
 		})
 	}
 }
 func TestLegacyPrefixes_Unchanged(t *testing.T) {
 	cases := []struct {
 		name string
 		got  string
 		want string
 	}{
 		{name: "Topic legacy", got: legacyRelayTopicPrefix, want: "ociportal-logs"},
 		{name: "Policy legacy", got: legacyRelayPolicyName, want: "ociportal-logs-sch"},
 		{name: "Connector legacy", got: legacyRelayConnectorName, want: "ociportal-logs"},
 	}
 	for _, tt := range cases {
 		t.Run(tt.name, func(t *testing.T) {
 			if tt.got != tt.want {
 				t.Errorf("legacy 常量被误改: got=%q, want=%q", tt.got, tt.want)
 			}
 		})
 	}
 }
 func TestRelayDescriptions_Neutral(t *testing.T) {
 	banned := []string{"oci-portal", "ociportal", "日志回传", "面板"}
 	for _, desc := range []string{relayTopicDescNew, relayPolicyDescNew} {
 		lower := strings.ToLower(desc)
 		for _, b := range banned {
 			if strings.Contains(lower, strings.ToLower(b)) {
 				t.Errorf("描述含品牌明文 %q: %q", b, desc)
 			}
 		}
 	}
 }
@@ -3,6 +3,8 @@ package oci
 import (
 	"strings"
 	"testing"
 	"github.com/oracle/oci-go-sdk/v65/sch"
 )
 func TestRelayEventCondition(t *testing.T) {
@@ -35,3 +37,31 @@ func TestRelayEventConditionQuoting(t *testing.T) {
 		t.Errorf("单引号数 = %d, want 2 (%s)", strings.Count(cond, "'"), cond)
 	}
 }
 func TestRelayConditionDiffers(t *testing.T) {
 	cond := "data.eventName='TerminateInstance'"
 	rule := func(c string) sch.TaskDetailsResponse {
 		return sch.LogRuleTaskDetailsResponse{Condition: &c}
 	}
 	tests := []struct {
 		name  string
 		tasks []sch.TaskDetailsResponse
 		want  string
 		diff  bool
 	}{
 		{name: "条件一致不漂移", tasks: []sch.TaskDetailsResponse{rule(cond)}, want: cond, diff: false},
 		{name: "条件文本不同漂移", tasks: []sch.TaskDetailsResponse{rule("data.eventName='LaunchInstance'")}, want: cond, diff: true},
 		{name: "无任务但期望条件漂移", tasks: nil, want: cond, diff: true},
 		{name: "多任务漂移", tasks: []sch.TaskDetailsResponse{rule(cond), rule(cond)}, want: cond, diff: true},
 		{name: "期望空且无任务不漂移", tasks: nil, want: "", diff: false},
 		{name: "期望空但有任务漂移", tasks: []sch.TaskDetailsResponse{rule(cond)}, want: "", diff: true},
 		{name: "条件缺失漂移", tasks: []sch.TaskDetailsResponse{sch.LogRuleTaskDetailsResponse{}}, want: cond, diff: true},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			if got := relayConditionDiffers(tt.tasks, tt.want); got != tt.diff {
 				t.Errorf("differs = %v, want %v", got, tt.diff)
 			}
 		})
 	}
 }
@@ -345,8 +345,8 @@ func (c *RealClient) UpdateVCN(ctx context.Context, cred Credentials, region, vc
 	return toVCN(resp.Vcn), nil
 }
-// DeleteVCN 实现 Client：级联清理子网、网关与非默认路由表 / 安全列表 /
+// DeleteVCN 实现 Client：级联清理子网、网关、网络安全组与非默认路由表 /
-// DHCP 选项后删除 VCN（见 vcndelete.go）；子网被实例占用时 OCI 返回 409。
+// 安全列表 / DHCP 选项后删除 VCN（见 vcndelete.go）；子网被实例占用时 OCI 返回 409。
 func (c *RealClient) DeleteVCN(ctx context.Context, cred Credentials, region, vcnID string) error {
 	vn, err := c.vcnClient(cred, region)
 	if err != nil {
@@ -0,0 +1,755 @@
 // 对象存储:namespace / 桶 / 对象 / 预签名请求(PAR)。
 // 上传下载数据面走 PAR 直连 OCI,面板只做控制面;
 // 例外:预览/编辑的小文件经面板中转(GetObject/PutObject),不签发 PAR。
 package oci
 import (
 	"bytes"
 	"context"
 	"errors"
 	"fmt"
 	"io"
 	"strings"
 	"time"
 	"github.com/oracle/oci-go-sdk/v65/common"
 	"github.com/oracle/oci-go-sdk/v65/objectstorage"
 )
 // ErrObjectTooLarge 表示对象超出面板中转大小上限。
 var ErrObjectTooLarge = errors.New("object too large for inline transfer")
 // ObjectContent 是对象内容与写入所需元数据(面板中转小文件用)。
 type ObjectContent struct {
 	Data        []byte
 	ContentType string
 	Etag        string
 }
 // Bucket 是存储桶摘要(含用量估算,来自 GetBucket 的 approximate 字段)。
 type Bucket struct {
 	Name             string     `json:"name"`
 	Namespace        string     `json:"namespace"`
 	Visibility       string     `json:"visibility"` // NoPublicAccess / ObjectRead
 	StorageTier      string     `json:"storageTier"`
 	VersioningOn     bool       `json:"versioningOn"`
 	ApproximateCount int64      `json:"approximateCount"`
 	ApproximateSize  int64      `json:"approximateSize"`
 	TimeCreated      *time.Time `json:"timeCreated"`
 }
 // ObjectSummary 是对象列表行;文件夹以 prefixes 单独返回。
 type ObjectSummary struct {
 	Name          string     `json:"name"`
 	Size          int64      `json:"size"`
 	StorageTier   string     `json:"storageTier"`
 	ArchivalState string     `json:"archivalState"`
 	TimeModified  *time.Time `json:"timeModified"`
 }
 // ListObjectsResult 是分页对象列表:delimiter="/" 模式,子层级归入 Prefixes。
 type ListObjectsResult struct {
 	Objects       []ObjectSummary `json:"objects"`
 	Prefixes      []string        `json:"prefixes"`
 	NextStartWith string          `json:"nextStartWith"`
 }
 // ObjectDetail 是对象元数据(HEAD)。
 type ObjectDetail struct {
 	Name          string            `json:"name"`
 	Size          int64             `json:"size"`
 	ContentType   string            `json:"contentType"`
 	Etag          string            `json:"etag"`
 	ContentMd5    string            `json:"contentMd5"`
 	StorageTier   string            `json:"storageTier"`
 	ArchivalState string            `json:"archivalState"`
 	TimeModified  *time.Time        `json:"timeModified"`
 	Metadata      map[string]string `json:"metadata"`
 }
 // PAR 是预签名请求摘要;FullURL 仅创建响应携带(OCI 事后不可再取回)。
 type PAR struct {
 	ID          string     `json:"id"`
 	Name        string     `json:"name"`
 	ObjectName  string     `json:"objectName"`
 	AccessType  string     `json:"accessType"`
 	FullURL     string     `json:"fullUrl,omitempty"`
 	TimeExpires *time.Time `json:"timeExpires"`
 	TimeCreated *time.Time `json:"timeCreated"`
 }
 // CreateBucketInput 创建桶参数;CompartmentID 空为生效 compartment。
 type CreateBucketInput struct {
 	Name          string
 	CompartmentID string
 	PublicRead    bool
 	StorageTier   string // Standard / Archive
 	VersioningOn  bool
 }
 // UpdateBucketInput 更新桶参数;nil 字段不改。
 type UpdateBucketInput struct {
 	PublicRead   *bool
 	VersioningOn *bool
 }
 // CreatePARInput 签发预签名请求参数。
 type CreatePARInput struct {
 	Name         string
 	ObjectName   string // 空 = 桶级(配合 AnyObjectReadWrite 前缀用法)
 	AccessType   string // ObjectRead / ObjectWrite / ObjectReadWrite / AnyObjectRead / AnyObjectWrite / AnyObjectReadWrite
 	ExpiresHours int
 }
 // bulkRetryPolicy 批量删除(清空桶)的限流退避:16 并发下 OCI 可能回 429。
 // 不用 DefaultRetryPolicy:其 8 次尝试、退避上限 30s,且带最终一致性模式
 // (9 次、上限 45s)——大批量删除里 worker 一旦触发就长睡,吞吐塌方;
 // 这里收紧为 5 次、上限 3s、关掉最终一致性,单条最坏 ~13s 后放行不拖全场。
 var bulkRetryPolicy = common.NewRetryPolicyWithOptions(
 	common.ReplaceWithValuesFromRetryPolicy(common.DefaultRetryPolicyWithoutEventualConsistency()),
 	common.WithMaximumNumberAttempts(5),
 	common.WithExponentialBackoff(3*time.Second, 2.0),
 )
 func (c *RealClient) osClient(cred Credentials, region string) (objectstorage.ObjectStorageClient, error) {
 	oc, err := objectstorage.NewObjectStorageClientWithConfigurationProvider(provider(cred))
 	if err != nil {
 		return oc, fmt.Errorf("new object storage client: %w", err)
 	}
 	applyProxy(&oc.BaseClient, cred)
 	if region != "" {
 		oc.SetRegion(normalizeRegion(region))
 	}
 	return oc, nil
 }
 // GetObjectStorageNamespace 实现 Client:租户 namespace(全租户唯一,常量语义),
 // 首次回源后按 tenancy 进程内缓存;此前每个对象存储操作都远程取一次,
 // 经代理链路时白付一整次冷连接往返。并发首次可能重复回源,结果相同无害。
 func (c *RealClient) GetObjectStorageNamespace(ctx context.Context, cred Credentials, region string) (string, error) {
 	if v, ok := c.namespaces.Load(cred.TenancyOCID); ok {
 		return v.(string), nil
 	}
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return "", err
 	}
 	resp, err := oc.GetNamespace(ctx, objectstorage.GetNamespaceRequest{})
 	if err != nil {
 		return "", fmt.Errorf("get namespace: %w", err)
 	}
 	if cred.TenancyOCID != "" {
 		c.namespaces.Store(cred.TenancyOCID, deref(resp.Value))
 	}
 	return deref(resp.Value), nil
 }
 // ListBuckets 实现 Client:列出指定 compartment 下的桶并逐个补全用量(空为生效 compartment)。
 func (c *RealClient) ListBuckets(ctx context.Context, cred Credentials, region, compartmentID string) ([]Bucket, error) {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return nil, err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return nil, err
 	}
 	resp, err := oc.ListBuckets(ctx, objectstorage.ListBucketsRequest{
 		NamespaceName: &ns,
 		CompartmentId: hostCompartment(cred, compartmentID),
 	})
 	if err != nil {
 		return nil, fmt.Errorf("list buckets: %w", err)
 	}
 	out := make([]Bucket, 0, len(resp.Items))
 	for _, it := range resp.Items {
 		out = append(out, c.bucketDetail(ctx, oc, ns, deref(it.Name)))
 	}
 	return out, nil
 }
 // bucketDetail 取单桶详情;失败时退化为只有名字的摘要,不拖垮列表。
 func (c *RealClient) bucketDetail(ctx context.Context, oc objectstorage.ObjectStorageClient, ns, name string) Bucket {
 	resp, err := oc.GetBucket(ctx, objectstorage.GetBucketRequest{
 		NamespaceName: &ns,
 		BucketName:    &name,
 		Fields:        []objectstorage.GetBucketFieldsEnum{"approximateCount", "approximateSize"},
 	})
 	if err != nil {
 		return Bucket{Name: name, Namespace: ns}
 	}
 	b := Bucket{
 		Name:             name,
 		Namespace:        ns,
 		Visibility:       string(resp.PublicAccessType),
 		StorageTier:      string(resp.StorageTier),
 		VersioningOn:     resp.Versioning == objectstorage.BucketVersioningEnabled,
 		ApproximateCount: derefI64(resp.ApproximateCount),
 		ApproximateSize:  derefI64(resp.ApproximateSize),
 	}
 	if resp.TimeCreated != nil {
 		b.TimeCreated = &resp.TimeCreated.Time
 	}
 	return b
 }
 func derefI64(p *int64) int64 {
 	if p != nil {
 		return *p
 	}
 	return 0
 }
 // CreateBucket 实现 Client。
 func (c *RealClient) CreateBucket(ctx context.Context, cred Credentials, region string, in CreateBucketInput) (Bucket, error) {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return Bucket{}, err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return Bucket{}, err
 	}
 	details := objectstorage.CreateBucketDetails{
 		Name:             &in.Name,
 		CompartmentId:    hostCompartment(cred, in.CompartmentID),
 		PublicAccessType: objectstorage.CreateBucketDetailsPublicAccessTypeNopublicaccess,
 		StorageTier:      objectstorage.CreateBucketDetailsStorageTierStandard,
 	}
 	if in.PublicRead {
 		details.PublicAccessType = objectstorage.CreateBucketDetailsPublicAccessTypeObjectread
 	}
 	if strings.EqualFold(in.StorageTier, "Archive") {
 		details.StorageTier = objectstorage.CreateBucketDetailsStorageTierArchive
 	}
 	if in.VersioningOn {
 		details.Versioning = objectstorage.CreateBucketDetailsVersioningEnabled
 	}
 	if _, err := oc.CreateBucket(ctx, objectstorage.CreateBucketRequest{
 		NamespaceName: &ns, CreateBucketDetails: details,
 	}); err != nil {
 		return Bucket{}, fmt.Errorf("create bucket: %w", err)
 	}
 	return c.bucketDetail(ctx, oc, ns, in.Name), nil
 }
 // UpdateBucket 实现 Client:改可见性 / 版本控制。
 func (c *RealClient) UpdateBucket(ctx context.Context, cred Credentials, region, name string, in UpdateBucketInput) (Bucket, error) {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return Bucket{}, err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return Bucket{}, err
 	}
 	details := objectstorage.UpdateBucketDetails{}
 	if in.PublicRead != nil {
 		details.PublicAccessType = objectstorage.UpdateBucketDetailsPublicAccessTypeNopublicaccess
 		if *in.PublicRead {
 			details.PublicAccessType = objectstorage.UpdateBucketDetailsPublicAccessTypeObjectread
 		}
 	}
 	if in.VersioningOn != nil {
 		details.Versioning = objectstorage.UpdateBucketDetailsVersioningSuspended
 		if *in.VersioningOn {
 			details.Versioning = objectstorage.UpdateBucketDetailsVersioningEnabled
 		}
 	}
 	if _, err := oc.UpdateBucket(ctx, objectstorage.UpdateBucketRequest{
 		NamespaceName: &ns, BucketName: &name, UpdateBucketDetails: details,
 	}); err != nil {
 		return Bucket{}, fmt.Errorf("update bucket: %w", err)
 	}
 	return c.bucketDetail(ctx, oc, ns, name), nil
 }
 // DeleteBucket 实现 Client:仅空桶可删,OCI 拒绝非空桶。
 // ErrBucketNotEmpty 表示桶内仍有对象 / 历史版本 / 未完成分片上传,OCI 拒绝删除。
 var ErrBucketNotEmpty = errors.New("bucket not empty")
 func (c *RealClient) DeleteBucket(ctx context.Context, cred Credentials, region, name string) error {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return err
 	}
 	if _, err := oc.DeleteBucket(ctx, objectstorage.DeleteBucketRequest{
 		NamespaceName: &ns, BucketName: &name,
 	}); err != nil {
 		if isBucketNotEmptyErr(err) {
 			return fmt.Errorf("delete bucket %s: %w", name, ErrBucketNotEmpty)
 		}
 		return fmt.Errorf("delete bucket: %w", err)
 	}
 	return nil
 }
 // AbortAllMultipartUploads 实现 Client:中止桶内全部未完成分片上传并删除已传分片。
 // 未完成分片会让「已清空」的桶仍以非空拒绝删除;404 视为桶已不存在,幂等成功。
 func (c *RealClient) AbortAllMultipartUploads(ctx context.Context, cred Credentials, region, bucket string) error {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return err
 	}
 	for page := (*string)(nil); ; {
 		resp, err := oc.ListMultipartUploads(ctx, objectstorage.ListMultipartUploadsRequest{
 			NamespaceName: &ns, BucketName: &bucket, Page: page,
 		})
 		if err != nil {
 			return ignoreNotFound(fmt.Errorf("list multipart uploads: %w", err))
 		}
 		for _, up := range resp.Items {
 			if _, err := oc.AbortMultipartUpload(ctx, objectstorage.AbortMultipartUploadRequest{
 				NamespaceName: &ns, BucketName: &bucket, ObjectName: up.Object, UploadId: up.UploadId,
 			}); err != nil {
 				if err := ignoreNotFound(fmt.Errorf("abort multipart upload: %w", err)); err != nil {
 					return err
 				}
 			}
 		}
 		if page = resp.OpcNextPage; page == nil {
 			return nil
 		}
 	}
 }
 // ignoreNotFound 把上游 404 归一为 nil(资源已不存在,操作目的已达成)。
 func ignoreNotFound(err error) error {
 	var se common.ServiceError
 	if errors.As(err, &se) && se.GetHTTPStatusCode() == 404 {
 		return nil
 	}
 	return err
 }
 // isBucketNotEmptyErr 识别「桶非空」类删除拒绝:对象/版本/分片报 BucketNotEmpty,
 // 仅剩活跃 PAR 时 OCI 报 409 且消息为 Active Preauthenticated Requests still exist,
 // 两者都可经后台清空(对象版本+PAR)后重删。
 func isBucketNotEmptyErr(err error) bool {
 	var se common.ServiceError
 	if !errors.As(err, &se) {
 		return false
 	}
 	if se.GetCode() == "BucketNotEmpty" {
 		return true
 	}
 	return se.GetHTTPStatusCode() == 409 &&
 		strings.Contains(se.GetMessage(), "Preauthenticated Request")
 }
 // ObjectVersion 是对象版本摘要,清空桶时逐版本删除用。
 type ObjectVersion struct {
 	Name      string `json:"name"`
 	VersionID string `json:"versionId"`
 }
 // ListObjectVersions 实现 Client:分页列出全部对象版本(未开版本控制的桶返回当前版本)。
 func (c *RealClient) ListObjectVersions(ctx context.Context, cred Credentials, region, bucket, page string) ([]ObjectVersion, string, error) {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return nil, "", err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return nil, "", err
 	}
 	req := objectstorage.ListObjectVersionsRequest{
 		NamespaceName: &ns, BucketName: &bucket, Limit: common.Int(1000),
 	}
 	if page != "" {
 		req.Page = &page
 	}
 	resp, err := oc.ListObjectVersions(ctx, req)
 	if err != nil {
 		return nil, "", fmt.Errorf("list object versions: %w", err)
 	}
 	out := make([]ObjectVersion, 0, len(resp.Items))
 	for _, it := range resp.Items {
 		out = append(out, ObjectVersion{Name: deref(it.Name), VersionID: deref(it.VersionId)})
 	}
 	return out, deref(resp.OpcNextPage), nil
 }
 // DeleteObjectVersion 实现 Client:删除指定版本(versionID 空为当前版本)。
 func (c *RealClient) DeleteObjectVersion(ctx context.Context, cred Credentials, region, bucket, object, versionID string) error {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return err
 	}
 	req := objectstorage.DeleteObjectRequest{
 		NamespaceName: &ns, BucketName: &bucket, ObjectName: &object,
 		RequestMetadata: common.RequestMetadata{RetryPolicy: &bulkRetryPolicy},
 	}
 	if versionID != "" {
 		req.VersionId = &versionID
 	}
 	if _, err := oc.DeleteObject(ctx, req); err != nil {
 		return fmt.Errorf("delete object version: %w", err)
 	}
 	return nil
 }
 // ListObjects 实现 Client:delimiter="/" 前缀模式;startWith 为上页游标。
 func (c *RealClient) ListObjects(ctx context.Context, cred Credentials, region, bucket, prefix, startWith string, limit int) (ListObjectsResult, error) {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return ListObjectsResult{}, err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return ListObjectsResult{}, err
 	}
 	if limit <= 0 || limit > 500 {
 		limit = 100
 	}
 	req := objectstorage.ListObjectsRequest{
 		NamespaceName: &ns,
 		BucketName:    &bucket,
 		Delimiter:     common.String("/"),
 		Limit:         &limit,
 		Fields:        common.String("name,size,timeModified,storageTier,archivalState"),
 	}
 	if prefix != "" {
 		req.Prefix = &prefix
 	}
 	if startWith != "" {
 		req.Start = &startWith
 	}
 	resp, err := oc.ListObjects(ctx, req)
 	if err != nil {
 		return ListObjectsResult{}, fmt.Errorf("list objects: %w", err)
 	}
 	return toListObjectsResult(resp), nil
 }
 func toListObjectsResult(resp objectstorage.ListObjectsResponse) ListObjectsResult {
 	out := ListObjectsResult{
 		Objects:       make([]ObjectSummary, 0, len(resp.Objects)),
 		Prefixes:      orEmpty(resp.Prefixes),
 		NextStartWith: deref(resp.NextStartWith),
 	}
 	for _, o := range resp.Objects {
 		item := ObjectSummary{
 			Name:          deref(o.Name),
 			Size:          derefI64(o.Size),
 			StorageTier:   string(o.StorageTier),
 			ArchivalState: string(o.ArchivalState),
 		}
 		if o.TimeModified != nil {
 			item.TimeModified = &o.TimeModified.Time
 		}
 		out.Objects = append(out.Objects, item)
 	}
 	return out
 }
 // DeleteObject 实现 Client。
 func (c *RealClient) DeleteObject(ctx context.Context, cred Credentials, region, bucket, object string) error {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return err
 	}
 	if _, err := oc.DeleteObject(ctx, objectstorage.DeleteObjectRequest{
 		NamespaceName: &ns, BucketName: &bucket, ObjectName: &object,
 	}); err != nil {
 		return fmt.Errorf("delete object: %w", err)
 	}
 	return nil
 }
 // RenameObject 实现 Client:OCI 原生重命名(同桶内)。
 func (c *RealClient) RenameObject(ctx context.Context, cred Credentials, region, bucket, src, dst string) error {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return err
 	}
 	if _, err := oc.RenameObject(ctx, objectstorage.RenameObjectRequest{
 		NamespaceName: &ns,
 		BucketName:    &bucket,
 		RenameObjectDetails: objectstorage.RenameObjectDetails{
 			SourceName: &src,
 			NewName:    &dst,
 		},
 	}); err != nil {
 		return fmt.Errorf("rename object: %w", err)
 	}
 	return nil
 }
 // RestoreObject 实现 Client:Archive 对象取回,hours 为可下载时长(默认 24)。
 func (c *RealClient) RestoreObject(ctx context.Context, cred Credentials, region, bucket, object string, hours int) error {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return err
 	}
 	req := objectstorage.RestoreObjectsRequest{
 		NamespaceName: &ns,
 		BucketName:    &bucket,
 		RestoreObjectsDetails: objectstorage.RestoreObjectsDetails{
 			ObjectName: &object,
 		},
 	}
 	if hours > 0 {
 		req.RestoreObjectsDetails.Hours = &hours
 	}
 	if _, err := oc.RestoreObjects(ctx, req); err != nil {
 		return fmt.Errorf("restore object: %w", err)
 	}
 	return nil
 }
 // HeadObject 实现 Client:对象元数据。
 func (c *RealClient) HeadObject(ctx context.Context, cred Credentials, region, bucket, object string) (ObjectDetail, error) {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return ObjectDetail{}, err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return ObjectDetail{}, err
 	}
 	resp, err := oc.HeadObject(ctx, objectstorage.HeadObjectRequest{
 		NamespaceName: &ns, BucketName: &bucket, ObjectName: &object,
 	})
 	if err != nil {
 		return ObjectDetail{}, fmt.Errorf("head object: %w", err)
 	}
 	d := ObjectDetail{
 		Name:          object,
 		Size:          derefI64(resp.ContentLength),
 		ContentType:   deref(resp.ContentType),
 		Etag:          deref(resp.ETag),
 		ContentMd5:    deref(resp.ContentMd5),
 		StorageTier:   string(resp.StorageTier),
 		ArchivalState: string(resp.ArchivalState),
 		Metadata:      resp.OpcMeta,
 	}
 	if resp.LastModified != nil {
 		d.TimeModified = &resp.LastModified.Time
 	}
 	return d, nil
 }
 // GetObject 实现 Client:整体读入对象内容;超过 maxBytes 返回 ErrObjectTooLarge。
 func (c *RealClient) GetObject(ctx context.Context, cred Credentials, region, bucket, object string, maxBytes int64) (ObjectContent, error) {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return ObjectContent{}, err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return ObjectContent{}, err
 	}
 	resp, err := oc.GetObject(ctx, objectstorage.GetObjectRequest{
 		NamespaceName: &ns, BucketName: &bucket, ObjectName: &object,
 	})
 	if err != nil {
 		return ObjectContent{}, fmt.Errorf("get object: %w", err)
 	}
 	defer resp.Content.Close()
 	if derefI64(resp.ContentLength) > maxBytes {
 		return ObjectContent{}, fmt.Errorf("get object %s (%d bytes): %w", object, derefI64(resp.ContentLength), ErrObjectTooLarge)
 	}
 	data, err := io.ReadAll(io.LimitReader(resp.Content, maxBytes+1))
 	if err != nil {
 		return ObjectContent{}, fmt.Errorf("read object body: %w", err)
 	}
 	if int64(len(data)) > maxBytes {
 		return ObjectContent{}, fmt.Errorf("get object %s: %w", object, ErrObjectTooLarge)
 	}
 	return ObjectContent{Data: data, ContentType: deref(resp.ContentType), Etag: deref(resp.ETag)}, nil
 }
 // PutObject 实现 Client:整体写入对象;ifMatch 非空时作为 If-Match 条件,
 // 不匹配由 OCI 返回 412(经 ServiceError 透出)。返回新 ETag。
 func (c *RealClient) PutObject(ctx context.Context, cred Credentials, region, bucket, object string, data []byte, contentType, ifMatch string) (string, error) {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return "", err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return "", err
 	}
 	length := int64(len(data))
 	req := objectstorage.PutObjectRequest{
 		NamespaceName: &ns, BucketName: &bucket, ObjectName: &object,
 		ContentLength: &length,
 		PutObjectBody: io.NopCloser(bytes.NewReader(data)),
 	}
 	if contentType != "" {
 		req.ContentType = &contentType
 	}
 	if ifMatch != "" {
 		req.IfMatch = &ifMatch
 	}
 	resp, err := oc.PutObject(ctx, req)
 	if err != nil {
 		return "", fmt.Errorf("put object: %w", err)
 	}
 	return deref(resp.ETag), nil
 }
 // CreatePAR 实现 Client:签发预签名请求并拼出完整 URL(仅此时可得)。
 func (c *RealClient) CreatePAR(ctx context.Context, cred Credentials, region, bucket string, in CreatePARInput) (PAR, error) {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return PAR{}, err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return PAR{}, err
 	}
 	details := createPARDetails(in, time.Now())
 	resp, err := oc.CreatePreauthenticatedRequest(ctx, objectstorage.CreatePreauthenticatedRequestRequest{
 		NamespaceName: &ns, BucketName: &bucket, CreatePreauthenticatedRequestDetails: details,
 	})
 	if err != nil {
 		return PAR{}, fmt.Errorf("create par: %w", err)
 	}
 	return toPAR(resp.PreauthenticatedRequest, oc.Endpoint()), nil
 }
 // createPARDetails 集中组装 SDK 请求,避免 accessType 与桶列举权限组合回归。
 func createPARDetails(in CreatePARInput, now time.Time) objectstorage.CreatePreauthenticatedRequestDetails {
 	hours := in.ExpiresHours
 	if hours <= 0 {
 		hours = 24
 	}
 	details := objectstorage.CreatePreauthenticatedRequestDetails{
 		Name:        &in.Name,
 		AccessType:  objectstorage.CreatePreauthenticatedRequestDetailsAccessTypeEnum(in.AccessType),
 		TimeExpires: &common.SDKTime{Time: now.Add(time.Duration(hours) * time.Hour)},
 	}
 	if in.ObjectName != "" {
 		details.ObjectName = &in.ObjectName
 	}
 	if in.AccessType == "AnyObjectRead" || in.AccessType == "AnyObjectReadWrite" {
 		details.BucketListingAction = objectstorage.PreauthenticatedRequestBucketListingActionListobjects
 	}
 	return details
 }
 func toPAR(p objectstorage.PreauthenticatedRequest, endpoint string) PAR {
 	out := PAR{
 		ID:         deref(p.Id),
 		Name:       deref(p.Name),
 		ObjectName: deref(p.ObjectName),
 		AccessType: string(p.AccessType),
 	}
 	if p.AccessUri != nil {
 		out.FullURL = strings.TrimSuffix(endpoint, "/") + *p.AccessUri
 	}
 	if p.TimeExpires != nil {
 		out.TimeExpires = &p.TimeExpires.Time
 	}
 	if p.TimeCreated != nil {
 		out.TimeCreated = &p.TimeCreated.Time
 	}
 	return out
 }
 // ListPARsPage 实现 Client:单页列出桶内预签名请求(摘要不含 URL),
 // 返回下一页游标,空串表示已到末页;limit ≤0 时用 OCI 默认页大小。
 func (c *RealClient) ListPARsPage(ctx context.Context, cred Credentials, region, bucket, page string, limit int) ([]PAR, string, error) {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return nil, "", err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return nil, "", err
 	}
 	req := objectstorage.ListPreauthenticatedRequestsRequest{NamespaceName: &ns, BucketName: &bucket}
 	if limit > 0 {
 		req.Limit = common.Int(limit)
 	}
 	if page != "" {
 		req.Page = &page
 	}
 	resp, err := oc.ListPreauthenticatedRequests(ctx, req)
 	if err != nil {
 		return nil, "", fmt.Errorf("list pars: %w", err)
 	}
 	out := make([]PAR, 0, len(resp.Items))
 	for _, it := range resp.Items {
 		out = append(out, summaryPAR(it))
 	}
 	return out, deref(resp.OpcNextPage), nil
 }
 // ListPARs 实现 Client:翻页列出桶内全部有效预签名请求(清空/全部删除用)。
 func (c *RealClient) ListPARs(ctx context.Context, cred Credentials, region, bucket string) ([]PAR, error) {
 	out := make([]PAR, 0, 16)
 	page := ""
 	for {
 		items, next, err := c.ListPARsPage(ctx, cred, region, bucket, page, 1000)
 		if err != nil {
 			return nil, err
 		}
 		out = append(out, items...)
 		if next == "" {
 			return out, nil
 		}
 		page = next
 	}
 }
 func summaryPAR(p objectstorage.PreauthenticatedRequestSummary) PAR {
 	out := PAR{
 		ID:         deref(p.Id),
 		Name:       deref(p.Name),
 		ObjectName: deref(p.ObjectName),
 		AccessType: string(p.AccessType),
 	}
 	if p.TimeExpires != nil {
 		out.TimeExpires = &p.TimeExpires.Time
 	}
 	if p.TimeCreated != nil {
 		out.TimeCreated = &p.TimeCreated.Time
 	}
 	return out
 }
 // DeletePAR 实现 Client:撤销预签名请求,链接立即失效。
 func (c *RealClient) DeletePAR(ctx context.Context, cred Credentials, region, bucket, parID string) error {
 	oc, err := c.osClient(cred, region)
 	if err != nil {
 		return err
 	}
 	ns, err := c.GetObjectStorageNamespace(ctx, cred, region)
 	if err != nil {
 		return err
 	}
 	if _, err := oc.DeletePreauthenticatedRequest(ctx, objectstorage.DeletePreauthenticatedRequestRequest{
 		NamespaceName: &ns, BucketName: &bucket, ParId: &parID,
 		RequestMetadata: common.RequestMetadata{RetryPolicy: &bulkRetryPolicy},
 	}); err != nil {
 		return fmt.Errorf("delete par: %w", err)
 	}
 	return nil
 }
@@ -0,0 +1,76 @@
 package oci
 import (
 	"context"
 	"encoding/json"
 	"strings"
 	"testing"
 	"time"
 )
 // namespace 为租户常量:缓存命中时直接返回,不构造客户端、不发起远程调用
 // (凭据为空也能取到,证明未走回源路径)。
 func TestGetObjectStorageNamespaceCached(t *testing.T) {
 	c := NewClient()
 	tests := []struct {
 		name    string
 		tenancy string
 		seed    string
 	}{
 		{name: "缓存命中直接返回", tenancy: "ocid1.tenancy.oc1..aaaa", seed: "ns-a"},
 		{name: "不同租户各取各的", tenancy: "ocid1.tenancy.oc1..bbbb", seed: "ns-b"},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			c.namespaces.Store(tt.tenancy, tt.seed)
 			got, err := c.GetObjectStorageNamespace(context.Background(), Credentials{TenancyOCID: tt.tenancy}, "us-ashburn-1")
 			if err != nil || got != tt.seed {
 				t.Fatalf("GetObjectStorageNamespace = %q, %v; want %q", got, err, tt.seed)
 			}
 		})
 	}
 }
 func TestCreatePARDetailsBucketListingAction(t *testing.T) {
 	cases := []struct {
 		accessType string
 		wantList   bool
 	}{
 		{"AnyObjectRead", true},
 		{"AnyObjectReadWrite", true},
 		{"AnyObjectWrite", false},
 		{"ObjectRead", false},
 	}
 	for _, tc := range cases {
 		details := createPARDetails(CreatePARInput{AccessType: tc.accessType, ExpiresHours: 1}, time.Unix(100, 0))
 		gotList := string(details.BucketListingAction) == "ListObjects"
 		if gotList != tc.wantList {
 			t.Errorf("%s listing = %q, wantList %v", tc.accessType, details.BucketListingAction, tc.wantList)
 		}
 		wire, err := json.Marshal(details)
 		if err != nil {
 			t.Fatalf("marshal %s details: %v", tc.accessType, err)
 		}
 		gotWireList := strings.Contains(string(wire), `"bucketListingAction":"ListObjects"`)
 		if gotWireList != tc.wantList {
 			t.Errorf("%s wire = %s, wantList %v", tc.accessType, wire, tc.wantList)
 		}
 	}
 }
 func TestCreatePARDetailsExpirationAndObject(t *testing.T) {
 	now := time.Date(2026, 7, 22, 12, 0, 0, 0, time.UTC)
 	details := createPARDetails(CreatePARInput{
 		Name: "share", ObjectName: "folder/a.txt", AccessType: "ObjectRead", ExpiresHours: 48,
 	}, now)
 	if got, want := details.TimeExpires.Time, now.Add(48*time.Hour); !got.Equal(want) {
 		t.Errorf("TimeExpires = %v, want %v", got, want)
 	}
 	if details.ObjectName == nil || *details.ObjectName != "folder/a.txt" {
 		t.Errorf("ObjectName = %v, want folder/a.txt", details.ObjectName)
 	}
 	defaults := createPARDetails(CreatePARInput{AccessType: "ObjectRead"}, now)
 	if got, want := defaults.TimeExpires.Time, now.Add(24*time.Hour); !got.Equal(want) {
 		t.Errorf("default TimeExpires = %v, want %v", got, want)
 	}
 }
@@ -5,6 +5,7 @@ import (
 	"net"
 	"net/http"
 	"net/url"
 	"sync"
 	"time"
 	"golang.org/x/net/proxy"
@@ -31,6 +32,20 @@ const (
 	proxyTLSHandshakeTimeout = 10 * time.Second
 )
 // 连接池参数:PerHost 须 > 批量删除并发数(service 层 16)——并发拨号竞速时
 // Transport 会投机新建连接,池上限过紧会让这些连接用一次即被丢弃(churn);
 // IdleConnTimeout 显式关闭空闲连接(零值=永不关,只能等远端 ~65s 断开,连接会堆积)。
 const (
 	proxyMaxIdleConns        = 128
 	proxyMaxIdleConnsPerHost = 32
 	proxyIdleConnTimeout     = 90 * time.Second
 )
 // proxyClients 按代理配置复用 http.Client。SDK client 每次操作新建,
 // 若 Transport 也随之新建则连接零复用:每个请求都要付完整的
 // TCP+SOCKS/CONNECT+TLS 握手(经代理 3+ 个 RTT),批量操作被拖到分钟级。
 var proxyClients sync.Map // ProxySpec(值) → *http.Client
 // applyProxy 在 SDK client 构造后统一挂出站代理;未关联代理时不动默认配置。
 // 所有 New*ClientWithConfigurationProvider 调用点构造成功后都必须经过这里。
 func applyProxy(base *common.BaseClient, cred Credentials) {
@@ -39,16 +54,21 @@ func applyProxy(base *common.BaseClient, cred Credentials) {
 	}
 }
-// proxyHTTPClient 按代理配置构造 http.Client;nil 或非法配置返回 nil(走直连)。
+// proxyHTTPClient 按代理配置取共享 http.Client;nil 或非法配置返回 nil(走直连)。
 // 同配置复用同一实例(连接池随之复用);调用方只可包装、不得改写其字段。
 func proxyHTTPClient(p *ProxySpec) *http.Client {
 	if p == nil || p.Host == "" || p.Port <= 0 {
 		return nil
 	}
 	if v, ok := proxyClients.Load(*p); ok {
 		return v.(*http.Client)
 	}
 	tr := transportFor(p)
 	if tr == nil {
 		return nil
 	}
-	return &http.Client{Transport: tr, Timeout: proxyClientTimeout}
+	v, _ := proxyClients.LoadOrStore(*p, &http.Client{Transport: tr, Timeout: proxyClientTimeout})
 	return v.(*http.Client)
 }
 // HTTPClientFor 供面板自身请求(如代理出口地理探测)复用与租户 SDK
@@ -57,6 +77,16 @@ func HTTPClientFor(p *ProxySpec) *http.Client {
 	return proxyHTTPClient(p)
 }
 // pooledTransport 连接池参数统一的 Transport 骨架;阶段超时见常量注释。
 func pooledTransport() *http.Transport {
 	return &http.Transport{
 		TLSHandshakeTimeout: proxyTLSHandshakeTimeout,
 		MaxIdleConns:        proxyMaxIdleConns,
 		MaxIdleConnsPerHost: proxyMaxIdleConnsPerHost,
 		IdleConnTimeout:     proxyIdleConnTimeout,
 	}
 }
 // transportFor 构造代理 Transport:http / https 走 CONNECT,socks5 走拨号器。
 func transportFor(p *ProxySpec) *http.Transport {
 	addr := fmt.Sprintf("%s:%d", p.Host, p.Port)
@@ -66,11 +96,10 @@ func transportFor(p *ProxySpec) *http.Transport {
 		if p.Username != "" {
 			u.User = url.UserPassword(p.Username, p.Password)
 		}
-		return &http.Transport{
+		tr := pooledTransport()
-			Proxy:               http.ProxyURL(u),
+		tr.Proxy = http.ProxyURL(u)
-			DialContext:         dialer.DialContext,
+		tr.DialContext = dialer.DialContext
-			TLSHandshakeTimeout: proxyTLSHandshakeTimeout,
+		return tr
 		}
 	}
 	var auth *proxy.Auth
 	if p.Username != "" {
@@ -84,8 +113,7 @@ func transportFor(p *ProxySpec) *http.Transport {
 	if !ok {
 		return nil
 	}
-	return &http.Transport{
+	tr := pooledTransport()
-		DialContext:         cd.DialContext,
+	tr.DialContext = cd.DialContext
-		TLSHandshakeTimeout: proxyTLSHandshakeTimeout,
+	return tr
 	}
 }
@@ -29,6 +29,63 @@ func TestTransportForStageTimeouts(t *testing.T) {
 			if tr.TLSHandshakeTimeout != proxyTLSHandshakeTimeout {
 				t.Fatalf("TLSHandshakeTimeout = %v, 期望 %v", tr.TLSHandshakeTimeout, proxyTLSHandshakeTimeout)
 			}
 			if tr.MaxIdleConnsPerHost != proxyMaxIdleConnsPerHost || tr.IdleConnTimeout != proxyIdleConnTimeout {
 				t.Fatalf("连接池参数未设置: PerHost=%d IdleTimeout=%v", tr.MaxIdleConnsPerHost, tr.IdleConnTimeout)
 			}
 		})
 	}
 }
 func TestProxyHTTPClientReuse(t *testing.T) {
 	tests := []struct {
 		name     string
 		a, b     *ProxySpec
 		wantSame bool
 	}{
 		{
 			name:     "同配置复用同一实例",
 			a:        &ProxySpec{Type: "socks5", Host: "10.0.0.1", Port: 1080},
 			b:        &ProxySpec{Type: "socks5", Host: "10.0.0.1", Port: 1080},
 			wantSame: true,
 		},
 		{
 			name: "不同配置各自实例",
 			a:    &ProxySpec{Type: "socks5", Host: "10.0.0.1", Port: 1080},
 			b:    &ProxySpec{Type: "socks5", Host: "10.0.0.2", Port: 1080},
 		},
 		{
 			name: "同地址不同凭据不复用",
 			a:    &ProxySpec{Type: "socks5", Host: "10.0.0.1", Port: 1080, Username: "u1", Password: "p1"},
 			b:    &ProxySpec{Type: "socks5", Host: "10.0.0.1", Port: 1080, Username: "u2", Password: "p2"},
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			ca, cb := proxyHTTPClient(tt.a), proxyHTTPClient(tt.b)
 			if ca == nil || cb == nil {
 				t.Fatal("proxyHTTPClient 返回 nil")
 			}
 			if (ca == cb) != tt.wantSame {
 				t.Fatalf("实例复用 = %v, 期望 %v", ca == cb, tt.wantSame)
 			}
 		})
 	}
 }
 func TestProxyHTTPClientInvalidSpec(t *testing.T) {
 	tests := []struct {
 		name string
 		spec *ProxySpec
 	}{
 		{name: "nil 配置", spec: nil},
 		{name: "缺 host", spec: &ProxySpec{Type: "socks5", Port: 1080}},
 		{name: "非法端口", spec: &ProxySpec{Type: "socks5", Host: "10.0.0.1"}},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			if c := proxyHTTPClient(tt.spec); c != nil {
 				t.Fatalf("非法配置应返回 nil,得到 %v", c)
 			}
 		})
 	}
 }
@@ -3,7 +3,9 @@ package oci
 import (
 	"context"
 	"fmt"
 	"time"
 	"github.com/oracle/oci-go-sdk/v65/common"
 	"github.com/oracle/oci-go-sdk/v65/core"
 )
@@ -62,7 +64,7 @@ func lookupPublicIP(ctx context.Context, vn core.VirtualNetworkClient, privateIP
 }
 // ChangeInstancePublicIP 实现 Client：为实例主 VNIC 主私有 IP 更换临时公网 IP。
-// 删除旧的临时公网 IP 再分配新的；若旧地址是保留 IP（RESERVED），拒绝操作。
+// 旧临时 IP 删除、旧保留 IP 自动解绑（资源保留在账户），随后分配新的临时 IP。
 func (c *RealClient) ChangeInstancePublicIP(ctx context.Context, cred Credentials, region, instanceID string) (string, error) {
 	vn, err := c.vcnClient(cred, region)
 	if err != nil {
@@ -72,13 +74,26 @@ func (c *RealClient) ChangeInstancePublicIP(ctx context.Context, cred Credential
 	if err != nil {
 		return "", err
 	}
-	if existing := lookupPublicIP(ctx, vn, priv.Id); existing != nil {
+	return replaceEphemeralPublicIP(ctx, vn, cred, priv)
-		if existing.Lifetime == core.PublicIpLifetimeReserved {
+}
-			return "", fmt.Errorf("change public ip: private ip has a reserved public ip, release it manually")
+
-		}
+// ChangeVnicPublicIP 实现 Client：为指定 VNIC 的主私有 IP 更换临时公网 IP(次要网卡场景)。
-		if _, err := vn.DeletePublicIp(ctx, core.DeletePublicIpRequest{PublicIpId: existing.Id}); err != nil {
+func (c *RealClient) ChangeVnicPublicIP(ctx context.Context, cred Credentials, region, vnicID string) (string, error) {
-			return "", fmt.Errorf("delete old public ip: %w", err)
+	vn, err := c.vcnClient(cred, region)
-		}
+	if err != nil {
 		return "", err
 	}
 	priv, err := vnicPrimaryPrivateIP(ctx, vn, vnicID)
 	if err != nil {
 		return "", err
 	}
 	return replaceEphemeralPublicIP(ctx, vn, cred, priv)
 }
 // replaceEphemeralPublicIP 释放私有 IP 上现有公网 IP（临时删除、保留解绑）并分配新临时 IP。
 func replaceEphemeralPublicIP(ctx context.Context, vn core.VirtualNetworkClient, cred Credentials, priv core.PrivateIp) (string, error) {
 	if err := detachExistingPublicIP(ctx, vn, priv.Id); err != nil {
 		return "", err
 	}
 	// OCI 要求临时公网 IP 与其私有 IP 同 compartment，故不能用生效 compartment
 	resp, err := vn.CreatePublicIp(ctx, core.CreatePublicIpRequest{
@@ -94,6 +109,45 @@ func (c *RealClient) ChangeInstancePublicIP(ctx context.Context, cred Credential
 	return deref(resp.IpAddress), nil
 }
 // detachExistingPublicIP 释放私有 IP 上已绑定的公网 IP：
 // 临时 IP 直接删除；保留 IP 仅解绑（回到未分配状态，资源不删除）。
 func detachExistingPublicIP(ctx context.Context, vn core.VirtualNetworkClient, privateIPID *string) error {
 	existing := lookupPublicIP(ctx, vn, privateIPID)
 	if existing == nil {
 		return nil
 	}
 	if existing.Lifetime != core.PublicIpLifetimeReserved {
 		if _, err := vn.DeletePublicIp(ctx, core.DeletePublicIpRequest{PublicIpId: existing.Id}); err != nil {
 			return fmt.Errorf("delete old public ip: %w", err)
 		}
 		return nil
 	}
 	_, err := vn.UpdatePublicIp(ctx, core.UpdatePublicIpRequest{
 		PublicIpId:            existing.Id,
 		UpdatePublicIpDetails: core.UpdatePublicIpDetails{PrivateIpId: common.String("")},
 	})
 	if err != nil {
 		return fmt.Errorf("unassign reserved public ip: %w", err)
 	}
 	waitPublicIPDetached(ctx, vn, privateIPID)
 	return nil
 }
 // waitPublicIPDetached 短轮询等私有 IP 上的旧绑定释放；保留 IP 解绑为异步操作，
 // 立即创建新临时 IP 可能撞上未释放的旧绑定。超时不报错，交由后续创建操作反馈。
 func waitPublicIPDetached(ctx context.Context, vn core.VirtualNetworkClient, privateIPID *string) {
 	for i := 0; i < 10; i++ {
 		if lookupPublicIP(ctx, vn, privateIPID) == nil {
 			return
 		}
 		select {
 		case <-ctx.Done():
 			return
 		case <-time.After(500 * time.Millisecond):
 		}
 	}
 }
 // primaryVnic 返回实例的主 VNIC。
 func (c *RealClient) primaryVnic(ctx context.Context, cred Credentials, region, instanceID string) (core.Vnic, error) {
 	vnics, _, err := c.instanceVnics(ctx, cred, region, instanceID)
@@ -0,0 +1,197 @@
 package oci
 import (
 	"context"
 	"fmt"
 	"time"
 	"github.com/oracle/oci-go-sdk/v65/common"
 	"github.com/oracle/oci-go-sdk/v65/core"
 )
 // ReservedIP 是保留公网 IP 摘要；绑定目标尽力反查，失败时对应字段为空。
 type ReservedIP struct {
 	ID                   string     `json:"id"`
 	DisplayName          string     `json:"displayName"`
 	IPAddress            string     `json:"ipAddress"`
 	LifecycleState       string     `json:"lifecycleState"`
 	AssignedInstanceID   string     `json:"assignedInstanceId"`
 	AssignedInstanceName string     `json:"assignedInstanceName"`
 	TimeCreated          *time.Time `json:"timeCreated"`
 }
 // ListReservedIPs 实现 Client：列出区间内全部保留公网 IP（REGION 作用域）；
 // compartmentID 为空时用生效 compartment。
 func (c *RealClient) ListReservedIPs(ctx context.Context, cred Credentials, region, compartmentID string) ([]ReservedIP, error) {
 	vn, err := c.vcnClient(cred, region)
 	if err != nil {
 		return nil, err
 	}
 	cc, err := c.computeClient(cred, region)
 	if err != nil {
 		return nil, err
 	}
 	out := make([]ReservedIP, 0, 4)
 	var page *string
 	for {
 		resp, err := vn.ListPublicIps(ctx, core.ListPublicIpsRequest{
 			Scope:         core.ListPublicIpsScopeRegion,
 			Lifetime:      core.ListPublicIpsLifetimeReserved,
 			CompartmentId: hostCompartment(cred, compartmentID),
 			Page:          page,
 		})
 		if err != nil {
 			return nil, fmt.Errorf("list reserved ips: %w", err)
 		}
 		for i := range resp.Items {
 			out = append(out, c.toReservedIP(ctx, vn, cc, resp.Items[i]))
 		}
 		if resp.OpcNextPage == nil {
 			break
 		}
 		page = resp.OpcNextPage
 	}
 	return out, nil
 }
 // toReservedIP 转换 SDK 对象并尽力反查绑定的实例。
 func (c *RealClient) toReservedIP(ctx context.Context, vn core.VirtualNetworkClient, cc core.ComputeClient, p core.PublicIp) ReservedIP {
 	var created *time.Time
 	if p.TimeCreated != nil {
 		created = &p.TimeCreated.Time
 	}
 	r := ReservedIP{
 		ID:             deref(p.Id),
 		DisplayName:    deref(p.DisplayName),
 		IPAddress:      deref(p.IpAddress),
 		LifecycleState: string(p.LifecycleState),
 		TimeCreated:    created,
 	}
 	if p.AssignedEntityType == core.PublicIpAssignedEntityTypePrivateIp && p.AssignedEntityId != nil {
 		r.AssignedInstanceID, r.AssignedInstanceName = resolveIPAssignee(ctx, vn, cc, *p.AssignedEntityId)
 	}
 	return r
 }
 // resolveIPAssignee 由私有 IP 反查所属实例；任一步失败即放弃，不影响列表主体。
 func resolveIPAssignee(ctx context.Context, vn core.VirtualNetworkClient, cc core.ComputeClient, privateIPID string) (string, string) {
 	priv, err := vn.GetPrivateIp(ctx, core.GetPrivateIpRequest{PrivateIpId: &privateIPID})
 	if err != nil || priv.VnicId == nil {
 		return "", ""
 	}
 	atts, err := cc.ListVnicAttachments(ctx, core.ListVnicAttachmentsRequest{
 		CompartmentId: priv.CompartmentId,
 		VnicId:        priv.VnicId,
 	})
 	if err != nil || len(atts.Items) == 0 || atts.Items[0].InstanceId == nil {
 		return "", ""
 	}
 	instanceID := *atts.Items[0].InstanceId
 	inst, err := cc.GetInstance(ctx, core.GetInstanceRequest{InstanceId: &instanceID})
 	if err != nil {
 		return instanceID, ""
 	}
 	return instanceID, deref(inst.DisplayName)
 }
 // CreateReservedIP 实现 Client：在指定 compartment 创建保留公网 IP（空为生效 compartment）。
 func (c *RealClient) CreateReservedIP(ctx context.Context, cred Credentials, region, compartmentID, displayName string) (ReservedIP, error) {
 	vn, err := c.vcnClient(cred, region)
 	if err != nil {
 		return ReservedIP{}, err
 	}
 	details := core.CreatePublicIpDetails{
 		CompartmentId: hostCompartment(cred, compartmentID),
 		Lifetime:      core.CreatePublicIpDetailsLifetimeReserved,
 	}
 	if displayName != "" {
 		details.DisplayName = &displayName
 	}
 	resp, err := vn.CreatePublicIp(ctx, core.CreatePublicIpRequest{CreatePublicIpDetails: details})
 	if err != nil {
 		return ReservedIP{}, fmt.Errorf("create reserved ip: %w", err)
 	}
 	cc, err := c.computeClient(cred, region)
 	if err != nil {
 		return ReservedIP{}, err
 	}
 	return c.toReservedIP(ctx, vn, cc, resp.PublicIp), nil
 }
 // AssignReservedIP 实现 Client：绑定保留 IP 到实例主私有 IP；instanceID 为空表示解绑。
 // 目标私有 IP 已有公网 IP 时自动释放（临时删除、其他保留解绑），地址会变更，调用方需提示用户。
 func (c *RealClient) AssignReservedIP(ctx context.Context, cred Credentials, region, publicIPID, instanceID string) error {
 	vn, err := c.vcnClient(cred, region)
 	if err != nil {
 		return err
 	}
 	target := common.String("")
 	if instanceID != "" {
 		priv, err := c.primaryPrivateIP(ctx, cred, region, instanceID)
 		if err != nil {
 			return err
 		}
 		if err := detachExistingPublicIP(ctx, vn, priv.Id); err != nil {
 			return err
 		}
 		target = priv.Id
 	}
 	_, err = vn.UpdatePublicIp(ctx, core.UpdatePublicIpRequest{
 		PublicIpId:            &publicIPID,
 		UpdatePublicIpDetails: core.UpdatePublicIpDetails{PrivateIpId: target},
 	})
 	if err != nil {
 		return fmt.Errorf("assign reserved ip: %w", err)
 	}
 	return nil
 }
 // AssignReservedIPToVnic 实现 Client：绑定保留 IP 到指定 VNIC 的主私有 IP（次要网卡场景）；
 // 该私有 IP 已有公网 IP 时自动释放（临时删除、其他保留解绑）。
 func (c *RealClient) AssignReservedIPToVnic(ctx context.Context, cred Credentials, region, publicIPID, vnicID string) error {
 	vn, err := c.vcnClient(cred, region)
 	if err != nil {
 		return err
 	}
 	priv, err := vnicPrimaryPrivateIP(ctx, vn, vnicID)
 	if err != nil {
 		return err
 	}
 	if err := detachExistingPublicIP(ctx, vn, priv.Id); err != nil {
 		return err
 	}
 	_, err = vn.UpdatePublicIp(ctx, core.UpdatePublicIpRequest{
 		PublicIpId:            &publicIPID,
 		UpdatePublicIpDetails: core.UpdatePublicIpDetails{PrivateIpId: priv.Id},
 	})
 	if err != nil {
 		return fmt.Errorf("assign reserved ip to vnic: %w", err)
 	}
 	return nil
 }
 // vnicPrimaryPrivateIP 取 VNIC 的主私有 IP。
 func vnicPrimaryPrivateIP(ctx context.Context, vn core.VirtualNetworkClient, vnicID string) (core.PrivateIp, error) {
 	resp, err := vn.ListPrivateIps(ctx, core.ListPrivateIpsRequest{VnicId: &vnicID})
 	if err != nil {
 		return core.PrivateIp{}, fmt.Errorf("list private ips: %w", err)
 	}
 	for _, p := range resp.Items {
 		if p.IsPrimary != nil && *p.IsPrimary {
 			return p, nil
 		}
 	}
 	return core.PrivateIp{}, fmt.Errorf("assign reserved ip: vnic has no primary private ip")
 }
 // DeleteReservedIP 实现 Client：删除保留公网 IP（已绑定的会先被 OCI 拒绝）。
 func (c *RealClient) DeleteReservedIP(ctx context.Context, cred Credentials, region, publicIPID string) error {
 	vn, err := c.vcnClient(cred, region)
 	if err != nil {
 		return err
 	}
 	if _, err := vn.DeletePublicIp(ctx, core.DeletePublicIpRequest{PublicIpId: &publicIPID}); err != nil {
 		return fmt.Errorf("delete reserved ip: %w", err)
 	}
 	return nil
 }
@@ -26,6 +26,9 @@ type ComputeShape struct {
 	MemoryMaxGBs         float32 `json:"memoryMaxGBs,omitempty"`
 	Gpus                 int     `json:"gpus,omitempty"`
 	ProcessorDescription string  `json:"processorDescription,omitempty"`
 	// QuotaNames 是该 shape 对应的配额名(与 Limits 服务 compute limit name 同名),
 	// 前端据此结合 limits 行判定配额与 AD 可用性。
 	QuotaNames []string `json:"quotaNames,omitempty"`
 }
 // shapeCacheEntry 是一份 shape 清单的缓存条目。
@@ -92,6 +95,7 @@ func toComputeShape(s core.Shape) ComputeShape {
 		BillingType:          string(s.BillingType),
 		IsFlexible:           s.OcpuOptions != nil,
 		ProcessorDescription: deref(s.ProcessorDescription),
 		QuotaNames:           s.QuotaNames,
 	}
 	out.Ocpus, out.MemoryInGBs = deref32(s.Ocpus), deref32(s.MemoryInGBs)
 	if s.Gpus != nil {
@@ -17,6 +17,9 @@ const ociConsolePolicyID = "OciConsolePolicy"
 // scimPatchSchema 是 SCIM PatchOp 的 schema。
 const scimPatchSchema = "urn:ietf:params:scim:api:messages:2.0:PatchOp"
 // signOnConsentSchema 是修改 Oracle 预置 OCI Console sign-on 策略的知情同意扩展 schema。
 const signOnConsentSchema = "urn:ietf:params:scim:schemas:oracle:idcs:extension:ociconsolesignonpolicyconsent:Policy"
 // SignOnRuleInfo 是 sign-on 策略中一条规则的关键字段。
 type SignOnRuleInfo struct {
 	ID                   string `json:"id"`
@@ -220,15 +223,18 @@ func sortedRules(rules []identitydomains.PolicyRules) []identitydomains.PolicyRu
 func patchPolicyRules(ctx context.Context, dc identitydomains.IdentityDomainsClient, rules []interface{}) error {
 	var value interface{} = rules
 	var consent interface{} = true
 	var justification interface{} = "MFA Configured in External IDP"
 	_, err := dc.PatchPolicy(ctx, identitydomains.PatchPolicyRequest{
 		PolicyId: common.String(ociConsolePolicyID),
 		PatchOp: identitydomains.PatchOp{
 			Schemas: []string{scimPatchSchema},
-			Operations: []identitydomains.Operations{{
+			// 改动 Oracle 预置策略必须附带知情同意,否则 400 Missing required attribute(s): consent
-				Op:    identitydomains.OperationsOpReplace,
+			Operations: []identitydomains.Operations{
-				Path:  common.String("rules"),
+				{Op: identitydomains.OperationsOpReplace, Path: common.String("rules"), Value: &value},
-				Value: &value,
+				{Op: identitydomains.OperationsOpAdd, Path: common.String(signOnConsentSchema + ":consent"), Value: &consent},
-			}},
+				{Op: identitydomains.OperationsOpAdd, Path: common.String(signOnConsentSchema + ":justification"), Value: &justification},
 			},
 		},
 	})
 	if err != nil {
@@ -760,6 +760,66 @@ func (c *RealClient) DeleteTenantUserApiKeys(ctx context.Context, cred Credentia
 	return deleted, nil
 }
 // TenantUserApiKey 是用户名下的一把 API 签名 key。
 type TenantUserApiKey struct {
 	Fingerprint string     `json:"fingerprint"`
 	TimeCreated *time.Time `json:"timeCreated"`
 	// IsCurrent 表示该 key 正被当前配置用于签名请求
 	IsCurrent bool `json:"isCurrent"`
 }
 // ListTenantUserApiKeys 实现 Client：列出用户的 API 签名 key。
 func (c *RealClient) ListTenantUserApiKeys(ctx context.Context, cred Credentials, homeRegion, userID string) ([]TenantUserApiKey, error) {
 	ic, err := c.identityClientAt(cred, homeRegion)
 	if err != nil {
 		return nil, err
 	}
 	resp, err := ic.ListApiKeys(ctx, identity.ListApiKeysRequest{UserId: &userID})
 	if err != nil {
 		return nil, fmt.Errorf("list api keys: %w", err)
 	}
 	keys := make([]TenantUserApiKey, 0, len(resp.Items))
 	for _, item := range resp.Items {
 		k := TenantUserApiKey{Fingerprint: deref(item.Fingerprint)}
 		if item.TimeCreated != nil {
 			t := item.TimeCreated.Time
 			k.TimeCreated = &t
 		}
 		k.IsCurrent = userID == cred.UserOCID && k.Fingerprint == cred.Fingerprint
 		keys = append(keys, k)
 	}
 	return keys, nil
 }
 // UploadTenantUserApiKey 实现 Client：为用户上传 RSA 公钥，返回 OCI 回填的指纹。
 func (c *RealClient) UploadTenantUserApiKey(ctx context.Context, cred Credentials, homeRegion, userID, publicKeyPEM string) (string, error) {
 	ic, err := c.identityClientAt(cred, homeRegion)
 	if err != nil {
 		return "", err
 	}
 	resp, err := ic.UploadApiKey(ctx, identity.UploadApiKeyRequest{
 		UserId:              &userID,
 		CreateApiKeyDetails: identity.CreateApiKeyDetails{Key: &publicKeyPEM},
 	})
 	if err != nil {
 		return "", fmt.Errorf("upload api key: %w", err)
 	}
 	return deref(resp.Fingerprint), nil
 }
 // DeleteTenantUserApiKey 实现 Client：按指纹删除用户的单把 API key。
 func (c *RealClient) DeleteTenantUserApiKey(ctx context.Context, cred Credentials, homeRegion, userID, fingerprint string) error {
 	ic, err := c.identityClientAt(cred, homeRegion)
 	if err != nil {
 		return err
 	}
 	_, err = ic.DeleteApiKey(ctx, identity.DeleteApiKeyRequest{UserId: &userID, Fingerprint: &fingerprint})
 	if err != nil {
 		return fmt.Errorf("delete api key %s: %w", fingerprint, err)
 	}
 	return nil
 }
 // scimUserID 用经典 OCID 在 Identity Domain 中解析 SCIM 用户 ID。
 func scimUserID(ctx context.Context, dc identitydomains.IdentityDomainsClient, classicOCID string) (string, error) {
 	u, found, err := domainUserByOcid(ctx, dc, classicOCID)
@@ -9,7 +9,7 @@ import (
 )
 // 本文件实现 VCN 的级联删除：OCI 要求 VCN 删除前先清空其子网、网关、
-// 非默认路由表 / 安全列表 / DHCP 选项，顺序参照控制台删除向导。
+// 网络安全组(NSG)与非默认路由表 / 安全列表 / DHCP 选项，顺序参照控制台删除向导。
 // 子网仍被 VNIC 占用（实例未终止）时 OCI 返回 409 IncorrectState，
 // 该错误经 api 层提炼后提示用户先终止实例，不在此做实例级清理。
@@ -32,6 +32,9 @@ func deleteVcnCascade(ctx context.Context, vn core.VirtualNetworkClient, vcnID s
 	if err := deleteVcnSecondaries(ctx, vn, comp, vcnID, vcnResp.Vcn); err != nil {
 		return err
 	}
 	if err := deleteVcnNsgs(ctx, vn, vcnID); err != nil {
 		return err
 	}
 	if _, err := vn.DeleteVcn(ctx, core.DeleteVcnRequest{VcnId: &vcnID}); err != nil {
 		return fmt.Errorf("delete vcn %s: %w", vcnID, err)
 	}
@@ -183,3 +186,25 @@ func deleteVcnSecondaries(ctx context.Context, vn core.VirtualNetworkClient, com
 	}
 	return nil
 }
 // deleteVcnNsgs 删除 VCN 下全部网络安全组：遗留 NSG 会使 DeleteVcn 报
 // 409 associated with NSG。仅按 VcnId 过滤,跨 compartment 的 NSG 也能覆盖;
 // 子网删除后 VNIC 已不存在,NSG 不再有关联,可直接删除。
 func deleteVcnNsgs(ctx context.Context, vn core.VirtualNetworkClient, vcnID string) error {
 	resp, err := vn.ListNetworkSecurityGroups(ctx, core.ListNetworkSecurityGroupsRequest{VcnId: &vcnID})
 	if err != nil {
 		return fmt.Errorf("list network security groups: %w", err)
 	}
 	for _, g := range resp.Items {
 		if g.LifecycleState == core.NetworkSecurityGroupLifecycleStateTerminated ||
 			g.LifecycleState == core.NetworkSecurityGroupLifecycleStateTerminating {
 			continue
 		}
 		if _, err := vn.DeleteNetworkSecurityGroup(ctx, core.DeleteNetworkSecurityGroupRequest{
 			NetworkSecurityGroupId: g.Id,
 		}); err != nil {
 			return fmt.Errorf("delete network security group %s: %w", deref(g.DisplayName), err)
 		}
 	}
 	return nil
 }
@@ -31,6 +31,8 @@ type AttachVnicInput struct {
 	AssignPublicIP bool   `json:"assignPublicIp"`
 	// AssignIpv6 为 true 时同时自动分配一个 IPv6(要求子网已启用 IPv6)。
 	AssignIpv6 bool `json:"assignIpv6"`
 	// ReservedPublicIPID 非空时不分配临时公网 IP,VNIC 就绪后由后台绑定该保留 IP。
 	ReservedPublicIPID string `json:"reservedPublicIpId"`
 }
 // ListInstanceVnics 实现 Client:列出实例全部 VNIC(含附加中/分离中的关系)。
@@ -113,6 +115,10 @@ func (c *RealClient) AttachVnic(ctx context.Context, cred Credentials, region, i
 	if err != nil {
 		return Vnic{}, err
 	}
 	// 选了保留 IP 就不分配临时公网 IP,避免绑定时还要先删一次
 	if in.ReservedPublicIPID != "" {
 		in.AssignPublicIP = false
 	}
 	details := &core.CreateVnicDetails{
 		SubnetId:       &in.SubnetID,
 		AssignPublicIp: &in.AssignPublicIP,
@@ -1048,6 +1048,10 @@ func (s *AiGatewayService) LogContent(entry model.AiContentLog) {
 		if err != nil || !ok {
 			return err
 		}
 		on, err := contentLogStillOn(tx, entry.KeyID)
 		if err != nil || !on {
 			return err
 		}
 		return tx.Create(&entry).Error
 	})
 	if err != nil {
@@ -1055,6 +1059,20 @@ func (s *AiGatewayService) LogContent(entry model.AiContentLog) {
 	}
 }
 // contentLogStillOn 写入事务内回读密钥:已删除、被停用或日志窗口已过期时放弃写入,
 // 防止管理员「立即关闭」后,在途长请求仍按鉴权时的旧快照把敏感正文落库。
 func contentLogStillOn(tx *gorm.DB, keyID uint) (bool, error) {
 	var key model.AiKey
 	err := tx.First(&key, keyID).Error
 	if errors.Is(err, gorm.ErrRecordNotFound) {
 		return false, nil
 	}
 	if err != nil {
 		return false, err
 	}
 	return key.Enabled && key.ContentLogUntil != nil && time.Now().Before(*key.ContentLogUntil), nil
 }
 func truncateBody(s string) string {
 	if len(s) > aiContentBodyLimit {
 		return s[:aiContentBodyLimit]
@@ -1110,7 +1128,12 @@ func (s *AiGatewayService) cleanupOnce(ctx context.Context) {
 	s.cleanupTable(ctx, &model.AiContentLog{}, aiContentLogRetention, aiContentLogMaxRows, "ai content log")
 }
-// cleanupTable 按保留期与行数上限清理日志表(超限删最旧)。
+// cleanupBatch 是超限清理每轮删除的行数上限;远小于各数据库绑定变量硬上限
 // (modernc SQLite 32766、MySQL/PG 65535),跨库安全。var 供测试注入小批次。
 var cleanupBatch = 10000
 // cleanupTable 按保留期与行数上限清理日志表(超限删最旧,固定批次循环,
 // 任一批失败必须记日志并中断,静默失败会让日志表无界增长)。
 func (s *AiGatewayService) cleanupTable(ctx context.Context, m any, retention time.Duration, maxRows int, tag string) {
 	cutoff := time.Now().Add(-retention)
 	if err := s.db.WithContext(ctx).Where("created_at < ?", cutoff).Delete(m).Error; err != nil {
@@ -1119,16 +1142,36 @@ func (s *AiGatewayService) cleanupTable(ctx context.Context, m any, retention ti
 	}
 	var total int64
 	if err := s.db.WithContext(ctx).Model(m).Count(&total).Error; err != nil {
 		log.Printf("%s cleanup count: %v", tag, err)
 		return
 	}
-	if overflow := int(total) - maxRows; overflow > 0 {
+	for overflow := int(total) - maxRows; overflow > 0; {
-		var ids []uint
+		n, err := s.deleteOldestBatch(ctx, m, min(overflow, cleanupBatch))
-		s.db.WithContext(ctx).Model(m).Order("id ASC").Limit(overflow).Pluck("id", &ids)
+		if err != nil {
-		if len(ids) > 0 {
+			log.Printf("%s cleanup overflow: %v", tag, err)
-			s.db.WithContext(ctx).Delete(m, ids)
+			return
 		}
 		if n == 0 {
 			return
 		}
 		overflow -= n
 	}
 }
 // deleteOldestBatch 删除表内最旧的至多 limit 行,返回实际删除数。
 func (s *AiGatewayService) deleteOldestBatch(ctx context.Context, m any, limit int) (int, error) {
 	var ids []uint
 	if err := s.db.WithContext(ctx).Model(m).Order("id ASC").Limit(limit).Pluck("id", &ids).Error; err != nil {
 		return 0, fmt.Errorf("pluck oldest: %w", err)
 	}
 	if len(ids) == 0 {
 		return 0, nil
 	}
 	if err := s.db.WithContext(ctx).Delete(m, ids).Error; err != nil {
 		return 0, fmt.Errorf("delete batch: %w", err)
 	}
 	return len(ids), nil
 }
 // Wait 等待后台清理 goroutine 退出。
 func (s *AiGatewayService) Wait() { s.wg.Wait() }
@@ -27,27 +27,27 @@ type aiCandidate struct {
 	modelOcid string
 }
-// RespPassthrough 编排一次非流式直通调用:选渠道(priority→加权随机)→ 调用 →
+// routeRetry 统一编排「选渠道(priority→加权随机)→ 调用 → 可重试错误换渠道」,
-// 可重试错误换渠道(整请求上限 3 次)并维护熔断;group 非空时只在同分组渠道内路由。
+// 整请求上限 3 次并维护熔断;group 非空时只在同分组渠道内路由。
-// 上游为 OpenAI-compatible /actions/v1/responses(实测可用,无 Oracle 文档合同)。
+func routeRetry[T any](ctx context.Context, s *AiGatewayService, modelName, group, capability string, once func(*aiCandidate) (T, error)) (T, ChatMeta, error) {
-func (s *AiGatewayService) RespPassthrough(ctx context.Context, raw []byte, modelName, group string) ([]byte, ChatMeta, error) {
+	var zero T
 	meta := ChatMeta{}
 	excluded := map[uint]bool{}
 	var lastErr error
 	for attempt := 0; attempt < 3; attempt++ {
-		cand, err := s.pick(ctx, modelName, group, "CHAT", excluded)
+		cand, err := s.pick(ctx, modelName, group, capability, excluded)
 		if err != nil {
-			return nil, meta, firstErr(lastErr, err)
+			return zero, meta, firstErr(lastErr, err)
 		}
 		meta.ChannelID, meta.ChannelName = cand.ch.ID, cand.ch.Name
-		payload, err := s.passthroughOnce(ctx, cand, raw)
+		out, err := once(cand)
 		if err == nil {
 			s.markSuccess(ctx, cand.ch.ID)
-			return payload, meta, nil
+			return out, meta, nil
 		}
 		retry, penalize := switchable(err)
 		if !retry {
-			return nil, meta, err
+			return zero, meta, err
 		}
 		if penalize {
 			s.markFailure(ctx, cand.ch.ID)
@@ -56,7 +56,15 @@ func (s *AiGatewayService) RespPassthrough(ctx context.Context, raw []byte, mode
 		meta.Retries++
 		lastErr = err
 	}
-	return nil, meta, lastErr
+	return zero, meta, lastErr
 }
 // RespPassthrough 编排一次非流式直通调用。
 // 上游为 OpenAI-compatible /actions/v1/responses(实测可用,无 Oracle 文档合同)。
 func (s *AiGatewayService) RespPassthrough(ctx context.Context, raw []byte, modelName, group string) ([]byte, ChatMeta, error) {
 	return routeRetry(ctx, s, modelName, group, "CHAT", func(cand *aiCandidate) ([]byte, error) {
 		return s.passthroughOnce(ctx, cand, raw)
 	})
 }
 func (s *AiGatewayService) passthroughOnce(ctx context.Context, cand *aiCandidate, raw []byte) ([]byte, error) {
@@ -70,36 +78,13 @@ func (s *AiGatewayService) passthroughOnce(ctx context.Context, cand *aiCandidat
 // RespPassthroughStream 编排流式直通:流建立成功即绑定渠道,建立失败按 switchable
 // 换渠道重试;建立后的中断不重试、不计熔断(与 OpenStream 语义一致)。
 func (s *AiGatewayService) RespPassthroughStream(ctx context.Context, raw []byte, modelName, group string) (io.ReadCloser, ChatMeta, error) {
-	meta := ChatMeta{}
+	return routeRetry(ctx, s, modelName, group, "CHAT", func(cand *aiCandidate) (io.ReadCloser, error) {
 	excluded := map[uint]bool{}
 	var lastErr error
 	for attempt := 0; attempt < 3; attempt++ {
 		cand, err := s.pick(ctx, modelName, group, "CHAT", excluded)
 		if err != nil {
 			return nil, meta, firstErr(lastErr, err)
 		}
 		meta.ChannelID, meta.ChannelName = cand.ch.ID, cand.ch.Name
 		cred, err := s.configs.credentialsByID(ctx, cand.ch.OciConfigID)
 		if err != nil {
-			return nil, meta, err
+			return nil, err
 		}
-		stream, err := s.client.GenAiCompatResponsesStream(ctx, cred, cand.ch.Region, raw, s.UpstreamWait())
+		return s.client.GenAiCompatResponsesStream(ctx, cred, cand.ch.Region, raw, s.UpstreamWait())
-		if err == nil {
+	})
 			s.markSuccess(ctx, cand.ch.ID)
 			return stream, meta, nil
 		}
 		retry, penalize := switchable(err)
 		if !retry {
 			return nil, meta, err
 		}
 		if penalize {
 			s.markFailure(ctx, cand.ch.ID)
 		}
 		excluded[cand.ch.ID] = true
 		meta.Retries++
 		lastErr = err
 	}
 	return nil, meta, lastErr
 }
 // firstErr 在换渠道后仍失败时优先返回上游错误(而非「无渠道」)。
@@ -221,34 +206,11 @@ func weightedPick(chs []model.AiChannel) model.AiChannel {
 	return chs[len(chs)-1]
 }
-// Embeddings 编排向量化调用:按 EMBEDDING 能力选渠道,可重试错误换渠道(整请求上限 3 次)。
+// Embeddings 编排向量化调用:按 EMBEDDING 能力选渠道,可重试错误换渠道。
 func (s *AiGatewayService) Embeddings(ctx context.Context, req aiwire.EmbeddingsRequest, group string) (*aiwire.EmbeddingsResponse, ChatMeta, error) {
-	meta := ChatMeta{}
+	return routeRetry(ctx, s, req.Model, group, "EMBEDDING", func(cand *aiCandidate) (*aiwire.EmbeddingsResponse, error) {
-	excluded := map[uint]bool{}
+		return s.embedOnce(ctx, cand, req)
-	var lastErr error
+	})
 	for attempt := 0; attempt < 3; attempt++ {
 		cand, err := s.pick(ctx, req.Model, group, "EMBEDDING", excluded)
 		if err != nil {
 			return nil, meta, firstErr(lastErr, err)
 		}
 		meta.ChannelID, meta.ChannelName = cand.ch.ID, cand.ch.Name
 		resp, err := s.embedOnce(ctx, cand, req)
 		if err == nil {
 			s.markSuccess(ctx, cand.ch.ID)
 			return resp, meta, nil
 		}
 		retry, penalize := switchable(err)
 		if !retry {
 			return nil, meta, err
 		}
 		if penalize {
 			s.markFailure(ctx, cand.ch.ID)
 		}
 		excluded[cand.ch.ID] = true
 		meta.Retries++
 		lastErr = err
 	}
 	return nil, meta, lastErr
 }
 // embedOnce 调用渠道向量化并装配 OpenAI 形态响应。
@@ -11,6 +11,8 @@ import (
 	"oci-portal/internal/aiwire"
 	"oci-portal/internal/model"
 	"oci-portal/internal/oci"
 	"gorm.io/gorm"
 )
 // TestSpeechBodyNormalize 断言 TTS 请求体校验与 language 缺省注入。
@@ -220,3 +222,71 @@ func TestAiModerations(t *testing.T) {
 		t.Errorf("ghost 分组 err = %v, want ErrAiNoChannel", err)
 	}
 }
 // TestCleanupTableBatchesOverflow 锁定超限清理的固定批次行为:
 // 溢出量大于单批上限时分多轮删完,且始终删最旧的行。
 func TestCleanupTableBatchesOverflow(t *testing.T) {
 	gw, _ := newTestGateway(t, &fakeClient{})
 	old := cleanupBatch
 	cleanupBatch = 3
 	t.Cleanup(func() { cleanupBatch = old })
 	for i := 0; i < 10; i++ {
 		if err := gw.db.Create(&model.AiCallLog{Endpoint: "chat"}).Error; err != nil {
 			t.Fatalf("seed %d: %v", i, err)
 		}
 	}
 	// maxRows=2:溢出 8 行,需 3 轮批次(3+3+2)
 	gw.cleanupTable(context.Background(), &model.AiCallLog{}, 24*365*time.Hour, 2, "test")
 	var rest []model.AiCallLog
 	if err := gw.db.Order("id").Find(&rest).Error; err != nil {
 		t.Fatalf("load rest: %v", err)
 	}
 	if len(rest) != 2 {
 		t.Fatalf("remaining = %d, want 2", len(rest))
 	}
 	for _, row := range rest {
 		if row.ID <= 8 {
 			t.Errorf("row %d survived, want oldest deleted first", row.ID)
 		}
 	}
 }
 // TestLogContentRechecksKeyInsideTx 锁定「立即关闭」语义:写入事务内回读密钥,
 // 窗口已关、密钥停用或已删时,鉴权期的旧快照不得再落敏感正文。
 func TestLogContentRechecksKeyInsideTx(t *testing.T) {
 	gw, _ := newTestGateway(t, &fakeClient{})
 	if err := gw.db.AutoMigrate(&model.AiContentLog{}); err != nil {
 		t.Fatalf("migrate content log: %v", err)
 	}
 	future := time.Now().Add(time.Hour)
 	key := model.AiKey{Name: "k", KeyHash: "h", Enabled: true, ContentLogUntil: &future}
 	call := model.AiCallLog{Endpoint: "chat"}
 	if err := gw.db.Create(&key).Error; err != nil {
 		t.Fatalf("seed key: %v", err)
 	}
 	if err := gw.db.Create(&call).Error; err != nil {
 		t.Fatalf("seed call: %v", err)
 	}
 	countIs := func(want int64, note string) {
 		t.Helper()
 		var n int64
 		if err := gw.db.Model(&model.AiContentLog{}).Count(&n).Error; err != nil || n != want {
 			t.Fatalf("%s: count=%d (%v), want %d", note, n, err, want)
 		}
 	}
 	gw.LogContent(model.AiContentLog{CallLogID: call.ID, KeyID: key.ID, RequestBody: "prompt"})
 	countIs(1, "窗口开启时应写入")
 	// 管理员立即关闭窗口:在途请求携带的旧快照不得再写
 	if err := gw.db.Model(&model.AiKey{}).Where("id = ?", key.ID).
 		Update("content_log_until", gorm.Expr("NULL")).Error; err != nil {
 		t.Fatalf("close window: %v", err)
 	}
 	gw.LogContent(model.AiContentLog{CallLogID: call.ID, KeyID: key.ID, RequestBody: "late"})
 	countIs(1, "窗口关闭后不得写入")
 	// 密钥删除后同样拒写
 	if err := gw.db.Delete(&model.AiKey{}, key.ID).Error; err != nil {
 		t.Fatalf("delete key: %v", err)
 	}
 	gw.LogContent(model.AiContentLog{CallLogID: call.ID, KeyID: key.ID, RequestBody: "orphan"})
 	countIs(1, "密钥已删后不得写入")
 }
@@ -7,6 +7,18 @@ import (
 	"oci-portal/internal/oci"
 )
 // ChangeVnicPublicIP 更换指定 VNIC 的临时公网 IP,返回新地址(旧保留 IP 自动解绑)。
 func (s *OciConfigService) ChangeVnicPublicIP(ctx context.Context, id uint, region, vnicID string) (string, error) {
 	if vnicID == "" {
 		return "", fmt.Errorf("change vnic public ip: vnicId is required")
 	}
 	cred, err := s.credentialsByID(ctx, id)
 	if err != nil {
 		return "", err
 	}
 	return s.client.ChangeVnicPublicIP(ctx, cred, region, vnicID)
 }
 // ChangeInstancePublicIP 更换实例主 VNIC 的临时公网 IP，返回新地址。
 func (s *OciConfigService) ChangeInstancePublicIP(ctx context.Context, id uint, region, instanceID string) (string, error) {
 	cred, err := s.credentialsByID(ctx, id)
@@ -46,7 +58,7 @@ func (s *OciConfigService) InstanceVnics(ctx context.Context, id uint, region, i
 	return s.client.ListInstanceVnics(ctx, cred, region, instanceID)
 }
-// AttachVnic 为实例附加次要 VNIC。
+// AttachVnic 为实例附加次要 VNIC;选了保留 IP 时由后台等网卡就绪后绑定。
 func (s *OciConfigService) AttachVnic(ctx context.Context, id uint, region, instanceID string, in oci.AttachVnicInput) (oci.Vnic, error) {
 	if instanceID == "" || in.SubnetID == "" {
 		return oci.Vnic{}, fmt.Errorf("attach vnic: instanceId and subnetId are required")
@@ -55,7 +67,16 @@ func (s *OciConfigService) AttachVnic(ctx context.Context, id uint, region, inst
 	if err != nil {
 		return oci.Vnic{}, err
 	}
-	return s.client.AttachVnic(ctx, cred, region, instanceID, in)
+	vnic, err := s.client.AttachVnic(ctx, cred, region, instanceID, in)
 	if err != nil {
 		return vnic, err
 	}
 	if in.ReservedPublicIPID != "" {
 		s.goBind(func() {
 			s.bindReservedIPToVnicWhenReady(cred, region, instanceID, vnic.AttachmentID, in.ReservedPublicIPID)
 		})
 	}
 	return vnic, nil
 }
 // DetachVnic 分离 VNIC 附加关系(主 VNIC 由 OCI 拒绝)。
@@ -39,13 +39,19 @@ type authClaims struct {
 // 用户不存在分支比对它以对齐耗时,防用户枚举与时序侧信道。
 const dummyBcryptHash = "$2a$10$N9qo8uLOickgx2ZMRZoMye3xW1Wq8p1zEIfQpXCXbXyE3xY5C6P6W"
-// AuthService 负责账号初始化、登录校验(密码 + 可选 TOTP)和 JWT 签发与验证。
+// AuthService 负责账号初始化、登录校验(密码 + 可选 TOTP)、JWT 签发与验证,
 // 以及会话落地与管理(session.go)。
 type AuthService struct {
 	db        *gorm.DB
 	jwtSecret []byte
 	guard     *loginGuard
 	// revoked 是登出令牌黑名单(哈希→占位),TTL 对齐令牌剩余有效期,过期自动清出
 	revoked *cache.Cache
 	// seen 是会话最后活跃回写的节流缓存(jti→占位);撤销时清键保证即时生效
 	seen *cache.Cache
 	// revokedJti 是定点撤销的负缓存:无容量上限的专用结构,
 	// 既不与高频 seen 回写争容量,也不存在满载淘汰导致的令牌复活
 	revokedJti *jtiTombstones
 	notifier *Notifier
 	settings *SettingService
@@ -53,6 +59,9 @@ type AuthService struct {
 	totpMu      sync.Mutex
 	totpPending map[string]pendingTotp // username → setup 暂存密钥
 	// cleanupWG 追踪会话清理 goroutine;关停时 Wait 保证清理查询已结束
 	cleanupWG sync.WaitGroup
 }
 // NewAuthService 组装依赖。
@@ -61,6 +70,8 @@ func NewAuthService(db *gorm.DB, jwtSecret string) *AuthService {
 		db: db, jwtSecret: []byte(jwtSecret),
 		guard:       newLoginGuard(),
 		revoked:     cache.New(4096),
 		seen:        cache.New(4096),
 		revokedJti:  newJtiTombstones(),
 		totpPending: map[string]pendingTotp{},
 	}
 }
@@ -109,11 +120,12 @@ func (s *AuthService) createUser(username, password string) error {
 	return nil
 }
-// Login 校验用户名密码与可选 TOTP,成功后签发 JWT;按「IP+用户名」滑动窗口防爆破,
+// Login 校验用户名密码与可选 TOTP,成功后签发 JWT 并落地会话;
-// 锁定期内一律 ErrLoginLocked(正确密码同样拒绝);阈值与时长取安全设置。
+// 按「IP+用户名」滑动窗口防爆破,锁定期内一律 ErrLoginLocked(正确密码同样拒绝);
-// 已启用两步验证时:密码通过但缺验证码返回 ErrTotpRequired(不计失败),验证码错误计入守卫。
+// 阈值与时长取安全设置。已启用两步验证时:密码通过但缺验证码返回
-func (s *AuthService) Login(ctx context.Context, username, password, clientIP, totpCode string) (string, time.Time, error) {
+// ErrTotpRequired(不计失败),验证码错误计入守卫。
-	key := guardKey(clientIP, username)
+func (s *AuthService) Login(ctx context.Context, username, password, totpCode string, meta SessionMeta) (string, time.Time, error) {
 	key := guardKey(meta.ClientIP, username)
 	now := time.Now()
 	sec := securityOf(s.settings)
 	lockFor := time.Duration(sec.LoginLockMinutes) * time.Minute
@@ -129,23 +141,24 @@ func (s *AuthService) Login(ctx context.Context, username, password, clientIP, t
 		if errors.Is(err, gorm.ErrRecordNotFound) {
 			// 与密码错误分支对齐耗时,防用户枚举
 			_ = bcrypt.CompareHashAndPassword([]byte(dummyBcryptHash), []byte(password))
-			return "", time.Time{}, s.failLogin(key, now, username, clientIP, sec)
+			return "", time.Time{}, s.failLogin(key, now, username, meta.ClientIP, sec)
 		}
 		return "", time.Time{}, fmt.Errorf("find user: %w", err)
 	}
 	if bcrypt.CompareHashAndPassword([]byte(user.PasswordHash), []byte(password)) != nil {
-		return "", time.Time{}, s.failLogin(key, now, username, clientIP, sec)
+		return "", time.Time{}, s.failLogin(key, now, username, meta.ClientIP, sec)
 	}
 	if user.TotpSecretEnc != "" {
 		if totpCode == "" {
 			return "", time.Time{}, ErrTotpRequired
 		}
 		if !s.verifyTotp(&user, totpCode) {
-			return "", time.Time{}, s.failLogin(key, now, username, clientIP, sec)
+			return "", time.Time{}, s.failLogin(key, now, username, meta.ClientIP, sec)
 		}
 	}
 	s.guard.success(key)
-	return s.signToken(user.Username, user.TokenVersion)
+	meta.Method = "password"
 	return s.signSessionToken(ctx, &user, meta)
 }
 // failLogin 记失败;达到阈值转锁定并推送告警(开关 login_lock,缺省开)。
@@ -176,7 +189,13 @@ func (s *AuthService) notifyLock(username, clientIP string, sec SecuritySettings
 	})
 }
-func (s *AuthService) signToken(username string, ver uint) (string, time.Time, error) {
+// signToken 签发 JWT,返回令牌、过期时间与 jti(会话落地用)。
 func (s *AuthService) signToken(username string, ver uint) (string, time.Time, string, error) {
 	return s.signTokenWithJTI(username, ver, newTokenID())
 }
 // signTokenWithJTI 为敏感换发沿用会话 jti,使旧/新 JWT 始终指向同一会话。
 func (s *AuthService) signTokenWithJTI(username string, ver uint, jti string) (string, time.Time, string, error) {
 	now := time.Now()
 	expires := now.Add(tokenTTL)
 	claims := authClaims{
@@ -184,31 +203,37 @@ func (s *AuthService) signToken(username string, ver uint) (string, time.Time, e
 			Subject:   username,
 			IssuedAt:  jwt.NewNumericDate(now),
 			ExpiresAt: jwt.NewNumericDate(expires),
-			// jti:同一秒签发的令牌若无唯一 ID 字节全同,登出一个会连坐全部
+			ID:        jti,
 			ID: newTokenID(),
 		},
 		Ver: ver,
 	}
 	token, err := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString(s.jwtSecret)
 	if err != nil {
-		return "", time.Time{}, fmt.Errorf("sign token: %w", err)
+		return "", time.Time{}, "", fmt.Errorf("sign token: %w", err)
 	}
-	return token, expires, nil
+	return token, expires, jti, nil
 }
-// IssueToken 按账号当前令牌版本签发新 JWT;敏感操作递增版本后用它为
+// IssueToken 按账号当前令牌版本签发新 JWT(不落会话行);
-// 操作者重签,避免操作者自身会话中断。
+// 需要会话接续的换发场景用 RenewToken。
 func (s *AuthService) IssueToken(ctx context.Context, username string) (string, time.Time, error) {
 	user, err := s.findUser(ctx, username)
 	if err != nil {
 		return "", time.Time{}, err
 	}
-	return s.signToken(user.Username, user.TokenVersion)
+	token, expires, _, err := s.signToken(user.Username, user.TokenVersion)
 	return token, expires, err
 }
 // bumpTokenVersion 原子递增账号令牌版本,使所有已签发令牌立即失效。
 func (s *AuthService) bumpTokenVersion(ctx context.Context, username string) error {
-	err := s.db.WithContext(ctx).Model(&model.User{}).Where("username = ?", username).
+	return bumpTokenVersionTx(s.db.WithContext(ctx), username)
 }
 // bumpTokenVersionTx 事务内递增令牌版本:与认证因子写入同事务提交,
 // 避免「因子已生效而旧令牌仍有效」的半程状态。
 func bumpTokenVersionTx(tx *gorm.DB, username string) error {
 	err := tx.Model(&model.User{}).Where("username = ?", username).
 		UpdateColumn("token_version", gorm.Expr("token_version + 1")).Error
 	if err != nil {
 		return fmt.Errorf("bump token version: %w", err)
@@ -216,12 +241,28 @@ func (s *AuthService) bumpTokenVersion(ctx context.Context, username string) err
 	return nil
 }
-// RevokeSessions 撤销账号全部会话(版本递增),并为操作者重签新令牌。
+// RevokeSessions 撤销账号全部会话(版本递增),并为操作者重签新令牌;
-func (s *AuthService) RevokeSessions(ctx context.Context, username string) (string, time.Time, error) {
+// oldToken 非空时其会话行接续到新令牌(当前设备在列表中保持连续)。
-	if err := s.bumpTokenVersion(ctx, username); err != nil {
+// 行锁下复核 proof:请求挂起期间令牌已失效则拒绝,并发敏感操作后到者拒。
-		return "", time.Time{}, err
+func (s *AuthService) RevokeSessions(ctx context.Context, username, oldToken string, meta SessionMeta, proof TokenProof) (string, time.Time, error) {
-	}
+	var token string
-	return s.IssueToken(ctx, username)
+	var expires time.Time
 	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 		user, err := lockUserForAuthChange(tx, username)
 		if err != nil {
 			return err
 		}
 		if err := s.ensureTokenCurrentTx(tx, user, proof); err != nil {
 			return err
 		}
 		if err := bumpTokenVersionTx(tx, username); err != nil {
 			return err
 		}
 		user.TokenVersion++
 		token, expires, err = s.renewSessionTx(tx, user, oldToken, meta)
 		return err
 	})
 	return token, expires, err
 }
 // newTokenID 生成 128 位随机令牌 ID(crypto/rand 自 Go 1.24 起不会失败)。
@@ -231,9 +272,28 @@ func newTokenID() string {
 	return hex.EncodeToString(b)
 }
 // TokenProof 是鉴权时观察到的令牌快照(版本 + jti):敏感事务在用户行锁下
 // 复核它仍是账号当前状态,防「请求挂起期间用户撤销 / 注销,恢复后仍完成
 // 敏感变更并换出新令牌」的在途绕过。
 type TokenProof struct {
 	Ver uint
 	Jti string
 }
 // ErrTokenStale 表示请求令牌在处理期间已失效(版本已递增或会话已撤销);
 // api 层映射 401,前端按「发送时令牌 == 当前令牌」决定是否登出。
 var ErrTokenStale = errors.New("会话已失效,请重新登录")
 // ParseToken 验证 JWT 签名、有效期与令牌版本,返回其中的用户名。
 // 版本落后于账号当前值(凭据等已变更)按无效处理,不区分具体原因。
 func (s *AuthService) ParseToken(ctx context.Context, tokenString string) (string, error) {
 	username, _, err := s.ParseTokenProof(ctx, tokenString)
 	return username, err
 }
 // ParseTokenProof 验证令牌并返回用户名与版本 / jti 快照(RequireAuth 与
 // 绑定发起点用;快照随后交由敏感事务复核)。
 func (s *AuthService) ParseTokenProof(ctx context.Context, tokenString string) (string, TokenProof, error) {
 	claims := &authClaims{}
 	_, err := jwt.ParseWithClaims(tokenString, claims, func(t *jwt.Token) (any, error) {
 		if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
@@ -242,23 +302,27 @@ func (s *AuthService) ParseToken(ctx context.Context, tokenString string) (strin
 		return s.jwtSecret, nil
 	})
 	if err != nil {
-		return "", fmt.Errorf("parse token: %w", err)
+		return "", TokenProof{}, fmt.Errorf("parse token: %w", err)
 	}
 	if _, hit := s.revoked.Get(tokenHash(tokenString)); hit {
-		return "", errors.New("token revoked")
+		return "", TokenProof{}, errors.New("token revoked")
 	}
 	user, err := s.findUser(ctx, claims.Subject)
 	if err != nil {
-		return "", fmt.Errorf("token subject: %w", err)
+		return "", TokenProof{}, fmt.Errorf("token subject: %w", err)
 	}
 	if claims.Ver != user.TokenVersion {
-		return "", errors.New("token version outdated")
+		return "", TokenProof{}, errors.New("token version outdated")
 	}
-	return claims.Subject, nil
+	if err := s.checkSession(ctx, claims.ID); err != nil {
 		return "", TokenProof{}, err
 	}
 	return claims.Subject, TokenProof{Ver: claims.Ver, Jti: claims.ID}, nil
 }
-// Logout 把令牌拉进黑名单直至其自然过期;无效/已过期令牌直接视为成功(幂等)。
+// Logout 把令牌拉进黑名单直至其自然过期,并标记对应会话行已撤销;
-func (s *AuthService) Logout(tokenString string) {
+// 无效/已过期令牌直接视为成功(幂等)。
 func (s *AuthService) Logout(ctx context.Context, tokenString string) {
 	claims := &jwt.RegisteredClaims{}
 	_, err := jwt.ParseWithClaims(tokenString, claims, func(t *jwt.Token) (any, error) {
 		return s.jwtSecret, nil
@@ -271,6 +335,7 @@ func (s *AuthService) Logout(tokenString string) {
 		return
 	}
 	s.revoked.Set(tokenHash(tokenString), struct{}{}, ttl)
 	s.revokeSessionByJTI(ctx, claims.Subject, claims.ID, ttl)
 }
 // tokenHash 取令牌 SHA-256 摘要作黑名单键,不在内存长期保留原令牌串。
@@ -21,7 +21,7 @@ func newTestAuth(t *testing.T) *AuthService {
 	if err != nil {
 		t.Fatalf("open in-memory sqlite: %v", err)
 	}
-	if err := db.AutoMigrate(&model.User{}); err != nil {
+	if err := db.AutoMigrate(&model.User{}, &model.UserSession{}); err != nil {
 		t.Fatalf("auto migrate: %v", err)
 	}
 	return NewAuthService(db, "test-jwt-secret")
@@ -32,7 +32,7 @@ func TestEnsureAdminCreatesUser(t *testing.T) {
 	if err := auth.EnsureAdmin("admin", "pass123"); err != nil {
 		t.Fatalf("EnsureAdmin: %v", err)
 	}
-	if _, _, err := auth.Login(context.Background(), "admin", "pass123", "127.0.0.1", ""); err != nil {
+	if _, _, err := auth.Login(context.Background(), "admin", "pass123", "", SessionMeta{ClientIP: "127.0.0.1"}); err != nil {
 		t.Errorf("Login after EnsureAdmin: %v", err)
 	}
 }
@@ -45,10 +45,10 @@ func TestEnsureAdminDoesNotResetPassword(t *testing.T) {
 	if err := auth.EnsureAdmin("admin", "second"); err != nil {
 		t.Fatalf("EnsureAdmin twice: %v", err)
 	}
-	if _, _, err := auth.Login(context.Background(), "admin", "first", "127.0.0.1", ""); err != nil {
+	if _, _, err := auth.Login(context.Background(), "admin", "first", "", SessionMeta{ClientIP: "127.0.0.1"}); err != nil {
 		t.Errorf("Login with original password: %v", err)
 	}
-	if _, _, err := auth.Login(context.Background(), "admin", "second", "127.0.0.1", ""); !errors.Is(err, ErrInvalidCredentials) {
+	if _, _, err := auth.Login(context.Background(), "admin", "second", "", SessionMeta{ClientIP: "127.0.0.1"}); !errors.Is(err, ErrInvalidCredentials) {
 		t.Errorf("Login with new password: got %v, want ErrInvalidCredentials", err)
 	}
 }
@@ -89,7 +89,7 @@ func TestLoginFailures(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			_, _, err := auth.Login(context.Background(), tt.username, tt.password, "127.0.0.1", "")
+			_, _, err := auth.Login(context.Background(), tt.username, tt.password, "", SessionMeta{ClientIP: "127.0.0.1"})
 			if !errors.Is(err, ErrInvalidCredentials) {
 				t.Errorf("Login(%q, %q) error = %v, want ErrInvalidCredentials", tt.username, tt.password, err)
 			}
@@ -102,7 +102,7 @@ func TestTokenRoundTrip(t *testing.T) {
 	if err := auth.EnsureAdmin("admin", "pass123"); err != nil {
 		t.Fatalf("EnsureAdmin: %v", err)
 	}
-	token, expires, err := auth.Login(context.Background(), "admin", "pass123", "127.0.0.1", "")
+	token, expires, err := auth.Login(context.Background(), "admin", "pass123", "", SessionMeta{ClientIP: "127.0.0.1"})
 	if err != nil {
 		t.Fatalf("Login: %v", err)
 	}
@@ -125,7 +125,7 @@ func TestParseTokenRejectsForged(t *testing.T) {
 	if err := other.EnsureAdmin("admin", "pass"); err != nil {
 		t.Fatalf("EnsureAdmin: %v", err)
 	}
-	forged, _, err := other.Login(context.Background(), "admin", "pass", "127.0.0.1", "")
+	forged, _, err := other.Login(context.Background(), "admin", "pass", "", SessionMeta{ClientIP: "127.0.0.1"})
 	if err != nil {
 		t.Fatalf("Login: %v", err)
 	}
@@ -143,21 +143,21 @@ func TestLogoutRevokesToken(t *testing.T) {
 	if err := auth.EnsureAdmin("admin", "pass123"); err != nil {
 		t.Fatalf("EnsureAdmin: %v", err)
 	}
-	token, _, err := auth.signToken("admin", 0)
+	token, _, _, err := auth.signToken("admin", 0)
 	if err != nil {
 		t.Fatalf("signToken: %v", err)
 	}
 	if _, err := auth.ParseToken(context.Background(), token); err != nil {
 		t.Fatalf("ParseToken before logout: %v", err)
 	}
-	auth.Logout(token)
+	auth.Logout(context.Background(), token)
 	if _, err := auth.ParseToken(context.Background(), token); err == nil {
 		t.Error("ParseToken after logout: got nil error, want revoked")
 	}
 	// 幂等:重复登出与无效令牌登出都不应 panic,也不影响其他令牌
-	auth.Logout(token)
+	auth.Logout(context.Background(), token)
-	auth.Logout("not.a.token")
+	auth.Logout(context.Background(), "not.a.token")
-	fresh, _, err := auth.signToken("admin", 0)
+	fresh, _, _, err := auth.signToken("admin", 0)
 	if err != nil {
 		t.Fatalf("signToken fresh: %v", err)
 	}
@@ -174,13 +174,13 @@ func TestTokenVersionInvalidatesOldToken(t *testing.T) {
 		t.Fatalf("EnsureAdmin: %v", err)
 	}
 	ctx := context.Background()
-	old, _, err := auth.Login(ctx, "admin", "pass123", "127.0.0.1", "")
+	old, _, err := auth.Login(ctx, "admin", "pass123", "", SessionMeta{ClientIP: "127.0.0.1"})
 	if err != nil {
 		t.Fatalf("Login: %v", err)
 	}
 	finalName, err := auth.UpdateCredentials(ctx, "admin", UpdateCredentialsInput{
 		NewPassword: "changed-456", CurrentPassword: "pass123",
-	})
+	}, proofOf(t, auth.db, "admin"))
 	if err != nil {
 		t.Fatalf("UpdateCredentials: %v", err)
 	}
@@ -203,11 +203,11 @@ func TestRevokeSessions(t *testing.T) {
 		t.Fatalf("EnsureAdmin: %v", err)
 	}
 	ctx := context.Background()
-	old, _, err := auth.Login(ctx, "admin", "pass123", "127.0.0.1", "")
+	old, _, err := auth.Login(ctx, "admin", "pass123", "", SessionMeta{ClientIP: "127.0.0.1"})
 	if err != nil {
 		t.Fatalf("Login: %v", err)
 	}
-	fresh, _, err := auth.RevokeSessions(ctx, "admin")
+	fresh, _, err := auth.RevokeSessions(ctx, "admin", "", SessionMeta{}, proofOf(t, auth.db, "admin"))
 	if err != nil {
 		t.Fatalf("RevokeSessions: %v", err)
 	}
@@ -0,0 +1,72 @@
 package service
 import (
 	"context"
 	"fmt"
 	"strings"
 	"oci-portal/internal/oci"
 )
 // maxInvoicePdfBytes 是发票 PDF 中转上限;正常发票远小于此,超限视为异常。
 const maxInvoicePdfBytes = 20 << 20
 // Invoices 列出租户发票;year>0 只取该自然年(前端按年懒加载),0 为全量。
 func (s *OciConfigService) Invoices(ctx context.Context, id uint, year int) ([]oci.Invoice, error) {
 	if year != 0 && (year < 2000 || year > 2100) {
 		return nil, fmt.Errorf("invoices: invalid year %d", year)
 	}
 	cred, err := s.credentialsByID(ctx, id)
 	if err != nil {
 		return nil, err
 	}
 	return s.client.ListInvoices(ctx, cred, year)
 }
 // InvoiceLines 列出一张发票的费用明细。
 func (s *OciConfigService) InvoiceLines(ctx context.Context, id uint, internalID string) ([]oci.InvoiceLine, error) {
 	if internalID == "" {
 		return nil, fmt.Errorf("invoice lines: internal invoice id is empty")
 	}
 	cred, err := s.credentialsByID(ctx, id)
 	if err != nil {
 		return nil, err
 	}
 	return s.client.ListInvoiceLines(ctx, cred, internalID)
 }
 // InvoicePdf 拉取一张发票的 PDF 原文。
 func (s *OciConfigService) InvoicePdf(ctx context.Context, id uint, internalID string) ([]byte, error) {
 	if internalID == "" {
 		return nil, fmt.Errorf("invoice pdf: internal invoice id is empty")
 	}
 	cred, err := s.credentialsByID(ctx, id)
 	if err != nil {
 		return nil, err
 	}
 	return s.client.DownloadInvoicePdf(ctx, cred, internalID, maxInvoicePdfBytes)
 }
 // PayInvoice 按订阅默认付款方式支付发票;email 接收付款回执,必填。
 func (s *OciConfigService) PayInvoice(ctx context.Context, id uint, internalID, email string) error {
 	if internalID == "" {
 		return fmt.Errorf("pay invoice: internal invoice id is empty")
 	}
 	if !strings.Contains(email, "@") {
 		return fmt.Errorf("pay invoice: invalid receipt email")
 	}
 	cred, err := s.credentialsByID(ctx, id)
 	if err != nil {
 		return err
 	}
 	return s.client.PayInvoice(ctx, cred, internalID, email)
 }
 // PaymentMethods 列出订阅上登记的全部付款方式。
 func (s *OciConfigService) PaymentMethods(ctx context.Context, id uint) ([]oci.PaymentMethod, error) {
 	cred, err := s.credentialsByID(ctx, id)
 	if err != nil {
 		return nil, err
 	}
 	return s.client.ListPaymentMethods(ctx, cred)
 }
@@ -0,0 +1,109 @@
 package service
 import (
 	"context"
 	"strings"
 	"testing"
 	"oci-portal/internal/oci"
 )
 // billingStubClient 只桩账单方法,其余经内嵌 fakeClient 兜底。
 type billingStubClient struct {
 	*fakeClient
 	invoices []oci.Invoice
 	lines    []oci.InvoiceLine
 	methods  []oci.PaymentMethod
 	pdf      []byte
 	listYear  int
 	paidID    string
 	paidEmail string
 }
 func (f *billingStubClient) ListInvoices(ctx context.Context, cred oci.Credentials, year int) ([]oci.Invoice, error) {
 	f.listYear = year
 	return f.invoices, nil
 }
 func (f *billingStubClient) ListInvoiceLines(ctx context.Context, cred oci.Credentials, internalInvoiceID string) ([]oci.InvoiceLine, error) {
 	return f.lines, nil
 }
 func (f *billingStubClient) DownloadInvoicePdf(ctx context.Context, cred oci.Credentials, internalInvoiceID string, maxBytes int64) ([]byte, error) {
 	return f.pdf, nil
 }
 func (f *billingStubClient) PayInvoice(ctx context.Context, cred oci.Credentials, internalInvoiceID, email string) error {
 	f.paidID, f.paidEmail = internalInvoiceID, email
 	return nil
 }
 func (f *billingStubClient) ListPaymentMethods(ctx context.Context, cred oci.Credentials) ([]oci.PaymentMethod, error) {
 	return f.methods, nil
 }
 func TestInvoicesAndPaymentMethods(t *testing.T) {
 	client := &billingStubClient{
 		fakeClient: &fakeClient{tenancy: oci.TenancyInfo{Name: "t"}},
 		invoices:   []oci.Invoice{{ID: "inv1", Number: "100001", Status: "OPEN"}},
 		lines:      []oci.InvoiceLine{{Product: "Compute", Total: 12.5}},
 		methods:    []oci.PaymentMethod{{Method: "CREDIT_CARD", LastDigits: "4242"}},
 		pdf:        []byte("%PDF-1.4 fake"),
 	}
 	svc := newTestService(t, client)
 	cfg := importAliveConfig(t, svc)
 	ctx := context.Background()
 	if list, err := svc.Invoices(ctx, cfg.ID, 0); err != nil || len(list) != 1 || list[0].Number != "100001" {
 		t.Fatalf("Invoices = %v, %v", list, err)
 	}
 	if _, err := svc.Invoices(ctx, cfg.ID, 2026); err != nil || client.listYear != 2026 {
 		t.Fatalf("Invoices(year) 透传 = %d, %v, want 2026", client.listYear, err)
 	}
 	if _, err := svc.Invoices(ctx, cfg.ID, 26); err == nil {
 		t.Fatal("Invoices(26) 应拒绝非法年份")
 	}
 	if lines, err := svc.InvoiceLines(ctx, cfg.ID, "6100"); err != nil || len(lines) != 1 {
 		t.Fatalf("InvoiceLines = %v, %v", lines, err)
 	}
 	if data, err := svc.InvoicePdf(ctx, cfg.ID, "6100"); err != nil || len(data) == 0 {
 		t.Fatalf("InvoicePdf = %d bytes, %v", len(data), err)
 	}
 	if ms, err := svc.PaymentMethods(ctx, cfg.ID); err != nil || len(ms) != 1 || ms[0].LastDigits != "4242" {
 		t.Fatalf("PaymentMethods = %v, %v", ms, err)
 	}
 }
 func TestPayInvoiceValidation(t *testing.T) {
 	client := &billingStubClient{fakeClient: &fakeClient{tenancy: oci.TenancyInfo{Name: "t"}}}
 	svc := newTestService(t, client)
 	cfg := importAliveConfig(t, svc)
 	ctx := context.Background()
 	tests := []struct {
 		name, internalID, email, wantErr string
 	}{
 		{"内部 ID 为空", "", "a@b.c", "internal invoice id is empty"},
 		{"邮箱非法", "6100", "not-an-email", "invalid receipt email"},
 		{"合法请求", "6100", "billing@example.com", ""},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			err := svc.PayInvoice(ctx, cfg.ID, tt.internalID, tt.email)
 			if tt.wantErr == "" {
 				if err != nil {
 					t.Fatalf("err = %v, want nil", err)
 				}
 				if client.paidID != tt.internalID || client.paidEmail != tt.email {
 					t.Fatalf("透传 = (%s, %s), want (%s, %s)", client.paidID, client.paidEmail, tt.internalID, tt.email)
 				}
 				return
 			}
 			if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
 				t.Fatalf("err = %v, want contains %q", err, tt.wantErr)
 			}
 		})
 	}
 }
@@ -8,6 +8,7 @@ import (
 	"golang.org/x/crypto/bcrypt"
 	"gorm.io/gorm"
 	"gorm.io/gorm/clause"
 	"oci-portal/internal/model"
 )
@@ -19,13 +20,16 @@ var ErrCredentialConfirm = errors.New("当前密码不正确")
 var ErrCredentialInvalid = errors.New("凭据输入非法")
 // ErrPasswordLoginDisabled 表示密码登录已被禁用;api 层映射 403。
-var ErrPasswordLoginDisabled = errors.New("密码登录已禁用,请使用外部身份登录")
+var ErrPasswordLoginDisabled = errors.New("密码登录已禁用,请使用免密方式登录")
-// ErrNeedIdentity 表示未绑定外部身份不可禁用密码登录;api 层映射 409。
+// ErrNeedIdentity 表示无任何可用免密登录方式时不可禁用密码登录;api 层映射 409。
-var ErrNeedIdentity = errors.New("至少绑定一个外部身份后才能禁用密码登录")
+var ErrNeedIdentity = errors.New("需先有可用的免密登录方式(通行密钥、钱包或已启用的外部登录),才能禁用密码登录")
-// ErrLastIdentity 表示密码登录禁用期间不可解绑最后一个身份(防自锁);api 层映射 409。
+// ErrProviderLastLogin 表示密码登录禁用期间不可禁用/清空最后可用的登录方式;api 层映射 409。
-var ErrLastIdentity = errors.New("密码登录已禁用,不能解绑最后一个外部身份;请先允许密码登录")
+var ErrProviderLastLogin = errors.New("密码登录已禁用,该操作将移除最后可用的登录方式;请先允许密码登录")
 // ErrLastIdentity 表示密码登录禁用期间不可移除最后一个免密登录方式(防自锁);api 层映射 409。
 var ErrLastIdentity = errors.New("密码登录已禁用,不能移除最后一个免密登录方式;请先允许密码登录")
 // UpdateCredentialsInput 是修改登录凭据的请求体;两项至少改一项,当前密码必填。
 type UpdateCredentialsInput struct {
@@ -34,9 +38,23 @@ type UpdateCredentialsInput struct {
 	CurrentPassword string `json:"currentPassword" binding:"required"`
 }
 type authenticatedMutation struct {
 	auth     *AuthService
 	username string
 	proof    TokenProof
 }
 func (m *authenticatedMutation) lockAndCheck(tx *gorm.DB) error {
 	user, err := lockUserForAuthChange(tx, m.username)
 	if err != nil {
 		return err
 	}
 	return m.auth.ensureTokenCurrentTx(tx, user, m.proof)
 }
 // UpdateCredentials 修改用户名 / 密码:当前密码必验;成功后令牌版本递增
 // (全部旧 JWT 立即失效),返回最终用户名供调用方为操作者重签新令牌。
-func (s *AuthService) UpdateCredentials(ctx context.Context, username string, in UpdateCredentialsInput) (string, error) {
+func (s *AuthService) UpdateCredentials(ctx context.Context, username string, in UpdateCredentialsInput, proof TokenProof) (string, error) {
 	user, err := s.findUser(ctx, username)
 	if err != nil {
 		return "", err
@@ -52,14 +70,40 @@ func (s *AuthService) UpdateCredentials(ctx context.Context, username string, in
 	if err != nil {
 		return "", err
 	}
 	// 同一条 UPDATE 里递增令牌版本,与凭据变更保持原子
 	updates["token_version"] = gorm.Expr("token_version + 1")
-	if err := s.db.WithContext(ctx).Model(&model.User{}).Where("id = ?", user.ID).Updates(updates).Error; err != nil {
+	if err := s.applyCredentialUpdates(ctx, username, proof, updates); err != nil {
-		return "", fmt.Errorf("update credentials: %w", err)
+		return "", err
 	}
 	return finalName, nil
 }
 func (s *AuthService) applyCredentialUpdates(
 	ctx context.Context, username string, proof TokenProof, updates map[string]any,
 ) error {
 	return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 		locked, err := lockUserForAuthChange(tx, username)
 		if err != nil {
 			return err
 		}
 		if err := s.ensureTokenCurrentTx(tx, locked, proof); err != nil {
 			return err
 		}
 		return updateCredentialsTx(tx, locked.ID, proof.Ver, updates)
 	})
 }
 func updateCredentialsTx(tx *gorm.DB, userID uint, version uint, updates map[string]any) error {
 	res := tx.Model(&model.User{}).
 		Where("id = ? AND token_version = ?", userID, version).Updates(updates)
 	if res.Error != nil {
 		return fmt.Errorf("update credentials: %w", res.Error)
 	}
 	if res.RowsAffected == 0 {
 		return ErrTokenStale
 	}
 	return nil
 }
 // credentialUpdates 组装凭据变更字段并返回最终用户名。
 func (s *AuthService) credentialUpdates(ctx context.Context, user *model.User, newName, newPassword string) (map[string]any, string, error) {
 	updates := map[string]any{}
@@ -118,37 +162,224 @@ func (s *AuthService) PasswordLoginDisabled(ctx context.Context) (bool, error) {
 	return s.settings.PasswordLoginDisabled(ctx)
 }
-// SetPasswordLoginDisabled 保存开关;开启前须至少绑定一个外部身份,防止自锁。
+// SetPasswordLoginDisabled 保存开关;开启前须至少有一种免密登录方式
-func (s *AuthService) SetPasswordLoginDisabled(ctx context.Context, username string, disabled bool) error {
+// (通行密钥或外部身份),防止自锁。检查与写入在同一事务内并锁定用户行,
 // 防与解绑身份/删除通行密钥并发绕过「至少一种登录方式」。
 func (s *AuthService) SetPasswordLoginDisabled(ctx context.Context, username string, disabled bool, proof TokenProof) error {
 	if s.settings == nil {
 		return errors.New("settings unavailable")
 	}
 	value := ""
 	if disabled {
-		user, err := s.findUser(ctx, username)
+		value = "1"
 	}
 	return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 		user, err := lockUserForAuthChange(tx, username)
 		if err != nil {
 			return err
 		}
-		n, err := s.identityCount(ctx, user.ID)
+		if err := s.ensureTokenCurrentTx(tx, user, proof); err != nil {
 		if err != nil {
 			return err
 		}
-		if n == 0 {
+		if err := s.ensurePasswordlessForToggle(tx, user.ID, disabled); err != nil {
-			return ErrNeedIdentity
+			return err
 		}
-	}
+		if err := saveSettingTx(tx, settingSecPasswordLoginOff, value); err != nil {
-	if err := s.settings.SetPasswordLoginDisabled(ctx, disabled); err != nil {
+			return err
-		return err
+		}
-	}
+		// 登录策略属敏感变更:版本递增与开关写入同事务提交,不留半程状态
-	// 登录策略属敏感变更:递增令牌版本,已签发会话全部失效
+		return bumpTokenVersionTx(tx, username)
-	return s.bumpTokenVersion(ctx, username)
+	})
 }
-func (s *AuthService) identityCount(ctx context.Context, userID uint) (int64, error) {
+func (s *AuthService) ensurePasswordlessForToggle(tx *gorm.DB, userID uint, disabled bool) error {
 	if !disabled {
 		return nil
 	}
 	origin, err := effectiveOriginTx(tx, s.settings)
 	if err != nil {
 		return err
 	}
 	ok, err := usablePasswordlessTx(tx, userID, 0, 0, origin)
 	if err != nil {
 		return err
 	}
 	if !ok {
 		return ErrNeedIdentity
 	}
 	return nil
 }
 // lockUserForAuthChange 事务内锁定用户行(SQLite 单写天然串行,MySQL/PG 靠行锁),
 // 「禁用密码登录」与「解绑身份」都先过这把锁,保证不变量检查与写入不交叉。
 func lockUserForAuthChange(tx *gorm.DB, username string) (*model.User, error) {
 	var user model.User
 	err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
 		First(&user, "username = ?", username).Error
 	if err != nil {
 		return nil, fmt.Errorf("find user %s: %w", username, err)
 	}
 	return &user, nil
 }
 func lockUserByIDForAuthChange(tx *gorm.DB, userID uint) (*model.User, error) {
 	var user model.User
 	err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&user, userID).Error
 	if err != nil {
 		return nil, fmt.Errorf("find user: %w", err)
 	}
 	return &user, nil
 }
 // ensureTokenCurrentTx 行锁下复核请求令牌仍是账号当前状态:版本一致
 // (改密 / 撤销全部会递增),且对应会话行未被注销或定点撤销
 // (Logout 联动标记 revoked_at,查行即可覆盖两者);存量令牌无行时仅校验版本。
 func (s *AuthService) ensureTokenCurrentTx(tx *gorm.DB, user *model.User, proof TokenProof) error {
 	if user.TokenVersion != proof.Ver {
 		return ErrTokenStale
 	}
 	if proof.Jti == "" {
 		return nil
 	}
 	if s.revokedJti.has(proof.Jti) {
 		return ErrTokenStale
 	}
 	var row model.UserSession
 	err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
 		Select("id", "revoked_at").Where("token_id = ?", proof.Jti).First(&row).Error
 	if err != nil {
 		if errors.Is(err, gorm.ErrRecordNotFound) {
 			return nil
 		}
 		return fmt.Errorf("find session: %w", err)
 	}
 	if row.RevokedAt != nil {
 		return ErrTokenStale
 	}
 	return nil
 }
 // lockUsersForAuthChange 锁定全部用户行(单管理员面板即一行):与
 // lockUserForAuthChange 竞争同一把行锁,防「改 provider / 面板地址配置」
 // 与「禁用密码 / 删除最后因子」并发交错绕过登录方式不变量。
 func lockUsersForAuthChange(tx *gorm.DB) error {
 	var users []model.User
 	if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).Find(&users).Error; err != nil {
 		return fmt.Errorf("lock users: %w", err)
 	}
 	return nil
 }
 // identityProviderCountTx 统计某 provider 的身份总数(单管理员面板,不区分账号)。
 func identityProviderCountTx(tx *gorm.DB, provider string) (int64, error) {
 	var n int64
 	err := tx.Model(&model.UserIdentity{}).Where("provider = ?", provider).Count(&n).Error
 	if err != nil {
 		return 0, fmt.Errorf("count identities: %w", err)
 	}
 	return n, nil
 }
 func identityCountTx(tx *gorm.DB, userID uint) (int64, error) {
 	var count int64
-	err := s.db.WithContext(ctx).Model(&model.UserIdentity{}).
+	err := tx.Model(&model.UserIdentity{}).
 		Where("user_id = ?", userID).Count(&count).Error
 	if err != nil {
 		return 0, fmt.Errorf("count identities: %w", err)
 	}
 	return count, nil
 }
 // passkeyCountTx 统计账号的通行密钥数(事务内,防自锁检查用)。
 func passkeyCountTx(tx *gorm.DB, userID uint) (int64, error) {
 	var count int64
 	err := tx.Model(&model.UserPasskey{}).
 		Where("user_id = ?", userID).Count(&count).Error
 	if err != nil {
 		return 0, fmt.Errorf("count passkeys: %w", err)
 	}
 	return count, nil
 }
 // usablePasswordlessTx 事务内判断(排除给定身份/通行密钥行后)是否仍存在
 // 可实际登录的免密方式:通行密钥仅统计注册 origin 与当前面板地址一致的
 // (地址变更后旧域名凭据不可登录,不得计入);钱包按地址绑定,恒可用;
 // GitHub/OIDC 身份须对应 provider 已配置且未禁用才计入(端到端防自锁)。
 // origin 为空时所有方式均不可用:Passkey RP、钱包 SIWE 与 OAuth 回调都依赖面板地址。
 func usablePasswordlessTx(tx *gorm.DB, userID uint, excludeIdentity, excludePasskey uint, origin string) (bool, error) {
 	if origin == "" {
 		return false, nil
 	}
 	pk, err := passkeyCountExcludingTx(tx, userID, excludePasskey, origin)
 	if err != nil || pk > 0 {
 		return pk > 0, err
 	}
 	if n, err := identityCountByProviderTx(tx, userID, "wallet", excludeIdentity); err != nil || n > 0 {
 		return n > 0, err
 	}
 	for _, p := range []string{"github", "oidc"} {
 		n, err := identityCountByProviderTx(tx, userID, p, excludeIdentity)
 		if err != nil {
 			return false, err
 		}
 		if n == 0 {
 			continue
 		}
 		if ok, err := oauthProviderUsableTx(tx, p); err != nil || ok {
 			return ok, err
 		}
 	}
 	return false, nil
 }
 // oauthProviderUsableTx 事务内判断 provider 当前可实际登录:
 // clientID 与 secret 均已配置(oidc 还需 issuer)且未禁用。
 func oauthProviderUsableTx(tx *gorm.DB, provider string) (bool, error) {
 	need := []string{settingOauthGithubClientID, settingOauthGithubClientSecret}
 	offKey := settingOauthGithubDisabled
 	if provider == "oidc" {
 		need = []string{settingOauthOidcClientID, settingOauthOidcClientSecret, settingOauthOidcIssuer}
 		offKey = settingOauthOidcDisabled
 	}
 	for _, k := range need {
 		v, err := settingValueTx(tx, k)
 		if err != nil || v == "" {
 			return false, err
 		}
 	}
 	off, err := settingValueTx(tx, offKey)
 	return off != "1", err
 }
 // identityCountByProviderTx 统计账号某 provider 的身份数,可排除一行(解绑前判定用)。
 func identityCountByProviderTx(tx *gorm.DB, userID uint, provider string, excludeID uint) (int64, error) {
 	q := tx.Model(&model.UserIdentity{}).Where("user_id = ? AND provider = ?", userID, provider)
 	if excludeID != 0 {
 		q = q.Where("id <> ?", excludeID)
 	}
 	var count int64
 	if err := q.Count(&count).Error; err != nil {
 		return 0, fmt.Errorf("count identities: %w", err)
 	}
 	return count, nil
 }
 // passkeyCountExcludingTx 统计「当前地址下可用」的通行密钥数,可排除一行;
 // userID 为 0 表示全表(单管理员面板);origin 非空时仅计注册来源一致的凭据。
 func passkeyCountExcludingTx(tx *gorm.DB, userID, excludeID uint, origin string) (int64, error) {
 	q := tx.Model(&model.UserPasskey{})
 	if userID != 0 {
 		q = q.Where("user_id = ?", userID)
 	}
 	if excludeID != 0 {
 		q = q.Where("id <> ?", excludeID)
 	}
 	if origin != "" {
 		q = q.Where("origin = ?", origin)
 	}
 	var count int64
 	if err := q.Count(&count).Error; err != nil {
 		return 0, fmt.Errorf("count passkeys: %w", err)
 	}
 	return count, nil
 }
@@ -5,6 +5,8 @@ import (
 	"errors"
 	"testing"
 	"gorm.io/gorm"
 	"oci-portal/internal/crypto"
 	"oci-portal/internal/model"
 )
@@ -17,7 +19,11 @@ func newCredEnv(t *testing.T) *AuthService {
 	if err != nil {
 		t.Fatalf("new cipher: %v", err)
 	}
-	auth.SetNotifier(nil, NewSettingService(db, cipher))
+	settings := NewSettingService(db, cipher)
 	if err := settings.UpdateSecurity(context.Background(), SecurityPatch{AppURL: strPtr("https://app.example.com")}); err != nil {
 		t.Fatalf("seed app url: %v", err)
 	}
 	auth.SetNotifier(nil, settings)
 	return auth
 }
@@ -26,16 +32,16 @@ func TestUpdateCredentials(t *testing.T) {
 	ctx := context.Background()
 	// 当前密码错误
-	_, err := auth.UpdateCredentials(ctx, "admin", UpdateCredentialsInput{NewPassword: "newpass-123", CurrentPassword: "wrong"})
+	_, err := auth.UpdateCredentials(ctx, "admin", UpdateCredentialsInput{NewPassword: "newpass-123", CurrentPassword: "wrong"}, proofOf(t, auth.db, "admin"))
 	if !errors.Is(err, ErrCredentialConfirm) {
 		t.Fatalf("wrong current password: err = %v, want ErrCredentialConfirm", err)
 	}
 	// 短密码 / 无变更均拒绝
-	_, err = auth.UpdateCredentials(ctx, "admin", UpdateCredentialsInput{NewPassword: "short", CurrentPassword: "pass123"})
+	_, err = auth.UpdateCredentials(ctx, "admin", UpdateCredentialsInput{NewPassword: "short", CurrentPassword: "pass123"}, proofOf(t, auth.db, "admin"))
 	if !errors.Is(err, ErrCredentialInvalid) {
 		t.Fatalf("short password: err = %v, want ErrCredentialInvalid", err)
 	}
-	_, err = auth.UpdateCredentials(ctx, "admin", UpdateCredentialsInput{NewUsername: "admin", CurrentPassword: "pass123"})
+	_, err = auth.UpdateCredentials(ctx, "admin", UpdateCredentialsInput{NewUsername: "admin", CurrentPassword: "pass123"}, proofOf(t, auth.db, "admin"))
 	if !errors.Is(err, ErrCredentialInvalid) {
 		t.Fatalf("no-op change: err = %v, want ErrCredentialInvalid", err)
 	}
@@ -43,24 +49,60 @@ func TestUpdateCredentials(t *testing.T) {
 	// 同时改名改密
 	_, err = auth.UpdateCredentials(ctx, "admin", UpdateCredentialsInput{
 		NewUsername: "root", NewPassword: "newpass-123", CurrentPassword: "pass123",
-	})
+	}, proofOf(t, auth.db, "admin"))
 	if err != nil {
 		t.Fatalf("UpdateCredentials: %v", err)
 	}
-	if _, _, err := auth.Login(ctx, "admin", "pass123", "127.0.0.1", ""); !errors.Is(err, ErrInvalidCredentials) {
+	if _, _, err := auth.Login(ctx, "admin", "pass123", "", SessionMeta{ClientIP: "127.0.0.1"}); !errors.Is(err, ErrInvalidCredentials) {
 		t.Errorf("old username login: err = %v, want ErrInvalidCredentials", err)
 	}
-	if _, _, err := auth.Login(ctx, "root", "newpass-123", "127.0.0.2", ""); err != nil {
+	if _, _, err := auth.Login(ctx, "root", "newpass-123", "", SessionMeta{ClientIP: "127.0.0.2"}); err != nil {
 		t.Errorf("new credentials login: %v", err)
 	}
 }
 func TestUpdateCredentialsRejectsRevokedJTI(t *testing.T) {
 	auth := newCredEnv(t)
 	ctx := context.Background()
 	stale := loginSession(t, auth, "10.10.0.1", "stale")
 	current := loginSession(t, auth, "10.10.0.2", "current")
 	proof := mustProof(t, auth, stale)
 	for _, item := range mustSessions(t, auth, current) {
 		if !item.Current {
 			if err := auth.RevokeSession(ctx, "admin", current, item.ID); err != nil {
 				t.Fatalf("RevokeSession: %v", err)
 			}
 		}
 	}
 	_, err := auth.UpdateCredentials(ctx, "admin", UpdateCredentialsInput{
 		NewPassword: "newpass-123", CurrentPassword: "pass123",
 	}, proof)
 	if !errors.Is(err, ErrTokenStale) {
 		t.Fatalf("UpdateCredentials err = %v, want ErrTokenStale", err)
 	}
 	if _, _, err := auth.Login(
 		ctx, "admin", "pass123", "", SessionMeta{ClientIP: "10.10.0.3"},
 	); err != nil {
 		t.Fatalf("old password should remain valid: %v", err)
 	}
 }
 // proofOf 取账号当前令牌版本组装快照(jti 空=不校验会话行),敏感调用测试用。
 func proofOf(t *testing.T, db *gorm.DB, username string) TokenProof {
 	t.Helper()
 	var user model.User
 	if err := db.Where("username = ?", username).First(&user).Error; err != nil {
 		t.Fatalf("find user: %v", err)
 	}
 	return TokenProof{Ver: user.TokenVersion}
 }
 func TestPasswordLoginToggle(t *testing.T) {
 	auth := newCredEnv(t)
 	ctx := context.Background()
 	// 未绑定外部身份不可禁用
-	if err := auth.SetPasswordLoginDisabled(ctx, "admin", true); !errors.Is(err, ErrNeedIdentity) {
+	if err := auth.SetPasswordLoginDisabled(ctx, "admin", true, proofOf(t, auth.db, "admin")); !errors.Is(err, ErrNeedIdentity) {
 		t.Fatalf("disable without identity: err = %v, want ErrNeedIdentity", err)
 	}
@@ -68,36 +110,73 @@ func TestPasswordLoginToggle(t *testing.T) {
 	if err := auth.db.Where("username = ?", "admin").First(&user).Error; err != nil {
 		t.Fatalf("find admin: %v", err)
 	}
-	ident := model.UserIdentity{UserID: user.ID, Provider: "github", Subject: "1", Display: "tester"}
+	// 用钱包身份:不依赖 provider 配置即可登录(github/oidc 身份须 provider 启用才计入)
 	ident := model.UserIdentity{UserID: user.ID, Provider: "wallet", Subject: "0xabc", Display: "tester"}
 	if err := auth.db.Create(&ident).Error; err != nil {
 		t.Fatalf("seed identity: %v", err)
 	}
-	if err := auth.SetPasswordLoginDisabled(ctx, "admin", true); err != nil {
+	if err := auth.SetPasswordLoginDisabled(ctx, "admin", true, proofOf(t, auth.db, "admin")); err != nil {
 		t.Fatalf("disable with identity: %v", err)
 	}
 	if off, err := auth.PasswordLoginDisabled(ctx); err != nil || !off {
 		t.Fatalf("PasswordLoginDisabled = %v, %v; want true", off, err)
 	}
 	// 密码登录被拒且不计失败(正确密码亦拒)
-	if _, _, err := auth.Login(ctx, "admin", "pass123", "127.0.0.1", ""); !errors.Is(err, ErrPasswordLoginDisabled) {
+	if _, _, err := auth.Login(ctx, "admin", "pass123", "", SessionMeta{ClientIP: "127.0.0.1"}); !errors.Is(err, ErrPasswordLoginDisabled) {
 		t.Fatalf("login while disabled: err = %v, want ErrPasswordLoginDisabled", err)
 	}
 	// 开关开着不能解绑最后一个身份
 	oauth := NewOAuthService(auth.db, nil, auth)
-	if err := oauth.Unbind(ctx, "admin", ident.ID); !errors.Is(err, ErrLastIdentity) {
+	if err := oauth.Unbind(ctx, "admin", ident.ID, proofOf(t, auth.db, "admin")); !errors.Is(err, ErrLastIdentity) {
 		t.Fatalf("unbind last identity: err = %v, want ErrLastIdentity", err)
 	}
 	// 恢复密码登录后可解绑、可登录
-	if err := auth.SetPasswordLoginDisabled(ctx, "admin", false); err != nil {
+	if err := auth.SetPasswordLoginDisabled(ctx, "admin", false, proofOf(t, auth.db, "admin")); err != nil {
 		t.Fatalf("enable password login: %v", err)
 	}
-	if err := oauth.Unbind(ctx, "admin", ident.ID); err != nil {
+	if err := oauth.Unbind(ctx, "admin", ident.ID, proofOf(t, auth.db, "admin")); err != nil {
 		t.Fatalf("unbind after enable: %v", err)
 	}
-	if _, _, err := auth.Login(ctx, "admin", "pass123", "127.0.0.3", ""); err != nil {
+	if _, _, err := auth.Login(ctx, "admin", "pass123", "", SessionMeta{ClientIP: "127.0.0.3"}); err != nil {
 		t.Errorf("login after enable: %v", err)
 	}
 }
 // TestPasswordLoginToggleWithPasskey 验证通行密钥计入禁用密码登录的门槛:
 // 仅有通行密钥即可开启;禁用期间最后一把钥匙受防自锁保护,身份可兜底解绑。
 func TestPasswordLoginToggleWithPasskey(t *testing.T) {
 	auth := newCredEnv(t)
 	ctx := context.Background()
 	pk := model.UserPasskey{
 		UserID: 1, Name: "k", CredentialID: "cred-1",
 		CredentialIDHash: "hash-1", Credential: "{}", Origin: "https://app.example.com",
 	}
 	if err := auth.db.Create(&pk).Error; err != nil {
 		t.Fatalf("seed passkey: %v", err)
 	}
 	// 无外部身份、仅通行密钥:可禁用密码登录
 	if err := auth.SetPasswordLoginDisabled(ctx, "admin", true, proofOf(t, auth.db, "admin")); err != nil {
 		t.Fatalf("disable with passkey only: %v", err)
 	}
 	// 禁用期间删除最后一把钥匙被拒(防自锁)
 	passkeys := NewPasskeyService(auth.db, auth.settings, auth)
 	if err := passkeys.Remove(ctx, "admin", pk.ID, proofOf(t, auth.db, "admin")); !errors.Is(err, ErrLastIdentity) {
 		t.Fatalf("remove last passkey: err = %v, want ErrLastIdentity", err)
 	}
 	// 绑定身份后钥匙可删;身份成为最后方式后解绑又被拒
 	ident := model.UserIdentity{UserID: 1, Provider: "wallet", Subject: "0xdef", Display: "t"}
 	if err := auth.db.Create(&ident).Error; err != nil {
 		t.Fatalf("seed identity: %v", err)
 	}
 	if err := passkeys.Remove(ctx, "admin", pk.ID, proofOf(t, auth.db, "admin")); err != nil {
 		t.Fatalf("remove passkey with identity fallback: %v", err)
 	}
 	oauth := NewOAuthService(auth.db, nil, auth)
 	if err := oauth.Unbind(ctx, "admin", ident.ID, proofOf(t, auth.db, "admin")); !errors.Is(err, ErrLastIdentity) {
 		t.Fatalf("unbind last identity: err = %v, want ErrLastIdentity", err)
 	}
 }
@@ -0,0 +1,89 @@
 package service
 import (
 	"encoding/hex"
 	"errors"
 	"fmt"
 	"strconv"
 	"strings"
 	"github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa"
 	"golang.org/x/crypto/sha3"
 )
 // 以太坊 personal_sign(EIP-191)验签工具:仅覆盖 EOA 签名恢复,
 // 不做 EIP-1271 合约钱包(需链上 RPC,超出自托管零依赖边界)。
 // errEthSig 是签名格式/恢复失败的内部标记;对外统一映射 ErrWalletSig。
 var errEthSig = errors.New("invalid ethereum signature")
 // keccak256 计算 Keccak-256 摘要(以太坊场景的非 NIST 填充变体)。
 func keccak256(data ...[]byte) []byte {
 	h := sha3.NewLegacyKeccak256()
 	for _, d := range data {
 		h.Write(d)
 	}
 	return h.Sum(nil)
 }
 // personalSignDigest 计算 EIP-191 personal_sign 摘要:
 // keccak256("\x19Ethereum Signed Message:\n" + 消息字节长度十进制 + 消息)。
 func personalSignDigest(msg []byte) []byte {
 	prefix := []byte("\x19Ethereum Signed Message:\n" + strconv.Itoa(len(msg)))
 	return keccak256(prefix, msg)
 }
 // recoverEthAddress 从 65 字节签名(r||s||v)恢复签名者地址(EIP-55 格式)。
 // v 兼容钱包生态的 27/28 与原始 0/1 两种取值;dcrec 的 compact 格式要求
 // 恢复位打头(27+v),与以太坊的尾置布局相反,需重排。
 func recoverEthAddress(digest, sig []byte) (string, error) {
 	if len(sig) != 65 {
 		return "", fmt.Errorf("%w: length %d", errEthSig, len(sig))
 	}
 	v := sig[64]
 	if v >= 27 {
 		v -= 27
 	}
 	if v > 1 {
 		return "", fmt.Errorf("%w: recovery id %d", errEthSig, sig[64])
 	}
 	compact := make([]byte, 65)
 	compact[0] = 27 + v
 	copy(compact[1:], sig[:64])
 	pub, _, err := ecdsa.RecoverCompact(compact, digest)
 	if err != nil {
 		return "", fmt.Errorf("%w: %v", errEthSig, err)
 	}
 	// 地址 = keccak256(未压缩公钥去掉 0x04 前缀)的后 20 字节
 	return eip55(keccak256(pub.SerializeUncompressed()[1:])[12:]), nil
 }
 // eip55 把 20 字节地址编码为 EIP-55 混合大小写校验和格式:
 // 对小写 hex 串取 keccak256,对应半字节 ≥ 8 的字母转大写。
 func eip55(addr []byte) string {
 	lower := hex.EncodeToString(addr)
 	sum := keccak256([]byte(lower))
 	out := []byte(lower)
 	for i, ch := range out {
 		nibble := sum[i/2] >> 4
 		if i%2 == 1 {
 			nibble = sum[i/2] & 0x0f
 		}
 		if ch >= 'a' && nibble >= 8 {
 			out[i] = ch - 'a' + 'A'
 		}
 	}
 	return "0x" + string(out)
 }
 // normalizeEthAddress 校验 0x+40hex 地址并返回 EIP-55 规范形;大小写不敏感。
 func normalizeEthAddress(addr string) (string, error) {
 	if len(addr) != 42 || !strings.HasPrefix(addr, "0x") {
 		return "", ErrWalletAddress
 	}
 	raw, err := hex.DecodeString(strings.ToLower(addr[2:]))
 	if err != nil {
 		return "", ErrWalletAddress
 	}
 	return eip55(raw), nil
 }
@@ -0,0 +1,136 @@
 package service
 import (
 	"encoding/hex"
 	"errors"
 	"strings"
 	"testing"
 	"github.com/decred/dcrd/dcrec/secp256k1/v4"
 	"github.com/decred/dcrd/dcrec/secp256k1/v4/ecdsa"
 )
 // ethAddrOf 从私钥派生 EIP-55 地址(keccak256(未压缩公钥[1:]) 后 20 字节)。
 func ethAddrOf(priv *secp256k1.PrivateKey) string {
 	return eip55(keccak256(priv.PubKey().SerializeUncompressed()[1:])[12:])
 }
 // testPrivKey 构造确定性的测试私钥;seed 填入 32 字节最低位。
 func testPrivKey(seed byte) *secp256k1.PrivateKey {
 	raw := make([]byte, 32)
 	raw[31] = seed
 	return secp256k1.PrivKeyFromBytes(raw)
 }
 // signPersonal 用 dcrec 标准路径生成 personal_sign 签名(r||s||v 的 hex);
 // legacyV 为 true 时 v 取 27/28,否则 0/1——两种取值链上钱包都会出现。
 func signPersonal(priv *secp256k1.PrivateKey, message string, legacyV bool) string {
 	compact := ecdsa.SignCompact(priv, personalSignDigest([]byte(message)), false)
 	sig := make([]byte, 65)
 	copy(sig, compact[1:])
 	v := compact[0] // 27 或 28(未压缩公钥)
 	if !legacyV {
 		v -= 27
 	}
 	sig[64] = v
 	return "0x" + hex.EncodeToString(sig)
 }
 // TestEip55Vectors 用 EIP-55 规范文档中的官方校验和向量。
 func TestEip55Vectors(t *testing.T) {
 	vectors := []string{
 		"0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
 		"0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359",
 		"0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB",
 		"0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb",
 	}
 	for _, want := range vectors {
 		t.Run(want[:10], func(t *testing.T) {
 			for _, input := range []string{strings.ToLower(want), "0x" + strings.ToUpper(want[2:])} {
 				got, err := normalizeEthAddress(input)
 				if err != nil {
 					t.Fatalf("normalizeEthAddress(%s): %v", input, err)
 				}
 				if got != want {
 					t.Errorf("normalizeEthAddress(%s) = %s, want %s", input, got, want)
 				}
 			}
 		})
 	}
 }
 func TestNormalizeEthAddressInvalid(t *testing.T) {
 	tests := []struct {
 		name string
 		in   string
 	}{
 		{name: "缺前缀", in: "5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed00"},
 		{name: "长度不足", in: "0x5aAeb6"},
 		{name: "非 hex 字符", in: "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAzz"},
 		{name: "空串", in: ""},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			if _, err := normalizeEthAddress(tt.in); !errors.Is(err, ErrWalletAddress) {
 				t.Errorf("normalizeEthAddress(%q) err = %v, want ErrWalletAddress", tt.in, err)
 			}
 		})
 	}
 }
 // TestKnownPrivKeyAddress 用公开锚点(私钥 0x…01 的以太坊地址)校验派生路径,
 // 防止 keccak / 公钥序列化环节自洽但整体错误。
 func TestKnownPrivKeyAddress(t *testing.T) {
 	got := ethAddrOf(testPrivKey(1))
 	want := "0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf"
 	if got != want {
 		t.Fatalf("address of privkey 0x01 = %s, want %s", got, want)
 	}
 }
 func TestRecoverEthAddressRoundTrip(t *testing.T) {
 	priv := testPrivKey(7)
 	addr := ethAddrOf(priv)
 	const msg = "demo.example.com wants you to sign in with your Ethereum account:\n0xabc"
 	tests := []struct {
 		name    string
 		sig     func() string
 		wantErr bool
 	}{
 		{name: "v=27/28", sig: func() string { return signPersonal(priv, msg, true) }},
 		{name: "v=0/1", sig: func() string { return signPersonal(priv, msg, false) }},
 		{name: "签名过短", sig: func() string { return "0x0102" }, wantErr: true},
 		{name: "v 非法", sig: func() string {
 			s := signPersonal(priv, msg, true)
 			return s[:len(s)-2] + "63" // v=99
 		}, wantErr: true},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			raw, err := hex.DecodeString(strings.TrimPrefix(tt.sig(), "0x"))
 			if err != nil {
 				t.Fatalf("decode sig: %v", err)
 			}
 			got, err := recoverEthAddress(personalSignDigest([]byte(msg)), raw)
 			if tt.wantErr {
 				if err == nil {
 					t.Fatal("recoverEthAddress: expected error, got nil")
 				}
 				return
 			}
 			if err != nil {
 				t.Fatalf("recoverEthAddress: %v", err)
 			}
 			if got != addr {
 				t.Errorf("recovered = %s, want %s", got, addr)
 			}
 		})
 	}
 	// 篡改消息:恢复出的地址必然不同
 	raw, _ := hex.DecodeString(strings.TrimPrefix(signPersonal(priv, msg, true), "0x"))
 	got, err := recoverEthAddress(personalSignDigest([]byte(msg+"x")), raw)
 	if err == nil && got == addr {
 		t.Error("tampered message still recovered the signer address")
 	}
 }
@@ -2,12 +2,36 @@ package service
 import (
 	"context"
 	"crypto/rand"
 	"encoding/hex"
 	"errors"
 	"fmt"
 	"io"
 	"path"
 	"strings"
 	"unicode"
 	"oci-portal/internal/oci"
 )
 // idpIconMaxBytes 是 IdP 图标上传上限;idpIconExts 是允许的图片扩展名。
 const (
 	idpIconMaxBytes    = 1 << 20
 	idpIconRandomBytes = 16
 )
 var idpIconExts = map[string]bool{
 	".png": true, ".jpg": true, ".jpeg": true, ".gif": true, ".svg": true, ".webp": true, ".ico": true,
 }
 // 图标校验错误哨兵:api 层据此映射 400 / 413 / 415,不落统一 500 边界。
 var (
 	ErrIdpIconEmpty    = errors.New("icon file is empty")
 	ErrIdpIconTooLarge = errors.New("icon exceeds 1MB")
 	ErrIdpIconBadType  = errors.New("icon file type not allowed")
 	ErrIdpIconBadName  = errors.New("icon file name is invalid")
 )
 // IdentityProviders 列出域内 SAML 身份提供者。
 func (s *OciConfigService) IdentityProviders(ctx context.Context, id uint, domainID string) ([]oci.IdentityProviderInfo, error) {
 	cred, homeRegion, err := s.credentialsAndHomeRegion(ctx, id)
@@ -34,7 +58,25 @@ func (s *OciConfigService) CreateIdentityProvider(ctx context.Context, id uint,
 	if err != nil {
 		return oci.IdentityProviderInfo{}, err
 	}
-	return s.client.CreateSamlIdentityProvider(ctx, cred, homeRegion, domainID, normalizeIdpInput(in))
+	in, err = s.enforceIdpDomainSettings(ctx, cred, homeRegion, domainID, normalizeIdpInput(in))
 	if err != nil {
 		return oci.IdentityProviderInfo{}, err
 	}
 	return s.client.CreateSamlIdentityProvider(ctx, cred, homeRegion, domainID, in)
 }
 func (s *OciConfigService) enforceIdpDomainSettings(ctx context.Context, cred oci.Credentials, region, domainID string, in oci.CreateIdpInput) (oci.CreateIdpInput, error) {
 	if !in.JitEnabled {
 		return in, nil
 	}
 	setting, err := s.client.GetIdentitySetting(ctx, cred, region, domainID)
 	if err != nil {
 		return in, fmt.Errorf("get identity setting before create idp: %w", err)
 	}
 	if setting.PrimaryEmailRequired {
 		in.JitMapEmail = true
 	}
 	return in, nil
 }
 // normalizeIdpInput 填充映射字段的控制台默认值：名称 ID 格式「无」、
@@ -97,6 +139,135 @@ func (s *OciConfigService) DomainSamlMetadata(ctx context.Context, id uint, doma
 	return s.client.DownloadDomainSamlMetadata(ctx, cred, homeRegion, domainID)
 }
 // UploadIdpIcon 上传 IdP 图标到身份域公共图片存储,返回公网地址与存储内文件名。
 func (s *OciConfigService) UploadIdpIcon(ctx context.Context, id uint, domainID, fileName string, data []byte) (string, string, error) {
 	return s.uploadIdpIcon(ctx, id, domainID, fileName, data, rand.Reader)
 }
 func (s *OciConfigService) uploadIdpIcon(ctx context.Context, id uint, domainID, fileName string, data []byte, random io.Reader) (string, string, error) {
 	if len(data) == 0 {
 		return "", "", fmt.Errorf("upload idp icon: %w", ErrIdpIconEmpty)
 	}
 	if len(data) > idpIconMaxBytes {
 		return "", "", fmt.Errorf("upload idp icon: %w", ErrIdpIconTooLarge)
 	}
 	fileName, err := validateIdpIcon(fileName, data)
 	if err != nil {
 		return "", "", fmt.Errorf("upload idp icon: %w", err)
 	}
 	fileName, err = newIdpIconStorageName(fileName, random)
 	if err != nil {
 		return "", "", fmt.Errorf("upload idp icon: %w", err)
 	}
 	cred, homeRegion, err := s.credentialsAndHomeRegion(ctx, id)
 	if err != nil {
 		return "", "", err
 	}
 	url, storedName, err := s.client.UploadDomainImage(ctx, cred, homeRegion, domainID, fileName, data)
 	if err != nil {
 		return "", "", fmt.Errorf("upload idp icon: %w", err)
 	}
 	return url, storedName, nil
 }
 func newIdpIconStorageName(fileName string, random io.Reader) (string, error) {
 	token := make([]byte, idpIconRandomBytes)
 	if _, err := io.ReadFull(random, token); err != nil {
 		return "", fmt.Errorf("generate storage name: %w", err)
 	}
 	ext := strings.ToLower(path.Ext(fileName))
 	return "idp-icon-" + hex.EncodeToString(token) + ext, nil
 }
 // DeleteIdpIcon 按上传响应中的 fileName 删除身份域公开图片。
 func (s *OciConfigService) DeleteIdpIcon(ctx context.Context, id uint, domainID, fileName string) error {
 	if err := validateDomainImageFileName(fileName); err != nil {
 		return fmt.Errorf("delete idp icon: %w", err)
 	}
 	cred, homeRegion, err := s.credentialsAndHomeRegion(ctx, id)
 	if err != nil {
 		return err
 	}
 	if err := s.client.DeleteDomainImage(ctx, cred, homeRegion, domainID, fileName); err != nil {
 		return fmt.Errorf("delete idp icon: %w", err)
 	}
 	return nil
 }
 func validateIdpIcon(input string, data []byte) (string, error) {
 	fileName := path.Base(strings.ReplaceAll(input, "\\", "/"))
 	if invalidIconName(fileName, 255) {
 		return "", ErrIdpIconBadName
 	}
 	ext := strings.ToLower(path.Ext(fileName))
 	if !idpIconExts[ext] || !iconMagicOK(ext, data) {
 		return "", fmt.Errorf("%w: %q", ErrIdpIconBadType, ext)
 	}
 	return fileName, nil
 }
 func validateDomainImageFileName(fileName string) error {
 	if invalidIconName(fileName, 1024) || strings.Contains(fileName, "\\") {
 		return ErrIdpIconBadName
 	}
 	clean := path.Clean(fileName)
 	if clean != fileName || path.Dir(clean) != "images" || !validIdpIconStorageBase(path.Base(clean)) {
 		return ErrIdpIconBadName
 	}
 	return nil
 }
 func validIdpIconStorageBase(fileName string) bool {
 	ext := path.Ext(fileName)
 	if ext == "" || ext != strings.ToLower(ext) || !idpIconExts[ext] {
 		return false
 	}
 	stem := strings.TrimSuffix(fileName, ext)
 	if !strings.HasPrefix(stem, "idp-icon-") {
 		return false
 	}
 	token := strings.TrimPrefix(stem, "idp-icon-")
 	if len(token) != hex.EncodedLen(idpIconRandomBytes) || token != strings.ToLower(token) {
 		return false
 	}
 	_, err := hex.DecodeString(token)
 	return err == nil
 }
 func invalidIconName(fileName string, maxBytes int) bool {
 	return fileName == "" || fileName == "." || fileName == ".." ||
 		len(fileName) > maxBytes || strings.TrimSpace(fileName) != fileName ||
 		strings.IndexFunc(fileName, unicode.IsControl) >= 0
 }
 // iconMagicOK 用文件头魔数轻量核对扩展名与内容大体一致。不做深度解码:
 // 图标由管理员为自己租户上传,存储与服务均在 Oracle 域名侧,传错内容只会
 // 让自己登录页图标裂开,深度校验的收益承担不起其复杂度与误伤。
 func iconMagicOK(ext string, data []byte) bool {
 	has := func(prefix string) bool {
 		return len(data) >= len(prefix) && string(data[:len(prefix)]) == prefix
 	}
 	switch ext {
 	case ".png":
 		return has("\x89PNG\r\n\x1a\n")
 	case ".jpg", ".jpeg":
 		return len(data) >= 3 && data[0] == 0xff && data[1] == 0xd8 && data[2] == 0xff
 	case ".gif":
 		return has("GIF87a") || has("GIF89a")
 	case ".webp":
 		return len(data) >= 12 && string(data[:4]) == "RIFF" && string(data[8:12]) == "WEBP"
 	case ".ico":
 		return len(data) >= 4 && data[0] == 0 && data[1] == 0 && data[2] == 1 && data[3] == 0
 	case ".svg":
 		head := data
 		if len(head) > 512 {
 			head = head[:512]
 		}
 		return strings.Contains(strings.ToLower(string(head)), "<svg")
 	}
 	return false
 }
 // ConsoleSignOnRules 按优先级列出 OCI Console sign-on 策略的规则。
 func (s *OciConfigService) ConsoleSignOnRules(ctx context.Context, id uint, domainID string) ([]oci.SignOnRuleInfo, error) {
 	cred, homeRegion, err := s.credentialsAndHomeRegion(ctx, id)
@@ -0,0 +1,227 @@
 package service
 import (
 	"bytes"
 	"context"
 	"errors"
 	"strings"
 	"testing"
 	"oci-portal/internal/oci"
 )
 type idpIconStubClient struct {
 	*fakeClient
 	uploadedNames []string
 }
 type idpCreateStubClient struct {
 	*fakeClient
 	setting      oci.IdentitySettingInfo
 	settingErr   error
 	settingCalls int
 	createCalls  int
 	createdInput oci.CreateIdpInput
 }
 func (c *idpIconStubClient) UploadDomainImage(_ context.Context, _ oci.Credentials, _, _, fileName string, _ []byte) (string, string, error) {
 	c.uploadedNames = append(c.uploadedNames, fileName)
 	return "https://images.example/" + fileName, "images/" + fileName, nil
 }
 func (c *idpCreateStubClient) GetIdentitySetting(_ context.Context, _ oci.Credentials, _, _ string) (oci.IdentitySettingInfo, error) {
 	c.settingCalls++
 	return c.setting, c.settingErr
 }
 func (c *idpCreateStubClient) CreateSamlIdentityProvider(_ context.Context, _ oci.Credentials, _, _ string, in oci.CreateIdpInput) (oci.IdentityProviderInfo, error) {
 	c.createCalls++
 	c.createdInput = in
 	return oci.IdentityProviderInfo{Name: in.Name}, nil
 }
 type failingIconRandom struct{}
 func (failingIconRandom) Read([]byte) (int, error) {
 	return 0, errors.New("entropy unavailable")
 }
 func newIdpIconTestService(t *testing.T) (*OciConfigService, *idpIconStubClient, uint) {
 	t.Helper()
 	base := &fakeClient{tenancy: oci.TenancyInfo{Name: "t", HomeRegionKey: "FRA"}}
 	client := &idpIconStubClient{fakeClient: base}
 	service := newTestService(t, client)
 	return service, client, importAliveConfig(t, service).ID
 }
 func newIdpCreateTestService(t *testing.T) (*OciConfigService, *idpCreateStubClient, uint) {
 	t.Helper()
 	base := &fakeClient{tenancy: oci.TenancyInfo{Name: "t", HomeRegionKey: "FRA"}}
 	client := &idpCreateStubClient{fakeClient: base}
 	service := newTestService(t, client)
 	return service, client, importAliveConfig(t, service).ID
 }
 func testCreateIdpInput(jitEnabled bool) oci.CreateIdpInput {
 	return oci.CreateIdpInput{
 		Name: "test-idp", Metadata: "<EntityDescriptor/>", JitEnabled: jitEnabled,
 	}
 }
 // iconFixture 生成带正确文件头魔数的最小样本;精简校验只核对魔数,不做深度解码。
 func iconFixture(ext string) []byte {
 	switch ext {
 	case ".png":
 		return append([]byte("\x89PNG\r\n\x1a\n"), 0, 0, 0, 0)
 	case ".jpg", ".jpeg":
 		return []byte{0xff, 0xd8, 0xff, 0xe0, 0, 0}
 	case ".gif":
 		return []byte("GIF89a\x00\x00")
 	case ".webp":
 		return []byte("RIFF\x00\x00\x00\x00WEBPVP8 ")
 	case ".ico":
 		return []byte{0, 0, 1, 0, 1, 0}
 	case ".svg":
 		return []byte(`<svg xmlns="http://www.w3.org/2000/svg"/>`)
 	}
 	return nil
 }
 func TestValidateIdpIconAcceptsMatchingContent(t *testing.T) {
 	for _, ext := range []string{".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".svg"} {
 		t.Run(ext, func(t *testing.T) {
 			fileName := "icon" + ext
 			got, err := validateIdpIcon(fileName, iconFixture(ext))
 			if err != nil || got != fileName {
 				t.Errorf("validateIdpIcon = %q, %v; want %q, nil", got, err, fileName)
 			}
 		})
 	}
 }
 func TestCreateIdentityProviderForcesEmailMapping(t *testing.T) {
 	service, client, configID := newIdpCreateTestService(t)
 	client.setting.PrimaryEmailRequired = true
 	_, err := service.CreateIdentityProvider(context.Background(), configID, "domain", testCreateIdpInput(true))
 	if err != nil {
 		t.Fatalf("CreateIdentityProvider: %v", err)
 	}
 	if client.settingCalls != 1 || client.createCalls != 1 {
 		t.Fatalf("calls = setting:%d create:%d; want 1, 1", client.settingCalls, client.createCalls)
 	}
 	if !client.createdInput.JitMapEmail {
 		t.Error("JitMapEmail = false, want true for primary-email-required domain")
 	}
 }
 func TestCreateIdentityProviderStopsWhenSettingFails(t *testing.T) {
 	service, client, configID := newIdpCreateTestService(t)
 	client.settingErr = errors.New("setting unavailable")
 	_, err := service.CreateIdentityProvider(context.Background(), configID, "domain", testCreateIdpInput(true))
 	if err == nil || !strings.Contains(err.Error(), "get identity setting") {
 		t.Fatalf("CreateIdentityProvider error = %v, want setting failure", err)
 	}
 	if client.settingCalls != 1 || client.createCalls != 0 {
 		t.Errorf("calls = setting:%d create:%d; want 1, 0", client.settingCalls, client.createCalls)
 	}
 }
 func TestCreateIdentityProviderSkipsSettingWithoutJIT(t *testing.T) {
 	service, client, configID := newIdpCreateTestService(t)
 	client.settingErr = errors.New("must not be called")
 	_, err := service.CreateIdentityProvider(context.Background(), configID, "domain", testCreateIdpInput(false))
 	if err != nil {
 		t.Fatalf("CreateIdentityProvider: %v", err)
 	}
 	if client.settingCalls != 0 || client.createCalls != 1 {
 		t.Errorf("calls = setting:%d create:%d; want 0, 1", client.settingCalls, client.createCalls)
 	}
 }
 func TestUploadIdpIconUsesUniqueServerNames(t *testing.T) {
 	service, client, configID := newIdpIconTestService(t)
 	data := iconFixture(".png")
 	randomData := append(bytes.Repeat([]byte{0x11}, idpIconRandomBytes), bytes.Repeat([]byte{0x22}, idpIconRandomBytes)...)
 	random := bytes.NewReader(randomData)
 	storedNames := make([]string, 2)
 	for index := range storedNames {
 		_, storedName, err := service.uploadIdpIcon(context.Background(), configID, "domain", "Logo.PNG", data, random)
 		if err != nil {
 			t.Fatalf("upload %d: %v", index, err)
 		}
 		storedNames[index] = storedName
 	}
 	wants := []string{"idp-icon-" + strings.Repeat("11", idpIconRandomBytes) + ".png", "idp-icon-" + strings.Repeat("22", idpIconRandomBytes) + ".png"}
 	for index, want := range wants {
 		if client.uploadedNames[index] != want || storedNames[index] != "images/"+want {
 			t.Errorf("upload %d = %q, %q; want %q, %q", index, client.uploadedNames[index], storedNames[index], want, "images/"+want)
 		}
 	}
 }
 func TestUploadIdpIconRandomFailureSkipsUpstream(t *testing.T) {
 	service, client, configID := newIdpIconTestService(t)
 	_, _, err := service.uploadIdpIcon(context.Background(), configID, "domain", "logo.png", iconFixture(".png"), failingIconRandom{})
 	if err == nil || !strings.Contains(err.Error(), "generate storage name") {
 		t.Fatalf("UploadIdpIcon error = %v, want random source failure", err)
 	}
 	if len(client.uploadedNames) != 0 {
 		t.Errorf("upstream upload calls = %d, want 0", len(client.uploadedNames))
 	}
 }
 type iconRejectCase struct {
 	name, fileName string
 	data           []byte
 	want           error
 }
 func assertIconRejected(t *testing.T, cases []iconRejectCase) {
 	t.Helper()
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
 			_, err := validateIdpIcon(tc.fileName, tc.data)
 			if !errors.Is(err, tc.want) {
 				t.Errorf("err = %v, want errors.Is(%v)", err, tc.want)
 			}
 		})
 	}
 }
 func TestValidateIdpIconRejectsSpoofedContent(t *testing.T) {
 	assertIconRejected(t, []iconRejectCase{
 		{"extension mismatch", "icon.jpg", iconFixture(".png"), ErrIdpIconBadType},
 		{"random bytes as png", "icon.png", []byte("not an image"), ErrIdpIconBadType},
 		{"unsupported extension", "icon.bmp", iconFixture(".png"), ErrIdpIconBadType},
 	})
 }
 func TestValidateIdpIconRejectsBadNames(t *testing.T) {
 	assertIconRejected(t, []iconRejectCase{
 		{"control name", "bad\r\n.png", iconFixture(".png"), ErrIdpIconBadName},
 		{"long name", strings.Repeat("a", 252) + ".png", iconFixture(".png"), ErrIdpIconBadName},
 	})
 }
 func TestValidateDomainImageFileName(t *testing.T) {
 	token := strings.Repeat("ab", idpIconRandomBytes)
 	cases := []struct {
 		name, fileName string
 		valid          bool
 	}{
 		{"generated image", "images/idp-icon-" + token + ".png", true},
 		{"empty", "", false}, {"wrong prefix", "icons/a.png", false},
 		{"traversal", "images/a/../secret", false}, {"backslash", `images\a.png`, false},
 		{"control", "images/a\x00.png", false}, {"directory", "images/", false},
 		{"unrelated domain image", "images/company-brand.png", false},
 		{"nested image", "images/generated/idp-icon-" + token + ".png", false},
 		{"uppercase token", "images/idp-icon-" + strings.ToUpper(token) + ".png", false},
 		{"wrong token length", "images/idp-icon-ab.png", false},
 	}
 	for _, tc := range cases {
 		err := validateDomainImageFileName(tc.fileName)
 		if (err == nil) != tc.valid {
 			t.Errorf("%s: err = %v, valid = %v", tc.name, err, tc.valid)
 		}
 	}
 }
@@ -37,6 +37,9 @@ func (s *OciConfigService) CreateInstances(ctx context.Context, id uint, in oci.
 	if count < 1 || count > maxBatchCreate {
 		return nil, nil, fmt.Errorf("create instances: count must be between 1 and %d", maxBatchCreate)
 	}
 	if in.ReservedPublicIPID != "" && count > 1 {
 		return nil, nil, fmt.Errorf("create instances: reserved public ip only supports single instance")
 	}
 	if err := validateCreateInstance(in); err != nil {
 		return nil, nil, err
 	}
@@ -59,6 +62,10 @@ func (s *OciConfigService) CreateInstances(ctx context.Context, id uint, in oci.
 			failures = append(failures, fmt.Sprintf("%s: %s", one.DisplayName, oci.CompactError(err)))
 			continue
 		}
 		if one.ReservedPublicIPID != "" {
 			region, instanceID, ipID := one.Region, instance.ID, one.ReservedPublicIPID
 			s.goBind(func() { s.bindReservedIPWhenReady(cred, region, instanceID, ipID) })
 		}
 		instances = append(instances, instance)
 	}
 	return instances, failures, nil
@@ -554,6 +554,8 @@ func envActor(env onsEnvelope) string {
 // envOutcome 判读事件成败与补充说明:登录事件解析 auditEventMapValue;其余
 // Audit 事件看 message 后缀,补充说明取 stateChange.current.description(策略描述)。
 // 计算类失败形如 "LaunchInstance failed with response 'NotAuthorizedOrNotFound'",
 // 判失败并以引号内错误码作补充说明(无其他说明时)。
 func envOutcome(env onsEnvelope) (outcome, detail string) {
 	if env.StateChange != nil {
 		detail = env.StateChange.Current.Description
@@ -566,10 +568,24 @@ func envOutcome(env onsEnvelope) (outcome, detail string) {
 		outcome = "成功"
 	case strings.HasSuffix(env.Message, " failed"):
 		outcome = "失败"
 	case strings.Contains(env.Message, " failed with response "):
 		outcome = "失败"
 		if detail == "" {
 			detail = failedResponse(env.Message)
 		}
 	}
 	return outcome, detail
 }
 // failedResponse 提取 "X failed with response 'Err'" 中引号内的错误码。
 func failedResponse(msg string) string {
 	_, after, ok := strings.Cut(msg, " failed with response ")
 	if !ok {
 		return ""
 	}
 	return strings.Trim(strings.TrimSpace(after), "'")
 }
 // ssoOutcome 解析 IDCS 审计负载(JSON 字符串):eventId 含 success/failure 定成败,
 // 失败时以其 message 作为原因说明。
 func ssoOutcome(raw, detail string) (string, string) {
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
wangdefa	23b2820101	发布 v0.8.3 CI / test (push) Successful in 22s Details Release / release (push) Successful in 44s Details	2026-07-30 12:44:14 +08:00
wangdefa	109c345e5e	新增活跃会话管理与通行密钥、钱包登录 CI / test (push) Successful in 55s Details	2026-07-30 12:23:05 +08:00
wangdefa	f1914880ac	发布 v0.8.2 CI / test (push) Successful in 21s Details Release / release (push) Successful in 54s Details	2026-07-22 22:15:23 +08:00
wangdefa	a95a8255bf	用户 API Key 管理:增删查、启用签名凭据;升级 SDK CI / test (push) Successful in 48s Details	2026-07-22 19:38:14 +08:00
wangdefa	8894330eba	发布 v0.8.1 CI / test (push) Successful in 21s Details Release / release (push) Successful in 42s Details	2026-07-22 17:10:58 +08:00
wangdefa	f51fb6c722	修复全量审查问题;设置接口PATCH化;回传指纹加固 CI / test (push) Successful in 32s Details	2026-07-22 16:51:23 +08:00
wangdefa	0614ef22af	发布 v0.8.0 CI / test (push) Successful in 22s Details Release / release (push) Successful in 51s Details	2026-07-21 19:43:02 +08:00
wangdefa	33e92a65e2	成本查询限窗过滤;桶级 PAR 放开列举 CI / test (push) Successful in 35s Details	2026-07-21 19:26:33 +08:00
wangdefa	f40f2a20e8	新增对象存储/账单/保留IP模块,删桶并发提速与成本增强 CI / test (push) Successful in 33s Details	2026-07-21 12:11:05 +08:00
wangdefa	9cfde8b702	发布 v0.7.3 CI / test (push) Successful in 20s Details Release / release (push) Successful in 58s Details	2026-07-17 17:09:06 +08:00
wangdefa	deea8629e0	实例规格透传 quotaNames,重新生成 swagger CI / test (push) Successful in 31s Details	2026-07-17 16:52:49 +08:00
wangdefa	6cf9465fea	云端事件:修复实例通知并移出 LaunchInstance 回传	2026-07-17 16:52:49 +08:00
wangdefa	882eeade1e	修复跨区间缓存串数据与会话回收泄漏,收敛网关重试 CI / test (push) Successful in 29s Details	2026-07-17 12:19:21 +08:00
wangdefa	7019d4c5a6	文档:记录 multi-agent 加密推理流式断流问题	2026-07-17 12:19:21 +08:00