# 交互设计 · 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」按钮 → 对话框：

1. **sk-key 粘贴框**（大号单行，paste 友好）——页脚安全注记：「粘贴后立即加密存储，界面不再回显明文」
2. 归属成员下拉（默认「未归属」，可后改；下拉旁附「+ 新建成员」快捷入口——缝合「开户 → 发令牌 → 开 key」的跨页流程断点，见《交互设计-成员管理》）
2b. 账本域输入（可空，已有值联想；与支付记录的 `billing_domain` 同语义）
3. 提交 → 服务端上游验证，四态反馈：

| 结果 | 反馈 |
|------|------|
| 成功 | 「已登记，首轮同步进行中（约 5 分钟内完成）」→ 清单出现新行，「数据截止」显示「同步中…」 |
| 已登记（hash 命中） | 「该 key 已在清单中」（定位到那行） |
| 上游拒绝（401） | 「上游拒绝了这枚 key——可能不存在或已被禁用」 |
| 上游暂不可用 | 「上游站点暂时不可达，请稍后重试」 |

## 3. 启停（纯手动，已裁决无自动摘除）

- **停用**：行操作 → 确认弹窗「停用后移出轮询清单（数据保留）。成员若仍在用它调用 API 不受影响——只有采集停止」→ `status = disabled`
- **启用**：行操作 → 「已启用——下一轮同步（≤5 分钟）将自动验证，结果见数据截止」（无人工预验证环节，引擎即验证器）
- **死亡处置推荐流**（对持续 401 的 key）：数据截止停滞 → 你查看引擎日志确认 → 停用 → 找运营方 → 修复后启用。界面在停滞标注的 hover 中给出这条指引文案（把「引擎记录不决策」的操作闭环写进提示里）

## 4. 归属 / 账本域变更

- 归属：清单行内下拉直接切换（含「未归属」选项）——即时生效，无确认弹窗（低风险、可逆）
- 账本域：行内联想输入，防抖保存（失焦落盘）；可清空为未标域
- 变更后统计自动按新归属呈现（行级联查当前归属——表设计 3.8 语义）；账本域影响成员支付参数可见性

## 5. 空态

- 无 key：引导文案「还没有登记任何 key——把你在 NewAPI 创建的 sk-key 粘贴进来」+ 登记按钮常驻