@pisell/pisellos 2.2.121 → 2.2.123

package/lib/server/index.js

@@ -65,6 +65,10 @@ var Server = class {
     // ---- 订单 / 预约列表查询订阅者 ----
     this.orderQuerySubscribers = /* @__PURE__ */ new Map();
     this.bookingQuerySubscribers = /* @__PURE__ */ new Map();
+    this.bookingRemoteQuerySubscribers = /* @__PURE__ */ new Map();
+    this.bookingRemoteCache = /* @__PURE__ */ new Map();
+    this.BOOKING_REMOTE_CACHE_TTL_MS = 5 * 60 * 1e3;
+    this.BOOKING_REMOTE_CACHE_MAX_ENTRIES = 80;
     this.floorPlanQuerySubscribers = /* @__PURE__ */ new Map();
     // 模块注册表 - 定义所有可用的模块配置
     this.moduleRegistry = {
@@ -180,18 +184,32 @@ var Server = class {
       console.log("[Server] handleOrderList:", url, method, data, config);
       const queryPayload = data && typeof data === "object" ? { ...data } : {};
       const { callback, subscriberId } = config || {};
-      this.logInfo("handleOrderList: 开始处理订单列表请求", { data: queryPayload });
-      if (subscriberId && typeof callback === "function") {
-        this.orderQuerySubscribers.set(subscriberId, {
-          callback,
-          context: queryPayload
-        });
-        this.logInfo("handleOrderList: 已注册订阅者", {
+      const useLocal = this.shouldUseLocalOrderQuery(queryPayload);
+      this.logInfo("handleOrderList: 开始处理订单列表请求", {
+        data: queryPayload,
+        useLocal
+      });
+      if (useLocal) {
+        if (subscriberId && typeof callback === "function") {
+          this.orderQuerySubscribers.set(subscriberId, {
+            callback,
+            context: queryPayload
+          });
+          this.logInfo("handleOrderList: 已注册订阅者", {
+            subscriberId,
+            totalSubscribers: this.orderQuerySubscribers.size
+          });
+        }
+        return this.computeOrderQueryResult(queryPayload);
+      }
+      if (subscriberId) {
+        this.orderQuerySubscribers.delete(subscriberId);
+        this.logInfo("handleOrderList: 已清理订阅者（走远端）", {
           subscriberId,
-          totalSubscribers: this.orderQuerySubscribers.size
+          remaining: this.orderQuerySubscribers.size
         });
       }
-      return this.computeOrderQueryResult(queryPayload);
+      return this.fetchOrderListFromAPI(queryPayload);
     };
     /**
      * 取消订单列表查询订阅（HTTP 路由入口）
@@ -215,12 +233,15 @@ var Server = class {
       console.log("[Server] handleBookingList:", url, method, data, config);
       const queryPayload = data && typeof data === "object" ? { ...data } : {};
       const { callback, subscriberId } = config || {};
-      const isToday = this.isBookingQueryForToday(queryPayload);
+      const useLocal = this.shouldUseLocalBookingQuery(queryPayload);
       this.logInfo("handleBookingList: 开始处理预约列表请求", {
         data: queryPayload,
-        isToday
+        useLocal
       });
-      if (isToday) {
+      if (useLocal) {
+        if (subscriberId) {
+          this.bookingRemoteQuerySubscribers.delete(subscriberId);
+        }
         if (subscriberId && typeof callback === "function") {
           this.bookingQuerySubscribers.set(subscriberId, {
             callback,
@@ -235,6 +256,26 @@ var Server = class {
       } else {
         if (subscriberId) {
           this.bookingQuerySubscribers.delete(subscriberId);
+        }
+        if (subscriberId && typeof callback === "function") {
+          const withFields = this.resolveBookingSalesWith(queryPayload);
+          const requestPayload = this.normalizeBookingRemoteQueryPayload(
+            queryPayload,
+            withFields
+          );
+          const cacheKey = this.buildBookingRemoteCacheKey(requestPayload);
+          this.bookingRemoteQuerySubscribers.set(subscriberId, {
+            callback,
+            context: queryPayload,
+            cacheKey
+          });
+          this.logInfo("handleBookingList: 已注册订阅者（非今天）", {
+            subscriberId,
+            cacheKey,
+            totalSubscribers: this.bookingRemoteQuerySubscribers.size
+          });
+        }
+        if (subscriberId) {
           this.logInfo("handleBookingList: 已清理订阅者（非今天）", {
             subscriberId,
             remaining: this.bookingQuerySubscribers.size
@@ -301,9 +342,11 @@ var Server = class {
       const { subscriberId } = data || {};
       if (subscriberId) {
         this.bookingQuerySubscribers.delete(subscriberId);
+        this.bookingRemoteQuerySubscribers.delete(subscriberId);
         this.logInfo("handleUnsubscribeBookingQuery: 已移除订阅者", {
           subscriberId,
-          remaining: this.bookingQuerySubscribers.size
+          remainingLocal: this.bookingQuerySubscribers.size,
+          remainingRemote: this.bookingRemoteQuerySubscribers.size
         });
       }
       return { code: 200, message: "ok", status: true };
@@ -634,6 +677,7 @@ var Server = class {
     this.core.effects.on(import_types3.OrderHooks.onOrdersChanged, () => {
       this.recomputeAndNotifyOrderQuery();
       this.recomputeAndNotifyBookingQuery();
+      this.syncBookingRemoteCacheFromOrderChanges();
     });
     const duration = Date.now() - startTime;
     this.logInfo("Server 初始化完成", {
@@ -927,23 +971,307 @@ var Server = class {
     }
   }
   /**
-   * 判断预约查询的 sales_time_between 起始日期是否为今天
+   * 从查询值中提取 YYYY-MM-DD 日期串。
+   *
+   * @example
+   * this.extractQueryDate('2026-04-15 09:58:00') // => '2026-04-15'
+   */
+  extractQueryDate(raw) {
+    if (raw == null)
+      return null;
+    const date = (0, import_dayjs.default)(raw);
+    if (date.isValid()) {
+      return date.format("YYYY-MM-DD");
+    }
+    const text = String(raw).trim();
+    if (!text)
+      return null;
+    return text.split("T")[0].split(" ")[0] || null;
+  }
+  /**
+   * 判断时间范围是否「开始和结束都不是今天」。
+   *
+   * @example
+   * this.isRangeBothNotToday('2026-04-13', '2026-04-14') // => true
+   */
+  isRangeBothNotToday(startRaw, endRaw) {
+    const startDate = this.extractQueryDate(startRaw);
+    const endDate = this.extractQueryDate(endRaw);
+    if (!startDate || !endDate)
+      return false;
+    const today = (0, import_dayjs.default)().format("YYYY-MM-DD");
+    return startDate !== today && endDate !== today;
+  }
+  /**
+   * 订单查询是否走本地：
+   * - 当 start_time 与 end_time 都不是今天时，走远端；
+   * - 其余情况走本地。
+   */
+  shouldUseLocalOrderQuery(data) {
+    return !this.isRangeBothNotToday(data == null ? void 0 : data.start_time, data == null ? void 0 : data.end_time);
+  }
+  /**
+   * 预约查询是否走本地：
+   * - 当 sales_time_between 的开始和结束都不是今天时，走远端；
+   * - 其余情况走本地。
    */
-  isBookingQueryForToday(data) {
+  shouldUseLocalBookingQuery(data) {
     const range = data == null ? void 0 : data.sales_time_between;
-    if (!Array.isArray(range) || range.length < 1)
+    if (!Array.isArray(range) || range.length < 2)
       return true;
-    const startDateStr = String(range[0]).split("T")[0].split(" ")[0];
-    const todayStr = (0, import_dayjs.default)().format("YYYY-MM-DD");
-    return startDateStr === todayStr;
+    return !this.isRangeBothNotToday(range[0], range[1]);
   }
   /**
-   * 非今天的预约查询：通过真实 API 获取数据，再做 flattenOrdersToBookings 拆分
+   * 日历 SSE 精简 with：只拉日历渲染必需的关联字段
    */
-  async fetchBookingListFromAPI(data) {
+  resolveBookingSalesWith(_queryPayload) {
+    return [
+      "bookings:booking_id,start_date,start_time,end_date,end_time,holder,metadata,parent_id,item_type",
+      "customer:id,display_name,phone",
+      "products"
+    ];
+  }
+  /**
+   * 日历 SSE 精简 select：渲染 + filterBookingsFromOrders 所需的主表字段
+   * business_code / payment_status 不直接用于渲染，但 matchOrder 过滤依赖
+   */
+  resolveBookingSalesSelect() {
+    return "status,payment_status,business_code,phone,customer_name,schedule_date,created_at,metadata";
+  }
+  normalizeBookingRemoteQueryPayload(data, withFields) {
+    return {
+      ...data,
+      form_record_ids: void 0,
+      enable_remote_memory_cache: void 0,
+      with: withFields,
+      select: this.resolveBookingSalesSelect(),
+      chunk_size: 50
+    };
+  }
+  /**
+   * 远端预约查询内存缓存开关：默认 false，仅显式 true 才启用。
+   */
+  isBookingRemoteMemoryCacheEnabled(queryPayload) {
+    return (queryPayload == null ? void 0 : queryPayload.enable_remote_memory_cache) === true;
+  }
+  stableSerialize(value) {
+    if (value === null || value === void 0)
+      return "null";
+    if (Array.isArray(value)) {
+      return `[${value.map((item) => this.stableSerialize(item)).join(",")}]`;
+    }
+    if (typeof value === "object") {
+      const obj = value;
+      const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+      return `{${keys.map((k) => `${JSON.stringify(k)}:${this.stableSerialize(obj[k])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+  }
+  buildBookingRemoteCacheKey(payload) {
+    return this.stableSerialize(payload);
+  }
+  parseBookingSalesRangeMeta(payload) {
+    const range = payload == null ? void 0 : payload.sales_time_between;
+    if (!Array.isArray(range) || range.length < 2)
+      return null;
+    const startAtMs = (0, import_dayjs.default)(range[0]).valueOf();
+    const endAtMs = (0, import_dayjs.default)(range[1]).valueOf();
+    if (!Number.isFinite(startAtMs) || !Number.isFinite(endAtMs))
+      return null;
+    if (endAtMs <= startAtMs)
+      return null;
+    return { startAtMs, endAtMs };
+  }
+  readBookingRemoteCache(cacheKey) {
+    const entry = this.bookingRemoteCache.get(cacheKey);
+    if (!entry)
+      return null;
+    if (entry.stale) {
+      this.bookingRemoteCache.delete(cacheKey);
+      return null;
+    }
+    const now = Date.now();
+    if (now - entry.updatedAt > this.BOOKING_REMOTE_CACHE_TTL_MS) {
+      this.bookingRemoteCache.delete(cacheKey);
+      return null;
+    }
+    return entry;
+  }
+  writeBookingRemoteCache(entry) {
+    this.bookingRemoteCache.set(entry.key, entry);
+    if (this.bookingRemoteCache.size <= this.BOOKING_REMOTE_CACHE_MAX_ENTRIES) {
+      return;
+    }
+    let oldestKey = null;
+    let oldestTime = Number.POSITIVE_INFINITY;
+    for (const [key, cache] of this.bookingRemoteCache.entries()) {
+      if (cache.updatedAt < oldestTime) {
+        oldestTime = cache.updatedAt;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey)
+      this.bookingRemoteCache.delete(oldestKey);
+  }
+  toOrderIdKey(order) {
+    if (!order || typeof order !== "object")
+      return null;
+    const raw = order.order_id;
+    if (raw === void 0 || raw === null || raw === "")
+      return null;
+    return String(raw);
+  }
+  markBookingRemoteCacheAllStale(reason) {
+    if (this.bookingRemoteCache.size === 0)
+      return;
+    for (const entry of this.bookingRemoteCache.values()) {
+      entry.stale = true;
+    }
+    this.logWarning("bookingRemoteCache: 全量标记失效", {
+      reason,
+      cacheSize: this.bookingRemoteCache.size
+    });
+  }
+  buildBookingResponse(bookingResult, extra) {
+    return {
+      code: 200,
+      data: {
+        ...extra ?? {},
+        list: bookingResult.list || [],
+        count: bookingResult.count || 0,
+        size: bookingResult.size || 0,
+        skip: bookingResult.skip || 0
+      },
+      message: "",
+      status: true
+    };
+  }
+  notifyBookingRemoteSubscribersByCacheKey(cacheKey, entry, reason) {
+    if (this.bookingRemoteQuerySubscribers.size === 0)
+      return;
+    for (const [subscriberId, subscriber] of this.bookingRemoteQuerySubscribers.entries()) {
+      if (subscriber.cacheKey !== cacheKey)
+        continue;
+      try {
+        const callbackStartAt = Date.now();
+        subscriber.callback(
+          this.buildBookingResponse(entry.bookingResult, {
+            cache_hit: true,
+            from_cache_sync: true,
+            sync_reason: reason
+          })
+        );
+        const callbackEndAt = Date.now();
+        this.logInfo("notifyBookingRemoteSubscribersByCacheKey: 已推送", {
+          subscriberId,
+          cacheKey,
+          reason,
+          callbackDurationMs: callbackEndAt - callbackStartAt
+        });
+      } catch (error) {
+        const errMsg = error instanceof Error ? error.message : String(error);
+        this.logError("notifyBookingRemoteSubscribersByCacheKey: 推送失败", {
+          subscriberId,
+          cacheKey,
+          reason,
+          error: errMsg
+        });
+      }
+    }
+  }
+  syncBookingRemoteCacheFromOrderChanges() {
     var _a, _b;
+    if (this.bookingRemoteCache.size === 0)
+      return;
+    const syncStartAt = Date.now();
+    const latestOrders = ((_b = (_a = this.order) == null ? void 0 : _a.getOrders) == null ? void 0 : _b.call(_a)) ?? [];
+    if (!Array.isArray(latestOrders) || latestOrders.length === 0) {
+      this.markBookingRemoteCacheAllStale("orderStoreEmptyAfterChange");
+      return;
+    }
+    let syncedEntryCount = 0;
+    for (const [cacheKey, entry] of this.bookingRemoteCache.entries()) {
+      if (entry.stale) {
+        this.bookingRemoteCache.delete(cacheKey);
+        continue;
+      }
+      try {
+        const queryPayload = entry.queryPayload;
+        const orderMap = /* @__PURE__ */ new Map();
+        for (const order of entry.rawOrders) {
+          const key = this.toOrderIdKey(order);
+          if (key)
+            orderMap.set(key, order);
+        }
+        let changed = false;
+        for (const latest of latestOrders) {
+          const key = this.toOrderIdKey(latest);
+          if (!key)
+            continue;
+          if (orderMap.has(key)) {
+            orderMap.set(key, latest);
+            changed = true;
+            continue;
+          }
+          orderMap.set(key, latest);
+          changed = true;
+        }
+        if (!changed)
+          continue;
+        const mergedOrders = [...orderMap.values()];
+        const filterStartAt = Date.now();
+        const bookingResult = (0, import_filterBookings.sortBookings)(
+          (0, import_filterBookings.filterBookingsFromOrders)(mergedOrders, queryPayload),
+          queryPayload
+        );
+        const filterEndAt = Date.now();
+        const nextEntry = {
+          ...entry,
+          rawOrders: mergedOrders,
+          bookingResult,
+          updatedAt: Date.now(),
+          stale: false
+        };
+        this.writeBookingRemoteCache(nextEntry);
+        this.notifyBookingRemoteSubscribersByCacheKey(
+          cacheKey,
+          nextEntry,
+          "orders_changed"
+        );
+        syncedEntryCount += 1;
+        this.logInfo("bookingRemoteCache: 单条缓存同步完成", {
+          cacheKey,
+          mergedOrderCount: mergedOrders.length,
+          filteredBookingCount: bookingResult.count,
+          filterDurationMs: filterEndAt - filterStartAt
+        });
+      } catch (error) {
+        const errMsg = error instanceof Error ? error.message : String(error);
+        this.logWarning("bookingRemoteCache: 同步失败并标记失效", {
+          cacheKey,
+          error: errMsg
+        });
+        const current = this.bookingRemoteCache.get(cacheKey);
+        if (current)
+          current.stale = true;
+      }
+    }
+    const syncEndAt = Date.now();
+    if (syncedEntryCount > 0) {
+      this.logInfo("bookingRemoteCache: 已同步 Ably 变更", {
+        syncedEntryCount,
+        cacheSize: this.bookingRemoteCache.size,
+        totalSyncDurationMs: syncEndAt - syncStartAt
+      });
+    }
+  }
+  /**
+   * 非本地窗口的订单查询：走真实 API。
+   */
+  async fetchOrderListFromAPI(data) {
+    var _a;
     if (!((_a = this.app) == null ? void 0 : _a.request)) {
-      this.logError("fetchBookingListFromAPI: app.request 不可用");
+      this.logError("fetchOrderListFromAPI: app.request 不可用");
       return {
         code: 500,
         message: "app.request 不可用",
@@ -952,24 +1280,118 @@ var Server = class {
       };
     }
     try {
-      const response = await this.app.request.get("/shop/order/sales", { ...data, form_record_ids: void 0, with: ["all"] }, {
+      const response = await this.app.request.post("/shop/order/v2/list", data, {
         isShopApi: true
       });
-      const rawList = ((_b = response == null ? void 0 : response.data) == null ? void 0 : _b.list) ?? (response == null ? void 0 : response.list) ?? [];
-      const list = (0, import_filterBookings.filterBookingsFromOrders)(rawList, data);
-      this.logInfo("fetchBookingListFromAPI: API 返回并拆分完成", {
-        rawCount: rawList.length,
-        flattenedCount: list.count
-      });
+      const payload = (response == null ? void 0 : response.data) ?? response;
+      const list = Array.isArray(payload == null ? void 0 : payload.list) ? payload.list : [];
+      const count = typeof (payload == null ? void 0 : payload.count) === "number" ? payload.count : list.length;
       return {
         code: 200,
-        data: { ...response.data, list: (list == null ? void 0 : list.list) || [] },
+        data: { ...payload, list, count },
         message: "",
         status: true
       };
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
-      this.logError("fetchBookingListFromAPI: 请求失败", { error: errorMessage });
+      this.logError("fetchOrderListFromAPI: 请求失败", { error: errorMessage });
+      return {
+        code: 500,
+        message: errorMessage,
+        data: { list: [], count: 0 },
+        status: false
+      };
+    }
+  }
+  /**
+   * 非今天的预约查询：通过 SSE 流式拉取订单，再做本地 booking 筛选展开
+   */
+  async fetchBookingListFromAPI(data) {
+    var _a;
+    if (!this.order) {
+      this.logError("fetchBookingListFromAPI: Order 模块不可用");
+      return {
+        code: 500,
+        message: "Order 模块不可用",
+        data: { list: [], count: 0 },
+        status: false
+      };
+    }
+    try {
+      const memoryCacheEnabled = this.isBookingRemoteMemoryCacheEnabled(data);
+      const withFields = this.resolveBookingSalesWith(data);
+      const requestPayload = this.normalizeBookingRemoteQueryPayload(
+        data,
+        withFields
+      );
+      const cacheKey = this.buildBookingRemoteCacheKey(requestPayload);
+      if (memoryCacheEnabled) {
+        const cached = this.readBookingRemoteCache(cacheKey);
+        if (cached) {
+          this.logInfo("fetchBookingListFromAPI: 命中内存缓存", {
+            cacheKey,
+            listCount: cached.bookingResult.count,
+            withFields: cached.withFields
+          });
+          return this.buildBookingResponse(cached.bookingResult, {
+            cache_hit: true
+          });
+        }
+      }
+      const rawList = await this.order.fetchOrdersBySSE(requestPayload);
+      const bookingResult = (0, import_filterBookings.sortBookings)(
+        (0, import_filterBookings.filterBookingsFromOrders)(rawList, data),
+        data
+      );
+      if (typeof globalThis !== "undefined") {
+        globalThis.__SSE_BOOKING_DEBUG__ = {
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          sseRequestPayload: requestPayload,
+          calendarFilters: data,
+          rawOrderCount: rawList.length,
+          rawOrderSample: rawList.slice(0, 2).map((o) => {
+            var _a2, _b, _c;
+            return {
+              order_id: o == null ? void 0 : o.order_id,
+              business_code: o == null ? void 0 : o.business_code,
+              status: o == null ? void 0 : o.status,
+              payment_status: o == null ? void 0 : o.payment_status,
+              bookingsCount: (_a2 = o == null ? void 0 : o.bookings) == null ? void 0 : _a2.length,
+              firstBooking: ((_b = o == null ? void 0 : o.bookings) == null ? void 0 : _b[0]) ? {
+                start_date: o.bookings[0].start_date,
+                start_time: o.bookings[0].start_time,
+                parent_id: o.bookings[0].parent_id,
+                item_type: o.bookings[0].item_type,
+                resourcesCount: (_c = o.bookings[0].resources) == null ? void 0 : _c.length
+              } : null
+            };
+          }),
+          filteredBookingCount: bookingResult.count,
+          filteredListLength: (_a = bookingResult.list) == null ? void 0 : _a.length
+        };
+      }
+      if (memoryCacheEnabled) {
+        this.writeBookingRemoteCache({
+          key: cacheKey,
+          queryPayload: data,
+          withFields,
+          rawOrders: Array.isArray(rawList) ? rawList : [],
+          bookingResult,
+          updatedAt: Date.now(),
+          stale: false,
+          rangeMeta: this.parseBookingSalesRangeMeta(requestPayload)
+        });
+      }
+      this.logInfo("fetchBookingListFromAPI: SSE 返回并拆分完成", {
+        rawCount: rawList.length,
+        flattenedCount: bookingResult.count,
+        cacheKey,
+        withFields
+      });
+      return this.buildBookingResponse(bookingResult);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logError("fetchBookingListFromAPI: SSE 请求失败", { error: errorMessage });
       return {
         code: 500,
         message: errorMessage,
@@ -1266,14 +1688,25 @@ var Server = class {
   async recomputeAndNotifyOrderQuery() {
     if (this.orderQuerySubscribers.size === 0)
       return;
+    const notifyStartAt = Date.now();
     this.logInfo("recomputeAndNotifyOrderQuery: 开始推送", {
-      subscriberCount: this.orderQuerySubscribers.size
+      subscriberCount: this.orderQuerySubscribers.size,
+      notifyStartAt: new Date(notifyStartAt).toISOString()
     });
     for (const [subscriberId, subscriber] of this.orderQuerySubscribers.entries()) {
       try {
+        const computeStartAt = Date.now();
         const result = await this.computeOrderQueryResult(subscriber.context);
+        const computeEndAt = Date.now();
+        const callbackStartAt = Date.now();
         subscriber.callback(result);
-        this.logInfo("recomputeAndNotifyOrderQuery: 已推送", { subscriberId });
+        const callbackEndAt = Date.now();
+        this.logInfo("recomputeAndNotifyOrderQuery: 已推送", {
+          subscriberId,
+          computeDurationMs: computeEndAt - computeStartAt,
+          callbackDurationMs: callbackEndAt - callbackStartAt,
+          totalDurationMs: callbackEndAt - computeStartAt
+        });
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         this.logError("recomputeAndNotifyOrderQuery: 推送失败", {
@@ -1282,6 +1715,11 @@ var Server = class {
         });
       }
     }
+    const notifyEndAt = Date.now();
+    this.logInfo("recomputeAndNotifyOrderQuery: 推送完成", {
+      subscriberCount: this.orderQuerySubscribers.size,
+      totalNotifyDurationMs: notifyEndAt - notifyStartAt
+    });
   }
   /**
    * 预约数据变更后，遍历订阅者重新计算并通过 callback 推送

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

@@ -13,7 +13,8 @@ export declare class OrderModule extends BaseModule implements Module {
     private orderDataSource;
     private pendingSyncMessages;
     private syncTimer?;
-    private readonly ORDER_SYNC_DEBOUNCE_MS;
+    private isProcessingSyncBatch;
+    private isIdlePhase;
     private resourceIdIndex;
     private logger;
     private storage;
@@ -31,6 +32,7 @@ export declare class OrderModule extends BaseModule implements Module {
      * @param metadata 日志元数据
      */
     private logError;
+    private getOrderSyncThrottleMs;
     preload(): Promise<void>;
     getOrders(): OrderData[];
     getOrderById(id: OrderId): OrderData | undefined;
@@ -38,6 +40,10 @@ export declare class OrderModule extends BaseModule implements Module {
     getOrderByOrderId(orderId: OrderId): OrderData | undefined;
     loadOrdersByServer(): Promise<OrderData[]>;
     getOrdersByResourceId(resourceId: string | number): OrderData[];
+    /**
+     * 通过 SSE 按自定义 query 拉取订单（支持 select/with 精简字段）
+     */
+    fetchOrdersBySSE(query?: Record<string, any>): Promise<OrderData[]>;
     getRoutes(): RouteDefinition[];
     destroy(): void;
     private syncOrdersMap;
@@ -48,15 +54,31 @@ export declare class OrderModule extends BaseModule implements Module {
      */
     private initOrderDataSource;
     /**
-     * 初始化 pubsub 订阅，监听订单变更
+     * 初始化 pubsub 订阅，监听订单变更（纯订阅，不拉数据；全量 SSE 由 loadOrdersByServer 负责）
      */
     private setupOrderSync;
     /**
-     * 处理防抖后的同步消息批次
+     * 调度订单同步节流窗口（leading-edge throttle）：
+     * - 空闲状态下收到的第一条消息立即触发批处理，无需等待；
+     * - 首条处理后进入冷却窗口，窗口期间的后续消息聚合，窗口结束后批量处理；
+     * - 若当前批处理执行中，则由批处理结束后决定是否开启下一轮窗口。
+     */
+    private scheduleOrderSyncThrottle;
+    /**
+     * 执行一次节流批处理并在需要时续约下一轮窗口。
+     * 批处理完成且无后续消息时恢复空闲状态，下一条消息将立即触发。
+     */
+    private flushOrderSyncMessagesByThrottle;
+    /**
+     * 处理节流窗口内聚合后的同步消息批次
      *
      * 后端统一发送 change 消息，不再区分新增/编辑/删除。
      * - 单条（id/order_id）：若携带 body/data 则直接 upsert 到本地
      * - 批量（ids）：通过 HTTP 按 ids 增量拉取，再 merge 到本地
+     *
+     * @example
+     * // pending 队列中存在 8 条消息时，仅处理一次批次并统一 merge
+     * await this.processOrderSyncMessages()
      */
     private processOrderSyncMessages;
     /**