72 lines
7.5 KiB
Markdown
72 lines
7.5 KiB
Markdown
# 骨架搭建指南
|
||
|
||
> 一次性执行文档：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` | 上游接口实证（登记验证、轮询数据源） |
|