payment-kit 1.27.2 → 1.28.0

package/cloudflare/docs/2026-04-22-sdk-1.30.9-upgrade-retro.md

@@ -0,0 +1,324 @@
+# SDK 1.26.3 → 1.30.9 升级完整回顾
+
+**时间**：2026-04-20 ~ 2026-04-22
+**涉及仓库**：`payment-kit` + `abt-wallet`
+**主要目标**：升级 `@arcblock/*` / `@ocap/*` 到 1.30.9，并在可行时切到 CBOR 编码
+
+---
+
+## 目录
+
+1. [升级目标与产出](#一升级目标与产出)
+2. [遇到的坑（按层级分类）](#二遇到的坑按层级分类)
+3. [每个问题的成因与解决](#三每个问题的成因与解决)
+4. [如果重新做一次：完整 Checklist](#四如果重新做一次完整-checklist)
+5. [尚未解决的事项](#五尚未解决的事项)
+
+---
+
+## 一、升级目标与产出
+
+### 起点
+- `@ocap/*`、`@arcblock/*` 在 1.26.3 系列（protobuf 原生，无 CBOR）
+- payment-kit 已迁移到 Cloudflare Workers 但 SDK 未升
+- abt-wallet 仍使用 1.26.3 SDK
+
+### 1.30.9 带来的主要变化
+| 变化 | 意义 | 对消费者影响 |
+|---|---|---|
+| `@ocap/client` 默认 → CBOR | wire 格式切换 | 必须改用 `/legacy` subpath 或接受 CBOR |
+| `@arcblock/did-util` 拆 `/cbor` `/protobuf` 两个 subpath | 按需引入，减小 bundle | 要手动选对子路径才省体积 |
+| `@ocap/asset/mint/client` 加入 CBOR-only 版本 | 同上 | 同上 |
+| `@scure/bip32` 替换 `@wangshijun/hdkey` | 移除 elliptic 依赖链 | **seed 严格 16-64 字节**（break change）|
+| `@noble/curves` v2 替换 elliptic | 安全审计 + bundle -45% | API 可能不同 |
+| Joi → Valibot schema 校验 | 更快、更小 | 某些 key-order 敏感路径要改 |
+| `@ocap/asset/mint/server`、`@arcblock/did-util` 顶层入口 | 需要显式 `encoding` 参数 | 旧代码会 break |
+| itx address derivation 跟 `client.txEncoding` 对齐 | 修复编码不一致 bug | 纯 UPSIDE |
+
+### 最终产出
+- `payment-kit/feat/cf-workers-migration`（legacy 分支）：1.30.9 + `/legacy` wire 格式 + Node 后端 pnpm override pin 到 1.29.27
+- `payment-kit/feat/cbor-migration-pk`（CBOR 分支）：1.30.9 + CBOR wire 格式，bundle 2.76 MB / gzip 819 KiB（比 legacy -21% raw / -11% gzip，google-protobuf 完全清除）
+- `abt-wallet/upgrade-sdk-to-1.30.9-dual-decode`：4.19.x + dual-decode 能力（WIP）
+- 两个 smoke test 脚本沉淀：`tools/sdk-v3-smoke.ts`、`tools/l2-wallet-chain-smoke.ts`
+
+---
+
+## 二、遇到的坑（按层级分类）
+
+### A. 依赖管理层（6 个）
+
+| # | 问题 | 难度 | 首次触发时间 |
+|---|---|---|---|
+| A1 | pnpm 不认 `resolutions` 字段（yarn-only），顶层 1.30.9 强制无效 | 高 | Phase A 后期 |
+| A2 | `@blocklet/sdk@1.17.11` 内嵌 `@arcblock/did-connect-js@1.29.8`，pnpm 扁平化后它 `require('@ocap/client')` 命中顶层 1.30.9，**Node 后端悄无声息切到 CBOR** | **极高** | 用户主动追问发现 |
+| A3 | `@arcblock/did-connect-js` 发布版本最高仅到 1.30.1，无法对齐 1.30.9 | 中 | Phase A 规划 |
+| A4 | `@wangshijun/hdkey` → `@scure/bip32` 严格 seed 长度，旧钱包 `fromAppDid('')` 炸 `seed length must be between 128 and 512 bits; got 152` | 高 | abt-wallet 编译后首次登录 |
+| A5 | 同一 npm 树下两个 webpack 副本（react-scripts 5.76.2 vs top-level 5.106.2），plugin 实例跨版本 `.tap()` 失败 | 极高 | 钱包 build |
+| A6 | nested packages 的 @ocap/client 无法通过 resolution 强制 pin，需 `pnpm.overrides` 的 `>` 语法显式隔离 | 高 | A2 的解决过程中 |
+
+### B. webpack / bundler 打包层（5 个）
+
+| # | 问题 | 难度 |
+|---|---|---|
+| B1 | `@ocap/message/esm/patch.mjs` 的 Rolldown `__require(createRequire(import.meta.url))` 在浏览器得到 noop，炸 "Cannot read properties of undefined (reading 'Map')" | 极高 |
+| B2 | CRA 5 `ModuleScopePlugin` 阻止所有 alias 指向 `src/` 之外的文件 | 高 |
+| B3 | CRA webpack 规则里 `oneOf` 的 file-loader fallback 把 `.cjs` 当静态资源，`require('@ocap/mcrypto')` 返回 URL 字符串而不是模块 → `mcrypto.Hasher === undefined` | **极高** |
+| B4 | webpack ESM↔CJS interop：CJS consumer `require('@ocap/mcrypto')` 经 ESM 路径加载时，命名导出 `.Hasher` 在某些场景下丢失 | 高 |
+| B5 | CRA 默认不编译 `.cjs` 文件（babel-loader test 仅 `/\.(m?js|tsx?)$/`），需显式加 rule | 中 |
+
+### C. SDK 运行时层（4 个）
+
+| # | 问题 | 难度 |
+|---|---|---|
+| C1 | `@ocap/client` 默认 entry 即使在 CBOR 模式下，仍静态引入 `@ocap/proto/gen/*_pb.js`（1.2 MB protobuf schema），bundle 未按 commit message 宣传那样瘦身 | 高 |
+| C2 | `@ocap/client/encode` 的 JSDoc 写 "protobuf 二进制" 但实际代码 `require('@ocap/message/cbor')` 输出 CBOR，文档与实现不符 | 中 |
+| C3 | `@arcblock/did-util` 顶层入口会无条件拉进 `protobuf.mjs` → `@ocap/proto/runtime`，即使消费者只用到 `toStakeAddress` 等通用工具 | 高 |
+| C4 | `@ocap/asset` 顶层入口同理会拉 `mint/server.mjs`（dual-encoding）→ 再拉 `@arcblock/did-util` 顶层 | 高 |
+
+### D. 应用代码层（4 个）
+
+| # | 问题 | 难度 |
+|---|---|---|
+| D1 | `@ocap/client/legacy` wire 格式下 tx bytes 是 protobuf，CBOR 钱包无法解；反之 CBOR bytes 也被 legacy 钱包拒 → `INVALID_CHECK: Unmatched end-group tag` | 中（理解后）|
+| D2 | 1.30.9 `toTokenAddress(payload)` 等函数签名加 `encoding` 参数为必填，不传报 `Expected 2 arguments, but got 1` | 中 |
+| D3 | 1.30.9 `preMintFromFactory({...})` 要求 `encoding` 字段，原来的调用处不传会 type check 失败 | 中 |
+| D4 | payment-kit 多个业务文件用顶层 `@arcblock/did-util` / `@ocap/asset`，变相带进整条 protobuf 链 | 中（追踪到之后）|
+
+### E. 体验层（非 bug 但影响调试）（3 个）
+
+| # | 问题 |
+|---|---|
+| E1 | payment-kit 服务端的 `INVALID_CHECK` / `INSUFFICIENT_FUND` 错误未结构化透传给钱包，钱包仅看到 "jwt response empty or invalid"，完全丢失诊断信息 |
+| E2 | `new Error('INVALID_CHECK', 'actual reason')` —— 第二参数被静默丢弃，钱包日志只剩错误码 |
+| E3 | wrangler dev 热重载有时对 ESM `import path` 大改动不敏感，需重启才生效 |
+
+---
+
+## 三、典型问题深度分析
+
+> 二节共记录 22 个问题；本节挑其中**耗时最长、最具代表性的 7 个**做深度解析，其余在"解决"栏里用一行概述。
+
+### A1: pnpm 不认 `resolutions`
+
+**成因**：pnpm 只识别 `pnpm.overrides`，顶层 package.json 的 `resolutions` 是 yarn 字段。
+**症状**：所有"强制 1.30.9"的意图全部无效，nested 依赖照样装旧版本。
+**解决**：把需要的 override 迁到 `pnpm.overrides`，支持 `A>B` 语法定点覆盖。
+**代码位置**：`payment-kit/package.json`
+
+### A2: @blocklet/sdk 嵌套 did-connect-js 偷偷用 CBOR
+
+**成因**：
+```
+@blocklet/sdk@1.17.11
+  └── node_modules/@arcblock/did-connect-js@1.29.8 (pinned, 不是 ^)
+        └── require('@ocap/client')   # pnpm 扁平化后命中顶层 1.30.9 (CBOR!)
+```
+**症状**：Node 后端 `blocklet dev` 悄悄发 CBOR 字节，与 master 钱包的 protobuf 解码器不兼容。**此 bug 在我们以为"Node 侧跟 CF 不一样"时隐藏了数小时**。
+**解决**：
+```json
+"pnpm": {
+  "overrides": {
+    "@arcblock/did-connect-js>@ocap/client": "1.29.27"
+  }
+}
+```
+pnpm 装了一份 1.29.27 在 `@blocklet/sdk/node_modules/@ocap/client`，Node resolution 向上查找时命中。顶层和 CF Workers 的 1.30.9 完全不受影响。
+
+### A4: @scure/bip32 seed 长度
+
+**成因**：旧 `@wangshijun/hdkey` 宽容地接受任意长度 seed；`@scure/bip32` 严格 16-64 字节。wallet 的 `fromAppDid('', root.base64Seed, ...)` 里 `base64Seed` 是 base64 编码的字符串，直接当 bytes 传会得到 152 字节。
+**症状**：`HDKey: seed length must be between 128 and 512 bits; got 152`
+**解决**：
+```js
+const seedLike = (root?.base64Seed || '').slice(0, 64);
+const newDID = fromAppDid('', seedLike, DID_TYPE_ARCBLOCK, 0);
+```
+**副作用 ⚠️**：现有用户的 wallet DID **会变**（seed 换算路径不同）。升级前必须评估用户数据迁移。
+
+### A5: Dual webpack
+
+**成因**：
+- `react-scripts` 内 `node_modules/webpack@5.76.2`
+- `node_modules/webpack@5.106.2`（被某个 dev dep 引入）
+
+`config-overrides.js` 的 `require('webpack')` 命中 5.106，但 compiler 创建用 5.76。`IgnorePlugin` 实例在 apply 时调用 `compiler.hooks.normalModuleFactory.beforeResolve.tap(...)` 这个 hook 在两个版本间 shape 不同。
+**症状**：`Cannot read properties of undefined (reading 'tap')`
+**解决**：
+```js
+const webpack = require('react-scripts/node_modules/webpack');
+```
+显式锁到 react-scripts 自带的 webpack。
+
+### B1: Rolldown __require shim
+
+**成因**：1.30.x 部分 `@ocap/*` 包用 Rolldown 打包，其 ESM runtime 里 `__require = createRequire(import.meta.url)` 在 Node 里 OK，在 webpack 浏览器 bundle 里 createRequire 被 stub 成 noop。
+**症状**：`@ocap/message/esm/patch.mjs` 模块 init 时 `__require('google-protobuf').Map` 炸。
+**解决**：`mocks/rolldown-runtime-shim.js` + `webpack.NormalModuleReplacementPlugin` 按正则替换 `_virtual/rolldown_runtime.mjs`：
+```js
+const __require = (id) => {
+  const loader = __requireModuleMap[id];
+  if (!loader) throw new Error(...);
+  return loader();
+};
+```
+静态 switch 因为 webpack 只能 bundle 它能静态分析的模块。
+
+### B3 + B5: `.cjs` 当静态资源
+
+**成因**：
+1. CRA 的 `oneOf` 最后一条是 file-loader fallback，match 所有未识别扩展名（包括 `.cjs`）。
+2. babel-loader 的 test 是 `/\.(m?js|tsx?)$/`，**不含 `.cjs`**。
+3. 结果 `.cjs` 文件被当作静态资源，`require('.../index.cjs')` 返回 URL 字符串。
+
+**症状**：`mcrypto_1.Hasher === undefined`（因为 mcrypto_1 其实是一个路径字符串）。
+
+**解决**：webpack rule 注入到 `oneOf` 顶部：
+```js
+for (const rule of config.module.rules) {
+  if (Array.isArray(rule.oneOf)) {
+    rule.oneOf.unshift({
+      test: /[\\/]node_modules[\\/]@ocap[\\/].*\.cjs$/,
+      type: 'javascript/auto',
+    });
+    break;
+  }
+}
+```
+**关键点**：scope **只限 `@ocap/*`**，否则会把 axon 等 Node-only CJS 也拉进来，触发 `Can't resolve 'net'`。
+
+### C1 + D4: Bundle 没瘦身的真相
+
+**Phase 2 commit message 宣称 "drops ~300KB google-protobuf"**，实测 `cfa2fb51` 只改了两个点，protobuf 还在 bundle 里，**实际只省了 5 KiB gzip**。
+
+**根因追踪（耗时最长的 bug）**：payment-kit 业务代码 6 处从顶层入口 import：
+```
+api/src/libs/util.ts              → import { toStakeAddress } from '@arcblock/did-util'
+api/src/libs/wallet-migration.ts  → import { toDelegateAddress, toStakeAddress }
+api/src/integrations/arcblock/stake.ts
+api/src/integrations/arcblock/token.ts
+api/src/routes/connect/shared.ts
+api/src/integrations/arcblock/nft.ts  → '@ocap/asset'（非 mint/client）
+```
+
+`@arcblock/did-util` 顶层无条件 `import './protobuf.mjs'` → `@ocap/proto/lib/runtime.js` → 拖入 1.2 MB `*_pb.js` + 246 KB google-protobuf。
+
+**解决**：改 6 个 import 到 `/cbor` / `/mint/client` 子路径。
+**收益**：raw -735 KB (-21%)、gzip -103 KiB (-11%)。
+
+**本质教训**：**CBOR 不自动瘦身 bundle**。切 wire 格式只是第一步，业务代码必须主动用 CBOR-only 子路径才能真省。
+
+---
+
+## 四、如果重新做一次：完整 Checklist
+
+### Phase 0：前置调研（1-2 天）
+
+- [ ] **读一遍 upstream CHANGELOG**，特别关注：
+  - 签名 / 接口变化（`encoding` 参数是否必填？）
+  - 依赖链路变化（`@wangshijun/hdkey` → `@scure/bip32` 这类替换）
+  - 新 subpath 是否已经存在（`/cbor`、`/mint/client`）
+- [ ] **画出完整依赖树**：`pnpm why @ocap/client`，找所有嵌套版本。标记谁 pin 了哪个。
+- [ ] **确认包管理器**：pnpm 还是 yarn？这决定 override 语法。
+- [ ] **列举自己业务代码对顶层 import 的使用**：`grep -rn "from '@arcblock/did-util'" src/`、`from '@ocap/asset'`、`from '@ocap/client'`。这些都是潜在的 "顶层 aggregate entry → 肥胖" 点。
+- [ ] **准备"legacy 中间态"作为回退点**：切 wire 格式前，先让 SDK 升级在 legacy/protobuf 下稳定。
+
+### Phase 1：SDK 升级（1-2 天）
+
+- [ ] bump `package.json`，`pnpm install`
+- [ ] **如果有 pnpm + 嵌套依赖**：先跑 `pnpm why @ocap/client | @ocap/message` 看扁平化后的版本，可能需要 `pnpm.overrides` 定点隔离
+- [ ] **写 L1 smoke 脚本**（Node 不经 bundler 直接测 SDK），验证：
+  - 新 SDK 的 `encode*Tx` / `sign*Tx` / `multiSign*Tx` 全部注册
+  - 常见 tx 类型（V2、V3、rollup）编码/解码 roundtrip 成功
+- [ ] **写 L2 smoke 脚本**（mirror 业务代码调用模式），避免先 build bundle 才发现 SDK 用法变了
+- [ ] 对付 build-time 问题：
+  - [ ] Rolldown shim（如果包用 Rolldown ESM）
+  - [ ] `.cjs` 加入 JS 解析 rule
+  - [ ] webpack 版本对齐（dual webpack 时锁到 react-scripts 自带版本）
+  - [ ] CRA ModuleScopePlugin 视情况 remove
+- [ ] 对付 breaking changes：
+  - [ ] 搜所有 `fromAppDid` / `fromMasterSeed` 用法，检查 seed 长度
+  - [ ] 搜所有 `toXxxAddress(payload)` / `preMintFromFactory({...})`，加 `encoding` 参数
+  - [ ] 搜所有 Joi schema，确认 Valibot key-order 敏感点
+
+### Phase 2：legacy 中间态（半天）
+
+- [ ] 把所有 `@ocap/client` 改 `@ocap/client/legacy`，继续 protobuf wire
+- [ ] **部署 legacy 1.30.9 到 staging**，先让它跑通跟 master 钱包的 E2E
+- [ ] 这个中间态作为"SDK 升级独立变量"的验证点：如果这一步不通，回退容易
+
+### Phase 3：CBOR 迁移（1-2 天，独立分支）
+
+- [ ] 新分支
+- [ ] `@ocap/client/legacy` → `@ocap/client` 默认
+- [ ] did-connect-auth 的 txEncoder 换 `@ocap/client/encode` 的 `createTxEncoder`
+- [ ] **pre-warm `fetchContext(chainHost)`** 在 `initAuth` 时调一次，避免首次请求 8s timeout
+- [ ] **搜索所有 `@arcblock/did-util` 顶层 import，改 `/cbor`**（这一步是 bundle 瘦身的真正来源）
+- [ ] **同理 `@ocap/asset` → `/mint/client`**
+- [ ] 对应的 tsconfig `paths` 可能要加 `.d.mts` 映射（看 moduleResolution）
+- [ ] Wallet 端必须有 dual-decode 能力（检查 CBOR tag `0xd9d9f7`，按需选 CBOR/protobuf 解码器）
+
+### Phase 4：验证
+
+- [ ] **bundle 体积实测**：用 esbuild meta.json 看 top 包，**不要信 commit message**
+- [ ] **Node 后端单独测**：`blocklet dev` 能起来、pre-start tsc 过、能跟 master 钱包通
+- [ ] **CF Workers 单独测**：`wrangler dev` 起来，扫 QR 能走通支付流
+- [ ] **扫 QR 测实际支付**：要一笔真的上链 tx hash 作为"迁移成功"证据
+- [ ] **错误路径也测**：用 balance 不足的钱包扫，看错误是否合理透传（当前 payment-kit 有 error-surface bug）
+
+### Phase 5：收尾
+
+- [ ] 两个分支都 push 到 origin，作为"legacy 回退线"和"CBOR 前进线"并存
+- [ ] 旧的诊断脚本（sdk-v3-smoke、l2-wallet-chain-smoke）归档到 `tools/`，下次升级复用
+- [ ] 写这份回顾文档（or update 本文档），记录坑和学到的东西
+
+---
+
+## 五、尚未解决的事项
+
+| 项目 | 状态 | 影响 |
+|---|---|---|
+| **abt-wallet V3 multi-sign "o is not a function"** | 未定位 | 浏览器扩展里 V3 多签走不通，原因可能是 webpack tree-shake 或 Rolldown shim 未覆盖。L1 smoke 证明不是 SDK bug |
+| **payment-kit 错误透传** | CBOR 分支已部分修复（commit `715ff9ae`：structured chain error parsing）；legacy 分支待合入 | 链拒 tx 时服务端返回破损 JWT，钱包只看到 "jwt empty" |
+| **`new Error('CODE', 'reason')` 参数丢失** | 已知 bug | 钱包十余处 throw 点丢 reason，调试困难 |
+| **钱包跨账户智能调度** | 产品 roadmap | 余额不够时应提示内部转账，而非 hard error |
+| **`.mts` type 解析（CBOR 分支）** | tsconfig 未更新 | `blocklet dev` 的 pre-start tsc 报 6 处 "Cannot find module"，不影响 esbuild |
+| **wallet DID 因 seed slice(0,64) 改变** | 未测 | 1.26.3 → 1.30.9 升级后，老用户的 wallet DID 可能变。**生产升级前必须做数据迁移评估** |
+| **官方 @blocklet/sdk 升级到 1.30.x** | 等上游 | 现在用 pnpm override 定点 pin 1.29.27，等 SDK 官方发布 1.18.x 对齐 1.30.9 再彻底解决 |
+
+---
+
+## 附录：关键 commit 索引
+
+### payment-kit
+```
+feat/cf-workers-migration (legacy 主线)
+  e5cb9fdb  test(tools): SDK + wallet-chain smoke scripts
+  e09e404b  fix(deps): pin did-connect-js's @ocap/client to 1.29.27
+  e89b73a9  fix(api): close TS type gaps after 1.30.9
+  f3aef135  fix(cloudflare): enable CORS on /__blocklet__.js
+  54c98f71  fix(cloudflare): adapt payment to 1.30.9 wallet compat
+  b6d8837a  chore(deps): bump @arcblock/@ocap SDK to ^1.30.9
+
+feat/cbor-migration-pk (CBOR 线)
+  715ff9ae  feat(api): structured chain error parsing for payment flow  ← 部分修 E1
+  93028445  fix(api): annotate implicit-any params in payment.ts
+  6727a62a  perf(cloudflare): drop google-protobuf from bundle (-720KB)
+  2c6d2ddd  fix(cloudflare): pre-warm chain context cache at initAuth
+  cfa2fb51  feat(cloudflare): Phase 2 — CBOR default
+```
+
+### abt-wallet
+```
+feat/cbor-migration-design (早期激进尝试，含审计文档)
+  11953f9f  docs(audit): honest Phase 1 change review
+  9ceaf3a8  chore(release): 4.20.0 — dual-mode CBOR migration
+  57668a5a  fix(wallet-did): slice encrypted seed to 64 bytes  ← 关键修复
+
+feat/sdk-upgrade-1.30-legacy (我的 Phase A 尝试)
+  73eb0a2e  fix(build): force @ocap/mcrypto to CJS entry
+  c33ef404  fix(build): pin webpack in config-overrides
+  36c9401b  fix(chain): pin @ocap/client imports to /legacy
+
+upgrade-sdk-to-1.30.9-dual-decode (用户自建的 WIP 分支)
+  667d6d49  WIP: Stage 1 upgrade SDK 1.26.3 -> 1.30.9 (legacy only)
+```

package/cloudflare/docs/2026-04-24-queue-ops-followup.md

@@ -0,0 +1,218 @@
+# CF Queues 免费额度连续触顶 — 2026-04-24 现状更新与部署记录
+
+| 字段 | 值 |
+|---|---|
+| 状态 | 🔴 每日 10k 免费额度连续 14 天被打穿；Plan 8 + Plan 13 已部署，效果待验证 |
+| 触发事件 | 2026-04-23 23:58 UTC CF 邮件："You have reached the daily Cloudflare Queues free tier limit of 10000 operations. Attempts to send a message to a queue will fail until the limit resets at 2026-04-25 at 00:00:00 UTC." |
+| 受影响环境 | ArcBlock 主账号 `983482dc52a0aee5dbd7f986840a6190` / `staging-aigne-hub-payment-kit` |
+| 本文定位 | **更正并替代** `cf-queues-ops-alert-analysis.md` 与 `payment-kit-platform-analysis-2026-04-20.md` 中与现状冲突的预期值和承诺阈值。原文档保留以备历史溯源，勘误对照详见 §5。|
+
+---
+
+## 1. 一句话结论
+
+**账号是免费套餐（不是 $5/月付费），Queue 免费配额是"每天 10,000 ops"（不是"每月 1,000,000 ops"）；自 2026-04-11 起连续 14 天超限，2026-04-24 06:00 UTC 首次实测触发 send() 拒绝，约 18 小时队列完全停写。** Plan 8（`runAllScheduledJobs` D1 合并）+ Plan 13（`depositVault` 合并 + `creditQueue` 恢复批处理）于 2026-04-24 12:33 UTC 部署，效果需 04-25 UTC 完整一日数据才能评估。
+
+---
+
+## 2. 事实更正（与旧文档冲突的关键点）
+
+### 2.1 账号是 **免费套餐**，不是付费 $5
+
+| 证据 | 内容 |
+|---|---|
+| CF 邮件原文（2026-04-23 23:58 UTC）| `"daily Cloudflare Queues free tier limit of 10000 operations"` + `"upgrade your (ArcBlock) account to the Paid plan"` |
+| API `/accounts/:id/subscriptions` | 返回空数组（无任何付费订阅） |
+| Workers account settings | `default_usage_model: "standard"`（仅表示计费模型类别，不表示是否付费） |
+
+**影响的旧文档陈述**：
+- `cf-queues-ops-alert-analysis.md` §1.1 / §8.2 / §17.2 / §18.3 多处假设"1M/月免费额度"
+- `payment-kit-platform-analysis-2026-04-20.md` §3.1 成本表整表基于"$5/月付费"基线
+
+### 2.2 Queue 免费配额是 **10k ops/day**，不是 1M ops/month
+
+- 每日 UTC 00:00 重置，达到 10k 后 `queue.send()` 返回错误直到次日
+- 1 条消息 = 1 Write + 1 Read + 1 Delete = **3 ops**，所以 ~3,333 条消息/天就打满
+- 付费 Workers Paid（$5/月）才有月度 1M ops 含额度 + $0.40/M 超额
+
+### 2.3 `cf-queues-ops-alert-analysis.md §18` 运维承诺已失效
+
+| 原文 | 现状 |
+|---|---|
+| O-1 `CF Queue 日 ops（稳态）≤ 5,000 / day` | 实际 10,000–13,000 / day |
+| O-2 `月度 ops 占 1M 免费额度 ≤ 20%` | 前提错（免费是日度 10k） |
+| O-3 `修复后 30 天内告警触发频次 = 0` | 04-23 再次收到每日限额告警，04-24 触发 send() 拒绝 |
+
+原文承诺的"Plan 1 + PR #1341 部署后 ops 降到 2-4k/day"**未达成**，原因：
+1. 业务量（AI 调用产生的 MeterEvent）是 ops 总量的主导因素（~85%）
+2. PR #1341 只消除了 shim 层 5× 放大（~15% 贡献）
+3. 消除 5× 放大后，底量 ~10-13k/day 仍高于 10k 免费线
+
+### 2.4 `exceededResources` 比率恶化，未按预期降到零
+
+| 日期 | 每小时 exceeded | 过载率 |
+|---|---|---|
+| 2026-04-18 (Plan 1 刚上线) | 12 | 13% |
+| 2026-04-20 14:00 起（突变） | 60 | 上升 |
+| **2026-04-23 稳态** | **60** | **42.2%**（success 1,991 / exceeded 1,451） |
+| 2026-04-24 部署前 | 60 | ~37% |
+
+`payment-kit-platform-analysis-2026-04-20.md` §1.1 预期 "Phase 1 后 <5%" 未达成。现实是 `runAllScheduledJobs` 每分钟对 16 队列做 32 次串行 D1 RTT，总计约 2s wall-time，稳定踩 CF scheduled handler 时长上限。Plan 8（见 §3）是针对此问题的修复。
+
+---
+
+## 3. 部署记录（2026-04-24）
+
+### 3.1 Plan 8 + Plan 13 组合部署
+
+| 项目 | 值 |
+|---|---|
+| 部署时间 | **2026-04-24 12:33:43 UTC** |
+| Worker Version ID | `4effff8a-1cd0-4006-a2ec-ca88d5be8f46` |
+| Deployment ID | `94059fb5-9b18-49f1-912c-bc7311f4183a` |
+| 分支 | `fix/plan13-reduce-queue-ops` |
+| 包含 commits | `94a7fc33`（Plan 8）+ `d57651e1`（Plan 13）+ `9f1f0ef5`（D1 ctx.waitUntil fix） |
+| URL | https://staging-aigne-hub-payment-kit.arcblock.workers.dev |
+
+### 3.2 Plan 8 — `runAllScheduledJobs` D1 查询合并
+
+**文件**：`blocklets/core/cloudflare/shims/queue.ts`
+
+原实现：对 16 个已注册队列串行调用 `getScheduledJobs()` + `getJobs()` = **32 次 D1 round-trip**，每次 50–80ms，总计 1.5–2.1s wall-time。
+
+新实现：单次 `Job.findAll` 跨所有队列（`Op.in` 过滤 queueName，`Op.or` 覆盖"延迟到期 + 立即卡滞"两类），本地按 queueName 分组路由到现有 `dispatchJob`。
+
+**预期影响**：scheduled handler wall-time 2s → <150ms，`exceededResources` 应从 60/h → ~0。
+
+**测试**：`blocklets/core/cloudflare/tests/shims/queue-scheduled.spec.ts` 新增 9 个单测（无队列早退、单次 findAll、按队列分组、异常隔离、WHERE 子句结构校验等）。
+
+### 3.3 Plan 13 — 队列 ops 源头减量
+
+**文件**：`blocklets/core/api/src/queues/payment.ts` + `blocklets/core/api/src/queues/credit-consume.ts`
+
+**改动 A: `startDepositVaultQueue` 合并 N 币种为单条消息**
+- 原：N 个启用 vault 的币种 × 288 次 cron/day = **288N writes/day**
+- 新：1 条 `{ currencyIds: [...] }` 消息，consumer 内部循环处理，per-currency try/catch 隔离
+- 保留 `currencyId?` 与 `currencyIds?` 双兼容字段
+- 使用稳定 jobId `deposit-vault-batch`（D1 unique constraint 提供背压）
+
+**改动 B: `startCreditConsumeQueue` 恢复路径按 customer 分组**
+- 原：pending MeterEvent 每条 → 1 次 `addCreditConsumptionJob` → 1 条 queue 消息
+- 新：按 `(customerId, eventName, subscriptionId)` 分组，多事件组走 `handleBatchCreditConsumption` 批路径
+- 单例组保留原逐条路径（失败隔离不变）
+- 使用稳定 jobId `batch-credit-recovery-${key}`（与实时 `addToBatch` 共享 batchKey 语义）
+
+**预期影响**（保守/乐观）：
+- depositVault writes 节省：假设 N=3 → 1,728 ops/day；N=5 → 3,456 ops/day
+- credit 恢复爆发压缩：单次恢复事件节省 270–1,350 ops（取决于 pending 数量）
+- 合计：日度 ops 从 10.5k 降到 **6.5–8.8k（保守）/ 4.5k（乐观）**
+
+---
+
+## 4. 部署后 2.5 小时观察
+
+### 4.1 Queue 无法测量（仍在熔断中）
+- 今日 06:00 UTC 打满 10,448 ops 后，send() 被 CF 拒绝至今
+- 04-25 00:00 UTC 解封后才能看到 Plan 13 效果
+- 预计首个完整评估窗口：**2026-04-25 UTC 全日**
+
+### 4.2 `exceededResources` 尚无明显改善
+| UTC 时段 | exceeded/h | 相对部署 |
+|---|---|---|
+| 11:00 | 59 | 部署前 |
+| 12:00 | 61 | 部署窗口 |
+| 13:00 | 54 | T+0.5h |
+| 14:00 | 59 | T+1.5h |
+| 15:00（部分） | 10 → 投射 60 | T+2.5h |
+
+Plan 8 预期把 scheduled handler 超时清零，目前看未兑现。可能原因：
+- Scheduled 路径还有其他 I/O 瓶颈（如 `flushPendingJobs` 或 `ctx.waitUntil` 内的下游调用）
+- 需 wrangler tail 实测日志进一步定位（本地 tail auth 暂时无法用，留待后续）
+
+### 4.3 HTTP 流量自 12:00 UTC 起静默
+success 调用：09:00 **2,219** → 10:00 882 → 11:00 214 → 12:00–15:00 **0**
+
+无法判断是正常业务低潮还是 queue 熔断的二级影响（上游 aigne-hub 因 payment-kit 队列失败而停止调用）。
+
+---
+
+## 5. 旧文档勘误对照表
+
+### 5.1 `cf-queues-ops-alert-analysis.md` 勘误
+
+| 位置 | 原文 | 更正 |
+|---|---|---|
+| §1.1 | "触达免费额度（1,000,000 ops / month）的 95%" | 免费是 10k/day 日度硬顶；95% 告警触发的是"日度阈值"而非"月度" |
+| §1.4 预期表 | "PR #1341 完整部署后 2-4k/day" | 实测 11-13k/day；降幅仅 ~15% 而非 80% |
+| §1.4 预期表 | "`exceededResources` 趋近 0" | 04-20 14:00 后升至 60/h 稳态；需 Plan 8 另行修复 |
+| §4 | "占 1M/month 免费额度 10-15%" | 前提错；实际每日超限 |
+| §8.2 | "17 天累计 90k ops → 对 1M/month 免费额度占用 9%" | 前提错；免费是日度 10k |
+| §13.2 | "目标 ≤ 3,000/day" | 从未达成；目标下调为 "≤ 10,000/day" 才符合现实约束 |
+| §17.2 | "升级付费计划... 根因修完后 ops 在免费额度 10× 以内，不必升级" | 现实每日超 10k，需考虑升级或继续减量 |
+| §18.3 O-1 | "CF Queue 日 ops ≤ 5,000/day" | **承诺失效**；当前基线 10-13k |
+| §18.3 O-2 | "月度 ops 占 1M 免费额度 ≤ 20%" | **承诺失效**；前提错 |
+| §18.3 O-3 | "修复后 30 天内告警 = 0" | **承诺失效**；04-23 再次告警 |
+| §21 | Plan 5/6/7/8/9 状态为 pending | Plan 5 已完成；Plan 8 已实施并部署；Plan 13（本文档新增）已部署 |
+
+### 5.2 `payment-kit-platform-analysis-2026-04-20.md` 勘误
+
+| 位置 | 原文 | 更正 |
+|---|---|---|
+| 总述 | "2-3 周 1 人可完成，账单仍 $5-10/月" | 基线错 —— 账号**未付费**；"$5/月"是升级后的底价，不是当前实际 |
+| §1.1 | "`exceededResources` 比率 13%" | 当前 36–42%；Phase 1 完成率 1/8 未整改 |
+| §1.4 预期 | "服务端时间 15-18 秒 / `exceededResources` < 5%" | 未兑现（Phase 1 未做完）|
+| §3.1 成本表 | 各列基于 $5 付费套餐假设 | 当前未付费；付费后真实月账单详见 §6 |
+| §4 Phase 1 清单 | 8 项改动 | 实际完成度：1 (item 7) / 8；item 4 索引 2/3；item 5 代码就绪但配置默认关闭 |
+| §4 item 6 | "空数组短路" 标记为"未做" | 复查代码后发现：所有现有 `Op.in + update/destroy` 路径已有 length 守卫；Sequelize 6.37.7 下空数组自带保护。不过防御式编程规则仍建议加 lint |
+
+### 5.3 在两份旧文档顶部各加一行交叉引用（不改原文）
+
+两份文档顶部会加一行 `> [!NOTE] 2026-04-24 更新：本文档部分预期/承诺值已被现实证伪，请先阅读 2026-04-24-queue-ops-followup.md`。
+
+---
+
+## 6. 付费模式下各规模预期月账单（基于真实用量推算）
+
+Workers Paid $5/月含 10M 请求 + 30M CPU-ms + 1M Queue ops + 5B D1 rows read + 50M D1 rows written。超额单价：Queue $0.40/M，Workers $0.30/M，D1 reads $0.001/M（即 $1/B），D1 writes $1/M。
+
+| 用户规模 | Queue ops/月 | D1 rows read/月 | 月账单 |
+|---|---|---|---|
+| 当前（~100 用户）| 335k | 1.45B | **$5** |
+| 1,000 用户 | 3.3M | 14.5B（超 9.5B × $1/B + Queue 超 2.3M × $0.40）| **~$15** |
+| 10,000 用户 | 33M | 145B | **~$155**（D1 读为主）|
+| 100,000 用户 | 335M | 1.45T | **~$1,500** |
+
+**要点**：D1 rows read 是最大成本随用户规模放大器。Dashboard 预聚合（旧文档 Phase 1 item 8，未做）是长期关键优化。Queue 层优化（Plan 8 + Plan 13）对未来付费账单节省有限，但对当前免费套餐保命必要。
+
+---
+
+## 7. 后续观察计划
+
+| 时间点 | 动作 | 判据 |
+|---|---|---|
+| **2026-04-25 00:00 UTC** | Queue 配额解封，业务消息恢复写入 | 期望：Plan 13 效果显现，日度 ops <10k |
+| 2026-04-25 12:00 UTC（T+24h）| 查 04-25 UTC 全日 ops | 期望：~6.5-8.8k/day |
+| 2026-04-26 UTC（T+48h）| 稳态判断 | 期望：稳定在 <10k/day，不再收到 CF 告警 |
+| 持续 | 监测 `exceededResources` | 若 48h 后仍 60/h，Plan 8 未解决根因，需独立 PR 深入定位 |
+
+若 T+48h 后仍每天超 10k，需在下列三路径中选一：
+- **A**：升级 CF Workers Paid $5/月 —— 立即解决
+- **B**：继续压 queue writes（Phase 1 item 8 Dashboard 预聚合 + 订阅 cron 精准化），还能再降 3–5k/day
+- **C**：完全去 CF Queue 化，改为纯 D1 + cron 自驱动 —— 1-2 周工程量，性价比差
+
+---
+
+## 8. 相关文档
+
+- `cf-queues-ops-alert-analysis.md` — 2026-04-17 首次告警根因分析（原始 RCA，保留供历史溯源；§18 承诺阈值已部分失效，以本文 §5.1 勘误为准）
+- `payment-kit-platform-analysis-2026-04-20.md` — 2026-04-20 平台级评估（Phase 1 建议仍有效，但成本表基于付费套餐假设，以本文 §5.2 勘误为准）
+
+---
+
+## 9. 变更记录
+
+| 日期 | 内容 | 状态 |
+|---|---|---|
+| 2026-04-24 | 本文档产出；汇总 Plan 8 + Plan 13 部署记录、事实勘误、旧文档对照 | ✅ |
+| 2026-04-25 00:00+ UTC | 预计 Queue 配额解封，开始效果验证 | ⏳ |
+| 2026-04-26 12:00 UTC | T+48h 稳态评估 | ⏳ |