skycurtain/new-api-key-usage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
去掉初版/新版与分支指称，重写 README/AGENTS，删子包 README，对齐文档交叉引用与已废止测试脚本。
This commit is contained in:
skycurtain
2026-10-10 07:56:07 +08:00
parent 8816c32025
commit 5f76bfc9d6
11 changed files with 116 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+7 -7
View File
@@ -5,18 +5,18 @@
## 协作约定（长期有效） ## 协作约定（长期有效）
- **Git**：仅当项目作者明确说"提交 / commit"时才执行提交；`git push` 永远由项目作者手工执行，AI 绝不推送 - **Git**：仅当项目作者明确说"提交 / commit"时才执行提交；`git push` 永远由项目作者手工执行，AI 绝不推送
- **命名**：需求 / 设计 / 交互 / 技术 / 计划等**文档名**用中文（`README` / `AGENTS` / `LICENSE` 等约定俗成除外）、**目录**用英文；新文档按性质放入 `docs/design/`（我们定的方案与决策）或 `docs/references/`（平台可用接口参考——实证事实，不做设计决策），并同步更新 README 的「文档地图」；`docs/deprecated/` 只归档已废弃文档——**勿引用、勿作依据**（本分支暂无此目录，需要时再建） - **命名**：需求 / 设计 / 交互 / 技术 / 计划等**文档名**用中文（`README` / `AGENTS` / `LICENSE` 等约定俗成除外）、**目录**用英文；新文档按性质放入 `docs/design/`（我们定的方案与决策）或 `docs/references/`（平台可用接口参考——实证事实，不做设计决策），并同步更新 README 的「文档地图」；`docs/deprecated/` 只归档已废弃文档——**勿引用、勿作依据**（需要时再建）
- **代码文件命名**：所有**目录名与文件名**一律 kebab-case（如 `time-range-picker.vue` · `admin-session.ts`）；**组件在模板中引用时用大驼峰**（`<TimeRangePicker />`）——文件名 kebab、模板标签 PascalCase - **代码文件命名**：所有**目录名与文件名**一律 kebab-case（如 `time-range-picker.vue` · `admin-session.ts`）；**组件在模板中引用时用大驼峰**（`<TimeRangePicker />`）——文件名 kebab、模板标签 PascalCase
- **文档状态**：头部表格标「状态」（草案 → 讨论中 → 待审阅 → 定稿(日期) → 已实现）；设计文档定稿后不搬家、只改状态；被取代时删除（git 历史即考古） - **文档状态**：头部表格标「状态」（草案 → 讨论中 → 待审阅 → 定稿(日期) → 已实现）；设计文档定稿后不搬家、只改状态；被取代时删除（git 历史即考古）
- **部署**：交付物必须保证「一条命令链」可部署；**双形态并行已裁决**——完整前后端（运营方服务器）先行，Cloudflare Workers 抽取版（作者自部署）后续（见 `docs/design/需求清单.md` R13） - **部署**：交付物必须保证「一条命令链」可部署；**双形态并行已裁决**——完整前后端（运营方服务器）先行，Cloudflare Workers 抽取版（作者自部署）后续（见 `docs/design/需求清单.md` R13）
- **不引入版本叙事**：不使用 v1/v2/v3 之类版本编号，不以「MVP」等标签或指称显式描述任何历史阶段；文档内容必须**自立**——不得引用、描述任何当前分支之外、可能被删除的分支内容 - **不引入版本叙事**：不使用 v1/v2/v3 之类版本编号，不以「MVP」等标签或指称显式描述任何历史阶段；文档内容必须**自立**——不得引用、描述任何当前仓库之外、可能被删除的分支或目录内容
- **本地不入库也不 ignore 的物料**（AI 提交时务必避开）：`api*.json`（上游实测快照）、`session-archive/`（作者主动备份的会话记录，如 `v1-设计-*.md`）——不加入 git、不写 `.gitignore`，靠提交时人工/执行者目视把关；`v1-设计-1.md` 为历史对话原档，允许保留旧术语，不作现行依据 - **本地不入库也不 ignore 的物料**（AI 提交时务必避开）：`api*.json`（上游实测快照）、`session-archive/`（作者主动备份的会话记录）——不加入 git、不写 `.gitignore`，靠提交时人工/执行者目视把关
## 项目速览（速记） ## 项目速览（速记）
- **`v1`（本分支）= 设计文档中心 + 实现主线**：实现代码与文档同分支演进（代码落点已定案），monorepo 结构（`apps/server` · `apps/web` · `packages/core` · `packages/db`）见 `docs/design/技术选型.md` §4 - **本仓库 = 设计文档中心 + 实现主线**：实现代码与文档同仓演进，monorepo 结构（`apps/server` · `apps/engine` · `apps/web` · `packages/core` · `packages/db`）见 `docs/design/技术选型.md` §4
- 数据模型：基线表（`api_keys` · `usage_logs` · `subscriptions` · `topups` · `qpu_history`）+ 三张访问主体表（`members` · `users` · `sessions`）——`payments` 单表已按方案 B 拆为 `subscriptions` + `topups`（见 `docs/design/payments建模评估.md`）；同步架构（轮询 + `request_id` 去重 + 攒库）的动因由上游物理约束决定，架构结论不变 - 数据模型：基线表（`api_keys` · `usage_logs` · `subscriptions` · `topups` · `qpu_history`）+ 三张访问主体表（`members` · `users` · `sessions`）——支付登记已拆为 `subscriptions` + `topups`（见 `docs/design/payments建模评估.md`）；同步架构（轮询 + `request_id` 去重 + 攒库）的动因由上游物理约束决定
- 需求总集与待裁决项（平台身份体系、费用分摊与账单、充值折算、多订阅、数据资产保护）见 `docs/design/需求清单.md`；交付形态已裁决（双形态并行，完整形态先行） - 需求总集与裁决档案见 `docs/design/需求清单.md`；交付形态已裁决（双形态并行，完整形态先行）
- 上游约束速记：只有 sk-key、无时间过滤接口 → 轮询攒库是唯一路径（README「架构的根本动因」） - 上游约束速记：只有 sk-key、无时间过滤接口 → 轮询攒库是唯一路径（README「架构的根本动因」）
## 命令 ## 命令
@@ -30,7 +30,7 @@ Bun 工具链（选型见 `docs/design/技术选型.md`）。**Windows 上 `bun`
| `bun run db:push` | 推送到本地库（开发期） | | `bun run db:push` | 推送到本地库（开发期） |
| `bun run db:studio` | Drizzle Studio 看库 | | `bun run db:studio` | Drizzle Studio 看库 |
| `bun run typecheck` | 根 tsconfig 类型检查（不含 web `.vue`） | | `bun run typecheck` | 根 tsconfig 类型检查（不含 web `.vue`） |
| `bun run dev:server` | 开发跑母体后端（hot reload） | | `bun run dev:server` | 开发跑后端（hot reload） |
| `bun run dev:engine` | 开发跑同步引擎（独立进程，读 `SYNC_*` env） | | `bun run dev:engine` | 开发跑同步引擎（独立进程，读 `SYNC_*` env） |
| `bun run dev:web` | 开发跑前端 Vite | | `bun run dev:web` | 开发跑前端 Vite |
| `bun run build:web` | 前端类型检查 + 产物构建 | | `bun run build:web` | 前端类型检查 + 产物构建 |
README.md
+93 -63
View File
@@ -1,95 +1,125 @@
# new-api-key-usage # new-api-key-usage
> 针对 NewAPI 平台的 key 用量统计工具 > NewAPI 网关下的 key 用量统计工具（产品名 **NAKU**）
定时用每个 sk-key 轮询网关日志接口，按 `request_id` 去重，攒全量日志到数据库；任意时间范围的用量查询，即一条本地聚合查询。 定时用每个 sk-key 轮询网关日志接口，按 `request_id` 去重，攒全量日志到数据库；任意时间范围的用量查询，即一条本地聚合查询。
| 项目 | 内容 | | 项目 | 内容 |
|------|------| |------|------|
| 当前状态 | **实现推进中**（`v1` 分支 = 文档中心 + 实现主线）——设计文档全部定稿；后端 + 同步引擎已落地；前端总览与 Key 管理已实现，其余页面进行中 | | 当前状态 | **实现推进中**——设计文档主体定稿；后端 + 同步引擎 + 前端（管理面与成员视图）已落地；部署链与衍生形态待收尾 |
| 技术栈 | 全栈 TypeScript（选型定稿见 [`docs/design/技术选型.md`](docs/design/技术选型.md)）：母体 Bun + Hono + Drizzle + PostgreSQL · 前端 Vue 3 + antdv-next | | 技术栈 | 全栈 TypeScript（选型见 [`docs/design/技术选型.md`](docs/design/技术选型.md)）：Bun + Hono + Drizzle + PostgreSQL · 前端 Vue 3 + antdv-next |
## 项目沿革 ## 这是什么
| 阶段 | 形态 | 结局 | 面向 [NewAPI](https://github.com/QuantumNous/new-api) 实例的**独立计费辅助平台**：作者购买订阅额度后，创建多个 sk- API key 分发给多名使用者分摊成本。平台只提供**事实服务**——用量、来源标注、支付参数、多维统计；**不算「谁该付谁多少钱」**（分摊是人和人之间的事）。
|------|------|------|
| 初版方案 | Cloudflare Workers | 弃——当时运营方愿意提供服务器资源 |
| 新版设计（当前） | **本分支，设计已收官、实现推进中** | 捡回 Cloudflare Workers（**serverless 后端**：Cron 定时轮询 + 云端数据库攒库，非初版原案复刻）作为后续衍生形态；母体完整前后端先行，CFW 延后至功能全集实现后 |
**双形态并行的直接动因**：服务器部署形态下，每次迭代都需实例运营方在服务器上手工升级，测试阶段迭代频繁而运营方无暇跟随；若部署到作者自控的 Cloudflare 账号（Workers + Pages），迭代部署权回到作者手里。 - 名字直述用途：NewAPI 网关下按 key 查询用量（key usage）；产品展示名 NAKU
- 全场景统一小写 kebab-case：仓库名 / 包名一致
## 文档地图 ## 背景与约束
| 文档 | 什么时候读 | 状态 | - 真实场景：NewAPI（Go + GORM 开源 LLM 网关）实例提供订阅服务，多使用者通过分发 API key 共享订阅额度——**非商业，纯成本分担**
|------|-----------|------| - 项目作者是该实例的**普通用户**：只有 sk-key，**没有实例管理员账号**
| [`docs/design/需求清单.md`](docs/design/需求清单.md) | **需求权威索引与裁决档案**——R1–R15 全部定案；2026-10-09 增补支付拆表裁决 | 定稿（2026-10-09） |
| [`docs/design/技术选型.md`](docs/design/技术选型.md) | 母体技术栈裁决（CFW 延后至功能全集实现后，仅零成本 R14 预留）：全栈 TS；Bun + Hono + Drizzle/pg；前端 Vue 3 + antdv-next；分层落地与回退；antdv-next 核验通过（§7.1） | 定稿（2026-10-02） |
| [`docs/design/api_keys表字段设计.md`](docs/design/api_keys表字段设计.md) | 数据模型第一张表：key 登记、生命周期与成员归属 | 定稿（2026-10-01） |
| [`docs/design/usage_logs表字段设计.md`](docs/design/usage_logs表字段设计.md) | 数据模型第二张表：日志明细、来源提列、去重与写入策略 | 同上 |
| [`docs/design/payments建模评估.md`](docs/design/payments建模评估.md) | 支付建模复盘：订阅权益 vs 充值入账两分；**方案 B 拆表已采纳**（2026-10-09） | 定稿（2026-10-09） |
| [`docs/design/subscriptions表字段设计.md`](docs/design/subscriptions表字段设计.md) | 订阅权益：期间 + 额度预算 + 可选付款事实；`subscription_id` 直连日志 | 待审阅（2026-10-09） |
| [`docs/design/topups表字段设计.md`](docs/design/topups表字段设计.md) | 充值入账事件：`paid_at` 主轴；不挂订阅 | 待审阅（2026-10-09） |
| [`docs/design/qpu_history表字段设计.md`](docs/design/qpu_history表字段设计.md) | 数据模型第四张表：换算参数时间线（自动采样、只读） | 同上 |
| [`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/交互设计-调用日志.md`](docs/design/交互设计-调用日志.md) | 管理面调用日志：筛选、明细表、与 key/成员/总览的跳转链 | 草案（待审阅） |
| [`docs/design/交互设计-key管理.md`](docs/design/交互设计-key管理.md) | 登记（sk-key 唯一界面露面）、启停、归属、死亡显形 | 同上 |
| [`docs/design/交互设计-支付记录.md`](docs/design/交互设计-支付记录.md) | 支付记录页（两 Tab）：订阅权益 / 充值入账登记、核对提示 | 待审阅（2026-10-09 拆表重写） |
| [`docs/design/交互设计-成员管理.md`](docs/design/交互设计-成员管理.md) | 开户、令牌签发/重发（明文仅一次）、停用 | 同上 |
| [`docs/design/交互设计-审计日志.md`](docs/design/交互设计-审计日志.md) | 管理操作留痕时间线 | 同上 |
| [`docs/design/交互设计-成员视图.md`](docs/design/交互设计-成员视图.md) | 成员世界——管理端同构壳三页（总览 / 调用日志 / 支付参数）；R12：订阅徽章弹窗 + 行展开调用详情 | 定稿（2026-10-09） |
| [`docs/design/API契约-公共约定.md`](docs/design/API契约-公共约定.md) | API 契约总纲：路由隔离与鉴权两档、错误信封、时间 / 数值 / 分页 / 命名（8 条拟定约定经审通过）——后两篇的引用锚点 | 定稿（2026-10-02） |
| [`docs/design/API契约-管理面.md`](docs/design/API契约-管理面.md) | 管理面 18 端点：引导与会话、引擎、总览、key、日志、**订阅/充值拆资源**、成员、审计 | 待审阅（2026-10-09 §7 拆表修订） |
| [`docs/design/API契约-成员视图.md`](docs/design/API契约-成员视图.md) | 成员视图 3 端点：`/me` · `/overview`（`subscriptions`+`topups`）· `/logs` | 待审阅（2026-10-09 拆表修订） |
| [`docs/design/同步引擎设计.md`](docs/design/同步引擎设计.md) | 独立 `apps/engine` 进程：手写 `setTimeout` 轮次、失败只记录、`engine_status` 快照供 `/api/admin/engine`；周期可配、**不为 CFW 预留** | 已实现（定稿 2026-10-05） |
| [`docs/references/NewAPI-接口范围.md`](docs/references/NewAPI-接口范围.md) | 计费平台在 NewAPI 中可用的接口参考：鉴权档位、请求与返回结构、字段语义、实测行为、源码出处（**唯一上游参考**） | 事实依据 |
- 命名与分区：**目录用英文、文档名用中文**；`docs/design/`（我们定的方案与决策）· `docs/references/`（平台可用接口参考——实证事实，不做设计决策）
- 生命周期：设计文档定稿后不搬家、只改状态（草案 → 讨论中 → 待审阅 → 定稿(日期) → 已实现）；被取代时删除（git 历史即考古）
## 这是什么项目
- 名字直述用途：NewAPI 网关下按 key 查询用量（key usage）
- 全场景统一小写 kebab-case：仓库名 / 包名 / 文档标题一致，无大写变体
## 背景故事
- 本工具源于一个真实场景：[NewAPI](https://github.com/QuantumNous/new-api)（Go + GORM 的开源 LLM 网关）实例提供订阅服务，多个使用者通过分发 API key 共享同一份订阅额度
- 项目作者是该实例的**普通用户**：购买了订阅额度，创建多个 sk- API key 分发给多名使用者分摊使用成本——**非商业，纯成本分担**
- 关键身份约束：项目作者**只有 sk-key，没有实例的管理员账号**。因此：
- 一切数据获取只能走 key 级接口（账号级接口用 sk-key 访问会 401） - 一切数据获取只能走 key 级接口（账号级接口用 sk-key 访问会 401）
- 部署形态已裁决为**双形态并行**：完整前后端部署在实例运营方提供的服务器上（作者不接触服务器）+ Cloudflare Workers 抽取版部署在作者自控账号（见 [`docs/design/需求清单.md`](docs/design/需求清单.md) R13） - 交付形态为**双形态并行**：完整前后端部署在实例运营方提供的服务器上（作者不接触服务器）+ Cloudflare Workers 抽取版部署在作者自控账号（见 [`docs/design/需求清单.md`](docs/design/需求清单.md) R13）
## 核心需求（基线摘要；完整范围见需求清单） **双形态并行的动因**：服务器部署形态下，每次迭代都需实例运营方手工升级；部署到作者自控的 Cloudflare 账号后，迭代部署权回到作者手里。母体完整前后端先行，Workers 抽取版延后至功能全集实现后。
| # | 需求 | 说明 | ## 核心能力
| # | 能力 | 说明 |
|---|------|------| |---|------|------|
| 1 | key 用量查询 | 按时间范围查模型请求日志与用量；作者的全员视角经管理面总览实现——「凭 sk-key 的开放查询」与「多 key 合并查询」机制已裁撤（见需求清单裁决记录） | | 1 | key 用量查询 | 按时间范围查模型请求日志与用量；作者全员视角在管理面总览，成员视角在成员视图 |
| 2 | key 登记 | 管理通道手动登记：登记后入库并加入轮询；查看面凭已登记的 key 查询（纯只读） | | 2 | key 登记 | 管理通道手动登记：入库并加入轮询；生命周期为手动启停（引擎只读 `status`） |
| 3 | 支付事实登记 | 订阅权益与充值入账分表登记；对成员完全公开透明 |
| 4 | 多维统计 | 按成员 / key / 计费来源 / 模型的任意时段聚合 |
基线刻意收缩的部分（费用分摊计算、计费周期管理、多组支持、登录页、admin 角色、会话记忆）与新增域（数据资产保护等）的完整需求盘点见 [`docs/design/需求清单.md`](docs/design/需求清单.md)。 完整需求范围（含刻意不做的部分）见 [`docs/design/需求清单.md`](docs/design/需求清单.md)。
## 架构的根本动因：为什么必须攒数据 ## 架构的根本动因：为什么必须攒数据
这不是优化选项，是上游接口的物理约束决定的**唯一路径**（不随部署形态改变）： 这不是优化选项，是上游接口的物理约束决定的**唯一路径**（不随部署形态改变）：
1. sk-key 可用的接口（`/api/usage/token`、`/api/log/token` 等）返回的都是**累计值**或**最近 1000 条**，没有任何接口支持时间范围过滤 1. sk-key 可用的接口（`/api/usage/token`、`/api/log/token` 等）返回的都是**累计值**或**最近 1000 条**，没有任何接口支持时间范围过滤
2. 真正适合算“当月用量”的接口（`/api/log/self/stat`，支持时间范围 + quota 汇总）需要账号登录态，sk-key 访问 401——这是“按时间段统计用量”无法纯客户端实现的**核心障碍** 2. 真正适合算「当月用量」的接口（`/api/log/self/stat`，支持时间范围 + quota 汇总）需要账号登录态，sk-key 访问 401——这是「按时间段统计用量」无法纯客户端实现的**核心障碍**
3. `/api/log/token` 硬上限 1000 条、不支持任何参数（分页 / limit / 时间过滤全被忽略） 3. `/api/log/token` 硬上限 1000 条、不支持任何参数（分页 / limit / 时间过滤全被忽略）
→ 结论：轮询同步 + `request_id` 去重入库 + 数据库。**部署形态可以变（运营方服务器 / Cloudflare Workers），攒库架构不变。**上游接口完整实证（含源码出处）见 [`docs/references/NewAPI-接口范围.md`](docs/references/NewAPI-接口范围.md)。 → 结论：轮询同步 + `request_id` 去重入库 + 数据库。**部署形态可以变，攒库架构不变。** 上游接口完整实证（含源码出处）见 [`docs/references/NewAPI-接口范围.md`](docs/references/NewAPI-接口范围.md)。
## 技术栈与结构
全栈 TypeScript，monorepo（Bun workspaces）：
```text
apps/
server/ # 后端：Hono + Drizzle/pg + Scalar 在线文档
engine/ # 同步引擎：独立进程，轮询去重入库
web/ # 前端：Vue 3 + antdv-next + Vite
packages/
core/ # 业务核心：去重、折算、加密、上游客户端、DTO
db/ # 数据访问层：Drizzle schema + 仓储
```
数据模型：`api_keys` · `usage_logs` · `subscriptions` · `topups` · `qpu_history` + `members` · `users` · `sessions`。
## 快速开始
前置：Bun、Docker（开发用 PostgreSQL）。
```bash
bun install
docker compose up -d # 起 PostgreSQL
cp .env.example .env # 按注释填写
bun run db:push # 推送 schema
bun run dev:server # 后端（默认 18456）
bun run dev:engine # 同步引擎（另开终端）
bun run dev:web # 前端 Vite（5175）
```
在线 API 文档：`http://127.0.0.1:18456/api/docs`。
更多命令与协作约定见 [`AGENTS.md`](AGENTS.md)。
## 文档地图
| 文档 | 什么时候读 | 状态 |
|------|-----------|------|
| [`docs/design/需求清单.md`](docs/design/需求清单.md) | **需求权威索引与裁决档案**——R1–R15 全部定案；含支付拆表裁决 | 定稿（2026-10-09） |
| [`docs/design/技术选型.md`](docs/design/技术选型.md) | 技术栈裁决：全栈 TS；Bun + Hono + Drizzle/pg；前端 Vue 3 + antdv-next；分层落地与回退 | 定稿（2026-10-02） |
| [`docs/design/api_keys表字段设计.md`](docs/design/api_keys表字段设计.md) | key 登记、生命周期与成员归属 | 定稿（2026-10-01） |
| [`docs/design/usage_logs表字段设计.md`](docs/design/usage_logs表字段设计.md) | 日志明细、来源提列、去重与写入策略 | 同上 |
| [`docs/design/payments建模评估.md`](docs/design/payments建模评估.md) | 支付建模复盘：订阅权益 vs 充值入账两分；拆表已采纳 | 定稿（2026-10-09） |
| [`docs/design/subscriptions表字段设计.md`](docs/design/subscriptions表字段设计.md) | 订阅权益：期间 + 额度预算 + 可选付款事实；`subscription_id` 直连日志 | 待审阅（2026-10-09） |
| [`docs/design/topups表字段设计.md`](docs/design/topups表字段设计.md) | 充值入账事件：`paid_at` 主轴；不挂订阅 | 待审阅（2026-10-09） |
| [`docs/design/qpu_history表字段设计.md`](docs/design/qpu_history表字段设计.md) | 换算参数时间线（自动采样、只读） | 定稿（2026-10-01） |
| [`docs/design/members表字段设计.md`](docs/design/members表字段设计.md) | 成员实体——key 归属、成员视图身份与按成员统计的锚点 | 同上 |
| [`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/交互设计-调用日志.md`](docs/design/交互设计-调用日志.md) | 调用日志：筛选、明细表、与 key/成员/总览的跳转链 | 定稿（2026-10-08） |
| [`docs/design/交互设计-key管理.md`](docs/design/交互设计-key管理.md) | 登记（sk-key 唯一界面露面）、启停、归属、死亡显形 | 定稿（2026-10-01） |
| [`docs/design/交互设计-支付记录.md`](docs/design/交互设计-支付记录.md) | 支付记录（两 Tab）：订阅权益 / 充值入账登记、核对提示 | 待审阅（2026-10-09） |
| [`docs/design/交互设计-成员管理.md`](docs/design/交互设计-成员管理.md) | 开户、令牌签发/重发（明文仅一次）、停用 | 定稿（2026-10-01） |
| [`docs/design/交互设计-审计日志.md`](docs/design/交互设计-审计日志.md) | 管理操作留痕时间线 | 同上 |
| [`docs/design/交互设计-成员视图.md`](docs/design/交互设计-成员视图.md) | 成员视图三页（总览 / 调用日志 / 支付参数）；订阅徽章展开 + 调用详情 | 定稿（2026-10-09） |
| [`docs/design/API契约-公共约定.md`](docs/design/API契约-公共约定.md) | API 总纲：路由隔离与鉴权两档、错误信封、时间 / 数值 / 分页 / 命名 | 定稿（2026-10-02） |
| [`docs/design/API契约-管理面.md`](docs/design/API契约-管理面.md) | 管理面 18 端点 | 待审阅（2026-10-09） |
| [`docs/design/API契约-成员视图.md`](docs/design/API契约-成员视图.md) | 成员视图 3 端点：`/me` · `/overview` · `/logs` | 待审阅（2026-10-09） |
| [`docs/design/同步引擎设计.md`](docs/design/同步引擎设计.md) | 独立 `apps/engine`：轮次、失败只记录、`engine_status` 快照 | 已实现（定稿 2026-10-05） |
| [`docs/references/NewAPI-接口范围.md`](docs/references/NewAPI-接口范围.md) | 上游可用接口参考：鉴权档位、字段语义、实测行为、源码出处（**唯一上游参考**） | 事实依据 |
- 命名与分区：**目录用英文、文档名用中文**；`docs/design/`（方案与决策）· `docs/references/`（平台可用接口参考——实证事实，不做设计决策）
- 生命周期：状态流转（草案 → 讨论中 → 待审阅 → 定稿(日期) → 已实现）；定稿后不搬家、只改状态；被取代时删除（git 历史即考古）
## 关键事实清单（实测 / 源码确认，设计时不得违反） ## 关键事实清单（实测 / 源码确认，设计时不得违反）
> 出处均见 [`docs/references/NewAPI-接口范围.md`](docs/references/NewAPI-接口范围.md)，此处仅索引。 > 出处均见 [`docs/references/NewAPI-接口范围.md`](docs/references/NewAPI-接口范围.md)，此处仅索引。
1. **`QuotaPerUnit = 500000`**：quota ÷ 500000 = 额度美元——**它不是实付金额**：折算到实付人民币还需乘「购买汇率」（由运营方定价、可变，历史上调整过一次） 1. **`QuotaPerUnit = 500000`**：quota ÷ 500000 = 额度美元——**它不是实付金额**；折算到实付金额还需乘「购买汇率」（由运营方定价、可变）
2. **去重必须用 `request_id`**：`/api/log/token` 返回的 `id` 是每次从 1 重编的展示序号，绝不能用于去重 2. **去重必须用 `request_id`**：`/api/log/token` 返回的 `id` 是每次从 1 重编的展示序号，绝不能用于去重
3. **`created_at` 是 UTC Unix 秒**（三字段交叉实测），北京时间输入需转换 3. **`created_at` 是 UTC Unix 秒**，本地时间输入需转换
4. **1000 条硬上限**：窗口只保留最近 1000 条——实测当前站点的日志速率下约等于 3 天；5 分钟级同步余量充分，但同步停摆超过约 3 天会永久丢数据 4. **1000 条硬上限**：窗口只保留最近 1000 条——当前日志速率下约等于 3 天；同步停摆超过窗口会永久丢数据
5. **`TokenAuthReadOnly`**：用量/日志接口用宽松鉴权，key 过期 / 额度耗尽仍可查询（用完也能对账）；**显式禁用会被 401 拒绝** 5. **`TokenAuthReadOnly`**：用量/日志接口用宽松鉴权，key 过期 / 额度耗尽仍可查询；**显式禁用会被 401 拒绝**
6. **`DisplayTokenStatEnabled` 已开启**：billing 接口返回 token 级额度 6. **`DisplayTokenStatEnabled` 已开启**：billing 接口返回 token 级额度
apps/server/README.md
-13
View File
@@ -1,13 +0,0 @@
# apps/server
母体后端（Hono + Bun）。
```sh
bun install
bun run dev
```
默认端口 **18456**（可用 `PORT` 覆盖）：
- 在线文档：http://127.0.0.1:18456/api/docs
- OpenAPI：http://127.0.0.1:18456/api/openapi.json
apps/web/README.md
-54
View File
@@ -1,54 +0,0 @@
# apps/web
This template should help get you started developing with Vue 3 in Vite.
## Recommended IDE Setup
[VS Code](https://code.visualstudio.com/) + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
## Recommended Browser Setup
- Chromium-based browsers (Chrome, Edge, Brave, etc.):
- [Vue.js devtools](https://chromewebstore.google.com/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
- [Turn on Custom Object Formatter in Chrome DevTools](http://bit.ly/object-formatters)
- Firefox:
- [Vue.js devtools](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)
- [Turn on Custom Object Formatter in Firefox DevTools](https://fxdx.dev/firefox-devtools-custom-object-formatters/)
## Type Support for `.vue` Imports in TS
TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types.
## Customize configuration
See [Vite Configuration Reference](https://vite.dev/config/).
## Project Setup
```sh
bun install
```
### Compile and Hot-Reload for Development
```sh
bun dev
```
### Type-Check, Compile and Minify for Production
```sh
bun run build
```
### Run Unit Tests with [Vitest](https://vitest.dev/)
```sh
bun test:unit
```
### Lint with [ESLint](https://eslint.org/)
```sh
bun lint
```
docs/design/API契约-公共约定.md
+2 -2
View File
@@ -5,7 +5,7 @@
| 项目 | 内容 | | 项目 | 内容 |
|------|------| |------|------|
| 状态 | 定稿（2026-10-02） | | 状态 | 定稿（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 命名 ## 7. DTO 命名
- **snake_case、与表字段同名同构**——七篇表字段设计即 DTO 字段权威，无映射层 - **snake_case、与表字段同名同构**——各篇表字段设计即 DTO 字段权威，无映射层
- 前端不做 camelCase 转换：全栈 snake_case（组件 props 是 antd 的 API、与数据 DTO 互不干扰） - 前端不做 camelCase 转换：全栈 snake_case（组件 props 是 antd 的 API、与数据 DTO 互不干扰）
## 8. 本稿拟定约定（交互设计未覆盖，请作者重点审） ## 8. 本稿拟定约定（交互设计未覆盖，请作者重点审）
docs/design/API契约-管理面.md
+1 -1
View File
@@ -5,7 +5,7 @@
| 项目 | 内容 | | 项目 | 内容 |
|------|------| |------|------|
| 状态 | 待审阅（2026-10-09 支付拆表修订——§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） | | 产出 | 端点清单、请求 / 响应字段、错误码、本稿裁定项（§10）与遗留项（§11） |
--- ---
docs/design/交互设计-总览与共性.md
+1 -1
View File
@@ -5,7 +5,7 @@
| 项目 | 内容 | | 项目 | 内容 |
|------|------| |------|------|
| 状态 | 定稿（2026-10-01） | | 状态 | 定稿（2026-10-01） |
| 关联 | `需求清单.md`（R 编号与裁决记录——本文全部设计的依据）· 七篇表字段设计（数据来源） | | 关联 | `需求清单.md`（R 编号与裁决记录——本文全部设计的依据）· 各篇表字段设计（数据来源） |
| 产出 | 访问拓扑、导航结构、跨页组件、状态模式、数值与时间呈现 | | 产出 | 访问拓扑、导航结构、跨页组件、状态模式、数值与时间呈现 |
--- ---
docs/design/同步引擎设计.md
+1 -1
View File
@@ -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 库），周期**可配置**。字段与去重的权威仍在各篇表字段设计；本文定「引擎怎么转」。
| 项目 | 内容 | | 项目 | 内容 |
|------|------| |------|------|
docs/design/技术选型.md
+3 -3
View File
@@ -41,13 +41,13 @@
| 前端框架 | **Vue 3** | 作者近年常用栈；实现期自由度（共性 §3.5「作者即前端」） | — | | 前端框架 | **Vue 3** | 作者近年常用栈；实现期自由度（共性 §3.5「作者即前端」） | — |
| 组件库 | **antdv-next**（作者指定尝试项） | Vue 3 企业组件库、对齐 ant-design（React 上游）设计体系；**已核验通过**（§7.1）：活跃周更、§3.7 清单逐项有对应组件、Agent 文档齐备 | Element Plus / ant-design-vue（§3.7 全覆盖） | | 组件库 | **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 垫片（同原语） | | 加密 | **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（规范不动、换皮即可） | | API 文档与校验 | **zod** + **@hono/zod-openapi** + **Scalar**（作者确认） | 一源三用：TS 类型 / 请求校验（`422` 与 `fields` 的机器来源）/ OpenAPI 生成；Scalar 为 Hono 官方搭档，规范与渲染器解耦 | Swagger UI（规范不动、换皮即可） |
## 4. 分层落地：monorepo（Bun workspaces） ## 4. 分层落地：monorepo（Bun workspaces）
```text ```text
（仓库根 · v1 分支） （仓库根）
├─ apps/ ├─ apps/
│ ├─ server/ # 母体后端：Hono serve 装配 · Drizzle/pg · 进程内调度 · 环境变量与密钥注入 │ ├─ server/ # 母体后端：Hono serve 装配 · Drizzle/pg · 进程内调度 · 环境变量与密钥注入
│ └─ web/ # 前端：Vue 3 + antdv-next + Vite │ └─ web/ # 前端：Vue 3 + antdv-next + Vite
@@ -58,7 +58,7 @@
**依赖规则（单向）**：`apps/*` → `packages/db` → `packages/core`；core 导出的 DTO 类型可被 web 以纯类型依赖引用（前后端共用一份契约类型）。 **依赖规则（单向）**：`apps/*` → `packages/db` → `packages/core`；core 导出的 DTO 类型可被 web 以纯类型依赖引用（前后端共用一份契约类型）。
**代码落点**：实现代码与设计文档同在 v1 分支演进。 **代码落点**：实现代码与设计文档同仓演进。
## 5. R14 预留：现阶段零成本，只为后续抽取不挖坑 ## 5. R14 预留：现阶段零成本，只为后续抽取不挖坑
docs/design/需求清单.md
+8 -8
View File
@@ -5,7 +5,7 @@
| 项目 | 内容 | | 项目 | 内容 |
|------|------| |------|------|
| 状态 | 定稿（2026-10-01） | | 状态 | 定稿（2026-10-01） |
| 关联 | `README.md`（项目沿革与动因）· 七篇表字段设计（定稿）· `docs/references/NewAPI-接口范围.md`（可用接口参考） | | 关联 | `README.md`（背景、动因与架构约束）· 各篇表字段设计 · `docs/references/NewAPI-接口范围.md`（可用接口参考） |
| 取代 | 《设计议题》（2026-09-29 由本清单取代；其中双形态裁决与 CFW 调研结论已并入本文 §5/§7） | | 取代 | 《设计议题》（2026-09-29 由本清单取代；其中双形态裁决与 CFW 调研结论已并入本文 §5/§7） |
--- ---
@@ -19,7 +19,7 @@
**背景**（三类问题促成当前设计阶段）： **背景**（三类问题促成当前设计阶段）：
1. **迭代部署成本**：服务器部署形态下每次迭代都需实例运营方手工升级，测试阶段迭代频繁而运营方无暇跟随 → 双形态交付（R13，已裁决） 1. **迭代部署成本**：服务器部署形态下每次迭代都需实例运营方手工升级，测试阶段迭代频繁而运营方无暇跟随 → 双形态交付（R13，已裁决）
2. **初版设计刻意收缩的部分**：管理面固定口令不妥（R11）、充值折算（R7）、多订阅处理（R8） 2. **刻意收缩后重新纳入的部分**：管理面固定口令不妥（R11）、充值折算（R7）、多订阅处理（R8）
3. **已知设计问题**：错误行 `request_id` 去重（R15 必修项） 3. **已知设计问题**：错误行 `request_id` 去重（R15 必修项）
## 1. 数据采集域 ## 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 官方文档核实，五项全部无阻断） ## 7. R13 的支撑材料：CFW 可行性调研（2026-09-29，developers.cloudflare.com 官方文档核实，五项全部无阻断）
@@ -90,7 +90,7 @@
## 8. 推进方式 ## 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. 裁决记录 ## 9. 裁决记录
@@ -138,11 +138,11 @@
### 2026-10-01 · R15 审阅定稿 ### 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，部门实例场景触发）：无支付记录 = 完整可用子集——参数卡中性空态、展开行降级、核对提示全空静默、订阅期间快捷项隐藏 - **纯用量模式**（共性 §3.8，部门实例场景触发）：无支付记录 = 完整可用子集——参数卡中性空态、展开行降级、核对提示全空静默、订阅期间快捷项隐藏
- **响应式范围收缩**（作者裁决）：只做布局响应，不做组件响应与移动端 UI 重设计 - **响应式范围收缩**（作者裁决）：只做布局响应，不做组件响应与移动端 UI 重设计
@@ -157,7 +157,7 @@
- **未关联分组 = 查询层产物**（LEFT JOIN 未匹配集，无新字段），正常时恒为零，非零即异常信号；两种未关联（日志缺 ID / 有 ID 无登记）的展示区分留设计期 - **未关联分组 = 查询层产物**（LEFT JOIN 未匹配集，无新字段），正常时恒为零，非零即异常信号；两种未关联（日志缺 ID / 有 ID 无登记）的展示区分留设计期
- **统计 = 派生视图**：数据库只存事实行，一切分组/分解/汇总为查询时聚合，无预计算存储 - **统计 = 派生视图**：数据库只存事实行，一切分组/分解/汇总为查询时聚合，无预计算存储
### 2026-10-09 · 支付建模拆表（方案 B） ### 2026-10-09 · 支付建模拆表
- **裁决：`payments` 单表拆为 `subscriptions`（订阅权益）+ `topups`（充值入账事件）**——`paid_at` 在订阅行上语义污染（更像登记时刻），后补录无法按付款时间对齐用量窗口；对齐 NewAPI「权益 vs 入账」两分（评估见 `payments建模评估.md`） - **裁决：`payments` 单表拆为 `subscriptions`（订阅权益）+ `topups`（充值入账事件）**——`paid_at` 在订阅行上语义污染（更像登记时刻），后补录无法按付款时间对齐用量窗口；对齐 NewAPI「权益 vs 入账」两分（评估见 `payments建模评估.md`）
- **三时刻钉死**：`created_at`（登记）· `paid_at`（钱出手，订阅可空）· `period_*`（用量覆盖期）；筛选：订阅看期间重叠、充值看 `paid_at`、补录看 `created_at` - **三时刻钉死**：`created_at`（登记）· `paid_at`（钱出手，订阅可空）· `period_*`（用量覆盖期）；筛选：订阅看期间重叠、充值看 `paid_at`、补录看 `created_at`
package.json
-1
View File
@@ -4,7 +4,6 @@
"type": "module", "type": "module",
"workspaces": ["apps/*", "packages/*"], "workspaces": ["apps/*", "packages/*"],
"scripts": { "scripts": {
"test": "bun test",
"typecheck": "tsc -p tsconfig.json --noEmit", "typecheck": "tsc -p tsconfig.json --noEmit",
"dev:server": "bun --hot --env-file=.env apps/server/src/index.ts", "dev:server": "bun --hot --env-file=.env apps/server/src/index.ts",
"dev:engine": "bun --env-file=.env apps/engine/src/index.ts", "dev:engine": "bun --env-file=.env apps/engine/src/index.ts",