trustbase-seller-backend 0.1.5 → 0.1.7

package/oracle/c5-glue.js

@@ -38,13 +38,36 @@
  *   幂等: LCD allowances 查已有 grant 直接跳过; 失败 warn 不阻塞后续注册/发放 (状态机无感)。
  *   商户侧: chain-signer/chain-writes 走 FEE_GRANTER_ADDR 代付 (无 grant 自动回退自付)。
  *
+ * N16 feegrant 前置 (xiaomu 批准): N15 的触发点在「审批后」, 全新净室商户提交首笔 KYC 时
+ *   还没拿到 feegrant (0 余额付不了 gas) → 首笔 KYC 卡死。触发点前移到「收到进件材料」:
+ *   ops-console POST /api/sp/materials 入库成功即 (a) 入队 bootstrap grant 行 (与审核通过
+ *   同一 credential_hash 锚点 sha256("license:"+统一社会信用代码), enqueue 按 credential_hash
+ *   + recipient 双去重防双行双发引导金) + (b) grantFeegrantFor() 立即发放。发放失败 warn
+ *   不阻塞材料入库 — 队列行每轮 tick 补发 (stepBootstrapGrant 顶部守卫, LCD 已有 allowance
+ *   静默跳过); 审核退回时撤销还没上链的队列行 (ops-console reject 路径), 防退回商户被自动审批发放。
+ *
  * N14 settle crank (2026-09-23): CONFIRMED 订单过 dispute_window (链上 order params,
  *   默认 259200s=3 天) 后需 MsgSettleOrder 才 settled=true, 否则货款/质押/担保永卡在途。
  *   每 tick 扫描 (无全局订单列表: 本地台账 chain_order_id + 链上 providers 的
  *   by-seller 订单列表), 到期单发 MsgSettleOrder{caller=oracle} (permissionless,
  *   签名者=caller 即可); 每 tick 最多 5 单; 已 settled/非 CONFIRMED 的链上返回按完成处理。
+ *
+ * N17 引导金池自动回补 (2026-09-25, xiaomu 拍板: 全自动 + 开关):
+ *   发放端 (MsgDisburseBootstrap) 早已自动, 注资端此前靠手动 `tx reward pool-transfer`。
+ *   本机制: 每 tick LCD 查引导金池余额, 低于阈值 → MsgRewardPoolTransfer 从 x/reward
+ *   奖励池自动回补 (authority=签名地址, 链上要求 gov 模块或 emergencyAuthority 双轨,
+ *   见 x/reward/keeper/msg_server.go checkPoolTransferAuthority)。
+ *   三道闸 (均可 env 调):
+ *     1. 阈值触发 POOL_REFILL_THRESHOLD_UTCT (默认 500 TCT), 每次补 POOL_REFILL_AMOUNT_UTCT
+ *        (默认 1000 TCT);
+ *     2. 滚动 24h 额度 POOL_REFILL_DAILY_CAP_UTCT (默认 3000 TCT, 本地台账 oracle_pool_refills
+ *        求和) + 划转冷却 POOL_REFILL_COOLDOWN_SECS (默认 600s, 防链上确认前重复发);
+ *     3. 开关两层: POOL_REFILL_ENABLED 总开关 (默认关, 显式开) + kill-switch 文件
+ *        (默认 <db目录>/pool-refill.off, touch 即停 rm 即恢复, 不重启进程; xiaomu 紧急权限)。
  */
 const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
 const chainWrites = require("../routes/chain-writes");
 
 // 链上模块未上线 (v3.9.3 前) 的特征: CLI 本地解码 / CheckTx / DeliverTx / LCD 404 都覆盖
@@ -123,6 +146,13 @@ CREATE TABLE IF NOT EXISTS oracle_credit_grants (
   updated_at INTEGER NOT NULL,
   PRIMARY KEY (reason_kind, ref_id)
 );
+CREATE TABLE IF NOT EXISTS oracle_pool_refills (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  recipient TEXT NOT NULL,       -- 引导金池地址
+  amount TEXT NOT NULL,          -- utct
+  txhash TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
 `);
 }
 
@@ -140,11 +170,14 @@ function createOracleGlue(deps) {
 
     // ============================== C2 引导金 ==============================
 
-    /** 入队 (幂等: credential_hash 已存在 → 返回现状) */
+    /** 入队 (幂等: credential_hash 已存在 → 返回现状; N16: 同 recipient 已有行也返回现状 —
+     *  材料入库预入队与审核通过正式入队两条路只留一行, 防同商户双行 → 双发引导金) */
     function enqueueBootstrapGrant({ recipient, credentialHash }) {
         const ch = credentialHash || sha256Hex(recipient);
         const existing = db.prepare("SELECT * FROM oracle_bootstrap_grants WHERE credential_hash = ?").get(ch);
         if (existing) return { enqueued: false, status: existing.status, credential_hash: ch };
+        const byRecipient = db.prepare("SELECT * FROM oracle_bootstrap_grants WHERE recipient = ? ORDER BY created_at DESC LIMIT 1").get(recipient);
+        if (byRecipient) return { enqueued: false, status: byRecipient.status, credential_hash: byRecipient.credential_hash, deduped_by: "recipient" };
         db.prepare("INSERT INTO oracle_bootstrap_grants (credential_hash, recipient, status, created_at, updated_at) VALUES (?,?,?,?,?)")
             .run(ch, recipient, "pending", nowSec(), nowSec());
         log(`[oracle-glue] bootstrap 入队 recipient=${recipient} credential_hash=${ch.slice(0, 12)}...`);
@@ -223,6 +256,13 @@ function createOracleGlue(deps) {
         }
     }
 
+    /** N16: 立即发放 feegrant (材料入库触发; 签名地址现取 — 与 tick 同一取法, CLI/JS 通道皆可)。
+     *  grantFeegrant 内部 LCD 幂等; 失败返回 false 不抛 (材料入库不阻塞, 队列行下轮补发)。 */
+    async function grantFeegrantFor(recipient) {
+        const oracleAddr = deps.oracleAddr || (await chainWrites.keyAddress(cfg));
+        return grantFeegrant(recipient, oracleAddr);
+    }
+
     /** 单条 bootstrap grant 推进一步 (每 tick 调用; 失败留状态下次重试) */
     async function stepBootstrapGrant(row, oracleAddr) {
         const upd = (fields) => {
@@ -230,6 +270,12 @@ function createOracleGlue(deps) {
                 .run(...Object.values(fields), nowSec(), row.credential_hash);
         };
 
+        // 步骤1.5 (N16): feegrant 前置补发 — 材料入库时已发过则这里 LCD 查到 allowance 静默跳过
+        // (不刷日志); 查无 (首次/上轮失败) 才真正发。商户提交 KYC 前 gas 就已可代付。
+        if (!(await findFeegrant(row.recipient))) {
+            await grantFeegrant(row.recipient, oracleAddr);
+        }
+
         // 步骤2 前置: 找链上实名记录
         if (!row.verification_id) {
             const v = await findVerification(row.recipient);
@@ -268,8 +314,9 @@ function createOracleGlue(deps) {
         }
 
         // 步骤2.4 (N15): 审批已过 → 发 feegrant (商户此后注册/KYC 的手续费由 oracle 代付)。
-        // 失败不阻塞: 注册/发放继续, 下轮 tick 对未 done 行重试。
-        if (!row.disburse_txhash) {
+        // N16 起顶部守卫通常已发过 — 这里 LCD 查到 allowance 静默跳过 (防 waiting_module 等
+        // 多轮停留的行每 tick 刷「已存在」日志); 失败不阻塞: 注册/发放继续, 下轮 tick 重试。
+        if (!row.disburse_txhash && !(await findFeegrant(row.recipient))) {
             await grantFeegrant(row.recipient, oracleAddr);
         }
 
@@ -337,6 +384,89 @@ function createOracleGlue(deps) {
         log(`[oracle-glue] 引导金已发放 recipient=${row.recipient} tx=${r.txhash}`);
     }
 
+    // ============================== N17 引导金池自动回补 ==============================
+
+    const POOL_ADDR = process.env.BOOTSTRAP_POOL_ADDR || "tct1l06faad88784ar4cljf8rcary9n355w4umuh3v";
+    const REFILL_THRESHOLD = BigInt(process.env.POOL_REFILL_THRESHOLD_UTCT || "500000000");   // 500 TCT
+    const REFILL_AMOUNT = process.env.POOL_REFILL_AMOUNT_UTCT || "1000000000";                // 每次 1000 TCT
+    const REFILL_DAILY_CAP = BigInt(process.env.POOL_REFILL_DAILY_CAP_UTCT || "3000000000");  // 滚动 24h 上限 3000 TCT
+    const REFILL_COOLDOWN = Number(process.env.POOL_REFILL_COOLDOWN_SECS || 600);
+    // kill-switch: 文件存在即停 (xiaomu 紧急权限, touch 即停 rm 即恢复, 不用重启进程)
+    const REFILL_KILL_FILE = process.env.POOL_REFILL_KILL_FILE
+        || path.join(path.dirname(db.name || "."), "pool-refill.off");
+    let lastRefillBeatAt = 0;
+
+    /** 开关状态: env 总开关 (默认关) + kill-switch 文件 (运行时可即时停) */
+    function refillEnabled() {
+        if (!/^(1|true|yes|on)$/i.test(process.env.POOL_REFILL_ENABLED || "")) {
+            return { on: false, why: "POOL_REFILL_ENABLED 未开启" };
+        }
+        try {
+            if (fs.existsSync(REFILL_KILL_FILE)) return { on: false, why: `kill-switch 文件存在: ${REFILL_KILL_FILE}` };
+        } catch (_) { /* 检查异常不阻断自动回补 */ }
+        return { on: true, why: "" };
+    }
+
+    /** 引导金池 utct 余额 (LCD 不可达 → null, 不动作; 账户无 utct 行 → 0) */
+    async function poolBalanceUtct() {
+        const j = await lcdGet(`/cosmos/bank/v1beta1/balances/${POOL_ADDR}`);
+        const list = j && j.balances;
+        if (!Array.isArray(list)) return null;
+        const c = list.find((b) => b.denom === "utct");
+        return c ? BigInt(c.amount) : 0n;
+    }
+
+    /** 滚动 24h 回补台账: 已划总额 + 最近一次划转时间 (冷却判定用, 抗进程重启) */
+    function refillWindow() {
+        const since = nowSec() - 86400;
+        const r = db.prepare("SELECT COALESCE(SUM(CAST(amount AS INTEGER)),0) AS used, MAX(created_at) AS lastAt FROM oracle_pool_refills WHERE created_at >= ?").get(since);
+        return { used: BigInt(r.used || 0), lastAt: Number(r.lastAt || 0) };
+    }
+
+    /** 每 tick: 池余额低于阈值 → MsgRewardPoolTransfer 自动回补 (三道闸见文件头 N17) */
+    async function stepPoolRefill(oracleAddr) {
+        const sw = refillEnabled();
+        if (!sw.on) {
+            if (nowSec() - lastRefillBeatAt >= 3600) {
+                lastRefillBeatAt = nowSec();
+                log(`[oracle-glue] N17 池自动回补关闭 (${sw.why})`);
+            }
+            return;
+        }
+        const bal = await poolBalanceUtct();
+        if (bal === null) return; // LCD 不可达, 下轮再看
+        if (bal >= REFILL_THRESHOLD) return;
+        const w = refillWindow();
+        if (w.lastAt && nowSec() - w.lastAt < REFILL_COOLDOWN) {
+            log(`[oracle-glue] N17 回补冷却中 (${nowSec() - w.lastAt}s < ${REFILL_COOLDOWN}s), 下轮再试`);
+            return;
+        }
+        if (w.used + BigInt(REFILL_AMOUNT) > REFILL_DAILY_CAP) {
+            warn(`[oracle-glue] ⚠️ N17 滚动24h额度用尽 (used=${w.used} cap=${REFILL_DAILY_CAP} utct), 池余额 ${bal} utct 仍低于阈值 — 需人工介入`);
+            return;
+        }
+        let r;
+        try {
+            r = await sendTx([{
+                "@type": "/trustchain.reward.v1.MsgRewardPoolTransfer",
+                authority: oracleAddr,
+                recipient: POOL_ADDR,
+                amount: REFILL_AMOUNT,
+            }]);
+        } catch (e) {
+            warn(`[oracle-glue] N17 回补异常: ${e.message} (下轮重试)`);
+            return;
+        }
+        if (r.code !== 0) {
+            if (MODULE_NOT_LIVE_RE.test(r.raw_log)) { warn("[oracle-glue] reward 模块未上线, N17 回补留待下轮"); return; }
+            warn(`[oracle-glue] N17 回补失败 code=${r.code}: ${String(r.raw_log).slice(0, 200)} (下轮重试)`);
+            return;
+        }
+        db.prepare("INSERT INTO oracle_pool_refills (recipient, amount, txhash, created_at) VALUES (?,?,?,?)")
+            .run(POOL_ADDR, REFILL_AMOUNT, r.txhash, nowSec());
+        log(`[oracle-glue] N17 引导金池已回补 amount=${REFILL_AMOUNT}utct pool=${POOL_ADDR} tx=${r.txhash} (触发时余额 ${bal} utct < 阈值 ${REFILL_THRESHOLD})`);
+    }
+
     // ============================== E6 积分结算 ==============================
 
     /** 链上 economy params (奖励金额/月度额度, 不读缓存, 每次结算现查) */
@@ -572,7 +702,7 @@ function createOracleGlue(deps) {
         }
     }
 
-    /** 每 tick: 推进 bootstrap 队列 + E6 结算 + N14 settle 扫描。签名地址每轮现取 (CLI/JS 通道皆可) */
+    /** 每 tick: N17 池回补检查 + 推进 bootstrap 队列 + E6 结算 + N14 settle 扫描。签名地址每轮现取 (CLI/JS 通道皆可) */
     async function tick() {
         let oracleAddr = deps.oracleAddr;
         if (!oracleAddr) {
@@ -583,6 +713,11 @@ function createOracleGlue(deps) {
                 return;
             }
         }
+        try {
+            await stepPoolRefill(oracleAddr);
+        } catch (e) {
+            warn(`[oracle-glue] N17 池回补检查异常: ${e.message} (不阻塞其他步骤)`);
+        }
         const rows = db.prepare("SELECT * FROM oracle_bootstrap_grants WHERE status NOT IN ('done')").all();
         for (const row of rows) {
             try {
@@ -597,7 +732,7 @@ function createOracleGlue(deps) {
         await settleExpiredOrders(oracleAddr);
     }
 
-    return { tick, enqueueBootstrapGrant, settleConfirmedFacts, settleExpiredOrders, stepBootstrapGrant, getEconomyParams, monthlyUsed, resolveOrderParties, settleFact, grantFeegrant, findFeegrant };
+    return { tick, enqueueBootstrapGrant, settleConfirmedFacts, settleExpiredOrders, stepBootstrapGrant, getEconomyParams, monthlyUsed, resolveOrderParties, settleFact, grantFeegrant, grantFeegrantFor, findFeegrant, stepPoolRefill, refillEnabled, poolBalanceUtct, refillWindow };
 }
 
 module.exports = { createOracleGlue, oracleCfg, sha256Hex, MODULE_NOT_LIVE_RE };

package/oracle/ops-console.js

@@ -6,6 +6,8 @@
  *   - 账号体系: 首次访问创建管理员 (用户名+密码); scrypt 哈希; 会话 cookie (HMAC 签名, 12h)
  *   - 商家进件资料接收: POST /api/sp/materials (独立低权密钥, 只允许这一个动作)
  *   - 审核台: 列出待审商家 → 查看资料/证件 → 预审通过 (触发 C2 引导金: approve + disburse) / 退回 (带理由)
+ *   - N16 feegrant 前置: 材料入库成功即预入队 bootstrap grant + 立即发 feegrant (全新净室
+ *     商户 0 余额也能付首笔 KYC gas); 退回时撤销还没上链的队列行。幂等与发放细节见 c5-glue.js N16。
  *
  * 边界:
  *   - 私钥永不进本模块; 通过 onApprove 回调交给 c5-glue (oracle 侧 CLI/JS 签名)
@@ -15,6 +17,7 @@
 const crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");
+const { createOracleGlue } = require("./c5-glue");
 
 const SESSION_COOKIE = "oc_sess";
 const SESSION_TTL_SEC = 12 * 3600;
@@ -46,6 +49,15 @@ function createOpsConsole(deps) {
     const say = log || ((...a) => console.log("[ops-console]", ...a));
     const loginFails = new Map(); // ip -> {count, until}
 
+    // N16: 材料入库触发的 glue 实例 (惰性建)。oracle-sync 只注入 db/materialsDir/onApprove,
+    // 拿不到主 glue — 这里自建: createOracleGlue 无定时器无副作用, 共用同一 index.db 连接,
+    // 发链走 chain-writes 模块级串行锁, 与 oracle-sync 的主实例并发安全。
+    let n16Glue = null;
+    function materialsGlue() {
+        if (!n16Glue) n16Glue = createOracleGlue({ db });
+        return n16Glue;
+    }
+
     db.exec(`
 CREATE TABLE IF NOT EXISTS oracle_admins (
   username TEXT PRIMARY KEY,
@@ -563,6 +575,11 @@ scheduleRefresh();
                     }
                     db.prepare("UPDATE sp_materials SET review_status = ?, review_note = ?, reviewer = ?, reviewed_at = ? WHERE tb_address = ?")
                         .run(decision === "approve" ? "approved" : "rejected", note, u.username, Math.floor(Date.now() / 1000), addr);
+                    if (decision === "reject") {
+                        // N16: 材料入库已预入队 — 退回即撤销还没上链的队列行 (approve/disburse 都没发才撤),
+                        // 防被退回商户提交 KYC 后被自动审批 + 发放引导金。重新提交材料会重新入队。
+                        db.prepare("DELETE FROM oracle_bootstrap_grants WHERE recipient = ? AND IFNULL(approve_txhash,'') = '' AND IFNULL(disburse_txhash,'') = ''").run(addr);
+                    }
                     say("review", decision, addr, "by", u.username);
                     json(200, { ok: true, message: decision === "approve" ? "已通过, 引导金已入队 (链上模块就绪后自动发放)" : "已退回, 请通知商家修改后重新提交" });
                 });
@@ -605,6 +622,20 @@ scheduleRefresh();
                               review_status = 'pending', review_note = '', reviewer = '', reviewed_at = 0`)
                     .run(addr, String(fields.merchant_name || ""), JSON.stringify(fields), JSON.stringify(files), String(b.bundle_hash || ""), Math.floor(Date.now() / 1000));
                 say("materials received:", addr, "files:", Object.keys(files).join(","));
+                // N16: 材料入库成功 → 预入队 bootstrap grant + 立即发 feegrant (feegrant 前置)。
+                // credential_hash 与审核通过同一锚点 (sha256("license:"+统一社会信用代码));
+                // enqueue 双去重 + LCD allowances 去重 → 重复提交材料不重复发。失败只 warn
+                // 不阻塞材料入库 — 队列行每轮 tick 补发 (c5-glue stepBootstrapGrant 顶部守卫)。
+                try {
+                    const licKey = String(fields.license_no || "").toUpperCase().replace(/[\s-]/g, "");
+                    const licHash = licKey ? crypto.createHash("sha256").update("license:" + licKey).digest("hex") : undefined;
+                    const enq = materialsGlue().enqueueBootstrapGrant({ recipient: addr, credentialHash: licHash });
+                    void materialsGlue().grantFeegrantFor(addr).then(
+                        (ok) => say("N16 feegrant 前置:", addr, "enqueued:", enq.enqueued, "granted:", ok),
+                        (e) => say("⚠️ N16 feegrant 前置失败 (tick 补发):", addr, String(e && e.message || e)));
+                } catch (e) {
+                    say("⚠️ N16 预入队失败 (不阻塞材料入库):", addr, String(e && e.message || e));
+                }
                 json(200, { ok: true, message: "资料已收到, 等待审核" });
             });
             return true;

package/package.json

@@ -1,73 +1,73 @@
-{
-  "name": "trustbase-seller-backend",
-  "version": "0.1.5",
-  "description": "TrustBase Seller Backend (merchant edition) — 商品上链/订单/支付/质押 write API for TrustBase 保障链生态. 单卖家自托管形态: 签名 key 即卖家身份, 私钥不出门.",
-  "main": "run-unified.js",
-  "bin": {
-    "tb-seller-backend": "./bin/tb-seller-backend.js",
-    "tb-seller-doctor": "./bin/tb-doctor.js"
-  },
-  "scripts": {
-    "start": "node run-unified.js",
-    "doctor": "node bin/tb-doctor.js"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "trustbase",
-    "trustchain",
-    "marketplace",
-    "seller",
-    "insurance",
-    "cosmos"
-  ],
-  "license": "MIT",
-  "dependencies": {
-    "@chainsafe/libp2p-noise": "^17.0.0",
-    "@cosmjs/amino": "^0.38.1",
-    "@cosmjs/crypto": "^0.38.1",
-    "@cosmjs/encoding": "^0.38.1",
-    "@cosmjs/proto-signing": "^0.38.1",
-    "@cosmjs/stargate": "^0.38.1",
-    "@maxmind/geoip2-node": "^7.1.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@noble/curves": "^1.9.7",
-    "@scure/bip32": "^2.4.0",
-    "@scure/bip39": "^1.2.0",
-    "axios": "^1.16.1",
-    "bcrypt": "^6.0.0",
-    "bech32": "^2.0.0",
-    "better-sqlite3": "^11.0.0",
-    "bip39": "^3.1.0",
-    "cors": "^2.8.6",
-    "dotenv": "^17.4.2",
-    "eventemitter3": "^5.0.0",
-    "express": "^4.21.0",
-    "http-proxy-middleware": "^3.0.5",
-    "it-handshake": "^4.1.3",
-    "it-length-prefixed": "^11.0.1",
-    "it-pipe": "^3.0.1",
-    "jsqr": "^1.4.0",
-    "nodemailer": "^10.0.10",
-    "pg": "^8.23.0",
-    "pino": "^9.0.0",
-    "protobufjs": "^8.8.0",
-    "qrcode": "^1.5.4",
-    "selfsigned": "^5.5.0",
-    "thirty-two": "^1.0.2",
-    "uint8arrays": "^6.1.1",
-    "uuid": "^9.0.0",
-    "ws": "^8.20.1",
-    "zod": "^3.23.0"
-  },
-  "optionalDependencies": {
-    "canvas": "^3.2.3"
-  },
-  "overrides": {
-    "requires-port": "^1.0.0"
-  },
-  "allowScripts": {
-    "better-sqlite3@11.10.0": true
-  }
-}
+{
+  "name": "trustbase-seller-backend",
+  "version": "0.1.7",
+  "description": "TrustBase Seller Backend (merchant edition) — 商品上链/订单/支付/质押 write API for TrustBase 保障链生态. 单卖家自托管形态: 签名 key 即卖家身份, 私钥不出门.",
+  "main": "run-unified.js",
+  "bin": {
+    "tb-seller-backend": "./bin/tb-seller-backend.js",
+    "tb-seller-doctor": "./bin/tb-doctor.js"
+  },
+  "scripts": {
+    "start": "node run-unified.js",
+    "doctor": "node bin/tb-doctor.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "trustbase",
+    "trustchain",
+    "marketplace",
+    "seller",
+    "insurance",
+    "cosmos"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@chainsafe/libp2p-noise": "^17.0.0",
+    "@cosmjs/amino": "^0.38.1",
+    "@cosmjs/crypto": "^0.38.1",
+    "@cosmjs/encoding": "^0.38.1",
+    "@cosmjs/proto-signing": "^0.38.1",
+    "@cosmjs/stargate": "^0.38.1",
+    "@maxmind/geoip2-node": "^7.1.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@noble/curves": "^1.9.7",
+    "@scure/bip32": "^2.4.0",
+    "@scure/bip39": "^1.2.0",
+    "axios": "^1.16.1",
+    "bcrypt": "^6.0.0",
+    "bech32": "^2.0.0",
+    "better-sqlite3": "^11.0.0",
+    "bip39": "^3.1.0",
+    "cors": "^2.8.6",
+    "dotenv": "^17.4.2",
+    "eventemitter3": "^5.0.0",
+    "express": "^4.21.0",
+    "http-proxy-middleware": "^3.0.5",
+    "it-handshake": "^4.1.3",
+    "it-length-prefixed": "^11.0.1",
+    "it-pipe": "^3.0.1",
+    "jsqr": "^1.4.0",
+    "nodemailer": "^10.0.10",
+    "pg": "^8.23.0",
+    "pino": "^9.0.0",
+    "protobufjs": "^8.8.0",
+    "qrcode": "^1.5.4",
+    "selfsigned": "^5.5.0",
+    "thirty-two": "^1.0.2",
+    "uint8arrays": "^6.1.1",
+    "uuid": "^9.0.0",
+    "ws": "^8.20.1",
+    "zod": "^3.23.0"
+  },
+  "optionalDependencies": {
+    "canvas": "^3.2.3"
+  },
+  "overrides": {
+    "requires-port": "^1.0.0"
+  },
+  "allowScripts": {
+    "better-sqlite3@11.10.0": true
+  }
+}

package/payments/wechat/profitsharing.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * profitsharing.js — 微信分账 APIv3 骨架 (服务商 partner / 直连通用, 2026-09-26)
+ *
+ * 纯函数模块, 不依赖 Express, 可独立单测:
+ *   addReceivers(receivers)               POST /v3/profitsharing/receivers/add
+ *   requestProfitsharing(params)          POST /v3/profitsharing/orders
+ *   queryProfitsharing(outOrderNo, opts)  GET  /v3/profitsharing/orders/{out_order_no}
+ *
+ * 开关: env WXPAY_PROFITSHARING_ENABLED=true 才真调微信; 默认 mock (log + 返回 {mock:true})。
+ * 身份: SP 模式 (WXPAY_SP_MCHID 已配) 用服务商身份签名 (wxSignAuth override),
+ *       body 带 appid + sp_mchid (+ sub_mchid); 未配则回落直连商户身份。
+ * 金额护栏: 单笔接收方金额 ≤ 交易金额 × 30% (硬顶, 与 sp-commission MAX_RATE_BP 对齐),
+ *           且 ≤ 交易金额本身; 护栏在 mock 模式同样生效 (先于一切网络调用)。
+ */
+const agentPay = require("../../routes/agent-pay");
+
+const MAX_SHARE_BP = 3000; // 单笔分账 ≤ 交易金额 30% (硬顶)
+
+/** env 现读 (测试可改 env, 无缓存状态) */
+function wxCfg() {
+    return {
+        gateway: process.env.WXPAY_GATEWAY || "https://api.mch.weixin.qq.com",
+        appid: process.env.WXPAY_APPID || "",
+        mchid: process.env.WXPAY_MCHID || "",
+        spMchid: process.env.WXPAY_SP_MCHID || "",
+        spSerial: process.env.WXPAY_SP_SERIAL || "",
+        spKeyPath: process.env.WXPAY_SP_KEY_PATH || "",
+        enabled: String(process.env.WXPAY_PROFITSHARING_ENABLED || "").toLowerCase() === "true",
+    };
+}
+
+/** SP 模式签名身份 override (未配 SP → undefined, wxSignAuth 回落直连商户身份) */
+function spOverride(c) {
+    return c.spMchid ? { mchid: c.spMchid, serial: c.spSerial, keyPath: c.spKeyPath } : undefined;
+}
+
+/** 统一调用入口: mock 模式只 log 不打网; 真调走 APIv3 签名 (复用 agent-pay wxSignAuth) */
+async function wxCall(method, urlPath, bodyObj) {
+    const c = wxCfg();
+    if (!c.enabled) {
+        console.log(`[profitsharing] mock ${method} ${urlPath}${bodyObj ? " " + JSON.stringify(bodyObj).slice(0, 200) : ""}`);
+        return { mock: true };
+    }
+    const bodyStr = bodyObj ? JSON.stringify(bodyObj) : "";
+    const r = await fetch(c.gateway + urlPath, {
+        method,
+        headers: {
+            "Authorization": agentPay.wxSignAuth(method, urlPath, bodyStr, spOverride(c)),
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": "trustbase-seller-backend/1.0",
+        },
+        body: method === "GET" ? undefined : bodyStr,
+        signal: AbortSignal.timeout(15000),
+    });
+    const j = await r.json().catch(() => ({}));
+    return { status: r.status, json: j };
+}
+
+/** 金额护栏: 正整数分, ≤ 交易金额, 且 ≤ 交易金额×30% (mock 模式同样生效) */
+function assertShareAmount(tradeAmount, shareAmount) {
+    if (!Number.isInteger(tradeAmount) || tradeAmount <= 0) {
+        throw new Error("trade_amount 必须是正整数 (分)");
+    }
+    if (!Number.isInteger(shareAmount) || shareAmount <= 0) {
+        throw new Error("分账金额必须是正整数 (分)");
+    }
+    if (shareAmount > tradeAmount) {
+        throw new Error(`分账金额 ${shareAmount} 超过交易金额 ${tradeAmount}`);
+    }
+    const cap = Math.floor(tradeAmount * MAX_SHARE_BP / 10000);
+    if (shareAmount > cap) {
+        throw new Error(`分账金额 ${shareAmount} 超过 30% 硬顶 (${cap})`);
+    }
+}
+
+/** 添加分账接收方 (服务商自己 mchid 或指定商户号)
+ *  receivers: [{account, type?, name?, relation_type?, sub_mchid?}] */
+async function addReceivers(receivers) {
+    const c = wxCfg();
+    const list = Array.isArray(receivers) ? receivers : [receivers];
+    if (!list.length) throw new Error("receivers 必填且非空");
+    const results = [];
+    for (const rcv of list) {
+        if (!rcv || !rcv.account) throw new Error("receiver.account 必填");
+        const body = {
+            appid: c.appid,
+            type: rcv.type || "MERCHANT_ID",
+            account: String(rcv.account),
+            relation_type: rcv.relation_type || "SERVICE_PROVIDER",
+        };
+        if (rcv.name) body.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);
+        }
+        const r = await wxCall("POST", "/v3/profitsharing/receivers/add", body);
+        results.push(r.mock ? { mock: true, account: body.account } : r);
+    }
+    return results.length === 1 ? results[0] : results;
+}
+
+/** 请求分账
+ *  params: {outTradeNo(分账单号 out_order_no, 幂等键), transactionId(微信支付单号),
+ *           tradeAmount(交易金额分, 护栏基准), subMchid?, unfreezeUnsplit?,
+ *           receivers: [{account, amount, description, type?}]} */
+async function requestProfitsharing(params) {
+    const c = wxCfg();
+    const p = params || {};
+    if (!p.outTradeNo || !p.transactionId) throw new Error("outTradeNo/transactionId 必填");
+    if (!Array.isArray(p.receivers) || !p.receivers.length) throw new Error("receivers 必填且非空");
+    for (const rcv of p.receivers) {
+        if (!rcv || !rcv.account) throw new Error("receiver.account 必填");
+        assertShareAmount(p.tradeAmount, rcv.amount); // 护栏先于一切网络调用
+    }
+    const body = {
+        appid: c.appid,
+        transaction_id: String(p.transactionId),
+        out_order_no: String(p.outTradeNo),
+        receivers: p.receivers.map((r) => ({
+            type: r.type || "MERCHANT_ID",
+            account: String(r.account),
+            amount: r.amount,
+            description: String(r.description || "服务商分账").slice(0, 80),
+        })),
+        unfreeze_unsplit: p.unfreezeUnsplit !== false,
+    };
+    if (c.spMchid) {
+        body.sp_mchid = c.spMchid;
+        if (p.subMchid) body.sub_mchid = String(p.subMchid);
+    }
+    const r = await wxCall("POST", "/v3/profitsharing/orders", body);
+    return r.mock ? { mock: true, out_order_no: body.out_order_no, receivers: body.receivers } : r;
+}
+
+/** 查询分账结果 (partner 模式须带 sub_mchid 查询串) */
+async function queryProfitsharing(outOrderNo, opts) {
+    const c = wxCfg();
+    if (!outOrderNo) throw new Error("outOrderNo 必填");
+    let urlPath = `/v3/profitsharing/orders/${encodeURIComponent(String(outOrderNo))}`;
+    const subMchid = opts && opts.subMchid;
+    if (c.spMchid && subMchid) urlPath += `?sub_mchid=${encodeURIComponent(String(subMchid))}`;
+    const r = await wxCall("GET", urlPath, null);
+    return r.mock ? { mock: true, out_order_no: String(outOrderNo) } : r;
+}
+
+module.exports = { addReceivers, requestProfitsharing, queryProfitsharing, assertShareAmount, MAX_SHARE_BP };