@pisell/pisellos 2.2.190 → 2.2.192

package/lib/server/modules/order/index.js

@@ -40,6 +40,12 @@ var INDEXDB_STORE_NAME = "orders";
 var ORDER_LAST_FULL_FETCH_AT_STORAGE_KEY = "server_order_last_full_fetch_at";
 var ORDER_SYNC_THROTTLE_MS_STORAGE_KEY = "order_sync_throttle_ms";
 var DEFAULT_ORDER_SYNC_THROTTLE_MS = 2e3;
+var ORDER_SQLITE_DEDUPE_MS = 15e3;
+var ORDER_SILENT_REFRESH_MIN_INTERVAL_MS = 3e4;
+var ORDER_BUSINESS_WRITE_SOURCES = /* @__PURE__ */ new Set([
+  "upsertOrdersFromRemote",
+  "overwriteExistingOrder"
+]);
 var OrderModule = class extends import_BaseModule.BaseModule {
   constructor(name, version) {
     super(name, version);
@@ -51,6 +57,10 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     // Map<resource_id, OrderId[]> 资源到订单的倒排索引
     this.resourceIdIndex = /* @__PURE__ */ new Map();
     this.orderSQLiteSaveQueue = Promise.resolve();
+    /** 按 storageKey 记录最近一次 SQLite 写入来源与时间，用于去重 */
+    this.recentSqliteWriteByStorageKey = /* @__PURE__ */ new Map();
+    /** 最近一次 SSE 全量拉取完成时间 */
+    this.lastServerFullFetchAtMs = 0;
   }
   async initialize(core, options) {
     var _a, _b;
@@ -155,6 +165,159 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     } catch {
     }
   }
+  /**
+   * 记录订单最近一次 SQLite 写入，供 pubsub 回声去重使用。
+   *
+   * @example
+   * this.recordRecentSqliteWrite('upsertOrdersFromRemote', orders)
+   */
+  recordRecentSqliteWrite(source, orders) {
+    const now = Date.now();
+    for (const order of orders) {
+      const storageKey = this.getOrderStorageKey(order);
+      if (!storageKey)
+        continue;
+      this.recentSqliteWriteByStorageKey.set(storageKey, { source, ts: now });
+    }
+  }
+  /**
+   * 过滤 pubsub 触发的冗余 SQLite patch（业务 API 刚写入过的 update 回声）。
+   *
+   * @example
+   * const { toWrite, skipped } = this.filterRedundantPatchOrders('pubsub.bodyUpsert', orders, mergeActions)
+   */
+  filterRedundantPatchOrders(source, orders, mergeActions) {
+    const eligibleSkipSources = /* @__PURE__ */ new Set(["pubsub.bodyUpsert", "pubsub.httpRefresh"]);
+    if (!eligibleSkipSources.has(source)) {
+      return { toWrite: orders, skipped: [] };
+    }
+    const now = Date.now();
+    const toWrite = [];
+    const skipped = [];
+    for (const order of orders) {
+      const storageKey = this.getOrderStorageKey(order);
+      if (!storageKey) {
+        toWrite.push(order);
+        continue;
+      }
+      const orderKey = order.order_id !== void 0 && order.order_id !== null ? this.getIdKey(order.order_id) : "";
+      const mergeAction = orderKey ? mergeActions[orderKey] : void 0;
+      if (mergeAction === "insert") {
+        toWrite.push(order);
+        continue;
+      }
+      const recent = this.recentSqliteWriteByStorageKey.get(storageKey);
+      if (recent && ORDER_BUSINESS_WRITE_SOURCES.has(recent.source) && now - recent.ts < ORDER_SQLITE_DEDUPE_MS) {
+        skipped.push({
+          orderId: order.order_id ?? null,
+          storageKey,
+          reason: "skip_pubsub_echo_after_business_write",
+          lastSource: recent.source,
+          elapsedMs: now - recent.ts
+        });
+        continue;
+      }
+      toWrite.push(order);
+    }
+    return { toWrite, skipped };
+  }
+  /**
+   * 过滤 pubsub HTTP 增量拉取 ids：本地刚由业务 API 写入的单可跳过 HTTP。
+   *
+   * @example
+   * const ids = this.filterRedundantHttpRefreshIds([99331, 99332])
+   */
+  filterRedundantHttpRefreshIds(ids) {
+    const now = Date.now();
+    const toFetch = [];
+    const skipped = [];
+    for (const id of ids) {
+      const existing = this.getOrderByOrderId(id);
+      if (!existing) {
+        toFetch.push(id);
+        continue;
+      }
+      const storageKey = this.getOrderStorageKey(existing);
+      const recent = storageKey ? this.recentSqliteWriteByStorageKey.get(storageKey) : void 0;
+      if (recent && recent.source === "upsertOrdersFromRemote" && now - recent.ts < ORDER_SQLITE_DEDUPE_MS) {
+        skipped.push({
+          orderId: id,
+          lastSource: recent.source,
+          elapsedMs: now - recent.ts
+        });
+        continue;
+      }
+      toFetch.push(id);
+    }
+    return { toFetch, skipped };
+  }
+  /**
+   * 解析 pubsub 消息会走哪条同步分支，便于对照为何触发 HTTP 重拉或 body 直写。
+   *
+   * @example
+   * this.resolveSyncMessageRoute(msg)
+   * // => { route: 'httpRefresh.batchIds', ... }
+   */
+  resolveSyncMessageRoute(msg) {
+    var _a;
+    const hasBatchIds = Array.isArray(msg.ids) && msg.ids.length > 0;
+    const singleIdRaw = msg.id ?? msg.order_id;
+    const hasSingleId = !hasBatchIds && singleIdRaw !== void 0 && singleIdRaw !== null;
+    const normalizedBody = this.normalizeOrderSyncPayload(msg.body || msg.data);
+    if (hasBatchIds) {
+      return {
+        route: "httpRefresh.batchIds",
+        hasBatchIds: true,
+        hasSingleId: false,
+        hasNormalizedBody: !!normalizedBody,
+        singleId: null,
+        batchIds: msg.ids || [],
+        bodyOrderId: (normalizedBody == null ? void 0 : normalizedBody.order_id) ?? null
+      };
+    }
+    if (hasSingleId && normalizedBody) {
+      return {
+        route: "bodyUpsert",
+        hasBatchIds: false,
+        hasSingleId: true,
+        hasNormalizedBody: true,
+        singleId: singleIdRaw,
+        batchIds: [],
+        bodyOrderId: normalizedBody.order_id ?? null
+      };
+    }
+    if (hasSingleId) {
+      return {
+        route: "httpRefresh.singleId",
+        hasBatchIds: false,
+        hasSingleId: true,
+        hasNormalizedBody: !!normalizedBody,
+        singleId: singleIdRaw,
+        batchIds: [],
+        bodyOrderId: (normalizedBody == null ? void 0 : normalizedBody.order_id) ?? null
+      };
+    }
+    if ((_a = msg.relation_order_ids) == null ? void 0 : _a.length) {
+      return {
+        route: "httpRefresh.relationIds",
+        hasBatchIds: false,
+        hasSingleId: false,
+        hasNormalizedBody: !!normalizedBody,
+        singleId: null,
+        batchIds: msg.relation_order_ids,
+        bodyOrderId: (normalizedBody == null ? void 0 : normalizedBody.order_id) ?? null
+      };
+    }
+    return {
+      route: "noop",
+      hasBatchIds: false,
+      hasSingleId: false,
+      hasNormalizedBody: !!normalizedBody,
+      singleId: null,
+      batchIds: [],
+      bodyOrderId: (normalizedBody == null ? void 0 : normalizedBody.order_id) ?? null
+    };
+  }
   getOrderSyncThrottleMs() {
     const raw = localStorage.getItem(ORDER_SYNC_THROTTLE_MS_STORAGE_KEY);
     if (raw !== null) {
@@ -167,8 +330,9 @@ var OrderModule = class extends import_BaseModule.BaseModule {
   async preload() {
     const getData = async () => {
       const orders = await this.loadOrdersByServer();
-      if (orders.length === 0)
+      if (orders.length === 0) {
         return;
+      }
       this.store.list = (0, import_lodash_es.cloneDeep)(orders);
       this.syncOrdersMap();
       this.core.effects.emit(import_types.OrderHooks.onOrdersChanged, this.store.list);
@@ -189,8 +353,9 @@ var OrderModule = class extends import_BaseModule.BaseModule {
   async getLocalOrderByOrderId(orderId) {
     const key = this.getIdKey(orderId);
     const memoryOrder = this.store.map.get(key);
-    if (memoryOrder)
+    if (memoryOrder) {
       return memoryOrder;
+    }
     const orders = await this.loadOrdersFromSQLite();
     const localOrder = orders.find((order) => {
       const shopOrderNumber = order == null ? void 0 : order.shop_order_number;
@@ -226,12 +391,13 @@ var OrderModule = class extends import_BaseModule.BaseModule {
           count: orderList.length
         });
         this.markOrderPulledAtNow();
+        this.lastServerFullFetchAtMs = Date.now();
       } catch {
         orderList = [];
         this.logInfo("loadOrdersByServer-SSE拉取失败，回退为空数组");
       }
     }
-    await this.saveOrdersToSQLite(orderList);
+    await this.replaceOrdersSnapshotInSQLite(orderList, "loadOrdersByServer");
     this.logInfo("loadOrdersByServer-结束", {
       count: orderList.length
     });
@@ -245,6 +411,10 @@ var OrderModule = class extends import_BaseModule.BaseModule {
    */
   async silentRefresh() {
     const startTime = Date.now();
+    const elapsedSinceFullFetch = Date.now() - this.lastServerFullFetchAtMs;
+    if (this.lastServerFullFetchAtMs > 0 && elapsedSinceFullFetch < ORDER_SILENT_REFRESH_MIN_INTERVAL_MS) {
+      return this.store.list;
+    }
     this.logInfo("silentRefresh 开始");
     try {
       const orders = await this.loadOrdersByServer();
@@ -300,7 +470,7 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       return this.getIdKey(id) === key ? fresh : order;
     });
     this.syncOrdersMap();
-    await this.saveOrdersToSQLite(this.store.list);
+    await this.updateOrderInSQLite(fresh, "overwriteExistingOrder");
     this.logInfo("overwriteExistingOrder-结束", {
       orderId,
       storeOrderCountAfter: this.store.list.length
@@ -318,7 +488,7 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       return;
     }
     this.logInfo("upsertOrdersFromRemote-开始", { count: freshOrders.length });
-    await this.mergeOrdersToStore(freshOrders);
+    await this.mergeOrdersToStore(freshOrders, "upsertOrdersFromRemote");
   }
   /**
    * 通过 SSE 按自定义 query 拉取订单（支持 select/with 精简字段）
@@ -426,7 +596,7 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     this.orderDataSource.run({
       pubsub: {
         callback: (res) => {
-          console.log("orderDataSource");
+          console.log("orderDataSource", res);
           const pubsubReceivedAt = Date.now();
           const message = this.normalizeOrderSyncMessage(res);
           if (!message)
@@ -434,6 +604,7 @@ var OrderModule = class extends import_BaseModule.BaseModule {
           message._pubsubReceivedAt = pubsubReceivedAt;
           this.pendingSyncMessages.push(message);
           const throttleMs = this.getOrderSyncThrottleMs();
+          const routeInfo = this.resolveSyncMessageRoute(message);
           this.logInfo("orderSync-收到消息并入队", {
             id: message.id ?? null,
             order_id: message.order_id ?? null,
@@ -506,7 +677,6 @@ var OrderModule = class extends import_BaseModule.BaseModule {
    * await this.processOrderSyncMessages()
    */
   async processOrderSyncMessages() {
-    var _a;
     const messages = [...this.pendingSyncMessages];
     this.pendingSyncMessages = [];
     if (messages.length === 0)
@@ -523,38 +693,47 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     });
     const upsertOrders = /* @__PURE__ */ new Map();
     const refreshIds = [];
-    for (const msg of messages) {
-      const hasBatchIds = Array.isArray(msg.ids) && msg.ids.length > 0;
-      const singleId = msg.id ?? msg.order_id;
-      const hasSingleId = !hasBatchIds && singleId !== void 0 && singleId !== null;
-      const rawBody = msg.body || msg.data;
-      const normalizedBody = this.normalizeOrderSyncPayload(rawBody);
-      if (hasSingleId && normalizedBody) {
+    messages.forEach((msg, msgIndex) => {
+      const routeInfo = this.resolveSyncMessageRoute(msg);
+      const hasBatchIds = routeInfo.hasBatchIds;
+      const singleId = routeInfo.singleId;
+      const hasSingleId = routeInfo.hasSingleId;
+      const normalizedBody = this.normalizeOrderSyncPayload(msg.body || msg.data);
+      if (routeInfo.route === "bodyUpsert" && normalizedBody) {
         upsertOrders.set(this.getIdKey(normalizedBody.order_id), normalizedBody);
-        continue;
+        return;
       }
       if (hasBatchIds)
-        refreshIds.push(...msg.ids);
-      else if (hasSingleId)
+        refreshIds.push(...routeInfo.batchIds);
+      else if (routeInfo.route === "httpRefresh.singleId" && singleId !== null)
         refreshIds.push(singleId);
-      else if ((_a = msg.relation_order_ids) == null ? void 0 : _a.length)
-        refreshIds.push(...msg.relation_order_ids);
-    }
+      else if (routeInfo.route === "httpRefresh.relationIds")
+        refreshIds.push(...routeInfo.batchIds);
+    });
     const uniqueRefreshIds = this.uniqueOrderIds(refreshIds);
     const upsertList = [...upsertOrders.values()];
     this.logInfo("processOrderSyncMessages-去重完成", {
       upsertCount: upsertList.length,
       refreshIdCount: uniqueRefreshIds.length
     });
-    if (upsertList.length > 0)
-      await this.mergeOrdersToStore(upsertList);
+    if (upsertList.length > 0) {
+      await this.mergeOrdersToStore(upsertList, "pubsub.bodyUpsert");
+    }
     if (uniqueRefreshIds.length > 0) {
-      const freshOrders = await this.fetchOrdersByHttp(uniqueRefreshIds);
-      if (freshOrders.length > 0)
-        await this.mergeOrdersToStore(freshOrders);
+      const { toFetch, skipped } = this.filterRedundantHttpRefreshIds(uniqueRefreshIds);
+      if (skipped.length > 0) {
+      }
+      if (toFetch.length > 0) {
+        const freshOrders = await this.fetchOrdersByHttp(toFetch);
+        if (freshOrders.length > 0) {
+          await this.mergeOrdersToStore(freshOrders, "pubsub.httpRefresh");
+        } else {
+        }
+      }
     }
-    if (upsertList.length === 0 && uniqueRefreshIds.length === 0)
+    if (upsertList.length === 0 && uniqueRefreshIds.length === 0) {
       return;
+    }
     const batchProcessEndAt = Date.now();
     this.logInfo("processOrderSyncMessages-结束", {
       upsertCount: upsertList.length,
@@ -595,7 +774,7 @@ var OrderModule = class extends import_BaseModule.BaseModule {
   /**
    * 将增量订单合并到 store
    */
-  async mergeOrdersToStore(freshOrders) {
+  async mergeOrdersToStore(freshOrders, source) {
     this.logInfo("mergeOrdersToStore-开始", {
       freshOrderCount: freshOrders.length,
       storeOrderCountBefore: this.store.list.length
@@ -608,6 +787,8 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       freshMap.set(this.getIdKey(id), order);
     }
     const uniqueFreshCount = freshMap.size;
+    const patchedOrders = [...freshMap.values()];
+    const mergeActions = {};
     const updatedList = this.store.list.map((order) => {
       const id = order.order_id;
       if (id === void 0 || id === null)
@@ -617,14 +798,21 @@ var OrderModule = class extends import_BaseModule.BaseModule {
         return order;
       const fresh = freshMap.get(key);
       freshMap.delete(key);
+      mergeActions[key] = "update";
       return fresh;
     });
     for (const order of freshMap.values()) {
+      const id = order.order_id;
+      if (id !== void 0 && id !== null) {
+        mergeActions[this.getIdKey(id)] = "insert";
+      }
       updatedList.push(order);
     }
+    const insertCount = Object.values(mergeActions).filter((v) => v === "insert").length;
+    const updateCount = Object.values(mergeActions).filter((v) => v === "update").length;
     this.store.list = updatedList;
     this.syncOrdersMap();
-    await this.saveOrdersToSQLite(this.store.list);
+    await this.patchOrdersInSQLite(patchedOrders, source, mergeActions);
     this.logInfo("mergeOrdersToStore-结束", {
       uniqueFreshCount,
       storeOrderCountAfter: this.store.list.length
@@ -674,6 +862,24 @@ var OrderModule = class extends import_BaseModule.BaseModule {
   getIdKey(id) {
     return String(id);
   }
+  /**
+   * 解析订单 SQLite 主键，规则与宿主 OrderDataSource.getOrderStorageKey 一致。
+   *
+   * @example
+   * const key = this.getOrderStorageKey({ order_id: 1001, external_sale_number: 'S-1001' })
+   * // => 'S-1001'
+   */
+  getOrderStorageKey(order) {
+    const externalSaleNumber = order == null ? void 0 : order.external_sale_number;
+    if (externalSaleNumber !== void 0 && externalSaleNumber !== null && externalSaleNumber !== "") {
+      return String(externalSaleNumber);
+    }
+    const orderId = order == null ? void 0 : order.order_id;
+    if (orderId !== void 0 && orderId !== null && orderId !== "") {
+      return String(orderId);
+    }
+    return "";
+  }
   /**
    * 当前订单拉取窗口：
    * - 优先使用 createdAtQuery.sales_time_between（已按营业日边界初始化）
@@ -745,12 +951,11 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     }
   }
   /**
-   * 串行执行订单 SQLite 保存任务，保证 clear + bulkAdd 组合不会被其它订单保存插入。
+   * 串行执行订单 SQLite 写入任务，避免快照替换与增量 upsert 并发交错。
    *
    * @example
    * await this.runInOrderSQLiteSaveQueue(async () => {
-   *   await this.dbManager.clear(INDEXDB_STORE_NAME)
-   *   await this.dbManager.bulkAdd(INDEXDB_STORE_NAME, orders)
+   *   await this.dbManager.bulkUpdate(INDEXDB_STORE_NAME, orders)
    * })
    */
   async runInOrderSQLiteSaveQueue(task) {
@@ -759,33 +964,138 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     return queuedTask;
   }
   /**
-   * 保存订单列表到 SQLite，内部会先清空 orders 表再批量写入当前快照。
+   * 批量增量 upsert 订单到 SQLite，不清空表；用于 pubsub / HTTP 增量合并。
    *
    * @example
-   * await this.saveOrdersToSQLite(this.store.list)
+   * await this.patchOrdersInSQLite(freshOrders)
    */
-  async saveOrdersToSQLite(orderList) {
-    if (!this.dbManager)
+  async patchOrdersInSQLite(orders, source, mergeActions = {}) {
+    if (!this.dbManager || orders.length === 0) {
+      return;
+    }
+    const ordersSnapshot = (0, import_lodash_es.cloneDeep)(orders).filter((order) => this.getOrderStorageKey(order));
+    if (ordersSnapshot.length === 0) {
+      return;
+    }
+    const { toWrite, skipped } = this.filterRedundantPatchOrders(
+      source,
+      ordersSnapshot,
+      mergeActions
+    );
+    if (toWrite.length === 0) {
       return;
+    }
+    try {
+      await this.runInOrderSQLiteSaveQueue(async () => {
+        let writeMethod = "none";
+        this.logInfo("patchOrdersInSQLite-开始", {
+          source,
+          count: toWrite.length,
+          dedupedCount: skipped.length
+        });
+        if (typeof this.dbManager.bulkUpdate === "function") {
+          writeMethod = "bulkUpdate";
+          await this.dbManager.bulkUpdate(INDEXDB_STORE_NAME, toWrite);
+        } else if (typeof this.dbManager.bulkAdd === "function") {
+          writeMethod = "bulkAdd";
+          await this.dbManager.bulkAdd(INDEXDB_STORE_NAME, toWrite);
+        } else if (typeof this.dbManager.update === "function") {
+          writeMethod = "update";
+          for (const order of toWrite) {
+            await this.dbManager.update(INDEXDB_STORE_NAME, order);
+          }
+        }
+        this.recordRecentSqliteWrite(source, toWrite);
+        this.logInfo("patchOrdersInSQLite-完成", {
+          source,
+          count: toWrite.length,
+          writeMethod,
+          dedupedCount: skipped.length
+        });
+      });
+    } catch (error) {
+      this.logError("增量保存订单到 SQLite 失败", {
+        error: error instanceof Error ? error.message : String(error),
+        orderCount: ordersSnapshot.length
+      });
+    }
+  }
+  /**
+   * 单条 upsert 订单到 SQLite；用于 overwriteExistingOrder 等单条覆盖场景。
+   *
+   * @example
+   * await this.updateOrderInSQLite(freshOrder)
+   */
+  async updateOrderInSQLite(order, source) {
+    if (!this.dbManager || !this.getOrderStorageKey(order)) {
+      return;
+    }
+    const orderSnapshot = (0, import_lodash_es.cloneDeep)(order);
+    try {
+      await this.runInOrderSQLiteSaveQueue(async () => {
+        let writeMethod = "none";
+        this.logInfo("updateOrderInSQLite-开始", {
+          source,
+          orderId: orderSnapshot.order_id ?? null,
+          storageKey: this.getOrderStorageKey(orderSnapshot)
+        });
+        if (typeof this.dbManager.update === "function") {
+          writeMethod = "update";
+          await this.dbManager.update(INDEXDB_STORE_NAME, orderSnapshot);
+        } else if (typeof this.dbManager.bulkUpdate === "function") {
+          writeMethod = "bulkUpdate";
+          await this.dbManager.bulkUpdate(INDEXDB_STORE_NAME, [orderSnapshot]);
+        } else if (typeof this.dbManager.bulkAdd === "function") {
+          writeMethod = "bulkAdd";
+          await this.dbManager.bulkAdd(INDEXDB_STORE_NAME, [orderSnapshot]);
+        }
+        this.recordRecentSqliteWrite(source, [orderSnapshot]);
+        this.logInfo("updateOrderInSQLite-完成", {
+          source,
+          orderId: orderSnapshot.order_id ?? null,
+          writeMethod
+        });
+      });
+    } catch (error) {
+      this.logError("单条保存订单到 SQLite 失败", {
+        error: error instanceof Error ? error.message : String(error),
+        orderId: orderSnapshot.order_id ?? null
+      });
+    }
+  }
+  /**
+   * 全量快照替换 orders 表（clear + bulkAdd），用于 SSE 全量拉取与营业日窗口裁剪。
+   *
+   * @example
+   * await this.replaceOrdersSnapshotInSQLite(orderList)
+   */
+  async replaceOrdersSnapshotInSQLite(orderList, source) {
+    if (!this.dbManager) {
+      return;
+    }
     const orderListSnapshot = (0, import_lodash_es.cloneDeep)(orderList);
     try {
       await this.runInOrderSQLiteSaveQueue(async () => {
-        this.logInfo("saveOrdersToSQLite-开始", {
+        this.logInfo("replaceOrdersSnapshotInSQLite-开始", {
+          source,
           count: orderListSnapshot.length
         });
         await this.dbManager.clear(INDEXDB_STORE_NAME);
-        this.logInfo("saveOrdersToSQLite-clear完成", {
+        this.logInfo("replaceOrdersSnapshotInSQLite-clear完成", {
           count: orderListSnapshot.length
         });
-        if (orderListSnapshot.length === 0)
+        if (orderListSnapshot.length === 0) {
           return;
+        }
         await this.dbManager.bulkAdd(INDEXDB_STORE_NAME, orderListSnapshot);
-        this.logInfo("saveOrdersToSQLite-bulkAdd完成", {
+        this.recordRecentSqliteWrite(source, orderListSnapshot);
+        this.logInfo("replaceOrdersSnapshotInSQLite-bulkAdd完成", {
+          source,
           count: orderListSnapshot.length
         });
       });
     } catch (error) {
-      this.logError("保存订单到 SQLite 失败", {
+      this.logError("全量保存订单到 SQLite 失败", {
         error: error instanceof Error ? error.message : String(error),
         orderList: orderListSnapshot.length
       });

package/lib/server/modules/order/types.d.ts

@@ -94,8 +94,6 @@ export interface OrderProductLineItem {
     num: number;
     /** 多规格 ID。来源：Detail.product_variant_id */
     product_variant_id?: number;
-    /** 选项配置 */
-    product_option_item?: unknown[];
     /**
      * 销售单价（交易快照，仅输出）。
      * 来源：Detail.selling_price

package/lib/server/modules/products/index.d.ts

@@ -27,6 +27,12 @@ export declare class ProductsModule extends BaseModule implements Module {
     private productDataSource;
     private pendingSyncMessages;
     private syncTimer?;
+    /** 最近一次 SSE 全量拉取完成时间 */
+    private lastServerFullFetchAtMs;
+    /** 最近一次 preload 完成时间（含 IndexDB 命中） */
+    private lastPreloadCompletedAtMs;
+    /** IndexDB 写入串行队列，避免快照与 patch 并发交错 */
+    private productIndexDBSaveQueue;
     constructor(name?: string, version?: string);
     initialize(core: PisellCore, options: any): Promise<void>;
     /**
@@ -209,10 +215,28 @@ export declare class ProductsModule extends BaseModule implements Module {
      */
     private loadProductsFromIndexDB;
     /**
-     * 保存商品数据到 IndexDB（平铺存储）
-     * @private
+     * 串行执行商品 IndexDB 写入，避免快照替换与增量 patch 并发交错。
+     *
+     * @example
+     * await this.runInProductIndexDBSaveQueue(async () => {
+     *   await this.dbManager.bulkUpdate(INDEXDB_STORE_NAME, products)
+     * })
+     */
+    private runInProductIndexDBSaveQueue;
+    /**
+     * 全量快照写入 IndexDB：clear + bulkUpdate，仅用于 SSE/HTTP 全量拉取。
+     *
+     * @example
+     * await this.replaceProductsSnapshotInIndexDB(list, 'loadProductsByServer')
      */
-    private saveProductsToIndexDB;
+    private replaceProductsSnapshotInIndexDB;
+    /**
+     * 增量 upsert 商品到 IndexDB，不清空表；用于 pubsub 批次合并后的变更商品。
+     *
+     * @example
+     * await this.patchProductsInIndexDB(changedProducts, 'pubsub.processProductSyncMessages', mergeActions)
+     */
+    private patchProductsInIndexDB;
     /**
      * 同步更新商品 Map 缓存
      * 将 list 中的商品同步到 map，以 id 为 key
@@ -262,14 +286,17 @@ export declare class ProductsModule extends BaseModule implements Module {
     /**
      * 将 body 完整数据直接覆盖到本地 store（不调用报价单接口）
      * 已存在的 → 直接替换；不存在的 → 追加
-     * 同时更新 Map 缓存、IndexDB，触发 onProductsChanged
-     * 价格缓存由 processProductSyncMessages 末尾统一清除
+     *
+     * @example
+     * await this.applyBodyUpdatesToStore(bodyUpdates, { skipIndexDB: true })
      */
     private applyBodyUpdatesToStore;
     /**
      * 将增量拉取的商品合并到 store
      * 已存在的 → 替换；新的 → 追加
-     * 同时更新 store.map、IndexDB，触发 onProductsChanged
+     *
+     * @example
+     * await this.mergeProductsToStore(freshProducts, { skipIndexDB: true })
      */
     private mergeProductsToStore;
     /**