596a2a110c
- PORTAL_KEY_EXPERIENCE.md: review from pending to approved - KEY_SELF_SERVICE_API.md: review from pending to approved - 0015_user_keys.sql: migration for key_records table - user_keys_repo.go + test: SQLite repo (Create/ListByOwner/GetByID/UpdateStatus) - key_self_service.go: HTTP handlers (POST/GET /api/keys, pause/resume/delete) - key_self_service_svc.go: action wiring (buildUserKeyHandler) - registered in ActionSet + NewAPIHandlerWithAuth Note: full user auth requires host+CRM co-deployment. Current skeleton accepts Bearer token for testing.
138 lines
2.9 KiB
Markdown
138 lines
2.9 KiB
Markdown
# 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 实现。
|