docs: 清除版本叙事并按开源文档体系整理

去掉初版/新版与分支指称，重写 README/AGENTS，删子包 README，对齐文档交叉引用与已废止测试脚本。
2026-10-10 07:56:07 +08:00
parent 8816c32025
commit 5f76bfc9d6
11 changed files with 116 additions and 154 deletions
@@ -5,7 +5,7 @@
 | 项目 | 内容 |
 |------|------|
 | 状态 | 定稿（2026-10-02） |
-| 关联 | 《交互设计-总览与共性》（§1 访问拓扑 · §3 呈现约定）·《交互设计-登录与会话》（鉴权档位与 401 分流）· 七篇表字段设计（DTO 字段权威）·《技术选型》§4（DTO 类型属 `packages/core`） |
+| 关联 | 《交互设计-总览与共性》（§1 访问拓扑 · §3 呈现约定）·《交互设计-登录与会话》（鉴权档位与 401 分流）· 各篇表字段设计（DTO 字段权威）·《技术选型》§4（DTO 类型属 `packages/core`） |
 | 产出 | 路由前缀与隔离机制 · 鉴权两档 · 错误信封 · 时间 / 数值 / 分页 / 命名约定 |

 ---
@@ -77,7 +77,7 @@

 ## 7. DTO 命名

- **snake_case、与表字段同名同构**——七篇表字段设计即 DTO 字段权威，无映射层
+- **snake_case、与表字段同名同构**——各篇表字段设计即 DTO 字段权威，无映射层
 - 前端不做 camelCase 转换：全栈 snake_case（组件 props 是 antd 的 API、与数据 DTO 互不干扰）

 ## 8. 本稿拟定约定（交互设计未覆盖，请作者重点审）
@@ -5,7 +5,7 @@
 | 项目 | 内容 |
 |------|------|
 | 状态 | 待审阅（2026-10-09 支付拆表修订——§7） |
-| 关联 | 《API契约-公共约定》（定稿——总纲）· 八篇交互设计 · `api_keys` / `usage_logs` / `subscriptions` / `topups` / `qpu_history` / `members` 表字段设计（DTO 字段权威）· `需求清单.md` §9（访问主体模型） |
+| 关联 | 《API契约-公共约定》（定稿——总纲）· 八篇交互设计 · `api_keys` / `usage_logs` / `subscriptions` / `topups` / `qpu_history` / `members` / `users` / `sessions` 表字段设计（DTO 字段权威）· `需求清单.md` §9（访问主体模型） |
 | 产出 | 端点清单、请求 / 响应字段、错误码、本稿裁定项（§10）与遗留项（§11） |

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

 ---
@@ -1,6 +1,6 @@
 # 同步引擎设计

-> 母体形态下同步引擎的进程形态、调度与轮次语义：拉什么、写什么、失败怎么办、状态如何暴露。**范围声明（2026-10-05 作者裁决）**：① 本阶段**不考虑 Cloudflare Workers，也不为 CFW 做准备**；② 引擎**独立于 HTTP 服务进程**（`apps/engine`），避免后台 CPU 与 API 抢事件循环；③ 调度用**手写 `setTimeout` 循环**（不引入 cron 库），周期**可配置**。字段与去重的权威仍在七篇表设计；本文定「引擎怎么转」。
+> 母体形态下同步引擎的进程形态、调度与轮次语义：拉什么、写什么、失败怎么办、状态如何暴露。**范围声明（2026-10-05 作者裁决）**：① 本阶段**不考虑 Cloudflare Workers，也不为 CFW 做准备**；② 引擎**独立于 HTTP 服务进程**（`apps/engine`），避免后台 CPU 与 API 抢事件循环；③ 调度用**手写 `setTimeout` 循环**（不引入 cron 库），周期**可配置**。字段与去重的权威仍在各篇表字段设计；本文定「引擎怎么转」。

 | 项目 | 内容 |
 |------|------|
@@ -41,13 +41,13 @@
 | 前端框架 | **Vue 3** | 作者近年常用栈；实现期自由度（共性 §3.5「作者即前端」） | — |
 | 组件库 | **antdv-next**（作者指定尝试项） | Vue 3 企业组件库、对齐 ant-design（React 上游）设计体系；**已核验通过**（§7.1）：活跃周更、§3.7 清单逐项有对应组件、Agent 文档齐备 | Element Plus / ant-design-vue（§3.7 全覆盖） |
 | 加密 | **WebCrypto** | HKDF / AES-256-GCM / HMAC-SHA256 / PBKDF2 与裁决一致（密钥体系见各表设计）；Bun 原生 | HKDF 若 Bun 覆盖滞后：基于 HMAC 的纯 TS 垫片（同原语） |
-| 构建 / 测试 | **Vite**（web）+ **bun test**（core/db/server） | Bun 自带 test runner；Vite 为 Vue 生态默认 | 前端组件测试可加 vitest（实现期定） |
+| 构建 / 测试 | **Vite**（web）；质量门 = `typecheck` + `build` + 人工验收 | 前端构建走 Vite 生态默认；自动化测试不在当前范围 | 需要时再引入测试框架 |
 | API 文档与校验 | **zod** + **@hono/zod-openapi** + **Scalar**（作者确认） | 一源三用：TS 类型 / 请求校验（`422` 与 `fields` 的机器来源）/ OpenAPI 生成；Scalar 为 Hono 官方搭档，规范与渲染器解耦 | Swagger UI（规范不动、换皮即可） |

 ## 4. 分层落地：monorepo（Bun workspaces）

 ```text
-（仓库根 · v1 分支）
+（仓库根）
 ├─ apps/
 │  ├─ server/     # 母体后端：Hono serve 装配 · Drizzle/pg · 进程内调度 · 环境变量与密钥注入
 │  └─ web/       # 前端：Vue 3 + antdv-next + Vite
@@ -58,7 +58,7 @@

 **依赖规则（单向）**：`apps/*` → `packages/db` → `packages/core`；core 导出的 DTO 类型可被 web 以纯类型依赖引用（前后端共用一份契约类型）。

-**代码落点**：实现代码与设计文档同在 v1 分支演进。
+**代码落点**：实现代码与设计文档同仓演进。

 ## 5. R14 预留：现阶段零成本，只为后续抽取不挖坑

@@ -5,7 +5,7 @@
 | 项目 | 内容 |
 |------|------|
 | 状态 | 定稿（2026-10-01） |
-| 关联 | `README.md`（项目沿革与动因）· 七篇表字段设计（定稿）· `docs/references/NewAPI-接口范围.md`（可用接口参考） |
+| 关联 | `README.md`（背景、动因与架构约束）· 各篇表字段设计 · `docs/references/NewAPI-接口范围.md`（可用接口参考） |
 | 取代 | 《设计议题》（2026-09-29 由本清单取代；其中双形态裁决与 CFW 调研结论已并入本文 §5/§7） |

 ---
@@ -19,7 +19,7 @@
 **背景**（三类问题促成当前设计阶段）：

 1. **迭代部署成本**：服务器部署形态下每次迭代都需实例运营方手工升级，测试阶段迭代频繁而运营方无暇跟随 → 双形态交付（R13，已裁决）
-2. **初版设计刻意收缩的部分**：管理面固定口令不妥（R11）、充值折算（R7）、多订阅处理（R8）
+2. **刻意收缩后重新纳入的部分**：管理面固定口令不妥（R11）、充值折算（R7）、多订阅处理（R8）
 3. **已知设计问题**：错误行 `request_id` 去重（R15 必修项）

 ## 1. 数据采集域
@@ -69,7 +69,7 @@

 | # | 需求 | 说明 | 状态 |
 |---|------|------|------|
-| R15 | 数据模型修订 | 七篇表设计经作者逐篇审阅**定稿**（2026-10-01）；其后 `payments` 按 2026-10-09 裁决拆为 `subscriptions` + `topups`（见裁决记录）——基线域现为 `api_keys` · `usage_logs` · `subscriptions` · `topups` · `qpu_history` + 访问主体三表 | **已裁决**（2026-10-01；2026-10-09 拆表修订） |
+| R15 | 数据模型修订 | 表字段设计经作者逐篇审阅**定稿**（2026-10-01）；其后 `payments` 按 2026-10-09 裁决拆为 `subscriptions` + `topups`（见裁决记录）——基线域现为 `api_keys` · `usage_logs` · `subscriptions` · `topups` · `qpu_history` + 访问主体三表 | **已裁决**（2026-10-01；2026-10-09 拆表修订） |

 ## 7. R13 的支撑材料：CFW 可行性调研（2026-09-29，developers.cloudflare.com 官方文档核实，五项全部无阻断）

@@ -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. 裁决记录

@@ -138,11 +138,11 @@

 ### 2026-10-01 · R15 审阅定稿

-七篇表设计经作者逐篇审阅，全部**定稿**。审阅期实质修订：`key_id` → `api_key_id`、`note` → `remark`、**401 自动摘除状态机裁撤**（api_keys 3.6——引擎记录不决策，`status` 纯手动开关）、**管理员初始化与重置改为空库双通道**（users 3.1——env 静默重建 / 引导页兜底，env 凭证降级为可弃）；另有多处语义辨析随文入档（错误行去重指纹、量与换算率、sessions 与 members 零关系、QPU 存在必要性裁决保留）。
+表字段设计经作者逐篇审阅，全部**定稿**。审阅期实质修订：`key_id` → `api_key_id`、`note` → `remark`、**401 自动摘除状态机裁撤**（api_keys 3.6——引擎记录不决策，`status` 纯手动开关）、**管理员初始化与重置改为空库双通道**（users 3.1——env 静默重建 / 引导页兜底，env 凭证降级为可弃）；另有多处语义辨析随文入档（错误行去重指纹、量与换算率、sessions 与 members 零关系、QPU 存在必要性裁决保留）。

-### 2026-10-01 · 交互设计八篇定稿
+### 2026-10-01 · 交互设计定稿

-八篇交互设计（共性 / 登录 / 总览 / key / 支付 / 成员 / 审计 / 成员视图）经作者逐篇审阅，全部**定稿**。审阅期修订：
+交互设计八篇（共性 / 登录 / 总览 / key / 支付 / 成员 / 审计 / 成员视图）经作者逐篇审阅，全部**定稿**。审阅期修订：

 - **纯用量模式**（共性 §3.8，部门实例场景触发）：无支付记录 = 完整可用子集——参数卡中性空态、展开行降级、核对提示全空静默、订阅期间快捷项隐藏
 - **响应式范围收缩**（作者裁决）：只做布局响应，不做组件响应与移动端 UI 重设计
@@ -157,7 +157,7 @@
 - **未关联分组 = 查询层产物**（LEFT JOIN 未匹配集，无新字段），正常时恒为零，非零即异常信号；两种未关联（日志缺 ID / 有 ID 无登记）的展示区分留设计期
 - **统计 = 派生视图**：数据库只存事实行，一切分组/分解/汇总为查询时聚合，无预计算存储

-### 2026-10-09 · 支付建模拆表（方案 B）
+### 2026-10-09 · 支付建模拆表

 - **裁决：`payments` 单表拆为 `subscriptions`（订阅权益）+ `topups`（充值入账事件）**——`paid_at` 在订阅行上语义污染（更像登记时刻），后补录无法按付款时间对齐用量窗口；对齐 NewAPI「权益 vs 入账」两分（评估见 `payments建模评估.md`）
 - **三时刻钉死**：`created_at`（登记）· `paid_at`（钱出手，订阅可空）· `period_*`（用量覆盖期）；筛选：订阅看期间重叠、充值看 `paid_at`、补录看 `created_at`