docs: 交互设计定稿——八篇按功能分篇，经作者逐篇审阅定稿

- 八篇：总览与共性 / 登录与会话 / 全员总览 / key 管理 / 支付记录 / 成员管理 / 审计日志 / 成员视图
- 关键定案：R12 携带形态（来源徽章 + 展开行，两种空值场景区分）、纯用量模式（部门实例——无支付记录的完整子集，共性 §3.8）、响应式只做布局响应、组件能力需求清单（选型验收标准）、审计日志保留操作者列（前向兼容多管理员）、Key 与成员管理分页 + 「+ 新建成员」缝合流程
- 审阅期修订全记录见需求清单 §9「交互设计八篇定稿」

README.md

@@ -30,6 +30,14 @@
 | [`docs/design/members表字段设计.md`](docs/design/members表字段设计.md) | 数据模型新增表：成员实体——key 归属、成员视图身份与按成员统计的锚点 | 定稿（2026-10-01） |
 | [`docs/design/users表字段设计.md`](docs/design/users表字段设计.md) | 数据模型新增表：管理员（单行）——登录体系的身份落点 | 同上 |
 | [`docs/design/sessions表字段设计.md`](docs/design/sessions表字段设计.md) | 数据模型新增表：管理面会话——cookie 令牌的服务端对应物 | 同上 |
+| [`docs/design/交互设计-总览与共性.md`](docs/design/交互设计-总览与共性.md) | 交互设计总纲：访问拓扑、导航、跨页组件、状态与数值呈现约定 | 定稿（2026-10-01） |
+| [`docs/design/交互设计-登录与会话.md`](docs/design/交互设计-登录与会话.md) | 管理面登录页、引导页、改密、成员登录壳 | 同上 |
+| [`docs/design/交互设计-全员总览.md`](docs/design/交互设计-全员总览.md) | 管理面首页：健康带 + 按成员 / key 汇总 | 同上 |
+| [`docs/design/交互设计-key管理.md`](docs/design/交互设计-key管理.md) | 登记（sk-key 唯一界面露面）、启停、归属、死亡显形 | 同上 |
+| [`docs/design/交互设计-支付记录.md`](docs/design/交互设计-支付记录.md) | 订阅/充值同构表单、核对提示 | 同上 |
+| [`docs/design/交互设计-成员管理.md`](docs/design/交互设计-成员管理.md) | 开户、令牌签发/重发（明文仅一次）、停用 | 同上 |
+| [`docs/design/交互设计-审计日志.md`](docs/design/交互设计-审计日志.md) | 管理操作留痕时间线 | 同上 |
+| [`docs/design/交互设计-成员视图.md`](docs/design/交互设计-成员视图.md) | 成员单页世界——R12 携带形态定案（徽章 + 展开行） | 同上 |
 | [`docs/references/NewAPI-接口范围.md`](docs/references/NewAPI-接口范围.md) | 计费平台在 NewAPI 中可用的接口参考：鉴权档位、请求与返回结构、字段语义、实测行为、源码出处（**唯一上游参考**） | 事实依据 |
 
 - 命名与分区：**目录用英文、文档名用中文**；`docs/design/`（我们定的方案与决策）· `docs/references/`（平台可用接口参考——实证事实，不做设计决策）

docs/design/api_keys表字段设计.md

@@ -103,7 +103,7 @@
 
 - **为什么外键在 key 侧**：成员与 key 是 1:N——外键由 N 侧持有是标准做法；成员表的行数不随 key 数量膨胀
 - **为什么可空**：未归属的 key 是真实存在的状态（测试 key、暂未分配的 key）——空值即「用量归作者」的默认归属，无需哨兵行
-- **归属变更即时生效**：`member_id` 是管理通道的 UPDATE，不影响日志行（历史日志按行级归属自然分桶——见 `usage_logs表字段设计.md` 3.6）
+- **归属变更即时生效**：`member_id` 是管理通道的 UPDATE，不影响日志行（历史日志按行级归属自然分组——见 `usage_logs表字段设计.md` 3.6）
 
 ## 4. 写入时机（两个写入者：管理通道 / 同步引擎）
 
@@ -111,7 +111,7 @@
 |------|------|
 | **登记**（管理通道，上游验证通过） | INSERT 一行：管理字段（HMAC / 加密 / registered_at / 归属 `member_id`）+ 上游字段全组（一次 `/api/usage/token` 拿全）+ 两个 synced_at；**首轮日志同步不阻塞登记响应**（由同步引擎立即异步补一轮） |
 | **启停**（管理通道） | UPDATE `status`：启用 → `active`（回轮询清单，下一轮同步即自然验证）/ 停用 → `disabled`（移出轮询清单）——数据保留、不删除 |
-| **归属变更**（管理通道） | UPDATE `member_id`——即时生效，不触碰日志行（统计按行级归属分桶，见 3.8） |
+| **归属变更**（管理通道） | UPDATE `member_id`——即时生效，不触碰日志行（统计按行级归属分组，见 3.8） |
 | **每轮轮询** | 仅写成功结果：UPDATE 上游字段全组 + `usage_synced_at`；日志同步成功后写 `log_synced_at`；任何失败（401 / 403 / 超时等）**不写行**——`log_synced_at` 停滞即管理面可见信号，失败明细进引擎运行日志 |
 
 - 两个上游调用各自独立：**各自的成功写各自的时间戳，互不阻塞、互不污染**

docs/design/payments表字段设计.md

@@ -81,7 +81,7 @@
 | 时机 | 动作 |
 |------|------|
 | 人工登记（管理通道） | INSERT：录入支付信息（时间 / 金额）与订阅信息（ID / 期间 / 总额度，抄自钱包页面）→ 确认 |
-| 系统观测（仅核对） | 日志观测到的订阅 ID / `subscription_total` 仅作核对提示（如「观测到 #N 未对应任何支付记录」——即「未关联」桶的健康信号），不参与回填 |
+| 系统观测（仅核对） | 日志观测到的订阅 ID / `subscription_total` 仅作核对提示（如「观测到 #N 未对应任何支付记录」——即「未关联」分组的健康信号），不参与回填 |
 | 编辑 / 删除 | 数据为人工登记，改错即修 |
 
 ## 5. 展示层边界（界面设计的输入）

docs/design/usage_logs表字段设计.md

@@ -34,7 +34,7 @@
 | 列 | 类型 | 上游来源 | 说明 |
 |----|------|---------|------|
 | `billing_source` | text | `other.billing_source` | 计费来源：`subscription`（订阅）/ `wallet`（充值）——按来源统计的维度 |
-| `subscription_id` | bigint NULL | `other.subscription_id` | 该次消耗所属的上游订阅实例 ID——与 `payments.subscription_id` 直连；缺失时 NULL（归「未关联」桶，见 3.6） |
+| `subscription_id` | bigint NULL | `other.subscription_id` | 该次消耗所属的上游订阅实例 ID——与 `payments.subscription_id` 直连；缺失时 NULL（归「未关联」分组，见 3.6） |
 
 ### 2.3 上游字段（20 个，`/api/log/token` 响应照收）
 
@@ -109,8 +109,8 @@
 ### 3.6 来源提列：`billing_source` 与 `subscription_id` 升为独立列
 
 - **为什么提列**：两者是按来源统计与日志-支付记录直连的核心维度——`other` jsonb 的键查询无法走索引（SQLite/D1 的 `json_extract` 同理），高频过滤维度应独立成列
-- **`subscription_id` 直连语义**（事实关联，非推算）：日志按 `subscription_id = payments.subscription_id` 关联支付记录；**不做期间推定**——订阅来源但该列缺失（NULL）的行归「未关联订阅」桶，统计中透明显示（正常应恒为零，非零即「缺登记」或「上游行为变化」的异常信号）
-- `billing_source = wallet`（充值）的日志不挂订阅（余额扣款与订阅实例无关），`subscription_id` 为 NULL 是**正常状态**而非异常——按来源统计时它们在「充值」桶，不进「未关联订阅」桶
+- **`subscription_id` 直连语义**（事实关联，非推算）：日志按 `subscription_id = payments.subscription_id` 关联支付记录；**不做期间推定**——订阅来源但该列缺失（NULL）的行归「未关联订阅」分组，统计中透明显示（正常应恒为零，非零即「缺登记」或「上游行为变化」的异常信号）
+- `billing_source = wallet`（充值）的日志不挂订阅（余额扣款与订阅实例无关），`subscription_id` 为 NULL 是**正常状态**而非异常——按来源统计时它们在「充值」分组，不进「未关联订阅」分组
 - **其他键留在 `other`**：提列只针对这两个一等维度；`cache_tokens`、倍率等仍留在 jsonb，出现真实分析需求再评估（见 §5）
 
 ### 3.7 行级归属

docs/design/交互设计-key管理.md

@@ -0,0 +1,55 @@
+# 交互设计 · Key 管理
+
+> key 的全生命周期操作面：登记（sk-key 明文在 web 界面的**唯一露面处**）、启停（纯手动，无自动摘除）、归属分配、死亡显形。
+
+| 项目 | 内容 |
+|------|------|
+| 状态 | 定稿（2026-10-01） |
+| 关联 | 《交互设计-总览与共性》· `api_keys表字段设计.md`（字段与 3.6 生命周期）· R2（已裁决：引擎记录不决策） |
+| 数据 | `api_keys` 全表 · 引擎轮次摘要（失败明细） |
+
+---
+
+## 1. Key 清单（页面主体）
+
+| 列 | 内容 | 备注 |
+|----|------|------|
+| 名称 | `token_name`（上游同步） | 展示名以它为准（上游改名随轮询更新） |
+| 归属 | 成员名徽章 / 「未归属」 | 行内下拉可直接改归属（见 §4） |
+| 状态 | `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」的跨页流程断点，见《交互设计-成员管理》）
+3. 提交 → 服务端上游验证，四态反馈：
+
+| 结果 | 反馈 |
+|------|------|
+| 成功 | 「已登记，首轮同步进行中（约 5 分钟内完成）」→ 清单出现新行，「数据截止」显示「同步中…」 |
+| 已登记（hash 命中） | 「该 key 已在清单中」（定位到那行） |
+| 上游拒绝（401） | 「上游拒绝了这枚 key——可能不存在或已被禁用」 |
+| 上游暂不可用 | 「上游站点暂时不可达，请稍后重试」 |
+
+## 3. 启停（纯手动，已裁决无自动摘除）
+
+- **停用**：行操作 → 确认弹窗「停用后移出轮询清单（数据保留）。成员若仍在用它调用 API 不受影响——只有采集停止」→ `status = disabled`
+- **启用**：行操作 → 「已启用——下一轮同步（≤5 分钟）将自动验证，结果见数据截止」（无人工预验证环节，引擎即验证器）
+- **死亡处置推荐流**（对持续 401 的 key）：数据截止停滞 → 你查看引擎日志确认 → 停用 → 找运营方 → 修复后启用。界面在停滞标注的 hover 中给出这条指引文案（把「引擎记录不决策」的操作闭环写进提示里）
+
+## 4. 归属变更
+
+- 清单行内下拉直接切换（含「未归属」选项）——即时生效，无确认弹窗（低风险、可逆）
+- 变更后统计自动按新归属呈现（行级联查当前归属——表设计 3.8 语义）
+
+## 5. 空态
+
+- 无 key：引导文案「还没有登记任何 key——把你在 NewAPI 创建的 sk-key 粘贴进来」+ 登记按钮常驻

docs/design/交互设计-全员总览.md

@@ -0,0 +1,55 @@
+# 交互设计 · 全员总览
+
+> 管理面首页（登录后的落地页）：整个池子的健康与用量全景——你的「全员视角」的唯一居所（开放查看面裁撤后，R5 的全员入口在这里）。
+
+| 项目 | 内容 |
+|------|------|
+| 状态 | 定稿（2026-10-01） |
+| 关联 | 《交互设计-总览与共性》（时间范围选择器、数值呈现）· `需求清单.md` R5（全员视角归此页）· R9（多维统计） |
+| 数据 | `usage_logs` 聚合（按成员 / key / 来源）· `api_keys.log_synced_at`（数据截止）· 引擎轮次摘要 |
+
+---
+
+## 1. 页面结构（自上而下）
+
+### 1.1 健康带（页面顶部，常驻）
+
+| 元素 | 内容 | 说明 |
+|------|------|------|
+| 引擎状态 | 「最近轮次：18 key，成功 16，失败 2」 | 失败数 > 0 时高亮并链到 Key 管理的失败筛选 |
+| 全池数据截止 | 取全池 `log_synced_at` **最慢**（既定聚合语义） | 落后超过 2 小时 → 黄色预警「数据截止停滞——检查引擎日志」 |
+| 未关联订阅分组 | 该时段内 `billing_source = subscription` 且 `subscription_id` 为空的量 | **正常恒为 0**；非零 → 红色提示（缺登记或上游行为变化）——健康指示器的可视化 |
+
+> 健康带不主动轮询（打开页面刷新即可）；告警推送能力属 R4（延后），此处只做「打开页面即可见」的显形。
+
+### 1.2 时间范围选择器
+
+- 共性篇 §3.1 的核心组件；**默认最近 30 天**，快捷项含「本订阅期间」
+
+### 1.3 按成员汇总区（主区块）
+
+卡片栅格，每成员一张卡：
+
+- 成员名（+备注 hover）
+- 名下 key 数、该时段用量（次数 / quota / 美元）、**占全员比例条**（该时段内的事实占比）
+- 数据截止（名下最慢）
+- 「未归属（归作者）」作为一张固定的卡——无归属 key 的用量去向（`member_id IS NULL` 的聚合）
+
+### 1.4 按 key 明细区
+
+- 折叠表（默认收起，与按成员卡互不抢屏）：key 名、归属、状态、数据截止、该时段用量
+- 行点击 → 跳转 Key 管理页该 key 详情
+- 按「按来源」的分解以**分段条**呈现于表头上方：订阅消耗 / 充值消耗（该时段）
+
+## 2. 交互流
+
+| 动作 | 流程 |
+|------|------|
+| 切换时间范围 | 局部刷新全部区块（口径标注同步更新） |
+| 点击健康带的失败数 | → Key 管理页，筛选「最近轮次失败」 |
+| 点击成员卡 | → 该成员的 key 列表过滤视图（或成员管理页定位该成员） |
+
+## 3. 空态
+
+- 无任何 key：健康带显示「未登记任何 key」，主区块引导「去 Key 管理登记第一个」
+- 有 key 无日志：各卡正常、用量为 0（空态与零值区分标注「该时段内无调用」）

docs/design/交互设计-审计日志.md

@@ -0,0 +1,39 @@
+# 交互设计 · 审计日志
+
+> 管理操作留痕的查看面——审计是独立正交需求（与鉴权方案无关），本页是作者的自察工具，无对外语义。
+
+| 项目 | 内容 |
+|------|------|
+| 状态 | 定稿（2026-10-01） |
+| 关联 | `需求清单.md` §9（访问主体模型·审计日志条目）· `members/users表字段设计.md`（写入时机中「落审计」的动作全集） |
+| 数据 | 审计日志表（表结构归技术稿——本文锁定信息结构与展示） |
+
+---
+
+## 1. 记录清单（页面主体）
+
+时间线列表（时间倒序）：
+
+| 列 | 内容 |
+|----|------|
+| 时间 | 到秒（北京时间） |
+| 操作者 | `user_id` → 用户名；**系统触发的事件（如空库重建）为 NULL**，天然区分系统操作与会话操作 |
+| 操作类型 | 分类标签（见 §2） |
+| 内容摘要 | 关键信息（「key 小张-01 · 停用」「成员 A · 令牌重发」「支付记录 #3 · 编辑」） |
+
+## 2. 操作类型体系（登记面的完整枚举）
+
+| 域 | 类型 |
+|----|------|
+| Key | 登记 / 启用 / 停用 / 归属变更 |
+| 支付记录 | 登记 / 编辑 / 删除 |
+| 成员 | 开户 / 停用 / 启用 / 令牌签发 / 令牌重发 |
+| 账号 | 改密 /（空库重建为系统事件，记「初始化」） |
+
+- 每类管理面写操作一行留痕——操作者列当前恒为作者（单管理员），但**审计是不可变历史，操作者归属不能事后补写**：保留该列是前向兼容（未来若扩展多管理员 / 权限引擎，历史记录自然区分），也是审计语义的自描述原则（who did what when 的 who 是本体字段）
+- 筛选：按域（Key / 支付 / 成员 / 账号）；分页（时间倒序 + 每页 50 条之类，细节随实现）
+
+## 3. 定位边界
+
+- 审计**只记录管理面写操作**：查询类动作（看总览、翻明细）不留痕；成员侧动作（看自己的视图）不属管理面、不在此列
+- 本页无任何操作（纯只读）

docs/design/交互设计-总览与共性.md

@@ -0,0 +1,108 @@
+# 交互设计 · 总览与共性
+
+> 交互层的定位、访问拓扑与跨页共性约定——所有功能页设计篇（登录、总览、key 管理、支付记录、成员管理、审计、成员视图）共用本文的规则。**双形态通用**：前端与部署形态无关（母体与 CFW 抽取版共用同一交互层），形态差异只在部署与运行时通道。
+
+| 项目 | 内容 |
+|------|------|
+| 状态 | 定稿（2026-10-01） |
+| 关联 | `需求清单.md`（R 编号与裁决记录——本文全部设计的依据）· 七篇表字段设计（数据来源） |
+| 产出 | 访问拓扑、导航结构、跨页组件、状态模式、数值与时间呈现 |
+
+---
+
+## 1. 访问拓扑：两个互不可见的世界
+
+```svg
+（拓扑见下文描述，实现时以此为准）
+```
+
+- **管理面**（作者专属）：入口为登录页（账号密码）→ 侧边栏布局；空库时按三态分流（见《交互设计-登录与会话》）
+- **成员视图**（成员专属）：入口为登录壳（令牌）→ 单页；与管理面物理隔离（两套路由、两套凭证中间件，令牌进不了管理面，会话进不了成员视图）
+- **没有第三种入口**：无开放查询页、无游客态；任何人第一眼看到的必然是两个登录入口之一
+- 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 回登录壳） |
+| 成员停用 | 同上，登录壳提示「令牌无效或已停用」 |

docs/design/交互设计-成员管理.md

@@ -0,0 +1,47 @@
+# 交互设计 · 成员管理
+
+> 成员实体的操作面：开户、令牌签发与重发（明文仅展示一次）、停用。访问主体模型中「凭证事务经作者」的落点。
+
+| 项目 | 内容 |
+|------|------|
+| 状态 | 定稿（2026-10-01） |
+| 关联 | 《交互设计-总览与共性》· `members表字段设计.md`（软删除、令牌不过期）· R12（成员视图的锚点） |
+| 数据 | `members` 全表 · 名下 key 聚合 |
+
+---
+
+## 1. 成员清单（页面主体）
+
+卡片栅格（成员量级：个位数）：
+
+| 元素 | 内容 |
+|------|------|
+| 名称 | `name`（+备注） |
+| 状态 | active / disabled 徽章 |
+| 令牌签发时间 | `token_issued_at`（提示「明文已不可找回，如需新令牌请重发」） |
+| 名下 key 数 | 聚合计数（hover 列出 key 名） |
+| 操作 | 重发令牌 / 停用（或启用） |
+
+## 2. 开户
+
+表单：名称（必填、唯一性校验）、备注（可空）→ 提交 → **自动生成令牌** → 明文展示对话框（见 §3）
+
+## 3. 令牌签发与重发（敏感操作的标准交互）
+
+**明文展示对话框**（开户自动触发，或重发触发）：
+
+- 令牌明文 + 复制按钮（点击即复制 + 「已复制」反馈）
+- 醒目警示：「**关闭后将无法再次查看**——请立即复制并通过你信任的渠道发给成员」
+- 关闭需二次确认（「我已保存并发送」按钮）
+- **重发**的确认弹窗先行：「重发后旧令牌立即失效（该成员正在用的访问将中断）」→ 确认 → 新明文对话框
+- 对话框关闭后，界面任何地方不再出现明文（库里只有哈希——members 3.1）
+
+## 4. 停用 / 启用
+
+- 停用：确认弹窗「停用后该成员的视图立即不可访问（令牌验证含状态检查）；数据保留」——退拼 / 令牌疑似泄露的标准动作
+- 启用：直接启用（下一请求即恢复）
+- 软删除语义：**无删除按钮**——成员与其历史用量是账本事实，只有停用（members 3.4）
+
+## 5. 空态
+
+「还没有成员——为每位分摊朋友开户并发放访问令牌」

docs/design/交互设计-成员视图.md

@@ -0,0 +1,76 @@
+# 交互设计 · 成员视图
+
+> 成员的单页世界——名下 key 的调用日志、用量聚合、完全公开透明的支付参数。**R12 的交互落点**：含「日志行携带所属订阅/充值信息」的形态定案。页面无任何「应付」概念（分摊哲学裁决）。
+
+| 项目 | 内容 |
+|------|------|
+| 状态 | 定稿（2026-10-01） |
+| 关联 | 《交互设计-总览与共性》（数值呈现、时间选择器）· R12（裁决记录）· `members表字段设计.md`（令牌）· `usage_logs表字段设计.md`（来源提列）· `payments表字段设计.md`（参数卡数据源） |
+| 数据 | 名下 key 的 `usage_logs` 聚合与明细 · 相关 `payments` 参数（完全可见） |
+| 前置 | 经登录壳（令牌）进入；无侧边栏、单页 |
+
+---
+
+## 1. 单页结构（自上而下，滚动即全部）
+
+### 1.1 页头
+
+成员名 + 一句话定位「你在本池的名下用量」（「你」= 该成员；页面文案以成员视角书写）
+
+### 1.2 时间范围选择器
+
+共性组件；默认最近 30 天，快捷项含「本订阅期间」
+
+### 1.3 聚合卡（该时段总览）
+
+- 总用量：次数 / quota / 美元（标注「按当时换算率」）
+- **按来源分解**：订阅消耗 / 充值消耗（分段条）——回答「我的用量花在哪个池子」
+
+### 1.4 支付参数卡（完全公开透明的落点）
+
+该时段涉及的订阅与充值，**参数原貌**逐笔列出：
+
+- 订阅：期间、订阅 ID、额度（quota + $）、金额（纯数字）
+- 充值：支付时间、额度、金额
+- 脚注：「支付参数对成员完全公开；币种由成员与作者约定」——透明裁决的界面声明
+
+> **不出现**任何派生金额：无「折合人民币」、无「占比 × 金额」、无「应付」——账本是事实，算账是社交层的事。
+>
+> 空态：无登记的部署形态（纯用量模式，《总览与共性》§3.8）下该卡显示中性文案「暂无支付记录信息」——不设行动引导（不登记是合法使用形态）。
+
+### 1.5 我的 key 列表
+
+每 key 一张窄卡：`token_name`、数据截止（停滞标注）、该时段用量（次数 / quota / $）。
+
+### 1.6 日志明细表
+
+| 列 | 内容 |
+|----|------|
+| 时间 | 到秒（北京时间） |
+| key | `token_name` |
+| 模型 | `model_name` |
+| 来源 | **来源徽章**：`订阅 #N` / `充值` / `未关联`（灰）——携带形态的第一层（一眼识别） |
+| 用量 | quota + 美元双单位 |
+| tokens | prompt + completion |
+
+**携带形态定案（R12 悬置项的本设计结论）**：两层实现——
+
+1. **行内徽章**（常驻）：来源类型 + 订阅编号，零噪声
+2. **展开行**（点击徽章）：该笔支付的完整参数（期间 / 额度 / 金额 / 备注）——完整透明的第二层，按需展开不打扰
+
+> 展开行降级：徽章对应的订阅**无支付记录**时，展开显示「该订阅无登记信息」（纯用量模式的常态，见《总览与共性》§3.8）；徽章显示「未关联」的行（日志缺 `subscription_id`）不可展开——两种空值场景各自归位，见 `usage_logs表字段设计.md` 3.6。
+
+> 该形态随实现期真实数据核查（订阅编号同一性）后再终验；徽章文案预留「未关联」的正常位（健康指示语义）。
+
+## 2. 状态与边界
+
+| 场景 | 表现 |
+|------|------|
+| 该时段无日志 | 聚合区「该时段内无调用」+ 明细空态 |
+| 名下无 key（刚开户） | 全页空态「作者尚未为你分配 key」 |
+| 令牌失效/停用 | 任意请求 401 → 登录壳（「令牌无效或已停用」） |
+| 旧令牌（作者重发后） | 同上——旧令牌即刻作废 |
+
+## 3. 窄屏说明
+
+成员可能用手机查看本页——但按《总览与共性》§3.5 的裁决：**不做移动端 UI 设计**，窄屏下依赖布局响应（区块纵向堆叠、宽度弹性）保证可读不崩；明细表保持表格形态，横向滚动即可。

docs/design/交互设计-支付记录.md

@@ -0,0 +1,47 @@
+# 交互设计 · 支付记录
+
+> 订阅与充值的登记面（同构表单）+ 系统核对提示的呈现——「只有作者知道」的信息的唯一录入处（payments 定位）。
+
+| 项目 | 内容 |
+|------|------|
+| 状态 | 定稿（2026-10-01） |
+| 关联 | 《交互设计-总览与共性》（数值呈现：金额无符号、额度双单位）· `payments表字段设计.md`（字段与「只存事实」）· R7（充值登记）· R8（`subscription_id` 直连） |
+| 数据 | `payments` 全表 · 日志观测的订阅 ID（核对提示） |
+
+---
+
+## 1. 记录清单（页面主体）
+
+| 列 | 内容 | 备注 |
+|----|------|------|
+| 类型 | `subscription` / `topup` 徽章（订阅 / 充值） | 同构表的两种形态 |
+| 金额 | **纯数字**（如「170」） | 币种由你们约定——列头标注「金额（币种自定）」 |
+| 时间 | 订阅：期间 `[start, end)`，未结束显示「进行中」；充值：`paid_at` | 期间左闭右开，展示为「09-01 ~ 10-01」 |
+| 订阅 ID | `subscription_id`（充值留空） | 直连日志的分源键 |
+| 额度 | 原始 quota + 美元换算双单位（如「12,500,000（$25.00）」） | 美元按 QPU 换算，标注「按当时换算率」 |
+| 备注 | `remark` | |
+
+- 排序：时间倒序；编辑 / 删除（删除有确认弹窗——「改错即修，删除即消失」，人工登记数据）
+
+## 2. 登记表单（订阅 / 充值同构，`kind` 切换）
+
+**公共字段**：金额（必填，纯数字输入；脚注「金额数值——币种由你们约定，系统不预设」）、备注（可空）
+
+**订阅形态追加**：
+- 支付时间、期间起止（结束可空 = 进行中）
+- 订阅 ID（抄自钱包页面「订阅 #N」）
+- 额度——**双输入模式**：直接输原始 quota，或输美元由系统按当前 QPU 换算落库（表单内二选一切换，换算即时预览；录入体验归交互层、数据落原始 quota——payments 3.6）
+
+**充值形态追加**：支付时间、额度（同上双输入）
+
+## 3. 核对提示（系统观测 ↔ 人工登记的对照）
+
+页面顶部提示区，由日志观测驱动：
+
+| 提示 | 触发 | 文案 |
+|------|------|------|
+| 未对应登记 | 观测到某 `subscription_id` 有消耗、但 `payments` 无此订阅 | 「观测到订阅 #N 有消耗，但尚无对应登记——请核对补录」 |
+| 正常 | 全部观测到的订阅均有登记 | 不显示（健康默认无声） |
+
+- 观测**只提示、不回填**（payments 定稿语义）；提示区与全员总览的「未关联订阅」分组互为印证（一个说「有 ID 没账」，一个说「有账路没 ID」）
+- **静默规则**：`payments` 全空时本提示区自动静默——纯用量模式（《总览与共性》§3.8，如部门实例）下「无登记」是作者的有意选择，此时提示是噪音而非健康信号

docs/design/交互设计-登录与会话.md

@@ -0,0 +1,48 @@
+# 交互设计 · 登录与会话
+
+> 两个世界的入口设计：管理面登录页、空库三态（静默重建 / 引导页）、改密表单、成员登录壳。访问主体模型的交互落点（R11 裁决）。
+
+| 项目 | 内容 |
+|------|------|
+| 状态 | 定稿（2026-10-01） |
+| 关联 | 《交互设计-总览与共性》（导航与状态模式）· `users表字段设计.md` 3.1（空库双通道）· `members表字段设计.md`（令牌）· `sessions表字段设计.md` |
+| 页面 | 管理面登录页、引导页、账号设置（改密）、成员登录壳 |
+
+---
+
+## 1. 管理面登录页
+
+- **唯一元素**：用户名、密码、登录按钮——无「忘记密码」链接（重置路径是服务器侧删行，见 users 3.1，不设界面入口）
+- 提交：失败 → 「用户名或密码错误」（通用提示）；成功 → 建会话（HttpOnly cookie）→ 落地全员总览
+- **空库三态在此路由内分流**（前端请求管理面入口时后端判定状态）：
+
+```
+GET 管理面入口
+ ├─ users 非空 ────────── 登录页（如常）
+ ├─ 空库 + env 凭证在 ─── 后端静默重建 → 登录页（密码即 env 凭证，用户无感）
+ └─ 空库 + env 凭证无 ─── 引导页（见 §2）
+```
+
+## 2. 引导页（空库兜底，一次性）
+
+- 出现条件：`users` 空且 env 无引导凭证——重置密码时的兜底通道
+- 表单：用户名、密码、确认密码；提交 → 落库 → 直接进入登录态（免二次登录）
+- 页头说明文案：「系统检测到管理员尚未初始化——请设置管理员账号」
+- **永不复现**：`users` 非空后此页面不再可能出现（后端状态判定保证）
+- 安全提示（页面脚注）：「请尽快完成设置——初始化完成前，此页面对任何访问者可见」
+
+## 3. 账号设置（改密）
+
+- 侧边栏「账号设置」：旧密码、新密码、确认新密码
+- 成功 → 提示「密码已更新；其他设备的登录已失效」（**删除其他会话行、保留当前**——sessions 可吊销能力的运用）
+- 失败 → 「旧密码不正确」
+
+## 4. 成员登录壳
+
+- 成员视图的唯一入口：令牌输入框（单字段）+ 进入按钮
+- 提交 → 服务端哈希比对 + `status` 检查：
+  - 通过 → 令牌存 sessionStorage → 进入成员视图（单页，见《交互设计-成员视图》）
+  - 失败/停用 → 「令牌无效或已停用」（同一提示，不泄露停用与错误的区别——成员侧无需区分，反正都是找作者）
+- 页面氛围：与登录页同构但**视觉上明确这是「成员入口」**（页头「成员入口」标识），防止你自己走错门
+- 无「找回令牌」链接：丢了找作者重发（裁决语义，界面不设自助入口）
+- 关闭标签 → sessionStorage 清除 → 下次重输（一个月一次的成本，换来零凭证持久化）

docs/design/需求清单.md

@@ -45,7 +45,7 @@
 | R5 | 用量查询 | 时间范围 / 明细与汇总；查询入口已归位——成员视图（令牌）与管理面总览/下钻（口令），「凭 sk-key 的开放查询」已裁撤（见裁决记录 2026-09-29）；统计维度含按 key / 成员 / 计费来源 / 模型（见 R9） | **已裁决**（2026-10-01，数据层随表设计定稿；查询口径细节归 API 契约） |
 | R6 | 美元换算与支付记录 | **重定义**（2026-09-29）：① quota → 额度美元换算（÷ `quota_per_unit`，`qpu_history` 时间线服务它）——纯客观单位换算，保留；② **裁撤**每行日志的实付分摊金额（`amount_rmb`，「quota 占比 × 实付」）——它是分摊口径的派生值，随购买记录漂移，违反事实服务原则；③ 支付记录登记：支付金额 ↔ 额度的**比率关系**（币种无关——系统不预设币种，见 R9） | **已裁决**（2026-09-29，重定义） |
 | R7 | 充值登记 | **重定义**（2026-09-29）：充值与订阅同构——支付记录（金额 + 额度 + 比率）+ 日志来源标注（`billing_source`）+ 按来源统计；**同样不做**充值用量的金额分摊（原「池子加权平均」方案裁撤） | **已裁决**（2026-09-29，重定义） |
-| R8 | 多订阅并行处理 | **重定义**（2026-09-29）：① 支付记录允许多订阅期间重叠（不设互斥约束）② 日志-支付记录按 `subscription_id` **直连**（上游标注的客观事实，不推算）——「整笔订阅一把尺」原则已随 `amount_rmb` 裁撤消亡，订阅维度无需任何「尺」③ 按订阅分组的统计为查询时聚合输出（**非物理表**——账本只存事实行，统计是随查随算的派生视图）；「未关联订阅」为 LEFT JOIN 未匹配集的透明桶（无新字段，正常时恒为零——非零即异常信号：缺登记或上游行为变化），兼作数据健康指示器；扣费顺序（先旧后新等）是上游策略，日志忠实记录，平台不管 | **已裁决**（2026-09-29，重定义） |
+| R8 | 多订阅并行处理 | **重定义**（2026-09-29）：① 支付记录允许多订阅期间重叠（不设互斥约束）② 日志-支付记录按 `subscription_id` **直连**（上游标注的客观事实，不推算）——「整笔订阅一把尺」原则已随 `amount_rmb` 裁撤消亡，订阅维度无需任何「尺」③ 按订阅分组的统计为查询时聚合输出（**非物理表**——账本只存事实行，统计是随查随算的派生视图）；「未关联订阅」为 LEFT JOIN 未匹配集的透明分组（无新字段，正常时恒为零——非零即异常信号：缺登记或上游行为变化），兼作数据健康指示器；扣费顺序（先旧后新等）是上游策略，日志忠实记录，平台不管 | **已裁决**（2026-09-29，重定义） |
 | R9 | 分摊原材料与多维统计 | **重定义**（2026-09-29）：平台**不做**应付款计算、**不做**分摊口径（闲置额度归谁之类是社交层问题）——只提供原材料：计费来源标注（`billing_source`：订阅 / 充值）、支付记录（**币种无关**：支付金额与额度之间的比率关系，不预设币种）、任意时段多维聚合（按 key / 成员 / 来源 / 模型） | **已裁决**（2026-09-29，重定义） |
 | R10 | ~~计费周期与账单~~ | **已裁撤**（2026-09-29）：周期 = 任意查询时段（订阅期间为预置选项）；无平台侧账单（应付款不计算，期末快照无对象）。保留行以维持编号连续 | **已裁撤** |
 
@@ -90,7 +90,7 @@
 
 ## 8. 推进方式
 
-**需求阶段收官（2026-10-01）**：15 项全部有归宿——R1 / R2 / R5 / R6 / R7 / R8 / R9 / R11 / R12 / R13 / R14 / R15 已裁决关闭，R10 裁撤，R3 / R4 延后（提案存档见 §9）。七篇表设计经作者逐篇审阅**定稿**。**下一批专门设计文档：API 契约 → 交互设计 → 同步引擎设计**（双形态架构下，逐篇立稿、逐篇审阅）。
+**需求阶段收官（2026-10-01）**：15 项全部有归宿——R1 / R2 / R5 / R6 / R7 / R8 / R9 / R11 / R12 / R13 / R14 / R15 已裁决关闭，R10 裁撤，R3 / R4 延后（提案存档见 §9）。七篇表设计、八篇交互设计均经作者逐篇审阅**定稿**。**剩余专门设计文档：API 契约 → 同步引擎设计**（双形态架构下，逐篇立稿、逐篇审阅）。
 
 ## 9. 裁决记录
 
@@ -117,7 +117,7 @@
 
 **开放查看面裁撤**（同日裁决）：「凭 sk-key 查」入口取消——sk-key 明文从 web 界面消失（仅登记时输入一次、随即加密）；场景归位：**成员 → 令牌视图；作者 → 管理面**（key 清单下钻 + 全员总览面板，总览为新增设计项）
 
-**审计日志（独立需求，与鉴权方案正交）**：管理面写操作（key 登记/启停、购买记录增删改、成员开户/停用、令牌签发/吊销、改密）逐条留痕：操作类型、时间、关键内容摘要；属业务核心层，两形态共有。同理正交的还有同步引擎运行日志——记录语义两形态一致，落盘通道随形态（母体 stdout/journald，CFW Workers Logs）
+**审计日志（独立需求，与鉴权方案正交）**：管理面写操作（key 登记/启停、购买记录增删改、成员开户/停用、令牌签发/吊销、改密）逐条留痕：**操作类型、时间、操作者**（前向兼容多管理员扩展——审计是不可变历史，归属不能事后补写；系统触发事件如空库重建为 NULL）、关键内容摘要；属业务核心层，两形态共有。同理正交的还有同步引擎运行日志——记录语义两形态一致，落盘通道随形态（母体 stdout/journald，CFW Workers Logs）
 
 ### 2026-09-29 · 分摊哲学与原材料（R9 重定义 · R10 裁撤 · R6/R7 重定义 · R12 形态修正）
 
@@ -140,11 +140,21 @@
 
 七篇表设计经作者逐篇审阅，全部**定稿**。审阅期实质修订：`key_id` → `api_key_id`、`note` → `remark`、**401 自动摘除状态机裁撤**（api_keys 3.6——引擎记录不决策，`status` 纯手动开关）、**管理员初始化与重置改为空库双通道**（users 3.1——env 静默重建 / 引导页兜底，env 凭证降级为可弃）；另有多处语义辨析随文入档（错误行去重指纹、量与换算率、sessions 与 members 零关系、QPU 存在必要性裁决保留）。
 
+### 2026-10-01 · 交互设计八篇定稿
+
+八篇交互设计（共性 / 登录 / 总览 / key / 支付 / 成员 / 审计 / 成员视图）经作者逐篇审阅，全部**定稿**。审阅期修订：
+
+- **纯用量模式**（共性 §3.8，部门实例场景触发）：无支付记录 = 完整可用子集——参数卡中性空态、展开行降级、核对提示全空静默、订阅期间快捷项隐藏
+- **响应式范围收缩**（作者裁决）：只做布局响应，不做组件响应与移动端 UI 重设计
+- **组件能力需求清单**（共性 §3.7）：组件库与前端框架归实现期自由度，本清单为选型验收标准
+- **审计日志保留操作者列**：前向兼容多管理员——审计是不可变历史，操作者归属不能事后补写；系统触发事件为 NULL
+- 其余：成员视图「移动端优先级」随响应式裁决改为「窄屏说明」；Key 登记对话框补「+ 新建成员」快捷入口；统计容器表述「桶」统一为「分组」
+
 ### 2026-09-29 · 多订阅并行（R8 重定义）
 
 - **「一把尺」原则已随 `amount_rmb` 裁撤消亡**——其唯一客户是分摊金额计算；quota → 美元走 QPU（站点参数），订阅维度无需任何「尺」
 - **日志归属 = 上游事实，非推算**：日志 `other.subscription_id` 直接关联支付记录（实现期核查项：登录态钱包页的订阅编号与日志 `subscription_id` 是否同一体系——基线草案既有推测，与 R12 携带形态并作一批真实数据核查）
-- **未关联桶 = 查询层产物**（LEFT JOIN 未匹配集，无新字段），正常时恒为零，非零即异常信号；两种未关联（日志缺 ID / 有 ID 无登记）的展示区分留设计期
+- **未关联分组 = 查询层产物**（LEFT JOIN 未匹配集，无新字段），正常时恒为零，非零即异常信号；两种未关联（日志缺 ID / 有 ID 无登记）的展示区分留设计期
 - **统计 = 派生视图**：数据库只存事实行，一切分组/分解/汇总为查询时聚合，无预计算存储
 
 ### 2026-09-29 · 数据资产域延后（R3 / R4）