trustbase-seller-backend 0.2.4 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trustbase-seller-backend",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "TrustBase Seller Backend (merchant edition) — 商品上链/订单/支付/质押 write API for TrustBase 保障链生态. 单卖家自托管形态: 签名 key 即卖家身份, 私钥不出门.",
   "main": "run-unified.js",
   "bin": {

package/payments/wechat/profitsharing.js

@@ -14,6 +14,7 @@
  *           且 ≤ 交易金额本身; 护栏在 mock 模式同样生效 (先于一切网络调用)。
  */
 const agentPay = require("../../routes/agent-pay");
+const crypto = require("crypto");
 
 const MAX_SHARE_BP = 3000; // 单笔分账 ≤ 交易金额 30% (硬顶)
 
@@ -51,6 +52,8 @@ async function wxCall(method, urlPath, bodyObj) {
             "Accept": "application/json",
             // 微信 APIv3 拒 undici 默认 Accept-Language: * (2026-09-25 实测 PARAM_ERROR) — 与 agent-pay wxApiCall 对齐
             "Accept-Language": "zh-CN",
+            // 分账等接口要求微信支付公钥 ID/平台证书序列号头 (2026-09-26 实测 PARAM_ERROR); SP 模式用 SP 公钥 ID
+            "Wechatpay-Serial": process.env.WXPAY_SP_PUBLIC_KEY_ID || process.env.WXPAY_PUBLIC_KEY_ID || c.spSerial || c.serial || "",
             "User-Agent": "trustbase-seller-backend/1.0",
         },
         body: method === "GET" ? undefined : bodyStr,
@@ -78,7 +81,8 @@ function assertShareAmount(tradeAmount, shareAmount) {
 }
 
 /** 添加分账接收方 (服务商自己 mchid 或指定商户号)
- *  receivers: [{account, type?, name?, relation_type?, sub_mchid?}] */
+ *  receivers: [{account, type?, name?, relation_type?, sub_mchid?}]
+ *  2026-09-26 实测: name 是敏感字段, 真调必须微信支付公钥 RSA-OAEP 加密 (否则 PARAM_ERROR "是否为加密后的密文") */
 async function addReceivers(receivers) {
     const c = wxCfg();
     const list = Array.isArray(receivers) ? receivers : [receivers];
@@ -92,7 +96,7 @@ async function addReceivers(receivers) {
             account: String(rcv.account),
             relation_type: rcv.relation_type || "SERVICE_PROVIDER",
         };
-        if (rcv.name) body.name = String(rcv.name); // MERCHANT_ID 真调时微信要求 name
+        if (rcv.name) body.name = c.enabled ? encryptReceiverName(String(rcv.name)) : String(rcv.name); // MERCHANT_ID 真调时微信要求 name (加密)
         if (c.spMchid) {
             body.sp_mchid = c.spMchid;
             if (rcv.sub_mchid) body.sub_mchid = String(rcv.sub_mchid);
@@ -103,6 +107,21 @@ async function addReceivers(receivers) {
     return results.length === 1 ? results[0] : results;
 }
 
+/** 接收方名称加密: 微信支付公钥 RSA-OAEP → base64。
+ *  ⚠️ 2026-09-26 实测坑: 微信"OAEPWithSHA-256AndMGF1Padding"是 Java 语义 — MGF1 实际用 SHA-1。
+ *  Node crypto.publicEncrypt 的 oaepHash 会把 OAEP+MGF1 都设成同一 hash → 微信"平台私钥解密失败"。
+ *  必须用 openssl 子进程分开指定 (rsa_oaep_md:sha256 + rsa_mgf1_md:sha1)。 */
+function encryptReceiverName(name) {
+    const p = process.env.WXPAY_SP_PUBLIC_KEY_PATH || process.env.WXPAY_PUBLIC_KEY_PATH;
+    if (!p) throw new Error("WXPAY_(SP_)PUBLIC_KEY_PATH 未配置, 接收方名称无法加密");
+    const { execSync } = require("child_process");
+    const b64 = execSync(
+        `openssl pkeyutl -encrypt -pubin -inkey ${JSON.stringify(p)} -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha1 | base64 -w0`,
+        { input: Buffer.from(name, "utf8"), maxBuffer: 1024 * 1024 }
+    ).toString("utf8").trim();
+    return b64;
+}
+
 /** 请求分账
  *  params: {outTradeNo(分账单号 out_order_no, 幂等键), transactionId(微信支付单号),
  *           tradeAmount(交易金额分, 护栏基准), subMchid?, unfreezeUnsplit?,
@@ -169,13 +188,15 @@ async function registerDefaultReceivers(db) {
         console.warn("[profitsharing] 未配 WXPAY_SP_MCHID/WXPAY_MCHID, 跳过接收方注册");
         return { registered: false, reason: "no_mchid" };
     }
-    const row = db.prepare("SELECT account FROM sp_ps_receivers WHERE account = ?").get(account);
-    if (row) return { registered: false, reason: "already" };
+    const row = db.prepare("SELECT account, mock FROM sp_ps_receivers WHERE account = ?").get(account);
+    // mock 落行不挡真调: mock=1 且当前真调模式 → 重新真调注册 (2026-09-26 实测: mock 期落的行把真调永久挡死)
+    const realMode = /^(1|true|yes|on)$/i.test(process.env.WXPAY_PROFITSHARING_ENABLED || "");
+    if (row && !(row.mock && realMode)) return { registered: false, reason: "already" };
     const r = await addReceivers([{ account, type: "MERCHANT_ID", name: process.env.SP_NAME || "服务商" }]);
     const one = Array.isArray(r) ? r[0] : r;
     const ok = !!(one && (one.mock || one.status === 200));
     if (ok) {
-        db.prepare("INSERT OR IGNORE INTO sp_ps_receivers (account, registered_at, mock) VALUES (?,?,?)")
+        db.prepare("INSERT INTO sp_ps_receivers (account, registered_at, mock) VALUES (?,?,?) ON CONFLICT(account) DO UPDATE SET registered_at=excluded.registered_at, mock=excluded.mock")
             .run(account, Math.floor(Date.now() / 1000), one.mock ? 1 : 0);
         console.log(`[profitsharing] 分账接收方已注册 account=${account} mock=${!!one.mock}`);
         return { registered: true, mock: !!one.mock };

package/routes/agent-pay.js

@@ -5,8 +5,14 @@
  * 职责:
  *   POST /api/agent/pay/session        E1 支付会话 (幂等/服务端报价/软持有/双token/PSP下单)
  *   POST /api/agent/pay/notify/wechat  E2 微信回调 (APIv3 验签+AES-GCM 解密+查重+金额核对+落账链)
+ *                                      M4: TRANSACTION.REFUND 退款事件 → REFUNDED
  *   POST /api/agent/pay/mock-pay       mock 沙箱 (仅 AGENT_PAY_MODE=mock, 模拟PSP回调)
- *   GET  /api/agent/order/status       状态查询 (session权威 + 链事实镜像)
+ *   GET  /api/agent/order/status       状态查询 (session权威 + 链事实镜像; M4: DISPUTED/REFUNDED 不再误映射 PAID, rail 真实值)
+ *   POST /api/agent/order/confirm      M4 买家确认收货 (DELIVERED→CONFIRMED, status_token 即买家凭证)
+ *   POST /api/agent/internal/logistics M4 物流推送 (HMAC 共享密钥头 x-logistics-key 鉴权, env LOGISTICS_HMAC_KEY;
+ *                                      状态机单向 PAID/ON_CHAIN→SHIPPED→DELIVERED, timeline 追加不覆盖)
+ *   M4 状态机: ON_CHAIN 由 markOrderOnChain() 回写 (链上建单需买家 tct1, 匿名法币单留 PAID 不强上链);
+ *   status_token 丢失暂无法自助找回 (🔵 后续), 需人工。
  *   对账轮询 E3: reconcileSweep() 由外层定时调用
  *
  * 设计依据: prd-docs/开发文档/trustbase-agent-commerce-协议方案-2026-09-20.md
@@ -384,7 +390,9 @@ function createAgentPayRouter(deps) {
         const acceptExpired = prevState === "EXPIRED" && (Date.now() / 1000) < sessionRow.expires_at + GRACE_AFTER_EXPIRY_MS / 1000;
         db.prepare("UPDATE agent_pay_sessions SET state='PAID', psp_txn_id=?, updated_at=? WHERE id=?").run(txnId, now, sessionRow.id);
         console.log(`[agent-pay] PAID ${sessionRow.order_ref} txn=${txnId} rail=${rail}${acceptExpired ? " (expired+grace accepted)" : ""}`);
-        // 触发既有链同步与 C5 申报 → 由插件 hook 侧/后续 E6 接线; 此处先置状态。
+        // M4: PAID → ON_CHAIN 占位 — 链上建单需买家 tct1 地址, 匿名法币单不强上链
+        // (链上订单是增强不是阻塞)。当前会话不存买家地址 (agent_addr 是归因哈希),
+        // 链上建单接线后由 markOrderOnChain(db, orderRef, chainOrderId) 回写 state/chain_order_id。
         return { ok: true, state: "PAID", grace: acceptExpired };
     }
 
@@ -427,6 +435,21 @@ function createAgentPayRouter(deps) {
                 return res.status(400).json({ code: "FAIL", message: "no resource" });
             }
             const plain = wxDecryptNotifyResource(resource);
+            // M4: 退款事件 (TRANSACTION.REFUND) — resource 是退款单 (refund_status), 不是支付单
+            if (body.event_type === "TRANSACTION.REFUND") {
+                const outRef = plain.out_trade_no;
+                const rRow = outRef && db.prepare("SELECT * FROM agent_pay_sessions WHERE order_ref = ?").get(outRef);
+                if (!rRow) return res.status(404).json({ code: "FAIL", message: "NOT_FOUND" });
+                if (plain.refund_status === "SUCCESS") {
+                    if (rRow.state !== "REFUNDED") {
+                        db.prepare("UPDATE agent_pay_sessions SET state='REFUNDED', updated_at=? WHERE id=?").run(nowSec(), rRow.id);
+                        console.log(`[agent-pay] REFUNDED ${outRef} refund_id=${plain.refund_id || ""}`);
+                    }
+                    return res.status(200).json({ code: "SUCCESS", refunded: true });
+                }
+                // 退款处理中/异常: 确认收到不改状态
+                return res.status(200).json({ code: "SUCCESS", ignored: plain.refund_status || "REFUND_PROCESSING" });
+            }
             const out = plain.out_trade_no;
             const row = out && db.prepare("SELECT * FROM agent_pay_sessions WHERE order_ref = ?").get(out);
             if (!row) return res.status(404).json({ code: "FAIL", message: "NOT_FOUND" });
@@ -454,7 +477,9 @@ function createAgentPayRouter(deps) {
         res.json(r.error ? r : { ok: true, state: r.state, grace: !!r.grace });
     });
 
-    /** 状态查询 (E4 后端部分: session 权威 + 链事实镜像) */
+    /** 状态查询 (E4 后端部分: session 权威 + 链事实镜像)
+     *  M4 修正: payment.state 不再把 DISPUTED/REFUNDED 误映射成 PAID; rail 取真实支付轨
+     *  (psp_txns 最新一条的 rail, 未支付回落 MODE)。 */
     router.get("/order/status", (req, res) => {
         const q = req.query || {};
         const row = db.prepare("SELECT * FROM agent_pay_sessions WHERE order_ref = ?").get(q.order_ref);
@@ -463,10 +488,16 @@ function createAgentPayRouter(deps) {
         const chain = row.chain_order_id
             ? db.prepare("SELECT txhash FROM chain_write_log WHERE order_id = ?").get(row.chain_order_id)
             : null;
+        // payment.state 映射: 已支付族 → PAID; 其余原样 (UNPAID/DISPUTED/REFUNDED/CLOSED)
+        const PAID_STATES = ["PAID", "ON_CHAIN", "SHIPPED", "DELIVERED", "CONFIRMED"];
+        const payState = PAID_STATES.includes(row.state) ? "PAID"
+            : (row.state === "CREATED" || row.state === "EXPIRED" ? "UNPAID" : row.state);
+        // rail 真实值: psp_txns 最新一条; 未支付 → 当前 MODE
+        const txn = db.prepare("SELECT rail FROM psp_txns WHERE session_id = ? ORDER BY created_at DESC LIMIT 1").get(row.id);
         res.json({
             order_ref: row.order_ref, chain_order_id: row.chain_order_id || null,
             state: row.state,
-            payment: { state: row.state === "CREATED" || row.state === "EXPIRED" ? "UNPAID" : "PAID", rail: "mock", txn_id: row.psp_txn_id || null },
+            payment: { state: payState, rail: txn ? txn.rail : MODE, txn_id: row.psp_txn_id || null },
             amount: { currency: row.currency, total: row.amount_total },
             agent_addr: row.agent_addr || null,
             chain_tx: chain ? chain.txhash : null,
@@ -481,28 +512,72 @@ function createAgentPayRouter(deps) {
         res.json({ ok: !r.error, ...r });
     });
 
-    /** E4': 物流推送接收 (ShopXO 发货 hook → 这里; PoC LAN 无鉴权, order_ref 为主键) */
+    /** E4': 物流推送接收 (ShopXO 发货 hook → 这里)
+     *  M4 (2026-10-03): ① 鉴权修复 — env LOGISTICS_HMAC_KEY 共享密钥头 (x-logistics-key)
+     *  比对, 未配置 env 全拒 (PoC 裸奔是审查 🔴); ② 状态机单向 — PAID/ON_CHAIN→SHIPPED,
+     *  SHIPPED→SHIPPED(更新)/DELIVERED, DELIVERED→DELIVERED(幂等), 回退 409;
+     *  ③ timeline 追加不覆盖。 */
+    function logisticsAuthed(req) {
+        const key = process.env.LOGISTICS_HMAC_KEY || "";
+        if (!key) return false; // 未配置 = 全拒 (宁可全拒不留后门)
+        const got = String(req.headers["x-logistics-key"] || "");
+        if (!got || got.length !== key.length) return false;
+        return crypto.timingSafeEqual(Buffer.from(got), Buffer.from(key));
+    }
     router.post("/internal/logistics", (req, res) => {
         try {
+            if (!logisticsAuthed(req)) {
+                return err(res, 401, "LOGISTICS_UNAUTHORIZED", { hint: "x-logistics-key 头缺失或错误 (env LOGISTICS_HMAC_KEY)" });
+            }
             const b = req.body || {};
             if (!b.order_ref) return err(res, 400, "order_ref 必填 (E6 后自动写入 ShopXO 订单备注, 当前由插件穿参)");
             const row = db.prepare("SELECT * FROM agent_pay_sessions WHERE order_ref = ?").get(b.order_ref);
             if (!row) return err(res, 404, "NOT_FOUND");
             const now = nowSec();
-            // 状态机: 仅 PAID/ON_CHAIN 可转 SHIPPED
-            if (!["PAID", "ON_CHAIN", "SHIPPED", "DELIVERED"].includes(row.state)) {
-                return err(res, 409, "STATE_INVALID", { current: row.state });
+            const cur = row.state;
+            const target = String(b.logistics_state || "SHIPPED") === "DELIVERED" ? "DELIVERED" : "SHIPPED";
+            // 单向状态机 (回退拒):
+            const allowed =
+                ((cur === "PAID" || cur === "ON_CHAIN") && target === "SHIPPED") ||
+                (cur === "SHIPPED" && (target === "SHIPPED" || target === "DELIVERED")) ||
+                (cur === "DELIVERED" && target === "DELIVERED");
+            if (!allowed) {
+                return err(res, 409, "STATE_INVALID", { current: cur, target, hint: "状态机单向: PAID/ON_CHAIN→SHIPPED→DELIVERED, 不允许回退" });
             }
-            db.prepare("UPDATE agent_pay_sessions SET state='SHIPPED', carrier=?, tracking_no=?, logistics_state=?, timeline=?, shopxo_order_no_ref=?, updated_at=? WHERE id=?")
-                .run(String(b.carrier || ""), String(b.tracking_no || ""), String(b.logistics_state || "SHIPPED"), JSON.stringify(b.timeline || []), String(b.shopxo_order_no || ""), now, row.id);
-            console.log(`[agent-pay] SHIPPED ${b.order_ref} carrier=${b.carrier} tracking=${b.tracking_no}`);
-            res.json({ ok: true, state: "SHIPPED" });
+            // timeline 追加不覆盖 (M4 修复: 旧实现整体覆盖丢历史)
+            const timeline = JSON.parse(row.timeline || "[]").concat(Array.isArray(b.timeline) ? b.timeline : []);
+            db.prepare("UPDATE agent_pay_sessions SET state=?, carrier=?, tracking_no=?, logistics_state=?, timeline=?, shopxo_order_no_ref=?, updated_at=? WHERE id=?")
+                .run(target, String(b.carrier || row.carrier || ""), String(b.tracking_no || row.tracking_no || ""),
+                    target, JSON.stringify(timeline), String(b.shopxo_order_no || row.shopxo_order_no_ref || ""), now, row.id);
+            console.log(`[agent-pay] ${target} ${b.order_ref} carrier=${b.carrier} tracking=${b.tracking_no}`);
+            res.json({ ok: true, state: target });
         } catch (e) {
             console.error("[agent-pay] logistics error:", e && e.message);
             err(res, 500, "internal");
         }
     });
 
+    /** M4: 买家确认收货 (DELIVERED → CONFIRMED) — status_token 即买家凭证 (买家在卖家后端
+     *  无账号体系, status_token 是签收时签发的唯一凭证; 丢失暂无法自助找回, 需人工 (🔵 后续)) */
+    router.post("/order/confirm", (req, res) => {
+        try {
+            const b = req.body || {};
+            const row = db.prepare("SELECT * FROM agent_pay_sessions WHERE order_ref = ?").get(b.order_ref);
+            if (!row) return err(res, 404, "NOT_FOUND");
+            if (sha256(String(b.token || "")) !== row.status_token_hash) return err(res, 401, "TOKEN_INVALID");
+            if (row.state === "CONFIRMED") return res.json({ ok: true, state: "CONFIRMED", idempotent: true });
+            if (row.state !== "DELIVERED") {
+                return err(res, 409, "STATE_INVALID", { current: row.state, expect: "DELIVERED", hint: "买家确认收货仅允许 DELIVERED → CONFIRMED" });
+            }
+            db.prepare("UPDATE agent_pay_sessions SET state='CONFIRMED', updated_at=? WHERE id=?").run(nowSec(), row.id);
+            console.log(`[agent-pay] CONFIRMED ${row.order_ref} (买家确认收货)`);
+            res.json({ ok: true, state: "CONFIRMED" });
+        } catch (e) {
+            console.error("[agent-pay] confirm error:", e && e.message);
+            err(res, 500, "internal");
+        }
+    });
+
     /** E-ONBOARD: 商家入驻提交 */
     router.post("/onboard/submit", (req, res) => {
         try {
@@ -563,4 +638,15 @@ function startReconcile(db) {
     return timer;
 }
 
-module.exports = { createAgentPayRouter, startReconcile, runReconcileOnce, wxSignAuth, wxAesGcmDecrypt, wxVerifyNotifySignature, wxDecryptNotifyResource, wxNativeOrder, wxQueryOrder, refreshPlatformCerts };
+/** M4: PAID → ON_CHAIN 回写 (链上建单成功后由后续批次调用; 仅 PAID 可转, 幂等键 chain_order_id) */
+function markOrderOnChain(db, orderRef, chainOrderId) {
+    const row = db.prepare("SELECT * FROM agent_pay_sessions WHERE order_ref = ?").get(orderRef);
+    if (!row) return { ok: false, error: "NOT_FOUND" };
+    if (row.state === "ON_CHAIN") return { ok: true, state: "ON_CHAIN", idempotent: true };
+    if (row.state !== "PAID") return { ok: false, error: "STATE_INVALID", current: row.state };
+    db.prepare("UPDATE agent_pay_sessions SET state='ON_CHAIN', chain_order_id=?, updated_at=? WHERE id=?")
+        .run(String(chainOrderId), nowSec(), row.id);
+    return { ok: true, state: "ON_CHAIN" };
+}
+
+module.exports = { createAgentPayRouter, startReconcile, runReconcileOnce, markOrderOnChain, wxSignAuth, wxAesGcmDecrypt, wxVerifyNotifySignature, wxDecryptNotifyResource, wxNativeOrder, wxQueryOrder, refreshPlatformCerts };

package/routes/onboard.html

@@ -122,7 +122,7 @@ img.auprev{display:none;width:100%;max-height:140px;object-fit:cover;border-radi
 <body>
 <div class="wrap">
 <h1>TrustBase 商家入驻</h1>
-<p class="sub">在你的电脑上完成入驻，密钥永不出门</p>
+<p class="sub">在你的电脑上完成入驻，安全词永不出门</p>
 
 <div class="spcard" id="spcard" style="display:none">
   <div class="spcard-h"><span>🏪</span><span id="sp-name" style="font-weight:600">服务商</span><span class="spbadge" id="sp-rate" style="display:none"></span></div>
@@ -134,14 +134,25 @@ img.auprev{display:none;width:100%;max-height:140px;object-fit:cover;border-radi
 <h3>入驻进度 <span id="status-meta" style="font-size:12px;color:#8A857B;font-weight:400"></span><button class="sbtn noprint" style="float:right;margin-top:-2px" onclick="loadStatus()">刷新状态</button></h3>
 <div class="step done" id="st-identity">
   <span class="mark">✅</span>
-  <div class="body">① 卖家身份 <span id="p-addr" style="font-family:Consolas,monospace;font-size:12px"></span><div class="desc">密钥只保存在这台电脑</div></div>
+  <div class="body">① 卖家身份 <span id="p-addr" style="font-family:Consolas,monospace;font-size:12px"></span><div class="desc">安全卡只保存在这台电脑</div></div>
 </div>
 <div class="step" id="st-backup">
   <span class="mark">⬜</span>
-  <div class="body">② 备份纸密钥
-    <div class="ops"><button class="sbtn" onclick="reprintKey()">重新打印纸密钥</button><button class="sbtn" onclick="var h=document.getElementById('hint-recover');h.style.display=h.style.display==='block'?'none':'block'">如何恢复身份</button></div>
-    <div class="hintbox" id="hint-reprint">出于安全，助记词只在生成时在本页展示一次。<br>重新打印请在你的电脑上运行: <code>npx @trustbase/shopxo-init print-key</code></div>
-    <div class="hintbox" id="hint-recover">丢了/换电脑: 重新安装后把纸上的助记词存入 seller-backend/tb-keyring/mnemonic.txt 即可恢复身份; 店铺数据用安装器的 restore 命令从备份包恢复。</div>
+  <div class="body">② 备份店铺安全卡
+    <div class="desc">安全卡 = 店铺的全部资产钥匙。丢了它且电脑坏了，谁也找不回 (服务商也不行)。请抄写或打印收好。</div>
+    <div class="ops"><button class="sbtn" onclick="reprintKey()">重新打印安全卡</button><button class="sbtn" onclick="var h=document.getElementById('hint-recover');h.style.display=h.style.display==='block'?'none':'block'">如何恢复店铺</button><button class="sbtn primary" onclick="startBackupVerify()">我已抄好, 验证备份</button></div>
+    <div class="hintbox" id="hint-reprint">出于安全，24 个安全词只在生成时在本页展示一次。<br>重新打印请在你的电脑上运行: <code>npx @trustbase/shopxo-init print-key</code></div>
+    <div class="hintbox" id="hint-recover">丢了/换电脑，在新机器的入驻页恢复店铺，两种方式:<br>① 扫码: 用手机相机扫安全卡上的二维码，屏幕上会显示 24 个安全词;<br>② 手填: 把安全卡上的 24 个安全词按顺序填到下面。<br>
+      <textarea id="restore-words" rows="3" placeholder="24 个安全词, 按顺序, 空格分隔" style="width:100%;margin-top:8px;padding:10px 12px;border:1px solid #D4CDBF;border-radius:8px;font-size:14px"></textarea>
+      <button class="sbtn primary" style="margin-top:6px" onclick="restoreIdentity()">恢复店铺</button>
+      <div id="restore-msg" style="font-size:13px;margin-top:6px"></div>
+    </div>
+    <div id="backup-quiz" style="display:none;margin-top:10px;background:#FCFAF4;border:1px solid #EAE3D6;border-radius:12px;padding:14px 16px">
+      <div class="desc" style="margin-bottom:4px">确认你真的抄好了 — 请按安全卡上抄写的填写 (答错不会提示正确答案, 可重新抽题):</div>
+      <div id="backup-questions"></div>
+      <button class="sbtn primary" style="margin-top:10px" onclick="checkBackupVerify()">提交验证</button>
+    </div>
+    <div id="backup-result"></div>
   </div>
 </div>
 <div class="step" id="st-verification">
@@ -315,16 +326,19 @@ img.auprev{display:none;width:100%;max-height:140px;object-fit:cover;border-radi
 
 <div class="keybox" id="keybox">
 <div id="print-area">
-<h3>你的卖家密钥 (这张纸 = 店铺的全部所有权)</h3>
+<h3>你的店铺安全卡 (这张卡 = 店铺的全部资产钥匙)</h3>
 <div class="warn">
-<b>请立即用笔抄写到纸上, 抄两份, 分开放好 (防火防水)。</b><br>
-不要拍照、不要截图、不要发到微信/网盘。谁拿到这串词, 谁就能拿走店铺和里面的资产。
+<b>请立即用笔把 24 个安全词抄写到纸上, 抄两份, 分开放好 (防火防水)。</b><br>
+不要拍照、不要截图、不要发到微信/网盘。谁拿到这 24 个词, 谁就能拿走店铺和里面的资产。
 </div>
+<div id="qr-slot" style="text-align:center;margin:10px 0"><img id="qr-img" alt="安全卡二维码" style="width:190px;height:190px;display:none;margin:0 auto;border:1px solid #EAE3D6;border-radius:8px"><div style="font-size:11px;color:#8A857B;margin-top:4px">换新电脑时, 手机相机扫这个码可读出 24 个安全词</div></div>
 <div class="mn-grid" id="mn-grid"></div>
 <div class="mn-addr" id="mn-addr"></div>
-<div style="font-size:12px;color:#6B655B">丢了/换电脑: 重新安装后用这串助记词恢复身份 (导入 seller-backend/tb-keyring/mnemonic.txt), 或用安装器的 restore 命令恢复。</div>
+<div style="font-size:12px;color:#6B655B">丢了/换电脑: 新机器上点第②步"如何恢复店铺", 扫码或手填 24 个安全词即可找回店铺。</div>
+<div style="font-size:11px;color:#8A857B;margin-top:6px">打印日期: <span id="print-date"></span></div>
 </div>
-<button class="btn noprint" onclick="window.print()">🖨 打印纸密钥</button>
+<button class="btn noprint" onclick="window.print()">🖨 打印安全卡</button>
+<button class="sbtn primary noprint" style="margin-left:8px" onclick="startBackupVerify()">我已抄好, 去验证 →</button>
 <span class="noprint" style="font-size:12px;color:#8A857B;margin-left:10px">打印后请关闭本页; 正式打印通道: 安装器 print-key 命令</span>
 </div>
 </div>
@@ -386,7 +400,7 @@ function renderProgress(s){
   if(meta){
     var bits=[];
     if(s.status_queried_at) bits.push('状态更新于 '+new Date(s.status_queried_at*1000).toLocaleTimeString()+' (每 15 秒自动刷新)');
-    if(s.sign_mode) bits.push('签名通道 '+s.sign_mode+(s.mnemonic_present?'':' · 未找到本机密钥'));
+    if(s.sign_mode) bits.push('签名通道 '+s.sign_mode+(s.mnemonic_present?'':' · 未找到本机安全卡'));
     if(s.keyring_dir) bits.push('密钥目录 '+s.keyring_dir);
     meta.textContent=bits.join(' · ');
   }
@@ -399,8 +413,70 @@ function renderProgress(s){
   } else if(g.status==='approved_pending_disburse'){
     document.getElementById('grant-desc').textContent='认证已通过, 等待发放 (自动)';
   }
-  // 当前可做项高亮
-  document.getElementById('st-backup').className='step current';
+  // 当前可做项高亮 (备份验证已过 → 持久打勾 (后端 tb_backup_ack 台账); 否则标当前可做)
+  if(s.backup_acked){ markStepDone('st-backup'); } else { document.getElementById('st-backup').className='step current'; }
+}
+// ---- 纸密钥备份回填验证 (2026-10-03, MetaMask 式抽词; 原则: mnemonic 不出本机) ----
+// 首次创建 (助记词还在页面内存 _mn) → 纯前端比对, 不调网络;
+// 页面刷新后 → POST /api/onboard/verify-backup 本机后端比对 (只送位置+词, 后端永不返回正确词)。
+var _bqTries=0;
+function startBackupVerify(){
+  // 随机抽 3 个词位 (1-24 不重复, 升序展示)
+  var pool=[]; for(var i=1;i<=24;i++) pool.push(i);
+  var pos=[];
+  while(pos.length<3){ pos.push(pool.splice(Math.floor(Math.random()*pool.length),1)[0]); }
+  pos.sort(function(a,b){return a-b;});
+  var q=document.getElementById('backup-questions');
+  q.innerHTML=pos.map(function(p){
+    return '<label style="display:block;font-size:13px;color:#6B655B;margin:8px 0 4px">请按安全卡上抄写的填写第 '+p+' 个词</label>'
+      +'<input class="bq-word" data-pos="'+p+'" placeholder="第 '+p+' 个词" autocapitalize="off" autocomplete="off" spellcheck="false" style="width:100%;padding:10px 12px;border:1px solid #D4CDBF;border-radius:8px;font-size:15px;background:#fff">';
+  }).join('');
+  document.getElementById('backup-result').innerHTML='';
+  var box=document.getElementById('backup-quiz');
+  box.style.display='block';
+  box.scrollIntoView({behavior:'smooth',block:'center'});
+}
+async function checkBackupVerify(){
+  var inputs=document.querySelectorAll('.bq-word');
+  var positions=[], words=[];
+  inputs.forEach(function(el){ positions.push(Number(el.getAttribute('data-pos'))); words.push(el.value); });
+  if(words.some(function(w){return !w.trim();})) return backupResult(false,'三个词都要填');
+  // ① 内存路径: 助记词还在 (_mn) → 纯前端比对 (更快, 零网络)
+  if(_mn){
+    var real=_mn.split(/\s+/);
+    var wrong=[];
+    positions.forEach(function(p,i){ if(words[i].trim().toLowerCase()!==real[p-1].toLowerCase()) wrong.push(p); });
+    if(!wrong.length){ await persistBackupAck(); return backupOk(); }
+    return backupWrong(wrong);
+  }
+  // ② 后端路径: 刷新后内存没有 → 本机后端比对 (mnemonic 不出本机)
+  try{
+    var j=await readJson(await fetch('/api/onboard/verify-backup',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({positions:positions,words:words})}));
+    if(j.ok) return backupOk();
+    if(j.error==='rate_limited') return backupResult(false, j.message||'30 秒内只能验证一次, 请稍后再试');
+    if(j.wrong_positions&&j.wrong_positions.length) return backupWrong(j.wrong_positions);
+    backupResult(false, j.message||'验证失败, 请稍后再试');
+  }catch(e){ backupResult(false,'服务暂时不可用，请刷新重试 ('+e.message+')'); }
+}
+async function persistBackupAck(){
+  try{ await fetch('/api/onboard/backup-ack',{method:'POST',headers:{'Content-Type':'application/json'},body:'{}'}); }catch(e){}
+}
+function backupOk(){
+  document.getElementById('backup-quiz').style.display='none';
+  markStepDone('st-backup'); // 步骤②打勾 (后端台账已持久化, 换浏览器仍绿)
+  backupResult(true,'✅ 备份已确认 — 你的店铺安全卡只有这一份, 请收好');
+  _bqTries=0;
+}
+function backupWrong(wrong){
+  _bqTries++;
+  var tip='⚠️ 第 '+wrong.join('、')+' 个词不对 — 请对照安全卡检查 (不会提示正确答案), 已重新抽题';
+  if(_bqTries>=3) tip='⚠️ 第 '+wrong.join('、')+' 个词不对; 已错 3 次, 建议点上方"重新打印安全卡"逐词对照后再试';
+  startBackupVerify(); // 重新抽题
+  backupResult(false, tip);
+}
+function backupResult(ok, text){
+  document.getElementById('backup-result').innerHTML=
+    '<div style="'+(ok?'background:#F0FDF4;border:1px solid #BBF7D0;color:#166534':'background:#FEF2F2;border:1px solid #FCA5A5;border-left:4px solid #DC2626;color:#991B1B')+';border-radius:10px;padding:10px 14px;font-size:13px;margin-top:8px;line-height:1.8">'+escHtml(text)+'</div>';
 }
 function reprintKey(){
   if(_mn){
@@ -733,19 +809,53 @@ async function submit(){
     document.getElementById('status').className='status-ok';
     // 2026-09-26 资产安全: 助记词只在首次创建返回; 已有身份时 j.mnemonic 为空
     document.getElementById('status').textContent=j.identity_created===false
-      ? '✅ 卖家身份已存在 (助记词仅首次创建时展示过)'
-      : '✅ 卖家身份已生成 (密钥已保存在本机 tb-keyring/)';
+      ? '✅ 卖家身份已存在 (安全词仅首次创建时展示过)'
+      : '✅ 卖家身份已生成 (安全卡已保存在本机)';
     if(j.mnemonic){
       _mn=j.mnemonic;
       var words=j.mnemonic.split(/\s+/);
       document.getElementById('mn-grid').innerHTML=words.map(function(w,i){return '<div class="mn-word"><span class="n">'+(i+1)+'</span>'+w+'</div>'}).join('');
       document.getElementById('mn-addr').textContent=j.tb_address;
+      document.getElementById('print-date').textContent=new Date().toLocaleDateString('zh-CN');
       document.getElementById('keybox').style.display='block';
+      loadBackupQr(); // 安全卡二维码 (本机 localhost 生成, 不走任何网络)
       document.getElementById('keybox').scrollIntoView({behavior:'smooth'});
     }
     loadStatus(); // 刷新进度面板
   }catch(e){alert('网络错误: '+e.message);btn.disabled=false}
 }
+// 安全卡二维码: 本机后端读 tb-keyring 出 dataURL (qrcode 包无浏览器 build, 且安全词不进 script 依赖链);
+// 只在创建会话 (_mn 在内存) 拉取 — 刷新后不再展示 (与"安全词只展示一次"同口径)
+async function loadBackupQr(){
+  if(!_mn) return;
+  try{
+    var j=await readJson(await fetch('/api/onboard/backup-qrcode'));
+    if(j&&j.ok&&j.data_url){
+      var img=document.getElementById('qr-img');
+      img.src=j.data_url; img.style.display='block';
+    }
+  }catch(e){ /* 二维码失败不挡安全卡展示 */ }
+}
+// 恢复店铺 (换新电脑): 手填 24 安全词 → 本机后端写入 tb-keyring + 派生地址
+async function restoreIdentity(){
+  var ta=document.getElementById('restore-words');
+  var msg=document.getElementById('restore-msg');
+  var mn=(ta.value||'').trim();
+  if(!mn){ msg.style.color='#DC2626'; msg.textContent='请先填写 24 个安全词'; return; }
+  msg.style.color=''; msg.textContent='恢复中...';
+  try{
+    var j=await readJson(await fetch('/api/onboard/restore-identity',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({mnemonic:mn})}));
+    if(j.ok){
+      msg.style.color='#16A34A';
+      msg.textContent='✅ 店铺已恢复 ('+j.tb_address+'), 正在刷新...';
+      ta.value=''; // 用完即清, 安全词不留页面
+      loadStatus();
+    }else{
+      msg.style.color='#DC2626';
+      msg.textContent=j.message||'恢复失败';
+    }
+  }catch(e){ msg.style.color='#DC2626'; msg.textContent='服务暂时不可用: '+e.message; }
+}
 </script>
 <script>
 /* ===== ③ 进件表单 美化增强 (2026-10-03) —— 纯追加脚本: 不修改/不覆盖任何现有函数,

package/routes/onboard.js

@@ -26,7 +26,7 @@
 const fs = require("fs");
 const path = require("path");
 const crypto = require("crypto");
-const { ensureSellerIdentity } = require("../core/seller-identity");
+const { ensureSellerIdentity, readSellerIdentity } = require("../core/seller-identity");
 const basePaths = require("../core/paths");
 const { isTctAddress } = require("../core/address");
 const chainWrites = require("./chain-writes");
@@ -163,10 +163,13 @@ function createOnboardRouter(deps) {
             // 签名通道现状: 页面/客服诊断用 (只回路径与模式, 绝不回助记词/私钥)
             let signMode = null;
             try { signMode = chainWrites.signModeInfo(); } catch (_) { signMode = null; }
+            let backupOk = false;
+            try { backupOk = !!db.prepare("SELECT acked_at FROM tb_backup_ack WHERE id=1").get(); } catch (_) { backupOk = false; }
             res.json({
                 ok: true,
                 identity_created: !!tbAddress,
                 tb_address: tbAddress,
+                backup_acked: backupOk, // 纸密钥备份验证标记 (tb_backup_ack 台账, 换浏览器仍绿)
                 shop_name: shop ? shop.merchant_shortname : null,
                 sub_mchid: (applyment && applyment.sub_mchid) || (shop ? shop.sub_mchid : "none"),
                 verification,
@@ -188,7 +191,7 @@ function createOnboardRouter(deps) {
                 shop_admin_user: (process.env.SHOP_ADMIN_USER || "admin").trim(), // 密码绝不进 API
                 steps: [
                     { key: "identity", label: "卖家身份", done: !!tbAddress },
-                    { key: "backup", label: "备份纸密钥", done: null },
+                    { key: "backup", label: "备份店铺安全卡", done: backupOk },
                     { key: "verification", label: "微信收款认证", done: applymentDone, kyc_approved: /approved/i.test(verification.status) },
                     { key: "grant", label: "引导金 100 TCT", done: grant.status === "issued" },
                     { key: "listing", label: "上架商品", done: false },
@@ -459,6 +462,134 @@ function createOnboardRouter(deps) {
         }
     });
 
+    // ---------- 纸密钥备份回填验证 (2026-10-03 xiaomu: MetaMask 式抽词验证) ----------
+    // 原则: mnemonic 永不出本机 — 页面只送 {positions, words}, 本机后端读 tb-keyring 比对,
+    // 永不返回正确词; 限流每 30s 一次 (防在线爆破, 虽然攻击面只是 localhost)。
+    // 验证通过 → tb_backup_ack 落标记 (sqlite 单行表), /onboard/status 读它让步骤②持久打勾。
+    function ensureBackupAckTable() {
+        db.prepare("CREATE TABLE IF NOT EXISTS tb_backup_ack (id INTEGER PRIMARY KEY CHECK(id=1), acked_at INTEGER NOT NULL)").run();
+    }
+    ensureBackupAckTable();
+    function backupAcked() {
+        try { return !!db.prepare("SELECT acked_at FROM tb_backup_ack WHERE id=1").get(); } catch (_) { return false; }
+    }
+    function markBackupAcked() {
+        ensureBackupAckTable();
+        db.prepare("INSERT INTO tb_backup_ack (id, acked_at) VALUES (1, ?) ON CONFLICT(id) DO UPDATE SET acked_at=excluded.acked_at")
+            .run(Math.floor(Date.now() / 1000));
+    }
+    const backupVerifyRate = new Map(); // ip → last attempt ms (单商户本机场景, 内存即可)
+    router.post("/verify-backup", (req, res) => {
+        try {
+            const b = req.body || {};
+            const positions = Array.isArray(b.positions) ? b.positions.map(Number) : [];
+            const words = Array.isArray(b.words) ? b.words.map((w) => String(w)) : [];
+            // 先参数校验 (烂请求不吃限流额度), 再限流, 最后读密钥
+            if (!positions.length || positions.length !== words.length || positions.length > 5) {
+                return res.status(400).json({ ok: false, error: "invalid_param", message: "positions/words 必填且等长 (≤5 个)" });
+            }
+            if (positions.some((p) => !Number.isInteger(p) || p < 1 || p > 24)) {
+                return res.status(400).json({ ok: false, error: "invalid_param", message: "positions 必须是 1-24 的整数" });
+            }
+            const ip = req.ip || "local";
+            const last = backupVerifyRate.get(ip) || 0;
+            if (Date.now() - last < 30000) {
+                return res.status(429).json({ ok: false, error: "rate_limited", message: "30 秒内只能验证一次, 请对照纸密钥稍后再试" });
+            }
+            backupVerifyRate.set(ip, Date.now());
+            let realWords;
+            try {
+                realWords = fs.readFileSync(basePaths.mnemonicFile(), "utf8").trim().split(/\s+/);
+            } catch (e) {
+                return res.status(404).json({ ok: false, error: "no_key", message: "本机还没有卖家密钥 (先完成第①步生成身份)" });
+            }
+            if (realWords.length < 24) {
+                return res.status(500).json({ ok: false, error: "key_corrupt", message: "本机密钥文件异常, 请联系服务商" });
+            }
+            const wrong = [];
+            positions.forEach((p, i) => {
+                if (String(words[i] || "").trim().toLowerCase() !== realWords[p - 1].toLowerCase()) wrong.push(p);
+            });
+            if (wrong.length === 0) {
+                markBackupAcked();
+                console.log("[onboard] 纸密钥备份验证通过 (ack 落台账)");
+                return res.json({ ok: true });
+            }
+            // 不泄答案: 只说哪几个位置错了
+            return res.json({ ok: false, wrong_positions: wrong, message: "有词不对, 请对照纸上抄写检查 (不会提示正确答案)" });
+        } catch (e) {
+            console.error("[onboard] verify-backup error:", e && e.message);
+            res.status(500).json({ ok: false, error: "internal", message: String(e && e.message).slice(0, 200) });
+        }
+    });
+    /** 纯前端比对路径 (首次创建安全词还在页面内存, 未过后端验证) 的 ack 落账入口 — 不带任何密钥材料 */
+    router.post("/backup-ack", (req, res) => {
+        markBackupAcked();
+        res.json({ ok: true });
+    });
+
+    // ---------- 安全卡二维码 + 恢复店铺 (2026-10-03 xiaomu: 安全卡打印版式升级) ----------
+    /** GET /backup-qrcode — 安全卡二维码 (内容 JSON {v:1,type:'tb-backup',mnemonic} 含 24 安全词)。
+     *  只在本机 localhost 生成/展示 (qrcode 包服务端 toDataURL; 该包无浏览器 build, 且安全词
+     *  不应进页面 script 依赖链)。页面仅在创建会话 (_mn 在内存) 时拉取展示。 */
+    router.get("/backup-qrcode", async (req, res) => {
+        try {
+            const identity = await readSellerIdentity(basePaths.baseDir()); // 只读不生成
+            if (!identity) {
+                return res.status(404).json({ ok: false, error: "no_key", message: "本机还没有店铺身份 (先完成第①步)" });
+            }
+            const { toDataURL } = require("qrcode");
+            const dataUrl = await toDataURL(JSON.stringify({ v: 1, type: "tb-backup", mnemonic: identity.mnemonic }), { margin: 1, width: 320 });
+            res.json({ ok: true, data_url: dataUrl });
+        } catch (e) {
+            console.error("[onboard] backup-qrcode error:", e && e.message);
+            res.status(500).json({ ok: false, error: "internal", message: String(e && e.message).slice(0, 200) });
+        }
+    });
+
+    /** POST /restore-identity {mnemonic} — 恢复店铺 (换新电脑): 24 安全词写 tb-keyring/mnemonic.txt
+     *  (0600) + 派生地址。已有身份 → 409 (防覆盖); BIP39 校验位不过 → 400; 限流 30s。 */
+    const restoreRate = new Map();
+    router.post("/restore-identity", async (req, res) => {
+        try {
+            const mn = String((req.body || {}).mnemonic || "").trim().toLowerCase().replace(/\s+/g, " ");
+            const words = mn ? mn.split(" ") : [];
+            // 先校验 (烂请求不吃限流额度), 再限流, 最后写盘
+            if (words.length !== 24) {
+                return res.status(400).json({ ok: false, error: "invalid_mnemonic", message: "请填写完整的 24 个安全词 (空格分隔)" });
+            }
+            // 已有身份 → 拒 (防覆盖别人的店)
+            const existing = await readSellerIdentity(basePaths.baseDir());
+            if (existing) {
+                return res.status(409).json({ ok: false, error: "identity_exists", message: "这台电脑已有店铺身份 (" + existing.address + "), 不能覆盖。如需换店请先备份再联系服务商" });
+            }
+            // BIP39 校验位验证 (错词/乱序会拒)
+            try {
+                const { Bip39, EnglishMnemonic } = require("@cosmjs/crypto");
+                Bip39.decode(new EnglishMnemonic(mn));
+            } catch (e) {
+                return res.status(400).json({ ok: false, error: "invalid_mnemonic", message: "安全词校验不过 (有错词或顺序不对), 请对照安全卡逐词检查" });
+            }
+            const ip = req.ip || "local";
+            const last = restoreRate.get(ip) || 0;
+            if (Date.now() - last < 30000) {
+                return res.status(429).json({ ok: false, error: "rate_limited", message: "30 秒内只能恢复一次, 请稍后再试" });
+            }
+            restoreRate.set(ip, Date.now());
+            fs.mkdirSync(basePaths.keyringDir(), { recursive: true });
+            fs.writeFileSync(basePaths.mnemonicFile(), mn + "\n", { encoding: "utf8", mode: 0o600 });
+            // 删旧 address.txt 强制按新安全词重新派生 (restore 场景理论上是全新机器没有它,
+            // 但测试/异常残留时必须防"新词配旧地址"的错位身份)
+            try { fs.unlinkSync(path.join(basePaths.keyringDir(), "address.txt")); } catch (_) { /* 不存在 */ }
+            const identity = await ensureSellerIdentity(basePaths.baseDir()); // 读刚写的安全词 → 派生地址补写 address.txt
+            console.log("[onboard] restore-identity 恢复成功 addr:", identity.address);
+            res.json({ ok: true, tb_address: identity.address, message: "店铺已恢复, 刷新页面即可看到进度" });
+        } catch (e) {
+            console.error("[onboard] restore-identity error:", e && e.message);
+            res.status(500).json({ ok: false, error: "internal", message: String(e && e.message).slice(0, 200) });
+        }
+    });
+
     // ---------- 微信特约商户进件 (Stage 2, 2026-10-03 架构纠偏: 卖家本机提交 → SP 网关 → 微信) ----------
     const spApplyment = require("./sp-applyment");
     /** 在卖家本机就要加密的敏感字段 (与 sp-applyment buildApplymentBody 加密清单一致;

package/routes/order.js

@@ -219,18 +219,11 @@ function createOrderRoutes(authPlugin, deps) {
     /**
      * 获取订单详情
      * GET /api/order/:orderId
+     * M4 (2026-10-03): 公开只读 — 纯 LCD 链上数据透传 (订单内容本就链上公开),
+     * 买家在卖家后端无凭证, 之前 401 是误伤。写操作 (confirm/cancel/dispute) 鉴权不变。
      */
     router.get('/:orderId', async (req, res) => {
         try {
-            const authHeader = req.headers.authorization;
-            if (!authHeader || !authHeader.startsWith('Bearer ')) {
-                return res.status(401).json({ error: 'Missing authorization header' });
-            }
-            const token = authHeader.substring(7);
-            const tokenData = await authPlugin.verifyToken(token);
-            if (!tokenData) {
-                return res.status(401).json({ error: 'Invalid token' });
-            }
             const { orderId } = req.params;
             const response = await fetch(`${lcdUrl}/oxiaom/trustchain/order/v1/orders/${orderId}`);
             if (!response.ok) {
@@ -247,18 +240,10 @@ function createOrderRoutes(authPlugin, deps) {
     /**
      * 获取买家订单列表
      * GET /api/order/buyer/:address
+     * M4: 公开只读 (链上公开数据透传, 无卖家敏感信息)
      */
     router.get('/buyer/:address', async (req, res) => {
         try {
-            const authHeader = req.headers.authorization;
-            if (!authHeader || !authHeader.startsWith('Bearer ')) {
-                return res.status(401).json({ error: 'Missing authorization header' });
-            }
-            const token = authHeader.substring(7);
-            const tokenData = await authPlugin.verifyToken(token);
-            if (!tokenData) {
-                return res.status(401).json({ error: 'Invalid token' });
-            }
             const { address } = req.params;
             const response = await fetch(`${lcdUrl}/oxiaom/trustchain/order/v1/buyers/${address}/orders`);
             if (!response.ok) {

package/test-agent-pay-lifecycle.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * test-agent-pay-lifecycle.js — M4 买家维度: agent-pay 状态机断头路修复 + order.js 买家只读面公开化
+ * node --test test-agent-pay-lifecycle.js
+ *
+ * 覆盖:
+ *   状态机全链 PAID→SHIPPED→DELIVERED→CONFIRMED (logistics HMAC + confirm status_token)
+ *   回退拒 (DELIVERED→SHIPPED 409) + timeline 追加不覆盖 + logistics 无 key/错 key 401
+ *   状态查询: rail 真实值 (psp_txns) + DISPUTED/REFUNDED 不再误映射 PAID
+ *   markOrderOnChain: PAID→ON_CHAIN 回写 chain_order_id (占位函数, 后续批次触发)
+ *   order.js: 买家只读面 (单查/买家列表) 无 token 200; 写操作 (confirm/cancel/dispute) 仍 401
+ * 不碰真微信/真链 (打桩 LCD)。
+ */
+const test = require("node:test");
+const assert = require("node:assert");
+const crypto = require("crypto");
+const http = require("http");
+const express = require("express");
+const Database = require("better-sqlite3");
+
+const agentPay = require("./routes/agent-pay");
+const { createOrderRoutes } = require("./routes/order");
+
+function nowSec() { return Math.floor(Date.now() / 1000); }
+function sha256(s) { return crypto.createHash("sha256").update(String(s)).digest("hex"); }
+
+/** 起 agent-pay 服务 (mock 模式) */
+async function startAgentPay() {
+    const db = new Database(":memory:");
+    const app = express();
+    app.use(express.json());
+    app.use("/api/agent", agentPay.createAgentPayRouter({ db }));
+    const srv = app.listen(0);
+    await new Promise((r) => srv.once("listening", r));
+    return { db, srv, base: `http://127.0.0.1:${srv.address().port}/api/agent` };
+}
+
+function insertPaidSession(db, orderRef, statusToken) {
+    db.prepare(`INSERT INTO agent_pay_sessions
+ (client_session_id, sku_id, qty, amount_total, currency, agent_addr, order_ref, pay_token_hash, status_token_hash, state, psp_code_url, callback_url, expires_at, created_at, updated_at)
+ VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
+        .run("cs-" + orderRef, "sku-1", 1, 100, "CNY", "", orderRef, sha256("pt-" + orderRef), sha256(statusToken), "PAID", "", "", nowSec() + 900, nowSec(), nowSec());
+}
+
+const LKEY = "test-logistics-hmac-key";
+
+test("M4 状态机全链: PAID→SHIPPED→DELIVERED→CONFIRMED + 回退拒 + timeline 追加 + HMAC 鉴权", async () => {
+    process.env.LOGISTICS_HMAC_KEY = LKEY;
+    const { db, srv, base } = await startAgentPay();
+    try {
+        insertPaidSession(db, "tb-lc-1", "st-lc-1");
+        const H = { "Content-Type": "application/json", "x-logistics-key": LKEY };
+        // 无 key → 401; 错 key → 401
+        let r = await fetch(base + "/internal/logistics", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ order_ref: "tb-lc-1" }) });
+        assert.strictEqual(r.status, 401, "无 key 拒");
+        r = await fetch(base + "/internal/logistics", { method: "POST", headers: { "Content-Type": "application/json", "x-logistics-key": "wrong" }, body: JSON.stringify({ order_ref: "tb-lc-1" }) });
+        assert.strictEqual(r.status, 401, "错 key 拒");
+        // PAID → SHIPPED
+        r = await fetch(base + "/internal/logistics", { method: "POST", headers: H, body: JSON.stringify({ order_ref: "tb-lc-1", carrier: "顺丰", tracking_no: "SF123", timeline: [{ t: "揽收" }] }) });
+        assert.strictEqual((await r.json()).state, "SHIPPED");
+        // SHIPPED → SHIPPED 更新, timeline 追加不覆盖
+        r = await fetch(base + "/internal/logistics", { method: "POST", headers: H, body: JSON.stringify({ order_ref: "tb-lc-1", timeline: [{ t: "运输中" }] }) });
+        assert.strictEqual((await r.json()).state, "SHIPPED");
+        let row = db.prepare("SELECT * FROM agent_pay_sessions WHERE order_ref='tb-lc-1'").get();
+        assert.strictEqual(JSON.parse(row.timeline).length, 2, "timeline 追加不覆盖");
+        assert.strictEqual(row.carrier, "顺丰", "carrier 保留 (未传不清空)");
+        // SHIPPED → DELIVERED
+        r = await fetch(base + "/internal/logistics", { method: "POST", headers: H, body: JSON.stringify({ order_ref: "tb-lc-1", logistics_state: "DELIVERED", timeline: [{ t: "签收" }] }) });
+        assert.strictEqual((await r.json()).state, "DELIVERED");
+        // 回退 DELIVERED → SHIPPED → 409
+        r = await fetch(base + "/internal/logistics", { method: "POST", headers: H, body: JSON.stringify({ order_ref: "tb-lc-1", logistics_state: "SHIPPED" }) });
+        assert.strictEqual(r.status, 409);
+        let ej = await r.json();
+        assert.strictEqual(ej.current, "DELIVERED", "回退被拒 (STATE_INVALID 详情带 current)");
+        assert.strictEqual(ej.target, "SHIPPED");
+        // DELIVERED → CONFIRMED (买家确认收货, status_token 凭证)
+        r = await fetch(base + "/order/confirm", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ order_ref: "tb-lc-1", token: "wrong-token" }) });
+        assert.strictEqual(r.status, 401, "错 status_token 拒");
+        r = await fetch(base + "/order/confirm", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ order_ref: "tb-lc-1", token: "st-lc-1" }) });
+        assert.strictEqual((await r.json()).state, "CONFIRMED");
+        // 幂等
+        r = await fetch(base + "/order/confirm", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ order_ref: "tb-lc-1", token: "st-lc-1" }) });
+        assert.strictEqual((await r.json()).idempotent, true);
+        // 终态后物流回退仍拒
+        r = await fetch(base + "/internal/logistics", { method: "POST", headers: H, body: JSON.stringify({ order_ref: "tb-lc-1", logistics_state: "SHIPPED" }) });
+        assert.strictEqual(r.status, 409);
+        // 状态查询: 全链后 payment.state=PAID + rail 真实
+        const st = await (await fetch(base + "/order/status?order_ref=tb-lc-1&token=st-lc-1")).json();
+        assert.strictEqual(st.state, "CONFIRMED");
+        assert.strictEqual(st.payment.state, "PAID");
+        assert.strictEqual(st.logistics.state, "DELIVERED");
+        assert.strictEqual(st.logistics.timeline.length, 3);
+    } finally { srv.close(); delete process.env.LOGISTICS_HMAC_KEY; }
+});
+
+test("M4: logistics 未配置 LOGISTICS_HMAC_KEY → 全拒 401 (宁可全拒不留后门)", async () => {
+    delete process.env.LOGISTICS_HMAC_KEY;
+    const { srv, base } = await startAgentPay();
+    try {
+        const r = await fetch(base + "/internal/logistics", { method: "POST", headers: { "Content-Type": "application/json", "x-logistics-key": "any" }, body: JSON.stringify({ order_ref: "x" }) });
+        assert.strictEqual(r.status, 401);
+    } finally { srv.close(); }
+});
+
+test("M4: 状态查询 payment.state 映射修正 (DISPUTED/REFUNDED 不再是 PAID) + rail 真实值", async () => {
+    const { db, srv, base } = await startAgentPay();
+    try {
+        // DISPUTED (金额不一致落账队列)
+        insertPaidSession(db, "tb-st-1", "st-1");
+        db.prepare("UPDATE agent_pay_sessions SET state='DISPUTED' WHERE order_ref='tb-st-1'").run();
+        db.prepare("INSERT INTO psp_txns (txn_id, session_id, rail, amount, raw, created_at) VALUES ('tx-st-1', (SELECT id FROM agent_pay_sessions WHERE order_ref='tb-st-1'), 'wechat_native', 100, '', ?)").run(nowSec());
+        let st = await (await fetch(base + "/order/status?order_ref=tb-st-1&token=st-1")).json();
+        assert.strictEqual(st.payment.state, "DISPUTED", "DISPUTED 不映射 PAID");
+        assert.strictEqual(st.payment.rail, "wechat_native", "rail 取 psp_txns 真实轨 (不是硬编码 mock)");
+        // REFUNDED
+        insertPaidSession(db, "tb-st-2", "st-2");
+        db.prepare("UPDATE agent_pay_sessions SET state='REFUNDED' WHERE order_ref='tb-st-2'").run();
+        st = await (await fetch(base + "/order/status?order_ref=tb-st-2&token=st-2")).json();
+        assert.strictEqual(st.payment.state, "REFUNDED");
+        // CREATED → UNPAID, rail 回落 MODE (mock)
+        insertPaidSession(db, "tb-st-3", "st-3");
+        db.prepare("UPDATE agent_pay_sessions SET state='CREATED' WHERE order_ref='tb-st-3'").run();
+        st = await (await fetch(base + "/order/status?order_ref=tb-st-3&token=st-3")).json();
+        assert.strictEqual(st.payment.state, "UNPAID");
+        assert.strictEqual(st.payment.rail, "mock");
+    } finally { srv.close(); }
+});
+
+test("M4: markOrderOnChain — PAID→ON_CHAIN 回写 chain_order_id (占位函数, 后续批次触发)", async () => {
+    const { db, srv } = await startAgentPay();
+    try {
+        insertPaidSession(db, "tb-oc-1", "st-oc");
+        const r = agentPay.markOrderOnChain(db, "tb-oc-1", "chain-order-42");
+        assert.strictEqual(r.ok, true);
+        const row = db.prepare("SELECT * FROM agent_pay_sessions WHERE order_ref='tb-oc-1'").get();
+        assert.strictEqual(row.state, "ON_CHAIN");
+        assert.strictEqual(row.chain_order_id, "chain-order-42");
+        // 幂等 + 非法态
+        assert.strictEqual(agentPay.markOrderOnChain(db, "tb-oc-1", "chain-order-42").idempotent, true);
+        db.prepare("UPDATE agent_pay_sessions SET state='CONFIRMED' WHERE order_ref='tb-oc-1'").run();
+        assert.strictEqual(agentPay.markOrderOnChain(db, "tb-oc-1", "x").error, "STATE_INVALID");
+        assert.strictEqual(agentPay.markOrderOnChain(db, "tb-nope", "x").error, "NOT_FOUND");
+    } finally { srv.close(); }
+});
+
+test("M4: order.js 买家只读面公开 (单查/买家列表无 token 200), 写操作仍 401", async () => {
+    // 打桩 LCD (链上公开数据)
+    const stub = http.createServer((req, res) => {
+        res.setHeader("content-type", "application/json");
+        if (req.url.startsWith("/oxiaom/trustchain/order/v1/orders/")) {
+            return res.end(JSON.stringify({ order: { order_id: "7", buyer: "tct1buyer", seller: "tct1seller", status: "ORDER_STATUS_PAID" } }));
+        }
+        if (req.url.startsWith("/oxiaom/trustchain/order/v1/buyers/")) {
+            return res.end(JSON.stringify({ orders: [{ order_id: "7" }] }));
+        }
+        res.writeHead(404); res.end("{}");
+    });
+    await new Promise((r) => stub.listen(0, "127.0.0.1", r));
+    const savedLcd = process.env.LCD_URL;
+    process.env.LCD_URL = `http://127.0.0.1:${stub.address().port}`;
+    const db = new Database(":memory:");
+    const app = express();
+    app.use(express.json());
+    const authPlugin = { verifyToken: async () => null }; // 写操作鉴权桩: 任何 token 都无效 → 写操作恒 401
+    app.use("/api/order", createOrderRoutes(authPlugin, { db }));
+    const srv = app.listen(0);
+    await new Promise((r) => srv.once("listening", r));
+    const base = `http://127.0.0.1:${srv.address().port}/api/order`;
+    try {
+        // 买家只读面: 无 token 可查
+        let r = await fetch(base + "/7");
+        assert.strictEqual(r.status, 200, "单查公开");
+        assert.strictEqual((await r.json()).order.order_id, "7");
+        r = await fetch(base + "/buyer/tct1buyer");
+        assert.strictEqual(r.status, 200, "买家列表公开");
+        assert.strictEqual((await r.json()).orders.length, 1);
+        // 写操作仍 401 (无 token)
+        for (const p of ["/confirm", "/cancel", "/dispute"]) {
+            const w = await fetch(base + p, { method: "POST", headers: { "Content-Type": "application/json" }, body: "{}" });
+            assert.strictEqual(w.status, 401, p + " 写操作保持鉴权");
+        }
+    } finally {
+        srv.close(); stub.close();
+        if (savedLcd === undefined) delete process.env.LCD_URL; else process.env.LCD_URL = savedLcd;
+    }
+});

package/test-agent-pay-wechat.js

@@ -258,3 +258,34 @@ test("E3 回归 (2026-09-25 实测 bug): EXPIRED 单过期 <24h 仍被查单,
     assert.ok(!refs.includes("tb-rec-2"), "过期 25h 的 EXPIRED 单不进查单范围");
     delete process.env.AGENT_PAY_MODE;
 });
+
+test("M4: E2 退款事件 TRANSACTION.REFUND → REFUNDED (幂等 + 处理中忽略)", async () => {
+    const { db, srv, base } = await startServer();
+    try {
+        insertSession(db, "tb-refund-1", 100);
+        db.prepare("UPDATE agent_pay_sessions SET state='PAID' WHERE order_ref='tb-refund-1'").run();
+        const body = JSON.stringify({
+            id: "EV-R1", event_type: "TRANSACTION.REFUND", resource_type: "encrypt-resource",
+            resource: wxEncryptResource({ out_trade_no: "tb-refund-1", refund_status: "SUCCESS", refund_id: "RF-1" }),
+        });
+        const r = await fetch(base + "/pay/notify/wechat", { method: "POST", headers: wxSignHeaders(body), body });
+        assert.strictEqual(r.status, 200);
+        assert.strictEqual((await r.json()).refunded, true);
+        assert.strictEqual(db.prepare("SELECT state FROM agent_pay_sessions WHERE order_ref='tb-refund-1'").get().state, "REFUNDED");
+        // 重放幂等: 仍 200 refunded, 状态保持
+        const r2 = await fetch(base + "/pay/notify/wechat", { method: "POST", headers: wxSignHeaders(body), body });
+        assert.strictEqual(r2.status, 200);
+        assert.strictEqual(db.prepare("SELECT state FROM agent_pay_sessions WHERE order_ref='tb-refund-1'").get().state, "REFUNDED");
+        // 退款处理中 → ignored 不改状态
+        insertSession(db, "tb-refund-2", 100);
+        db.prepare("UPDATE agent_pay_sessions SET state='SHIPPED' WHERE order_ref='tb-refund-2'").run();
+        const body2 = JSON.stringify({
+            id: "EV-R2", event_type: "TRANSACTION.REFUND", resource_type: "encrypt-resource",
+            resource: wxEncryptResource({ out_trade_no: "tb-refund-2", refund_status: "PROCESSING", refund_id: "RF-2" }),
+        });
+        const r3 = await fetch(base + "/pay/notify/wechat", { method: "POST", headers: wxSignHeaders(body2), body: body2 });
+        assert.strictEqual(r3.status, 200);
+        assert.ok((await r3.json()).ignored, "处理中不落 REFUNDED");
+        assert.strictEqual(db.prepare("SELECT state FROM agent_pay_sessions WHERE order_ref='tb-refund-2'").get().state, "SHIPPED");
+    } finally { srv.close(); }
+});

package/test-onboard-backup.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * test-onboard-backup.js — 纸密钥备份回填验证 (MetaMask 式抽词) 离线单测 (2026-10-03)
+ * node --test test-onboard-backup.js
+ *
+ * 覆盖:
+ *   POST /api/onboard/verify-backup — 正确词 ok+台账落 ack / 错词 wrong_positions (不泄答案)
+ *     / 限流 30s / 参数校验 / 无密钥 404
+ *   POST /api/onboard/backup-ack — 纯前端比对路径的 ack 落账
+ *   GET /onboard/status — backup_acked + steps[1].done 持久化
+ * 安全断言: 任何响应体都不得包含真实助记词内容。
+ */
+const test = require("node:test");
+const assert = require("node:assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const express = require("express");
+const Database = require("better-sqlite3");
+
+// 测试助记词 (24 词, 落临时 tb-keyring — 隔离不碰真机)
+// 必须用合法 BIP39 (EnglishMnemonic 会校验 checksum): 直接复用 seller-identity 测试向量
+const VECTOR_MNEMONIC = "economy stock theory fatal elder harbor betray wasp final emotion task crumble siren bottom lizard educate guess current outdoor pair theory focus wife stone";
+const WORDS = VECTOR_MNEMONIC.split(" ");
+// 恢复测试用助记词: 测试运行时真生成 (合法 BIP39 24 词)
+let RESTORE_MNEMONIC = "";
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "backup-verify-test-"));
+fs.mkdirSync(path.join(tmpDir, "tb-keyring"), { recursive: true });
+fs.writeFileSync(path.join(tmpDir, "tb-keyring", "mnemonic.txt"), WORDS.join(" "), { mode: 0o600 });
+
+// env 必须在 require 前 (core/paths freeze)
+process.env.TB_BASE_DIR = tmpDir;
+
+const onboard = require("./routes/onboard");
+
+async function startServer() {
+    const db = new Database(":memory:");
+    const app = express();
+    app.use(express.json());
+    const router = onboard.createOnboardRouter({ db });
+    app.use("/api/onboard", router);
+    app.use("/onboard", router);
+    const srv = app.listen(0);
+    await new Promise((r) => srv.once("listening", r));
+    return { db, srv, base: `http://127.0.0.1:${srv.address().port}` };
+}
+
+const H = { "Content-Type": "application/json" };
+
+test("verify-backup: 正确词 → ok + ack 落台账 + status 步骤② done 持久化", async () => {
+    const { srv, base } = await startServer();
+    try {
+        const r = await fetch(base + "/api/onboard/verify-backup", {
+            method: "POST", headers: H,
+            body: JSON.stringify({ positions: [3, 7, 24], words: ["theory", "betray", "stone"] }),
+        });
+        const j = await r.json();
+        assert.strictEqual(r.status, 200);
+        assert.strictEqual(j.ok, true, JSON.stringify(j));
+        // status: backup_acked + steps[1].done
+        const st = await (await fetch(base + "/onboard/status")).json();
+        assert.strictEqual(st.backup_acked, true);
+        assert.strictEqual(st.steps[1].key, "backup");
+        assert.strictEqual(st.steps[1].done, true, "步骤②持久打勾 (换浏览器仍绿)");
+    } finally { srv.close(); }
+});
+
+test("verify-backup: 错词 → wrong_positions (不泄正确答案) + 大小写/空白容忍", async () => {
+    const { srv, base } = await startServer();
+    try {
+        // 第 3 词故意错 (charlie→wrong), 第 7 词大小写+空白混合也对 (容忍)
+        const r = await fetch(base + "/api/onboard/verify-backup", {
+            method: "POST", headers: H,
+            body: JSON.stringify({ positions: [3, 7, 11], words: ["wrongword", " BETRAY ", "Task"] }),
+        });
+        const j = await r.json();
+        assert.strictEqual(r.status, 200);
+        assert.strictEqual(j.ok, false);
+        assert.deepStrictEqual(j.wrong_positions, [3], "只报第 3 个错 (7/11 大小写空白容忍)");
+        // 不泄答案: 响应体不得含任何真实词
+        const raw = JSON.stringify(j);
+        for (const w of WORDS) assert.ok(!raw.includes(w), "响应泄露了真实词: " + w);
+    } finally { srv.close(); }
+});
+
+test("verify-backup: 限流 30s (同 IP 连续两次 → 第二次 429)", async () => {
+    const { srv, base } = await startServer();
+    try {
+        const body = JSON.stringify({ positions: [1, 2, 3], words: ["economy", "stock", "theory"] });
+        const r1 = await fetch(base + "/api/onboard/verify-backup", { method: "POST", headers: H, body });
+        assert.strictEqual(r1.status, 200);
+        const r2 = await fetch(base + "/api/onboard/verify-backup", { method: "POST", headers: H, body });
+        assert.strictEqual(r2.status, 429);
+        assert.strictEqual((await r2.json()).error, "rate_limited");
+    } finally { srv.close(); }
+});
+
+test("verify-backup: 参数校验 (空 positions / 越界位置 / 不等长 → 400)", async () => {
+    const { srv, base } = await startServer();
+    try {
+        for (const body of [
+            { positions: [], words: [] },
+            { positions: [0, 25], words: ["a", "b"] },      // 越界 (1-24)
+            { positions: [1, 2], words: ["alpha"] },         // 不等长
+        ]) {
+            const r = await fetch(base + "/api/onboard/verify-backup", { method: "POST", headers: H, body: JSON.stringify(body) });
+            assert.strictEqual(r.status, 400, JSON.stringify(body));
+        }
+    } finally { srv.close(); }
+});
+
+test("backup-ack: 纯前端比对路径落账 (不带密钥材料) + status done", async () => {
+    const { srv, base } = await startServer();
+    try {
+        const r = await fetch(base + "/api/onboard/backup-ack", { method: "POST", headers: H, body: "{}" });
+        assert.strictEqual((await r.json()).ok, true);
+        const st = await (await fetch(base + "/onboard/status")).json();
+        assert.strictEqual(st.backup_acked, true);
+        assert.strictEqual(st.steps[1].done, true);
+    } finally { srv.close(); }
+});
+
+test("页面含备份验证 UI (抽题/提交/结果显示) + 内存路径分支", async () => {
+    const { srv, base } = await startServer();
+    try {
+        const html = await (await fetch(base + "/onboard/")).text();
+        assert.ok(html.includes("startBackupVerify"), "抽题入口");
+        assert.ok(html.includes("backup-quiz") && html.includes("bq-word"), "回填控件");
+        assert.ok(html.includes("/api/onboard/verify-backup"), "后端比对路径");
+        assert.ok(html.includes("persistBackupAck"), "内存路径 ack 落账");
+        assert.ok(html.includes("我已抄好"), "大白话文案");
+    } finally { srv.close(); }
+});
+
+// ---- 安全卡二维码 + 恢复店铺 (2026-10-03) ----
+const KEYRING = path.join(tmpDir, "tb-keyring");
+
+test("backup-qrcode: 本机出二维码 dataURL (安全词只在 localhost 流转)", async () => {
+    const { srv, base } = await startServer();
+    try {
+        const r = await fetch(base + "/api/onboard/backup-qrcode");
+        const j = await r.json();
+        assert.strictEqual(r.status, 200);
+        assert.ok(j.data_url.startsWith("data:image/png;base64,"), "QR dataURL");
+        assert.ok(j.data_url.length > 500, "QR 有内容");
+    } finally { srv.close(); }
+});
+
+test("restore-identity: 写入+派生地址正确 (测试向量) / 已有身份 409 / 烂词 400", async () => {
+    const { srv, base } = await startServer();
+    const bak = path.join(KEYRING, "mnemonic.txt.bak");
+    try {
+        // 已有身份 (模块加载时写的向量助记词) → 409
+        let r = await fetch(base + "/api/onboard/restore-identity", { method: "POST", headers: H, body: JSON.stringify({ mnemonic: VECTOR_MNEMONIC }) });
+        assert.strictEqual(r.status, 409);
+        assert.strictEqual((await r.json()).error, "identity_exists");
+        // 词数不对 → 400 (词数校验先于身份检查)
+        r = await fetch(base + "/api/onboard/restore-identity", { method: "POST", headers: H, body: JSON.stringify({ mnemonic: "alpha bravo charlie" }) });
+        assert.strictEqual(r.status, 400);
+        // 挪走现有身份 → 24 个合法词但校验位不过 → 400 (abandon×24 校验位非法;
+        //  注意 abandon×23+art 恰是 BIP39 全零熵官方合法向量, 别拿它当反例)
+        fs.renameSync(path.join(KEYRING, "mnemonic.txt"), bak);
+        r = await fetch(base + "/api/onboard/restore-identity", { method: "POST", headers: H, body: JSON.stringify({ mnemonic: "abandon ".repeat(23) + "abandon" }) });
+        assert.strictEqual(r.status, 400);
+        // 合法助记词恢复 → 地址与独立派生一致
+        RESTORE_MNEMONIC = await require("./core/seller-identity").generateMnemonic();
+        r = await fetch(base + "/api/onboard/restore-identity", { method: "POST", headers: H, body: JSON.stringify({ mnemonic: RESTORE_MNEMONIC }) });
+        const j = await r.json();
+        assert.strictEqual(r.status, 200, JSON.stringify(j));
+        const expectAddr = await require("./core/seller-identity").mnemonicToAddress(RESTORE_MNEMONIC);
+        assert.strictEqual(j.tb_address, expectAddr, "派生地址与独立派生一致");
+        assert.strictEqual(fs.readFileSync(path.join(KEYRING, "mnemonic.txt"), "utf8").trim(), RESTORE_MNEMONIC);
+        assert.strictEqual(fs.readFileSync(path.join(KEYRING, "address.txt"), "utf8").trim(), expectAddr, "address.txt 补写");
+    } finally {
+        // 还原原始测试密钥
+        try { fs.unlinkSync(path.join(KEYRING, "mnemonic.txt")); } catch (_) {}
+        try { fs.unlinkSync(path.join(KEYRING, "address.txt")); } catch (_) {}
+        if (fs.existsSync(bak)) fs.renameSync(bak, path.join(KEYRING, "mnemonic.txt"));
+        srv.close();
+    }
+});
+
+test("页面: 安全卡二维码容器 + 打印日期 + 恢复入口 + 打印样式", async () => {
+    const { srv, base } = await startServer();
+    try {
+        const html = await (await fetch(base + "/onboard/")).text();
+        assert.ok(html.includes("qr-slot") && html.includes("qr-img"), "二维码容器");
+        assert.ok(html.includes("print-date"), "打印日期");
+        assert.ok(html.includes("restore-words") && html.includes("/api/onboard/restore-identity"), "恢复入口");
+        assert.ok(html.includes("@media print"), "打印样式");
+        assert.ok(html.includes("backup-qrcode"), "QR 数据源");
+        // 术语红线: 商户可见文案不再有 助记词/纸密钥 (注释/代码除外)
+        const visible = html.replace(/\/\/[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
+        assert.ok(!visible.includes("纸密钥"), "残留 纸密钥");
+        assert.ok(!visible.includes("助记词"), "残留 助记词");
+        assert.ok(html.includes("店铺安全卡") && html.includes("安全词"), "新口径");
+    } finally { srv.close(); }
+});