wkgeo-cli 0.2.0 → 0.2.2

package/lib/commands/billing.mjs

@@ -1,421 +1,641 @@
-/**
- * 钱包命令：`wallet` / `wallet txns` / `wallet recharge`
- *
- * 这是"钱包余额支付"链路的**观察窗口**：每次下单/支付/退款后都用它复核余额，
- * 报告里的"事前/事后一分不差"就是拿它的数字对比的。
- *
- * ⚠️ 关于"钱包流水"的接口事实（已核对服务端代码）：
- *   * `getMyWallet` 自己就带了最近流水（`data.rows`，按时间倒序，limit 1~100）——
- *     **普通用户看自己的流水就是走它**，这就是 `wallet txns` 的实现。
- *   * `adminListWalletTxns` 是**管理员**接口（能力 `billing:manage`），
- *     OAuth 令牌默认拿不到，也不该拿 —— 所以 CLI **不会**去调它。
- *   * 服务端**没有**"我的流水分页/按时间筛选"的独立接口（只有 limit，没有 offset）。
- *     这是个真实缺口，已写进报告。
- */
-
-import { withTrailingSlash } from '../config.mjs';
-import { UsageError, CliError, EXIT } from '../errors.mjs';
-import { formatMoney, formatTime } from '../format.mjs';
-import { openUrlForUser, browserPasteText, browserOpenedText, browserFailedHintLines } from '../login.mjs';
-import { renderQrOptional } from '../qr.mjs';
-
-/**
- * 拼出「我们自己的网上收银台」地址：`<webBase>/pay/?order_id=<id>&token=<支付令牌>`
- *
- * ## 为什么必须走这里、不许在命令里手拼
- *
- * 1. **尾斜杠必须在 `?` 之前**（本仓库铁律，踩过线上事故）：
- *    前端是静态导出，产物是"每个路由一个目录"（`dist/pay/index.html`），
- *    托管侧（OSS 静态托管 / 阿里云 ESA）对**不带尾斜杠**的目录路径会返回 302，
- *    而这个 302 **不携带原始 query** —— 于是 `?order_id=…` 在浏览器里
- *    根本到不了页面，用户看到的是一个"没有订单号的收银台"。
- *    所以统一走 `withTrailingSlash()`（全项目唯一构造入口，见 `config.mjs`）。
- * 2. 参数一律走 `URLSearchParams` 编码：手拼一旦漏编码，
- *    订单号里任何特殊字符都会把后面的参数吃掉（登录回跳那条链踩过同样的坑）。
- *    ⚠️ 令牌是 **base64url**，含 `-` / `_` / `.`，看着"很安全"，但**也必须编码** ——
- *      别因为"它字面上没特殊字符"就手拼。
- *
- * ⚠️ 老板定的产品流程就是这条：**在网上生成订单 → 打开我们网站的收银台页面**，
- *    而不是"在本地搞一个二维码让别人扫"。
- *
- * ## ★ 2026-10-02 新增第三个参数：订单支付令牌（`token`）
- *   老板原话：「你拿到 token 之后，**以那个 token 为基础来进行支付**，
- *   而不是还要他用**用户名那一套**来进行支付。」
- *
- *   现场：用户是在 **AI 客户端右侧的内置浏览器**里付这一单，那里**通常没有网页登录态**
- *   （甚至跟他平时登录后台的账号不是同一个）。服务端在下单时把"这一单是谁的"签成
- *   一把**只对这一单有效**的令牌（`createRechargeOrder` 的 `pay_token`）交给我们，
- *   收银台凭它就能读这一单的支付参数 —— **不需要网页登录**。
- *   ⚠️ 令牌只授权"读这一单的支付参数"：读不到钱包、读不到订单列表、不能下单、不能取消。
- *
- *   ⚠️ 幂等/兼容：服务端**没给**令牌（老版本云函数未部署 / 密钥未配置）时，
- *      `payUrl` 照旧只有 `order_id` —— 那条路**仍然要求网页登录**，
- *      行为与改造前逐字一致（不因为"新功能没上线"就把命令搞失败）。
- *
- * @param {string} webBase  前端基址。★ 2026-10-02 起传的是 `config.payWebBase`
- *                          （`https://pay.wkgeo.com`），老站基址只是兜底
- * @param {string} orderId  订单号
- * @param {string} [payToken] 订单支付令牌（`pay_token`），没有就不带这个参数
- * @returns {string|null} 订单号缺失时返回 null（没订单号就拼不出能用的收银台地址）
- */
-export function buildPayUrl(webBase, orderId, payToken) {
-  const id = orderId === undefined || orderId === null ? '' : String(orderId).trim();
-  if (!id) return null;
-  const base = String(webBase || '').replace(/\/+$/, '');
-  const params = { order_id: id };
-  const token =
-    payToken === undefined || payToken === null ? '' : String(payToken).trim();
-  if (token) params.token = token;
-  const query = new URLSearchParams(params).toString();
-  return withTrailingSlash(`${base}/pay`) + `?${query}`;
-}
-
-const KIND_LABEL = {
-  recharge: '充值',
-  pay: '支付',
-  refund: '退款',
-  adjust: '调账',
-  grant: '赠送',
-  withdraw: '提现',
-};
-
-function normalizeTxn(r) {
-  const amount = Number(r.amount_cents) || 0;
-  return {
-    id: r.id ?? null,
-    kind: r.kind || null,
-    kind_label: KIND_LABEL[r.kind] || r.kind || null,
-    amount_cents: amount,
-    amount_text: `${amount >= 0 ? '+' : '-'}${formatMoney(Math.abs(amount))}`,
-    balance_after_cents: r.balance_after === undefined || r.balance_after === null ? null : Number(r.balance_after),
-    balance_after_text: r.balance_after === undefined || r.balance_after === null ? '-' : formatMoney(r.balance_after),
-    order_id: r.order_id || null,
-    remark: r.remark || null,
-    created_at: r.created_at || null,
-  };
-}
-
-async function loadWallet(ctx, limit) {
-  const res = await ctx.callData('getMyWallet', { limit });
-  const rows = (res && Array.isArray(res.rows) ? res.rows : []).map(normalizeTxn);
-  return { balance_cents: Number((res && res.balance_cents) || 0), rows };
-}
-
-const TXN_COLUMNS = [
-  { title: '时间', key: 'created_at', format: (v) => formatTime(v), width: 20 },
-  { title: '类型', key: 'kind_label', width: 8 },
-  { title: '金额', key: 'amount_text', width: 12 },
-  { title: '余额后', key: 'balance_after_text', width: 12 },
-  { title: '备注', key: 'remark', width: 34 },
-];
-
-/* ------------------------------------------------------------------ */
-/* wallet（总览）                                                       */
-/* ------------------------------------------------------------------ */
-
-export const walletCommand = {
-  name: 'wallet',
-  summary: '查钱包余额与最近流水（加 --entitlements 看生效中的权益）',
-  usage: 'wkgeo wallet [--limit 10] [--entitlements]',
-  flags: {
-    limit: { type: 'string', desc: '流水条数（1~100，默认 10）' },
-    entitlements: { type: 'boolean', desc: '同时列出我的权益（加量包/套餐生效情况）' },
-  },
-  async run(ctx) {
-    const { out, flags } = ctx;
-    const limit = flags.limit !== undefined ? Number(flags.limit) : 10;
-    const wallet = await loadWallet(ctx, limit);
-
-    let entitlements = null;
-    if (flags.entitlements) {
-      try {
-        const e = await ctx.callData('listMyEntitlements', {});
-        entitlements = (e && e.rows) || [];
-      } catch (err) {
-        // 权益接口未部署/无权限时不该让"查余额"这个核心动作失败
-        out.warn(`读取权益失败（不影响余额）：${err.message}`);
-        entitlements = null;
-      }
-    }
-
-    const data = {
-      balance_cents: wallet.balance_cents,
-      balance_text: formatMoney(wallet.balance_cents),
-      rows: wallet.rows,
-      entitlements: entitlements
-        ? entitlements.map((x) => ({
-            quota_key: x.quota_key || null,
-            name: x.name || null,
-            amount: x.amount ?? null,
-            used: x.used ?? null,
-            status: x.status || null,
-            expires_at: x.expires_at || null,
-          }))
-        : undefined,
-    };
-
-    if (!out.json) {
-      out.head('钱包');
-      out.line(`  余额：${data.balance_text}`);
-      out.line('');
-      out.line('最近流水：');
-      out.table(TXN_COLUMNS, wallet.rows);
-      if (entitlements) {
-        out.line('');
-        out.line('生效中的权益：');
-        out.table(
-          [
-            { title: '配额', key: 'quota_key', width: 18 },
-            { title: '数量', key: 'amount', width: 12 },
-            { title: '状态', key: 'status', width: 10 },
-            { title: '到期', key: 'expires_at', format: (v) => formatTime(v), width: 20 },
-          ],
-          entitlements,
-        );
-      }
-    }
-    ctx.done(data);
-    return data;
-  },
-};
-
-/* ------------------------------------------------------------------ */
-/* wallet txns                                                         */
-/* ------------------------------------------------------------------ */
-
-export const walletTxnsCommand = {
-  name: 'wallet txns',
-  summary: '钱包流水（走"我的钱包"接口自带的流水，普通用户即可读）',
-  usage: 'wkgeo wallet txns [--limit 20]',
-  flags: {
-    limit: { type: 'string', desc: '流水条数（1~100，默认 20）' },
-  },
-  async run(ctx) {
-    const { out, flags } = ctx;
-    const limit = flags.limit !== undefined ? Number(flags.limit) : 20;
-    const wallet = await loadWallet(ctx, limit);
-    const data = {
-      balance_cents: wallet.balance_cents,
-      balance_text: formatMoney(wallet.balance_cents),
-      rows: wallet.rows,
-      total: wallet.rows.length,
-      note: '服务端当前只支持 limit，没有 offset/时间筛选（我的流水缺口）',
-    };
-    if (!out.json) {
-      out.head(`钱包流水（最近 ${wallet.rows.length} 条）`);
-      out.line(`  当前余额：${data.balance_text}`);
-      out.line('');
-      out.table(TXN_COLUMNS, wallet.rows);
-    }
-    ctx.done(data);
-    return data;
-  },
-};
-
-/* ------------------------------------------------------------------ */
-/* wallet recharge                                                     */
-/* ------------------------------------------------------------------ */
-
-export const walletRechargeCommand = {
-  name: 'wallet recharge',
-  summary:
-    '充值下单：创建一笔微信 Native 待支付订单，**并打开我们网站的收银台页面**扫码支付（不会自动扣款）',
-  usage: 'wkgeo wallet recharge --amount-cents <分> [--no-browser] [--open-browser] [--dry-run]',
-  flags: {
-    'amount-cents': { type: 'string', required: true, desc: '充值金额，单位**分**（如 100 = ¥1.00，最低 100，最高 10000000）' },
-    'no-browser': { type: 'boolean', desc: '不自动打开浏览器（自动化/无桌面环境用；地址仍会打印并放在 pay_url 里）' },
-    /**
-     * ★ 老板最终拍板走**传统路线**：默认**总是尝试打开**系统浏览器（人在终端与 AI 场景都一样），
-     *   所以本开关现在**与默认行为等价**。保留它只为两件事：
-     *     1. **显式语义**（脚本里写"我就是要弹"比依赖默认值更清楚）；
-     *     2. **兼容**既有脚本（不许删）。
-     * ⚠️ `--no-browser` 优先（关掉就是关掉，见 login.mjs 的 resolveBrowserIntent）。
-     */
-    'open-browser': { type: 'boolean', desc: '强制尝试打开系统浏览器（⚠️ 现在与默认行为等价，保留只为显式语义与兼容）' },
-    'dry-run': { type: 'boolean', desc: '只打印将要做什么，不真的创建订单' },
-  },
-  async run(ctx) {
-    const { out, flags } = ctx;
-    const amountCents = Number(flags.amountCents);
-    if (!Number.isInteger(amountCents) || amountCents <= 0) {
-      throw new UsageError(`--amount-cents 必须是正整数（单位：分），收到：${flags.amountCents}`);
-    }
-    if (amountCents < 100) throw new UsageError('充值金额不能低于 ¥1.00（100 分）');
-    if (amountCents > 10000000) throw new UsageError('单笔充值不能超过 ¥100,000.00（10000000 分）');
-
-    if (flags.dryRun === true) {
-      const data = {
-        dry_run: true,
-        amount_cents: amountCents,
-        amount_text: formatMoney(amountCents),
-        created: false,
-        /** 真跑时会给出的收银台地址（彩排阶段还没有订单号，所以是 null） */
-        pay_url: null,
-      };
-      if (!out.json) {
-        out.head('充值（彩排，未创建订单）');
-        out.line(`  将创建一笔 ¥${(amountCents / 100).toFixed(2)} 的微信 Native 待支付订单`);
-        out.info('  去掉 --dry-run 即真正创建；创建后 CLI 会**打开我们网站的收银台页面**让你扫码支付（不会自动扣款）。');
-      }
-      ctx.done(data);
-      return data;
-    }
-
-    /**
-     * ⚠️ 这里会**在微信侧创建一笔真实的待支付商户订单**（不扣款、不自动支付）。
-     *    这是"老板要测充值"必须的能力，但绝不能在自动化测试里跑 ——
-     *    测试只在离线桩里验证请求体，真钱流程由人手动完成。
-     */
-    const res = await ctx.callData('createRechargeOrder', { amount_cents: amountCents });
-    const orderId = (res && res.order_id) || null;
-    /**
-     * ★ 我们自己的**网上收银台**地址（老板定的产品流程：走网上充值页面，
-     *   而不是在本地生成一个二维码页面让人扫）。
-     *   拼装口径与尾斜杠规则见本文件顶部的 `buildPayUrl()`。
-     *
-     * ★ 第三个参数 = 服务端在**下单那一刻**签发的订单支付令牌（`pay_token`）：
-     *   带上它，收银台在**没有网页登录态**的 AI 端内置浏览器里也能付这一单
-     *   （老板："以那个 token 为基础来进行支付，而不是还要他用用户名那一套"）。
-     *   ⚠️ 老服务端没这个字段时就是 `undefined` ⇒ 地址退回只有 `order_id` 的老形态。
-     *
-     * ★ 2026-10-02（三站拆分）：基址改用**收银台子域** `config.payWebBase`
-     *   （`https://pay.wkgeo.com`）。`config.webBase` 只作为老配置对象的兜底
-     *   （联调时 `WKONGAI_WEB_BASE` 总覆盖会把两者设成同一个值）。
-     */
-    const payUrl = buildPayUrl(
-      ctx.config && (ctx.config.payWebBase || ctx.config.webBase),
-      orderId,
-      res && res.pay_token,
-    );
-    const data = {
-      order_id: orderId,
-      out_trade_no: (res && res.out_trade_no) || null,
-      paid: !!(res && res.paid),
-      amount_cents: Number((res && res.amount_cents) || amountCents),
-      amount_text: formatMoney((res && res.amount_cents) || amountCents),
-      pay_amount_cents: res && res.pay_amount_cents !== undefined ? Number(res.pay_amount_cents) : null,
-      /** 微信侧的支付链接：**保留给自动化**，但人看的流程走 pay_url（下面那行） */
-      code_url: (res && res.code_url) || null,
-      /** ★ 收银台地址：人点它、自动化也可以直接开它 */
-      pay_url: payUrl,
-      expires_at_minutes: (res && res.expires_at_minutes) || null,
-      wallet_paid_cents: Number((res && res.wallet_paid_cents) || 0),
-      open_browser: { attempted: false, opened: false, tried: [], url: payUrl || '', skipped_reason: null },
-      /** ★ 给 AI 端"照着念"的一句话（下面 openUrlForUser 之后会按实际情况覆盖） */
-      paste_text: payUrl ? browserPasteText(payUrl, { kind: 'pay' }) : null,
-    };
-
-    /**
-     * 自动打开收银台。
-     *
-     * ⚠️ 复用 `login.mjs` 的 `openUrlForUser`（多策略 + 结果归一化 + ★「默认总是尝试打开」闸门），
-     *    **不是**在这里再写一份 spawn —— 那几个坑（cmd start 的引号、URL 里的 `&`
-     *    被 shell 吃掉、error 事件没挂）在那边已经踩过并修过，复制一份必然会再踩。
-     * ⚠️ 打开失败**绝不允许**让命令失败：地址已经完整打印（人类可读）并放在
-     *    `--json` 的 `pay_url` 里，手动复制照样能完成支付。
-     * ⚠️ 闸门在 `openUrlForUser` **内部**：这里不再自己判断"要不要开"（除了 payUrl 有没有），
-     *    否则总有一天会出现"授权不弹、支付还弹"。
-     */
-    if (payUrl) {
-      data.open_browser = await openUrlForUser(payUrl, {
-        deps: {
-          openBrowser: ctx.openBrowser,
-          spawnImpl: ctx.spawnImpl,
-          platform: ctx.platform,
-          verbose: !!(ctx.config && ctx.config.verbose),
-          /** ★ 与 login 同源的四个事实（见 login.mjs 的 resolveBrowserIntent） */
-          isTTY: ctx.isTTY === true,
-          json: out.json === true,
-          forceOpen: flags.openBrowser === true,
-          noBrowser: flags.noBrowser === true,
-        },
-        log: (m) => out.info(m),
-      });
-      data.paste_text = browserPasteText(payUrl, { kind: 'pay' });
-    }
-
-    if (!out.json) {
-      out.head('充值订单已创建');
-      out.line(`  订单号：${data.order_id}`);
-      out.line(`  金额：${data.amount_text}`);
-      out.line(`  有效期：${data.expires_at_minutes ?? '?'} 分钟`);
-      if (payUrl) {
-        out.line('');
-        out.line('  收银台（我们网站的充值页面，请在这里扫码支付）：');
-        out.line(`  ${payUrl}`);
-        if (flags.noBrowser === true) {
-          out.info('  （已按 --no-browser 跳过自动打开）请把上面这一整行复制到浏览器地址栏打开。');
-        } else if (data.open_browser.opened) {
-          // ★ 成功：明说"已经打开了"（老板最终拍板走传统路线：弹系统浏览器）
-          out.line(browserOpenedText({ kind: 'pay' }));
-        } else {
-          /**
-           * 打开失败：与 login 同一段文案（`browserFailedHintLines`）——
-           *   1. **醒目**：说清"没能自动打开"，别让用户以为还在打开中；
-           *   2. **可操作**：把**完整地址再打一遍**，并说清动作是"复制→粘贴到地址栏"；
-           *   3. 说清打开之后干什么（用微信扫码）。
-           */
-          for (const line of browserFailedHintLines(payUrl, { kind: 'pay', agent: ctx.isTTY !== true })) {
-            out.line(line);
-          }
-        }
-
-        /**
-         * ★ 2026-10-02（老板）：**支付完成之后那个页面会自己关掉** —— 提前交代一句。
-         *   为什么要说：页面"自己没了"时，用户第一反应是"是不是崩了 / 是不是没付成功"；
-         *   提前说一句，这件事就变成"预期之内"。
-         *   ⚠️ 后半句"没关就手动关掉即可"**不能省**：`window.close()` 只对**脚本打开的**窗口
-         *      有效，收银台是导航过去的 ⇒ **大概率关不掉**（详见
-         *      `admin-web/src/pages/billing/pay` 的「尝试自动关闭」注释）。
-         */
-        out.info('（支付成功后页面会自动尝试关闭；没关就手动关掉即可。）');
-
-        /**
-         * 终端二维码：**只在网页打不开时**作为兜底。
-         * ⚠️ 老板明确否掉了"本地生成二维码让别人扫"当**主流程**的做法：
-         *    二维码只是收银台页面内部的一个展示件；终端里画码这条路必须降级，
-         *    而且要说清"正常应该在我们网站的收银台页面上扫"。
-         */
-        const 网页没打开 = data.open_browser.attempted && !data.open_browser.opened;
-        if (网页没打开 && data.code_url) {
-          out.line('');
-          out.info('  兜底：网页确实打不开时，也可以直接用微信扫下面这个二维码。');
-          out.info('  （正常流程请在上面那个收银台页面里扫码支付。）');
-          const qrShown = await renderQrOptional(data.code_url, out);
-          if (!qrShown) {
-            out.info('  （未安装可选的 qrcode-terminal，无法在终端画码；请用上面的收银台地址付款）');
-          }
-        }
-        out.line('');
-        out.line(`  支付完成后运行：wkgeo orders check ${data.order_id}   # 查支付结果与最新余额`);
-      } else if (data.code_url) {
-        out.warn('没有拼出收银台地址（订单号缺失），只能给出微信支付链接');
-        out.line(`  ${data.code_url}`);
-      } else {
-        out.warn('服务端没有返回 code_url（可能微信支付参数未配置），请到网页后台核对');
-      }
-      out.info('  CLI 不会替你付款，也不会模拟支付成功。');
-    } else if (payUrl) {
-      /**
-       * ★ `--json` / 非 TTY 时，**人看的那段提示不能消失**：走 stderr（`out.notice`），
-       *   stdout 依然只有机器可读 JSON；结构化字段（`pay_url` / `paste_text` / `open_browser`）
-       *   照样都在 stdout 里。
-       *
-       * ★ 老板最终拍板走传统路线后，这里的分支变成"如实播报结果"：
-       *   * `--no-browser` → 明说跳过了（地址仍要打印，用户得能复制）；
-       *   * 打开成功      → 说一句"已为你打开浏览器"；
-       *   * 打开失败      → ⚠️ 那段**含完整地址**的醒目提示（AI 端/用户就靠它手动打开）。
-       *     ⚠️ 失败提示**不能只给 JSON**：真客户不会去 `pay_url` 字段里翻地址。
-       */
-      if (flags.noBrowser === true) {
-        out.notice('（已按 --no-browser 跳过自动打开）请手动复制 pay_url 到浏览器地址栏打开。');
-      } else if (data.open_browser.opened) {
-        out.notice(browserOpenedText({ kind: 'pay' }));
-      } else {
-        for (const line of browserFailedHintLines(payUrl, { kind: 'pay', agent: true })) out.notice(line);
-      }
-    }
-    ctx.done(data);
-    return data;
-  },
-};
+/**
+ * 钱包命令：`wallet` / `wallet txns` / `wallet recharge`
+ *
+ * 这是"钱包余额支付"链路的**观察窗口**：每次下单/支付/退款后都用它复核余额，
+ * 报告里的"事前/事后一分不差"就是拿它的数字对比的。
+ *
+ * ⚠️ 关于"钱包流水"的接口事实（已核对服务端代码）：
+ *   * `getMyWallet` 自己就带了最近流水（`data.rows`，按时间倒序，limit 1~100）——
+ *     **普通用户看自己的流水就是走它**，这就是 `wallet txns` 的实现。
+ *   * `adminListWalletTxns` 是**管理员**接口（能力 `billing:manage`），
+ *     OAuth 令牌默认拿不到，也不该拿 —— 所以 CLI **不会**去调它。
+ *   * 服务端**没有**"我的流水分页/按时间筛选"的独立接口（只有 limit，没有 offset）。
+ *     这是个真实缺口，已写进报告。
+ */
+
+import { withTrailingSlash } from '../config.mjs';
+import { UsageError, CliError, EXIT } from '../errors.mjs';
+import { formatMoney, formatTime } from '../format.mjs';
+import { openUrlForUser, browserPasteText, browserOpenedText, browserFailedHintLines } from '../login.mjs';
+import { renderQrOptional } from '../qr.mjs';
+
+/**
+ * 拼出「我们自己的网上收银台」地址：`<webBase>/?order_id=<id>&token=<支付令牌>`
+ *
+ * ★ 2026-10-02（第二次拍板）：收银台站去掉了冗余的 `/pay` 前缀 —— **收银台就是站根 `/`**
+ *   （`https://pay.wkgeo.com/?order_id=…`，原来是 `…/?order_id=…`）。
+ *
+ * ## 为什么必须走这里、不许在命令里手拼
+ *
+ * 1. **尾斜杠必须在 `?` 之前**（本仓库铁律，踩过线上事故）：
+ *    前端是静态导出，产物是"每个路由一个目录"（`dist-pay/xxx/index.html`），
+ *    托管侧（OSS 静态托管 / 阿里云 ESA）对**不带尾斜杠**的目录路径会返回 302，
+ *    而这个 302 **不携带原始 query** —— 于是 `?order_id=…` 在浏览器里
+ *    根本到不了页面，用户看到的是一个"没有订单号的收银台"。
+ *    所以路径一律走 `withTrailingSlash()`（全项目唯一构造入口，见 `config.mjs`）；
+ *    收银台搬到站根之后这条对它不再适用，但拼法照旧过一道（对 `/` 幂等）。
+ * 2. 参数一律走 `URLSearchParams` 编码：手拼一旦漏编码，
+ *    订单号里任何特殊字符都会把后面的参数吃掉（登录回跳那条链踩过同样的坑）。
+ *    ⚠️ 令牌是 **base64url**，含 `-` / `_` / `.`，看着"很安全"，但**也必须编码** ——
+ *      别因为"它字面上没特殊字符"就手拼。
+ *
+ * ⚠️ 老板定的产品流程就是这条：**在网上生成订单 → 打开我们网站的收银台页面**，
+ *    而不是"在本地搞一个二维码让别人扫"。
+ *
+ * ## ★ 2026-10-02 新增第三个参数：订单支付令牌（`token`）
+ *   老板原话：「你拿到 token 之后，**以那个 token 为基础来进行支付**，
+ *   而不是还要他用**用户名那一套**来进行支付。」
+ *
+ *   现场：用户是在 **AI 客户端右侧的内置浏览器**里付这一单，那里**通常没有网页登录态**
+ *   （甚至跟他平时登录后台的账号不是同一个）。服务端在下单时把"这一单是谁的"签成
+ *   一把**只对这一单有效**的令牌（`createRechargeOrder` 的 `pay_token`）交给我们，
+ *   收银台凭它就能读这一单的支付参数 —— **不需要网页登录**。
+ *   ⚠️ 令牌只授权"读这一单的支付参数"：读不到钱包、读不到订单列表、不能下单、不能取消。
+ *
+ *   ⚠️ 幂等/兼容：服务端**没给**令牌（老版本云函数未部署 / 密钥未配置）时，
+ *      `payUrl` 照旧只有 `order_id` —— 那条路**仍然要求网页登录**，
+ *      行为与改造前逐字一致（不因为"新功能没上线"就把命令搞失败）。
+ *
+ * @param {string} webBase  前端基址。★ 2026-10-02 起传的是 `config.payWebBase`
+ *                          （`https://pay.wkgeo.com`），老站基址只是兜底
+ * @param {string} orderId  订单号
+ * @param {string} [payToken] 订单支付令牌（`pay_token`），没有就不带这个参数
+ * @returns {string|null} 订单号缺失时返回 null（没订单号就拼不出能用的收银台地址）
+ */
+export function buildPayUrl(webBase, orderId, payToken) {
+  const id = orderId === undefined || orderId === null ? '' : String(orderId).trim();
+  if (!id) return null;
+  const base = String(webBase || '').replace(/\/+$/, '');
+  const params = { order_id: id };
+  const token =
+    payToken === undefined || payToken === null ? '' : String(payToken).trim();
+  if (token) params.token = token;
+  const query = new URLSearchParams(params).toString();
+  // ★ 2026-10-02（第二次拍板）：收银台站去掉冗余的 `/pay` 前缀 —— **收银台就是站根 `/`**
+  //    （原来是 `${base}/pay`）。`withTrailingSlash('https://pay.wkgeo.com')` 补出
+  //    `https://pay.wkgeo.com/`，正好是收银台首页；尾斜杠在 `?` 之前这条规矩也仍然成立。
+  //    ⚠️ 站根是桶里真实存在的 `index.html`（不是"目录路径"），不会再触发
+  //       下面第 1 条那个"目录 302 丢 query"的坑。
+  return withTrailingSlash(base) + `?${query}`;
+}
+
+/**
+ * 拼「独立充值页」地址：`<收银台基址>/recharge/?ticket=<一次性凭证>`
+ *
+ * ★ 2026-10-02（方案 A，老板拍板）：收银台站上新增了一个**独立充值页** ——
+ *   用户在那一页**自己选金额**（¥10 / ¥20 快捷，或自定义；最低 ¥9.90、不设上限），
+ *   提交后由页面用 ticket 建单、再跳到收银台扫码支付，**全程不需要登录会员中心**。
+ *
+ * ⚠️ 为什么地址里只能是 **ticket** 而不是长期 OAuth 令牌：
+ *    地址会进浏览器历史、Referer、各级网关日志。ticket 是**一次性 + 10 分钟**的窄凭证
+ *    （只够建一笔充值单），长期令牌一旦从这些地方漏出去就是 30 天的全量授权。
+ * ⚠️ 尾斜杠必须落在 `?` 之前（本仓库铁律，踩过线上事故）：
+ *    前端产物是"每个路由一个目录"（`dist-pay/recharge/index.html`），
+ *    托管侧对**不带尾斜杠**的目录路径会 302，而那个 302 **不携带原始 query** ——
+ *    于是 `?ticket=…` 根本到不了页面，用户看到的是一个"没有凭证的充值页"。
+ *    所以路径**必须**过 `withTrailingSlash()`（全项目唯一构造入口，见 `config.mjs`）。
+ * ⚠️ 参数一律走 `URLSearchParams` 编码：ticket 是 base64url（含 `-` `_`），
+ *    手拼看着"很安全"，但这类豁免迟早会在别的字符上出事。
+ *
+ * @param {string} webBase 收银台站基址（`config.payWebBase`，老配置对象里是 `webBase`）
+ * @param {string} ticket  一次性充值凭证（`createRechargeTicket` 返回的 `ticket`）
+ * @returns {string|null} 没有 ticket 就返回 null（没凭证就拼不出能用的地址）
+ */
+export function buildRechargeTicketUrl(webBase, ticket) {
+  const t = ticket === undefined || ticket === null ? '' : String(ticket).trim();
+  if (!t) return null;
+  const base = String(webBase || '').replace(/\/+$/, '');
+  const query = new URLSearchParams({ ticket: t }).toString();
+  // `/recharge` 是收银台站上的一级路径（构建期由 `SITES.pay.rewritePaths` 把
+  // `/pay/recharge` 改写成 `/recharge`；子域已说明是哪个站，路径不再重复 `/pay`）。
+  return `${withTrailingSlash(`${base}/recharge`)}?${query}`;
+}
+
+const KIND_LABEL = {
+  recharge: '充值',
+  pay: '支付',
+  refund: '退款',
+  adjust: '调账',
+  grant: '赠送',
+  withdraw: '提现',
+};
+
+function normalizeTxn(r) {
+  const amount = Number(r.amount_cents) || 0;
+  return {
+    id: r.id ?? null,
+    kind: r.kind || null,
+    kind_label: KIND_LABEL[r.kind] || r.kind || null,
+    amount_cents: amount,
+    amount_text: `${amount >= 0 ? '+' : '-'}${formatMoney(Math.abs(amount))}`,
+    balance_after_cents: r.balance_after === undefined || r.balance_after === null ? null : Number(r.balance_after),
+    balance_after_text: r.balance_after === undefined || r.balance_after === null ? '-' : formatMoney(r.balance_after),
+    order_id: r.order_id || null,
+    remark: r.remark || null,
+    created_at: r.created_at || null,
+  };
+}
+
+async function loadWallet(ctx, limit) {
+  const res = await ctx.callData('getMyWallet', { limit });
+  const rows = (res && Array.isArray(res.rows) ? res.rows : []).map(normalizeTxn);
+  return { balance_cents: Number((res && res.balance_cents) || 0), rows };
+}
+
+const TXN_COLUMNS = [
+  { title: '时间', key: 'created_at', format: (v) => formatTime(v), width: 20 },
+  { title: '类型', key: 'kind_label', width: 8 },
+  { title: '金额', key: 'amount_text', width: 12 },
+  { title: '余额后', key: 'balance_after_text', width: 12 },
+  { title: '备注', key: 'remark', width: 34 },
+];
+
+/* ------------------------------------------------------------------ */
+/* wallet（总览）                                                       */
+/* ------------------------------------------------------------------ */
+
+export const walletCommand = {
+  name: 'wallet',
+  summary: '查钱包余额与最近流水（加 --entitlements 看生效中的权益）',
+  usage: 'wkgeo wallet [--limit 10] [--entitlements]',
+  flags: {
+    limit: { type: 'string', desc: '流水条数（1~100，默认 10）' },
+    entitlements: { type: 'boolean', desc: '同时列出我的权益（加量包/套餐生效情况）' },
+  },
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const limit = flags.limit !== undefined ? Number(flags.limit) : 10;
+    const wallet = await loadWallet(ctx, limit);
+
+    let entitlements = null;
+    if (flags.entitlements) {
+      try {
+        const e = await ctx.callData('listMyEntitlements', {});
+        entitlements = (e && e.rows) || [];
+      } catch (err) {
+        // 权益接口未部署/无权限时不该让"查余额"这个核心动作失败
+        out.warn(`读取权益失败（不影响余额）：${err.message}`);
+        entitlements = null;
+      }
+    }
+
+    const data = {
+      balance_cents: wallet.balance_cents,
+      balance_text: formatMoney(wallet.balance_cents),
+      rows: wallet.rows,
+      entitlements: entitlements
+        ? entitlements.map((x) => ({
+            quota_key: x.quota_key || null,
+            name: x.name || null,
+            amount: x.amount ?? null,
+            used: x.used ?? null,
+            status: x.status || null,
+            expires_at: x.expires_at || null,
+          }))
+        : undefined,
+    };
+
+    if (!out.json) {
+      out.head('钱包');
+      out.line(`  余额：${data.balance_text}`);
+      out.line('');
+      out.line('最近流水：');
+      out.table(TXN_COLUMNS, wallet.rows);
+      if (entitlements) {
+        out.line('');
+        out.line('生效中的权益：');
+        out.table(
+          [
+            { title: '配额', key: 'quota_key', width: 18 },
+            { title: '数量', key: 'amount', width: 12 },
+            { title: '状态', key: 'status', width: 10 },
+            { title: '到期', key: 'expires_at', format: (v) => formatTime(v), width: 20 },
+          ],
+          entitlements,
+        );
+      }
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* wallet txns                                                         */
+/* ------------------------------------------------------------------ */
+
+export const walletTxnsCommand = {
+  name: 'wallet txns',
+  summary: '钱包流水（走"我的钱包"接口自带的流水，普通用户即可读）',
+  usage: 'wkgeo wallet txns [--limit 20]',
+  flags: {
+    limit: { type: 'string', desc: '流水条数（1~100，默认 20）' },
+  },
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const limit = flags.limit !== undefined ? Number(flags.limit) : 20;
+    const wallet = await loadWallet(ctx, limit);
+    const data = {
+      balance_cents: wallet.balance_cents,
+      balance_text: formatMoney(wallet.balance_cents),
+      rows: wallet.rows,
+      total: wallet.rows.length,
+      note: '服务端当前只支持 limit，没有 offset/时间筛选（我的流水缺口）',
+    };
+    if (!out.json) {
+      out.head(`钱包流水（最近 ${wallet.rows.length} 条）`);
+      out.line(`  当前余额：${data.balance_text}`);
+      out.line('');
+      out.table(TXN_COLUMNS, wallet.rows);
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* wallet recharge                                                     */
+/* ------------------------------------------------------------------ */
+
+export const walletRechargeCommand = {
+  name: 'wallet recharge',
+  summary:
+    '充值下单：创建一笔微信 Native 待支付订单，**并打开我们网站的收银台页面**扫码支付（不会自动扣款）',
+  usage: 'wkgeo wallet recharge --amount-cents <分> [--no-browser] [--open-browser] [--dry-run]',
+  flags: {
+    'amount-cents': { type: 'string', required: true, desc: '充值金额，单位**分**（最低 990 = ¥9.90；**不设上限**）' },
+    'no-browser': { type: 'boolean', desc: '不自动打开浏览器（自动化/无桌面环境用；地址仍会打印并放在 pay_url 里）' },
+    /**
+     * ★ 老板最终拍板走**传统路线**：默认**总是尝试打开**系统浏览器（人在终端与 AI 场景都一样），
+     *   所以本开关现在**与默认行为等价**。保留它只为两件事：
+     *     1. **显式语义**（脚本里写"我就是要弹"比依赖默认值更清楚）；
+     *     2. **兼容**既有脚本（不许删）。
+     * ⚠️ `--no-browser` 优先（关掉就是关掉，见 login.mjs 的 resolveBrowserIntent）。
+     */
+    'open-browser': { type: 'boolean', desc: '强制尝试打开系统浏览器（⚠️ 现在与默认行为等价，保留只为显式语义与兼容）' },
+    'dry-run': { type: 'boolean', desc: '只打印将要做什么，不真的创建订单' },
+  },
+  async run(ctx) {
+    const { out, flags } = ctx;
+    const amountCents = Number(flags.amountCents);
+    if (!Number.isInteger(amountCents) || amountCents <= 0) {
+      throw new UsageError(`--amount-cents 必须是正整数（单位：分），收到：${flags.amountCents}`);
+    }
+    if (amountCents < 990) throw new UsageError('充值金额不能低于 ¥9.90（990 分）');
+    // ⚠️ 单笔**不设业务上限**（老板 2026-10-02）；只保留安全整数兜底，避免溢出
+
+    if (flags.dryRun === true) {
+      const data = {
+        dry_run: true,
+        amount_cents: amountCents,
+        amount_text: formatMoney(amountCents),
+        created: false,
+        /** 真跑时会给出的收银台地址（彩排阶段还没有订单号，所以是 null） */
+        pay_url: null,
+      };
+      if (!out.json) {
+        out.head('充值（彩排，未创建订单）');
+        out.line(`  将创建一笔 ¥${(amountCents / 100).toFixed(2)} 的微信 Native 待支付订单`);
+        out.info('  去掉 --dry-run 即真正创建；创建后 CLI 会**打开我们网站的收银台页面**让你扫码支付（不会自动扣款）。');
+      }
+      ctx.done(data);
+      return data;
+    }
+
+    /**
+     * ⚠️ 这里会**在微信侧创建一笔真实的待支付商户订单**（不扣款、不自动支付）。
+     *    这是"老板要测充值"必须的能力，但绝不能在自动化测试里跑 ——
+     *    测试只在离线桩里验证请求体，真钱流程由人手动完成。
+     */
+    const res = await ctx.callData('createRechargeOrder', { amount_cents: amountCents });
+    const orderId = (res && res.order_id) || null;
+    /**
+     * ★ 我们自己的**网上收银台**地址（老板定的产品流程：走网上充值页面，
+     *   而不是在本地生成一个二维码页面让人扫）。
+     *   拼装口径与尾斜杠规则见本文件顶部的 `buildPayUrl()`。
+     *
+     * ★ 第三个参数 = 服务端在**下单那一刻**签发的订单支付令牌（`pay_token`）：
+     *   带上它，收银台在**没有网页登录态**的 AI 端内置浏览器里也能付这一单
+     *   （老板："以那个 token 为基础来进行支付，而不是还要他用用户名那一套"）。
+     *   ⚠️ 老服务端没这个字段时就是 `undefined` ⇒ 地址退回只有 `order_id` 的老形态。
+     *
+     * ★ 2026-10-02（三站拆分）：基址改用**收银台子域** `config.payWebBase`
+     *   （`https://pay.wkgeo.com`）。`config.webBase` 只作为老配置对象的兜底
+     *   （联调时 `WKONGAI_WEB_BASE` 总覆盖会把两者设成同一个值）。
+     */
+    const payUrl = buildPayUrl(
+      ctx.config && (ctx.config.payWebBase || ctx.config.webBase),
+      orderId,
+      res && res.pay_token,
+    );
+    const data = {
+      order_id: orderId,
+      out_trade_no: (res && res.out_trade_no) || null,
+      paid: !!(res && res.paid),
+      amount_cents: Number((res && res.amount_cents) || amountCents),
+      amount_text: formatMoney((res && res.amount_cents) || amountCents),
+      pay_amount_cents: res && res.pay_amount_cents !== undefined ? Number(res.pay_amount_cents) : null,
+      /** 微信侧的支付链接：**保留给自动化**，但人看的流程走 pay_url（下面那行） */
+      code_url: (res && res.code_url) || null,
+      /** ★ 收银台地址：人点它、自动化也可以直接开它 */
+      pay_url: payUrl,
+      expires_at_minutes: (res && res.expires_at_minutes) || null,
+      wallet_paid_cents: Number((res && res.wallet_paid_cents) || 0),
+      open_browser: { attempted: false, opened: false, tried: [], url: payUrl || '', skipped_reason: null },
+      /** ★ 给 AI 端"照着念"的一句话（下面 openUrlForUser 之后会按实际情况覆盖） */
+      paste_text: payUrl ? browserPasteText(payUrl, { kind: 'pay' }) : null,
+    };
+
+    /**
+     * 自动打开收银台。
+     *
+     * ⚠️ 复用 `login.mjs` 的 `openUrlForUser`（多策略 + 结果归一化 + ★「默认总是尝试打开」闸门），
+     *    **不是**在这里再写一份 spawn —— 那几个坑（cmd start 的引号、URL 里的 `&`
+     *    被 shell 吃掉、error 事件没挂）在那边已经踩过并修过，复制一份必然会再踩。
+     * ⚠️ 打开失败**绝不允许**让命令失败：地址已经完整打印（人类可读）并放在
+     *    `--json` 的 `pay_url` 里，手动复制照样能完成支付。
+     * ⚠️ 闸门在 `openUrlForUser` **内部**：这里不再自己判断"要不要开"（除了 payUrl 有没有），
+     *    否则总有一天会出现"授权不弹、支付还弹"。
+     */
+    if (payUrl) {
+      data.open_browser = await openUrlForUser(payUrl, {
+        deps: {
+          openBrowser: ctx.openBrowser,
+          spawnImpl: ctx.spawnImpl,
+          platform: ctx.platform,
+          verbose: !!(ctx.config && ctx.config.verbose),
+          /** ★ 与 login 同源的四个事实（见 login.mjs 的 resolveBrowserIntent） */
+          isTTY: ctx.isTTY === true,
+          json: out.json === true,
+          forceOpen: flags.openBrowser === true,
+          noBrowser: flags.noBrowser === true,
+        },
+        log: (m) => out.info(m),
+      });
+      data.paste_text = browserPasteText(payUrl, { kind: 'pay' });
+    }
+
+    if (!out.json) {
+      out.head('充值订单已创建');
+      out.line(`  订单号：${data.order_id}`);
+      out.line(`  金额：${data.amount_text}`);
+      out.line(`  有效期：${data.expires_at_minutes ?? '?'} 分钟`);
+      if (payUrl) {
+        out.line('');
+        out.line('  收银台（我们网站的充值页面，请在这里扫码支付）：');
+        out.line(`  ${payUrl}`);
+        if (flags.noBrowser === true) {
+          out.info('  （已按 --no-browser 跳过自动打开）请把上面这一整行复制到浏览器地址栏打开。');
+        } else if (data.open_browser.opened) {
+          // ★ 成功：明说"已经打开了"（老板最终拍板走传统路线：弹系统浏览器）
+          out.line(browserOpenedText({ kind: 'pay' }));
+        } else {
+          /**
+           * 打开失败：与 login 同一段文案（`browserFailedHintLines`）——
+           *   1. **醒目**：说清"没能自动打开"，别让用户以为还在打开中；
+           *   2. **可操作**：把**完整地址再打一遍**，并说清动作是"复制→粘贴到地址栏"；
+           *   3. 说清打开之后干什么（用微信扫码）。
+           */
+          for (const line of browserFailedHintLines(payUrl, { kind: 'pay', agent: ctx.isTTY !== true })) {
+            out.line(line);
+          }
+        }
+
+        /**
+         * ★ 2026-10-02（老板）：**支付完成之后那个页面会自己关掉** —— 提前交代一句。
+         *   为什么要说：页面"自己没了"时，用户第一反应是"是不是崩了 / 是不是没付成功"；
+         *   提前说一句，这件事就变成"预期之内"。
+         *   ⚠️ 后半句"没关就手动关掉即可"**不能省**：`window.close()` 只对**脚本打开的**窗口
+         *      有效，收银台是导航过去的 ⇒ **大概率关不掉**（详见
+         *      `admin-web/src/pages/billing/pay` 的「尝试自动关闭」注释）。
+         */
+        out.info('（支付成功后页面会自动尝试关闭；没关就手动关掉即可。）');
+
+        /**
+         * 终端二维码：**只在网页打不开时**作为兜底。
+         * ⚠️ 老板明确否掉了"本地生成二维码让别人扫"当**主流程**的做法：
+         *    二维码只是收银台页面内部的一个展示件；终端里画码这条路必须降级，
+         *    而且要说清"正常应该在我们网站的收银台页面上扫"。
+         */
+        const browserNotOpened = data.open_browser.attempted && !data.open_browser.opened;
+        if (browserNotOpened && data.code_url) {
+          out.line('');
+          out.info('  兜底：网页确实打不开时，也可以直接用微信扫下面这个二维码。');
+          out.info('  （正常流程请在上面那个收银台页面里扫码支付。）');
+          const qrShown = await renderQrOptional(data.code_url, out);
+          if (!qrShown) {
+            out.info('  （未安装可选的 qrcode-terminal，无法在终端画码；请用上面的收银台地址付款）');
+          }
+        }
+        out.line('');
+        out.line(`  支付完成后运行：wkgeo orders check ${data.order_id}   # 查支付结果与最新余额`);
+      } else if (data.code_url) {
+        out.warn('没有拼出收银台地址（订单号缺失），只能给出微信支付链接');
+        out.line(`  ${data.code_url}`);
+      } else {
+        out.warn('服务端没有返回 code_url（可能微信支付参数未配置），请到网页后台核对');
+      }
+      out.info('  CLI 不会替你付款，也不会模拟支付成功。');
+    } else if (payUrl) {
+      /**
+       * ★ `--json` / 非 TTY 时，**人看的那段提示不能消失**：走 stderr（`out.notice`），
+       *   stdout 依然只有机器可读 JSON；结构化字段（`pay_url` / `paste_text` / `open_browser`）
+       *   照样都在 stdout 里。
+       *
+       * ★ 老板最终拍板走传统路线后，这里的分支变成"如实播报结果"：
+       *   * `--no-browser` → 明说跳过了（地址仍要打印，用户得能复制）；
+       *   * 打开成功      → 说一句"已为你打开浏览器"；
+       *   * 打开失败      → ⚠️ 那段**含完整地址**的醒目提示（AI 端/用户就靠它手动打开）。
+       *     ⚠️ 失败提示**不能只给 JSON**：真客户不会去 `pay_url` 字段里翻地址。
+       */
+      if (flags.noBrowser === true) {
+        out.notice('（已按 --no-browser 跳过自动打开）请手动复制 pay_url 到浏览器地址栏打开。');
+      } else if (data.open_browser.opened) {
+        out.notice(browserOpenedText({ kind: 'pay' }));
+      } else {
+        for (const line of browserFailedHintLines(payUrl, { kind: 'pay', agent: true })) out.notice(line);
+      }
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* wallet recharge-link（独立充值页）                                   */
+/* ------------------------------------------------------------------ */
+
+/**
+ * `wallet recharge-link` —— 生成**独立充值页**链接（AI/CLI 把链接交给用户）。
+ *
+ * ## 与 `wallet recharge` 的分工（★ 两条路都存在，别搞混）
+ *   * `wallet recharge --amount-cents`：**金额在命令行里定死**，CLI 直接建单，
+ *     再打开收银台扫码。适合"用户已经说了充 100 块"的场景。
+ *   * `wallet recharge-link`（本命令）：**不建单、不定金额**，只换一张一次性 ticket
+ *     并给出链接。用户在**收银台站的独立充值页**上自己选金额（¥10 / ¥20 快捷，
+ *     或自定义；最低 ¥9.90、**不设上限**），提交后由那一页建单并跳到收银台。
+ *     老板原话：「我们希望是有一个页面，然后呢直接选择金额，选择支付就行了……
+ *     他先选择金额之后，先创建订单，然后再跳到收银台，**不能说是登录到管理员账号里面再去支付**。」
+ *
+ * ⚠️ 本命令**不改** `wallet recharge` 的任何行为与参数（那条路已上线，脚本依赖它）。
+ *
+ * ## 默认**不**自动打开浏览器（与 `wallet recharge` 的默认相反，这是刻意的）
+ *   这条命令的典型调用者是 **AI**：它要把链接**交给用户**（发在对话里 / 做成可点的卡片），
+ *   而 CLI 往往跑在**服务器 / 容器**里 —— 在那里弹一个浏览器既弹不出来、也没有意义。
+ *   所以默认只打印链接；真要打开就显式 `--open-browser`（走 `login.mjs` 那套既有实现，
+ *   不在这里另写一份 spawn）。`--no-browser` 优先级最高（关掉就是关掉）。
+ *
+ * ## 一句话交接物
+ *   `data.pay_url`（`--json` 里也有）+ `data.paste_text`（给 AI 照着念的那句）。
+ *   ⚠️ **绝不能**把长期 OAuth 令牌放进这个地址：地址里的 `ticket` 是一次性的、
+ *   10 分钟失效、只能建一笔充值单（见 `buildRechargeTicketUrl()` 的说明）。
+ */
+export const walletRechargeLinkCommand = {
+  name: 'wallet recharge-link',
+  summary:
+    '生成「独立充值页」链接：用户在收银台上**自己选金额**并支付（无需登录会员中心；不扣款）',
+  usage: 'wkgeo wallet recharge-link [--open-browser] [--no-browser]',
+  flags: {
+    'open-browser': {
+      type: 'boolean',
+      desc: '在系统浏览器里打开这个链接（**默认不打开**：本命令的交接物是链接本身，给 AI/用户用）',
+    },
+    'no-browser': {
+      type: 'boolean',
+      desc: '明确不打开浏览器（优先于 --open-browser；默认行为本来就不打开）',
+    },
+  },
+  async run(ctx) {
+    const { out, flags } = ctx;
+
+    /**
+     * ⚠️ 这一步会**在库里插一行一次性凭证**（10 分钟后自动失效，无副作用、不花钱）。
+     *    它**不会**建订单、不会调微信、不会扣款 —— 建单发生在用户提交充值页表单的那一刻。
+     */
+    const res = await ctx.callData('createRechargeTicket', {});
+    const ticket = res && res.ticket ? String(res.ticket) : '';
+    if (!ticket) {
+      throw new CliError(
+        '服务端没有返回一次性凭证（ticket）—— 可能 data 云函数还没部署到支持「独立充值页」的版本。',
+      );
+    }
+
+    /**
+     * 收银台基址：与 `wallet recharge` 同源（`config.payWebBase`，老配置对象兜底 `webBase`）。
+     * 联调时 `WKONGAI_WEB_BASE` 这个**总覆盖**会把两者设成同一个值。
+     */
+    const payUrl = buildRechargeTicketUrl(
+      ctx.config && (ctx.config.payWebBase || ctx.config.webBase),
+      ticket,
+    );
+
+    /**
+     * 「照着念」的那句话 —— **按"有没有真的打开浏览器"分两种**（见下面 `paste_text` 的说明）。
+     *
+     * @param {boolean} opened 只在**确实打开成功**时传 true
+     */
+    const handoffText = (opened) => {
+      if (!payUrl) return null;
+      if (opened) return browserPasteText(payUrl, { kind: 'pay' });
+      return `充值链接（10 分钟内有效、一次性，用户在网页上自己选金额）：${payUrl}`;
+    };
+
+    const data = {
+      ticket,
+      /** ★ 交接物：发给用户的充值链接（他打开后自己选金额） */
+      pay_url: payUrl,
+      expires_at: (res && res.expires_at) || null,
+      expires_at_minutes: (res && res.expires_at_minutes) || 10,
+      /** 默认不打开；只有显式 `--open-browser` 才会改成 attempted/opened 的实况 */
+      open_browser: {
+        attempted: false,
+        opened: false,
+        tried: [],
+        url: payUrl || '',
+        skipped_reason: flags.noBrowser === true ? 'no_browser' : null,
+      },
+      /**
+       * 给 AI"照着念"的一句话。
+       *
+       * ⚠️ **只有真打开了浏览器**才能说"已为你打开浏览器"（`browserPasteText` 那句就是这么说
+       *    的）—— 本命令默认**不打开**，默认那句必须是"链接在这儿，你发给用户"。
+       *    否则 AI 会把"已为你打开浏览器"原样转述给用户，而用户机器上什么都没弹出来，
+       *    他会以为链接坏了（这正是 login/wallet recharge 那边反复修过的文案坑）。
+       */
+      paste_text: handoffText(false),
+      /**
+       * 本命令默认**不弹浏览器**（理由见上面那段注释），所以额外给一句**机器可读**的口径，
+       * 免得 AI 把 `skipped_reason: null` 误读成"我们试过但没打开"。
+       */
+      open_browser_default_off: true,
+    };
+
+    /**
+     * 打开浏览器：**只有显式 `--open-browser` 才走这里**。
+     * ⚠️ 仍然复用 `openUrlForUser`（多策略 + `resolveBrowserIntent` 闸门 + 结果归一化），
+     *    不在这里另写一份 spawn —— 那几个坑（cmd start 的引号、URL 里的 `&` 被 shell 吃掉、
+     *    error 事件没挂）在那边已经踩过并修过。
+     * ⚠️ 打开失败**绝不允许**让命令失败：链接已经打印出来，手动复制照样能完成充值。
+     */
+    if (payUrl && flags.openBrowser === true) {
+      data.open_browser = await openUrlForUser(payUrl, {
+        deps: {
+          openBrowser: ctx.openBrowser,
+          spawnImpl: ctx.spawnImpl,
+          platform: ctx.platform,
+          verbose: !!(ctx.config && ctx.config.verbose),
+          /** 与 login / wallet recharge 同源的四个事实（见 resolveBrowserIntent） */
+          isTTY: ctx.isTTY === true,
+          json: out.json === true,
+          forceOpen: true,
+          noBrowser: flags.noBrowser === true,
+        },
+        log: (m) => out.info(m),
+      });
+      // ⚠️ 只有**确实打开了**才换成"已为你打开浏览器…"那句（否则与用户的屏幕对不上）
+      data.paste_text = handoffText(data.open_browser.opened === true);
+    }
+
+    if (!out.json) {
+      out.head('独立充值页链接已生成');
+      out.line(`  有效期：${data.expires_at_minutes} 分钟（一次性，用掉即失效）`);
+      out.line('');
+      out.line('  充值链接（用户在网页上自己选金额后支付）：');
+      out.line(`  ${payUrl}`);
+      out.line('');
+      out.info('  把上面这一整行发给用户：他打开后选金额（最低 ¥9.90，不设上限）→ 微信扫码支付。');
+      out.info('  （不需要登录会员中心；本命令不会代替他付款，也不会模拟支付成功。）');
+      if (flags.noBrowser === true) {
+        out.info('  （已按 --no-browser 跳过自动打开）');
+      } else if (data.open_browser.attempted === false) {
+        out.info('  （默认不自动打开浏览器；需要在这台机器上弹出，请加 --open-browser）');
+      } else if (data.open_browser.opened) {
+        out.line(browserOpenedText({ kind: 'pay' }));
+      } else {
+        for (const line of browserFailedHintLines(payUrl, { kind: 'pay', agent: ctx.isTTY !== true })) {
+          out.line(line);
+        }
+      }
+    } else {
+      /**
+       * ⚠️ `--json` / 非 TTY（AI 场景）下，**人看的那段提示不能消失**：走 stderr（`out.notice`），
+       *    stdout 依然只有机器可读 JSON。AI 端就靠这段（含完整地址）把链接转述给用户。
+       */
+      out.notice(`充值链接（${data.expires_at_minutes} 分钟内有效、一次性）：${payUrl}`);
+      if (flags.openBrowser !== true) {
+        out.notice(
+          '（默认不自动打开浏览器；需要在这台机器上弹出请加 --open-browser。把上面的链接发给用户即可。）',
+        );
+      } else if (data.open_browser.opened) {
+        out.notice(browserOpenedText({ kind: 'pay' }));
+      } else {
+        for (const line of browserFailedHintLines(payUrl, { kind: 'pay', agent: true })) {
+          out.notice(line);
+        }
+      }
+    }
+
+    ctx.done(data);
+    return data;
+  },
+};