3.7 KiB
3.7 KiB
交互设计 · Key 管理
key 的全生命周期操作面：登记（sk-key 明文在 web 界面的唯一露面处）、启停（纯手动，无自动摘除）、归属分配、死亡显形。
| 项目 | 内容 |
|---|---|
| 状态 | 定稿（2026-10-01） |
| 关联 | 《交互设计-总览与共性》· api_keys表字段设计.md（字段与 3.6 生命周期）· R2（已裁决：引擎记录不决策） |
| 数据 | api_keys 全表 · 引擎轮次摘要（失败明细） |
1. Key 清单（页面主体）
| 列 | 内容 | 备注 |
|---|---|---|
| 名称 | token_name（上游同步） |
展示名以它为准（上游改名随轮询更新） |
| 归属 | 成员名徽章 / 「未归属」 | 行内下拉可直接改归属（见 §4） |
| 账本域 | billing_domain / 「—」 |
行内可编辑（联想输入，防抖落盘）；列表可按域筛，含「未标注」 |
| 状态 | active / disabled 徽章 |
disabled 灰态 |
| 数据截止 | log_synced_at |
停滞预警：落后 > 2 小时 → 该单元格黄色标注「停滞」+ hover 提示「检查引擎日志；若持续 401 请停用」 |
| 累计已用 / 剩余 | total_used / total_available + unlimited_quota 分支 |
「剩余：不限」分支 |
| 登记时间 | registered_at |
- 筛选：按成员、按状态、按「最近轮次失败」；排序默认按数据截止降序（异常在前）
- 页面顶部：健康摘要行（本页相关的失败 key 数）
2. 登记（sk-key 的唯一界面露面）
入口：「登记 Key」按钮 → 对话框：
- sk-key 粘贴框（大号单行，paste 友好）——页脚安全注记：「粘贴后立即加密存储，界面不再回显明文」
- 归属成员下拉（默认「未归属」，可后改；下拉旁附「+ 新建成员」快捷入口——缝合「开户 → 发令牌 → 开 key」的跨页流程断点，见《交互设计-成员管理》）
2b. 账本域输入（可空，已有值联想；与支付记录的
billing_domain同语义） - 提交 → 服务端上游验证，四态反馈：
| 结果 | 反馈 |
|---|---|
| 成功 | 「已登记，首轮同步进行中（约 5 分钟内完成）」→ 清单出现新行，「数据截止」显示「同步中…」 |
| 已登记（hash 命中） | 「该 key 已在清单中」（定位到那行） |
| 上游拒绝（401） | 「上游拒绝了这枚 key——可能不存在或已被禁用」 |
| 上游暂不可用 | 「上游站点暂时不可达，请稍后重试」 |
3. 启停（纯手动，已裁决无自动摘除）
- 停用：行操作 → 确认弹窗「停用后移出轮询清单（数据保留）。成员若仍在用它调用 API 不受影响——只有采集停止」→
status = disabled - 启用：行操作 → 「已启用——下一轮同步（≤5 分钟）将自动验证，结果见数据截止」（无人工预验证环节，引擎即验证器）
- 死亡处置推荐流（对持续 401 的 key）：数据截止停滞 → 你查看引擎日志确认 → 停用 → 找运营方 → 修复后启用。界面在停滞标注的 hover 中给出这条指引文案（把「引擎记录不决策」的操作闭环写进提示里）
4. 归属 / 账本域变更
- 归属：清单行内下拉直接切换（含「未归属」选项）——即时生效，无确认弹窗（低风险、可逆）
- 账本域：行内联想输入，防抖保存（失焦落盘）；可清空为未标域
- 变更后统计自动按新归属呈现（行级联查当前归属——表设计 3.8 语义）；账本域影响成员支付参数可见性
5. 空态
- 无 key：引导文案「还没有登记任何 key——把你在 NewAPI 创建的 sk-key 粘贴进来」+ 登记按钮常驻