@pisell/pisellos 2.2.190 → 2.2.191

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

@@ -40,6 +40,15 @@ 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_FLOW_LOG_WINDOW_KEY = "__orderModuleFlowLogs";
+var ORDER_WRITE_STATS_WINDOW_KEY = "__orderModuleWriteStats";
+var ORDER_FLOW_LOG_MAX_LENGTH = 1e3;
+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 +60,12 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     // Map<resource_id, OrderId[]> 资源到订单的倒排索引
     this.resourceIdIndex = /* @__PURE__ */ new Map();
     this.orderSQLiteSaveQueue = Promise.resolve();
+    /** 全局递增的 SQLite 写入序号，便于日志关联同一次操作 */
+    this.orderFlowWriteSeq = 0;
+    /** 按 storageKey 记录最近一次 SQLite 写入来源与时间，用于去重 */
+    this.recentSqliteWriteByStorageKey = /* @__PURE__ */ new Map();
+    /** 最近一次 SSE 全量拉取完成时间 */
+    this.lastServerFullFetchAtMs = 0;
   }
   async initialize(core, options) {
     var _a, _b;
@@ -113,8 +128,15 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       this.store.list = [];
       this.store.map = /* @__PURE__ */ new Map();
     }
+    this.initOrderFlowLogs();
     this.initOrderDataSource();
     this.setupOrderSync();
+    this.pushOrderFlowLog("initialize.complete", {
+      hasDbManager: !!this.dbManager,
+      hasLogger: !!this.logger,
+      initialOrderCount: this.store.list.length,
+      createdAtQuery: this.store.createdAtQuery || null
+    });
     this.logInfo("OrderServer模块初始化完成", {
       hasDbManager: !!this.dbManager,
       hasLogger: !!this.logger,
@@ -154,6 +176,297 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       }
     } catch {
     }
+    this.pushOrderFlowLog(`error.${title}`, metadata);
+  }
+  /**
+   * 初始化 window 上的订单流程调试日志数组及辅助方法。
+   *
+   * @example
+   * window.clearOrderModuleFlowLogs()
+   * // 操作完成后：
+   * copy(window.exportOrderModuleFlowLogs?.() || '[]')
+   */
+  initOrderFlowLogs() {
+    try {
+      const win = typeof globalThis !== "undefined" ? globalThis.window : void 0;
+      if (!win)
+        return;
+      win[ORDER_FLOW_LOG_WINDOW_KEY] = [];
+      win[ORDER_WRITE_STATS_WINDOW_KEY] = {};
+      win.clearOrderModuleFlowLogs = () => {
+        win[ORDER_FLOW_LOG_WINDOW_KEY] = [];
+        win[ORDER_WRITE_STATS_WINDOW_KEY] = {};
+        this.orderFlowWriteSeq = 0;
+        this.recentSqliteWriteByStorageKey.clear();
+        this.lastServerFullFetchAtMs = 0;
+        this.pushOrderFlowLog("debug.clear", {});
+      };
+      win.exportOrderModuleFlowLogs = () => {
+        const logs = win[ORDER_FLOW_LOG_WINDOW_KEY] || [];
+        return JSON.stringify(logs, null, 2);
+      };
+      win.exportOrderModuleWriteStats = () => {
+        const stats = win[ORDER_WRITE_STATS_WINDOW_KEY] || {};
+        return JSON.stringify(stats, null, 2);
+      };
+      win.summarizeOrderModuleWrites = (topN = 20) => {
+        const stats = win[ORDER_WRITE_STATS_WINDOW_KEY] || {};
+        return Object.entries(stats).map(([storageKey, entries]) => {
+          const list = entries || [];
+          const sources = [...new Set(list.map((item) => item.source))];
+          const last = list[list.length - 1];
+          return {
+            storageKey,
+            orderId: (last == null ? void 0 : last.orderId) ?? null,
+            writeCount: list.length,
+            sources,
+            lastWriteAt: (last == null ? void 0 : last.ts) || ""
+          };
+        }).sort((a, b) => b.writeCount - a.writeCount).slice(0, topN);
+      };
+      this.pushOrderFlowLog("debug.init", {
+        logKey: ORDER_FLOW_LOG_WINDOW_KEY,
+        writeStatsKey: ORDER_WRITE_STATS_WINDOW_KEY,
+        helpers: [
+          "clearOrderModuleFlowLogs",
+          "exportOrderModuleFlowLogs",
+          "exportOrderModuleWriteStats",
+          "summarizeOrderModuleWrites"
+        ]
+      });
+    } catch {
+    }
+  }
+  /**
+   * 写入 window 订单流程调试日志。
+   *
+   * @example
+   * this.pushOrderFlowLog('mergeOrdersToStore.start', { count: 3 })
+   */
+  pushOrderFlowLog(step, metadata) {
+    try {
+      const win = typeof globalThis !== "undefined" ? globalThis.window : void 0;
+      if (!win)
+        return;
+      if (!Array.isArray(win[ORDER_FLOW_LOG_WINDOW_KEY])) {
+        win[ORDER_FLOW_LOG_WINDOW_KEY] = [];
+      }
+      const entry = {
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        step,
+        metadata: metadata || {}
+      };
+      win[ORDER_FLOW_LOG_WINDOW_KEY].push(entry);
+      const logs = win[ORDER_FLOW_LOG_WINDOW_KEY];
+      if (logs.length > ORDER_FLOW_LOG_MAX_LENGTH) {
+        logs.splice(0, logs.length - ORDER_FLOW_LOG_MAX_LENGTH);
+      }
+      console.log(`[OrderFlow] ${step}`, metadata || {});
+    } catch {
+    }
+  }
+  /** 当前内存 store 快照信息，供流程日志使用 */
+  getOrderStoreSnapshot() {
+    return {
+      storeListCount: this.store.list.length,
+      storeMapCount: this.store.map.size,
+      pendingSyncCount: this.pendingSyncMessages.length,
+      isProcessingSyncBatch: this.isProcessingSyncBatch,
+      isIdlePhase: this.isIdlePhase
+    };
+  }
+  /**
+   * 记录一次 SQLite 写入到 window 统计，用于排查同一订单被多次写入的原因。
+   *
+   * @example
+   * this.trackOrderWrite('upsertOrdersFromRemote', 'bulkUpdate', orders, 'insert')
+   */
+  trackOrderWrite(source, writeMethod, orders, mergeActions = {}, defaultMergeAction = "update") {
+    this.orderFlowWriteSeq += 1;
+    const writeSeq = this.orderFlowWriteSeq;
+    try {
+      const win = typeof globalThis !== "undefined" ? globalThis.window : void 0;
+      if (!win)
+        return writeSeq;
+      if (!win[ORDER_WRITE_STATS_WINDOW_KEY]) {
+        win[ORDER_WRITE_STATS_WINDOW_KEY] = {};
+      }
+      const stats = win[ORDER_WRITE_STATS_WINDOW_KEY];
+      for (const order of orders) {
+        const storageKey = this.getOrderStorageKey(order);
+        if (!storageKey)
+          continue;
+        const orderKey = order.order_id !== void 0 && order.order_id !== null ? this.getIdKey(order.order_id) : "";
+        const mergeAction = orderKey && mergeActions[orderKey] || defaultMergeAction;
+        const entry = {
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          writeSeq,
+          source,
+          writeMethod,
+          orderId: order.order_id ?? null,
+          storageKey,
+          mergeAction
+        };
+        if (!stats[storageKey])
+          stats[storageKey] = [];
+        stats[storageKey].push(entry);
+      }
+    } catch {
+    }
+    return writeSeq;
+  }
+  /**
+   * 记录订单最近一次 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);
@@ -165,14 +478,21 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     return DEFAULT_ORDER_SYNC_THROTTLE_MS;
   }
   async preload() {
+    this.pushOrderFlowLog("preload.start", this.getOrderStoreSnapshot());
     const getData = async () => {
       const orders = await this.loadOrdersByServer();
-      if (orders.length === 0)
+      if (orders.length === 0) {
+        this.pushOrderFlowLog("preload.empty", this.getOrderStoreSnapshot());
         return;
+      }
       this.store.list = (0, import_lodash_es.cloneDeep)(orders);
       this.syncOrdersMap();
       this.core.effects.emit(import_types.OrderHooks.onOrdersChanged, this.store.list);
       this.core.effects.emit(import_types.OrderHooks.onOrdersSyncCompleted, null);
+      this.pushOrderFlowLog("preload.done", {
+        ...this.getOrderStoreSnapshot(),
+        loadedCount: orders.length
+      });
     };
     getData();
   }
@@ -189,8 +509,11 @@ 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) {
+      this.pushOrderFlowLog("getLocalOrderByOrderId.hitMemory", { orderId, key });
       return memoryOrder;
+    }
+    this.pushOrderFlowLog("getLocalOrderByOrderId.missMemory", { orderId, key });
     const orders = await this.loadOrdersFromSQLite();
     const localOrder = orders.find((order) => {
       const shopOrderNumber = order == null ? void 0 : order.shop_order_number;
@@ -208,11 +531,16 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     return localOrder;
   }
   async loadOrdersByServer() {
-    var _a;
+    var _a, _b;
     let orderList = [];
+    this.pushOrderFlowLog("loadOrdersByServer.start", {
+      ...this.getOrderStoreSnapshot(),
+      query: ((_a = this.store) == null ? void 0 : _a.createdAtQuery) || null,
+      hasOrderDataSource: !!this.orderDataSource
+    });
     this.logInfo("loadOrdersByServer-开始", {
       hasOrderDataSource: !!this.orderDataSource,
-      query: ((_a = this.store) == null ? void 0 : _a.createdAtQuery) || null
+      query: ((_b = this.store) == null ? void 0 : _b.createdAtQuery) || null
     });
     if (this.orderDataSource) {
       try {
@@ -222,16 +550,23 @@ var OrderModule = class extends import_BaseModule.BaseModule {
           }
         });
         orderList = data || [];
+        this.pushOrderFlowLog("loadOrdersByServer.sseSuccess", { count: orderList.length });
         this.logInfo("loadOrdersByServer-SSE拉取成功", {
           count: orderList.length
         });
         this.markOrderPulledAtNow();
+        this.lastServerFullFetchAtMs = Date.now();
       } catch {
         orderList = [];
+        this.pushOrderFlowLog("loadOrdersByServer.sseFailed", {});
         this.logInfo("loadOrdersByServer-SSE拉取失败，回退为空数组");
       }
     }
-    await this.saveOrdersToSQLite(orderList);
+    await this.replaceOrdersSnapshotInSQLite(orderList, "loadOrdersByServer");
+    this.pushOrderFlowLog("loadOrdersByServer.done", {
+      count: orderList.length,
+      ...this.getOrderStoreSnapshot()
+    });
     this.logInfo("loadOrdersByServer-结束", {
       count: orderList.length
     });
@@ -245,6 +580,19 @@ 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) {
+      this.pushOrderFlowLog("silentRefresh.skipped", {
+        elapsedMs: elapsedSinceFullFetch,
+        minIntervalMs: ORDER_SILENT_REFRESH_MIN_INTERVAL_MS,
+        ...this.getOrderStoreSnapshot()
+      });
+      return this.store.list;
+    }
+    this.pushOrderFlowLog("silentRefresh.start", {
+      ...this.getOrderStoreSnapshot(),
+      callerHint: "Server.refreshOrdersInBackground 或其他调用方"
+    });
     this.logInfo("silentRefresh 开始");
     try {
       const orders = await this.loadOrdersByServer();
@@ -253,11 +601,17 @@ var OrderModule = class extends import_BaseModule.BaseModule {
         this.syncOrdersMap();
         this.core.effects.emit(import_types.OrderHooks.onOrdersChanged, this.store.list);
         await this.core.effects.emit(import_types.OrderHooks.onOrdersSyncCompleted, null);
+        this.pushOrderFlowLog("silentRefresh.done", {
+          orderCount: orders.length,
+          durationMs: Date.now() - startTime,
+          ...this.getOrderStoreSnapshot()
+        });
         this.logInfo("silentRefresh 完成", {
           orderCount: orders.length,
           duration: `${Date.now() - startTime}ms`
         });
       } else {
+        this.pushOrderFlowLog("silentRefresh.empty", { durationMs: Date.now() - startTime });
         this.logInfo("silentRefresh: 服务器未返回数据");
       }
       return this.store.list;
@@ -289,6 +643,12 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       this.logInfo("overwriteExistingOrder-本地不存在该订单，跳过", { orderId });
       return { overwritten: false };
     }
+    this.pushOrderFlowLog("overwriteExistingOrder.start", {
+      orderId,
+      storageKey: this.getOrderStorageKey(fresh),
+      ...this.getOrderStoreSnapshot(),
+      callerHint: "Server.handleUpdateLocalOrder 本地已存在时"
+    });
     this.logInfo("overwriteExistingOrder-开始覆盖", {
       orderId,
       storeOrderCountBefore: this.store.list.length
@@ -300,7 +660,11 @@ 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.pushOrderFlowLog("overwriteExistingOrder.done", {
+      orderId,
+      ...this.getOrderStoreSnapshot()
+    });
     this.logInfo("overwriteExistingOrder-结束", {
       orderId,
       storeOrderCountAfter: this.store.list.length
@@ -317,8 +681,13 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       this.logInfo("upsertOrdersFromRemote-订单列表为空", {});
       return;
     }
+    this.pushOrderFlowLog("upsertOrdersFromRemote.start", {
+      count: freshOrders.length,
+      orderIds: freshOrders.map((o) => o.order_id).filter((id) => id !== void 0 && id !== null),
+      callerHint: "Server.handleUpdateLocalOrder / handleOrderSalesDetail / handleUpdateLocalOrdersBatch"
+    });
     this.logInfo("upsertOrdersFromRemote-开始", { count: freshOrders.length });
-    await this.mergeOrdersToStore(freshOrders);
+    await this.mergeOrdersToStore(freshOrders, "upsertOrdersFromRemote");
   }
   /**
    * 通过 SSE 按自定义 query 拉取订单（支持 select/with 精简字段）
@@ -426,7 +795,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 +803,16 @@ var OrderModule = class extends import_BaseModule.BaseModule {
           message._pubsubReceivedAt = pubsubReceivedAt;
           this.pendingSyncMessages.push(message);
           const throttleMs = this.getOrderSyncThrottleMs();
+          const routeInfo = this.resolveSyncMessageRoute(message);
+          this.pushOrderFlowLog("orderSync.received", {
+            id: message.id ?? null,
+            order_id: message.order_id ?? null,
+            type: message.type ?? null,
+            pendingCount: this.pendingSyncMessages.length,
+            throttleMs,
+            ...routeInfo,
+            duplicateRiskHint: routeInfo.route === "httpRefresh.batchIds" && routeInfo.hasNormalizedBody ? "有 body 但被 ids 优先，会走 HTTP 重拉" : routeInfo.route === "bodyUpsert" ? "body 直写，可能与 upsertOrdersFromRemote 重复" : null
+          });
           this.logInfo("orderSync-收到消息并入队", {
             id: message.id ?? null,
             order_id: message.order_id ?? null,
@@ -459,6 +838,9 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       return;
     if (this.isIdlePhase) {
       this.isIdlePhase = false;
+      this.pushOrderFlowLog("orderSync.flushImmediate", {
+        pendingCount: this.pendingSyncMessages.length
+      });
       this.logInfo("orderSync-首条消息立即触发处理");
       void this.flushOrderSyncMessagesByThrottle();
       return;
@@ -466,6 +848,10 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     if (this.syncTimer)
       return;
     const throttleMs = this.getOrderSyncThrottleMs();
+    this.pushOrderFlowLog("orderSync.flushScheduled", {
+      pendingCount: this.pendingSyncMessages.length,
+      throttleMs
+    });
     this.syncTimer = setTimeout(() => {
       this.syncTimer = void 0;
       void this.flushOrderSyncMessagesByThrottle();
@@ -483,6 +869,9 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       return;
     }
     this.isProcessingSyncBatch = true;
+    this.pushOrderFlowLog("orderSync.flushStart", {
+      pendingCount: this.pendingSyncMessages.length
+    });
     try {
       await this.processOrderSyncMessages();
     } finally {
@@ -506,12 +895,15 @@ var OrderModule = class extends import_BaseModule.BaseModule {
    * await this.processOrderSyncMessages()
    */
   async processOrderSyncMessages() {
-    var _a;
     const messages = [...this.pendingSyncMessages];
     this.pendingSyncMessages = [];
     if (messages.length === 0)
       return;
     const batchProcessStartAt = Date.now();
+    this.pushOrderFlowLog("processOrderSyncMessages.start", {
+      messageCount: messages.length,
+      ...this.getOrderStoreSnapshot()
+    });
     const earliestReceivedAt = Math.min(
       ...messages.map((m) => m._pubsubReceivedAt ?? batchProcessStartAt)
     );
@@ -523,39 +915,74 @@ 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);
+      this.pushOrderFlowLog("processOrderSyncMessages.messageRoute", {
+        msgIndex,
+        ...routeInfo
+      });
+      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.pushOrderFlowLog("processOrderSyncMessages.deduped", {
+      upsertCount: upsertList.length,
+      upsertOrderIds: upsertList.map((o) => o.order_id),
+      refreshIdCount: uniqueRefreshIds.length,
+      refreshIds: uniqueRefreshIds,
+      willCallMergeTimes: (upsertList.length > 0 ? 1 : 0) + (uniqueRefreshIds.length > 0 ? 1 : 0)
+    });
     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) {
+        this.pushOrderFlowLog("processOrderSyncMessages.httpRefreshFiltered", {
+          requestedIds: uniqueRefreshIds,
+          skippedIds: skipped.map((item) => item.orderId),
+          skipped
+        });
+      }
+      if (toFetch.length > 0) {
+        const freshOrders = await this.fetchOrdersByHttp(toFetch);
+        if (freshOrders.length > 0) {
+          await this.mergeOrdersToStore(freshOrders, "pubsub.httpRefresh");
+        } else {
+          this.pushOrderFlowLog("processOrderSyncMessages.httpRefreshEmpty", {
+            refreshIds: toFetch
+          });
+        }
+      }
     }
-    if (upsertList.length === 0 && uniqueRefreshIds.length === 0)
+    if (upsertList.length === 0 && uniqueRefreshIds.length === 0) {
+      this.pushOrderFlowLog("processOrderSyncMessages.noop", {});
       return;
+    }
     const batchProcessEndAt = Date.now();
+    this.pushOrderFlowLog("processOrderSyncMessages.done", {
+      upsertCount: upsertList.length,
+      refreshIdCount: uniqueRefreshIds.length,
+      batchProcessDurationMs: batchProcessEndAt - batchProcessStartAt,
+      ...this.getOrderStoreSnapshot()
+    });
     this.logInfo("processOrderSyncMessages-结束", {
       upsertCount: upsertList.length,
       refreshIdCount: uniqueRefreshIds.length,
@@ -577,9 +1004,15 @@ var OrderModule = class extends import_BaseModule.BaseModule {
   async fetchOrdersByHttp(ids) {
     if (!this.orderDataSource || ids.length === 0)
       return [];
+    this.pushOrderFlowLog("fetchOrdersByHttp.start", { ids, count: ids.length });
     try {
       if (typeof this.orderDataSource.fetchOrdersByIds === "function") {
         const orderList2 = await this.orderDataSource.fetchOrdersByIds(ids);
+        this.pushOrderFlowLog("fetchOrdersByHttp.done", {
+          ids,
+          count: (orderList2 == null ? void 0 : orderList2.length) || 0,
+          via: "fetchOrdersByIds"
+        });
         return orderList2 || [];
       }
       const orderList = await this.orderDataSource.run({
@@ -587,15 +1020,27 @@ var OrderModule = class extends import_BaseModule.BaseModule {
           query: { ids }
         }
       });
+      this.pushOrderFlowLog("fetchOrdersByHttp.done", {
+        ids,
+        count: (orderList == null ? void 0 : orderList.length) || 0,
+        via: "run.http"
+      });
       return orderList || [];
     } catch {
+      this.pushOrderFlowLog("fetchOrdersByHttp.failed", { ids });
       return [];
     }
   }
   /**
    * 将增量订单合并到 store
    */
-  async mergeOrdersToStore(freshOrders) {
+  async mergeOrdersToStore(freshOrders, source) {
+    this.pushOrderFlowLog("mergeOrdersToStore.start", {
+      source,
+      freshOrderCount: freshOrders.length,
+      freshOrderIds: freshOrders.map((o) => o.order_id).filter((id) => id !== void 0 && id !== null),
+      ...this.getOrderStoreSnapshot()
+    });
     this.logInfo("mergeOrdersToStore-开始", {
       freshOrderCount: freshOrders.length,
       storeOrderCountBefore: this.store.list.length
@@ -608,6 +1053,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 +1064,32 @@ 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.pushOrderFlowLog("mergeOrdersToStore.done", {
+      source,
+      uniqueFreshCount,
+      insertCount,
+      updateCount,
+      patchedCount: patchedOrders.length,
+      patchedOrderIds: patchedOrders.map((o) => o.order_id),
+      patchedStorageKeys: patchedOrders.map((o) => this.getOrderStorageKey(o)),
+      mergeActions,
+      ...this.getOrderStoreSnapshot()
+    });
     this.logInfo("mergeOrdersToStore-结束", {
       uniqueFreshCount,
       storeOrderCountAfter: this.store.list.length
@@ -674,6 +1139,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 +1228,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 +1241,231 @@ 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) {
+      this.pushOrderFlowLog("patchOrdersInSQLite.skip", {
+        source,
+        hasDbManager: !!this.dbManager,
+        inputCount: orders.length
+      });
+      return;
+    }
+    const ordersSnapshot = (0, import_lodash_es.cloneDeep)(orders).filter((order) => this.getOrderStorageKey(order));
+    if (ordersSnapshot.length === 0) {
+      this.pushOrderFlowLog("patchOrdersInSQLite.skipNoStorageKey", {
+        source,
+        inputCount: orders.length
+      });
+      return;
+    }
+    const { toWrite, skipped } = this.filterRedundantPatchOrders(
+      source,
+      ordersSnapshot,
+      mergeActions
+    );
+    if (skipped.length > 0) {
+      this.pushOrderFlowLog("patchOrdersInSQLite.dedupeSkipped", {
+        source,
+        skippedCount: skipped.length,
+        skipped
+      });
+    }
+    if (toWrite.length === 0) {
+      this.pushOrderFlowLog("patchOrdersInSQLite.skipAllDeduped", {
+        source,
+        inputCount: ordersSnapshot.length,
+        skipped
+      });
+      return;
+    }
+    try {
+      await this.runInOrderSQLiteSaveQueue(async () => {
+        let writeMethod = "none";
+        this.pushOrderFlowLog("patchOrdersInSQLite.start", {
+          source,
+          count: toWrite.length,
+          orderIds: toWrite.map((o) => o.order_id),
+          storageKeys: toWrite.map((o) => this.getOrderStorageKey(o)),
+          dedupedCount: skipped.length
+        });
+        this.logInfo("patchOrdersInSQLite-开始", {
+          source,
+          count: toWrite.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);
+          }
+        }
+        const writeSeq = this.trackOrderWrite(source, writeMethod, toWrite, mergeActions);
+        this.recordRecentSqliteWrite(source, toWrite);
+        this.pushOrderFlowLog("patchOrdersInSQLite.done", {
+          source,
+          writeSeq,
+          count: toWrite.length,
+          writeMethod,
+          dedupedCount: skipped.length
+        });
+        this.logInfo("patchOrdersInSQLite-完成", {
+          source,
+          count: toWrite.length,
+          dedupedCount: skipped.length
+        });
+      });
+    } catch (error) {
+      this.pushOrderFlowLog("patchOrdersInSQLite.error", {
+        source,
+        error: error instanceof Error ? error.message : String(error),
+        orderCount: ordersSnapshot.length
+      });
+      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)) {
+      this.pushOrderFlowLog("updateOrderInSQLite.skip", {
+        source,
+        hasDbManager: !!this.dbManager,
+        orderId: (order == null ? void 0 : order.order_id) ?? null
+      });
       return;
+    }
+    const orderSnapshot = (0, import_lodash_es.cloneDeep)(order);
+    try {
+      await this.runInOrderSQLiteSaveQueue(async () => {
+        let writeMethod = "none";
+        this.pushOrderFlowLog("updateOrderInSQLite.start", {
+          source,
+          orderId: orderSnapshot.order_id ?? null,
+          storageKey: this.getOrderStorageKey(orderSnapshot)
+        });
+        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]);
+        }
+        const writeSeq = this.trackOrderWrite(
+          source,
+          writeMethod,
+          [orderSnapshot],
+          {},
+          "singleUpdate"
+        );
+        this.recordRecentSqliteWrite(source, [orderSnapshot]);
+        this.pushOrderFlowLog("updateOrderInSQLite.done", {
+          source,
+          writeSeq,
+          orderId: orderSnapshot.order_id ?? null,
+          storageKey: this.getOrderStorageKey(orderSnapshot),
+          writeMethod
+        });
+        this.logInfo("updateOrderInSQLite-完成", {
+          orderId: orderSnapshot.order_id ?? null
+        });
+      });
+    } catch (error) {
+      this.pushOrderFlowLog("updateOrderInSQLite.error", {
+        source,
+        error: error instanceof Error ? error.message : String(error),
+        orderId: orderSnapshot.order_id ?? null
+      });
+      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) {
+      this.pushOrderFlowLog("replaceOrdersSnapshotInSQLite.skip", { source, count: orderList.length });
+      return;
+    }
     const orderListSnapshot = (0, import_lodash_es.cloneDeep)(orderList);
     try {
       await this.runInOrderSQLiteSaveQueue(async () => {
-        this.logInfo("saveOrdersToSQLite-开始", {
+        this.pushOrderFlowLog("replaceOrdersSnapshotInSQLite.start", {
+          source,
+          count: orderListSnapshot.length
+        });
+        this.logInfo("replaceOrdersSnapshotInSQLite-开始", {
+          source,
           count: orderListSnapshot.length
         });
         await this.dbManager.clear(INDEXDB_STORE_NAME);
-        this.logInfo("saveOrdersToSQLite-clear完成", {
+        this.pushOrderFlowLog("replaceOrdersSnapshotInSQLite.cleared", {
+          source,
           count: orderListSnapshot.length
         });
-        if (orderListSnapshot.length === 0)
+        this.logInfo("replaceOrdersSnapshotInSQLite-clear完成", {
+          count: orderListSnapshot.length
+        });
+        if (orderListSnapshot.length === 0) {
+          this.pushOrderFlowLog("replaceOrdersSnapshotInSQLite.doneEmpty", { source });
           return;
+        }
         await this.dbManager.bulkAdd(INDEXDB_STORE_NAME, orderListSnapshot);
-        this.logInfo("saveOrdersToSQLite-bulkAdd完成", {
+        const writeSeq = this.trackOrderWrite(
+          source,
+          "clear+bulkAdd",
+          orderListSnapshot,
+          {},
+          "snapshot"
+        );
+        this.recordRecentSqliteWrite(source, orderListSnapshot);
+        this.pushOrderFlowLog("replaceOrdersSnapshotInSQLite.done", {
+          source,
+          writeSeq,
+          count: orderListSnapshot.length,
+          writeMethod: "clear+bulkAdd"
+        });
+        this.logInfo("replaceOrdersSnapshotInSQLite-bulkAdd完成", {
           count: orderListSnapshot.length
         });
       });
     } catch (error) {
-      this.logError("保存订单到 SQLite 失败", {
+      this.pushOrderFlowLog("replaceOrdersSnapshotInSQLite.error", {
+        source,
+        error: error instanceof Error ? error.message : String(error),
+        orderList: orderListSnapshot.length
+      });
+      this.logError("全量保存订单到 SQLite 失败", {
         error: error instanceof Error ? error.message : String(error),
         orderList: orderListSnapshot.length
       });