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

docs: 对齐实现状态——进程拆分、部署与支付拆表相关稿定稿

Browse Source
This commit is contained in:
skycurtain
2026-10-13 01:11:13 +08:00
parent 905d4ce77e
commit 2dbd625e87
9 changed files with 18 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+6 -6
View File
@@ -6,7 +6,7 @@
| 项目 | 内容 |
|------|------|
| 当前状态 | **实现推进中**——设计文档主体定稿；后端 + 同步引擎 + 前端（管理面与成员视图）已落地；部署方案与衍生形态待定 |
| 当前状态 | **实现推进中**——设计文档主体定稿；后端 + 同步引擎 + 前端（管理面与成员视图）已落地；部署链已定（见 [`docs/design/部署方案.md`](docs/design/部署方案.md)）；CFW 衍生形态待做 |
| 技术栈 | 全栈 TypeScript（选型见 [`docs/design/技术选型.md`](docs/design/技术选型.md)）：Bun + Hono + Drizzle + PostgreSQL · 前端 Vue 3 + antdv-next |
## 这是什么
@@ -125,8 +125,8 @@ docker compose ps # migrate 应为 exited(0)，其余 running/healthy
| [`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/subscriptions表字段设计.md`](docs/design/subscriptions表字段设计.md) | 订阅权益：期间 + 额度预算 + 可选付款事实；`subscription_id` 直连日志 | 定稿（2026-10-12） |
| [`docs/design/topups表字段设计.md`](docs/design/topups表字段设计.md) | 充值入账事件：`paid_at` 主轴；不挂订阅 | 定稿（2026-10-12） |
| [`docs/design/qpu_history表字段设计.md`](docs/design/qpu_history表字段设计.md) | 换算参数时间线（自动采样、只读） | 定稿（2026-10-01） |
| [`docs/design/members表字段设计.md`](docs/design/members表字段设计.md) | 成员实体——key 归属、身份与统计锚点；档案可改、空壳可删 | 定稿（2026-10-10） |
| [`docs/design/users表字段设计.md`](docs/design/users表字段设计.md) | 管理员（单行）——登录体系的身份落点 | 同上 |
@@ -136,13 +136,13 @@ docker compose ps # migrate 应为 exited(0)，其余 running/healthy
| [`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) | 支付记录（两 Tab）：订阅权益 / 充值入账登记、核对提示 | 定稿（2026-10-12） |
| [`docs/design/交互设计-成员管理.md`](docs/design/交互设计-成员管理.md) | 开户、档案修改、令牌签发/重发、启停、空壳删除 | 定稿（2026-10-10） |
| [`docs/design/交互设计-审计日志.md`](docs/design/交互设计-审计日志.md) | 管理操作留痕时间线 | 定稿（2026-10-10） |
| [`docs/design/交互设计-成员视图.md`](docs/design/交互设计-成员视图.md) | 成员视图三页（总览 / 调用日志 / 支付参数）；订阅徽章展开 + 调用详情 | 定稿（2026-10-09） |
| [`docs/design/API契约-公共约定.md`](docs/design/API契约-公共约定.md) | API 总纲：路由隔离与鉴权两档、错误信封、时间 / 数值 / 分页 / 命名 | 定稿（2026-10-10） |
| [`docs/design/API契约-管理面.md`](docs/design/API契约-管理面.md) | 管理面 18 端点 | 待审阅（2026-10-09 支付拆表）；R16 定稿 |
| [`docs/design/API契约-成员视图.md`](docs/design/API契约-成员视图.md) | 成员视图 3 端点：`/me` · `/overview` · `/logs` | 待审阅（2026-10-09） |
| [`docs/design/API契约-管理面.md`](docs/design/API契约-管理面.md) | 管理面 18 端点 | 定稿（2026-10-12） |
| [`docs/design/API契约-成员视图.md`](docs/design/API契约-成员视图.md) | 成员视图 3 端点：`/me` · `/overview` · `/logs` | 定稿（2026-10-12） |
| [`docs/design/同步引擎设计.md`](docs/design/同步引擎设计.md) | 独立 `apps/engine`：轮次、失败只记录、`engine_status` 快照 | 已实现（定稿 2026-10-05） |
| [`docs/references/NewAPI-接口范围.md`](docs/references/NewAPI-接口范围.md) | 上游可用接口参考：鉴权档位、字段语义、实测行为、源码出处（**唯一上游参考**） | 事实依据 |
docs/design/API契约-成员视图.md
+1 -1
View File
@@ -4,7 +4,7 @@
| 项目 | 内容 |
|------|------|
| 状态 | 待审阅（2026-10-09 支付拆表——overview 分 `subscriptions`/`topups`） |
| 状态 | 定稿（2026-10-12，作者认可实现） |
| 关联 | 《API契约-公共约定》（定稿——总纲）·《API契约-管理面》·《交互设计-成员视图》·《交互设计-登录与会话》§4（登录壳）· `members` / `usage_logs` / `subscriptions` / `topups` 表字段设计（DTO 字段权威） |
| 产出 | 端点清单（3 个）、请求 / 响应字段、裁定项（§5）、遗留项（§6） |
docs/design/API契约-管理面.md
+1 -1
View File
@@ -4,7 +4,7 @@
| 项目 | 内容 |
|------|------|
| 状态 | 待审阅（2026-10-09 支付拆表修订——§7）；R16 定稿（2026-10-10——§8） |
| 状态 | 定稿（2026-10-12，作者认可实现；含 10-09 支付拆表与 R16） |
| 关联 | 《API契约-公共约定》（定稿——总纲）· 八篇交互设计 · `api_keys` / `usage_logs` / `subscriptions` / `topups` / `qpu_history` / `members` / `users` / `sessions` 表字段设计（DTO 字段权威）· `需求清单.md` §9（访问主体模型） |
| 产出 | 端点清单、请求 / 响应字段、错误码、本稿裁定项（§10）与遗留项（§11） |
docs/design/subscriptions表字段设计.md
+1 -1
View File
@@ -4,7 +4,7 @@
| 项目 | 内容 |
|------|------|
| 状态 | 待审阅（2026-10-09 拆出自原 `payments` 单表） |
| 状态 | 定稿（2026-10-12，作者认可实现） |
| 关联 | `topups表字段设计.md`（充值事件）· `payments建模评估.md`（拆表裁决）· `usage_logs表字段设计.md` 3.6（`subscription_id` 直连）· `qpu_history表字段设计.md` · `docs/references/NewAPI-接口范围.md` §4.3 |
| 范围 | 列结构 + 语义 + 写入时机；方言映射归数据访问层 |
| 字段数 | 9 = 1 主键 + 1 上游编号 + 2 期间 + 1 额度 + 2 付款（可空） + 1 备注 + 1 登记时刻 |
docs/design/topups表字段设计.md
+1 -1
View File
@@ -4,7 +4,7 @@
| 项目 | 内容 |
|------|------|
| 状态 | 待审阅（2026-10-09 拆表 + 充值接口实测；事件时刻单列） |
| 状态 | 定稿（2026-10-12，作者认可实现） |
| 关联 | `subscriptions表字段设计.md` · `payments建模评估.md` · `NewAPI-接口范围.md` §4.5 · `qpu_history表字段设计.md` |
| 范围 | 列结构 + 语义 + 写入时机 |
| 字段数 | 10 = 1 主键 + 8 上游/业务事实 + 1 登记时刻 |
docs/design/交互设计-支付记录.md
+1 -1
View File
@@ -4,7 +4,7 @@
| 项目 | 内容 |
|------|------|
| 状态 | 待审阅（2026-10-09 随拆表重写） |
| 状态 | 定稿（2026-10-12，作者认可实现） |
| 关联 | 《交互设计-总览与共性》· `subscriptions表字段设计.md` · `topups表字段设计.md` · R7/R8 |
| 数据 | `subscriptions` + `topups` · 日志观测的订阅 ID（核对提示） |
docs/design/同步引擎设计.md
+1 -1
View File
@@ -4,7 +4,7 @@
| 项目 | 内容 |
|------|------|
| 状态 | 定稿（2026-10-05） |
| 状态 | 已实现（定稿 2026-10-05） |
| 关联 | 《api_keys表字段设计》§4 写入时机 · 《usage_logs表字段设计》§3.1 去重 · 《qpu_history表字段设计》§4 采样 · 《API契约-管理面》§3 `engine` 端点 · 《技术选型》§4 monorepo（本文增补 `apps/engine`）· `docs/references/NewAPI-接口范围.md` |
| 产出 | 进程形态 · 调度与轮次语义 · 失败与观测 · 与 `/api/admin/engine` 的状态衔接 · 配置与验收 |
docs/design/技术选型.md
+5 -3
View File
@@ -48,11 +48,13 @@
```text
（仓库根）
├─ apps/
│ ├─ server/ # 母体后端：Hono serve 装配 · Drizzle/pg · 进程内调度 · 环境变量与密钥注入
│ ├─ server/ # 母体后端：Hono serve 装配 · Drizzle/pg · 环境变量与密钥注入
│ ├─ engine/ # 同步引擎：独立进程（《同步引擎设计》）
│ └─ web/ # 前端：Vue 3 + antdv-next + Vite
├─ packages/
│ ├─ core/ # 业务核心：轮询与 request_id 去重 · 折算链 · 加密体系 · API 语义与 DTO 类型
│ └─ db/ # 数据访问层：Drizzle schema（pg 方言）+ 仓储实现
│ └─ db/ # 数据访问层：Drizzle schema（pg 方言）+ 仓储 + 迁移 CLI
├─ scripts/ # 打包/构建 CLI（naku pack / build）
```
**依赖规则（单向）**：`apps/*` → `packages/db` → `packages/core`；core 导出的 DTO 类型可被 web 以纯类型依赖引用（前后端共用一份契约类型）。
@@ -63,7 +65,7 @@
R13 的 CFW 抽取版仍是长期裁决，功能全集实现后启动，届时按 R14「从母体抽业务核心、换基础设施层」执行。本稿只保留两条现阶段零成本、届时免重写的预留：
1. **Bun 纪律**：`packages/core` 只使用 TypeScript 标准库与 Web 标准 API（`fetch` / WebCrypto / `URL` / `TextEncoder` / `setTimeout` 等）；`Bun.*`、`bun:*`、`node:*` 与具体数据库驱动只出现在 `apps/server` 与 `packages/db`——届时 CFW 形态的绑定物（D1 等）同样只落在新的装配层，core 原样搬运；
1. **Bun 纪律**：`packages/core` 只使用 TypeScript 标准库与 Web 标准 API（`fetch` / WebCrypto / `URL` / `TextEncoder` / `setTimeout` 等）；`Bun.*`、`bun:*`、`node:*` 与具体数据库驱动只出现在 `apps/*` 装配层、`packages/db` 与 `scripts/`——届时 CFW 形态的绑定物（D1 等）同样只落在新的装配层，core 原样搬运；
2. **方言不外泄**：pg 特有物（`jsonb` 等）只出现在 `packages/db` 的 schema 与仓储实现内，不进 core——届时补一份 SQLite 方言 schema 即可，core 与仓储接口不动。
Hono（双运行时可跑）与 WebCrypto 本身恰好与 CFW 兼容，属顺手之得，不构成现阶段约束。
docs/design/需求清单.md
+1 -1
View File
@@ -63,7 +63,7 @@
| # | 需求 | 说明 | 状态 |
|---|------|------|------|
| R13 | 双形态交付 | **完整前后端（先行，母体）**：服务器部署的前后端分离应用 + PostgreSQL（后端单进程承载 API 路由与同步引擎），功能全集在此形态上设计与实现；**CFW 抽取版（后续，衍生）**：Cloudflare Workers（API + Cron Triggers 轮询）+ D1 攒库 + 前端静态资产托管，从母体中抽取业务核心、替换基础设施层——承载「部署权归作者」的目标形态 | **已裁决**（2026-09-29） |
| R13 | 双形态交付 | **完整前后端（先行，母体）**：服务器部署的前后端分离应用 + PostgreSQL（`apps/server` 承载 API 路由，`apps/engine` 独立进程同步——见《同步引擎设计》2026-10-05），功能全集在此形态上设计与实现；**CFW 抽取版（后续，衍生）**：Cloudflare Workers（API + Cron Triggers 轮询）+ D1 攒库 + 前端静态资产托管，从母体中抽取业务核心、替换基础设施层——承载「部署权归作者」的目标形态 | **已裁决**（2026-09-29；进程拆分修订 2026-10-05） |
| R14 | 可移植性分层 | R13 的横切约束：业务核心（轮询逻辑 / `request_id` 去重 / 折算链计算 / 加密体系 / API 语义）与形态耦合面（HTTP 框架 / 调度器 / 数据库驱动 / 托管部署）分离；数据访问层隔离 PostgreSQL 与 SQLite/D1 方言（`jsonb` → TEXT + SQLite JSON 函数、类型与索引映射）；轮次语义统一（幂等、错过即补——每轮全量拉最近 1000 条天然补偿） | **已裁决**（2026-09-29） |
## 6. 数据模型