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

- 八篇:总览与共性 / 登录与会话 / 全员总览 / key 管理 / 支付记录 / 成员管理 / 审计日志 / 成员视图
- 关键定案:R12 携带形态(来源徽章 + 展开行,两种空值场景区分)、纯用量模式(部门实例——无支付记录的完整子集,共性 §3.8)、响应式只做布局响应、组件能力需求清单(选型验收标准)、审计日志保留操作者列(前向兼容多管理员)、Key 与成员管理分页 + 「+ 新建成员」缝合流程
- 审阅期修订全记录见需求清单 §9「交互设计八篇定稿」
This commit is contained in:
2026-10-01 23:58:28 +08:00
parent e4d25526f3
commit db20dcb611
13 changed files with 503 additions and 10 deletions
+14 -4
View File
@@ -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)