new-api-key-usage/docs/design/交互设计-总览与共性.md

交互设计 · 总览与共性

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

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

---

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

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

• 管理面（作者专属）：入口为登录页（账号密码）→ 侧边栏布局；空库时按三态分流（见《交互设计-登录与会话》）
• 成员视图（成员专属）：入口为登录壳（令牌）→ 单页；与管理面物理隔离（两套路由、两套凭证中间件，令牌进不了管理面，会话进不了成员视图）
• 没有第三种入口：无开放查询页、无游客态；任何人第一眼看到的必然是两个登录入口之一
• 401 分流统一约定：管理面任意请求 401 → 登录页（提示「会话已过期」）；成员视图任意请求 401 → 登录壳（提示「令牌无效或已停用」）——各自回各自的家，不交叉

2. 管理面导航：侧边栏

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

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

• 侧边栏底部：当前用户名 + 登出（登出即删会话行 → 回登录页）
• 成员视图无侧边栏（单页，页头导航）

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 纯用量模式（无支付记录的完整子集）

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

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

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

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