docs: 命令登记与 SK_KEY_ENCRYPTION_SECRET 命名对齐
AGENTS 命令表、会话留档约定；骨架搭建指南与设计文档键名对齐代码。
This commit is contained in:
@@ -9,6 +9,7 @@
|
||||
- **文档状态**：头部表格标「状态」（草案 → 讨论中 → 待审阅 → 定稿(日期) → 已实现）；设计文档定稿后不搬家、只改状态；被取代时删除（git 历史即考古）
|
||||
- **部署**：交付物必须保证「一条命令链」可部署；**双形态并行已裁决**——完整前后端（运营方服务器）先行，Cloudflare Workers 抽取版（作者自部署）后续（见 `docs/design/需求清单.md` R13）
|
||||
- **不引入版本叙事**：不使用 v1/v2/v3 之类版本编号，不以「MVP」等标签或指称显式描述任何历史阶段；文档内容必须**自立**——不得引用、描述任何当前分支之外、可能被删除的分支内容
|
||||
- **本地不入库也不 ignore 的物料**（AI 提交时务必避开）：`api*.json`（上游实测快照）、`session-archive/`（作者主动备份的会话记录，如 `v1-设计-*.md`）——不加入 git、不写 `.gitignore`，靠提交时人工/执行者目视把关；`v1-设计-1.md` 为历史对话原档，允许保留旧术语，不作现行依据
|
||||
|
||||
## 项目速览（速记）
|
||||
|
||||
@@ -19,4 +20,20 @@
|
||||
|
||||
## 命令
|
||||
|
||||
实现骨架尚未搭建，暂无构建 / 测试命令；骨架落地后在此登记（Bun 工具链，选型见 `docs/design/技术选型.md`）。
|
||||
Bun 工具链（选型见 `docs/design/技术选型.md`）。**Windows 上 `bun` 需在 PowerShell 7（`pwsh`）里跑**——mise shim 由 pwsh profile 激活；Windows PowerShell 5.1 会报 command not found，改用 `pwsh -c "…"` 或绝对路径。
|
||||
|
||||
| 命令 | 用途 |
|
||||
|------|------|
|
||||
| `bun install` | 安装 / 链接 workspace 依赖（在仓库根） |
|
||||
| `bun test` | 全部测试（core 契约 + server HTTP + **集成**）；集成需 `DATABASE_URL`（compose 中的 PG），无库时自动跳过 |
|
||||
| `bun --env-file=.env scripts/seed-from-samples.ts` | 从根目录 `api*.json` 实测快照灌开发库（幂等）；验收接口口径用 |
|
||||
| `bun run typecheck` | 根 tsconfig 类型检查（不含 web `.vue`） |
|
||||
| `bun run dev:server` | 开发跑母体后端（hot reload） |
|
||||
| `bun run dev:web` | 开发跑前端 Vite |
|
||||
| `docker compose up -d` | 起开发用 PostgreSQL |
|
||||
| `bun run --filter @new-api-key-usage/db db:generate` | 生成 SQL 迁移（`packages/db/drizzle/`） |
|
||||
| `bun run --filter @new-api-key-usage/db db:push` | 推送到本地库（开发期） |
|
||||
|
||||
环境变量见 `.env.example`（复制为 `.env` 后填写）。
|
||||
|
||||
**默认端口 `18456`**（避开 3000/3001 等本机占用）；`NEWAPI_BASE` 是上游 NewAPI 地址，与本服务端口无关。在线文档：`http://127.0.0.1:18456/api/docs`。
|
||||
|
||||
@@ -42,6 +42,7 @@
|
||||
| [`docs/design/API契约-公共约定.md`](docs/design/API契约-公共约定.md) | API 契约总纲：路由隔离与鉴权两档、错误信封、时间 / 数值 / 分页 / 命名（8 条拟定约定经审通过）——后两篇的引用锚点 | 定稿（2026-10-02） |
|
||||
| [`docs/design/API契约-管理面.md`](docs/design/API契约-管理面.md) | 管理面 16 端点：引导与会话三态、引擎状态、总览聚合、key 登记四态、下钻明细、支付、成员（令牌明文仅一次）、审计；5 项裁定（经审通过）+ 4 项遗留（key 详情已裁决：实现期定） | 定稿（2026-10-02） |
|
||||
| [`docs/design/API契约-成员视图.md`](docs/design/API契约-成员视图.md) | 成员视图 3 端点：令牌验证与页头、单页聚合（含支付参数卡判定）、日志明细（DTO 与管理面同构）；4 项裁定（经审通过）+ 1 项遗留 | 定稿（2026-10-02） |
|
||||
| [`docs/design/骨架搭建指南.md`](docs/design/骨架搭建指南.md) | monorepo 骨架 + 在线文档页的一次性执行指南（供作者或任一 AI 执行者）：前置、步骤、验收清单、红线、依据文档索引 | 草案（待审阅） |
|
||||
| [`docs/references/NewAPI-接口范围.md`](docs/references/NewAPI-接口范围.md) | 计费平台在 NewAPI 中可用的接口参考：鉴权档位、请求与返回结构、字段语义、实测行为、源码出处（**唯一上游参考**） | 事实依据 |
|
||||
|
||||
- 命名与分区：**目录用英文、文档名用中文**；`docs/design/`（我们定的方案与决策）· `docs/references/`（平台可用接口参考——实证事实，不做设计决策）
|
||||
|
||||
@@ -55,14 +55,14 @@
|
||||
|
||||
- `key_hash`（HMAC-SHA256，不可逆）：只服务「命中判定」——没有它，每次查询都要把全部 key 送去上游验证
|
||||
- `key_ciphertext`（AES-256-GCM，可解密）：唯一用途是调上游
|
||||
- 密钥 `KEYS_MASTER_KEY` 经 env 注入（HKDF 派生 hmac / aes 子密钥）；**密钥丢失 = 全部 key 需重新登记**（记入部署文档）
|
||||
- 密钥 `SK_KEY_ENCRYPTION_SECRET` 经 env 注入（HKDF 派生 hmac / aes 子密钥）；**密钥丢失 = 全部 key 需重新登记**（记入部署文档）
|
||||
|
||||
> **注解：为什么是两个字段（给非密码学背景的读者）**
|
||||
>
|
||||
> 两列各管一件事——`key_hash` 管「找得到」，`key_ciphertext` 管「用得起来」：
|
||||
>
|
||||
> - `key_hash` 像**单向粉碎机**：同样的输入永远产出同样的指纹，指纹却反推不出原文。输入 key 时（登记或查询），服务端算出的指纹与库中比对，命中即「已登记」，零上游调用；即便整库泄露，外人拿到的也只是指纹。选用 HMAC（而非裸哈希）是多掺一味只有服务器持有的「调料」：没有它，就无法用「猜测输入 → 对照指纹」的方式离线验证。
|
||||
> - `key_ciphertext` 像**保险箱**：用 `KEYS_MASTER_KEY` 加密锁存，轮询调上游时开锁取明文；AES-GCM 自带防篡改，密文被动过则解密直接报错。
|
||||
> - `key_ciphertext` 像**保险箱**：用 `SK_KEY_ENCRYPTION_SECRET` 加密锁存，轮询调上游时开锁取明文；AES-GCM 自带防篡改，密文被动过则解密直接报错。
|
||||
> - **两列并存的原因**：加密每次都掺随机数（同一 key 两次密文不同）→ 密文不能用于查找；哈希不可逆 → 指纹还原不出明文。「可查找」与「可还原」两个需求互斥，只能分存两份形态。
|
||||
> - **防线边界**：能同时接触数据库与环境变量的人（服务器运营方）防不住——这是已接受的信任模型前提；本设计防的是「数据库单独落到第三方手里」的常见拖库场景（SQL 注入、备份泄露）。
|
||||
> - 实现提示：两种算法均为标准件，Bun 内置 `crypto` 直接提供，无需第三方库。
|
||||
|
||||
+1
-1
@@ -79,7 +79,7 @@
|
||||
| 2 | D1 限制 | 单库 **500 MB / 10 GB**；每 Worker 调用查询数 **50 / 1000**；单条 SQL ≤ 100 KB、绑定参数 ≤ 100/语句；库为单线程（写入串行）——本项目低频批量写入无碍 |
|
||||
| 3 | Workers 运行时 | CPU：**10 ms**（网络等待不计）/ 30 s（<1h 间隔 cron；≥1h 为 15 min）；外网子请求 **50 / 1000** 每调用；出站并发 6；Cron Triggers 每账号 5 / 250 |
|
||||
| 4 | 免费额度 | Workers Free：10 万请求/天；D1 Free：读 500 万行/天、写 **10 万行/天**、存储 5 GB；**静态资产请求免费无限**（前端托管零成本） |
|
||||
| 5 | 加密体系 | Workers 完整实现 Web Crypto：**HKDF ✓ / AES-256-GCM ✓ / HMAC-SHA256 ✓**（原生加速）——`KEYS_MASTER_KEY` 体系可平移 |
|
||||
| 5 | 加密体系 | Workers 完整实现 Web Crypto：**HKDF ✓ / AES-256-GCM ✓ / HMAC-SHA256 ✓**（原生加速）——`SK_KEY_ENCRYPTION_SECRET` 体系可平移 |
|
||||
|
||||
**负载画像对照**（key 数按 10–25 估）：
|
||||
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
# 骨架搭建指南
|
||||
|
||||
> 一次性执行文档：monorepo 骨架 + 在线文档页的搭建步骤，供作者本人或任一 AI 执行者照做。**执行前先读 `README.md` 与 `AGENTS.md`（协作约定——尤其 git push 禁令与提交规则）**；本指南只定步骤、验收与红线，**字段与语义的权威在各定稿文档**（§6 索引）——动手前先读对应文档，不要凭本指南或记忆复述实现。执行完毕本指南状态翻「已实现」。
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 状态 | 草案（待作者审阅） |
|
||||
| 关联 | 《技术选型》《API契约-公共约定》《API契约-管理面》《API契约-成员视图》（均定稿）· 七篇表字段设计（定稿）· 八篇交互设计（定稿）· `docs/references/NewAPI-接口范围.md`（上游接口实证） |
|
||||
| 产出 | 可运行的 monorepo 骨架 · Scalar 在线文档页 · 首批端点 · 通过的测试与验收清单 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 前置条件
|
||||
|
||||
- **Bun ≥ 1.2**——本机已装 **1.4.2**（mise 全局安装，声明于 `C:\Users\YYY\.config\mise\config.toml`，可执行文件 `C:\Users\YYY\AppData\Local\mise\installs\bun\1.4.2\bin\bun.exe`）。**⚠️ 验证须在作者的 PowerShell 7 里执行**：mise 的 shim 由 pwsh 的 profile 激活，在 Windows PowerShell 5.1 里 `bun` 会报 command not found（那是 shell 差异，不是没装）——执行者若用 5.1，请改用 `pwsh -c "bun -v"` 或上述绝对路径
|
||||
- **Docker**（开发期跑 PostgreSQL 容器）——本机 29.6.2 已装
|
||||
- **git**：`design` 分支（实现代码落点裁决：文档与代码同分支演进）；**push 永远由作者手工**
|
||||
|
||||
## 2. 目标结构（《技术选型》§4）
|
||||
|
||||
```text
|
||||
（仓库根 · design 分支）
|
||||
├─ apps/
|
||||
│ ├─ server/ # 母体后端：Hono serve 装配 · Drizzle/pg · 进程内调度 · 环境变量与密钥注入
|
||||
│ └─ web/ # 前端：Vue 3 + antdv-next + Vite
|
||||
├─ packages/
|
||||
│ ├─ core/ # 业务核心：zod schema 与 DTO 类型 · 轮询与 request_id 去重 · 折算链 · 加密体系 · API 语义
|
||||
│ └─ db/ # 数据访问层：Drizzle schema（pg 方言）+ 仓储实现
|
||||
```
|
||||
|
||||
依赖方向单向：`apps/*` → `packages/db` → `packages/core`；web 对 core 仅纯类型依赖。
|
||||
|
||||
## 3. 步骤（按序）
|
||||
|
||||
1. **根骨架**：`package.json`（`workspaces: ["apps/*", "packages/*"]`）+ 根 `tsconfig`（strict；模块解析与路径按 Bun 惯例）+ `.gitignore` 增补（`node_modules` / `dist` / `.env`）
|
||||
2. **apps/web 第一步做 §3.7 能力 spike**（《技术选型》§7 风险表既定：实现期第一步）：Vite + Vue 3 + **antdv-next**，按《交互设计-总览与共性》§3.7 清单逐项搭小样——可折叠侧边栏 / 抽屉、密集表格（**展开行**、行内编辑、横向滚动）、对话框 + 二次确认、message / Alert、**DatePicker 范围选择**、大号粘贴输入框、徽章 / Segmented / Skeleton / Pagination；**任一项不覆盖即触发回退**（Element Plus / ant-design-vue）并回报作者再继续；**锁版本**（antdv-next 周更，用精确版本）
|
||||
3. **packages/core**：zod schema + DTO 类型——字段权威 = 契约三篇（`LogItem`、错误信封、各端点请求 / 响应 schema）；加密体系（`SK_KEY_ENCRYPTION_SECRET` 经 HKDF 派生 hmac / aes 子密钥——《api_keys表字段设计》3.1）与折算链（`qpuAt(t)`——《qpu_history表字段设计》3.3）先立接口与纯函数。**Bun 纪律红线**：只用 TS 标准库与 Web 标准 API（`fetch` / WebCrypto / `URL` / `TextEncoder` / `setTimeout`），禁止 `Bun.*` / `bun:*` / `node:*` / 数据库驱动
|
||||
4. **packages/db**：drizzle-orm `pg-core` schema——字段权威 = 七篇表设计（`api_keys` 16 列 / `usage_logs` 25 列 / `payments` 9 列 / `qpu_history` 3 列 / `members` 7 列 / `users` / `sessions`；索引与 `dedupe_key` 规则照表设计）；drizzle-kit 迁移；驱动 **postgres.js**（定案）。**方言红线**：pg 特有物（`jsonb` 等）不出本层
|
||||
5. **apps/server**：Hono（Bun 原生 serve）+ `@hono/zod-openapi` + **Scalar** 文档页（挂 `/api/docs`，开放只读）；两套凭证中间件照《API契约-公共约定》§2（会话 cookie `admin_session`：`HttpOnly + Secure + SameSite=Lax`，`Path=/api/admin`；成员 Bearer：`members.token_hash` 哈希比对 + `status` 检查）；`.env`：`DATABASE_URL`、`SK_KEY_ENCRYPTION_SECRET`、初始化凭证（示意 `ADMIN_INIT_USERNAME` / `ADMIN_INIT_PASSWORD`——空库双通道，users 表设计 3.1：空库 + env 在 → 静默落库）
|
||||
6. **开发用 compose**：只起 PostgreSQL 容器（server 本地跑）；部署形态（server 镜像化）归后续部署设计，不在本步骤
|
||||
7. **首批端点**（实现顺序）：`setup-state` / `setup` / `session` / `password`（三态与登录——《API契约-管理面》§2）→ `engine` 端点先立路由桩（状态存储归同步引擎设计，返回占位结构）→ `keys` 登记四态（上游验证：解密 `key_ciphertext` 调上游——上游行为实证见 `NewAPI-接口范围.md`）→ 其余按契约逐个
|
||||
8. **测试**：`bun test`——集成测试直打 Hono app；**契约有的端点必须有 handler、schema 必须对齐契约**（漂移钉住）；错误信封、401、409 附 `key_id`、三态、`type=2` 口径都要有用例
|
||||
9. **AGENTS.md 命令节登记**（作者常设授权「该改时就改」）：`bun install` / `bun test` / 开发启动命令
|
||||
|
||||
## 4. 验收清单（全部通过才算完成）
|
||||
|
||||
- [ ] `bun install` 与 `bun test` 通过
|
||||
- [ ] `/api/docs` 文档页可开、已实现端点可见、可试调
|
||||
- [ ] 空库三态：无 env 无行 → 引导态；env 在 → 静默落库；非空 → 登录态
|
||||
- [ ] 登录建会话（cookie 形态正确）；任意受保护端点无凭证 → `401` 错误信封
|
||||
- [ ] keys 登记：成功 `201` / hash 命中 `409`（附注 `key_id`）/ 上游拒绝 `422` / 上游不可达 `502`
|
||||
- [ ] 聚合与明细口径：聚合仅 `type=2`；明细 `token_name` 取当前名
|
||||
- [ ] 未知 `/api/*` → `404` 错误信封（JSON，非 HTML）
|
||||
- [ ] 红线自查：`packages/core` 无 `Bun.*` / `node:*` / 驱动 import；`sk-key` 明文与 `key_ciphertext` / `token_hash` 永不出现在任何响应
|
||||
- [ ] 每个管理面写操作落审计一行（action 枚举 =《API契约-管理面》§9）
|
||||
|
||||
## 5. 红线（违反即返工，出处见各定稿文档）
|
||||
|
||||
- **Bun 纪律与方言不外泄**（《技术选型》§5）；**业务错误一律非 2xx、成功无信封**（《API契约-公共约定》§3）；**snake_case 与表字段同构**（同文 §7）
|
||||
- 令牌明文仅签发响应出现一次；审计是不可变历史；提交避开 `api*.json`（未脱敏快照）与 `session-archive/`（会话原档，未跟踪、勿 ignore）
|
||||
|
||||
## 6. 依据文档索引（执行者动手前必读）
|
||||
|
||||
| 文档 | 权威范围 |
|
||||
|------|---------|
|
||||
| `docs/design/技术选型.md`（定稿） | 栈、monorepo 结构、Bun 纪律、回退 |
|
||||
| `docs/design/API契约-公共约定.md`（定稿） | 路由隔离、鉴权两档、错误信封、时间 / 数值 / 分页 / 命名 |
|
||||
| `docs/design/API契约-管理面.md` / `API契约-成员视图.md`（定稿） | 全部端点与请求 / 响应字段 |
|
||||
| `docs/design/*表字段设计.md` 七篇（定稿） | 全部表字段、索引、`dedupe_key`、写入时机 |
|
||||
| `docs/design/交互设计-*.md` 八篇（定稿） | 页面语义（web 实现时的信息结构与文案） |
|
||||
| `docs/references/NewAPI-接口范围.md` | 上游接口实证（登记验证、轮询数据源） |
|
||||
Reference in New Issue
Block a user