trustbase-seller-backend (商户版)

TrustBase 保障链生态的卖家自托管后端: 商品上链 / 订单 / 支付确认 / 单件质押 的写入口。 单卖家形态 — 签名 key 即卖家身份, 私钥不出本机。

给「npx trustbase-shop-init 一键安装器」当依赖用, 也可以独立运行。

快速开始

npm install -g trustbase-seller-backend
cp .env.example .env   # 编辑链端点与卖家 key
tb-seller-backend

前置条件:

• Node.js >= 18
• 卖家身份: 内置生成 (入驻页或首次提交时自动生成, BIP39 24 词 → m/44'/118'/0'/0/0 → tct1 地址, 助记词落盘 tb-keyring/mnemonic.txt, 只存本机)。也可继续用 trustchaind 生成: trustchaind keys add seller --keyring-backend test --home ./tb-keyring (生产建议 keyring-backend=file + 强口令)
• 卖家地址需要 TCT: 上链列表费 (0.5 TCT/条) + 单件质押 (>=1 TCT/件)

✅ 2026-09-21 更新: JS 直签已上线 (core/chain-signer.js)。SIGN_MODE 三态:

• js — cosmjs 直签 (tb-keyring 助记词 → secp256k1 → 广播), 不需要 trustchaind 二进制
• trustchaind — 原 CLI 路径 (保留)
• auto (默认) — 有助记词走 js, 缺失或 js 签名失败自动降级 CLI

Windows 商家机默认 auto, 装好即用, 无需 trustchaind。

🔧 2026-09-22 更新: 路径不再依赖进程 cwd (core/paths.js)。安装目录 = TB_BASE_DIR → <base>/node_modules/trustbase-seller-backend 包布局 → 启动 cwd, 启动时解析一次并冻结; CHAIN_HOME 相对值一律按安装目录解析成绝对路径 (历史故障: cd / 启动 → trustchaind tx sign --home /tb-keyring 空 keyring → 签名失败)。 一条命令自检 (路径/身份/签名通道/链上账户):

tb-seller-doctor          # 或 tb-seller-backend doctor / npm run doctor

启动日志会打印一行 [boot] base=... keyring=... mnemonic=yes/no signMode=js|trustchaind。

🔧 2026-09-23 更新: 运行时数据 (api-keys.json / .encryption-key / auth-sessions.json 等) 迁出 node_modules — 原来落在 <base>/node_modules/data/, npm install <tgz> 升级会把 node_modules 下非声明目录清掉 → 升级即清空全部 API key 和加密密钥 (.215 实际发生过)。 现在统一由 core/runtime-data.js 解析: 默认 <安装目录>/data (node_modules 同级, npm 碰不到), 启动时自动把旧 node_modules/data/ 的数据搬迁过来 (rename 优先, 失败 copy+校验+删, 新目录同名文件先备份 .bak-<ts>); 环境变量 TRUSTBASE_DATA_DIR 可显式覆盖 (优先级最高, doctor 会打印实际目录)。

与插件/安装器的契约

| 端点 | 用途 | 备注 | |---|---|---| | POST /api/products | 商品上架 (sku_prefix=sxo) | wp_post_id=小整数 goods_id | | PUT /api/seller/products/{sku}/update-pledge | 改单件质押 | sku 支持完整 sxo-{id} | | POST /api/orders | 订单上链 | v3.9.4: buyer_address 必填 (真实买家 tct1, 不再回填卖家); 响应带 chain_order_ids + order_intent_hash/order_intent_memo | | POST /api/order/ship | 发货 | 仅 PAID 可发; MsgShipOrder.seller = 签名者; 字段是 tracking_info | | POST /api/order/confirm | 确认收货 (+评分) | 仅 SHIPPED; signer=submitter=本机卖家, buyer 取链上订单; 响应带 submit_path | | POST /api/order/cancel | 取消订单 | 仅 PENDING; signer=seller; canceller 缺省记卖家, initiator:"buyer" 记买家; 链上无 reason 字段 | | POST /api/order/dispute | 发起争议 | SHIPPED/CONFIRMED 且未结算; signer=submitter; memo=tb-auth:<sha256(申诉意愿)> + 原文落 order_intent_log | | POST /api/order/create | ⛔ 410 停用 | 下单走 POST /api/orders (不做第二套) | | POST /api/payments | 支付确认 | order_id 用链上单号 | | GET /api/marketplace/* | 商品搜索/详情 | 未质押不可见 |

/api/order/{ship,confirm,cancel,dispute} 沿用 Bearer JWT 操作员鉴权 (与同文件既有 GET 一致); 签名者恒为本机卖家 key, 与调用方是谁无关 —— 这是"卖家代买家提交"的实现方式。

安全语义 (2026-09-20 起): 订单/支付的 seller/authority 强制取签名 key; 广播后 15s 未入块返回 502 tx_delivery_timeout (调用方走重试); 同账户发送串行化。

v3.9.4 卖家代建单 (2026-09 起, 必须与链升级同批上线): MsgCreateOrder 的 signer = seller (买家不装节点、浏览器不持私钥), buyer 必须由调用方给真实买家 tct1 地址 (非空/合法 bech32/≠卖家, 且该买家已注册 trustcoin 账户); 买家意愿走 tx memo tb-auth:<sha256(整批订单意愿)>, 原文落本地 order_intent_log 备查。 详见 core/order-intent.js 与 POST /api/orders 注释。

v3.9.4 / D2 订单生命周期 (同一批上线, 剧本 §7 的上线顺序):

| 消息 | signer (proto 注解) | "实际发起方"记录字段 | 备注 | |---|---|---|---| | MsgShipOrder | seller | — | 语义未变 | | MsgConfirmOrder | submitter | buyer (keeper 校验 = 订单买家) | 白名单: 订单卖家 / params.dispute_authority / 超时兜底 | | MsgCancelOrder | seller | canceller (buyer 或 seller) | 仅 PENDING; keeper 校验 seller = 订单卖家 | | MsgDisputeOrder | submitter | disputer (buyer 或 seller) | 白名单同 Confirm |

⚠️ 上线顺序 (硬约束): 先发本后端, 再换链。 链升级后旧后端发出的 tx 会全部被链拒 (缺 submitter/seller 字段, 或 buyer == seller); 而本后端不发新语义的 Confirm/Cancel/Dispute, 则"确认收货 / 取消 / 争议"在链上不可用 (订单死锁)。 本仓的 vendored proto (proto/trustchain/order/v1/tx.proto) 已按 trustchain-relmerge 对齐; 再同步链侧 proto 时必须一起 vendor —— protobufjs 对未知字段是静默丢弃, 漏 vendor 的症状是链上 submitter is required, 而不是本地报错。

商户版裁剪 (路线)

当前包是全量 indexer 的直搬 (跑 run-unified.js)。商户版裁剪目标: 只留 chain-writes / marketplace / seller 三组路由 + 健康检查, 去掉 council/oracle/p2p/m2m/mcp 等平台侧组件。裁剪清单见 MERCHANT-EDITION.md。