trustbase-seller-backend 0.6.1 → 0.7.1

package/api/seller-products.js

@@ -22,7 +22,27 @@ exports.createSellerProductsRouter = createSellerProductsRouter;
 const express_1 = require("express");
 const crypto_1 = require("crypto");
 const wallet_auth_1 = require("../middleware/wallet-auth");
+// A1: 复用 buyer-shop 的建表/迁移 (它已 export ensureBuyerTables; 无反向依赖, 无循环引用风险)
+const buyer_shop_1 = require("../routes/buyer-shop");
 const VALID_STATUSES = ['draft', 'active', 'out_of_stock', 'archived'];
+/**
+ * A1 商品类型白名单 —— 与 `buyer-shop.js` 下单侧判定**同一口径**（`physical` 要收货地址,
+ * `virtual` 免地址并生成交付凭证）。
+ *
+ * ⚠️ 这里**显式拒绝**非法值而不是静默回退成 `physical`：下单侧是
+ * `=== 'virtual' ? virtual : physical`, 若上架时误传链上枚举名（如 `saas`）却被静默存成
+ * `physical`, 买家买虚拟商品时会被迫填收货地址 —— 那是静默的业务错误, 比 400 更糟。
+ * 缺省才回退 `physical`（向后兼容：老客户端不传该字段不受影响）。
+ *
+ * 注：链上 proto 的 5 值枚举（UNSPECIFIED/PHYSICAL/DIGITAL/SAAS/SERVICE）与此处的 2 值
+ * 不是同一套口径, 映射规则待 xiaomu 拍板后在此处收敛。
+ */
+const VALID_PRODUCT_TYPES = ['physical', 'virtual'];
+/** 缺省 `physical`（DB 列 `NOT NULL DEFAULT 'physical'`, 与之保持一致） */
+const DEFAULT_PRODUCT_TYPE = 'physical';
+function normalizeProductType(value) {
+    return typeof value === 'string' && value !== '' ? value : DEFAULT_PRODUCT_TYPE;
+}
 function parsePagination(req) {
     const page = Math.max(1, parseInt(String(req.query.page || '1'), 10) || 1);
     const pageSize = Math.min(100, Math.max(1, parseInt(String(req.query.page_size || '20'), 10) || 20));
@@ -34,6 +54,16 @@ function parsePagination(req) {
 function createSellerProductsRouter(config) {
     const router = (0, express_1.Router)();
     const { db, enableAuth = true } = config;
+    // A1: 建品/改品要写 `product_type`, 老库没这列会直接
+    // `table store_products has no column named product_type` → 商家建品 500。
+    // `buyer-shop` 也会建这列, 但两个 router 的加载顺序不保证谁先到, 这里自建一次兜底
+    // (`ensureBuyerTables` 内部对已存在的列是 no-op, 重复调用安全)。
+    try {
+        (0, buyer_shop_1.ensureBuyerTables)(db);
+    }
+    catch (e) {
+        console.warn('[seller-products] ensureBuyerTables 失败 (建品可能受影响):', e.message);
+    }
     // Lesson #308: 全部端点走 wallet signature 鉴权
     if (enableAuth !== false) {
         router.use((0, wallet_auth_1.walletAuth)());
@@ -143,6 +173,15 @@ function createSellerProductsRouter(config) {
                     errorMessage: `status must be one of ${VALID_STATUSES.join('|')}, got ${status}`,
                 });
             }
+            // A1: 商品类型 (缺省 physical; 非法值显式 400 —— 不静默降级, 见 VALID_PRODUCT_TYPES 注释)
+            const productType = normalizeProductType(input.product_type);
+            if (!VALID_PRODUCT_TYPES.includes(productType)) {
+                return res.status(400).json({
+                    success: false,
+                    errorCode: 'INVALID_PRODUCT_TYPE',
+                    errorMessage: `product_type must be one of ${VALID_PRODUCT_TYPES.join('|')}, got ${input.product_type}`,
+                });
+            }
             // 2. 验商家注册 (Lesson #266b: 必须在 store_settings 中 active 才能创建商品)
             const sellerSetting = db
                 .prepare(`SELECT status FROM store_settings WHERE seller_address = ?`)
@@ -160,9 +199,9 @@ function createSellerProductsRouter(config) {
             const tagsJson = JSON.stringify(input.tags || []);
             db.prepare(`INSERT INTO store_products (
           id, seller_address, title, description, price_utct, stock,
-          status, category, image_url, tags, featured, sales_count,
+          status, category, image_url, tags, featured, sales_count, product_type,
           created_at, updated_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, 0, ?, ?)`).run(productId, sellerAddress, input.title, input.description || '', input.price_utct, input.stock, status, input.category || 'general', input.image_url || null, tagsJson, now, now);
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, 0, ?, ?, ?)`).run(productId, sellerAddress, input.title, input.description || '', input.price_utct, input.stock, status, input.category || 'general', input.image_url || null, tagsJson, productType, now, now);
             // 4. 返回 (Lesson #335: 字段一致)
             const product = db
                 .prepare(`SELECT * FROM store_products WHERE id = ?`)
@@ -268,10 +307,21 @@ function createSellerProductsRouter(config) {
             // 4. 更新
             const now = Date.now();
             const tagsJson = input.tags !== undefined ? JSON.stringify(input.tags) : row.tags;
+            // A1: 商品类型可改 (缺省沿用原值; 非法值显式 400 —— 不静默降级)
+            if (input.product_type !== undefined && !VALID_PRODUCT_TYPES.includes(input.product_type)) {
+                return res.status(400).json({
+                    success: false,
+                    errorCode: 'INVALID_PRODUCT_TYPE',
+                    errorMessage: `product_type must be one of ${VALID_PRODUCT_TYPES.join('|')}, got ${input.product_type}`,
+                });
+            }
+            const nextProductType = input.product_type !== undefined
+                ? input.product_type
+                : normalizeProductType(row.product_type);
             db.prepare(`UPDATE store_products SET
           title = ?, description = ?, price_utct = ?, category = ?,
-          image_url = ?, tags = ?, status = ?, updated_at = ?
-         WHERE id = ?`).run(input.title !== undefined ? input.title : row.title, input.description !== undefined ? input.description : row.description, input.price_utct !== undefined ? input.price_utct : row.price_utct, input.category !== undefined ? input.category : row.category, input.image_url !== undefined ? input.image_url : row.image_url, tagsJson, newStatus, now, productId);
+          image_url = ?, tags = ?, status = ?, product_type = ?, updated_at = ?
+         WHERE id = ?`).run(input.title !== undefined ? input.title : row.title, input.description !== undefined ? input.description : row.description, input.price_utct !== undefined ? input.price_utct : row.price_utct, input.category !== undefined ? input.category : row.category, input.image_url !== undefined ? input.image_url : row.image_url, tagsJson, newStatus, nextProductType, now, productId);
             // 5. 返回
             const updated = db
                 .prepare(`SELECT * FROM store_products WHERE id = ?`)
@@ -446,6 +496,8 @@ function rowToProduct(row) {
         tags,
         featured: row.featured === 1 ? 1 : 0,
         sales_count: row.sales_count,
+        // A1: 缺列的老库 / NULL 一律按 physical —— 与下单侧判定同口径
+        product_type: normalizeProductType(row.product_type),
         created_at: row.created_at,
         updated_at: row.updated_at,
     };

package/db/store-migrate.js

@@ -88,6 +88,8 @@ function runStoreMigrations(db) {
         `ALTER TABLE store_products ADD COLUMN chain_listed_at INTEGER`,
         `ALTER TABLE store_products ADD COLUMN chain_tx_hash TEXT`,
         `ALTER TABLE store_products ADD COLUMN chain_stake_per_unit INTEGER`,
+        // A1 (2026-10-05): 商品类型驱动收货地址 — physical(默认) 实物 / virtual 虚拟
+        `ALTER TABLE store_products ADD COLUMN product_type TEXT NOT NULL DEFAULT 'physical'`,
     ];
     for (const stmt of alterStatements) {
         try {

package/package.json

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

package/routes/agent-pay.js

@@ -70,8 +70,9 @@ CREATE INDEX IF NOT EXISTS idx_aps_state ON agent_pay_sessions(state);
         if (!_c.includes("sub_mchid")) db.exec("ALTER TABLE agent_pay_sessions ADD COLUMN sub_mchid TEXT DEFAULT ''");
     } catch (_) {}
 
-    // 2026-09-20 E4': 物流列 (老库兼容)
-    for (const col of ["carrier TEXT DEFAULT ''", "tracking_no TEXT DEFAULT ''", "logistics_state TEXT DEFAULT ''", "timeline TEXT DEFAULT '[]'", "shopxo_order_no_ref TEXT DEFAULT ''"]) {
+    // 2026-09-20 E4': 物流列 (老库兼容) + A1 收货地址/交付凭据列
+    for (const col of ["carrier TEXT DEFAULT ''", "tracking_no TEXT DEFAULT ''", "logistics_state TEXT DEFAULT ''", "timeline TEXT DEFAULT '[]'", "shopxo_order_no_ref TEXT DEFAULT ''",
+        "shipping_address TEXT DEFAULT ''", "delivery_credential TEXT DEFAULT ''"]) {
         try { db.exec("ALTER TABLE agent_pay_sessions ADD COLUMN " + col); } catch (e) { /* 已存在 */ }
     }
 }

package/routes/buyer-shop.js

@@ -31,6 +31,9 @@
  *
  * 下单要点:
  *   - 价格权威 = 本地 DB (单价 × qty 算总分), 客户端传的任何金额字段一律忽略
+ *   - A1 (2026-10-05 设计方案): product_type 驱动收货地址 — physical 强制 shipping_address
+ *     (缺失 400 SHIPPING_ADDRESS_REQUIRED), virtual 免地址并生成 delivery_credential
+ *     (license 格式 tb-license-{order_ref}-{random4}); 无 product_type 列/字段默认 physical
  *   - qty 整数 >=1 且不超库存; 单价折算后 <= 0 分 → 409 (微信不支持 0 元单)
  *   - 幂等两级: ① body.client_order_no → client_session_id='buyer:{card}:{no}' 同号返原单
  *     ② 无 client_order_no → 同 buyer_card+product_id 5 分钟窗口内未支付未过期单直接复用
@@ -93,11 +96,19 @@ CREATE TABLE IF NOT EXISTS agent_pay_sessions (
   updated_at INTEGER NOT NULL
 );
 `);
-    // 老库兼容: agent-pay 的物流列 + U7 分账标记列 (已存在则跳过)
+    // 老库兼容: agent-pay 的物流列 + Lane C 商户号列 + U7 分账标记列 + A1 收货地址/交付凭据列 (已存在则跳过)
     for (const col of ["carrier TEXT DEFAULT ''", "tracking_no TEXT DEFAULT ''", "logistics_state TEXT DEFAULT ''", "timeline TEXT DEFAULT '[]'", "shopxo_order_no_ref TEXT DEFAULT ''",
-        "ps_flag INTEGER NOT NULL DEFAULT 0"]) { // U7: 1=下单带 settle_info.profit_sharing (rate>0 且 SP 模式)
+        "sub_mchid TEXT DEFAULT ''",          // Lane C: 本单所属特约商户 (INSERT 引用; 0.4.3 教训: 写路径自建, 不依赖 agent-pay 先跑)
+        "ps_flag INTEGER NOT NULL DEFAULT 0", // U7: 1=下单带 settle_info.profit_sharing (rate>0 且 SP 模式)
+        "shipping_address TEXT DEFAULT ''",   // A1: 实物订单收货地址 (虚拟单允许空)
+        "delivery_credential TEXT DEFAULT ''" // A1: 虚拟商品交付凭据 (license/兑换码; 实物单为空)
+    ]) {
         try { db.exec("ALTER TABLE agent_pay_sessions ADD COLUMN " + col); } catch (e) { /* 已存在 */ }
     }
+    // A1 商品类型: store_products 补 product_type (写路径自建, 不依赖 store-migrate 先跑; 表不存在则跳过)
+    if (hasTable(db, "store_products")) {
+        try { db.exec("ALTER TABLE store_products ADD COLUMN product_type TEXT NOT NULL DEFAULT 'physical'"); } catch (e) { /* 已存在 */ }
+    }
 }
 
 function hasTable(db, name) {
@@ -247,6 +258,8 @@ function createBuyerShopRouter(deps) {
             price: fenToYuan(unitFenOf(row)),
             image_url: productCols.includes("image_url") ? String(row.image_url || "") : "",
             stock: Number(row.stock) || 0,
+            // A1: 商品类型 (physical=实物要收货地址 / virtual=虚拟免地址发凭据); 无该列的老库默认 physical
+            product_type: productCols.includes("product_type") ? String(row.product_type || "physical") : "physical",
         };
     }
 
@@ -278,6 +291,9 @@ function createBuyerShopRouter(deps) {
             quantity: row.qty,
             tx_hash: txHash,
             code_url: row.psp_code_url || "",
+            // A1: 收货地址 / 交付凭据 (老订单两列为空 → 空串)
+            shipping_address: String(row.shipping_address || ""),
+            delivery_credential: String(row.delivery_credential || ""),
         };
     }
 
@@ -365,6 +381,13 @@ function createBuyerShopRouter(deps) {
             if (!(unitFen >= 1)) return err("PRICE_UNAVAILABLE", 409, "该商品暂未定价，暂不可购买");
             const totalFen = unitFen * qty;
 
+            // A1 商品类型驱动收货地址 (2026-10-05 设计方案): physical 强制收货地址, virtual 免地址生成交付凭据
+            const productType = String(product.product_type || "physical").toLowerCase() === "virtual" ? "virtual" : "physical";
+            const shippingAddress = String(b.shipping_address || "").trim().slice(0, 500);
+            if (productType === "physical" && !shippingAddress) {
+                return err("SHIPPING_ADDRESS_REQUIRED", 400, "该商品需要填写收货地址");
+            }
+
             // 幂等②: 无 client_order_no 时, 同买家同商品 5 分钟内未支付未过期单直接复用
             const now = nowSec();
             if (!clientOrderNo) {
@@ -388,6 +411,11 @@ function createBuyerShopRouter(deps) {
             const clientSessionId = `buyer:${buyerCard}:${clientOrderNo || orderRef}`;
             const exp = now + SESSION_TTL_SEC;
 
+            // A1: 虚拟商品交付凭据 (license/兑换码, 与订单绑定, 格式 tb-license-{order_ref}-{random4}; 实物单为空)
+            const deliveryCredential = productType === "virtual"
+                ? `tb-license-${orderRef}-${crypto.randomBytes(2).toString("hex")}`
+                : "";
+
             // 微信 Native 下单拿 code_url (mock 模式生成伪码, 不碰真微信)
             let codeUrl = "";
             if (MODE === "mock") {
@@ -409,11 +437,11 @@ function createBuyerShopRouter(deps) {
             // 买家面无账号体系, 订单 id 即凭据 — 与 pwa-shop-demo 轮询模型一致)
             // U7: ps_flag 台账标注该单是否带分账标记 (运营台区分用)
             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, ps_flag, sub_mchid)
- VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
+ (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, ps_flag, sub_mchid, shipping_address, delivery_credential)
+ VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
                 .run(clientSessionId, productId, qty, totalFen, "CNY", "buyer:" + buyerCard, orderRef,
                     crypto.randomBytes(32).toString("hex"), crypto.randomBytes(32).toString("hex"),
-                    "CREATED", codeUrl, "", exp, now, now, psFlag, subMchid);
+                    "CREATED", codeUrl, "", exp, now, now, psFlag, subMchid, shippingAddress, deliveryCredential);
             console.log(`[buyer-shop] 下单 ${orderRef} product=${productId} qty=${qty} total=${totalFen}分 ps_flag=${psFlag}`);
             const row = db.prepare("SELECT * FROM agent_pay_sessions WHERE order_ref = ?").get(orderRef);
             res.json(orderToJson(row));

package/routes/chain-writes-products.js

@@ -10,6 +10,7 @@ exports.findSlotBySku = findSlotBySku;
 exports.replayHit = replayHit;
 exports.logWrite = logWrite;
 exports.createChainWritesProductsRouter = createChainWritesProductsRouter;
+exports.mapDbProductTypeToChain = mapDbProductTypeToChain;
 /**
  * chain-writes-products.ts — 商品上链路由 (WooCommerce 商品 → 链上 x/marketplace)
  *
@@ -57,6 +58,40 @@ const CATEGORY_RE = /^[A-Za-z0-9 _-]*$/;
 /** keeper ListSKU 重复报错文案 (msg_server.go: "SKU already listed: %s") */
 exports.DUP_SKU_RE = /already listed|already exists|duplicate/i;
 const REPLAY_WINDOW_SQL = "created_at >= datetime('now', '-5 minutes')";
+/**
+ * A1 商品类型映射 (2026-10-06 xiaomu 拍板**口径 A**)。
+ *
+ * | DB (二值, 决定"要不要收货地址") | 链上 `ProductType` |
+ * |---|---|
+ * | `physical` (缺省) | `PRODUCT_TYPE_PHYSICAL` |
+ * | `virtual` | `PRODUCT_TYPE_DIGITAL` |
+ *
+ * 为什么 `virtual` 落到 `DIGITAL`: 链上另有 `SAAS` / `SERVICE` 两个非实体值, 但 xiaomu 定的是
+ * "商品类型只用于一个决策——要不要匹配收货地址", 细分语义暂不使用, 统一收敛到 `DIGITAL`。
+ *
+ * ⚠️ 非法值**显式 400** 而不是静默回落 `physical`: 静默回落会让虚拟商品被当成实体,
+ * 买家下单时被迫填收货地址 —— 静默的业务错误比 400 危险。缺省才回落 `physical`
+ * (向后兼容: 老 hook 不传该字段)。
+ *
+ * 注: `PRODUCT_TYPE_UNSPECIFIED`(=0) 不再用于新品 —— 它是 proto 的"未指定"默认值,
+ * 显式写 PHYSICAL 比留 UNSPECIFIED 更清晰, 也与 DB 侧口径一致。
+ */
+const DB_PRODUCT_TYPES = ['physical', 'virtual'];
+const DB_TO_CHAIN_PRODUCT_TYPE = {
+    physical: 'PRODUCT_TYPE_PHYSICAL',
+    virtual: 'PRODUCT_TYPE_DIGITAL',
+};
+/** 缺省 `physical`; 非法值抛 400 */
+function mapDbProductTypeToChain(value) {
+    if (value === undefined || value === null || value === '') return DB_TO_CHAIN_PRODUCT_TYPE.physical;
+    const key = String(value).toLowerCase();
+    const mapped = DB_TO_CHAIN_PRODUCT_TYPE[key];
+    if (mapped === undefined) {
+        throw new chain_writes_1.HttpError(400, 'invalid_param',
+            `product_type must be one of ${DB_PRODUCT_TYPES.join('|')}, got ${value}`);
+    }
+    return mapped;
+}
 function sha256Hex(s) {
     return crypto_1.default.createHash('sha256').update(s, 'utf8').digest('hex');
 }
@@ -198,14 +233,25 @@ function createChainWritesProductsRouter(deps) {
             const imageUrls = assertImageUrls(b.image_urls);
             const category = assertCategory(b.category);
             const skuId = `${assertSkuPrefix(b.sku_prefix)}-${wpPostId}`;
+            // A1 (2026-10-06 xiaomu 拍板口径 A): DB 二值 physical/virtual → 链上 5 值枚举。
+            // 选项 A 的映射: virtual → PRODUCT_TYPE_DIGITAL (数字产品);
+            // 其余一律 PHYSICAL。链上 DIGITAL/SAAS/SERVICE 的细分语义**暂不使用**
+            // (xiaomu: "商品类型只用于一个决策——要不要匹配收货地址")。
+            // ⚠️ 这只是 `MsgListSKU` 的链上字段; DB 侧仍是二值, 两侧靠本函数收敛。
+            const chainProductType = mapDbProductTypeToChain(b.product_type);
             // content_hash: sha256(JSON) 的 raw bytes → proto JSON bytes 字段要 base64
+            // 2026-10-06: product_type **不进 content_hash** —— 它是链上独立的枚举字段,
+            //   已由 MsgListSKU.product_type 承载; 塞进内容哈希会改变**已上架商品**的链上锚定,
+            //   代价大于收益。xiao mu 未要求, 保守处理 (见 A1 设计文档 §7.4)。
             const contentHashHex = sha256Hex(JSON.stringify({
                 title, description, image_urls: imageUrls, category, price_usd_cents: priceUsdCents,
             }));
             const contentHashB64 = Buffer.from(contentHashHex, 'hex').toString('base64');
+            // payload_hash: 幂等键。2026-10-06 **必须包含 product_type** ——
+            //   否则商家改商品类型后重发同一请求会被 replayHit 判成重放, 改了不生效。
             const payloadHash = sha256Hex(JSON.stringify({
                 wp_post_id: wpPostId, title, description, price_usd_cents: priceUsdCents,
-                stock, image_urls: imageUrls, category,
+                stock, image_urls: imageUrls, category, product_type: chainProductType,
             }));
             // 幂等短路: 完全相同 payload 5 分钟内重放 → 返回上次 txhash, 不再发链
             // (list/add_stock 两个 key 都查: 上次可能走了重复转 AddStock 路径)
@@ -228,7 +274,7 @@ function createChainWritesProductsRouter(deps) {
                 stake_per_unit: process.env.CHAIN_STAKE_PER_UNIT || '1000000',
                 cdn_url: '',
                 p2p_endpoint: process.env.P2P_ENDPOINT || '',
-                product_type: 'PRODUCT_TYPE_UNSPECIFIED', // proto 默认值 0 (实体物品)
+                product_type: chainProductType, // 2026-10-06: 不再写死 (见 mapDbProductTypeToChain)
             };
             let result = await sendTxAs(c, addr, [listMsg]);
             let action = 'list';

package/test-buyer-shop-ps.js

@@ -71,10 +71,10 @@ function withWechatMode(fn) {
     };
 }
 
-async function placeOrder(base, card) {
+async function placeOrder(base, card, productId = "p1") {
     const r = await fetch(base + "/api/orders", {
         method: "POST", headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ product_id: "p1", quantity: 1, buyer_card: card }),
+        body: JSON.stringify({ product_id: productId, quantity: 1, buyer_card: card, shipping_address: "addr-ps" }),
     });
     return { status: r.status, json: await r.json() };
 }
@@ -90,7 +90,7 @@ test("rate=0 (网关 404 未登记) + SP 模式 → 不带 settle_info, ps_flag=
         const { status, json } = await placeOrder(base, "card_ps1");
         assert.strictEqual(status, 200, JSON.stringify(json));
         assert.strictEqual(wxCalls.length, 1);
-        assert.strictEqual(wxCalls[0].opts, undefined, "rate=0 不传 settleInfo");
+        assert.deepStrictEqual(wxCalls[0].opts, { subMchid: "1118152327", subMchidSource: "env-fallback" }, "rate=0 不传 settleInfo");
         const row = db.prepare("SELECT ps_flag FROM agent_pay_sessions WHERE order_ref = ?").get(json.id);
         assert.strictEqual(row.ps_flag, 0, "台账 ps_flag=0");
     } finally { srv.close(); restoreEnv(env); }
@@ -110,7 +110,7 @@ test("rate=100 (env SP_COMMISSION_BP 覆盖) + SP 模式 → settle_info.profit_
         assert.strictEqual(status, 200, JSON.stringify(json));
         assert.strictEqual(gwCalls, 0, "env 覆盖时不调网关");
         assert.strictEqual(wxCalls.length, 1);
-        assert.deepStrictEqual(wxCalls[0].opts, { settleInfo: { profit_sharing: true } }, "带分账标记");
+        assert.deepStrictEqual(wxCalls[0].opts, { subMchid: "1118152327", subMchidSource: "env-fallback", settleInfo: { profit_sharing: true } }, "带分账标记");
         assert.strictEqual(db.prepare("SELECT ps_flag FROM agent_pay_sessions WHERE order_ref = ?").get(json.id).ps_flag, 1);
     } finally { srv.close(); restoreEnv(env); }
 }));
@@ -126,13 +126,13 @@ test("网关接口返回 rate_bp=100 → 带 settle_info; 60s 缓存 (第二次
         process.env.SP_GATEWAY_URL = "https://gw.example.com";
         const a = await placeOrder(base, "card_ps3a");
         assert.strictEqual(a.status, 200);
-        assert.deepStrictEqual(wxCalls[0].opts, { settleInfo: { profit_sharing: true } });
+        assert.deepStrictEqual(wxCalls[0].opts, { subMchid: "1118152327", subMchidSource: "env-fallback", settleInfo: { profit_sharing: true } });
         assert.strictEqual(gwCalls, 1);
         // 第二次下单 (不同买家卡避免幂等复用) → 命中缓存, 不再调网关
         const b = await placeOrder(base, "card_ps3b");
         assert.strictEqual(b.status, 200);
         assert.strictEqual(gwCalls, 1, "60s 缓存生效");
-        assert.deepStrictEqual(wxCalls[1].opts, { settleInfo: { profit_sharing: true } });
+        assert.deepStrictEqual(wxCalls[1].opts, { subMchid: "1118152327", subMchidSource: "env-fallback", settleInfo: { profit_sharing: true } });
         assert.strictEqual(db.prepare("SELECT COUNT(*) n FROM agent_pay_sessions WHERE ps_flag = 1").get().n, 2);
     } finally { srv.close(); restoreEnv(env); }
 }));
@@ -148,7 +148,7 @@ test("费率网关失败 → 缓存 0 防抖动, 不阻塞下单, 不带 settle_
         process.env.SP_GATEWAY_URL = "https://unreachable.example.com";
         const a = await placeOrder(base, "card_ps4a");
         assert.strictEqual(a.status, 200, "网关失败不阻塞下单");
-        assert.strictEqual(wxCalls[0].opts, undefined, "失败按 rate=0 不带标记");
+        assert.deepStrictEqual(wxCalls[0].opts, { subMchid: "1118152327", subMchidSource: "env-fallback" }, "失败按 rate=0 不带标记");
         const b = await placeOrder(base, "card_ps4b");
         assert.strictEqual(b.status, 200);
         assert.strictEqual(gwCalls, 1, "失败也缓存 60s (防抖动)");
@@ -167,12 +167,15 @@ test("本地 sp_commission_rates 兜底 (网关未配置, 同库直读) + 直连
         process.env.WXPAY_SUB_MCHID = "1118152327";
         const a = await placeOrder(base, "card_ps5a");
         assert.strictEqual(a.status, 200);
-        assert.deepStrictEqual(wxCalls[0].opts, { settleInfo: { profit_sharing: true } }, "本地表 rate=150 → 带标记");
+        assert.deepStrictEqual(wxCalls[0].opts, { subMchid: "1118152327", subMchidSource: "env-fallback", settleInfo: { profit_sharing: true } }, "本地表 rate=150 → 带标记");
         // 直连模式: 即便有费率也不标记 (settle_info 是 SP 分账语义)
+        // Lane C: sub_mchid 解析按卖家地址缓存 — 换另一个卖家的商品, 避免命中上一单的 env-fallback 缓存
         delete process.env.WXPAY_SUB_MCHID;
-        const b = await placeOrder(base, "card_ps5b");
+        db.prepare(`INSERT INTO store_products (id, seller_address, title, description, price_utct, stock, status, image_url, created_at, updated_at)
+ VALUES ('p2','tct1sellerDirect','U7直连商品','',2500000,10,'active',NULL,?,?)`).run(NOW_MS, NOW_MS);
+        const b = await placeOrder(base, "card_ps5b", "p2");
         assert.strictEqual(b.status, 200);
-        assert.strictEqual(wxCalls[1].opts, undefined, "直连模式不带 settle_info");
+        assert.deepStrictEqual(wxCalls[1].opts, { subMchid: "", subMchidSource: "none" }, "直连模式不带 settle_info");
         assert.strictEqual(db.prepare("SELECT ps_flag FROM agent_pay_sessions WHERE order_ref = ?").get(b.json.id).ps_flag, 0);
     } finally { srv.close(); restoreEnv(env); }
 }));

package/test-buyer-shop.js

@@ -87,12 +87,13 @@ test("GET /api/products: 只在架商品 + 契约字段 + utct 折元 (整数分
         assert.ok(Array.isArray(list), "契约: 裸数组");
         assert.strictEqual(list.length, 3, "draft 被过滤 (active 3 个)");
         const p = list.find((x) => x.id === "p-active-1");
-        assert.deepStrictEqual(Object.keys(p).sort(), ["description", "id", "image_url", "name", "price", "stock"], "契约字段一字不差");
+        assert.deepStrictEqual(Object.keys(p).sort(), ["description", "id", "image_url", "name", "price", "product_type", "stock"], "契约字段一字不差");
         assert.strictEqual(p.name, "测试商品A");
         assert.strictEqual(p.description, "好用");
         assert.strictEqual(p.price, 2.5, "2_500_000 utct / 1e6 = 2.5 元");
         assert.strictEqual(p.image_url, "https://img.example.com/a.jpg");
         assert.strictEqual(p.stock, 10);
+        assert.strictEqual(p.product_type, "physical", "A1: 无 product_type 列的老库默认 physical");
         const noImg = list.find((x) => x.id === "p-nostock");
         assert.strictEqual(noImg.image_url, "", "无图给空字符串");
         assert.strictEqual(noImg.price, 1);
@@ -125,7 +126,7 @@ test("POST /api/orders: 正常下单 (mock code_url) + 价格以 DB 为权威 (
     try {
         const r = await fetch(base + "/api/orders", {
             method: "POST", headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ product_id: "p-active-1", quantity: 2, buyer_card: "card_test001", amount: 0.01, price: 0 }), // 乱传金额无效
+            body: JSON.stringify({ product_id: "p-active-1", quantity: 2, buyer_card: "card_test001", shipping_address: "上海市浦东新区测试路1号", amount: 0.01, price: 0 }), // 乱传金额无效
         });
         const j = await r.json();
         assert.strictEqual(r.status, 200, JSON.stringify(j));
@@ -182,20 +183,20 @@ test("POST /api/orders 幂等: client_order_no 同号返原单; 无号 5 分钟
             method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body),
         }).then((r) => r.json());
         // ① client_order_no 幂等
-        const a = await post({ product_id: "p-active-1", quantity: 1, buyer_card: "card_idem1", client_order_no: "ORDER-X-1" });
-        const b = await post({ product_id: "p-active-1", quantity: 1, buyer_card: "card_idem1", client_order_no: "ORDER-X-1" });
+        const a = await post({ product_id: "p-active-1", quantity: 1, buyer_card: "card_idem1", client_order_no: "ORDER-X-1", shipping_address: "addr-1" });
+        const b = await post({ product_id: "p-active-1", quantity: 1, buyer_card: "card_idem1", client_order_no: "ORDER-X-1", shipping_address: "addr-1" });
         assert.strictEqual(b.id, a.id, "同 client_order_no 返原单");
         assert.strictEqual(db.prepare("SELECT COUNT(*) n FROM agent_pay_sessions").get().n, 1);
         // 不同 client_order_no → 新单
-        const c = await post({ product_id: "p-active-1", quantity: 1, buyer_card: "card_idem1", client_order_no: "ORDER-X-2" });
+        const c = await post({ product_id: "p-active-1", quantity: 1, buyer_card: "card_idem1", client_order_no: "ORDER-X-2", shipping_address: "addr-1" });
         assert.notStrictEqual(c.id, a.id);
         // ② 无号窗口复用 (同买家同商品)
-        const d = await post({ product_id: "p-active-1", quantity: 3, buyer_card: "card_idem2" });
-        const e = await post({ product_id: "p-active-1", quantity: 1, buyer_card: "card_idem2" });
+        const d = await post({ product_id: "p-active-1", quantity: 3, buyer_card: "card_idem2", shipping_address: "addr-2" });
+        const e = await post({ product_id: "p-active-1", quantity: 1, buyer_card: "card_idem2", shipping_address: "addr-2" });
         assert.strictEqual(e.id, d.id, "5 分钟窗口内复用未支付单");
         assert.strictEqual(e.amount, 7.5, "复用的是原单金额 (qty=3)");
         // 不同买家不复用
-        const f = await post({ product_id: "p-active-1", quantity: 1, buyer_card: "card_idem3" });
+        const f = await post({ product_id: "p-active-1", quantity: 1, buyer_card: "card_idem3", shipping_address: "addr-3" });
         assert.notStrictEqual(f.id, d.id);
     } finally { srv.close(); }
 });
@@ -205,7 +206,7 @@ test("POST /api/orders 限流: IP 维度 10 单/分钟, 第 11 单 429", async (
     try {
         const post = (card) => fetch(base + "/api/orders", {
             method: "POST", headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ product_id: "p-active-1", quantity: 1, buyer_card: card }),
+            body: JSON.stringify({ product_id: "p-active-1", quantity: 1, buyer_card: card, shipping_address: "addr-rl" }),
         });
         for (let i = 0; i < 10; i++) {
             const r = await post("card_rl_" + i); // 不同买家卡 → 每单独立 (不触发幂等)
@@ -226,12 +227,12 @@ test("GET /api/orders/:id: 状态映射 pending/paid/completed/failed + 404", as
     try {
         const cr = await fetch(base + "/api/orders", {
             method: "POST", headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ product_id: "p-active-1", quantity: 2, buyer_card: "card_st1" }),
+            body: JSON.stringify({ product_id: "p-active-1", quantity: 2, buyer_card: "card_st1", shipping_address: "addr-st1" }),
         });
         const { id } = await cr.json();
         const get = () => fetch(base + "/api/orders/" + id).then((r) => r.json());
         let o = await get();
-        assert.deepStrictEqual(Object.keys(o).sort(), ["amount", "code_url", "id", "product_id", "product_name", "quantity", "status", "tx_hash"] /* 0.5.2 补 product_id (Pi 复核 P2) */, "契约字段一字不差");
+        assert.deepStrictEqual(Object.keys(o).sort(), ["amount", "code_url", "delivery_credential", "id", "product_id", "product_name", "quantity", "shipping_address", "status", "tx_hash"] /* 0.5.2 补 product_id (Pi 复核 P2); A1 补 shipping_address/delivery_credential */, "契约字段一字不差");
         assert.strictEqual(o.status, "pending", "CREATED → pending");
         assert.strictEqual(o.amount, 5);
         assert.strictEqual(o.product_name, "测试商品A", "product_name 联 store_products.title");
@@ -295,7 +296,7 @@ test("wechat 模式: wxNativeOrder 注入捕获参数 (out_trade_no/金额分/
     try {
         const r = await fetch(base + "/api/orders", {
             method: "POST", headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ product_id: "p-active-1", quantity: 2, buyer_card: "card_wx1" }),
+            body: JSON.stringify({ product_id: "p-active-1", quantity: 2, buyer_card: "card_wx1", shipping_address: "addr-wx1" }),
         });
         const j = await r.json();
         assert.strictEqual(r.status, 200, JSON.stringify(j));
@@ -319,7 +320,7 @@ test("wechat 模式: 微信下单失败 → 502, 不落单", async () => {
     try {
         const r = await fetch(base + "/api/orders", {
             method: "POST", headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ product_id: "p-active-1", quantity: 1, buyer_card: "card_wx2" }),
+            body: JSON.stringify({ product_id: "p-active-1", quantity: 1, buyer_card: "card_wx2", shipping_address: "addr-wx2" }),
         });
         assert.strictEqual(r.status, 502);
         const j = await r.json();

package/test-product-type-chain.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * test-product-type-chain.js — A1 **链上上架**侧 (2026-10-06, xiaomu 拍板口径 A)
+ * node --test test-product-type-chain.js
+ *
+ * 覆盖 `routes/chain-writes-products.js` 的 DB→链上枚举映射, 以及两个哈希的取舍:
+ *
+ *   1. `physical` → `PRODUCT_TYPE_PHYSICAL` (缺省也是它, 向后兼容老 hook)
+ *   2. `virtual`  → `PRODUCT_TYPE_DIGITAL`   (口径 A: 细分语义暂不使用)
+ *   3. 大小写不敏感
+ *   4. 非法值 / 链上枚举名 (`saas`/`digital`) → **显式 400**, 不静默回落 physical
+ *      ⚠️ 静默回落会让虚拟商品被当实体, 买家被迫填收货地址
+ *   5. `payload_hash` **含** product_type ⇒ 改类型后不会被幂等短路
+ *   6. `content_hash` **不含** product_type ⇒ 不改变已上架商品的链上锚定
+ *
+ * 本文件不碰真链: 只测纯函数 + 用源码结构断言两个哈希的取舍 (口径 A 的关键决策点)。
+ */
+const test = require("node:test");
+const assert = require("node:assert");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const { mapDbProductTypeToChain } = require("./routes/chain-writes-products");
+
+const SRC = fs.readFileSync(path.join(__dirname, "routes/chain-writes-products.js"), "utf8");
+
+test("口径 A 映射: physical → PRODUCT_TYPE_PHYSICAL", () => {
+    assert.strictEqual(mapDbProductTypeToChain("physical"), "PRODUCT_TYPE_PHYSICAL");
+});
+
+test("口径 A 映射: 缺省 → PRODUCT_TYPE_PHYSICAL (向后兼容老 hook 不传该字段)", () => {
+    assert.strictEqual(mapDbProductTypeToChain(undefined), "PRODUCT_TYPE_PHYSICAL");
+    assert.strictEqual(mapDbProductTypeToChain(null), "PRODUCT_TYPE_PHYSICAL");
+    assert.strictEqual(mapDbProductTypeToChain(""), "PRODUCT_TYPE_PHYSICAL");
+});
+
+test("口径 A 映射: virtual → PRODUCT_TYPE_DIGITAL (不是 SAAS/SERVICE)", () => {
+    assert.strictEqual(mapDbProductTypeToChain("virtual"), "PRODUCT_TYPE_DIGITAL");
+});
+
+test("口径 A 映射: 大小写不敏感", () => {
+    assert.strictEqual(mapDbProductTypeToChain("VIRTUAL"), "PRODUCT_TYPE_DIGITAL");
+    assert.strictEqual(mapDbProductTypeToChain("Physical"), "PRODUCT_TYPE_PHYSICAL");
+});
+
+test("口径 A 映射: 链上枚举名当入参 → 显式抛错, 不静默回落", () => {
+    // 这三个是链上 proto 的值, 不是 DB 的值 —— 直接传进来必须报错, 否则会静默变实体
+    for (const bad of ["saas", "digital", "service", "PRODUCT_TYPE_SAAS"]) {
+        assert.throws(() => mapDbProductTypeToChain(bad), (err) => {
+            assert.match(err.message, /product_type must be one of physical\|virtual/);
+            return true;
+        }, `输入 ${bad} 应当抛错`);
+    }
+});
+
+test("幂等键 payload_hash 含 product_type (改类型不会被重放短路)", () => {
+    const m = SRC.match(/const payloadHash = sha256Hex\(JSON\.stringify\(\{([^}]*)\}\)\)/);
+    assert.ok(m, "应能定位到 payloadHash 计算块");
+    assert.match(m[1], /product_type/, "payload_hash 必须含 product_type, 否则改类型会被幂等当重放");
+});
+
+test("content_hash 不含 product_type (不改变已上架商品的链上锚定)", () => {
+    const m = SRC.match(/const contentHashHex = sha256Hex\(JSON\.stringify\(\{([^}]*)\}\)\)/);
+    assert.ok(m, "应能定位到 contentHash 计算块");
+    assert.doesNotMatch(m[1], /product_type/,
+        "content_hash 不应含 product_type —— 会改变已上架商品的链上内容哈希");
+});
+
+test("上架 msg 不再写死 PRODUCT_TYPE_UNSPECIFIED", () => {
+    assert.doesNotMatch(SRC, /product_type:\s*'PRODUCT_TYPE_UNSPECIFIED'/,
+        "应已改为走 mapDbProductTypeToChain");
+    assert.match(SRC, /product_type:\s*chainProductType/);
+});

package/test-product-type-write.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * test-product-type-write.js — A1 **写入端**离线单测 (2026-10-06 补)
+ * node --test test-product-type-write.js
+ *
+ * ## 为什么单独一个文件
+ *
+ * 原 `test-product-type.js` 的 5 个用例**全部直接 INSERT 数据库**再打下单接口,
+ * 没有一个走过**建品接口**。于是"商家建品时无法指定 product_type"这条断链
+ * 当时完全测不出来 —— 单测全绿,真实链路上 `virtual` 却永远写不进去。
+ *
+ * 本文件专门覆盖写入端,让这种断链以后能被测出来。
+ *
+ * 覆盖:
+ *   1. 建品传 `product_type: 'virtual'` → 真落库 (断链一回归)
+ *   2. 建品不传 → 默认 `physical` (向后兼容, 老客户端不受影响)
+ *   3. 建品传**非法值** (如链上枚举名 `saas`) → 400 INVALID_PRODUCT_TYPE
+ *      ⚠️ 必须报错而不是静默降级成 physical: 下单侧是 `=== 'virtual' ? virtual : physical`,
+ *         静默降级会让买虚拟商品的买家被迫填收货地址
+ *   4. 改品 `product_type` → 可改 (physical ⇄ virtual)
+ *   5. 改品不传该字段 → 沿用原值, 不被意外重置
+ *   6. 响应体回显 `product_type`
+ *   7. 老库缺 `product_type` 列时 rowToProduct 仍返回 `physical` (不炸)
+ *
+ * 离��: `:memory:` 库 + express, `enableAuth: false` 绕开 wallet 签名 (本文件只测参数校验与落库)。
+ */
+const test = require("node:test");
+const assert = require("node:assert");
+const express = require("express");
+const Database = require("better-sqlite3");
+
+const { createSellerProductsRouter } = require("./api/seller-products");
+
+const SELLER = "tct1" + "s".repeat(38);
+const NOW_MS = Date.now();
+
+/** A1 迁移后的 schema (含 product_type 列) */
+function seed(db) {
+    db.exec(`
+CREATE TABLE store_products (
+  id TEXT PRIMARY KEY, seller_address TEXT NOT NULL, title TEXT NOT NULL,
+  description TEXT NOT NULL DEFAULT '', price_utct INTEGER NOT NULL,
+  stock INTEGER NOT NULL DEFAULT 0, status TEXT NOT NULL DEFAULT 'draft',
+  category TEXT DEFAULT 'general', image_url TEXT, tags TEXT DEFAULT '[]',
+  featured INTEGER NOT NULL DEFAULT 0, sales_count INTEGER NOT NULL DEFAULT 0,
+  product_type TEXT NOT NULL DEFAULT 'physical',
+  created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+);
+CREATE TABLE store_settings (seller_address TEXT PRIMARY KEY, status TEXT NOT NULL);
+`);
+    db.prepare("INSERT INTO store_settings (seller_address, status) VALUES (?, 'active')").run(SELLER);
+}
+
+/** 老库: 没有 product_type 列 (验证向后兼容不炸) */
+function seedLegacyNoColumn(db) {
+    db.exec(`
+CREATE TABLE store_products (
+  id TEXT PRIMARY KEY, seller_address TEXT NOT NULL, title TEXT NOT NULL,
+  description TEXT NOT NULL DEFAULT '', price_utct INTEGER NOT NULL,
+  stock INTEGER NOT NULL DEFAULT 0, status TEXT NOT NULL DEFAULT 'draft',
+  category TEXT DEFAULT 'general', image_url TEXT, tags TEXT DEFAULT '[]',
+  featured INTEGER NOT NULL DEFAULT 0, sales_count INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+);
+CREATE TABLE store_settings (seller_address TEXT PRIMARY KEY, status TEXT NOT NULL);
+`);
+    db.prepare("INSERT INTO store_settings (seller_address, status) VALUES (?, 'active')").run(SELLER);
+    // 前置: 确认这张表确实没有 product_type 列（boot 里 router 会把它补上）
+    assert.ok(
+        !db.prepare("PRAGMA table_info(store_products)").all().map((c) => c.name).includes("product_type"),
+        "前置失败: seedLegacyNoColumn 建出的表不该有 product_type 列"
+    );
+}
+
+async function post(port, body) {
+    const r = await fetch(`http://127.0.0.1:${port}/api/seller/products`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    return { status: r.status, body: await r.json() };
+}
+
+async function patch(port, id, body) {
+    const r = await fetch(`http://127.0.0.1:${port}/api/seller/products/${id}`, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    return { status: r.status, body: await r.json() };
+}
+
+/** 起服务并确保端口就绪 (app.listen(0) 之后 address() 才可用) */
+async function boot(seedFn) {
+    const db = new Database(":memory:");
+    seedFn(db);
+    const app = express();
+    app.use(express.json());
+    app.use((req, _res, next) => {
+        req.walletAddress = SELLER;
+        next();
+    });
+    app.use("/api/seller", createSellerProductsRouter({ db, enableAuth: false }));
+    const srv = await new Promise((resolve) => {
+        const s = app.listen(0, "127.0.0.1", () => resolve(s));
+    });
+    return { db, port: srv.address().port, close: () => srv.close() };
+}
+
+test("A1 写入端: 建品能指定 virtual —— 断链一回归", async () => {
+    const { db, port, close } = await boot(seed);
+    try {
+        const r = await post(port, { title: "技能商店基础版", price_utct: 1000000, stock: 99, product_type: "virtual" });
+        assert.strictEqual(r.status, 201, "建品应成功");
+        assert.strictEqual(r.body.product.product_type, "virtual", "响应体应回显 virtual");
+
+        // 真落库核验 (不能只看响应)
+        const row = db.prepare("SELECT product_type FROM store_products WHERE id = ?").get(r.body.product.id);
+        assert.strictEqual(row.product_type, "virtual", "DB 里必须真的写进去了");
+    } finally { close(); }
+});
+
+test("A1 写入端: 不传 product_type → 默认 physical (向后兼容)", async () => {
+    const { db, port, close } = await boot(seed);
+    try {
+        const r = await post(port, { title: "云南滇红 250g", price_utct: 2500000, stock: 10 });
+        assert.strictEqual(r.status, 201);
+        assert.strictEqual(r.body.product.product_type, "physical");
+        const row = db.prepare("SELECT product_type FROM store_products WHERE id = ?").get(r.body.product.id);
+        assert.strictEqual(row.product_type, "physical");
+    } finally { close(); }
+});
+
+test("A1 写入端: 非法 product_type → 400, 绝不静默降级成 physical", async () => {
+    const { db, port, close } = await boot(seed);
+    try {
+        // 链上 proto 的枚举名 —— 属于 §7.2 待拍板的口径冲突, 现在必须明确拒绝而不是静默吞掉
+        const r = await post(port, { title: "订阅服务", price_utct: 100, stock: 1, product_type: "saas" });
+        assert.strictEqual(r.status, 400, "非法值必须 400");
+        assert.strictEqual(r.body.errorCode, "INVALID_PRODUCT_TYPE");
+        // 关键: 不能建出商品来
+        const n = db.prepare("SELECT COUNT(*) c FROM store_products").get().c;
+        assert.strictEqual(n, 0, "被拒的商品不应落库");
+    } finally { close(); }
+});
+
+test("A1 写入端: product_type 可改 (physical ⇄ virtual)", async () => {
+    const { db, port, close } = await boot(seed);
+    try {
+        const created = await post(port, { title: "手作陶壶", price_utct: 8800000, stock: 5, product_type: "physical" });
+        const id = created.body.product.id;
+
+        const r1 = await patch(port, id, { product_type: "virtual" });
+        assert.strictEqual(r1.status, 200);
+        assert.strictEqual(r1.body.product.product_type, "virtual");
+        assert.strictEqual(
+            db.prepare("SELECT product_type FROM store_products WHERE id = ?").get(id).product_type,
+            "virtual"
+        );
+
+        const r2 = await patch(port, id, { product_type: "physical" });
+        assert.strictEqual(r2.body.product.product_type, "physical");
+    } finally { close(); }
+});
+
+test("A1 写入端: 改品不传该字段 → 沿用原值, 不被重置", async () => {
+    const { db, port, close } = await boot(seed);
+    try {
+        const created = await post(port, { title: "入门课程", price_utct: 5000, stock: 9, product_type: "virtual" });
+        const id = created.body.product.id;
+        // 只改标题, 不碰类型
+        const r = await patch(port, id, { title: "课程 (改名)" });
+        assert.strictEqual(r.status, 200);
+        assert.strictEqual(r.body.product.product_type, "virtual", "类型不应被意外重置成 physical");
+    } finally { close(); }
+});
+
+test("A1 写入端: 改品传非法值 → 400, 原值不变", async () => {
+    const { db, port, close } = await boot(seed);
+    try {
+        const created = await post(port, { title: "插件工具包", price_utct: 1000, stock: 3, product_type: "virtual" });
+        const id = created.body.product.id;
+        const r = await patch(port, id, { product_type: "digital" });
+        assert.strictEqual(r.status, 400);
+        assert.strictEqual(r.body.errorCode, "INVALID_PRODUCT_TYPE");
+        assert.strictEqual(
+            db.prepare("SELECT product_type FROM store_products WHERE id = ?").get(id).product_type,
+            "virtual",
+            "被拒的修改不应生效"
+        );
+    } finally { close(); }
+});
+
+test("A1 写入端: 老库缺 product_type 列 → 自动补列, 建品成功 (不是 500)", async () => {
+    const { db, port, close } = await boot(seedLegacyNoColumn);
+    try {
+        // 修复证据: router 初始化时 ensureBuyerTables 已把列补上
+        const cols = db.prepare("PRAGMA table_info(store_products)").all().map((c) => c.name);
+        assert.ok(cols.includes("product_type"), "router 应已自动补上 product_type 列");
+
+        const r = await post(port, { title: "老库商品", price_utct: 100, stock: 1, product_type: "virtual" });
+        // router 初始化时 ensureBuyerTables 应已把列补上 —— 老库商家不该被 500 拦住
+        assert.strictEqual(r.status, 201, `老库建品应成功, 实得 ${r.status}: ${JSON.stringify(r.body)}`);
+        assert.strictEqual(r.body.product.product_type, "virtual");
+
+        // 不传类型时也应回落 physical, 而不是因为补列前的 NULL 出问题
+        const r2 = await post(port, { title: "老库商品二", price_utct: 100, stock: 1 });
+        assert.strictEqual(r2.status, 201);
+        assert.strictEqual(r2.body.product.product_type, "physical");
+    } finally { close(); }
+});

package/test-product-type.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * test-product-type.js — A1 商品类型驱动收货地址 离线单测 (2026-10-05 设计方案)
+ * node --test test-product-type.js
+ *
+ * 照 test-buyer-shop.js 模式: :memory: 库起 mock server, AGENT_PAY_MODE=mock 不碰真微信/真链。
+ * 覆盖设计方案 4 条验收:
+ *   1. physical 商品下单必须提供 shipping_address, 缺失 400 (SHIPPING_ADDRESS_REQUIRED)
+ *   2. virtual 商品下单不要地址, 返回 delivery_credential (tb-license-{order_ref}-{random4})
+ *   3. 向后兼容: 无 product_type 列的商品默认 physical, 要求地址
+ *   4. 老订单 (新列为空) 查询正常, 返回空串
+ */
+const test = require("node:test");
+const assert = require("node:assert");
+const express = require("express");
+const Database = require("better-sqlite3");
+
+process.env.AGENT_PAY_MODE = "mock";
+
+const buyerShop = require("./routes/buyer-shop");
+
+const NOW_MS = Date.now();
+const ADDR = "上海市浦东新区测试路1号 张三收 13800000000";
+
+/** 新 schema: store_products 含 product_type 列 (A1 迁移后) */
+function seedProductsWithType(db) {
+    db.exec(`
+CREATE TABLE store_products (
+  id TEXT PRIMARY KEY, seller_address TEXT NOT NULL, title TEXT NOT NULL,
+  description TEXT NOT NULL DEFAULT '', price_utct INTEGER NOT NULL,
+  stock INTEGER NOT NULL DEFAULT 0, status TEXT NOT NULL DEFAULT 'draft',
+  product_type TEXT NOT NULL DEFAULT 'physical',
+  created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+);
+`);
+    const ins = db.prepare(`INSERT INTO store_products (id, seller_address, title, price_utct, stock, status, product_type, created_at, updated_at)
+ VALUES (?,?,?,?,?,?,?,?,?)`);
+    ins.run("p-phys-1", "tct1seller", "实物商品", 2500000, 10, "active", "physical", NOW_MS, NOW_MS);
+    ins.run("p-virt-1", "tct1seller", "虚拟商品", 1000000, 99, "active", "virtual", NOW_MS, NOW_MS);
+}
+
+/** 老 schema: store_products 无 product_type 列 (A1 迁移前的生产库形状, 同 test-buyer-shop.js) */
+function seedProductsLegacy(db) {
+    db.exec(`
+CREATE TABLE store_products (
+  id TEXT PRIMARY KEY, seller_address TEXT NOT NULL, title TEXT NOT NULL,
+  description TEXT NOT NULL DEFAULT '', price_utct INTEGER NOT NULL,
+  stock INTEGER NOT NULL DEFAULT 0, status TEXT NOT NULL DEFAULT 'draft',
+  created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
+);
+`);
+    db.prepare(`INSERT INTO store_products (id, seller_address, title, price_utct, stock, status, created_at, updated_at)
+ VALUES (?,?,?,?,?,?,?,?)`)
+        .run("p-legacy-1", "tct1seller", "老商品", 2500000, 10, "active", NOW_MS, NOW_MS);
+}
+
+async function startServer(seed) {
+    const db = new Database(":memory:");
+    seed(db);
+    const app = express();
+    app.use(express.json());
+    app.use("/api", buyerShop.createBuyerShopRouter({ 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}` };
+}
+
+function post(base, body) {
+    return fetch(base + "/api/orders", {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body),
+    });
+}
+
+test("① physical 商品: 缺 shipping_address → 400 SHIPPING_ADDRESS_REQUIRED; 提供后下单成功且落库/返回地址", async () => {
+    const { db, srv, base } = await startServer(seedProductsWithType);
+    try {
+        // 缺地址 → 400
+        let r = await post(base, { product_id: "p-phys-1", quantity: 1, buyer_card: "card_pt1" });
+        assert.strictEqual(r.status, 400);
+        let j = await r.json();
+        assert.strictEqual(j.error, "SHIPPING_ADDRESS_REQUIRED");
+        assert.ok(j.message, "{error, message} 结构");
+        // 空白地址也视为缺失
+        r = await post(base, { product_id: "p-phys-1", quantity: 1, buyer_card: "card_pt1", shipping_address: "   " });
+        assert.strictEqual(r.status, 400);
+        assert.strictEqual(db.prepare("SELECT COUNT(*) n FROM agent_pay_sessions").get().n, 0, "校验失败不落单");
+        // 提供地址 → 200, 地址落库且随单返回
+        r = await post(base, { product_id: "p-phys-1", quantity: 1, buyer_card: "card_pt1", shipping_address: ADDR });
+        j = await r.json();
+        assert.strictEqual(r.status, 200, JSON.stringify(j));
+        assert.match(j.id, /^tb-[0-9a-f]{16}$/);
+        assert.strictEqual(j.shipping_address, ADDR);
+        assert.strictEqual(j.delivery_credential, "", "实物单无交付凭据");
+        const row = db.prepare("SELECT * FROM agent_pay_sessions WHERE order_ref = ?").get(j.id);
+        assert.strictEqual(row.shipping_address, ADDR, "地址落 agent_pay_sessions");
+        assert.strictEqual(row.delivery_credential, "");
+        // 查单也带地址
+        const o = await (await fetch(base + "/api/orders/" + j.id)).json();
+        assert.strictEqual(o.shipping_address, ADDR);
+    } finally { srv.close(); }
+});
+
+test("② virtual 商品: 不要地址, 返回 delivery_credential (license 格式), 幂等重放凭据不变", async () => {
+    const { db, srv, base } = await startServer(seedProductsWithType);
+    try {
+        let r = await post(base, { product_id: "p-virt-1", quantity: 1, buyer_card: "card_pt2", client_order_no: "V-ORDER-1" });
+        const j = await r.json();
+        assert.strictEqual(r.status, 200, JSON.stringify(j));
+        assert.match(j.delivery_credential, /^tb-license-tb-[0-9a-f]{16}-[0-9a-f]{4}$/, "license 格式 tb-license-{order_ref}-{random4}");
+        assert.ok(j.delivery_credential.includes(j.id), "凭据与订单绑定");
+        assert.strictEqual(j.shipping_address, "", "虚拟单地址为空");
+        const row = db.prepare("SELECT * FROM agent_pay_sessions WHERE order_ref = ?").get(j.id);
+        assert.strictEqual(row.delivery_credential, j.delivery_credential, "凭据落库");
+        // 幂等重放 → 同一凭据 (不重新生成)
+        r = await post(base, { product_id: "p-virt-1", quantity: 1, buyer_card: "card_pt2", client_order_no: "V-ORDER-1" });
+        const j2 = await r.json();
+        assert.strictEqual(j2.id, j.id);
+        assert.strictEqual(j2.delivery_credential, j.delivery_credential);
+        // 查单带凭据
+        const o = await (await fetch(base + "/api/orders/" + j.id)).json();
+        assert.strictEqual(o.delivery_credential, j.delivery_credential);
+        // 两个虚拟单凭据不同
+        const j3 = await (await post(base, { product_id: "p-virt-1", quantity: 1, buyer_card: "card_pt2", client_order_no: "V-ORDER-2" })).json();
+        assert.notStrictEqual(j3.delivery_credential, j.delivery_credential);
+    } finally { srv.close(); }
+});
+
+test("②b 商品面: GET /products 返回 product_type (virtual/physical 如实; 列表含类型)", async () => {
+    const { srv, base } = await startServer(seedProductsWithType);
+    try {
+        const list = await (await fetch(base + "/api/products")).json();
+        assert.strictEqual(list.find((x) => x.id === "p-phys-1").product_type, "physical");
+        assert.strictEqual(list.find((x) => x.id === "p-virt-1").product_type, "virtual");
+        const one = await (await fetch(base + "/api/products/p-virt-1")).json();
+        assert.strictEqual(one.product_type, "virtual");
+    } finally { srv.close(); }
+});
+
+test("③ 向后兼容: 无 product_type 列的老商品默认 physical, 下单要求地址", async () => {
+    const { srv, base } = await startServer(seedProductsLegacy);
+    try {
+        // 商品面默认 physical
+        const p = await (await fetch(base + "/api/products/p-legacy-1")).json();
+        assert.strictEqual(p.product_type, "physical", "无该列 → 默认 physical");
+        // 缺地址 → 400
+        let r = await post(base, { product_id: "p-legacy-1", quantity: 1, buyer_card: "card_pt3" });
+        assert.strictEqual(r.status, 400);
+        assert.strictEqual((await r.json()).error, "SHIPPING_ADDRESS_REQUIRED");
+        // 带地址 → 200
+        r = await post(base, { product_id: "p-legacy-1", quantity: 1, buyer_card: "card_pt3", shipping_address: ADDR });
+        assert.strictEqual(r.status, 200, JSON.stringify(await r.json()));
+    } finally { srv.close(); }
+});
+
+test("④ 老订单 (新列为空) 查询正常, shipping_address / delivery_credential 返回空串", async () => {
+    const { db, srv, base } = await startServer(seedProductsWithType);
+    try {
+        // 直插一行"迁移前形状"的老订单 (不指定新列 → DEFAULT '')
+        const now = Math.floor(Date.now() / 1000);
+        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, ps_flag, sub_mchid)
+ VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`)
+            .run("buyer:card_old:tb-00000000000000ff", "p-phys-1", 1, 250, "CNY", "buyer:card_old", "tb-00000000000000ff",
+                "x".repeat(64), "y".repeat(64), "PAID", "", "", now + 900, now, now, 0, "");
+        const r = await fetch(base + "/api/orders/tb-00000000000000ff");
+        assert.strictEqual(r.status, 200);
+        const o = await r.json();
+        assert.strictEqual(o.shipping_address, "", "老订单地址空串");
+        assert.strictEqual(o.delivery_credential, "", "老订单凭据空串");
+        assert.strictEqual(o.status, "paid", "状态机不受影响");
+        assert.strictEqual(o.amount, 2.5);
+    } finally { srv.close(); }
+});