# 交互设计 · 总览与共性

> 交互层的定位、访问拓扑与跨页共性约定——所有功能页设计篇（登录、总览、key 管理、支付记录、成员管理、审计、成员视图）共用本文的规则。**双形态通用**：前端与部署形态无关（母体与 CFW 抽取版共用同一交互层），形态差异只在部署与运行时通道。

| 项目 | 内容 |
|------|------|
| 状态 | 定稿（2026-10-01） |
| 关联 | `需求清单.md`（R 编号与裁决记录——本文全部设计的依据）· 各篇表字段设计（数据来源） |
| 产出 | 访问拓扑、导航结构、跨页组件、状态模式、数值与时间呈现 |

---

## 1. 访问拓扑：两个互不可见的世界

```svg
（拓扑见下文描述，实现时以此为准）
```

- **管理面**（作者专属）：入口为登录页（账号密码）→ 侧边栏布局；空库时按三态分流（见《交互设计-登录与会话》）；地址栏访问 `/admin`（根路径不指向此处）
- **成员视图**（成员专属）：入口为登录壳（令牌）→ 侧边栏布局（与管理端同构壳，菜单三项：总览 / 调用日志 / 支付参数）；与管理面物理隔离（两套路由、两套凭证中间件，令牌进不了管理面，会话进不了成员视图）；**根路径 `/` 默认进入本世界**（未知路径同样回退到此）
- **没有第三种入口**：无开放查询页、无游客态、无分发页；根地址即成员入口。管理面的入口形态待定（当前经地址栏 `/admin` 进入）
- 401 分流统一约定：管理面任意请求 401 → 登录页（提示「会话已过期」）；成员视图任意请求 401 → 登录壳（提示「令牌无效或已停用」）——各自回各自的家，不交叉

## 2. 管理面导航：侧边栏

- 左侧固定侧边栏，结构（自上而下）：

| 菜单 | 页面 | 职责一句话 |
|------|------|-----------|
| 总览 | 全员总览 | 健康与用量全景（首页，登录后落地） |
| 成员管理 | 成员清单 | 开户、档案修改、令牌、启停、空壳删除 |
| Key 管理 | key 清单 | 登记、启停、归属 |
| 支付记录 | 记录清单 | 订阅/充值登记、核对 |
| 调用日志 | 请求明细 | 全池模型请求查询与筛选 |
| 审计日志 | 操作留痕 | 管理动作时间线 |
| 账号设置 | 改密 | 会话体系基本配套 |

顺序逻辑：先看全景 → 立对象（成员 → Key → 支付）→ 查事实（调用日志）→ 系统（审计 / 账号）。

- 侧边栏底部：当前用户名 + 登出（登出即删会话行 → 回登录页）
- 成员视图**同构侧边栏**（三项菜单，见《交互设计-成员视图》§2）：布局壳与管理端一致，菜单与数据不同；顶栏下拉「退出」= 清 sessionStorage 令牌

## 3. 跨页组件与呈现规则

### 3.1 时间范围选择器（核心组件）

- 一切统计的公共维度：**任意时段** + 快捷项
- 快捷项：**今天** / 最近 7 天 / 最近 30 天（默认）/ **本订阅期间**（订阅期间作为预置选项——R10 裁撤后的「周期」形态；依赖支付记录，无登记的部署形态自动隐藏该项，见 §3.8）/ 自定义起止
- 所有统计数字标注其口径（「2026-09-02 ~ 10-01」），杜绝无口径数字

### 3.2 数值呈现三约定

| 值 | 呈现 | 依据 |
|----|------|------|
| 支付金额（`paid_amount`） | **纯数字，无货币符号**——如「170」；登记表单注明「金额数值，币种由你们约定，系统不预设」 | 币种无关裁决（R9） |
| 额度与用量 | **双单位**：原始 quota（如 12,500,000）+ 美元换算（$25.00）——美元由 QPU 换算，带 `$` 前缀（换算目标客观明确） | quota 域同域可比 + 人眼直觉 |
| 美元换算的取值 | 按日志时刻取 QPU（`qpu_history`）；聚合数字一律注明「按当时换算率」 | qpu_history 定稿 |

### 3.3 时间呈现

- 存储为 UTC，**展示一律北京时间**（应用层转换——表设计既有约定）
- 明细时间到秒（14:22:05），统计口径到日；「数据截止」到分钟

### 3.4 状态模式（全页面统一）

| 态 | 表现 |
|----|------|
| 加载 | 骨架屏（首屏）/ 行内 spinner（局部刷新），不整页白屏 |
| 空态 | 一句话说明 + 下一步动作引导（如「还没有登记任何 key——去 Key 管理登记第一个」） |
| 错误 | 顶部错误条（可重试操作提供按钮）；401 走 §1 分流 |
| 同步中 | 数据截止旁的「同步中…」态（登记后首轮、或截止落后时） |

### 3.5 响应式原则

- **只做布局响应**：侧边栏窄屏折叠为抽屉、栅格与区块自适应换行、宽度弹性——纯 CSS 布局层的自适应，仅此而已
- **不做组件响应**：表格在窄屏保持表格形态（横向滚动即可），不为移动端做卡片化视图；**不做移动端 UI 重设计**——窄屏只是布局自然收窄，不识别设备、不切换界面
- 视觉稿、组件库、间距体系不在交互设计范围（作者即前端，实现期自定）；本文锁定**信息结构、交互流、状态与文案**

### 3.6 文案基调

- 中文、直白、零营销腔；数字精确显示（用量不四舍五入口径内的原值）；错误提示说人话（「上游站点暂时不可达，请稍后重试」而非「ERROR 502」）

### 3.7 组件能力需求（实现期选型参照）

八篇交互设计实际用到的组件能力——组件库与前端框架是实现期自由度，本清单是选型的验收标准而非锁定：

1. **布局**：可折叠侧边栏 / 抽屉、栅格系统（布局响应，见 §3.5）
2. **表格**：密集列、行内编辑（归属下拉）、行级操作、窄屏横向滚动；详情弹窗（调用详情 / 订阅参数）
3. **浮层**：对话框（含二次确认）、toast（复制反馈）、顶部提示条（可关闭）
4. **表单**：日期范围选择（时间选择器的快捷项 + 自定义起止）、大号粘贴输入框、双输入切换（支付记录的额度模式）
5. **展示**：徽章 / 标签（来源、状态）、分段条（来源分解）、骨架屏、分页

### 3.8 纯用量模式（无支付记录的完整子集）

平台支持**不登记任何支付记录**的部署形态（如部门实例：只看用量、不掌握订阅套餐信息）——用量统计链路（登记 → 采集 → 聚合）独立于金额层，**零改造支持**：

- 成员视图支付参数页：中性空态「暂无支付记录信息」——**不设行动引导**（不登记是合法使用形态，非遗漏）
- 日志来源徽章的弹窗：无对应登记时显示「该订阅无登记信息」
- 核对提示条：`subscriptions` + `topups` 皆空时**自动静默**（作者显然选择了不登记，此时提示是噪音而非健康信号）
- 「本订阅期间」快捷项自动隐藏（无期间数据）
- 完全不受影响：健康带、按成员 / key 聚合、来源徽章与分解、全部管理操作、审计

## 4. 会话与令牌的生命周期呈现

| 事件 | 界面行为 |
|------|---------|
| 会话过期（7 天） | 下一请求 401 → 登录页 + 「会话已过期」提示 |
| 登出 | 删除会话行 → 登录页 |
| 改密成功 | 删除**其他**会话行（保留当前），提示「其他设备的登录已失效」 |
| 成员令牌重发 | 旧令牌即时失效（成员侧下次 401 回登录壳） |
| 成员停用 | 同上，登录壳提示「令牌无效或已停用」 |