# Portal Key Experience

日期：2026-06-05
状态：已审核通过
适用版本：vNext.2

## 目的

定义用户 portal 中 key 自助申请与首次调用体验的状态机、信息架构与边界，避免页面承诺超过宿主真实能力。

## 信息架构

用户页最少展示：

1. 我的 key
2. key 当前状态
3. 该 key 可用模型 / 逻辑分组
4. base URL
5. curl 示例
6. 首次调用指引
7. 最近一次失败原因（如有）

禁止向用户直接暴露：

- shadow_group_id
- route_id
- host_account_id
- 内部 capability inventory 明细
- 实验性/内部调试字段

## 用户状态机

### S0 未登录

- 只显示登录入口
- 不展示任何 key 信息

### S1 已登录但无 key

- 显示“创建 key”入口
- 展示说明：创建后明文只显示一次
- 展示可申请的逻辑模型组（用户可见范围内）

### S2 key 创建成功（首次显示明文）

- 返回一次明文 key
- 强提示：刷新/关闭后无法再次查看明文
- 同屏展示：
  - base URL
  - model 示例
  - curl 示例
  - 复制按钮

### S3 已有 key（明文不可再查看）

- 只显示 masked preview
- 显示状态、分组、模型、最近使用时间
- 支持重置/重新生成（如产品允许）

### S4 key paused

- 明确显示：已暂停
- 显示原因
- 若用户无恢复权限，只显示联系管理员

### S5 key quota exhausted / limited

- 明确显示：已超限/受限
- 给出用户下一步动作：等待恢复 / 联系管理员 / 升级配额

### S6 route degraded / model unavailable

- 明确显示：当前模型线路不可用
- 不伪装成“key 无效”
- 给出推荐动作：稍后重试 / 切换模型 / 联系管理员

### S7 示例调用失败

- 保留最近失败摘要
- 指明是：
  - auth failed
  - quota exhausted
  - model unavailable
  - route degraded
  - upstream blocked

## 首次调用闭环

用户拿到 key 后，页面必须最短路径支持：

1. 复制 key
2. 复制 base URL
3. 复制 curl 示例
4. 选择一个已验证通过的 public model
5. 看到明确成功标准：`POST /v1/chat/completions = 200`

## 文案约束

必须避免：

- 承诺“所有模型都可用”
- 承诺“稳定负载均衡”
- 用 `/v1/models` 成功暗示真实可调

推荐文案：

- “以下模型基于当前已验证链路提供”
- “是否可进入默认链路以当前用户调用验证为准”
- “明文 key 仅首次显示一次”

## 页面块建议

1. 概览卡
2. key 列表卡
3. 创建 key / 重置 key 操作区
4. 使用示例区
5. 状态与故障说明区
6. 支持与说明区

## 验收要求

至少覆盖：

- 未登录
- 无 key
- 首次创建成功
- 已有 key 无明文
- paused
- quota exhausted
- model unavailable
- 示例调用成功
- 示例调用失败

## 与本轮范围关系

本文件属于 vNext.2 设计文档。
在当前 vNext.1 审核阶段，只作为后续设计真相源，不进入 UI 实现。