docs: 清理骨架搭建指南并校准 README 进度表述

README.md

@@ -6,7 +6,7 @@
 
 | 项目 | 内容 |
 |------|------|
-| 当前状态 | **实现启动阶段**（`design` 分支 = 文档中心 + 实现主线）——需求 / 数据模型 / 交互 / 技术选型 / API 契约全部定稿，余同步引擎设计（与实现并行），骨架 + 在线文档页动工 |
+| 当前状态 | **实现推进中**（`design` 分支 = 文档中心 + 实现主线）——设计文档全部定稿（含同步引擎）；后端全量落地（core / db / server / engine + Scalar 在线文档），同步引擎已人工验收；**前端仅有 antdv-next 能力 spike，真实页面待开工** |
 | 技术栈 | 全栈 TypeScript（选型定稿见 [`docs/design/技术选型.md`](docs/design/技术选型.md)）：母体 Bun + Hono + Drizzle + PostgreSQL · 前端 Vue 3 + antdv-next |
 
 ## 项目沿革
@@ -14,9 +14,9 @@
 | 阶段 | 形态 | 结局 |
 |------|------|------|
 | 初版方案 | Cloudflare Workers | 弃——当时运营方愿意提供服务器资源 |
-| 新版设计（当前） | **本分支，设计进行中** | 捡回 Cloudflare Workers（**serverless 后端**：Cron 定时轮询 + 云端数据库攒库，非初版原案复刻）与完整前后端方案并列评估；同时解决管理面鉴权、充值折算、多订阅等设计问题 |
+| 新版设计（当前） | **本分支，设计已收官、实现推进中** | 捡回 Cloudflare Workers（**serverless 后端**：Cron 定时轮询 + 云端数据库攒库，非初版原案复刻）作为后续衍生形态；母体完整前后端先行，CFW 延后至功能全集实现后 |
 
-**当前设计阶段的直接动因**：服务器部署形态下，每次迭代都需实例运营方在服务器上手工升级，测试阶段迭代频繁而运营方无暇跟随；若部署到作者自控的 Cloudflare 账号（Workers + Pages），迭代部署权回到作者手里。
+**双形态并行的直接动因**：服务器部署形态下，每次迭代都需实例运营方在服务器上手工升级，测试阶段迭代频繁而运营方无暇跟随；若部署到作者自控的 Cloudflare 账号（Workers + Pages），迭代部署权回到作者手里。
 
 ## 文档地图
 
@@ -42,8 +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/design/同步引擎设计.md`](docs/design/同步引擎设计.md) | 独立 `apps/engine` 进程：手写 `setTimeout` 轮次、失败只记录、`engine_status` 快照供 `/api/admin/engine`；周期可配、**不为 CFW 预留** | 定稿（2026-10-05） |
+| [`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/`（平台可用接口参考——实证事实，不做设计决策）
@@ -62,7 +61,7 @@
   - 一切数据获取只能走 key 级接口（账号级接口用 sk-key 访问会 401）
   - 部署形态已裁决为**双形态并行**：完整前后端部署在实例运营方提供的服务器上（作者不接触服务器）+ Cloudflare Workers 抽取版部署在作者自控账号（见 [`docs/design/需求清单.md`](docs/design/需求清单.md) R13）
 
-## 核心需求（基线草案，待复审；完整范围见需求清单）
+## 核心需求（基线摘要；完整范围见需求清单）
 
 | # | 需求 | 说明 |
 |---|------|------|

docs/design/骨架搭建指南.md

@@ -1,71 +0,0 @@
-# 骨架搭建指南
-
-> 一次性执行文档：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` | 上游接口实证（登记验证、轮询数据源） |