@pisell/pisellos 0.0.568 → 0.0.570

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

@@ -7,6 +7,7 @@ exports.OrderModule = void 0;
 var _lodashEs = require("lodash-es");
 var _dayjs = _interopRequireDefault(require("dayjs"));
 var _BaseModule = require("../../../modules/BaseModule");
+var _orderCollectionIdentity = require("../../../modules/Order/utils/orderCollectionIdentity");
 var _types = require("./types");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 /**
@@ -14,6 +15,27 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  */
 const INDEXDB_STORE_NAME = 'orders';
 const ORDER_LAST_FULL_FETCH_AT_STORAGE_KEY = 'server_order_last_full_fetch_at';
+const ORDER_SYNC_THROTTLE_MS_STORAGE_KEY = 'order_sync_throttle_ms';
+const DEFAULT_ORDER_SYNC_THROTTLE_MS = 2_000;
+/** pubsub 回声写入去重窗口：业务 API 刚写入后，跳过同单 SQLite patch */
+const ORDER_SQLITE_DEDUPE_MS = 15_000;
+/** silentRefresh 最小间隔，避免 preload 后立即全量重拉 */
+const ORDER_SILENT_REFRESH_MIN_INTERVAL_MS = 30_000;
+/** 视为「业务侧刚写入」的来源，pubsub 回声可跳过 SQLite */
+const ORDER_BUSINESS_WRITE_SOURCES = new Set(['upsertOrdersFromRemote', 'upsertPendingSyncOrders', 'overwriteExistingOrder', 'markOrderSyncedByExternalSaleNumber']);
+
+/**
+ * 合并热路径全表去重自检开关：默认关闭。
+ * 开启后每次合并会额外对整张 store 做一次 O(n^2) 重复检测并告警，
+ * 仅用于排查增量身份索引是否遗漏了重复订单，不应在生产常开。
+ */
+const ORDER_MERGE_SELF_CHECK = false;
+const ORDER_AUTHORITATIVE_COLLECTION_FIELDS = ['products', 'bookings', 'payments'];
+const ORDER_COLLECTION_KIND_BY_FIELD = {
+  products: 'product',
+  bookings: 'booking',
+  payments: 'payment'
+};
 
 /**
  * Order 模块 - 基础框架
@@ -26,14 +48,32 @@ class OrderModule extends _BaseModule.BaseModule {
   orderDataSource;
   pendingSyncMessages = [];
   syncTimer;
-  ORDER_SYNC_DEBOUNCE_MS = 5_000;
-  // Map<resource_id, OrderId[]> 资源到订单的倒排索引
-  resourceIdIndex = new Map();
+  isProcessingSyncBatch = false;
+  isIdlePhase = true;
   logger; // LoggerManager 实例
   storage;
+  orderSQLiteSaveQueue = Promise.resolve(); /** 按 storageKey 记录最近一次 SQLite 写入来源与时间，用于去重 */
+  recentSqliteWriteByStorageKey = new Map();
+  /** 最近一次 SSE 全量拉取完成时间 */
+  lastServerFullFetchAtMs = 0;
   constructor(name, version) {
     super(name, version);
   }
+
+  /**
+   * 广播订单变更事件，兼容全量列表订阅并额外携带本次变更订单。
+   *
+   * @example
+   * await this.emitOrdersChanged([freshOrder], 'pubsub.bodyUpsert')
+   */
+  async emitOrdersChanged(changedOrders = [], source) {
+    const payload = {
+      list: this.store.list,
+      changedOrders: changedOrders.map(order => this.normalizeOrderForMemoryList(order)),
+      source
+    };
+    await this.core.effects.emit(_types.OrderHooks.onOrdersChanged, payload);
+  }
   async initialize(core, options) {
     this.core = core;
     this.store = options?.store;
@@ -44,42 +84,12 @@ class OrderModule extends _BaseModule.BaseModule {
       this.dbManager = app.sqlite;
       this.logger = app.logger;
       this.storage = app.storage;
-      const coreData = app.data.store.getStore().getDataByModel('core');
-      if (!this.store.createdAtQuery?.sales_time_between && coreData?.core) {
-        const today = (0, _dayjs.default)();
-        if (coreData?.core.operating_day_boundary) {
-          const operatingDayBoundary = coreData.core.operating_day_boundary;
-          if (operatingDayBoundary.type === 'start_time') {
-            const boundaryTime = String(operatingDayBoundary.time || '').trim();
-            const boundaryStart = (0, _dayjs.default)(`${today.format('YYYY-MM-DD')} ${boundaryTime}`);
-            const boundaryEnd = boundaryStart.add(1, 'day');
-            if (boundaryStart.isValid()) {
-              this.store.createdAtQuery = {
-                sales_time_between: [boundaryStart.format('YYYY-MM-DD HH:mm:ss'), boundaryEnd.format('YYYY-MM-DD HH:mm:ss')]
-              };
-            } else {
-              // 边界时间异常时回退到自然日，避免 createdAtQuery 为空导致后续查询异常
-              this.store.createdAtQuery = {
-                sales_time_between: [today.startOf('day').format('YYYY-MM-DD HH:mm:ss'), today.endOf('day').format('YYYY-MM-DD HH:mm:ss')]
-              };
-            }
-          } else {
-            this.store.createdAtQuery = {
-              sales_time_between: [today.startOf('day').format('YYYY-MM-DD HH:mm:ss'), today.endOf('day').format('YYYY-MM-DD HH:mm:ss')]
-            };
-          }
-        } else {
-          // TODO: 这里后续可能需要使用店铺营业时间查询
-          this.store.createdAtQuery = {
-            sales_time_between: [today.startOf('day').format('YYYY-MM-DD HH:mm:ss'), today.endOf('day').format('YYYY-MM-DD HH:mm:ss')]
-          };
-        }
-      }
+      this.updateCreateStore();
     }
     if (Array.isArray(options?.initialState?.list)) {
-      this.store.list = options.initialState.list;
+      this.store.list = options.initialState.list.map(order => this.normalizeOrderForMemoryList(order));
       this.syncOrdersMap();
-      this.core.effects.emit(_types.OrderHooks.onOrdersChanged, this.store.list);
+      this.emitOrdersChanged([], 'initialState');
     } else {
       this.store.list = [];
       this.store.map = new Map();
@@ -94,10 +104,10 @@ class OrderModule extends _BaseModule.BaseModule {
   }
 
   /**
-  * 记录信息日志
-  * @param title 日志标题
-  * @param metadata 日志元数据
-  */
+   * 记录信息日志
+   * @param title 日志标题
+   * @param metadata 日志元数据
+   */
   logInfo(title, metadata) {
     try {
       if (this.logger) {
@@ -130,8 +140,312 @@ class OrderModule extends _BaseModule.BaseModule {
       // 日志记录失败不影响主流程
     }
   }
+  logWarning(title, metadata) {
+    try {
+      if (this.logger) {
+        this.logger.addLog({
+          type: 'warning',
+          title: `[OrderServerModule] ${title}`,
+          metadata: metadata || {}
+        });
+      }
+    } catch {
+      // 日志记录失败不影响主流程
+    }
+  }
+
+  /**
+   * 在订单进入内存或 SQLite 前统一压缩子项强身份重复并补齐协议 UID。
+   * 仅记录计数与订单标识，不输出商品、预约、支付或客户明细。
+   */
+  normalizeOrderCollectionsForIngress(order, source) {
+    const result = (0, _orderCollectionIdentity.normalizeOrderCollections)(order);
+    const kinds = ['product', 'booking', 'payment'];
+    const hasChanges = kinds.some(kind => {
+      const stats = result.stats[kind];
+      return stats.backfilledUidCount > 0 || stats.collapsedDuplicateCount > 0 || stats.uidConflictCount > 0 || stats.anonymousRowCount > 0;
+    });
+    if (hasChanges) {
+      const summarize = stats => ({
+        backfilled_uid_count: stats.backfilledUidCount,
+        collapsed_duplicate_count: stats.collapsedDuplicateCount,
+        uid_conflict_count: stats.uidConflictCount,
+        anonymous_row_count: stats.anonymousRowCount
+      });
+      const context = {
+        source,
+        order_id: order?.order_id ?? null,
+        external_sale_number: order?.external_sale_number ?? null,
+        products: summarize(result.stats.product),
+        bookings: summarize(result.stats.booking),
+        payments: summarize(result.stats.payment)
+      };
+      const hasUnsafeIdentity = kinds.some(kind => {
+        const stats = result.stats[kind];
+        return stats.uidConflictCount > 0 || stats.anonymousRowCount > 0;
+      });
+      if (hasUnsafeIdentity) {
+        this.logWarning('订单子项身份存在冲突或匿名行', context);
+      } else {
+        this.logInfo('订单子项身份已规范化', context);
+      }
+    }
+    return result.order;
+  }
+
+  /**
+   * incoming 决定权威成员集合；同一持久化行仍从 existing 补齐 incoming 省略的本地展示字段。
+   */
+  mergeAuthoritativeOrderCollection(field, existing, incoming, uidRemaps = []) {
+    const kind = ORDER_COLLECTION_KIND_BY_FIELD[field];
+    const existingItems = Array.isArray(existing) ? existing : [];
+    return incoming.map(incomingItem => {
+      const existingItem = existingItems.find(item => (0, _orderCollectionIdentity.isSameOrderCollectionItem)(kind, item, incomingItem));
+      if (!existingItem) return (0, _lodashEs.cloneDeep)(incomingItem);
+      const mergedItem = (0, _orderCollectionIdentity.mergeOrderCollectionItems)(kind, existingItem, incomingItem);
+      const mergedUid = (0, _orderCollectionIdentity.getOrderCollectionUid)(kind, mergedItem);
+      if (mergedUid) {
+        for (const from of new Set([(0, _orderCollectionIdentity.getOrderCollectionReferenceUid)(kind, existingItem), (0, _orderCollectionIdentity.getOrderCollectionReferenceUid)(kind, incomingItem)])) {
+          if (!from || from === mergedUid) continue;
+          uidRemaps.push({
+            kind,
+            from,
+            to: mergedUid,
+            persistentId: (0, _orderCollectionIdentity.getOrderCollectionPersistentId)(kind, incomingItem) || (0, _orderCollectionIdentity.getOrderCollectionPersistentId)(kind, existingItem)
+          });
+        }
+      }
+      return mergedItem;
+    });
+  }
+  reconcileOverwriteOrderCollections(existing, incoming) {
+    const reconciled = (0, _lodashEs.cloneDeep)(incoming);
+    const existingRecord = existing;
+    const incomingRecord = incoming;
+    const uidRemaps = [];
+    for (const field of ORDER_AUTHORITATIVE_COLLECTION_FIELDS) {
+      if (!Array.isArray(incomingRecord[field])) continue;
+      reconciled[field] = this.mergeAuthoritativeOrderCollection(field, existingRecord[field], incomingRecord[field], uidRemaps);
+    }
+    return this.normalizeOrderCollectionsForIngress((0, _orderCollectionIdentity.applyOrderCollectionUidRemaps)(reconciled, uidRemaps), 'overwriteExistingOrder.reconciled');
+  }
+
+  /**
+   * 记录订单最近一次 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 = 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 !== undefined && order.order_id !== null ? this.getIdKey(order.order_id) : '';
+      const mergeAction = orderKey ? mergeActions[orderKey] : undefined;
+
+      // 新增单必须落库，不参与去重
+      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) : undefined;
+      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) {
+    const hasBatchIds = Array.isArray(msg.ids) && msg.ids.length > 0;
+    const singleIdRaw = msg.id ?? msg.order_id;
+    const hasSingleId = !hasBatchIds && singleIdRaw !== undefined && 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?.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?.order_id ?? null
+      };
+    }
+    if (msg.relation_order_ids?.length) {
+      return {
+        route: 'httpRefresh.relationIds',
+        hasBatchIds: false,
+        hasSingleId: false,
+        hasNormalizedBody: !!normalizedBody,
+        singleId: null,
+        batchIds: msg.relation_order_ids,
+        bodyOrderId: normalizedBody?.order_id ?? null
+      };
+    }
+    return {
+      route: 'noop',
+      hasBatchIds: false,
+      hasSingleId: false,
+      hasNormalizedBody: !!normalizedBody,
+      singleId: null,
+      batchIds: [],
+      bodyOrderId: normalizedBody?.order_id ?? null
+    };
+  }
+  updateCreateStore() {
+    const appPlugin = this.core.getPlugin('app');
+    const app = appPlugin?.getApp();
+    if (app) {
+      const coreData = app.data.store.getStore().getDataByModel('core');
+      if (coreData?.core) {
+        const today = (0, _dayjs.default)();
+        if (coreData?.core.operating_day_boundary) {
+          const operatingDayBoundary = coreData.core.operating_day_boundary;
+          if (operatingDayBoundary.type === 'start_time') {
+            const boundaryTime = String(operatingDayBoundary.time || '').trim();
+            const boundaryStart = (0, _dayjs.default)(`${today.format('YYYY-MM-DD')} ${boundaryTime}`);
+            if (boundaryStart.isValid()) {
+              const isAfterBoundary = today.isAfter(boundaryStart);
+              const queryStart = isAfterBoundary ? today.startOf('day') : today.subtract(1, 'day').startOf('day');
+              const queryEnd = isAfterBoundary ? today.add(1, 'day').endOf('day') : today.endOf('day');
+              this.store.createdAtQuery = {
+                sales_time_between: [queryStart.format('YYYY-MM-DD HH:mm:ss'), queryEnd.format('YYYY-MM-DD HH:mm:ss')]
+              };
+            } else {
+              // 边界时间异常时回退到自然日，避免 createdAtQuery 为空导致后续查询异常
+              this.store.createdAtQuery = {
+                sales_time_between: [today.startOf('day').format('YYYY-MM-DD HH:mm:ss'), today.endOf('day').format('YYYY-MM-DD HH:mm:ss')]
+              };
+            }
+          } else {
+            this.store.createdAtQuery = {
+              sales_time_between: [today.startOf('day').format('YYYY-MM-DD HH:mm:ss'), today.endOf('day').format('YYYY-MM-DD HH:mm:ss')]
+            };
+          }
+        } else {
+          // TODO: 这里后续可能需要使用店铺营业时间查询
+          this.store.createdAtQuery = {
+            sales_time_between: [today.startOf('day').format('YYYY-MM-DD HH:mm:ss'), today.endOf('day').format('YYYY-MM-DD HH:mm:ss')]
+          };
+        }
+      }
+    }
+  }
+  getOrderSyncThrottleMs() {
+    const raw = localStorage.getItem(ORDER_SYNC_THROTTLE_MS_STORAGE_KEY);
+    if (raw !== null) {
+      const parsed = Number(raw);
+      if (Number.isFinite(parsed) && parsed >= 0) return parsed;
+    }
+    return DEFAULT_ORDER_SYNC_THROTTLE_MS;
+  }
   async preload() {
-    // const cachedOrders = await this.loadOrdersFromSQLite()
     // const hasPulledInCurrentWindow = this.hasPulledOrdersToday()
     // // 仅当缓存属于当前统计窗口时才直接复用，避免跨天/跨营业日窗口继续使用旧数据
     // if (cachedOrders.length > 0 && hasPulledInCurrentWindow) {
@@ -148,11 +462,17 @@ class OrderModule extends _BaseModule.BaseModule {
     //   return
     // }
 
-    const orders = await this.loadOrdersByServer();
-    if (orders.length === 0) return;
-    this.store.list = (0, _lodashEs.cloneDeep)(orders);
-    this.syncOrdersMap();
-    this.core.effects.emit(_types.OrderHooks.onOrdersChanged, this.store.list);
+    const getData = async () => {
+      const orders = await this.loadOrdersByServer();
+      if (orders.length === 0) {
+        return;
+      }
+      this.store.list = (0, _lodashEs.cloneDeep)(orders);
+      this.syncOrdersMap();
+      this.emitOrdersChanged([], 'preload');
+      this.core.effects.emit(_types.OrderHooks.onOrdersSyncCompleted, null);
+    };
+    getData();
   }
   getOrders() {
     return this.store.list;
@@ -161,32 +481,315 @@ class OrderModule extends _BaseModule.BaseModule {
     return this.store.map.get(this.getIdKey(id));
   }
 
-  /** 按 order_id 查询（推荐） */
+  /** 按 order_id 查询内存订单。 */
   getOrderByOrderId(orderId) {
     return this.store.map.get(this.getIdKey(orderId));
   }
+  getLocalOrderFromMemoryByLookup(lookup) {
+    const key = this.getIdKey(lookup);
+    const memoryOrderById = this.store.map.get(key);
+    if (memoryOrderById) return memoryOrderById;
+    const memoryOrder = this.store.list.find(order => this.isOrderLookupMatch(order, key));
+    return memoryOrder || null;
+  }
+  async getLocalOrderByLookup(lookup) {
+    const key = this.getIdKey(lookup);
+    const memoryOrderById = this.store.map.get(key);
+    if (memoryOrderById) return memoryOrderById;
+    const memoryOrder = this.store.list.find(order => this.isOrderLookupMatch(order, key));
+    if (memoryOrder) return memoryOrder;
+    const orders = await this.loadOrdersFromSQLite();
+    const localOrder = orders.find(order => this.isOrderLookupMatch(order, key));
+    if (!localOrder) return null;
+    this.store.list = orders.map(order => this.normalizeOrderForMemoryList(order));
+    this.syncOrdersMap();
+    return this.normalizeOrderForMemoryList(localOrder);
+  }
   async loadOrdersByServer() {
     let orderList = [];
+    this.logInfo('loadOrdersByServer-开始', {
+      hasOrderDataSource: !!this.orderDataSource,
+      query: this.store?.createdAtQuery || null
+    });
     if (this.orderDataSource) {
       try {
         const data = await this.orderDataSource.run({
-          http: {
+          sse: {
             query: this.store.createdAtQuery
           }
         });
         orderList = data || [];
+        this.logInfo('loadOrdersByServer-SSE拉取成功', {
+          count: orderList.length
+        });
         this.markOrderPulledAtNow();
+        this.lastServerFullFetchAtMs = Date.now();
       } catch {
-        orderList = [];
+        this.logInfo('loadOrdersByServer-SSE拉取失败，保持当前内存订单');
+        return this.store.list;
+      }
+    }
+    const mergedOrders = await this.replaceOrdersSnapshotInSQLite(orderList, 'loadOrdersByServer');
+    const memoryOrders = mergedOrders.map(order => this.normalizeOrderForMemoryList(order));
+    this.logInfo('loadOrdersByServer-结束', {
+      count: memoryOrders.length
+    });
+    await this.core.effects.emit(_types.OrderHooks.onOrdersLoaded, memoryOrders);
+    return memoryOrders;
+  }
+
+  /**
+   * 静默全量刷新：后台重新拉取全量 SSE 订单数据并更新本地
+   * 拿到完整数据后一次性替换 store，触发订单变更与同步完成事件
+   * @returns 刷新后的订单列表
+   */
+  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 {
+      // 刷新前，需要更新当前营业日边界（store.createdAtQuery）
+      this.updateCreateStore();
+      const orders = await this.loadOrdersByServer();
+      if (orders.length > 0) {
+        this.store.list = (0, _lodashEs.cloneDeep)(orders);
+        this.syncOrdersMap();
+        this.emitOrdersChanged([], 'silentRefresh');
+        await this.core.effects.emit(_types.OrderHooks.onOrdersSyncCompleted, null);
+        this.logInfo('silentRefresh 完成', {
+          orderCount: orders.length,
+          duration: `${Date.now() - startTime}ms`
+        });
+      } else {
+        this.logInfo('silentRefresh: 服务器未返回数据');
+      }
+      return this.store.list;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logError('silentRefresh 失败', {
+        duration: `${Date.now() - startTime}ms`,
+        error: errorMessage
+      });
+      return this.store.list;
+    }
+  }
+  normalizeOrderForMemoryList(order, source = 'normalizeOrderForMemoryList') {
+    const normalizedOrder = this.normalizeOrderCollectionsForIngress(order, source);
+    const externalSaleNumber = normalizedOrder?.external_sale_number;
+    if (normalizedOrder?.order_id !== undefined && normalizedOrder?.order_id !== null && normalizedOrder?.order_id !== '') {
+      return normalizedOrder;
+    }
+    if (externalSaleNumber === undefined || externalSaleNumber === null || externalSaleNumber === '') {
+      return normalizedOrder;
+    }
+    return {
+      ...normalizedOrder,
+      order_id: externalSaleNumber
+    };
+  }
+
+  /**
+   * 仅覆盖本地已存在的订单；不存在则直接跳过，不落库、不 emit。
+   * 适用于"按 order_id 主动刷新本地订单详情"的代理场景。
+   */
+  async overwriteExistingOrder(fresh) {
+    const orderId = fresh?.order_id;
+    if (orderId === undefined || orderId === null) {
+      this.logError('overwriteExistingOrder-入参缺少 order_id');
+      return {
+        overwritten: false
+      };
+    }
+    const key = this.getIdKey(orderId);
+    if (!this.store.map.has(key)) {
+      this.logInfo('overwriteExistingOrder-本地不存在该订单，跳过', {
+        orderId
+      });
+      return {
+        overwritten: false
+      };
+    }
+    this.logInfo('overwriteExistingOrder-开始覆盖', {
+      orderId,
+      storeOrderCountBefore: this.store.list.length
+    });
+    const normalizedFresh = this.normalizeOrderForMemoryList(fresh, 'overwriteExistingOrder.incoming');
+    const existingOrder = this.store.map.get(key);
+    const reconciledFresh = this.reconcileOverwriteOrderCollections(existingOrder, normalizedFresh);
+    this.store.list = this.store.list.map(order => {
+      const id = order?.order_id;
+      if (id === undefined || id === null) {
+        return this.normalizeOrderForMemoryList(order, 'overwriteExistingOrder.existingMemory');
+      }
+      return this.getIdKey(id) === key ? reconciledFresh : this.normalizeOrderForMemoryList(order, 'overwriteExistingOrder.existingMemory');
+    });
+    this.syncOrdersMap();
+    await this.updateOrderInSQLite(reconciledFresh, 'overwriteExistingOrder');
+    this.logInfo('overwriteExistingOrder-结束', {
+      orderId,
+      storeOrderCountAfter: this.store.list.length
+    });
+    await this.emitOrdersChanged([reconciledFresh], 'overwriteExistingOrder');
+    return {
+      overwritten: true
+    };
+  }
+
+  /**
+   * 将远端拉取的订单合并进本地 store（已存在则更新，不存在则追加），落库并 emit onOrdersChanged。
+   * 供 /update/localOrder 等在「本地尚无该单」时写入新建单。
+   */
+  async upsertOrdersFromRemote(freshOrders) {
+    if (!freshOrders?.length) {
+      this.logInfo('upsertOrdersFromRemote-订单列表为空', {});
+      return;
+    }
+    this.logInfo('upsertOrdersFromRemote-开始', {
+      count: freshOrders.length
+    });
+    await this.mergeOrdersToStore(freshOrders, 'upsertOrdersFromRemote');
+  }
+  async markOrderSyncedByExternalSaleNumber(params) {
+    const externalSaleNumber = params.externalSaleNumber;
+    if (externalSaleNumber === undefined || externalSaleNumber === null || externalSaleNumber === '') {
+      this.logError('markOrderSyncedByExternalSaleNumber-缺少 external_sale_number');
+      return {
+        updated: false
+      };
+    }
+    const key = this.getIdKey(externalSaleNumber);
+    const targetIndex = this.store.list.findIndex(order => {
+      const value = order?.external_sale_number;
+      if (value === undefined || value === null || value === '') return false;
+      return this.getIdKey(value) === key;
+    });
+    if (targetIndex < 0) {
+      this.logInfo('markOrderSyncedByExternalSaleNumber-本地订单不存在，跳过', {
+        external_sale_number: externalSaleNumber
+      });
+      return {
+        updated: false
+      };
+    }
+    const existing = this.store.list[targetIndex];
+    const nextOrder = this.normalizeRemoteSyncedOrder({
+      ...existing,
+      ...(params.patch || {}),
+      external_sale_number: existing.external_sale_number ?? externalSaleNumber,
+      need_sync: 0
+    });
+    const storageKey = this.getOrderStorageKey(nextOrder) || key;
+    this.store.list = this.store.list.map((order, index) => {
+      if (index !== targetIndex) return order;
+      return nextOrder;
+    });
+    this.syncOrdersMap();
+    await this.patchOrdersInSQLite([nextOrder], 'markOrderSyncedByExternalSaleNumber', {
+      [storageKey]: 'update'
+    });
+    this.logInfo('markOrderSyncedByExternalSaleNumber-完成', {
+      external_sale_number: externalSaleNumber,
+      order_id: nextOrder.order_id ?? null
+    });
+    await this.emitOrdersChanged([nextOrder], 'markOrderSyncedByExternalSaleNumber');
+    return {
+      updated: true,
+      order: nextOrder
+    };
+  }
+
+  /**
+   * 将本地待同步订单按 SQLite storage key 合并进 store 并落库。
+   * checkout 离线兜底可能没有 order_id，但通常会有 external_sale_number。
+   */
+  async upsertPendingSyncOrders(pendingOrders) {
+    if (!pendingOrders?.length) {
+      this.logInfo('upsertPendingSyncOrders-订单列表为空', {});
+      return;
+    }
+    const pendingMap = new Map();
+    const memoryPendingMap = new Map();
+    for (const order of pendingOrders) {
+      const normalizedOrder = this.normalizeOrderCollectionsForIngress(order, 'upsertPendingSyncOrders.incoming');
+      const storageKey = this.getOrderStorageKey(normalizedOrder);
+      if (!storageKey) continue;
+      pendingMap.set(storageKey, normalizedOrder);
+      memoryPendingMap.set(storageKey, this.normalizeOrderForMemoryList(normalizedOrder, 'upsertPendingSyncOrders.memory'));
+    }
+    if (pendingMap.size === 0) {
+      this.logError('upsertPendingSyncOrders-订单缺少可落库标识', {
+        count: pendingOrders.length
+      });
+      return;
+    }
+    this.logInfo('upsertPendingSyncOrders-开始', {
+      count: pendingMap.size
+    });
+    const mergeActions = {};
+    const updatedList = this.store.list.map(order => this.normalizeOrderForMemoryList(order, 'upsertPendingSyncOrders.existingMemory'));
+
+    // 与 mergeOrdersToStore 一致：基于身份键（field:value）建立索引，把「查找已存在订单」
+    // 从 O(n) 线性扫描降为 O(1)，整体复杂度由 O(n^2) 降为 O(n + m)。
+    const identityKeyToIndex = new Map();
+    for (let index = 0; index < updatedList.length; index += 1) {
+      for (const key of this.getOrderIdentityMatchKeys(updatedList[index])) {
+        // 同一 key 命中多张时保留最靠前的下标，与原 findIndex「取首个匹配」一致
+        if (!identityKeyToIndex.has(key)) identityKeyToIndex.set(key, index);
       }
     }
-    await this.saveOrdersToSQLite(orderList);
-    await this.core.effects.emit(_types.OrderHooks.onOrdersLoaded, orderList);
-    return orderList;
+    for (const [storageKey, pendingOrder] of memoryPendingMap.entries()) {
+      const matchIndex = this.lookupOrderIndexByIdentityKeys(identityKeyToIndex, this.getOrderIdentityMatchKeys(pendingOrder));
+      if (matchIndex >= 0) {
+        const existingOrder = updatedList[matchIndex];
+        const mergedOrder = this.mergeOrderRecords(existingOrder, pendingOrder);
+        updatedList[matchIndex] = mergedOrder;
+        const pendingSnapshot = pendingMap.get(storageKey);
+        if (pendingSnapshot) {
+          pendingMap.set(storageKey, this.reconcileOverwriteOrderCollections(existingOrder, pendingSnapshot));
+        }
+        // 合并后身份字段可能新增（如挂单拿到 order_id），同步登记，供同批后续 pending 命中同一槽位
+        this.registerOrderIdentityKeys(identityKeyToIndex, mergedOrder, matchIndex);
+        mergeActions[storageKey] = 'update';
+        continue;
+      }
+      const insertIndex = updatedList.length;
+      updatedList.push(pendingOrder);
+      this.registerOrderIdentityKeys(identityKeyToIndex, pendingOrder, insertIndex);
+      mergeActions[storageKey] = 'insert';
+    }
+    const patchedOrders = [...pendingMap.values()];
+    // 增量索引已保证 store 去重不变量，无需再对全表做 O(n^2) 压缩；仅自检开关开启时兜底。
+    this.store.list = this.runOrderStoreSelfCheck(updatedList, 'upsertPendingSyncOrders.store');
+    this.syncOrdersMap();
+    await this.patchOrdersInSQLite(patchedOrders, 'upsertPendingSyncOrders', mergeActions);
+    this.logInfo('upsertPendingSyncOrders-结束', {
+      count: patchedOrders.length,
+      storeOrderCountAfter: this.store.list.length
+    });
+    await this.emitOrdersChanged(patchedOrders, 'upsertPendingSyncOrders');
   }
-  getOrdersByResourceId(resourceId) {
-    const ids = this.resourceIdIndex.get(String(resourceId)) || [];
-    return ids.map(id => this.store.map.get(id)).filter(order => !!order);
+
+  /**
+   * 通过 SSE 按自定义 query 拉取订单（支持 select/with 精简字段）
+   */
+  async fetchOrdersBySSE(query = {}) {
+    if (!this.orderDataSource) return [];
+    try {
+      const data = await this.orderDataSource.run({
+        sse: {
+          query
+        }
+      });
+      return data || [];
+    } catch (error) {
+      this.logError('fetchOrdersBySSE-失败', {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return [];
+    }
   }
   getRoutes() {
     return [];
@@ -196,41 +799,67 @@ class OrderModule extends _BaseModule.BaseModule {
       clearTimeout(this.syncTimer);
       this.syncTimer = undefined;
     }
+    this.isProcessingSyncBatch = false;
     this.pendingSyncMessages = [];
     if (this.orderDataSource?.destroy) this.orderDataSource.destroy();
     super.destroy();
   }
   syncOrdersMap() {
     this.store.map.clear();
-    this.resourceIdIndex.clear();
     for (const order of this.store.list) {
-      const id = order.order_id;
-      if (id === undefined || id === null) continue;
-      this.store.map.set(this.getIdKey(id), order);
-      const resourceIds = this.extractResourceIds(order);
-      for (const resourceId of resourceIds) {
-        const key = String(resourceId);
-        const existing = this.resourceIdIndex.get(key) || [];
-        if (existing.some(eid => this.getIdKey(eid) === this.getIdKey(id))) continue;
-        existing.push(id);
-        this.resourceIdIndex.set(key, existing);
-      }
-    }
-  }
-  extractResourceIds(order) {
-    const ids = new Set();
-    const visitResources = resources => {
-      if (!Array.isArray(resources)) return;
-      resources.forEach(resource => {
-        const rid = resource?.relation_id;
-        if (rid !== undefined && rid !== null && rid !== '') ids.add(String(rid));
-        if (Array.isArray(resource?.children)) visitResources(resource.children);
+      const primaryIdentity = this.getOrderMapKey(order);
+      if (!primaryIdentity) continue;
+      this.store.map.set(primaryIdentity, order);
+    }
+  }
+  getOrderMapKey(order) {
+    if (!order) return '';
+    if (!this.isBlankIdentityValue(order.order_id)) {
+      return this.getIdKey(order.order_id);
+    }
+    const externalSaleNumber = order.external_sale_number;
+    if (!this.isBlankIdentityValue(externalSaleNumber)) {
+      return this.getIdKey(externalSaleNumber);
+    }
+    return '';
+  }
+  isBlankIdentityValue(value) {
+    return value === undefined || value === null || value === '';
+  }
+  getOrderIdentityEntries(order) {
+    if (!order) return [];
+    const record = order;
+    const candidates = [{
+      field: 'order_id',
+      value: order.order_id
+    }, {
+      field: 'external_sale_number',
+      value: record.external_sale_number
+    }, {
+      field: 'order_number',
+      value: record.order_number
+    }, {
+      field: 'shop_order_number',
+      value: record.shop_order_number
+    }];
+    const entries = [];
+    for (const candidate of candidates) {
+      if (this.isBlankIdentityValue(candidate.value)) continue;
+      const key = this.getIdKey(candidate.value);
+      if (entries.some(entry => entry.field === candidate.field && entry.key === key)) continue;
+      entries.push({
+        field: candidate.field,
+        key
       });
-    };
-    if (Array.isArray(order?.bookings)) {
-      order.bookings.forEach(booking => visitResources(booking?.resources || []));
     }
-    return [...ids];
+    return entries;
+  }
+  getOrderIdentityKeys(order) {
+    const keys = [];
+    for (const entry of this.getOrderIdentityEntries(order)) {
+      if (!keys.includes(entry.key)) keys.push(entry.key);
+    }
+    return keys;
   }
   getOrderDateKey(order) {
     const candidates = [order?.schedule_date, order?.create_date, order?.created_at, order?.bookings?.[0]?.start_date, order?.bookings?.[0]?.select_date];
@@ -253,73 +882,163 @@ class OrderModule extends _BaseModule.BaseModule {
   }
 
   /**
-   * 初始化 pubsub 订阅，监听订单变更
+   * 初始化 pubsub 订阅，监听订单变更（纯订阅，不拉数据；全量 SSE 由 loadOrdersByServer 负责）
    */
   setupOrderSync() {
     if (!this.orderDataSource) return;
-    const shouldSkipHttpPull = this.hasPulledOrdersToday();
-    const syncPayload = {
+    this.orderDataSource.run({
       pubsub: {
         callback: res => {
+          const pubsubReceivedAt = Date.now();
           const message = this.normalizeOrderSyncMessage(res);
           if (!message) return;
+          message._pubsubReceivedAt = pubsubReceivedAt;
           this.pendingSyncMessages.push(message);
-          if (this.syncTimer) clearTimeout(this.syncTimer);
-          this.syncTimer = setTimeout(() => {
-            this.processOrderSyncMessages();
-          }, this.ORDER_SYNC_DEBOUNCE_MS);
+          const throttleMs = this.getOrderSyncThrottleMs();
+          const routeInfo = this.resolveSyncMessageRoute(message);
+          this.logInfo('orderSync-收到消息并入队', {
+            id: message.id ?? null,
+            order_id: message.order_id ?? null,
+            type: message.type ?? null,
+            pendingCount: this.pendingSyncMessages.length,
+            throttleMs,
+            pubsubReceivedAt: new Date(pubsubReceivedAt).toISOString(),
+            fullMessage: JSON.stringify(message)
+          });
+          this.scheduleOrderSyncThrottle();
         }
       }
-    };
-    syncPayload.http = {
-      query: this.store.createdAtQuery,
-      skipHttp: shouldSkipHttpPull
-    };
-    this.orderDataSource.run(syncPayload).then(() => {
-      if (!shouldSkipHttpPull) this.markOrderPulledAtNow();
     }).catch(() => {
       // 忽略同步初始化异常，避免影响主流程
     });
   }
 
   /**
-   * 处理防抖后的同步消息批次
+   * 调度订单同步节流窗口（leading-edge throttle）：
+   * - 空闲状态下收到的第一条消息立即触发批处理，无需等待；
+   * - 首条处理后进入冷却窗口，窗口期间的后续消息聚合，窗口结束后批量处理；
+   * - 若当前批处理执行中，则由批处理结束后决定是否开启下一轮窗口。
+   */
+  scheduleOrderSyncThrottle() {
+    if (this.isProcessingSyncBatch) return;
+    if (this.isIdlePhase) {
+      this.isIdlePhase = false;
+      this.logInfo('orderSync-首条消息立即触发处理');
+      void this.flushOrderSyncMessagesByThrottle();
+      return;
+    }
+    if (this.syncTimer) return;
+    const throttleMs = this.getOrderSyncThrottleMs();
+    this.syncTimer = setTimeout(() => {
+      this.syncTimer = undefined;
+      void this.flushOrderSyncMessagesByThrottle();
+    }, throttleMs);
+  }
+
+  /**
+   * 执行一次节流批处理并在需要时续约下一轮窗口。
+   * 批处理完成且无后续消息时恢复空闲状态，下一条消息将立即触发。
+   */
+  async flushOrderSyncMessagesByThrottle() {
+    if (this.isProcessingSyncBatch) return;
+    if (this.pendingSyncMessages.length === 0) {
+      this.isIdlePhase = true;
+      return;
+    }
+    this.isProcessingSyncBatch = true;
+    try {
+      await this.processOrderSyncMessages();
+    } finally {
+      this.isProcessingSyncBatch = false;
+      if (this.pendingSyncMessages.length > 0) {
+        this.scheduleOrderSyncThrottle();
+      } else {
+        this.isIdlePhase = true;
+      }
+    }
+  }
+
+  /**
+   * 处理节流窗口内聚合后的同步消息批次
    *
    * 后端统一发送 change 消息，不再区分新增/编辑/删除。
    * - 单条（id/order_id）：若携带 body/data 则直接 upsert 到本地
    * - 批量（ids）：通过 HTTP 按 ids 增量拉取，再 merge 到本地
+   *
+   * @example
+   * // pending 队列中存在 8 条消息时，仅处理一次批次并统一 merge
+   * await this.processOrderSyncMessages()
    */
   async processOrderSyncMessages() {
     const messages = [...this.pendingSyncMessages];
     this.pendingSyncMessages = [];
     if (messages.length === 0) return;
+    const batchProcessStartAt = Date.now();
+    const earliestReceivedAt = Math.min(...messages.map(m => m._pubsubReceivedAt ?? batchProcessStartAt));
+    this.logInfo('processOrderSyncMessages-开始', {
+      messageCount: messages.length,
+      earliestReceivedAt: new Date(earliestReceivedAt).toISOString(),
+      batchProcessStartAt: new Date(batchProcessStartAt).toISOString(),
+      waitDurationMs: batchProcessStartAt - earliestReceivedAt
+    });
     const upsertOrders = 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 !== undefined && 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(singleId);else if (msg.relation_order_ids?.length) refreshIds.push(...msg.relation_order_ids);
-    }
+      if (hasBatchIds) refreshIds.push(...routeInfo.batchIds);else if (routeInfo.route === 'httpRefresh.singleId' && singleId !== null) refreshIds.push(singleId);else if (routeInfo.route === 'httpRefresh.relationIds') refreshIds.push(...routeInfo.batchIds);
+    });
     const uniqueRefreshIds = this.uniqueOrderIds(refreshIds);
     const upsertList = [...upsertOrders.values()];
-    if (upsertList.length > 0) await this.mergeOrdersToStore(upsertList);
+    this.logInfo('processOrderSyncMessages-去重完成', {
+      upsertCount: upsertList.length,
+      refreshIdCount: uniqueRefreshIds.length
+    });
+    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) {
+      return;
     }
-    if (upsertList.length === 0 && uniqueRefreshIds.length === 0) return;
+    const batchProcessEndAt = Date.now();
+    this.logInfo('processOrderSyncMessages-结束', {
+      upsertCount: upsertList.length,
+      refreshIdCount: uniqueRefreshIds.length,
+      batchProcessDurationMs: batchProcessEndAt - batchProcessStartAt,
+      totalFromPubsubToProcessedMs: batchProcessEndAt - earliestReceivedAt
+    });
     await this.core.effects.emit(_types.OrderHooks.onOrdersSyncCompleted, null);
   }
 
   /**
-   * 通过 HTTP 按 ids 增量拉取订单
+   * 通过 HTTP 按 ids 批量拉取订单详情（走 orderDataSource）。
+   *
+   * - 优先使用 `orderDataSource.fetchOrdersByIds`（如适配器实现了该方法）
+   * - 否则回退到 `orderDataSource.run({ http: { query: { ids } } })`
+   * - 失败统一返回空数组（由调用方按"返回缺失的 id" 判断单笔失败）
+   *
+   * @example
+   * const fresh = await orderModule.fetchOrdersByHttp(['96971', '96972'])
    */
   async fetchOrdersByHttp(ids) {
     if (!this.orderDataSource || ids.length === 0) return [];
@@ -344,29 +1063,145 @@ class OrderModule extends _BaseModule.BaseModule {
   /**
    * 将增量订单合并到 store
    */
-  async mergeOrdersToStore(freshOrders) {
-    const freshMap = new Map();
+  async mergeOrdersToStore(freshOrders, source) {
+    const storeOrderCountBefore = this.store.list.length;
+    this.logInfo('mergeOrdersToStore-开始', {
+      freshOrderCount: freshOrders.length,
+      storeOrderCountBefore,
+      source
+    });
+    this.logDuplicateOrders(`${source}.beforeMerge`, this.store.list);
+    const normalizedFreshOrders = [];
     for (const order of freshOrders) {
       const id = order?.order_id;
       if (id === undefined || id === null) continue;
-      freshMap.set(this.getIdKey(id), order);
-    }
-    const updatedList = this.store.list.map(order => {
-      const id = order.order_id;
-      if (id === undefined || id === null) return order;
-      const key = this.getIdKey(id);
-      if (!freshMap.has(key)) return order;
-      const fresh = freshMap.get(key);
-      freshMap.delete(key);
-      return fresh;
-    });
-    for (const order of freshMap.values()) {
-      updatedList.push(order);
+      normalizedFreshOrders.push(this.normalizeRemoteSyncedOrder(order));
+    }
+    // 先对本批新单做去重（批内规模 m 很小），保证每条 fresh 身份唯一
+    const uniqueFreshOrders = this.compactOrderListByIdentity(normalizedFreshOrders, `${source}.incoming`).list;
+    const uniqueFreshCount = uniqueFreshOrders.length;
+    const patchedOrders = [];
+    const mergeActions = {};
+    const updatedList = this.store.list.map(order => this.normalizeOrderForMemoryList(order, `${source}.existingMemory`));
+
+    // 基于身份键（field:value）建立索引，把「查找已存在订单」从 O(n) 线性扫描降为 O(1)，
+    // 整体合并复杂度由 O(n^2) 降为 O(n + m)。索引语义与 doOrdersShareIdentity 完全一致：
+    // 任一身份字段（order_id/external_sale_number/order_number/shop_order_number）同值即同一单。
+    const identityKeyToIndex = new Map();
+    for (let index = 0; index < updatedList.length; index += 1) {
+      const identityKeys = this.getOrderIdentityMatchKeys(updatedList[index]);
+      for (const key of identityKeys) {
+        // 同一 key 命中多张时保留最靠前的下标，与原 findIndex「取首个匹配」一致
+        if (!identityKeyToIndex.has(key)) identityKeyToIndex.set(key, index);
+      }
+    }
+    for (const fresh of uniqueFreshOrders) {
+      const freshIdentityKeys = this.getOrderIdentityMatchKeys(fresh);
+      const matchIndex = this.lookupOrderIndexByIdentityKeys(identityKeyToIndex, freshIdentityKeys);
+      const storageKey = this.getOrderStorageKey(fresh);
+      const mergeKey = storageKey || (fresh.order_id !== undefined && fresh.order_id !== null ? this.getIdKey(fresh.order_id) : '');
+      if (matchIndex >= 0) {
+        const existingOrder = updatedList[matchIndex];
+        if (this.isPendingSyncOrder(existingOrder) && this.isRemoteEchoMergeSource(source)) {
+          this.logInfo('mergeOrdersToStore-跳过 pending 订单远端覆盖', {
+            source,
+            order_id: existingOrder.order_id ?? fresh.order_id ?? null,
+            external_sale_number: existingOrder.external_sale_number ?? fresh.external_sale_number ?? null,
+            local_payment_status: existingOrder.payment_status ?? null,
+            remote_payment_status: fresh.payment_status ?? null,
+            local_need_sync: existingOrder.need_sync ?? null,
+            remote_need_sync: fresh.need_sync ?? null,
+            reason: 'protect_pending_sync_order_from_remote_echo'
+          });
+          continue;
+        }
+        const mergedOrder = this.mergeOrderRecords(existingOrder, fresh);
+        updatedList[matchIndex] = mergedOrder;
+        // 合并后身份字段可能新增（如挂单拿到 order_id），同步登记到索引，
+        // 供同批后续 fresh 命中同一槽位，避免重复插入
+        this.registerOrderIdentityKeys(identityKeyToIndex, mergedOrder, matchIndex);
+        patchedOrders.push(mergedOrder);
+        if (mergeKey) mergeActions[mergeKey] = 'update';
+        continue;
+      }
+      const insertIndex = updatedList.length;
+      updatedList.push(fresh);
+      this.registerOrderIdentityKeys(identityKeyToIndex, fresh, insertIndex);
+      patchedOrders.push(fresh);
+      if (mergeKey) mergeActions[mergeKey] = 'insert';
     }
-    this.store.list = updatedList;
+    const insertCount = Object.values(mergeActions).filter(v => v === 'insert').length;
+    const updateCount = Object.values(mergeActions).filter(v => v === 'update').length;
+    this.logInfo('mergeOrdersToStore-合并完成', {
+      insertCount,
+      updateCount,
+      storeOrderCountAfter: this.store.list.length
+    });
+    // 增量索引已保证 store 去重不变量，无需再对全表做 O(n^2) 压缩；
+    // 仅在自检开关开启时做一次兜底校验。
+    this.store.list = this.runOrderStoreSelfCheck(updatedList, `${source}.store`);
     this.syncOrdersMap();
-    await this.saveOrdersToSQLite(this.store.list);
-    this.core.effects.emit(_types.OrderHooks.onOrdersChanged, this.store.list);
+    await this.patchOrdersInSQLite(patchedOrders, source, mergeActions);
+    this.logInfo('mergeOrdersToStore-结束', {
+      uniqueFreshCount,
+      storeOrderCountAfter: this.store.list.length,
+      insertCount,
+      updateCount
+    });
+    await this.emitOrdersChanged(patchedOrders, source);
+  }
+
+  /**
+   * 在身份索引中查找与目标订单共享任一身份键的已存在订单下标。
+   * 返回所有命中键里最小的下标，等价于原 findOrderIndexByIdentity 的「取首个匹配」语义。
+   *
+   * @example
+   * const idx = this.lookupOrderIndexByIdentityKeys(identityKeyToIndex, freshIdentityKeys)
+   */
+  lookupOrderIndexByIdentityKeys(identityKeyToIndex, identityKeys) {
+    let matchIndex = -1;
+    for (const key of identityKeys) {
+      const index = identityKeyToIndex.get(key);
+      if (index === undefined) continue;
+      if (matchIndex < 0 || index < matchIndex) matchIndex = index;
+    }
+    return matchIndex;
+  }
+  isRemoteEchoMergeSource(source) {
+    return source === 'pubsub.bodyUpsert' || source === 'pubsub.httpRefresh';
+  }
+
+  /**
+   * 将订单的全部身份键登记到索引并指向其在列表中的下标。
+   * 合并后订单新增的身份字段（如挂单同步后拿到 order_id）也会被登记。
+   *
+   * @example
+   * this.registerOrderIdentityKeys(identityKeyToIndex, mergedOrder, matchIndex)
+   */
+  registerOrderIdentityKeys(identityKeyToIndex, order, index) {
+    const identityKeys = this.getOrderIdentityMatchKeys(order);
+    for (const key of identityKeys) {
+      identityKeyToIndex.set(key, index);
+    }
+  }
+
+  /**
+   * 合并热路径去重兜底：默认直接返回原列表（增量索引已保证无重复）。
+   * 仅当 ORDER_MERGE_SELF_CHECK 开启时，额外做一次全表压缩并在发现残留重复时告警。
+   */
+  runOrderStoreSelfCheck(orders, source) {
+    if (!ORDER_MERGE_SELF_CHECK) return orders;
+    const {
+      list,
+      removedCount
+    } = this.compactOrderListByIdentity(orders, source);
+    if (removedCount > 0) {
+      this.logWarning('合并自检发现残留重复订单，已压缩', {
+        source,
+        removedCount
+      });
+    }
+    return list;
   }
   normalizeOrderSyncMessage(res) {
     const data = res?.data || res;
@@ -404,6 +1239,169 @@ class OrderModule extends _BaseModule.BaseModule {
   getIdKey(id) {
     return String(id);
   }
+  isOrderLookupMatch(order, lookupKey) {
+    if (!order || !lookupKey) return false;
+    const candidates = [order.order_id, order.external_sale_number, order.order_number, order.shop_order_number, order.shop_full_order_number];
+    return candidates.some(value => {
+      if (value === undefined || value === null || value === '') return false;
+      return this.getIdKey(value) === lookupKey;
+    });
+  }
+
+  /**
+   * 解析订单 SQLite 主键，规则与宿主 OrderDataSource.getOrderStorageKey 一致。
+   *
+   * @example
+   * const key = this.getOrderStorageKey({ order_id: 1001, external_sale_number: 'S-1001' })
+   * // => 'S-1001'
+   */
+  getOrderStorageKey(order) {
+    const externalSaleNumber = order?.external_sale_number;
+    if (externalSaleNumber !== undefined && externalSaleNumber !== null && externalSaleNumber !== '') {
+      return String(externalSaleNumber);
+    }
+    const orderId = order?.order_id;
+    if (orderId !== undefined && orderId !== null && orderId !== '') {
+      return String(orderId);
+    }
+    return '';
+  }
+  getOrderIdentityMatchKeys(order) {
+    return this.getOrderIdentityEntries(order).map(entry => `${entry.field}:${entry.key}`);
+  }
+  doOrdersShareIdentity(left, right) {
+    const leftKeys = new Set(this.getOrderIdentityMatchKeys(left));
+    if (leftKeys.size === 0) return false;
+    return this.getOrderIdentityMatchKeys(right).some(key => leftKeys.has(key));
+  }
+  findOrderIndexByIdentity(orders, target) {
+    if (this.getOrderIdentityMatchKeys(target).length === 0) return -1;
+    return orders.findIndex(order => this.doOrdersShareIdentity(order, target));
+  }
+  getOrderCompletenessScore(order) {
+    const record = order;
+    let score = this.isPendingSyncOrder(order) ? 0 : 100;
+    if (!this.isBlankIdentityValue(order.order_id) && order.order_id !== record.external_sale_number) score += 30;
+    score += this.getOrderIdentityMatchKeys(order).length * 5;
+    if (Array.isArray(order.products)) score += Math.min(order.products.length, 10);
+    if (Array.isArray(order.bookings)) score += Math.min(order.bookings.length, 10);
+    if (Array.isArray(order.payments)) score += Math.min(order.payments.length, 10);
+    if (record.updated_at) score += 1;
+    return score;
+  }
+  pickPreferredOrder(left, right) {
+    const leftScore = this.getOrderCompletenessScore(left);
+    const rightScore = this.getOrderCompletenessScore(right);
+    if (rightScore >= leftScore) return right;
+    return left;
+  }
+  mergeOrderRecords(existing, incoming) {
+    const preferred = this.pickPreferredOrder(existing, incoming);
+    const secondary = preferred === existing ? incoming : existing;
+    const merged = {
+      ...secondary,
+      ...preferred
+    };
+    const fieldsToPreserve = ['order_id', 'external_sale_number', 'order_number', 'shop_order_number', 'shop_full_order_number'];
+    const incomingPatchFields = ['payment_status', 'status', 'shipping_status', 'updated_at', 'shop_discount', 'summary', 'note', 'customer_id', 'customer_name', 'customer', 'holder', 'contacts_info', 'phone', 'email', 'relation_forms'];
+    const mergedRecord = merged;
+    const preferredRecord = preferred;
+    const secondaryRecord = secondary;
+    const existingRecord = existing;
+    const incomingRecord = incoming;
+    const childUidRemaps = [];
+    for (const field of fieldsToPreserve) {
+      if (!this.isBlankIdentityValue(preferredRecord[field])) {
+        mergedRecord[field] = preferredRecord[field];
+        continue;
+      }
+      if (!this.isBlankIdentityValue(secondaryRecord[field])) {
+        mergedRecord[field] = secondaryRecord[field];
+      }
+    }
+    for (const field of incomingPatchFields) {
+      if (!Object.prototype.hasOwnProperty.call(incomingRecord, field)) continue;
+      if (incomingRecord[field] === undefined || incomingRecord[field] === null) continue;
+      if (typeof incomingRecord[field] === 'string' && incomingRecord[field] === '') continue;
+      mergedRecord[field] = (0, _lodashEs.cloneDeep)(incomingRecord[field]);
+    }
+
+    // 子项数组遵循完整快照语义：incoming 自有且为数组（包括 []）时权威替换；
+    // 字段缺席或不是数组时视为稀疏 patch，继续保留 existing。
+    for (const field of ORDER_AUTHORITATIVE_COLLECTION_FIELDS) {
+      if (Array.isArray(incomingRecord[field])) {
+        mergedRecord[field] = this.mergeAuthoritativeOrderCollection(field, existingRecord[field], incomingRecord[field], childUidRemaps);
+        continue;
+      }
+      if (Object.prototype.hasOwnProperty.call(existingRecord, field)) {
+        mergedRecord[field] = (0, _lodashEs.cloneDeep)(existingRecord[field]);
+      } else {
+        delete mergedRecord[field];
+      }
+    }
+    if (!this.isPendingSyncOrder(preferred) || !this.isPendingSyncOrder(secondary)) {
+      merged.need_sync = 0;
+    }
+    return this.normalizeOrderCollectionsForIngress((0, _orderCollectionIdentity.applyOrderCollectionUidRemaps)(merged, childUidRemaps), 'mergeOrderRecords');
+  }
+  summarizeDuplicateOrders(orders) {
+    const groups = new Map();
+    for (const order of orders) {
+      for (const key of this.getOrderIdentityMatchKeys(order)) {
+        const group = groups.get(key) || [];
+        group.push(order);
+        groups.set(key, group);
+      }
+    }
+    return [...groups.entries()].filter(([, group]) => group.length > 1).slice(0, 20).map(([key, group]) => ({
+      key,
+      count: group.length,
+      orders: group.map(order => ({
+        order_id: order.order_id ?? null,
+        external_sale_number: order.external_sale_number ?? null,
+        shop_order_number: order.shop_order_number ?? null,
+        shop_full_order_number: order.shop_full_order_number ?? null,
+        need_sync: order.need_sync ?? null
+      }))
+    }));
+  }
+  logDuplicateOrders(source, orders) {
+    const duplicateGroups = this.summarizeDuplicateOrders(orders);
+    if (duplicateGroups.length === 0) return;
+    this.logWarning('检测到重复订单身份键', {
+      source,
+      duplicateGroupCount: duplicateGroups.length,
+      duplicateGroups
+    });
+  }
+  compactOrderListByIdentity(orders, source) {
+    const list = [];
+    let removedCount = 0;
+    for (const order of orders) {
+      const normalizedOrder = this.normalizeOrderCollectionsForIngress(order, `${source}.order`);
+      const matchIndex = this.findOrderIndexByIdentity(list, normalizedOrder);
+      if (matchIndex < 0) {
+        list.push(normalizedOrder);
+        continue;
+      }
+      list[matchIndex] = this.mergeOrderRecords(list[matchIndex], normalizedOrder);
+      removedCount += 1;
+    }
+    if (removedCount > 0) {
+      this.logWarning('订单列表重复项已压缩', {
+        source,
+        beforeCount: orders.length,
+        afterCount: list.length,
+        removedCount
+      });
+    } else {
+      this.logDuplicateOrders(source, orders);
+    }
+    return {
+      list,
+      removedCount
+    };
+  }
 
   /**
    * 当前订单拉取窗口：
@@ -474,34 +1472,219 @@ class OrderModule extends _BaseModule.BaseModule {
     if (!this.dbManager) return [];
     try {
       const orders = await this.dbManager.getAll(INDEXDB_STORE_NAME);
-      return orders || [];
+      return (orders || []).map(order => this.normalizeOrderCollectionsForIngress(order, 'loadOrdersFromSQLite'));
     } catch {
       return [];
     }
   }
-  async saveOrdersToSQLite(orderList) {
-    if (!this.dbManager) return;
+  isPendingSyncOrder(order) {
+    return Number(order?.need_sync) === 1;
+  }
+  normalizeRemoteSyncedOrder(order) {
+    const normalizedOrder = this.normalizeOrderCollectionsForIngress(order, 'normalizeRemoteSyncedOrder');
+    if (this.isPendingSyncOrder(normalizedOrder)) return normalizedOrder;
+    return {
+      ...normalizedOrder,
+      need_sync: 0
+    };
+  }
+  mergeRemoteSnapshotWithPendingOrders(remoteOrders, existingOrders) {
+    const merged = remoteOrders.map(order => this.normalizeRemoteSyncedOrder(order));
+    for (const rawOrder of existingOrders) {
+      const order = this.normalizeOrderCollectionsForIngress(rawOrder, 'mergeRemoteSnapshotWithPendingOrders.existingSQLite');
+      if (!this.isPendingSyncOrder(order)) continue;
+      const matchIndex = this.findOrderIndexByIdentity(merged, order);
+      if (matchIndex >= 0) {
+        merged[matchIndex] = this.mergeOrderRecords(order, merged[matchIndex]);
+        continue;
+      }
+      if (!this.getOrderStorageKey(order)) continue;
+      merged.push(order);
+    }
+    return this.compactOrderListByIdentity(merged, 'mergeRemoteSnapshotWithPendingOrders').list;
+  }
+
+  /**
+   * 串行执行订单 SQLite 写入任务，避免快照替换与增量 upsert 并发交错。
+   *
+   * @example
+   * await this.runInOrderSQLiteSaveQueue(async () => {
+   *   await this.dbManager.bulkUpdate(INDEXDB_STORE_NAME, orders)
+   * })
+   */
+  async runInOrderSQLiteSaveQueue(task) {
+    const queuedTask = this.orderSQLiteSaveQueue.then(task, task);
+    this.orderSQLiteSaveQueue = queuedTask.then(() => undefined, () => undefined);
+    return queuedTask;
+  }
+
+  /**
+   * 批量增量 upsert 订单到 SQLite，不清空表；用于 pubsub / HTTP 增量合并。
+   *
+   * @example
+   * await this.patchOrdersInSQLite(freshOrders)
+   */
+  async patchOrdersInSQLite(orders, source, mergeActions = {}) {
+    if (!this.dbManager || orders.length === 0) {
+      return;
+    }
+    const ordersSnapshot = (0, _lodashEs.cloneDeep)(orders).map(order => this.normalizeOrderCollectionsForIngress(order, `${source}.sqliteIngress`)).filter(order => this.getOrderStorageKey(order));
+    if (ordersSnapshot.length === 0) {
+      return;
+    }
+    const {
+      toWrite,
+      skipped
+    } = this.filterRedundantPatchOrders(source, ordersSnapshot, mergeActions);
+    if (toWrite.length === 0) {
+      return;
+    }
+    const compactedToWrite = this.compactOrderListByIdentity(toWrite, `${source}.sqlitePatch`).list;
+    if (compactedToWrite.length === 0) {
+      return;
+    }
     try {
-      await this.dbManager.clear(INDEXDB_STORE_NAME);
-      if (orderList.length === 0) return;
-      await this.dbManager.bulkAdd(INDEXDB_STORE_NAME, orderList);
+      await this.runInOrderSQLiteSaveQueue(async () => {
+        let writeMethod = 'none';
+        this.logInfo('patchOrdersInSQLite-开始', {
+          source,
+          count: compactedToWrite.length,
+          dedupedCount: skipped.length
+        });
+        if (typeof this.dbManager.bulkUpdate === 'function') {
+          writeMethod = 'bulkUpdate';
+          await this.dbManager.bulkUpdate(INDEXDB_STORE_NAME, compactedToWrite);
+        } else if (typeof this.dbManager.bulkAdd === 'function') {
+          writeMethod = 'bulkAdd';
+          await this.dbManager.bulkAdd(INDEXDB_STORE_NAME, compactedToWrite);
+        } else if (typeof this.dbManager.update === 'function') {
+          writeMethod = 'update';
+          for (const order of compactedToWrite) {
+            await this.dbManager.update(INDEXDB_STORE_NAME, order);
+          }
+        }
+        this.recordRecentSqliteWrite(source, compactedToWrite);
+        this.logInfo('patchOrdersInSQLite-完成', {
+          source,
+          count: compactedToWrite.length,
+          writeMethod,
+          dedupedCount: skipped.length
+        });
+      });
     } catch (error) {
-      // SQLite 异常，避免影响主流程
-      this.logError('保存订单到 SQLite 失败', {
+      this.logError('增量保存订单到 SQLite 失败', {
         error: error instanceof Error ? error.message : String(error),
-        orderList: orderList.length
+        orderCount: ordersSnapshot.length
       });
     }
   }
+
+  /**
+   * 单条 upsert 订单到 SQLite；用于 overwriteExistingOrder 等单条覆盖场景。
+   *
+   * @example
+   * await this.updateOrderInSQLite(freshOrder)
+   */
+  async updateOrderInSQLite(order, source) {
+    if (!this.dbManager || !this.getOrderStorageKey(order)) {
+      return;
+    }
+    const orderSnapshot = this.normalizeOrderCollectionsForIngress((0, _lodashEs.cloneDeep)(order), `${source}.sqliteIngress`);
+    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 this.compactOrderListByIdentity(orderList.map(order => this.normalizeRemoteSyncedOrder(order)), `${source}.snapshotNoDb`).list;
+    }
+    const remoteSnapshot = (0, _lodashEs.cloneDeep)(orderList).map(order => this.normalizeOrderCollectionsForIngress(order, `${source}.remoteIngress`));
+    let mergedSnapshot = this.compactOrderListByIdentity(remoteSnapshot.map(order => this.normalizeRemoteSyncedOrder(order)), `${source}.remoteSnapshot`).list;
+    try {
+      await this.runInOrderSQLiteSaveQueue(async () => {
+        const existingOrders = typeof this.dbManager.getAll === 'function' ? await this.dbManager.getAll(INDEXDB_STORE_NAME) : [];
+        const orderListSnapshot = this.mergeRemoteSnapshotWithPendingOrders(remoteSnapshot, existingOrders || []);
+        mergedSnapshot = this.compactOrderListByIdentity(orderListSnapshot, `${source}.sqliteSnapshot`).list;
+        this.logInfo('replaceOrdersSnapshotInSQLite-开始', {
+          source,
+          count: mergedSnapshot.length,
+          remoteCount: remoteSnapshot.length,
+          preservedPendingCount: mergedSnapshot.length - remoteSnapshot.length
+        });
+        await this.dbManager.clear(INDEXDB_STORE_NAME);
+        this.logInfo('replaceOrdersSnapshotInSQLite-clear完成', {
+          count: mergedSnapshot.length
+        });
+        if (mergedSnapshot.length === 0) {
+          return;
+        }
+        await this.dbManager.bulkAdd(INDEXDB_STORE_NAME, mergedSnapshot);
+        this.recordRecentSqliteWrite(source, mergedSnapshot);
+        this.logInfo('replaceOrdersSnapshotInSQLite-bulkAdd完成', {
+          source,
+          count: mergedSnapshot.length
+        });
+      });
+    } catch (error) {
+      this.logError('全量保存订单到 SQLite 失败', {
+        error: error instanceof Error ? error.message : String(error),
+        orderList: remoteSnapshot.length
+      });
+    }
+    return mergedSnapshot;
+  }
+
+  /**
+   * 清空订单模块的内存数据和本地 SQLite 订单表。
+   *
+   * @example
+   * await orderModule.clear()
+   */
   async clear() {
     this.store.list = [];
     this.store.map = new Map();
-    this.resourceIdIndex.clear();
     if (this.dbManager) {
-      await this.dbManager.clear(INDEXDB_STORE_NAME);
+      await this.runInOrderSQLiteSaveQueue(async () => {
+        await this.dbManager.clear(INDEXDB_STORE_NAME);
+      });
     }
     this.setStorageItem(ORDER_LAST_FULL_FETCH_AT_STORAGE_KEY, '');
-    this.core.effects.emit(_types.OrderHooks.onOrdersChanged, this.store.list);
+    this.emitOrdersChanged([], 'clear');
   }
 }
 exports.OrderModule = OrderModule;