trustbase-seller-backend 0.2.3 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trustbase-seller-backend",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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,17 @@ async function addReceivers(receivers) {
     return results.length === 1 ? results[0] : results;
 }
 
+/** 接收方名称加密: 微信支付公钥 RSA-OAEP-SHA256 → base64 (与进件敏感字段同口径) */
+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 pem = require("fs").readFileSync(p, "utf8");
+    return crypto.publicEncrypt(
+        { key: pem, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: "sha256" },
+        Buffer.from(name, "utf8")
+    ).toString("base64");
+}
+
 /** 请求分账
  *  params: {outTradeNo(分账单号 out_order_no, 幂等键), transactionId(微信支付单号),
  *           tradeAmount(交易金额分, 护栏基准), subMchid?, unfreezeUnsplit?,
@@ -147,4 +162,43 @@ async function queryProfitsharing(outOrderNo, opts) {
     return r.mock ? { mock: true, out_order_no: String(outOrderNo) } : r;
 }
 
-module.exports = { addReceivers, requestProfitsharing, queryProfitsharing, assertShareAmount, MAX_SHARE_BP };
+/** M3-1: 分账接收方注册台账 (幂等标记; 已注册不重复调微信 — 重复调会报 "接收方已存在" 类错误) */
+function ensurePsReceiverTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS sp_ps_receivers (
+  account TEXT PRIMARY KEY,      -- 接收方商户号 (SP 自身 mchid)
+  registered_at INTEGER NOT NULL,
+  mock INTEGER NOT NULL DEFAULT 0
+);
+`);
+}
+
+/** M3-1: 注册默认分账接收方 (SP 自身 mchid, type MERCHANT_ID)。
+ *  调用时机: SP 服务启动 (createSpNotifyRouter 挂载) + 进件 FINISHED 钩子 (sp-applyment)。
+ *  幂等: 台账有记录 → {registered:false, reason:'already'} 不调微信; mock 模式同样落台账。 */
+async function registerDefaultReceivers(db) {
+    ensurePsReceiverTable(db);
+    const c = wxCfg();
+    const account = c.spMchid || c.mchid;
+    if (!account) {
+        console.warn("[profitsharing] 未配 WXPAY_SP_MCHID/WXPAY_MCHID, 跳过接收方注册");
+        return { registered: false, reason: "no_mchid" };
+    }
+    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 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 };
+    }
+    console.warn(`[profitsharing] 接收方注册未成功 account=${account}: ${JSON.stringify(one && one.json || one).slice(0, 200)}`);
+    return { registered: false, reason: "wx_error", detail: one && one.json };
+}
+
+module.exports = { addReceivers, requestProfitsharing, queryProfitsharing, assertShareAmount, MAX_SHARE_BP, registerDefaultReceivers, ensurePsReceiverTable };

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/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/routes/sp-applyment.js

@@ -46,6 +46,8 @@ const crypto = require("crypto");
 const fs = require("fs");
 const agentPay = require("./agent-pay");
 const chainWrites = require("./chain-writes");
+const spCommission = require("./sp-commission");
+const profitsharing = require("../payments/wechat/profitsharing");
 
 const HttpError = chainWrites.HttpError;
 
@@ -630,10 +632,10 @@ function createSpApplymentRouter(deps) {
     }
 
     /** GET /info — 服务商公开名片 (2026-10-03 xiaomu: 卖家入驻页要显示服务商是谁)
-     *  公开只读, 不要 admin key — 名片本来就是给商户看的公开信息 */
+     *  公开只读, 不要 admin key — 名片本来就是给商户看的公开信息
+     *  M3 🟡-1: 公示比例读 sp_commission_rates 默认行 (__default__) 优先, env 只作首次种子 */
     router.get("/info", (req, res) => {
-        const rateBp = Number(process.env.SP_DEFAULT_COMMISSION_BP || 100); // 默认 1%
-        const bp = Number.isInteger(rateBp) && rateBp >= 0 ? rateBp : 100;
+        const bp = spCommission.getDefaultRateBp(db);
         res.json({
             name: process.env.SP_NAME || "TrustBase 官方服务商",
             desc: process.env.SP_DESC || "",
@@ -719,12 +721,14 @@ function createSpApplymentRouter(deps) {
             if (r.status !== 200 || !(r.json.applyment_id != null)) return wxError(res, r, "提交进件失败");
             const applymentId = String(r.json.applyment_id);
             // 台账快照: 敏感字段脱敏 (身份证/卡号只留后 4 位; already_encrypted 时已是密文, 脱敏无妨)
+            // M3 🟡-1: 进件时刻的公示抽佣比例快照进 subject_json (事后对账依据)
             const snapshot = {
                 ...f,
                 legal_id_number: maskTail(f.legal_id_number),
                 account_number: maskTail(f.account_number),
                 business_code: undefined,
                 already_encrypted: undefined,
+                commission_bp_at_apply: spCommission.getDefaultRateBp(db),
             };
             const now = nowSec();
             // upsert: 驳回重提时更新已有行 (同 business_code 覆盖), 否则插新行
@@ -791,6 +795,8 @@ function createSpApplymentRouter(deps) {
  ON CONFLICT(sub_mchid) DO UPDATE SET seller_address=excluded.seller_address, shop_name=excluded.shop_name`)
                             .run(String(j.sub_mchid), row.tb_address || "", String(snap.merchant_shortname || ""), now);
                         console.log(`[sp-applyment] FINISHED 钩子: sub_mchid=${j.sub_mchid} 已登记回调路由 seller=${(row.tb_address || "").slice(0, 14)}…`);
+                        // M3-1: 进件通过时也确认分账接收方已注册 (启动时注册失败的兜底; 台账幂等)
+                        await profitsharing.registerDefaultReceivers(db);
                         if (row.tb_address) {
                             const g = await notifyOracleGrant(deps, { tb_address: row.tb_address, license_number: snap.license_number });
                             if (g.ok) {

package/routes/sp-commission.js

@@ -35,6 +35,21 @@ CREATE TABLE IF NOT EXISTS sp_commission_rates (
 /** rate_bp → 人性化百分比 ("1.50%") */
 function ratePct(rateBp) { return (rateBp / 100).toFixed(2) + "%"; }
 
+/** M3 🟡-1: 公示默认抽佣比例 (sub_mchid='__default__' 特殊行) — 读表优先,
+ *  env SP_DEFAULT_COMMISSION_BP 只作首次种子 (表里没有时落一行, 之后 PUT 覆盖生效) */
+const DEFAULT_ROW_KEY = "__default__";
+function getDefaultRateBp(db) {
+    ensureCommissionTables(db);
+    const row = db.prepare("SELECT rate_bp FROM sp_commission_rates WHERE sub_mchid = ?").get(DEFAULT_ROW_KEY);
+    if (row) return row.rate_bp;
+    let seed = Number(process.env.SP_DEFAULT_COMMISSION_BP || 100);
+    if (!Number.isInteger(seed) || seed < 0 || seed > MAX_RATE_BP) seed = 100;
+    const now = nowSec();
+    db.prepare("INSERT OR IGNORE INTO sp_commission_rates (sub_mchid, provider, rate_bp, updated_by, created_at, updated_at) VALUES (?,?,?,?,?,?)")
+        .run(DEFAULT_ROW_KEY, "", seed, "env-seed", now, now);
+    return seed;
+}
+
 function createSpCommissionRouter(deps) {
     const router = express.Router();
     const { db } = deps;
@@ -101,4 +116,4 @@ function createSpCommissionRouter(deps) {
     return router;
 }
 
-module.exports = { createSpCommissionRouter, ensureCommissionTables, ratePct, MAX_RATE_BP };
+module.exports = { createSpCommissionRouter, ensureCommissionTables, ratePct, MAX_RATE_BP, getDefaultRateBp, DEFAULT_ROW_KEY };

package/routes/sp-notify.js

@@ -12,6 +12,9 @@
  *     6. 上链 MsgSubmitPaymentFact (失败 warn 不阻塞, chain_txhash 留空等 retryPending 补)
  *     7. 转发商户 webhook (3s 超时, 结果记 forward_status)
  *     8. 按登记的抽佣比例触发微信分账 (默认 mock, WXPAY_PROFITSHARING_ENABLED=true 才真调)
+ *     9. M3 (2026-10-03): 分账台账列 (ps_*) + 触发落行 pending→done/mock/failed + 5min 补扫
+ *        (retryProfitsharingSweep 同步微信真实状态/同号重发) + 启动/进件时注册分账接收方
+ *        (profitsharing.registerDefaultReceivers, 台账幂等)
  *
  * 与直连模式 (agent-pay E2) 的差异: 回调只推到服务商, 服务商验签解密后按 sub_mchid
  * 分发 —— 上链提交支付事实 + 转发/落账给对应商户。
@@ -51,6 +54,16 @@ CREATE TABLE IF NOT EXISTS sp_sub_merchants (
   created_at INTEGER NOT NULL
 );
 `);
+    // M3-2: 分账台账列 (老库兼容: PRAGMA 检查后 ALTER)
+    const cols = db.prepare("PRAGMA table_info(sp_payment_facts)").all().map((c) => c.name);
+    for (const [col, ddl] of [
+        ["ps_out_order_no", "ALTER TABLE sp_payment_facts ADD COLUMN ps_out_order_no TEXT DEFAULT ''"],
+        ["ps_status", "ALTER TABLE sp_payment_facts ADD COLUMN ps_status TEXT DEFAULT ''"],       // ''/pending/mock/done/failed
+        ["ps_amount", "ALTER TABLE sp_payment_facts ADD COLUMN ps_amount INTEGER"],
+        ["ps_at", "ALTER TABLE sp_payment_facts ADD COLUMN ps_at INTEGER"],
+    ]) {
+        if (!cols.includes(col)) db.exec(ddl);
+    }
 }
 
 /** 上链 MsgSubmitPaymentFact (真实通道; 异常上抛, 由调用方降级为 warn 不阻塞)
@@ -102,12 +115,73 @@ async function retryPending(db, opts) {
     return { scanned: rows.length, retried, failed };
 }
 
+/** M3-2: 分账补扫 — 扫 ps_status='pending'/'failed' 的台账行:
+ *  先 queryProfitsharing 同步微信侧真实状态 (FINISHED → done); 仍 failed 的用同 out_order_no
+ *  重发一笔 (微信侧幂等)。mock 模式: pending → mock, failed → 重发 mock 后记 mock。 */
+async function retryProfitsharingSweep(db, opts) {
+    const rows = db.prepare(`SELECT txn_id, sub_mchid, amount, ps_out_order_no, ps_amount, ps_status
+ FROM sp_payment_facts WHERE ps_status IN ('pending','failed') AND ps_out_order_no <> '' LIMIT 20`).all();
+    let synced = 0, retried = 0, failed = 0;
+    const receiverAccount = process.env.WXPAY_SP_MCHID || process.env.WXPAY_MCHID || "";
+    for (const row of rows) {
+        try {
+            const q = await profitsharing.queryProfitsharing(row.ps_out_order_no, { subMchid: row.sub_mchid });
+            if (q && q.mock) {
+                // mock: 无真实状态可同步; failed 行重发一笔 mock 分账
+                if (row.ps_status === "failed") {
+                    await profitsharing.requestProfitsharing({
+                        outTradeNo: row.ps_out_order_no, transactionId: row.txn_id, tradeAmount: row.amount,
+                        subMchid: row.sub_mchid,
+                        receivers: [{ account: receiverAccount, amount: row.ps_amount, description: "服务商抽佣" }],
+                    });
+                    retried++;
+                } else {
+                    synced++;
+                }
+                db.prepare("UPDATE sp_payment_facts SET ps_status='mock', ps_at=? WHERE txn_id=?").run(nowSec(), row.txn_id);
+                continue;
+            }
+            if (q && q.status === 200 && q.json) {
+                const st = String(q.json.state || "");
+                if (/FINISHED|SUCCESS/i.test(st)) {
+                    db.prepare("UPDATE sp_payment_facts SET ps_status='done', ps_at=? WHERE txn_id=?").run(nowSec(), row.txn_id);
+                    synced++;
+                } else if (row.ps_status === "failed") {
+                    // 微信侧未成功 → 同 out_order_no 重发 (幂等)
+                    const r2 = await profitsharing.requestProfitsharing({
+                        outTradeNo: row.ps_out_order_no, transactionId: row.txn_id, tradeAmount: row.amount,
+                        subMchid: row.sub_mchid,
+                        receivers: [{ account: receiverAccount, amount: row.ps_amount, description: "服务商抽佣" }],
+                    });
+                    const ok = r2 && r2.status === 200;
+                    db.prepare("UPDATE sp_payment_facts SET ps_status=?, ps_at=? WHERE txn_id=?").run(ok ? "pending" : "failed", nowSec(), row.txn_id);
+                    if (ok) retried++; else failed++;
+                }
+                // pending 且微信侧还在处理中: 保持 pending 下轮再扫
+            } else {
+                failed++;
+                console.warn(`[sp-notify] 分账补扫查询未成功 out_order_no=${row.ps_out_order_no} status=${q && q.status}`);
+            }
+        } catch (e) {
+            failed++;
+            console.warn(`[sp-notify] 分账补扫失败 txn=${row.txn_id}:`, e && e.message);
+        }
+    }
+    return { scanned: rows.length, synced, retried, failed };
+}
+
 function createSpNotifyRouter(deps) {
     const router = express.Router();
     const { db } = deps;
     ensureTables(db);
     spCommission.ensureCommissionTables(db); // 分账触发要查抽佣表
     const injectedSendTx = deps.sendTx || null; // 测试注入 (绕过真实链)
+    // M3-1: 启动即注册分账接收方 (SP 自身 mchid; 幂等, 台账标记, mock 也落行)
+    profitsharing.registerDefaultReceivers(db)
+        .catch((e) => console.warn("[sp-notify] 分账接收方注册失败 (进件 FINISHED 钩子会再试):", e && e.message));
+    // M3-2: 分账补扫定时器 (5min; 扫 ps_status pending/failed 同步微信真实状态/重发)
+    const psTimer = setInterval(() => { retryProfitsharingSweep(db).catch((e) => console.warn("[sp-notify] 分账补扫异常:", e && e.message)); }, 5 * 60 * 1000);
+    psTimer.unref && psTimer.unref();
 
     /** 上链统一入口: 禁用开关 > 测试注入 > 真实通道 */
     async function sendFact(fact) {
@@ -116,7 +190,8 @@ function createSpNotifyRouter(deps) {
         return submitPaymentFactToChain(fact);
     }
 
-    /** 抽佣分账触发: 按 sp_commission_rates 登记比例, 失败只 warn (mock 默认, 不阻塞回调) */
+    /** 抽佣分账触发: 按 sp_commission_rates 登记比例, 失败只 warn (mock 默认, 不阻塞回调)
+     *  M3-2: 台账落行 pending → 微信/mock 返回后 done/mock/failed; failed/pending 由 retryProfitsharingSweep 补扫 */
     function maybeTriggerProfitsharing(f) {
         try {
             const rate = db.prepare("SELECT rate_bp FROM sp_commission_rates WHERE sub_mchid = ?").get(f.subMchid);
@@ -124,15 +199,22 @@ function createSpNotifyRouter(deps) {
             const commission = Math.floor(f.amount * rate.rate_bp / 10000);
             if (!(commission > 0)) return;
             const receiverAccount = process.env.WXPAY_SP_MCHID || process.env.WXPAY_MCHID || "";
+            const outOrderNo = "ps-" + f.txnId; // 分账单号 (微信侧 out_order_no, 幂等键)
+            // 台账先落 pending (即使后续调用失败也留痕可补扫)
+            db.prepare("UPDATE sp_payment_facts SET ps_out_order_no=?, ps_amount=?, ps_status='pending', ps_at=? WHERE txn_id=?")
+                .run(outOrderNo, commission, nowSec(), f.txnId);
             profitsharing.requestProfitsharing({
-                outTradeNo: "ps-" + f.txnId, // 分账单号 (微信侧 out_order_no, 幂等键)
+                outTradeNo: outOrderNo,
                 transactionId: f.txnId,
                 tradeAmount: f.amount,
                 subMchid: f.subMchid,
                 receivers: [{ account: receiverAccount, amount: commission, description: "服务商抽佣" }],
             }).then((r) => {
-                console.log(`[sp-notify] 分账触发 txn=${f.txnId} commission=${commission} mock=${!!(r && r.mock)}`);
+                const st = (r && r.mock) ? "mock" : (r && r.status === 200 ? "done" : "failed");
+                db.prepare("UPDATE sp_payment_facts SET ps_status=?, ps_at=? WHERE txn_id=?").run(st, nowSec(), f.txnId);
+                console.log(`[sp-notify] 分账触发 txn=${f.txnId} commission=${commission} ps_status=${st} mock=${!!(r && r.mock)}`);
             }).catch((e) => {
+                db.prepare("UPDATE sp_payment_facts SET ps_status='failed', ps_at=? WHERE txn_id=?").run(nowSec(), f.txnId);
                 console.warn(`[sp-notify] 分账触发失败 txn=${f.txnId}:`, e && e.message);
             });
         } catch (e) {
@@ -249,4 +331,4 @@ function createSpNotifyRouter(deps) {
     return router;
 }
 
-module.exports = { createSpNotifyRouter, ensureTables, retryPending, submitPaymentFactToChain };
+module.exports = { createSpNotifyRouter, ensureTables, retryPending, retryProfitsharingSweep, submitPaymentFactToChain };

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-sp-applyment.js

@@ -154,6 +154,8 @@ test("submit mock: 落台账 + 敏感字段加密 (非明文且可还原) + 重
         assert.ok(!row.subject_json.includes("440300199001011234"), "快照不含明文身份证");
         assert.ok(!row.subject_json.includes("6225880212345678"), "快照不含明文卡号");
         assert.ok(row.subject_json.includes("1234"), "脱敏后留后4位");
+        // M3 🟡-1: 进件时刻公示比例快照
+        assert.ok(JSON.parse(row.subject_json).commission_bp_at_apply >= 0, "快照含 commission_bp_at_apply");
 
         // 敏感字段加密断言: 用同一入口 buildApplymentBody 组装, 密文非明文且测试私钥可还原
         const pem = fs.readFileSync(pubKeyPath, "utf8");
@@ -230,24 +232,57 @@ test("GET /api/sp/info 公开名片: 无 admin key 200 + env 覆盖生效", asyn
         assert.strictEqual(j.commission_rate_bp, 100, "默认 1%");
         assert.strictEqual(j.rate_pct, "1.00%");
         assert.ok(j.gateway.includes("127.0.0.1"), "gateway 从 req host 推断");
-        // env 覆盖
+        // env 覆盖: 文本类即时生效; SP_DEFAULT_COMMISSION_BP 只作首次种子 (M3 🟡-1),
+        // 当前库已被首次调用种子为 100 → 需新库验证种子语义
         process.env.SP_NAME = "无锡小播鼠网络科技";
         process.env.SP_DESC = "TrustBase 官方支付服务商";
         process.env.SP_OFFICIAL_URL = "https://trustbase.example.com";
         process.env.SP_CONTACT = "微信: xiaomu";
-        process.env.SP_DEFAULT_COMMISSION_BP = "150";
         process.env.SP_CHAIN_ADDR = "tct1zg7wa9v2gkwp3yvmxrjlmwgfu0tw9vwcuhwwg7";
         r = await fetch(base + "/api/sp/info");
         j = await r.json();
         assert.strictEqual(j.name, "无锡小播鼠网络科技");
         assert.strictEqual(j.contact, "微信: xiaomu");
-        assert.strictEqual(j.commission_rate_bp, 150);
-        assert.strictEqual(j.rate_pct, "1.50%");
+        assert.strictEqual(j.commission_rate_bp, 100, "种子已落表, env 改不动公示比例 (读表优先)");
         assert.strictEqual(j.chain_address, "tct1zg7wa9v2gkwp3yvmxrjlmwgfu0tw9vwcuhwwg7");
     } finally {
         srv.close();
         delete process.env.SP_NAME; delete process.env.SP_DESC; delete process.env.SP_OFFICIAL_URL;
-        delete process.env.SP_CONTACT; delete process.env.SP_DEFAULT_COMMISSION_BP; delete process.env.SP_CHAIN_ADDR;
+        delete process.env.SP_CONTACT; delete process.env.SP_CHAIN_ADDR;
+    }
+});
+
+test("M3 🟡-1: /info 公示比例 env 首种子 + 表行优先 (PUT __default__ 覆盖生效)", async () => {
+    // 新库 + env 种子 250 → 首次读 2.50% 且落表; 之后 admin PUT __default__=200 → 2.00% (env 不再生效)
+    process.env.SP_DEFAULT_COMMISSION_BP = "250";
+    const spCommission = require("./routes/sp-commission");
+    const db = new Database(":memory:");
+    const app = express();
+    app.use(express.json());
+    app.use("/api/sp", spApplyment.createSpApplymentRouter({ db }));
+    app.use("/api/sp", spCommission.createSpCommissionRouter({ db }));
+    const srv = app.listen(0);
+    await new Promise((r) => srv.once("listening", r));
+    const base = `http://127.0.0.1:${srv.address().port}`;
+    try {
+        let j = await (await fetch(base + "/api/sp/info")).json();
+        assert.strictEqual(j.commission_rate_bp, 250);
+        assert.strictEqual(j.rate_pct, "2.50%");
+        const seedRow = db.prepare("SELECT * FROM sp_commission_rates WHERE sub_mchid='__default__'").get();
+        assert.ok(seedRow, "env 首种子落表");
+        assert.strictEqual(seedRow.rate_bp, 250);
+        // admin 改公示比例 → 读表优先
+        const put = await fetch(base + "/api/sp/commission-rate", {
+            method: "PUT", headers: { "Content-Type": "application/json", "x-sp-admin-key": ADMIN_KEY },
+            body: JSON.stringify({ sub_mchid: "__default__", rate_bp: 200 }),
+        });
+        assert.strictEqual(put.status, 200, JSON.stringify(await put.json()));
+        j = await (await fetch(base + "/api/sp/info")).json();
+        assert.strictEqual(j.commission_rate_bp, 200, "PUT __default__ 覆盖生效");
+        assert.strictEqual(j.rate_pct, "2.00%");
+    } finally {
+        srv.close();
+        delete process.env.SP_DEFAULT_COMMISSION_BP;
     }
 });
 

package/test-sp-gateway.js

@@ -359,3 +359,77 @@ test("retryPending: 上链失败台账留空 → 扫出重试补 txhash", async
         process.env.SP_CHAIN_DISABLED = "1";
     }
 });
+
+test("M3-1: 分账接收方注册幂等 (台账标记, 已注册不重复调)", async () => {
+    const db = new Database(":memory:");
+    spNotify.ensureTables(db);
+    // 首次注册 (mock 模式, WXPAY_SP_MCHID=1000686974 已在 env)
+    const r1 = await profitsharing.registerDefaultReceivers(db);
+    assert.strictEqual(r1.registered, true);
+    assert.strictEqual(r1.mock, true);
+    // 台账落行
+    const row = db.prepare("SELECT * FROM sp_ps_receivers WHERE account='1000686974'").get();
+    assert.ok(row, "接收方台账落行");
+    assert.strictEqual(row.mock, 1);
+    // 第二次 → 幂等跳过
+    const r2 = await profitsharing.registerDefaultReceivers(db);
+    assert.strictEqual(r2.registered, false);
+    assert.strictEqual(r2.reason, "already");
+    assert.strictEqual(db.prepare("SELECT COUNT(*) n FROM sp_ps_receivers").get().n, 1);
+});
+
+test("M3-2: 分账台账落行 (pending→mock) + 补扫重试 failed", async () => {
+    const { db, srv, merchantSrv, base } = await startServers();
+    try {
+        insertMerchant(db, SUB_MCHID, "");
+        // 登记抽佣 1% (100bp)
+        await fetch(base + "/commission-rate", {
+            method: "PUT", headers: { "content-type": "application/json", "x-sp-admin-key": ADMIN_KEY },
+            body: JSON.stringify({ sub_mchid: SUB_MCHID, rate_bp: 100 }),
+        });
+        const body = makeNotifyBody({
+            out_trade_no: "tb-ps-1", transaction_id: "4200009999000100",
+            trade_state: "SUCCESS", amount: { total: 10000, currency: "CNY" }, sub_mchid: SUB_MCHID,
+        });
+        const r = await fetch(base + "/notify/wechat", { method: "POST", headers: wxSignHeaders(body), body });
+        assert.strictEqual(r.status, 200);
+        // 分账 fire-and-forget → 等台账 ps_status 落定 (mock 秒回)
+        let row = null;
+        for (let i = 0; i < 50; i++) {
+            row = db.prepare("SELECT * FROM sp_payment_facts WHERE txn_id = ?").get("4200009999000100");
+            if (row && row.ps_status && row.ps_status !== "pending") break;
+            await new Promise((rs) => setTimeout(rs, 20));
+        }
+        assert.strictEqual(row.ps_out_order_no, "ps-4200009999000100", "分账单号落台账");
+        assert.strictEqual(row.ps_amount, 100, "1% 抽佣 = 100 分");
+        assert.strictEqual(row.ps_status, "mock", "mock 模式落 mock");
+        assert.ok(row.ps_at > 0);
+        // 手动置 failed → 补扫重发 (mock) → 回 mock
+        db.prepare("UPDATE sp_payment_facts SET ps_status='failed' WHERE txn_id=?").run("4200009999000100");
+        const res = await spNotify.retryProfitsharingSweep(db);
+        assert.strictEqual(res.scanned, 1);
+        assert.strictEqual(res.retried, 1, "failed 行重发一笔");
+        const row2 = db.prepare("SELECT ps_status FROM sp_payment_facts WHERE txn_id = ?").get("4200009999000100");
+        assert.strictEqual(row2.ps_status, "mock");
+        // 再扫: 无 pending/failed
+        const res2 = await spNotify.retryProfitsharingSweep(db);
+        assert.strictEqual(res2.scanned, 0);
+    } finally { srv.close(); merchantSrv.close(); }
+});
+
+test("M3-2: 无抽佣登记的商户回调 → 分账列留空 (不触发)", async () => {
+    const { db, srv, merchantSrv, base } = await startServers();
+    try {
+        insertMerchant(db, SUB_MCHID, "");
+        const body = makeNotifyBody({
+            out_trade_no: "tb-ps-2", transaction_id: "4200009999000101",
+            trade_state: "SUCCESS", amount: { total: 500 }, sub_mchid: SUB_MCHID,
+        });
+        const r = await fetch(base + "/notify/wechat", { method: "POST", headers: wxSignHeaders(body), body });
+        assert.strictEqual(r.status, 200);
+        await new Promise((rs) => setTimeout(rs, 100));
+        const row = db.prepare("SELECT * FROM sp_payment_facts WHERE txn_id = ?").get("4200009999000101");
+        assert.strictEqual(row.ps_status, "", "未登记抽佣不触发分账");
+        assert.strictEqual(row.ps_out_order_no, "");
+    } finally { srv.close(); merchantSrv.close(); }
+});