docs: 实施计划——离线开发与样例数据（§6），阶段 2/4 验收标准适配

- 新增 §6：样例数据（api*.json，未入库）的用途与开发策略——上游客户端接口化（真实 HTTP / 样例文件两实现）+ seed 脚本（阶段 4 落地）+ 真实链路待验清单
- 前提改为「以样例数据为主，真实 key 未开，不阻塞」
- 阶段 2 验收改为「注入样例实现」；阶段 4 增 seed 脚本与 401 状态机单测；阶段 6 用 seed 数据走查

docs/design/实施计划.md

@@ -35,12 +35,12 @@
 | 7 | 登记成功后立即异步跑一次该 key 的单轮同步（不等 tick） | 契约 §2.2 已定「立即异步补一轮」 |
 | 8 | 前端提交时间用 `toISOString()`（`Z` 形式） | 契约 约定 9 允许 |
 | 9 | drizzle-kit 的连库驱动用 `postgres`（postgres.js，纯 JS）——仅 CLI 需要；运行时仍走 Bun 内建 SQL（`drizzle-orm/bun-sql`） | devDependency，可换 `pg` |
+| 10 | 上游客户端以**接口 + 可注入实现**组织（真实 HTTP / 样例文件两种实现），引擎与路由依赖接口 | 见 §6；可改 |
 
 ## 2. 前提（2026-09-14 定）
 
 - **开发库**：Docker 本地 PostgreSQL（`docker-compose.yml` 已落地；连接串走 `.env`，不入库）——四张表已建
-- **上游联调**：真实 sk-key（作者已填 `.env`）——`NEWAPI_BASE` 实测可达：HTTP 200 / 5.2KB / 2.0s；`quota_per_unit = 500000`、`quota_display_type = USD`、`usd_exchange_rate = 6.8`，与文档一致
-- **联调用的测试 key**：作者新建专用测试 key（用完可删），并**用它发一次成功调用**（产生 `type=2` 日志）与**一次故意失败调用**（产生 `type=5` 日志）——阶段 4/5 的验证依赖这些日志
+- **联调策略**：**以样例数据为主**（见 §6）——作者未开测试 key；`NEWAPI_BASE` 可达性已验证（HTTP 200 / 5.2KB / 2.0s；`quota_per_unit = 500000`、`quota_display_type = USD`、`usd_exchange_rate = 6.8`，与文档一致）。真实登记 / 采集链路标「待作者补验」，**不阻塞**其他阶段
 - **提交**：loop 内直接提交已授权；push 由作者手工（仓库有两个远端）
 
 ## 3. 阶段与验收标准
@@ -49,11 +49,11 @@
 |------|------|---------|------|
 | 0 | 脚手架 + 契约类型 + 501 骨架 | 命令链全绿（type-check / test / build） | ✅ 2026-09-14 |
 | 1 | **数据层与密钥**：crypto（HKDF 派生 / HMAC-SHA256 / AES-256-GCM）· 时间工具（+08:00 序列化、UTC 秒转换）· 建表 | 单测：哈希确定性 + 加解密往返；`db:push` 后四张表在库 | ✅ 2026-09-14（15 项单测绿；四表在库——`api_keys` 17 列 / `usage_logs` 23 列 / 索引 8 个） |
-| 2 | **上游客户端 + key 管理**（`GET` / `POST` / `PATCH` 三端点） | curl 实测：登记 → 清单 → 停用/启用；三类错误码分支正确（`key_rejected` / `already_registered` / `upstream_unavailable`） | ☐ |
+| 2 | **上游客户端 + key 管理**（`GET` / `POST` / `PATCH` 三端点）· 客户端接口化（§6） | curl 实测：登记 → 清单 → 停用/启用（**注入样例实现**：登记成功路径用样例响应驱动）；三类错误码分支正确（`key_rejected` / `already_registered` / `upstream_unavailable`） | ☐ |
 | 3 | **管理面其余**：purchases 五端点 + qpu 一端点 | curl 实测：CRUD 全流程 + 观测聚合（`matched_purchase_id` 判定正确） | ☐ |
-| 4 | **同步引擎**：tick（5 分钟 + 防重入 + 启动即跑）· 日志整批事务入库 · 额度采集 · QPU 采样 · 401 状态机（N=3） | 库中出现真实数据；`[sync]` 日志符合引擎设计；连续 401 触发摘除且 `disabled_source = auto_401` | ☐ |
+| 4 | **同步引擎**：tick（5 分钟 + 防重入 + 启动即跑）· 日志整批事务入库 · 额度采集 · QPU 采样 · 401 状态机（N=3）· **seed 脚本**（§6） | 库中出现数据（seed 或真实采集）；`[sync]` 日志符合引擎设计；401 状态机单测（连续 401 → 摘除且 `disabled_source = auto_401`） | ☐ |
 | 5 | **查看面数据面**：`logs/query` + `summary` + 折算链（按购买期间分段取尺） | curl 实测：字段齐全、`meta.data_until` 取最慢、金额按购买分段累加；**无归属购买的行 `amount_rmb = null` 且计入 `unpriced_count`**（2026-09-14 定） | ☐ |
-| 6 | **前端 `/usage-log`**：筛选区（key 标签 + datetimerange + 快捷项）· 卡片 · 表格 + 展开行 · 分页器 · 六种状态模式 | 浏览器实测：真实数据走一遍；六态逐一可见（加载 / 初始 / 未收录 / 无记录 / 同步中 / 失败）；金额为 `null` 显示「—」 | ☐ |
+| 6 | **前端 `/usage-log`**：筛选区（key 标签 + datetimerange + 快捷项）· 卡片 · 表格 + 展开行 · 分页器 · 六种状态模式 | 浏览器实测：seed 数据走一遍；六态逐一可见（加载 / 初始 / 未收录 / 无记录 / 同步中 / 失败）；金额为 `null` 显示「—」 | ☐ |
 | 7 | **前端管理面**：口令门帘 + 侧边栏 + 三页（key 管理 / 购买记录含核对提示与补录 / 换算参数） | 浏览器实测：登记、启停、CRUD、补录、时间线全操作 | ☐ |
 | 8 | **收尾**：部署文档（`docs/delivery/`）· 端到端走查 · 文档状态更新（设计文档 → 已实现） | 一条命令链可部署（前后端独立 + 后端单实例注记）；走查无阻 | ☐ |
 
@@ -68,6 +68,22 @@
 
 ## 5. 风险
 
-- 真实上游联调依赖网络可达（已实测 200）；不可用时临时以假上游过渡（不改变验收口径）
+- 真实上游联调依赖网络可达（已实测 200）；真实 key 未开——以样例数据替代（§6），真实链路标「待作者补验」
 - 折算链（阶段 5）依赖已登记的购买记录——无记录时的行为已定（`null` + `unpriced_count`）
 - **后端必须单实例**（同步引擎前提）：部署文档（阶段 8）必须写明；本地开发也不要起两个后端
+
+## 6. 离线开发与样例数据（2026-09-14 定）
+
+**结论：不需要真实 key 也能跑完全部阶段。** 仓库根目录有三个**实测响应快照**——未入库（`.gitignore` 用 `/api*.json` 排除，**绝不提交**），供开发与验证使用：
+
+| 文件 | 内容 | 用途 |
+|------|------|------|
+| `api.log.token.json` | `/api/log/token` 的 1000 条响应快照（≈3.2 天、含 `type=2` 与 `type=5`） | 引擎解析 / 去重 / 入库的 fixture；**seed 数据源** |
+| `api.log.token.other.json` | 单条日志 `other` 字段样本（26 键：`subscription_*` 八件套、`cache_tokens`、倍率等） | 解析与展示字段核对 |
+| `api.status.json` | `/api/status` 响应（含 `quota_per_unit = 500000` / `quota_display_type = USD` / `usd_exchange_rate = 6.8`） | QPU 采样逻辑的 fixture |
+
+**开发策略**：
+
+1. **上游客户端接口化（假设 #10）**：定义接口（如 `UpstreamClient`：`fetchTokenUsage` / `fetchLogs` / `fetchStatus`），两套实现——真实 HTTP 实现 + **样例文件实现**（从上述 JSON 读响应）；引擎与路由依赖接口，联调时替换
+2. **seed 脚本**（阶段 4 落地，`apps/server/scripts/seed.ts`）：从样例灌入——一个占位 `api_keys` 行（**假 key 常量**，其哈希/密文走真实 crypto 逻辑，便于用固定测试 key 查询命中）+ 1000 条 `usage_logs` + `qpu_history` 基线 + 一条示例 `purchases`（用于验证折算链）——使阶段 5/6/7 的开发与验证有真实形状的数据
+3. **真实链路验证清单**（标「待作者补验」）：登记成功路径（真实 `/api/usage/token` 验证）、真实采集轮次、真实 401 摘除——不阻塞其他阶段，做完在报告中列出待验项