7.5 KiB
7.5 KiB
骨架搭建指南
一次性执行文档：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）
（仓库根 · 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. 步骤（按序）
- 根骨架：
package.json（workspaces: ["apps/*", "packages/*"]）+ 根tsconfig（strict；模块解析与路径按 Bun 惯例）+.gitignore增补（node_modules/dist/.env） - 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 周更，用精确版本）
- 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:*/ 数据库驱动 - packages/db：drizzle-orm
pg-coreschema——字段权威 = 七篇表设计（api_keys16 列 /usage_logs25 列 /payments9 列 /qpu_history3 列 /members7 列 /users/sessions；索引与dedupe_key规则照表设计）；drizzle-kit 迁移；驱动 postgres.js（定案）。方言红线：pg 特有物（jsonb等）不出本层 - apps/server：Hono（Bun 原生 serve）+
@hono/zod-openapi+ Scalar 文档页（挂/api/docs，开放只读）；两套凭证中间件照《API契约-公共约定》§2（会话 cookieadmin_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 在 → 静默落库） - 开发用 compose：只起 PostgreSQL 容器（server 本地跑）；部署形态（server 镜像化）归后续部署设计，不在本步骤
- 首批端点（实现顺序）：
setup-state/setup/session/password（三态与登录——《API契约-管理面》§2）→engine端点先立路由桩（状态存储归同步引擎设计，返回占位结构）→keys登记四态（上游验证：解密key_ciphertext调上游——上游行为实证见NewAPI-接口范围.md）→ 其余按契约逐个 - 测试：
bun test——集成测试直打 Hono app；契约有的端点必须有 handler、schema 必须对齐契约（漂移钉住）；错误信封、401、409 附key_id、三态、type=2口径都要有用例 - 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 |
上游接口实证（登记验证、轮询数据源） |