7.0 KiB
7.0 KiB
交互设计 · 总览与共性
交互层的定位、访问拓扑与跨页共性约定——所有功能页设计篇（登录、总览、key 管理、支付记录、成员管理、审计、成员视图）共用本文的规则。双形态通用：前端与部署形态无关（母体与 CFW 抽取版共用同一交互层），形态差异只在部署与运行时通道。
| 项目 | 内容 |
|---|---|
| 状态 | 定稿（2026-10-01） |
| 关联 | 需求清单.md（R 编号与裁决记录——本文全部设计的依据）· 七篇表字段设计（数据来源） |
| 产出 | 访问拓扑、导航结构、跨页组件、状态模式、数值与时间呈现 |
1. 访问拓扑：两个互不可见的世界
（拓扑见下文描述，实现时以此为准）
- 管理面（作者专属）：入口为登录页（账号密码）→ 侧边栏布局；空库时按三态分流（见《交互设计-登录与会话》）
- 成员视图（成员专属）：入口为登录壳（令牌）→ 单页；与管理面物理隔离（两套路由、两套凭证中间件，令牌进不了管理面，会话进不了成员视图）
- 没有第三种入口：无开放查询页、无游客态；任何人第一眼看到的必然是两个登录入口之一
- 401 分流统一约定：管理面任意请求 401 → 登录页（提示「会话已过期」）；成员视图任意请求 401 → 登录壳（提示「令牌无效或已停用」）——各自回各自的家，不交叉
2. 管理面导航：侧边栏
- 左侧固定侧边栏，结构（自上而下）：
| 菜单 | 页面 | 职责一句话 |
|---|---|---|
| 总览 | 全员总览 | 健康与用量全景（首页，登录后落地） |
| 成员管理 | 成员清单 | 开户、令牌、停用 |
| Key 管理 | 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 组件能力需求（实现期选型参照）
八篇交互设计实际用到的组件能力——组件库与前端框架是实现期自由度，本清单是选型的验收标准而非锁定：
- 布局：可折叠侧边栏 / 抽屉、栅格系统（布局响应，见 §3.5）
- 表格：密集列、行内编辑（归属下拉）、展开行（来源徽章的展开层）、行级操作、窄屏横向滚动
- 浮层：对话框（含二次确认）、toast（复制反馈）、顶部提示条（可关闭）
- 表单：日期范围选择（时间选择器的快捷项 + 自定义起止）、大号粘贴输入框、双输入切换（支付记录的额度模式）
- 展示：徽章 / 标签（来源、状态）、分段条（来源分解）、骨架屏、分页
3.8 纯用量模式（无支付记录的完整子集）
平台支持不登记任何支付记录的部署形态（如部门实例：只看用量、不掌握订阅套餐信息）——用量统计链路（登记 → 采集 → 聚合）独立于金额层，零改造支持：
- 成员视图支付参数卡：中性空态「暂无支付记录信息」——不设行动引导（不登记是合法使用形态，非遗漏）
- 日志来源徽章的展开行：无对应登记时显示「该订阅无登记信息」
- 核对提示条：
payments全空时自动静默（作者显然选择了不登记，此时提示是噪音而非健康信号） - 「本订阅期间」快捷项自动隐藏（无期间数据）
- 完全不受影响：健康带、按成员 / key 聚合、来源徽章与分解、全部管理操作、审计
4. 会话与令牌的生命周期呈现
| 事件 | 界面行为 |
|---|---|
| 会话过期（7 天） | 下一请求 401 → 登录页 + 「会话已过期」提示 |
| 登出 | 删除会话行 → 登录页 |
| 改密成功 | 删除其他会话行（保留当前），提示「其他设备的登录已失效」 |
| 成员令牌重发 | 旧令牌即时失效（成员侧下次 401 回登录壳） |
| 成员停用 | 同上，登录壳提示「令牌无效或已停用」 |