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.
2.9 KiB
2.9 KiB
Portal Key Experience
日期：2026-06-05 状态：已审核通过 适用版本：vNext.2
目的
定义用户 portal 中 key 自助申请与首次调用体验的状态机、信息架构与边界，避免页面承诺超过宿主真实能力。
信息架构
用户页最少展示：
- 我的 key
- key 当前状态
- 该 key 可用模型 / 逻辑分组
- base URL
- curl 示例
- 首次调用指引
- 最近一次失败原因（如有）
禁止向用户直接暴露：
- 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 后，页面必须最短路径支持：
- 复制 key
- 复制 base URL
- 复制 curl 示例
- 选择一个已验证通过的 public model
- 看到明确成功标准：
POST /v1/chat/completions = 200
文案约束
必须避免：
- 承诺“所有模型都可用”
- 承诺“稳定负载均衡”
- 用
/v1/models成功暗示真实可调
推荐文案：
- “以下模型基于当前已验证链路提供”
- “是否可进入默认链路以当前用户调用验证为准”
- “明文 key 仅首次显示一次”
页面块建议
- 概览卡
- key 列表卡
- 创建 key / 重置 key 操作区
- 使用示例区
- 状态与故障说明区
- 支持与说明区
验收要求
至少覆盖：
- 未登录
- 无 key
- 首次创建成功
- 已有 key 无明文
- paused
- quota exhausted
- model unavailable
- 示例调用成功
- 示例调用失败
与本轮范围关系
本文件属于 vNext.2 设计文档。 在当前 vNext.1 审核阶段，只作为后续设计真相源，不进入 UI 实现。