@pisell/pisellos 0.0.568 → 0.0.569

package/lib/server/index.js

@@ -11,13 +11,17 @@ var _menu = require("./modules/menu");
 var _quotation = require("./modules/quotation");
 var _schedule = require("./modules/schedule");
 var _resource = require("./modules/resource");
+var _floorPlan = require("./modules/floor-plan");
+var _types = require("./modules/floor-plan/types");
+var _payment = require("./modules/payment");
 var _schedule2 = require("./utils/schedule");
-var _types = require("./modules/products/types");
+var _types2 = require("./modules/products/types");
 var _product = require("./utils/product");
 var _order = require("./modules/order");
-var _types2 = require("./modules/order/types");
+var _types3 = require("./modules/order/types");
 var _filterOrders = require("./modules/order/utils/filterOrders");
 var _filterBookings = require("./modules/order/utils/filterBookings");
+var _smallTicket = require("./utils/small-ticket");
 var _modules = require("./modules");
 Object.keys(_modules).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;
@@ -39,6 +43,14 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
 
 /** 预约列表查询订阅者 */
 
+/** 非当天（远端）预约查询订阅者 */
+
+/** Server 运行时诊断快照，用于排查订阅者是否持续增长。 */
+
+/** 平面图 GET 查询订阅者（列表 / id 详情 / code 详情） */
+
+const PRODUCT_TITLE_SNAPSHOT_KEYS = ['en', 'ja', 'pt', 'auto', 'zh-CN', 'zh-HK', 'kitchen', 'original'];
+
 /**
  * Server 类
  * 用于注册和管理服务端模块
@@ -55,6 +67,15 @@ class Server {
   schedule;
   resource;
   order;
+  floor_plan;
+  payment;
+  paymentRouteModule;
+  paymentRouteModuleInFlight;
+  quotationAvailableCache = new Map();
+  quotationAvailableInFlight = new Map();
+
+  /** GET 前缀路由（最长前缀优先匹配） */
+  prefixRouterGet = [];
 
   // 路由注册表
   router = {
@@ -66,10 +87,23 @@ class Server {
 
   // ---- 商品查询订阅者 ----
   productQuerySubscribers = new Map();
+  /** subscriberId → 智能定价变价时间点定时器句柄（与 subscriber 分离存储，便于 clear） */
+  productQueryScheduleTimers = new Map();
+  /** 餐牌筛选为空时才触发的菜单/日程缓存自愈，避免每次商品查询都请求远端。 */
+  menuScheduleRefreshInFlight = null;
+  lastMenuScheduleRefreshAt = 0;
+  MENU_SCHEDULE_REFRESH_COOLDOWN_MS = 30 * 1000;
 
   // ---- 订单 / 预约列表查询订阅者 ----
   orderQuerySubscribers = new Map();
   bookingQuerySubscribers = new Map();
+  bookingRemoteQuerySubscribers = new Map();
+  bookingRemoteCache = new Map();
+  BOOKING_REMOTE_CACHE_TTL_MS = 5 * 60 * 1000;
+  BOOKING_REMOTE_CACHE_MAX_ENTRIES = 80;
+  salesSearchSubscribers = new Map();
+  deviceTaskActionsRegistered = false;
+  floorPlanQuerySubscribers = new Map();
 
   // 模块注册表 - 定义所有可用的模块配置
   moduleRegistry = {
@@ -121,6 +155,15 @@ class Server {
         list: []
       }
     },
+    payment: {
+      name: 'payment',
+      moduleClass: _payment.PaymentServerModule,
+      moduleName: 'server_payment',
+      version: '1.0.0',
+      defaultStore: {
+        payMethods: []
+      }
+    },
     resource: {
       name: 'resource',
       moduleClass: _resource.ResourceModule,
@@ -131,6 +174,17 @@ class Server {
         map: new Map(),
         bookings: []
       }
+    },
+    floor_plan: {
+      name: 'floor_plan',
+      moduleClass: _floorPlan.FloorPlanModule,
+      moduleName: 'server_floor_plan',
+      version: '1.0.0',
+      defaultStore: {
+        list: [],
+        map: new Map(),
+        codeMap: new Map()
+      }
     }
   };
   constructor(core) {
@@ -144,6 +198,28 @@ class Server {
     });
   }
 
+  /**
+   * 获取 Server 内部订阅者和缓存数量快照。
+   *
+   * @example
+   * const snapshot = pisellos.server?.getDiagnosticsSnapshot?.();
+   */
+  getDiagnosticsSnapshot() {
+    return {
+      subscribers: {
+        productQuerySubscribers: this.productQuerySubscribers.size,
+        orderQuerySubscribers: this.orderQuerySubscribers.size,
+        bookingQuerySubscribers: this.bookingQuerySubscribers.size,
+        bookingRemoteQuerySubscribers: this.bookingRemoteQuerySubscribers.size,
+        salesSearchSubscribers: this.salesSearchSubscribers.size,
+        floorPlanQuerySubscribers: this.floorPlanQuerySubscribers.size
+      },
+      caches: {
+        bookingRemoteCache: this.bookingRemoteCache.size
+      }
+    };
+  }
+
   /**
    * 注册路由
    * @param routes 路由定义数组
@@ -180,6 +256,29 @@ class Server {
     });
   }
 
+  /**
+   * 注册前缀路由（仅 GET）。匹配规则：path === prefix 或 path 以 prefix + '/' 开头；最长前缀优先。
+   */
+  registerPrefixRoutes(routes) {
+    for (const r of routes) {
+      if (r.method !== 'get') {
+        this.logWarning('registerPrefixRoutes: 当前仅支持 GET', {
+          method: r.method,
+          prefix: r.prefix
+        });
+        continue;
+      }
+      this.prefixRouterGet.push({
+        prefix: r.prefix,
+        handler: r.handler
+      });
+    }
+    this.prefixRouterGet.sort((a, b) => b.prefix.length - a.prefix.length);
+    this.logInfo('前缀 GET 路由已更新', {
+      count: this.prefixRouterGet.length
+    });
+  }
+
   /**
    * 注册单个模块并自动注册其路由
    * @param module 模块实例
@@ -386,6 +485,7 @@ class Server {
 
     // 注册 Server 层的业务路由
     this.registerServerRoutes();
+    this.registerDeviceTaskActions();
 
     // 注册模块
     const registeredModules = await this.registerModules(moduleConfigs);
@@ -398,18 +498,26 @@ class Server {
         autoPreload
       });
     }
+    await this.setupProductsQuotationPriceBridge();
 
     // 监听 ProductsModule 同步完成事件，重新计算并推送查询结果
-    this.core.effects.on(_types.ProductsHooks.onProductsSyncCompleted, payload => {
+    this.core.effects.on(_types2.ProductsHooks.onProductsSyncCompleted, payload => {
       this.recomputeAndNotifyProductQuery({
         changedIds: payload?.changedIds
       });
     });
 
+    // 平面图：本地列表任意变更（预加载、pubsub 同步）时，向 GET 订阅者推送最新列表/详情
+    this.core.effects.on(_types.FloorPlanHooks.onFloorPlansChanged, () => {
+      void this.recomputeAndNotifyFloorPlanQuery();
+    });
+
     // 订单 / 预约本地数据变更时，向订阅者推送最新列表
-    this.core.effects.on(_types2.OrderHooks.onOrdersChanged, () => {
+    this.core.effects.on(_types3.OrderHooks.onOrdersChanged, payload => {
       this.recomputeAndNotifyOrderQuery();
       this.recomputeAndNotifyBookingQuery();
+      this.syncBookingRemoteCacheFromOrderChanges();
+      this.notifySalesSearchSubscribers(payload);
     });
     const duration = Date.now() - startTime;
     this.logInfo('Server 初始化完成', {
@@ -418,6 +526,237 @@ class Server {
     });
     return registeredModules;
   }
+  registerDeviceTaskActions() {
+    if (this.deviceTaskActionsRegistered) return;
+    const deviceTask = this.getDeviceTaskPlugin();
+    if (!deviceTask?.registerAction) {
+      this.logWarning('registerDeviceTaskActions: deviceTask 插件不可用');
+      return;
+    }
+    const registeredActions = new Set(typeof deviceTask.getActions === 'function' ? (deviceTask.getActions() || []).map(action => action?.action).filter(Boolean) : []);
+    const register = definition => {
+      if (registeredActions.has(definition.action)) return;
+      deviceTask.registerAction?.(definition);
+      registeredActions.add(definition.action);
+    };
+    register({
+      action: 'sync_sales',
+      name: '同步订单',
+      validate: payload => payload?.backendPath && payload?.data ? null : '缺少 backendPath 或 data',
+      handler: ctx => this.handleSyncSalesTask(ctx)
+    });
+    this.deviceTaskActionsRegistered = true;
+    this.logInfo('DeviceTask actions 已注册', {
+      actions: ['sync_sales']
+    });
+  }
+  async handleSyncSalesTask(ctx) {
+    const payload = ctx.task?.payload || {};
+    const backendPath = payload.backendPath;
+    const data = payload.data;
+    const title = payload.title || 'sync_sales';
+    if (!backendPath || !data) {
+      return this.taskFail('INVALID_PAYLOAD', '缺少 backendPath 或 data');
+    }
+    if (!this.app?.request) {
+      this.logError(`${title}: sync_sales app.request 不可用`);
+      return this.taskTimeout('app.request 不可用');
+    }
+    try {
+      const syncResult = await this.runCheckoutSync({
+        backendPath,
+        data,
+        title,
+        externalSaleNumber: payload.external_sale_number,
+        deviceId: ctx.task?.device_id,
+        persistCheckoutDataWithResponse: false
+      });
+      if (syncResult.rejected) {
+        this.logError(`${title}: sync_sales 后端明确失败`, {
+          backendPath,
+          response: syncResult.errorResponse
+        });
+        return this.taskFail('BACKEND_REJECTED', syncResult.message || '后端明确拒绝 checkout', syncResult.errorResponse);
+      }
+      return this.taskOk({
+        order: syncResult.syncedOrder ?? null,
+        response: syncResult.normalizedResponse
+      });
+    } catch (error) {
+      const backendError = this.extractBackendErrorResponse(error);
+      if (backendError) {
+        const message = backendError?.message || '后端明确拒绝 checkout';
+        this.logError(`${title}: sync_sales 后端明确失败`, {
+          backendPath,
+          backendError
+        });
+        return this.taskFail('BACKEND_REJECTED', message, backendError);
+      }
+      const errorMessage = this.getUnknownErrorMessage(error);
+      this.logError(`${title}: sync_sales 请求未明确成功`, {
+        backendPath,
+        error: errorMessage,
+        error_detail: this.normalizeUnknownError(error)
+      });
+      return this.taskTimeout(errorMessage);
+    }
+  }
+  async runCheckoutSync(params) {
+    const {
+      backendPath,
+      title
+    } = params;
+    const normalizedData = await this.normalizeCheckoutSubmitData(params.data, title);
+    const checkoutData = await this.ensureCheckoutOrderNumbers(normalizedData, title);
+    const remoteCheckoutData = this.omitCheckoutSyncMode(checkoutData);
+    if (!this.app?.request?.post) {
+      throw new Error('app.request 不可用');
+    }
+    const response = await this.app.request.post(backendPath, remoteCheckoutData, {
+      isShopApi: true,
+      customToast: () => {}
+    });
+    if (this.isCheckoutResponseRejected(response)) {
+      return {
+        rejected: true,
+        message: response?.message || '后端明确拒绝 checkout',
+        errorResponse: response,
+        response,
+        normalizedResponse: this.normalizeCheckoutResponse(response),
+        checkoutData: remoteCheckoutData
+      };
+    }
+    const fresh = this.extractOrderDataFromCheckoutResponse(response);
+    const externalSaleNumber = this.getCheckoutExternalSaleNumber(remoteCheckoutData, {
+      external_sale_number: params.externalSaleNumber,
+      data: remoteCheckoutData
+    });
+    const syncedOrder = await this.persistSyncedCheckoutOrder({
+      backendPath,
+      checkoutData: remoteCheckoutData,
+      externalSaleNumber,
+      fresh,
+      title,
+      persistCheckoutDataWithResponse: params.persistCheckoutDataWithResponse === true
+    });
+    const printableSyncedOrder = syncedOrder ? this.buildSyncedOrderForPrint({
+      syncedOrder,
+      checkoutResponseOrder: fresh
+    }) : undefined;
+    if (printableSyncedOrder && this.shouldPrintSyncedOrder({
+      checkoutData: remoteCheckoutData,
+      syncedOrder: printableSyncedOrder
+    })) {
+      await this.dispatchPrintOtherReceiptTask({
+        checkoutData: remoteCheckoutData,
+        syncedOrder: printableSyncedOrder,
+        response,
+        deviceId: params.deviceId
+      });
+    }
+    return {
+      rejected: false,
+      response,
+      normalizedResponse: this.normalizeCheckoutResponse(response),
+      checkoutData: remoteCheckoutData,
+      syncedOrder,
+      fresh
+    };
+  }
+  omitCheckoutSyncMode(data) {
+    if (!data || typeof data !== 'object') return data;
+    const next = {
+      ...data
+    };
+    delete next.sync_mode;
+    delete next.syncMode;
+    return next;
+  }
+  async persistSyncedCheckoutOrder(params) {
+    const {
+      backendPath,
+      checkoutData,
+      externalSaleNumber,
+      fresh,
+      title,
+      persistCheckoutDataWithResponse
+    } = params;
+    const shouldMergeRemoteOrder = fresh ? this.isMergeableCheckoutOrder(fresh, externalSaleNumber) : false;
+    let syncedOrder;
+    if (this.order && fresh && (shouldMergeRemoteOrder || persistCheckoutDataWithResponse)) {
+      syncedOrder = persistCheckoutDataWithResponse ? {
+        ...checkoutData,
+        ...fresh,
+        external_sale_number: fresh.external_sale_number ?? externalSaleNumber,
+        need_sync: 0
+      } : {
+        ...fresh,
+        external_sale_number: fresh.external_sale_number ?? externalSaleNumber,
+        need_sync: 0
+      };
+      await this.order.upsertOrdersFromRemote([syncedOrder]);
+      this.logInfo(`${title}: sync_sales 完整订单已同步到本地`, {
+        order_id: fresh.order_id,
+        external_sale_number: syncedOrder.external_sale_number,
+        order_number: fresh.order_number,
+        mergedRemoteOrder: shouldMergeRemoteOrder,
+        persistedCheckoutDataWithResponse: persistCheckoutDataWithResponse
+      });
+    } else if (this.order && externalSaleNumber && typeof this.order.markOrderSyncedByExternalSaleNumber === 'function') {
+      const patch = this.buildCheckoutSyncSuccessPatch(fresh);
+      const result = await this.order.markOrderSyncedByExternalSaleNumber({
+        externalSaleNumber,
+        patch
+      });
+      syncedOrder = result?.order || {
+        ...checkoutData,
+        ...patch,
+        external_sale_number: externalSaleNumber,
+        need_sync: 0
+      };
+      this.logInfo(`${title}: sync_sales 已按 external_sale_number 标记本地订单`, {
+        order_id: syncedOrder?.order_id ?? null,
+        external_sale_number: externalSaleNumber,
+        hasRemoteOrder: !!fresh,
+        mergedRemoteOrder: false
+      });
+    } else {
+      this.logWarning(`${title}: sync_sales Order 模块未注册`, {
+        backendPath,
+        external_sale_number: externalSaleNumber,
+        order_id: fresh?.order_id
+      });
+    }
+    return syncedOrder;
+  }
+
+  /**
+   * 将普通层 QuotationModule 的报价单计算能力桥接到 Server Products 模块。
+   */
+  async setupProductsQuotationPriceBridge() {
+    if (!this.products) {
+      this.logInfo('setupProductsQuotationPriceBridge: Products 模块未注册');
+      return;
+    }
+    if (!this.schedule) {
+      this.logInfo('setupProductsQuotationPriceBridge: Schedule 模块未注册');
+      return;
+    }
+    try {
+      await this.schedule.loadAllSchedule();
+      this.products.clearPriceCache();
+      await this.products.setupQuotationPriceBridge({
+        scheduleModule: this.schedule,
+        channel: this.core.context?.channel
+      });
+      this.logInfo('Products 报价单价格桥接初始化完成');
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logError('Products 报价单价格桥接初始化失败', {
+        error: errorMessage
+      });
+    }
+  }
 
   /**
    * 获取 Products 模块实例
@@ -458,6 +797,7 @@ class Server {
     if (this.schedule) modules.push('schedule');
     if (this.resource) modules.push('resource');
     if (this.order) modules.push('order');
+    if (this.floor_plan) modules.push('floor_plan');
     return modules;
   }
 
@@ -490,6 +830,35 @@ class Server {
     }
   }
 
+  /**
+   * 后台静默刷新订单数据
+   * 重新拉取全量 SSE 接口，更新本地数据后触发 onOrdersSyncCompleted
+   * 不影响当前界面展示，适用于切回前台、定时刷新等场景
+   */
+  async refreshOrdersInBackground() {
+    if (!this.order) {
+      this.logWarning('refreshOrdersInBackground: Order 模块未注册');
+      return;
+    }
+    this.logInfo('refreshOrdersInBackground 开始');
+    const startTime = Date.now();
+    try {
+      await this.order.silentRefresh();
+      const duration = Date.now() - startTime;
+      this.logInfo('refreshOrdersInBackground 完成', {
+        duration: `${duration}ms`
+      });
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.error('[Server] refreshOrdersInBackground 失败:', error);
+      this.logError('refreshOrdersInBackground 失败', {
+        duration: `${duration}ms`,
+        error: errorMessage
+      });
+    }
+  }
+
   /**
    * 清空所有server模块的IndexedDB缓存
    * @returns Promise<void>
@@ -524,6 +893,10 @@ class Server {
       clearTasks.push(this.order.clear());
       moduleNames.push('Order');
     }
+    if (this.floor_plan) {
+      clearTasks.push(this.floor_plan.clear());
+      moduleNames.push('FloorPlan');
+    }
     if (clearTasks.length === 0) {
       console.warn('[Server] 没有找到已注册的模块，无需清空');
       this.logWarning('没有找到已注册的模块，无需清空 IndexedDB');
@@ -562,7 +935,25 @@ class Server {
    * @param path 路径
    */
   getRouteHandler(method, path) {
-    return this.router[method]?.[path];
+    const exact = this.router[method]?.[path];
+    if (exact) {
+      return exact;
+    }
+    // GET /shop/product/query/:productId（纯数字 id），与 POST /shop/product/query、unsubscribe 区分
+    if (method === 'get' && /^\/shop\/product\/query\/\d+$/.test(path)) {
+      return this.handleProductQueryById;
+    }
+    if (method === 'get' && this.prefixRouterGet.length > 0) {
+      for (const {
+        prefix,
+        handler
+      } of this.prefixRouterGet) {
+        if (path === prefix || path.startsWith(`${prefix}/`)) {
+          return handler;
+        }
+      }
+    }
+    return undefined;
   }
 
   /**
@@ -571,7 +962,7 @@ class Server {
    * @param path 路径
    */
   hasRoute(method, path) {
-    return !!this.router[method]?.[path];
+    return !!this.getRouteHandler(method, path);
   }
 
   /**
@@ -597,7 +988,10 @@ class Server {
       throw new Error(`Route not found: ${method.toUpperCase()} ${path}`);
     }
     try {
-      const result = await handler(params);
+      const result = await handler({
+        ...params,
+        path
+      });
       const duration = Date.now() - startTime;
       this.logInfo(`路由请求完成: ${method.toUpperCase()} ${path}`, {
         method: method.toUpperCase(),
@@ -664,6 +1058,22 @@ class Server {
       method: 'post',
       path: '/shop/order/v2/list/unsubscribe',
       handler: this.handleUnsubscribeOrderQuery.bind(this)
+    }, {
+      method: 'post',
+      path: '/shop/es/search/sales',
+      handler: this.handleSalesSearchModule.bind(this)
+    }, {
+      method: 'post',
+      path: '/shop/es/search/sales/unsubscribe',
+      handler: this.handleUnsubscribeSalesSearch.bind(this)
+    }, {
+      method: 'post',
+      path: '/shop/es/search',
+      handler: this.handleSalesSearchAggregate.bind(this)
+    }, {
+      method: 'post',
+      path: '/shop/es/search/unsubscribe',
+      handler: this.handleUnsubscribeSalesSearch.bind(this)
     }, {
       method: 'get',
       path: '/shop/schedule/booking',
@@ -676,14 +1086,145 @@ class Server {
       method: 'get',
       path: '/shop/form/resource/page',
       handler: this.handleResourceList.bind(this)
+    }, {
+      method: 'get',
+      path: '/update/localOrder',
+      handler: this.handleUpdateLocalOrder.bind(this)
+    }, {
+      method: 'get',
+      path: '/shop/pay/custom-payment/all',
+      handler: this.handlePaymentMethods.bind(this)
+    }, {
+      method: 'get',
+      path: '/shop/quotation/available',
+      handler: this.handleQuotationAvailable.bind(this)
+    }, {
+      method: 'get',
+      path: '/quotation/available',
+      handler: this.handleQuotationAvailable.bind(this)
+    }, {
+      method: 'post',
+      path: '/shop/order/sales/checkout',
+      handler: this.handleOrderSalesCheckout.bind(this)
+    }, {
+      method: 'post',
+      path: '/order/checkout',
+      handler: this.handleOrderCheckout.bind(this)
+    }, {
+      method: 'post',
+      path: '/shop/local/print-order',
+      handler: this.handleLocalPrintOrder.bind(this)
+    }, {
+      method: 'post',
+      path: '/shop/machinecode/batch',
+      handler: this.handleMachinecodeBatchMeta.bind(this)
+    }, {
+      method: 'post',
+      path: '/machinecode/batch',
+      handler: this.handleMachinecodeBatchMeta.bind(this)
+    }]);
+    this.registerPrefixRoutes([{
+      method: 'get',
+      prefix: '/shop/order/sales',
+      handler: this.handleOrderSalesDetail.bind(this)
+    }, {
+      method: 'get',
+      prefix: '/shop/schedule/floor-plan',
+      handler: this.handleFloorPlanGet.bind(this)
     }]);
   }
+  async getPaymentRouteModule() {
+    if (this.payment) return this.payment;
+    if (this.paymentRouteModule) return this.paymentRouteModule;
+    if (this.paymentRouteModuleInFlight) return this.paymentRouteModuleInFlight;
+    this.paymentRouteModuleInFlight = (async () => {
+      const module = new _payment.PaymentServerModule('server_payment_route', '1.0.0');
+      await module.initialize(this.core, {
+        store: {
+          payMethods: []
+        }
+      });
+      this.paymentRouteModule = module;
+      return module;
+    })().finally(() => {
+      this.paymentRouteModuleInFlight = undefined;
+    });
+    return this.paymentRouteModuleInFlight;
+  }
+  handlePaymentMethods = async ({
+    data,
+    config
+  }) => {
+    const payment = await this.getPaymentRouteModule();
+    const payMethods = await payment.getPayMethodListAsync({
+      shouldFilter: data?.filterPaymentMethods === true || config?.filterPaymentMethods === true
+    });
+    return {
+      code: 200,
+      status: true,
+      data: payMethods
+    };
+  };
+  handleQuotationAvailable = async ({
+    data
+  }) => {
+    const queryPayload = data && typeof data === 'object' ? {
+      ...data
+    } : {};
+    const cacheKey = this.stableSerialize(queryPayload);
+    if (this.quotationAvailableCache.has(cacheKey)) {
+      this.logInfo('handleQuotationAvailable: 命中运行时缓存', {
+        cacheKey
+      });
+      return this.quotationAvailableCache.get(cacheKey);
+    }
+    const inFlight = this.quotationAvailableInFlight.get(cacheKey);
+    if (inFlight) {
+      this.logInfo('handleQuotationAvailable: 复用进行中的请求', {
+        cacheKey
+      });
+      return inFlight;
+    }
+    const requestPromise = this.fetchQuotationAvailableFromAPI(queryPayload).then(response => {
+      if (this.isSuccessfulRemoteResponse(response)) {
+        this.quotationAvailableCache.set(cacheKey, response);
+      }
+      return response;
+    }).finally(() => {
+      this.quotationAvailableInFlight.delete(cacheKey);
+    });
+    this.quotationAvailableInFlight.set(cacheKey, requestPromise);
+    return requestPromise;
+  };
+  async fetchQuotationAvailableFromAPI(data) {
+    const requester = this.app?.request || this.core.getPlugin('request');
+    if (!requester?.get) {
+      this.logError('fetchQuotationAvailableFromAPI: request 不可用');
+      return {
+        code: 500,
+        message: 'request 不可用',
+        data: {
+          list: []
+        },
+        status: false
+      };
+    }
+    return requester.get('/shop/quotation/available', data);
+  }
+  isSuccessfulRemoteResponse(response) {
+    if (!response) return false;
+    if (response.status === false) return false;
+    if (typeof response.status === 'number' && response.status >= 400) return false;
+    if (response.code !== undefined && response.code !== 200 && response.code !== '200') return false;
+    return true;
+  }
 
   /**
    * 根据 subscriberId 移除商品查询订阅者
    */
   removeProductQuerySubscriber(subscriberId) {
     if (subscriberId) {
+      this.clearSubscriberScheduleTimers(subscriberId);
       this.productQuerySubscribers.delete(subscriberId);
       this.logInfo('removeProductQuerySubscriber: 已移除订阅者', {
         subscriberId,
@@ -692,6 +1233,157 @@ class Server {
     }
   }
 
+  /**
+   * 构建商品 query 响应 data 段，附带智能定价 schedule_time_points 元数据。
+   */
+  buildProductQueryResultPayload(list, count) {
+    return {
+      list,
+      count: count ?? list.length,
+      schedule_time_points: this.products?.getLastScheduleTimePoints?.() ?? []
+    };
+  }
+
+  /**
+   * 是否启用商品 query 订阅的 schedule 时间点定时重算。
+   * strategy_context.enable_schedule_reload === false 时关闭。
+   */
+  shouldScheduleProductQueryReload(strategy_context) {
+    return strategy_context?.enable_schedule_reload !== false;
+  }
+
+  /**
+   * 清除指定 subscriber 的全部 schedule 定时器，防止重复 query 或 unsubscribe 后泄漏。
+   */
+  clearSubscriberScheduleTimers(subscriberId) {
+    const timers = this.productQueryScheduleTimers.get(subscriberId);
+    if (timers?.length) {
+      timers.forEach(timerId => clearTimeout(timerId));
+    }
+    this.productQueryScheduleTimers.delete(subscriberId);
+    const subscriber = this.productQuerySubscribers.get(subscriberId);
+    if (subscriber) {
+      subscriber.scheduleTimerIds = [];
+    }
+  }
+
+  /**
+   * 从 productQueryScheduleTimers 移除已触发的 timer 引用。
+   */
+  removeScheduleTimerRef(subscriberId, timerId) {
+    const timers = this.productQueryScheduleTimers.get(subscriberId);
+    if (!timers?.length) return;
+    const next = timers.filter(id => id !== timerId);
+    if (next.length === 0) {
+      this.productQueryScheduleTimers.delete(subscriberId);
+    } else {
+      this.productQueryScheduleTimers.set(subscriberId, next);
+    }
+    const subscriber = this.productQuerySubscribers.get(subscriberId);
+    if (subscriber) {
+      subscriber.scheduleTimerIds = next;
+    }
+  }
+
+  /**
+   * 计算 schedule 变价时间点到当前时刻的延迟（ms）。已过期返回 -1。
+   */
+  computeScheduleTimePointDelayMs(scheduleDate, timePoint) {
+    const parts = timePoint.split(':');
+    if (parts.length < 2) return -1;
+    const hours = parseInt(parts[0], 10);
+    const minutes = parseInt(parts[1], 10);
+    if (!Number.isFinite(hours) || !Number.isFinite(minutes)) return -1;
+    const target = (0, _dayjs.default)(scheduleDate).hour(hours).minute(minutes).second(4).millisecond(0);
+    const delayMs = target.diff((0, _dayjs.default)());
+    return delayMs >= 0 ? delayMs : -1;
+  }
+
+  /**
+   * 定时重算前刷新 subscriber schedule 上下文：使用执行瞬间时间，禁止沿用首次 query 的 schedule_datetime。
+   */
+  refreshSubscriberScheduleAtExecution(subscriber) {
+    const executedAt = (0, _dayjs.default)();
+    const bookingDate = subscriber.context.schedule_date || executedAt.format('YYYY-MM-DD');
+    subscriber.context.schedule_date = bookingDate;
+    subscriber.context.schedule_datetime = `${bookingDate} ${executedAt.format('HH:mm:ss')}`;
+  }
+
+  /**
+   * 为 subscriber 注册智能定价 scheduleTimePoints 定时重算。
+   * 必须先 clearSubscriberScheduleTimers，再调用本方法。
+   */
+  scheduleSubscriberTimePointReloads(subscriberId, timePoints) {
+    const subscriber = this.productQuerySubscribers.get(subscriberId);
+    if (!subscriber || !timePoints.length) return;
+    const scheduleDate = subscriber.context.schedule_date || (0, _dayjs.default)().format('YYYY-MM-DD');
+    const timerIds = [];
+    for (const timePoint of timePoints) {
+      const delayMs = this.computeScheduleTimePointDelayMs(scheduleDate, timePoint);
+      if (delayMs < 0) continue;
+      const timerId = setTimeout(() => {
+        void this.onScheduleTimePointTimerFire(subscriberId, timerId);
+      }, delayMs);
+      timerIds.push(timerId);
+    }
+    if (timerIds.length > 0) {
+      this.productQueryScheduleTimers.set(subscriberId, timerIds);
+      subscriber.scheduleTimerIds = timerIds;
+      this.logInfo('scheduleSubscriberTimePointReloads: 已注册定时器', {
+        subscriberId,
+        timerCount: timerIds.length,
+        timePoints
+      });
+    }
+  }
+
+  /**
+   * schedule 变价时间点定时器触发：刷新 schedule_datetime 后重算并 callback。
+   */
+  async onScheduleTimePointTimerFire(subscriberId, timerId) {
+    this.removeScheduleTimerRef(subscriberId, timerId);
+    if (!this.productQuerySubscribers.has(subscriberId)) return;
+    const subscriber = this.productQuerySubscribers.get(subscriberId);
+    this.refreshSubscriberScheduleAtExecution(subscriber);
+    await this.recomputeAndNotifySubscriber(subscriberId);
+  }
+
+  /**
+   * 对单个商品 query 订阅者重算并推送（定时路径；不新建 schedule timer）。
+   */
+  async recomputeAndNotifySubscriber(subscriberId) {
+    const subscriber = this.productQuerySubscribers.get(subscriberId);
+    if (!subscriber) return;
+    try {
+      const result = await this.computeProductQueryResult(subscriber.context);
+      subscriber.callback(result);
+      this.logInfo('recomputeAndNotifySubscriber: 已推送', {
+        subscriberId,
+        schedule_datetime: subscriber.context.schedule_datetime
+      });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logError('recomputeAndNotifySubscriber: 推送失败', {
+        subscriberId,
+        error: errorMessage
+      });
+    }
+  }
+
+  /**
+   * query 完成后为 subscriber 同步 schedule 定时器（先 clear 再 schedule）。
+   */
+  syncProductQueryScheduleTimers(subscriberId, strategy_context) {
+    this.clearSubscriberScheduleTimers(subscriberId);
+    if (!this.shouldScheduleProductQueryReload(strategy_context)) {
+      return;
+    }
+    const timePoints = this.products?.getLastScheduleTimePoints?.() ?? [];
+    if (timePoints.length > 0) {
+      this.scheduleSubscriberTimePointReloads(subscriberId, timePoints);
+    }
+  }
+
   /**
    * 处理商品查询请求
    * 存储订阅者信息，便于数据变更时推送最新结果
@@ -704,17 +1396,30 @@ class Server {
   }) => {
     const {
       menu_list_ids,
-      schedule_datetime,
-      schedule_date
+      customer_id,
+      ids,
+      extension_type,
+      strategy_context
     } = data;
     const {
-      callback,
+      schedule_date,
+      schedule_datetime
+    } = this.resolveProductQueryScheduleContext({
+      schedule_date: data.schedule_date,
+      schedule_datetime: data.schedule_datetime
+    });
+    const {
+      callback,
       subscriberId
     } = config || {};
     this.logInfo('handleProductQuery: 开始处理商品查询请求', {
       menu_list_ids,
+      ids,
       schedule_datetime,
-      schedule_date
+      schedule_date,
+      customer_id,
+      extension_type,
+      strategyContextKeys: strategy_context ? Object.keys(strategy_context) : []
     });
 
     // 存储订阅者：后续 pubsub 数据变更时可通过 callback 推送最新结果
@@ -723,8 +1428,12 @@ class Server {
         callback,
         context: {
           menu_list_ids,
+          ids,
           schedule_date,
-          schedule_datetime
+          schedule_datetime,
+          customer_id,
+          extension_type,
+          strategy_context
         }
       });
       this.logInfo('handleProductQuery: 已注册订阅者', {
@@ -732,10 +1441,110 @@ class Server {
         totalSubscribers: this.productQuerySubscribers.size
       });
     }
-    return this.computeProductQueryResult({
+    const result = await this.computeProductQueryResult({
       menu_list_ids,
+      ids,
+      schedule_date,
+      schedule_datetime,
+      customer_id,
+      extension_type,
+      strategy_context
+    });
+    if (subscriberId && typeof callback === 'function') {
+      this.syncProductQueryScheduleTimers(subscriberId, strategy_context);
+    }
+    return result;
+  };
+
+  /**
+   * ProductList callers such as standalone retail pages do not always have a selected schedule.
+   * In that case query against the current local time so menu availability can still be evaluated.
+   */
+  resolveProductQueryScheduleContext(params) {
+    const now = (0, _dayjs.default)();
+    const schedule_datetime = typeof params.schedule_datetime === 'string' && params.schedule_datetime.trim() ? params.schedule_datetime : now.format('YYYY-MM-DD HH:mm:ss');
+    const schedule_date = typeof params.schedule_date === 'string' && params.schedule_date.trim() ? params.schedule_date : (0, _dayjs.default)(schedule_datetime).isValid() ? (0, _dayjs.default)(schedule_datetime).format('YYYY-MM-DD') : now.format('YYYY-MM-DD');
+    return {
       schedule_date,
       schedule_datetime
+    };
+  }
+
+  /**
+   * OpenData 的关联餐牌可能已更新，而 server_menu/server_schedule 仍命中本地持久化缓存。
+   * 仅在当前筛选没有任何生效餐牌时刷新一次，并由调用方重新计算筛选结果。
+   */
+  async refreshMenuScheduleCacheAfterEmptyResult() {
+    if (!this.menu || !this.schedule) return false;
+    const now = Date.now();
+    if (now - this.lastMenuScheduleRefreshAt < this.MENU_SCHEDULE_REFRESH_COOLDOWN_MS) {
+      return false;
+    }
+    if (!this.menuScheduleRefreshInFlight) {
+      this.lastMenuScheduleRefreshAt = now;
+      this.menuScheduleRefreshInFlight = Promise.all([this.menu.loadMenuList(), this.schedule.loadAllSchedule()]).then(() => undefined).catch(error => {
+        this.logWarning('刷新菜单/日程缓存失败，继续使用现有缓存', {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }).finally(() => {
+        this.menuScheduleRefreshInFlight = null;
+      });
+    }
+    await this.menuScheduleRefreshInFlight;
+    return true;
+  }
+
+  /**
+   * 按商品 id 查询单条（GET /shop/product/query/:productId）
+   * schedule_date 必填：query 或 data；schedule_datetime 可选。不走订阅。
+   */
+  handleProductQueryById = async ({
+    path,
+    method,
+    data,
+    url
+  }) => {
+    const pathname = this.parseRequestPath(url || '', path);
+    const idMatch = pathname.match(/^\/shop\/product\/query\/(\d+)$/);
+    const productId = idMatch ? Number(idMatch[1]) : NaN;
+    if (!Number.isFinite(productId)) {
+      this.logWarning('handleProductQueryById: 无效的商品 id', {
+        path: pathname
+      });
+      return {
+        code: 400,
+        message: '无效的商品路径',
+        status: false,
+        data: {
+          item: null
+        }
+      };
+    }
+    const scheduleDateFromData = data && typeof data === 'object' && typeof data.schedule_date === 'string' ? data.schedule_date.trim() : '';
+    const schedule_date = scheduleDateFromData || (this.extractQueryParam(url || '', 'schedule_date') || '').trim() || (0, _dayjs.default)().format('YYYY-MM-DD');
+    if (!schedule_date) {
+      this.logWarning('handleProductQueryById: 缺少 schedule_date', {
+        productId
+      });
+      return {
+        code: 400,
+        message: 'schedule_date 为必填（query 或 data）',
+        status: false,
+        data: null
+      };
+    }
+    const scheduleDtFromData = data && typeof data === 'object' && typeof data.schedule_datetime === 'string' ? data.schedule_datetime.trim() : '';
+    const scheduleDtFromUrl = (this.extractQueryParam(url || '', 'schedule_datetime') || '').trim();
+    const scheduleDatetime = scheduleDtFromData || scheduleDtFromUrl || `${schedule_date}T00:00:00`;
+    this.logInfo('handleProductQueryById: 开始', {
+      productId,
+      schedule_date,
+      schedule_datetime: scheduleDatetime
+    });
+    return this.computeProductQueryResult({
+      schedule_date,
+      schedule_datetime: scheduleDatetime,
+      product_id: productId
     });
   };
 
@@ -773,20 +1582,32 @@ class Server {
       callback,
       subscriberId
     } = config || {};
+    const useLocal = this.shouldUseLocalOrderQuery(queryPayload);
     this.logInfo('handleOrderList: 开始处理订单列表请求', {
-      data: queryPayload
+      data: queryPayload,
+      useLocal
     });
-    if (subscriberId && typeof callback === 'function') {
-      this.orderQuerySubscribers.set(subscriberId, {
-        callback,
-        context: queryPayload
-      });
-      this.logInfo('handleOrderList: 已注册订阅者', {
+    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);
   };
 
   /**
@@ -813,26 +1634,116 @@ class Server {
   };
 
   /**
-   * 判断预约查询的 sales_time_between 起始日期是否为今天
+   * 处理 sales 单模块搜索：请求透传后端，仅在 OS 层维护已返回订单号集合。
+   *
+   * @example
+   * await this.handleSalesSearchModule({ url: '/shop/es/search/sales', method: 'post', data: { keyword: 'A' } })
    */
-  isBookingQueryForToday(data) {
-    const range = data?.sales_time_between;
-    if (!Array.isArray(range) || range.length < 1) return true;
-    const startDateStr = String(range[0]).split('T')[0].split(' ')[0];
-    const todayStr = (0, _dayjs.default)().format('YYYY-MM-DD');
-    return startDateStr === todayStr;
+  handleSalesSearchModule = async ({
+    data,
+    config
+  }) => {
+    return this.handleSalesSearchRequest('single', '/shop/es/search/sales', data, config);
+  };
+
+  /**
+   * 处理 sales 聚合搜索：请求透传后端，仅订阅 sales 分组的已返回订单号。
+   *
+   * @example
+   * await this.handleSalesSearchAggregate({ url: '/shop/es/search', method: 'post', data: { modules: [] } })
+   */
+  handleSalesSearchAggregate = async ({
+    data,
+    config
+  }) => {
+    return this.handleSalesSearchRequest('aggregate', '/shop/es/search', data, config);
+  };
+
+  /**
+   * 取消 sales 搜索订阅。
+   *
+   * @example
+   * await this.handleUnsubscribeSalesSearch({ data: { subscriberId: 'global-search-order' } } as any)
+   */
+  handleUnsubscribeSalesSearch = async ({
+    data
+  }) => {
+    const {
+      subscriberId
+    } = data || {};
+    if (subscriberId) {
+      this.salesSearchSubscribers.delete(subscriberId);
+      this.logInfo('handleUnsubscribeSalesSearch: 已移除订阅者', {
+        subscriberId,
+        remaining: this.salesSearchSubscribers.size
+      });
+    }
+    return {
+      code: 200,
+      message: 'ok',
+      status: true
+    };
+  };
+
+  /**
+   * 执行 sales 搜索并登记可见订单号。
+   * 搜索参数完全透传后端，OS 不做过滤、筛选、排序。
+   *
+   * @example
+   * const result = await this.handleSalesSearchRequest('single', '/shop/es/search/sales', { keyword: '1001' }, {})
+   */
+  async handleSalesSearchRequest(kind, backendPath, data, config) {
+    const queryPayload = data && typeof data === 'object' ? {
+      ...data
+    } : {};
+    const result = await this.fetchSalesSearchFromAPI(backendPath, queryPayload);
+    const {
+      callback,
+      subscriberId,
+      resetVisibleOrderIds
+    } = config || {};
+    if (subscriberId && typeof callback === 'function') {
+      const contextSignature = this.buildSalesSearchSignature(kind, queryPayload);
+      const existing = this.salesSearchSubscribers.get(subscriberId);
+      const shouldReset = resetVisibleOrderIds === true || !existing || existing.kind !== kind || existing.contextSignature !== contextSignature;
+      const visibleOrderIds = shouldReset ? new Set() : new Set(existing.visibleOrderIds);
+      for (const orderId of this.extractSalesSearchOrderIds(kind, result)) {
+        visibleOrderIds.add(orderId);
+      }
+      this.salesSearchSubscribers.set(subscriberId, {
+        callback,
+        kind,
+        contextSignature,
+        visibleOrderIds,
+        lastResponseData: this.extractSalesSearchResponseData(result)
+      });
+      this.logInfo('handleSalesSearchRequest: 已注册/更新订阅者', {
+        subscriberId,
+        kind,
+        shouldReset,
+        visibleCount: visibleOrderIds.size
+      });
+    }
+    return result;
   }
 
   /**
-   * 非今天的预约查询：通过真实 API 获取数据，再做 flattenOrdersToBookings 拆分
+   * 透传调用后端 sales 搜索接口。
+   *
+   * @example
+   * const res = await this.fetchSalesSearchFromAPI('/shop/es/search/sales', { keyword: '1001' })
    */
-  async fetchBookingListFromAPI(data) {
+  async fetchSalesSearchFromAPI(backendPath, data) {
     if (!this.app?.request) {
-      this.logError('fetchBookingListFromAPI: app.request 不可用');
+      this.logError('fetchSalesSearchFromAPI: app.request 不可用', {
+        backendPath
+      });
       return {
         code: 500,
         message: 'app.request 不可用',
-        data: {
+        data: backendPath === '/shop/es/search' ? {
+          results: []
+        } : {
           list: [],
           count: 0
         },
@@ -840,115 +1751,2625 @@ class Server {
       };
     }
     try {
-      const response = await this.app.request.get('/shop/order/sales', {
-        ...data,
-        form_record_ids: undefined,
-        with: ["all"]
-      }, {
+      const response = await this.app.request.post(backendPath, data, {
         isShopApi: true
       });
-      const rawList = response?.data?.list ?? response?.list ?? [];
-      const list = (0, _filterBookings.filterBookingsFromOrders)(rawList, data);
-      this.logInfo('fetchBookingListFromAPI: API 返回并拆分完成', {
-        rawCount: rawList.length,
-        flattenedCount: list.count
+      const payload = response?.data ?? response;
+      return {
+        code: response?.code ?? 200,
+        status: response?.status ?? true,
+        message: response?.message ?? '',
+        data: payload
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logError('fetchSalesSearchFromAPI: 请求失败', {
+        backendPath,
+        error: errorMessage
+      });
+      return {
+        code: 500,
+        message: errorMessage,
+        data: backendPath === '/shop/es/search' ? {
+          results: []
+        } : {
+          list: [],
+          count: 0
+        },
+        status: false
+      };
+    }
+  }
+
+  /**
+   * 构建搜索订阅签名；页码变化不重置，可继续累计 visibleOrderIds。
+   *
+   * @example
+   * const signature = this.buildSalesSearchSignature('single', { keyword: 'A', page: 2 })
+   */
+  buildSalesSearchSignature(kind, payload) {
+    return this.stableSerialize({
+      kind,
+      payload: this.stripSalesSearchPageParams(payload)
+    });
+  }
+
+  /**
+   * 移除页码参数，保留 page size、keyword、filters、sort 等查询语义参数。
+   *
+   * @example
+   * this.stripSalesSearchPageParams({ page: 2, per_page: 20, keyword: 'A' })
+   */
+  stripSalesSearchPageParams(value) {
+    if (Array.isArray(value)) {
+      return value.map(item => this.stripSalesSearchPageParams(item));
+    }
+    if (!value || typeof value !== 'object') return value;
+    const next = {};
+    for (const [key, item] of Object.entries(value)) {
+      if (key === 'page' || key === 'skip') continue;
+      next[key] = this.stripSalesSearchPageParams(item);
+    }
+    return next;
+  }
+
+  /**
+   * 提取响应 data，兼容 OS 包装结构与后端直接响应结构。
+   *
+   * @example
+   * const data = this.extractSalesSearchResponseData(result)
+   */
+  extractSalesSearchResponseData(result) {
+    return result?.data ?? result;
+  }
+
+  /**
+   * 从搜索响应中提取 sales 命中的订单号。
+   *
+   * @example
+   * const ids = this.extractSalesSearchOrderIds('single', result)
+   */
+  extractSalesSearchOrderIds(kind, result) {
+    const data = this.extractSalesSearchResponseData(result);
+    const list = kind === 'aggregate' ? this.findSalesSearchAggregateGroup(data)?.list : data?.list;
+    if (!Array.isArray(list)) return [];
+    return list.map(item => this.getSalesSearchOrderId(item)).filter(id => !!id);
+  }
+
+  /**
+   * 查找聚合搜索响应中的 sales 分组。
+   *
+   * @example
+   * const group = this.findSalesSearchAggregateGroup({ results: [{ module: 'sales' }] })
+   */
+  findSalesSearchAggregateGroup(data) {
+    const results = Array.isArray(data?.results) ? data.results : [];
+    return results.find(item => item?.module === 'sales') || null;
+  }
+
+  /**
+   * 从订单或搜索命中项中取订单号。
+   *
+   * @example
+   * const id = this.getSalesSearchOrderId({ order_id: 1001 })
+   */
+  getSalesSearchOrderId(order) {
+    if (!order || typeof order !== 'object') return null;
+    const raw = order.order_id ?? order.id;
+    if (raw === undefined || raw === null || raw === '') return null;
+    return String(raw);
+  }
+
+  /**
+   * 从查询值中提取 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, _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.isRangeFullyToday('2026-04-15', '2026-04-15') // => true
+   */
+  isRangeFullyToday(startRaw, endRaw) {
+    const startDate = this.extractQueryDate(startRaw);
+    const endDate = this.extractQueryDate(endRaw);
+    if (!startDate || !endDate) return false;
+    const today = (0, _dayjs.default)().format('YYYY-MM-DD');
+    return startDate === today && endDate === today;
+  }
+
+  /**
+   * 判断时间范围是否「开始和结束都不是今天」。
+   *
+   * @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, _dayjs.default)().format('YYYY-MM-DD');
+    return startDate !== today && endDate !== today;
+  }
+
+  /**
+   * 订单查询是否走本地：
+   * - 仅当 start_time 与 end_time 都是今天时，走本地；
+   * - 任意一端不是今天时，走云端，确保跨天查询能拉取非本地窗口数据。
+   */
+  shouldUseLocalOrderQuery(data) {
+    return this.isRangeFullyToday(data?.start_time, data?.end_time);
+  }
+
+  /**
+   * 预约查询是否走本地：
+   * - 当 sales_time_between 的开始和结束都不是今天时，走远端；
+   * - 其余情况走本地。
+   */
+  shouldUseLocalBookingQuery(data) {
+    const range = data?.sales_time_between;
+    if (!Array.isArray(range) || range.length < 2) return true;
+    return !this.isRangeBothNotToday(range[0], range[1]);
+  }
+
+  /**
+   * 日历 SSE 精简 with：由调用方显式声明 compact_fields 决定
+   * - compact_fields === true → 精简字段（周/月视图）
+   * - 其余（false / 未传）→ ['all']（日视图/表格/平面图合并）
+   */
+  resolveBookingSalesWith(queryPayload) {
+    if (queryPayload?.compact_fields === true) {
+      return ['bookings:booking_id,start_date,start_time,end_date,end_time,holder,metadata,parent_id,item_type', 'customer:id,display_name,phone', 'products'
+      // 'resources'
+      ];
+    }
+    return ['all'];
+  }
+
+  /**
+   * 日历 SSE 精简 select：渲染 + filterBookingsFromOrders 所需的主表字段
+   * business_code / payment_status 不直接用于渲染，但 matchOrder 过滤依赖
+   */
+  resolveBookingSalesSelect() {
+    return 'status,payment_status,business_code,phone,customer_name,schedule_date,created_at,metadata';
+  }
+
+  /**
+   * 日历（compact_fields）场景下要直接在 SSE 层排除的订单类型：
+   * 这些类型不会出现在日历上，拉取它们只会浪费带宽并增加前端过滤成本。
+   */
+  BOOKING_SALES_COMPACT_EXCLUDE_TYPES = ['virtual', 'shipping', 'delivery', 'pickup'];
+  normalizeBookingRemoteQueryPayload(data, withFields) {
+    const isFullWith = withFields.length === 1 && withFields[0] === 'all';
+    const isCompact = data?.compact_fields === true;
+    return {
+      ...data,
+      form_record_ids: undefined,
+      enable_remote_memory_cache: undefined,
+      compact_fields: undefined,
+      with: withFields,
+      ...(isFullWith ? {} : {
+        select: this.resolveBookingSalesSelect()
+      }),
+      ...(isCompact ? {
+        exclude_types: this.BOOKING_SALES_COMPACT_EXCLUDE_TYPES
+      } : {}),
+      chunk_size: 50
+    };
+  }
+
+  /**
+   * 远端预约查询内存缓存开关：默认 false，仅显式 true 才启用。
+   */
+  isBookingRemoteMemoryCacheEnabled(queryPayload) {
+    return queryPayload?.enable_remote_memory_cache === true;
+  }
+  stableSerialize(value) {
+    if (value === null || value === undefined) 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] !== undefined).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?.sales_time_between;
+    if (!Array.isArray(range) || range.length < 2) return null;
+    const startAtMs = (0, _dayjs.default)(range[0]).valueOf();
+    const endAtMs = (0, _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 === undefined || 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() {
+    if (this.bookingRemoteCache.size === 0) return;
+    const syncStartAt = Date.now();
+    const latestOrders = this.order?.getOrders?.() ?? [];
+    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 = 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, _filterBookings.sortBookings)((0, _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) {
+    if (!this.app?.request) {
+      this.logError('fetchOrderListFromAPI: app.request 不可用');
+      return {
+        code: 500,
+        message: 'app.request 不可用',
+        data: {
+          list: [],
+          count: 0
+        },
+        status: false
+      };
+    }
+    try {
+      const response = await this.app.request.post('/shop/order/v2/list', data, {
+        isShopApi: true
+      });
+      const payload = response?.data ?? response;
+      const list = Array.isArray(payload?.list) ? payload.list : [];
+      const count = typeof payload?.count === 'number' ? payload.count : list.length;
+      return {
+        code: 200,
+        data: {
+          ...payload,
+          list,
+          count
+        },
+        message: '',
+        status: true
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logError('fetchOrderListFromAPI: 请求失败', {
+        error: errorMessage
+      });
+      return {
+        code: 500,
+        message: errorMessage,
+        data: {
+          list: [],
+          count: 0
+        },
+        status: false
+      };
+    }
+  }
+
+  /**
+   * 非今天的预约查询：通过 SSE 流式拉取订单，再做本地 booking 筛选展开
+   */
+  async fetchBookingListFromAPI(data) {
+    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, _filterBookings.sortBookings)((0, _filterBookings.filterBookingsFromOrders)(rawList, data), data);
+
+      // DEBUG: 挂到 window 上方便排查 SSE → 日历数据丢失问题
+      if (typeof globalThis !== 'undefined') {
+        globalThis.__SSE_BOOKING_DEBUG__ = {
+          ts: new Date().toISOString(),
+          sseRequestPayload: requestPayload,
+          calendarFilters: data,
+          rawOrderCount: rawList.length,
+          rawOrderSample: rawList.slice(0, 2).map(o => ({
+            order_id: o?.order_id,
+            business_code: o?.business_code,
+            status: o?.status,
+            payment_status: o?.payment_status,
+            bookingsCount: o?.bookings?.length,
+            firstBooking: o?.bookings?.[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: o.bookings[0].resources?.length
+            } : null
+          })),
+          filteredBookingCount: bookingResult.count,
+          filteredListLength: bookingResult.list?.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,
+        data: {
+          list: [],
+          count: 0
+        },
+        status: false
+      };
+    }
+  }
+
+  /**
+   * 处理预约列表查询
+   * 今天：注册订阅者 + 本地数据筛选；非今天：清理订阅者 + 走真实 API
+   */
+  handleBookingList = async ({
+    url,
+    method,
+    data,
+    config
+  }) => {
+    const queryPayload = data && typeof data === 'object' ? {
+      ...data
+    } : {};
+    const {
+      callback,
+      subscriberId
+    } = config || {};
+    const useLocal = this.shouldUseLocalBookingQuery(queryPayload);
+    this.logInfo('handleBookingList: 开始处理预约列表请求', {
+      data: queryPayload,
+      useLocal
+    });
+    if (useLocal) {
+      if (subscriberId) {
+        this.bookingRemoteQuerySubscribers.delete(subscriberId);
+      }
+      if (subscriberId && typeof callback === 'function') {
+        this.bookingQuerySubscribers.set(subscriberId, {
+          callback,
+          context: queryPayload
+        });
+        this.logInfo('handleBookingList: 已注册订阅者（今天）', {
+          subscriberId,
+          totalSubscribers: this.bookingQuerySubscribers.size
+        });
+      }
+      return this.computeBookingQueryResult(queryPayload);
+    } 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
+        });
+      }
+      return this.fetchBookingListFromAPI(queryPayload);
+    }
+  };
+
+  /**
+   * 处理资源列表查询
+   * 转发到资源模块去
+   */
+  handleResourceList = async ({
+    url,
+    method,
+    data,
+    config
+  }) => {
+    const list = this.resource?.getResources({
+      skip: data?.skip || 1,
+      num: data?.num || 10
+    });
+    this.logInfo('Server 劫持 Resource 接口：handleResourceList: 资源列表查询结果', {
+      list
+    });
+    return {
+      code: 200,
+      data: {
+        list,
+        count: list?.length || 0
+      },
+      message: '',
+      status: true
+    };
+  };
+
+  /**
+   * 代理刷新 / 合并订单到本地（单笔 / 批量二合一）：
+   * - 入参（GET query 或 data 任一）：
+   *   - `order_id`：单笔模式，原有行为
+   *   - `order_ids`：批量模式，逗号分隔的 id 列表（如 `?order_ids=1,2,3`），数组也兼容
+   *   - 同时存在时优先批量
+   * - 单笔流程：后端 /order/sales/{id}?with[]=all → 本地有则覆盖、无则 merge → 落 SQLite → emit onOrdersChanged
+   * - 批量流程：并发拉取每笔详情 → 一次性 `upsertOrdersFromRemote` 合并写入 → 仅 emit 一次 onOrdersChanged，
+   *   单笔失败不影响其他成功项；返回 { overwritten, inserted, failed }
+   * - 监听级联：onOrdersChanged 触发订单 / 预约 / bookingRemoteCache 三路订阅者推送
+   *
+   * @example 单笔：GET /update/localOrder?order_id=96971
+   * @example 批量：GET /update/localOrder?order_ids=96971,96972,96973
+   */
+  handleUpdateLocalOrder = async ({
+    url,
+    data
+  }) => {
+    if (typeof data?.order_id === 'string' && data?.order_id?.startsWith('LOCAL_')) {
+      // 本地订单跳过这个更新
+      // TODO 待优化 UI 层的调用
+      return {
+        code: 200,
+        status: true
+      };
+    }
+    const batchIds = this.parseOrderIdsParam(url, data);
+    if (batchIds.length > 0) {
+      return this.handleUpdateLocalOrdersBatch(batchIds);
+    }
+    const rawOrderId = (data && typeof data === 'object' ? data.order_id : undefined) ?? this.extractQueryParam(url, 'order_id');
+    const orderId = rawOrderId === undefined || rawOrderId === null || rawOrderId === '' ? null : String(rawOrderId).trim();
+    this.logInfo('handleUpdateLocalOrder: 开始处理', {
+      url,
+      orderId
+    });
+    if (!orderId) {
+      this.logWarning('handleUpdateLocalOrder: order_id 缺失', {
+        url,
+        data
+      });
+      return {
+        code: 400,
+        status: false,
+        message: 'order_id 缺失',
+        data: null
+      };
+    }
+    if (!this.order) {
+      this.logError('handleUpdateLocalOrder: Order 模块未注册');
+      return {
+        code: 500,
+        status: false,
+        message: 'Order 模块未注册',
+        data: null
+      };
+    }
+    if (!this.app?.request) {
+      this.logError('handleUpdateLocalOrder: app.request 不可用');
+      return {
+        code: 500,
+        status: false,
+        message: 'app.request 不可用',
+        data: null
+      };
+    }
+    const backendPath = `/shop/order/sales/${encodeURIComponent(orderId)}?with%5B%5D=all`;
+    try {
+      const response = await this.app.request.get(backendPath, undefined, {
+        isShopApi: true
+      });
+      const fresh = response?.data ?? response;
+      if (!fresh || typeof fresh !== 'object' || fresh.order_id == null) {
+        this.logError('handleUpdateLocalOrder: 后端返回订单为空', {
+          orderId,
+          backendPath
+        });
+        return {
+          code: 500,
+          status: false,
+          message: '后端返回订单为空',
+          data: null
+        };
+      }
+      const exists = !!this.order.getOrderByOrderId(orderId);
+      if (exists) {
+        const {
+          overwritten
+        } = await this.order.overwriteExistingOrder(fresh);
+        this.logInfo('handleUpdateLocalOrder: 覆盖完成', {
+          orderId,
+          overwritten
+        });
+        return {
+          code: 200,
+          status: true,
+          message: '',
+          data: {
+            overwritten,
+            inserted: false,
+            order_id: orderId
+          }
+        };
+      }
+      await this.order.upsertOrdersFromRemote([fresh]);
+      this.logInfo('handleUpdateLocalOrder: 本地合并新订单完成', {
+        orderId
+      });
+      return {
+        code: 200,
+        status: true,
+        message: '',
+        data: {
+          overwritten: false,
+          inserted: true,
+          order_id: orderId
+        }
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logError('handleUpdateLocalOrder: 请求失败', {
+        orderId,
+        backendPath,
+        error: errorMessage
+      });
+      return {
+        code: 500,
+        status: false,
+        message: errorMessage,
+        data: null
+      };
+    }
+  };
+  handleOrderSalesCheckout = async ({
+    data
+  }) => {
+    return this.handleOrderCheckoutSubmit({
+      backendPath: '/shop/order/sales/checkout',
+      data,
+      title: 'handleOrderSalesCheckout'
+    });
+  };
+  handleOrderCheckout = async ({
+    data
+  }) => {
+    return this.handleOrderCheckoutSubmit({
+      backendPath: '/order/checkout',
+      data,
+      title: 'handleOrderCheckout'
+    });
+  };
+  getDeviceTaskPlugin() {
+    return this.app?.getPlugin?.('deviceTask') || null;
+  }
+  getIdGeneratorPlugin() {
+    return this.app?.getPlugin?.('idGenerator') || null;
+  }
+  getAppData(key) {
+    const getData = this.core.getPlugin('app')?.getData?.();
+    if (typeof getData === 'function') return getData(key);
+    const directValue = this.app?.getData?.(key);
+    if (directValue !== undefined) return directValue;
+    const coreData = this.app?.models?.getStore?.().getDataByModel?.('core', 'core') || this.app?.data?.store?.getStore?.().getDataByModel?.('core', 'core') || this.app?.data?.store?.getStore?.().getDataByModel?.('core')?.core;
+    return coreData?.[key];
+  }
+  getSmallTicketShopInfo() {
+    const shopInfo = this.getAppData('shop_info') || {};
+    return {
+      ...shopInfo,
+      currency_symbol: shopInfo.currency_symbol || this.getAppData('shop_symbol') || this.getAppData('currency_symbol'),
+      currency_code: shopInfo.currency_code || this.getAppData('shop_currency_code') || this.getAppData('currency_code'),
+      tax_title: shopInfo.tax_title || this.getAppData('tax_title'),
+      tax_country_code: shopInfo.tax_country_code || this.getAppData('tax_country_code'),
+      is_price_include_tax: shopInfo.is_price_include_tax ?? this.getAppData('is_price_include_tax')
+    };
+  }
+  taskOk(result) {
+    return {
+      status: 'success',
+      result
+    };
+  }
+  taskFail(code, message, result) {
+    return {
+      status: 'failed',
+      error: {
+        code,
+        message
+      },
+      ...(result !== undefined ? {
+        result
+      } : {})
+    };
+  }
+  taskTimeout(message) {
+    return {
+      status: 'timeout',
+      error: {
+        code: 'TIMEOUT',
+        message
+      }
+    };
+  }
+  async getShortNumberOrDeviceId() {
+    const getAsyncIotDeviceInfo = this.getAppData('async_iot_device_info');
+    if (getAsyncIotDeviceInfo) {
+      const res = await getAsyncIotDeviceInfo?.();
+      if (res?.short_number) {
+        return res?.short_number;
+      }
+    }
+    return String(this.getAppData('device_id') || 0).slice(-2);
+  }
+  buildCheckoutTaskIdempotencyKey(data) {
+    const identity = data?.request_unique_idempotency_token || data?.external_sale_number || data?.order_id || data?.shop_order_number || data?.shop_full_order_number;
+    if (identity === undefined || identity === null || identity === '') return undefined;
+    return `sync_sales:${identity}`;
+  }
+  isBlankCheckoutValue(value) {
+    return value === undefined || value === null || value === '';
+  }
+  isLocalCheckoutOrderId(orderId) {
+    return typeof orderId === 'string' && orderId.startsWith('LOCAL_');
+  }
+  async normalizeCheckoutSubmitData(data, title) {
+    if (!data || typeof data !== 'object') return data;
+    const next = {
+      ...data
+    };
+    const externalSaleNumber = next.external_sale_number;
+    const shouldClearLocalOrderId = this.isLocalCheckoutOrderId(next.order_id);
+    if (shouldClearLocalOrderId) next.order_id = null;
+    // 删除 数据体中的 vouchers,对小票和后端来说他们不需要，这个字段只是单向同步给前端用的，而且目前对订单来说还没什么用
+    delete next.vouchers;
+    const hasCheckoutOrderNumbers = !this.isBlankCheckoutValue(next.shop_order_number) && !this.isBlankCheckoutValue(next.shop_full_order_number);
+    if (hasCheckoutOrderNumbers) {
+      this.logInfo(`${title}: checkout 已携带订单号，跳过查重`, {
+        original_order_id: data.order_id,
+        order_id: next.order_id,
+        external_sale_number: externalSaleNumber,
+        shop_order_number: next.shop_order_number,
+        shop_full_order_number: next.shop_full_order_number
+      });
+      return next;
+    }
+    if (this.isBlankCheckoutValue(externalSaleNumber)) {
+      if (shouldClearLocalOrderId) {
+        this.logInfo(`${title}: checkout 本地订单号已清理`, {
+          original_order_id: data.order_id,
+          order_id: next.order_id
+        });
+      }
+      return next;
+    }
+    if (!this.order || typeof this.order.getLocalOrderFromMemoryByLookup !== 'function') {
+      if (shouldClearLocalOrderId) {
+        this.logInfo(`${title}: checkout 本地订单号已清理`, {
+          original_order_id: data.order_id,
+          external_sale_number: externalSaleNumber
+        });
+      }
+      return next;
+    }
+    try {
+      const localOrder = this.order.getLocalOrderFromMemoryByLookup(externalSaleNumber);
+      if (!localOrder) {
+        if (shouldClearLocalOrderId) {
+          this.logInfo(`${title}: checkout 本地订单号已清理`, {
+            original_order_id: data.order_id,
+            external_sale_number: externalSaleNumber,
+            localOrderFound: false
+          });
+        }
+        return next;
+      }
+      if (this.isBlankCheckoutValue(next.shop_order_number)) {
+        next.shop_order_number = localOrder.shop_order_number;
+      }
+      if (this.isBlankCheckoutValue(next.shop_full_order_number)) {
+        next.shop_full_order_number = localOrder.shop_full_order_number;
+      }
+      this.logInfo(`${title}: checkout 已复用本地订单号`, {
+        original_order_id: data.order_id,
+        order_id: next.order_id,
+        external_sale_number: externalSaleNumber,
+        local_order_id: localOrder.order_id,
+        shop_order_number: next.shop_order_number,
+        shop_full_order_number: next.shop_full_order_number
+      });
+      // 删除 数据体中的 vouchers,对小票和后端来说他们不需要，这个字段只是单向同步给前端用的，而且目前对订单来说还没什么用
+      return next;
+    } catch (error) {
+      this.logWarning(`${title}: checkout 查找本地订单失败`, {
+        external_sale_number: externalSaleNumber,
+        error: this.getUnknownErrorMessage(error),
+        error_detail: this.normalizeUnknownError(error)
+      });
+      return next;
+    }
+  }
+  async ensureCheckoutOrderNumbers(data, title) {
+    if (!data || typeof data !== 'object') return data;
+    const next = {
+      ...data
+    };
+    const needsShopOrderNumber = next.shop_order_number === undefined || next.shop_order_number === null || next.shop_order_number === '';
+    const needsShopFullOrderNumber = next.shop_full_order_number === undefined || next.shop_full_order_number === null || next.shop_full_order_number === '';
+    if (!needsShopOrderNumber && !needsShopFullOrderNumber) return next;
+    const idGenerator = this.getIdGeneratorPlugin();
+    if (!idGenerator) {
+      this.logWarning(`${title}: idGenerator 插件不可用，无法生成订单号`, {
+        needsShopOrderNumber,
+        needsShopFullOrderNumber
+      });
+      return next;
+    }
+    try {
+      if (needsShopOrderNumber && idGenerator.generateShopOrderNumber) {
+        next.shop_order_number = await idGenerator.generateShopOrderNumber({
+          biz: next.business_code || 'ticket'
+        });
+      }
+      if (needsShopFullOrderNumber && idGenerator.generateReceiptId) {
+        next.shop_full_order_number = await idGenerator.generateReceiptId({
+          biz: next.business_code || 'ticket'
+        });
+      }
+      this.logInfo(`${title}: checkout 订单号已准备`, {
+        shop_order_number: next.shop_order_number,
+        shop_full_order_number: next.shop_full_order_number
+      });
+    } catch (error) {
+      this.logError(`${title}: 生成 checkout 订单号失败`, {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+    return next;
+  }
+  async dispatchCheckoutSyncTask(params) {
+    this.registerDeviceTaskActions();
+    const deviceTask = this.getDeviceTaskPlugin();
+    const debugDeviceId = await this.getShortNumberOrDeviceId();
+    const debugIdempotencyKey = this.buildCheckoutTaskIdempotencyKey(params.data);
+    if (!deviceTask?.dispatch) {
+      this.logError(`${params.title}: deviceTask.dispatch 不可用`);
+      return;
+    }
+    try {
+      const result = await deviceTask.dispatch({
+        action: 'sync_sales',
+        device_id: debugDeviceId,
+        payload: {
+          backendPath: params.backendPath,
+          data: params.data,
+          external_sale_number: params.data?.external_sale_number,
+          title: params.title
+        },
+        retry_limit: 5,
+        idempotency_key: debugIdempotencyKey,
+        name: '同步订单',
+        source: 'server',
+        source_type: 'order',
+        source_id: params.data?.order_id || params.data?.external_sale_number || params.data?.shop_order_number
+      });
+      this.logInfo(`${params.title}: sync_sales 任务已派发`, {
+        uuid: result?.uuid,
+        status: result?.status,
+        reused: result?.reused
+      });
+    } catch (error) {
+      this.logError(`${params.title}: 派发 sync_sales 任务失败`, {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  async dispatchPrintOtherReceiptTask(params) {
+    const deviceTask = this.getDeviceTaskPlugin();
+    if (!deviceTask?.dispatch) {
+      this.logWarning('dispatchPrintOtherReceiptTask: deviceTask.dispatch 不可用');
+      return;
+    }
+    try {
+      let printIdentity = this.getPrintOrderIdentity(params.syncedOrder);
+      const deviceId = await this.getShortNumberOrDeviceId();
+      await deviceTask.dispatch({
+        action: 'print_all',
+        device_id: params.deviceId ?? deviceId,
+        payload: {
+          type: params.isManualPrint ? '0' : '99',
+          data: params.receiptOnly ? {
+            order_id: printIdentity,
+            small_ticket_data: params.syncedOrder?.payment_info?.small_ticket_data,
+            skip_wristband: true,
+            skip_voucher: true
+          } : {
+            order_id: printIdentity,
+            machine_code_print_info: params.syncedOrder?.payment_info?.machine_code_print_info,
+            machine_code_print_info_v2: params.syncedOrder?.machine_code_print_info_v2,
+            skip_receipt: true
+          }
+        },
+        idempotency_key: this.buildPrintOtherReceiptIdempotencyKey(params.syncedOrder, {
+          receiptOnly: params.receiptOnly
+        }),
+        name: 'PRINT_V1',
+        source: 'server',
+        source_type: 'order',
+        source_id: printIdentity
+      });
+    } catch (error) {
+      this.logError('dispatchPrintOtherReceiptTask: 派发失败', {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  buildPrintOtherReceiptIdempotencyKey(order, options) {
+    const identity = order?.external_sale_number || order?.shop_order_number || order?.shop_full_order_number || order?.order_id;
+    if (identity === undefined || identity === null || identity === '') return undefined;
+    return `${options?.receiptOnly ? 'print_receipt' : 'print_voucher'}:${identity}:${Date.now()}`;
+  }
+  getPrintOrderIdentity(order) {
+    return order?.order_id || order?.external_sale_number || order?.shop_order_number || order?.shop_full_order_number;
+  }
+  async dispatchLocalReceiptPrint(params) {
+    if (params.requireFullyPaid && !this.isSalesOrderFullyPaid(params.order)) {
+      return {
+        printed: false,
+        order: params.order
+      };
+    }
+    const printableOrder = await this.withLocalSmallTicketData(params.order, {
+      requireFullyPaid: params.requireFullyPaid
+    });
+    if (!(0, _smallTicket.hasSmallTicketData)(printableOrder.payment_info?.small_ticket_data)) {
+      return {
+        printed: false,
+        order: printableOrder
+      };
+    }
+    this.logInfo('dispatchLocalReceiptPrint: 构建触发任务前', {
+      checkoutData: params.checkoutData,
+      printableOrder,
+      response: params.response
+    });
+    await this.dispatchPrintOtherReceiptTask({
+      checkoutData: params.checkoutData,
+      syncedOrder: printableOrder,
+      response: params.response,
+      receiptOnly: true,
+      isManualPrint: params.isManualPrint
+    });
+    return {
+      printed: true,
+      order: printableOrder
+    };
+  }
+  shouldLookupLocalPrintOrder(input) {
+    const flag = input?.lookup_order_from_db ?? input?.lookupOrderFromDb;
+    return flag === true || flag === 1 || flag === '1';
+  }
+  getLocalPrintOrderLookup(input) {
+    const orderId = input?.order_id ?? input?.orderId;
+    if (orderId !== undefined && orderId !== null && orderId !== '') return orderId;
+    const externalSaleNumber = input?.external_sale_number ?? input?.externalSaleNumber;
+    if (externalSaleNumber !== undefined && externalSaleNumber !== null && externalSaleNumber !== '') {
+      return externalSaleNumber;
+    }
+    return undefined;
+  }
+  handleLocalPrintOrder = async ({
+    data
+  }) => {
+    try {
+      const inputOrder = data?.order && typeof data.order === 'object' ? data.order : data;
+      if (!inputOrder || typeof inputOrder !== 'object') {
+        return {
+          code: 400,
+          status: false,
+          message: '订单数据不能为空',
+          data: {
+            printed: false,
+            order: null
+          }
+        };
+      }
+      const shouldLookup = this.shouldLookupLocalPrintOrder(inputOrder) || this.shouldLookupLocalPrintOrder(data);
+      this.logInfo('handleLocalPrintOrder: 是否需要查找本地订单', {
+        shouldLookup,
+        inputOrder,
+        data
+      });
+      const lookup = shouldLookup ? this.getLocalPrintOrderLookup(inputOrder) ?? this.getLocalPrintOrderLookup(data) : undefined;
+      let sourceOrder = inputOrder;
+      if (shouldLookup) {
+        if (lookup === undefined) {
+          return {
+            code: 400,
+            status: false,
+            message: '订单 lookup 缺失',
+            data: {
+              printed: false,
+              order: null
+            }
+          };
+        }
+        if (!this.order?.getLocalOrderByLookup) {
+          return {
+            code: 500,
+            status: false,
+            message: 'Order 模块未注册',
+            data: {
+              printed: false,
+              order: null
+            }
+          };
+        }
+        const localOrder = await this.order.getLocalOrderByLookup(lookup);
+        if (!localOrder) {
+          return {
+            code: 404,
+            status: false,
+            message: '订单不存在',
+            data: {
+              printed: false,
+              order: null
+            }
+          };
+        }
+        sourceOrder = {
+          ...localOrder,
+          ...inputOrder,
+          order_id: localOrder.order_id ?? inputOrder.order_id ?? inputOrder.orderId,
+          external_sale_number: localOrder.external_sale_number ?? inputOrder.external_sale_number ?? inputOrder.externalSaleNumber
+        };
+      }
+      const checkoutData = await this.ensureCheckoutOrderNumbers({
+        ...sourceOrder,
+        small_ticket_data_flag: 1
+      }, 'handleLocalPrintOrder');
+      const printableOrder = {
+        ...checkoutData,
+        need_sync: checkoutData.need_sync ?? 1
+      };
+      this.logInfo('handleLocalPrintOrder: 本地打印小票，构建触发任务前', {
+        checkoutData,
+        printableOrder
+      });
+      const printResult = await this.dispatchLocalReceiptPrint({
+        checkoutData,
+        order: printableOrder,
+        response: null,
+        requireFullyPaid: false,
+        isManualPrint: true
+      });
+      return {
+        code: 200,
+        status: true,
+        message: '',
+        data: {
+          printed: printResult.printed,
+          order: printResult.order
+        }
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logError('handleLocalPrintOrder: 本地打印小票失败', {
+        error: message
+      });
+      return {
+        code: 500,
+        status: false,
+        message,
+        data: {
+          printed: false,
+          order: null
+        }
+      };
+    }
+  };
+  handleMachinecodeBatchMeta = async ({
+    data
+  }) => {
+    const title = 'handleMachinecodeBatchMeta';
+    const backendPath = '/shop/machinecode/batch';
+    const ids = Array.isArray(data?.ids) ? data.ids : [];
+    const status = data?.status;
+    this.logInfo(`${title}: 开始处理`, {
+      backendPath,
+      batchSize: ids.length,
+      status,
+      order_lookup: this.resolveMachinecodeBatchMetadataLookup(data) ?? null
+    });
+    if (ids.length === 0) {
+      return {
+        code: 200,
+        status: true,
+        message: '',
+        data: []
+      };
+    }
+    if (status !== 'used' && status !== 'unused') {
+      return {
+        code: 400,
+        status: false,
+        message: '无效的核销状态',
+        data: null
+      };
+    }
+    try {
+      await this.syncMachinecodeRedeemStatusToLocalOrder(data, ids, status);
+    } catch (error) {
+      const message = this.getUnknownErrorMessage(error);
+      this.logError(`${title}: 本地订单核销状态更新失败`, {
+        error: message,
+        error_detail: this.normalizeUnknownError(error)
+      });
+      return {
+        code: 500,
+        status: false,
+        message,
+        data: null
+      };
+    }
+    if (!this.app?.request?.post) {
+      this.logError(`${title}: app.request 不可用`, {
+        backendPath
+      });
+      return {
+        code: 500,
+        status: false,
+        message: 'app.request 不可用',
+        data: null
+      };
+    }
+    try {
+      const response = await this.app.request.post(backendPath, {
+        ids,
+        status
+      }, {
+        isShopApi: true,
+        customToast: () => {}
+      });
+      return {
+        code: response?.code ?? 200,
+        status: response?.status ?? true,
+        message: response?.message ?? '',
+        data: response?.data ?? response
+      };
+    } catch (error) {
+      const backendError = this.extractBackendErrorResponse(error);
+      if (backendError) {
+        return {
+          code: backendError.code ?? 500,
+          status: backendError.status ?? false,
+          message: backendError.message ?? '后端拒绝 batch-metadata',
+          data: backendError.data ?? null
+        };
+      }
+      const message = this.getUnknownErrorMessage(error);
+      this.logError(`${title}: 请求失败`, {
+        backendPath,
+        error: message,
+        error_detail: this.normalizeUnknownError(error)
+      });
+      return {
+        code: 500,
+        status: false,
+        message,
+        data: null
+      };
+    }
+  };
+  resolveMachinecodeBatchMetadataLookup(data) {
+    const candidates = [data?.order_lookup, data?.orderLookup, data?.external_sale_number, data?.externalSaleNumber, data?.order_id, data?.orderId, data?.order_number, data?.orderNumber, data?.shop_order_number, data?.shopOrderNumber, data?.shop_full_order_number, data?.shopFullOrderNumber];
+    return candidates.find(candidate => candidate !== undefined && candidate !== null && candidate !== '');
+  }
+  async syncMachinecodeRedeemStatusToLocalOrder(data, ids, status) {
+    const title = 'handleMachinecodeBatchMetadata';
+    const lookup = this.resolveMachinecodeBatchMetadataLookup(data);
+    if (lookup === undefined) {
+      this.logWarning(`${title}: order lookup 缺失，跳过本地订单核销状态更新`, {
+        batchSize: ids.length,
+        status
+      });
+      return;
+    }
+    if (!this.order?.getLocalOrderByLookup) {
+      this.logWarning(`${title}: Order 模块未注册，跳过本地订单核销状态更新`, {
+        lookup,
+        status
+      });
+      return;
+    }
+    const localOrder = await this.order.getLocalOrderByLookup(lookup);
+    if (!localOrder) {
+      this.logWarning(`${title}: 本地订单不存在，跳过核销状态更新`, {
+        lookup,
+        status
+      });
+      return;
+    }
+    const voucherIdSet = new Set(ids.filter(id => id !== undefined && id !== null && id !== '').map(id => String(id)));
+    if (voucherIdSet.size === 0) {
+      this.logWarning(`${title}: voucher ids 缺失，跳过本地订单核销状态更新`, {
+        lookup,
+        status
+      });
+      return;
+    }
+    const vouchers = Array.isArray(localOrder.vouchers) ? localOrder.vouchers : [];
+    let hasUpdatedVoucher = false;
+    const nextVouchers = vouchers.map(voucher => {
+      const voucherId = voucher?.voucher_id;
+      if (voucherId === undefined || voucherId === null) return voucher;
+      if (!voucherIdSet.has(String(voucherId))) return voucher;
+      hasUpdatedVoucher = true;
+      return {
+        ...voucher,
+        status
+      };
+    });
+    if (!hasUpdatedVoucher) {
+      this.logWarning(`${title}: 本地订单未命中任何 voucher，跳过核销状态更新`, {
+        lookup,
+        voucher_ids: Array.from(voucherIdSet),
+        status
+      });
+      return;
+    }
+    if (typeof this.order.overwriteExistingOrder === 'function') {
+      await this.order.overwriteExistingOrder({
+        ...localOrder,
+        vouchers: nextVouchers
+      });
+      this.logInfo(`${title}: 本地订单 vouchers 核销状态已更新`, {
+        lookup,
+        updatedCount: voucherIdSet.size,
+        status
+      });
+      return;
+    }
+    if (data?.external_sale_number && typeof this.order.markOrderSyncedByExternalSaleNumber === 'function') {
+      await this.order.markOrderSyncedByExternalSaleNumber({
+        externalSaleNumber: data.external_sale_number,
+        patch: {
+          vouchers: nextVouchers
+        }
+      });
+      this.logInfo(`${title}: 本地订单 vouchers 核销状态已更新`, {
+        lookup,
+        updatedCount: voucherIdSet.size,
+        status
+      });
+      return;
+    }
+    this.logWarning(`${title}: Order 模块不支持本地订单覆盖，跳过核销状态更新`, {
+      lookup,
+      status
+    });
+  }
+  async handleOrderCheckoutSubmit(params) {
+    const {
+      backendPath,
+      data,
+      title
+    } = params;
+    this.logInfo(`${title}: 开始处理`, {
+      backendPath,
+      order_id: data?.order_id,
+      external_sale_number: data?.external_sale_number,
+      order_number: data?.order_number
+    });
+    if (data?.sync_mode || data?.syncMode) {
+      return this.handleSyncCheckoutSubmit({
+        backendPath,
+        data,
+        title
+      });
+    }
+    const normalizedData = await this.normalizeCheckoutSubmitData(data, title);
+    const checkoutData = await this.ensureCheckoutOrderNumbers(normalizedData, title);
+    const pendingResult = await this.handlePendingSyncCheckoutOrder({
+      backendPath,
+      data: checkoutData,
+      title,
+      reason: 'checkout 已转入设备任务同步'
+    });
+    if (pendingResult?.status === true) {
+      const pendingOrder = pendingResult.data;
+      const platform = this.core.context?.getPlatform();
+      const isAndroid = platform === 'android';
+      if (pendingOrder && this.shouldBuildSmallTicketData(checkoutData) && this.isSalesOrderFullyPaid(pendingOrder) && (
+      // TODO 这里先加个兼容，如果是安卓，则需要 type=virtual 才走打印，如果是苹果则无限制
+      isAndroid ? checkoutData.type === 'virtual' : true)) {
+        await this.dispatchLocalReceiptPrint({
+          checkoutData,
+          order: pendingOrder,
+          response: pendingResult,
+          requireFullyPaid: true
+        });
+      }
+      await this.dispatchCheckoutSyncTask({
+        backendPath,
+        data: checkoutData,
+        title
+      });
+    }
+    if (!pendingResult.data.order_id) {
+      return {
+        ...pendingResult,
+        data: {
+          ...pendingResult.data,
+          order_id: pendingResult.data.external_sale_number
+        }
+      };
+    }
+    return pendingResult;
+  }
+  async handleSyncCheckoutSubmit(params) {
+    const {
+      backendPath,
+      data,
+      title
+    } = params;
+    if (!this.app?.request?.post) {
+      this.logError(`${title}: sync checkout app.request 不可用`);
+      return {
+        code: 500,
+        status: false,
+        message: 'app.request 不可用',
+        data: null
+      };
+    }
+    try {
+      const syncResult = await this.runCheckoutSync({
+        backendPath,
+        data,
+        title,
+        persistCheckoutDataWithResponse: true
+      });
+      if (syncResult.rejected) {
+        const normalized = this.normalizeCheckoutResponse(syncResult.errorResponse);
+        return {
+          ...normalized,
+          status: false,
+          message: syncResult.message || normalized?.message || '后端明确拒绝 checkout',
+          data: normalized?.data ?? null
+        };
+      }
+      const response = this.withSyncedOrderIdInCheckoutResponse(syncResult.normalizedResponse, syncResult.syncedOrder);
+      const syncedOrder = syncResult.syncedOrder;
+      if (syncedOrder && this.shouldBuildSmallTicketData(syncResult.checkoutData) && this.isSalesOrderFullyPaid(syncedOrder)) {
+        await this.dispatchLocalReceiptPrint({
+          checkoutData: syncResult.checkoutData,
+          order: syncedOrder,
+          response: syncResult.normalizedResponse,
+          requireFullyPaid: true,
+          // print_all 的 type=0 是收据打印；不要沿用同步成功后的券/手环打印 type=99。
+          isManualPrint: true
+        });
+      }
+      return response;
+    } catch (error) {
+      const backendError = this.extractBackendErrorResponse(error);
+      if (backendError) {
+        const normalized = this.normalizeCheckoutResponse(backendError);
+        return {
+          ...normalized,
+          status: false,
+          message: backendError?.message || normalized?.message || '后端明确拒绝 checkout',
+          data: normalized?.data ?? null
+        };
+      }
+      const message = this.getUnknownErrorMessage(error);
+      this.logError(`${title}: sync checkout 请求未明确成功`, {
+        backendPath,
+        error: message,
+        error_detail: this.normalizeUnknownError(error)
+      });
+      return {
+        code: 500,
+        status: false,
+        message,
+        data: null
+      };
+    }
+  }
+  async handlePendingSyncCheckoutOrder(params) {
+    const {
+      backendPath,
+      data,
+      title,
+      reason
+    } = params;
+    const pendingOrder = await this.buildPendingSyncCheckoutOrder(data);
+    if (!pendingOrder) {
+      this.logError(`${title}: checkout 失败且订单缺少本地存储标识`, {
+        backendPath,
+        reason
+      });
+      return {
+        code: 500,
+        status: false,
+        message: '订单缺少本地存储标识，无法写入待同步队列',
+        data: null
+      };
+    }
+    if (!this.order || typeof this.order.upsertPendingSyncOrders !== 'function') {
+      this.logError(`${title}: Order 模块不支持本地待同步写入`, {
+        backendPath,
+        reason
+      });
+      return {
+        code: 500,
+        status: false,
+        message: 'Order 模块不支持本地待同步写入',
+        data: null
+      };
+    }
+    try {
+      await this.order.upsertPendingSyncOrders([pendingOrder]);
+      this.logInfo(`${title}: 订单已写入本地待同步`, {
+        backendPath,
+        reason,
+        order_id: pendingOrder.order_id,
+        external_sale_number: pendingOrder.external_sale_number,
+        order_number: pendingOrder.order_number
+      });
+      const changeGivenAmount = pendingOrder?.payments?.reduce((sum, payment) => sum + this.toAmountNumber(payment?.metadata?.change_given_amount), 0);
+      return {
+        code: 200,
+        status: true,
+        message: '',
+        data: {
+          ...pendingOrder,
+          amount_gap: pendingOrder?.summary?.amount_gap,
+          expect_amount: pendingOrder?.summary?.expect_amount,
+          total_amount: pendingOrder?.summary?.total_amount,
+          payment_status: pendingOrder?.payment_status,
+          payment_info: {
+            ...(pendingOrder?.payment_info || {}),
+            current_change_given_amount: changeGivenAmount
+          }
+        }
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logError(`${title}: 写入本地待同步订单失败`, {
+        backendPath,
+        reason,
+        error: errorMessage
+      });
+      return {
+        code: 500,
+        status: false,
+        message: errorMessage,
+        data: null
+      };
+    }
+  }
+  async buildPendingSyncCheckoutOrder(data) {
+    if (!data || typeof data !== 'object') return null;
+    const hasStorageKey = data.external_sale_number !== undefined && data.external_sale_number !== null && data.external_sale_number !== '' ? true : data.order_id !== undefined && data.order_id !== null && data.order_id !== '';
+    if (!hasStorageKey) return null;
+    const pendingOrder = {
+      ...data,
+      need_sync: 1
+    };
+    const productMap = await this.buildSmallTicketProductMap(pendingOrder);
+    const orderWithProductTitles = this.withPendingSyncProductTitles(pendingOrder, productMap);
+    return this.withLocalSmallTicketData(orderWithProductTitles, {
+      requireFullyPaid: true,
+      productMap
+    });
+  }
+  shouldBuildSmallTicketData(order) {
+    if (!order || typeof order !== 'object') return false;
+    // if (hasSmallTicketData(order.payment_info?.small_ticket_data)) return false;
+    return Number(order.small_ticket_data_flag ?? order.smallTicketDataFlag ?? 0) === 1;
+  }
+  shouldPrintSyncedOrder(params) {
+    if (this.hasPaymentStatus(params.syncedOrder)) {
+      return this.isSalesOrderFullyPaid(params.syncedOrder);
+    }
+    return this.isSalesOrderFullyPaid(params.checkoutData);
+  }
+  hasPaymentStatus(order) {
+    return order?.payment_status !== undefined && order?.payment_status !== null && order?.payment_status !== '';
+  }
+  isSalesOrderFullyPaid(order) {
+    if (!order || typeof order !== 'object') return false;
+    const paymentStatus = String(order.payment_status || '').toLowerCase();
+    if (paymentStatus === 'paid' || paymentStatus === 'finished') return true;
+    if (paymentStatus === 'partially_paid' || paymentStatus === 'payment_processing' || paymentStatus === 'pending' || paymentStatus === 'unpaid') {
+      return false;
+    }
+    const amountGap = order.summary?.amount_gap ?? order.amount_gap;
+    if (amountGap !== undefined && amountGap !== null && amountGap !== '') {
+      return this.toAmountNumber(amountGap) <= 0;
+    }
+    const paidAmount = this.sumPaidOrderPayments(order.payments);
+    const targetAmount = this.toAmountNumber(order.summary?.expect_amount ?? order.summary?.total_amount ?? order.expect_amount ?? order.total_amount);
+    if (targetAmount <= 0) return paidAmount > 0;
+    return paidAmount >= targetAmount;
+  }
+  sumPaidOrderPayments(payments) {
+    if (!Array.isArray(payments)) return 0;
+    return payments.reduce((sum, payment) => {
+      const status = String(payment?.status || '').toLowerCase();
+      if (status === 'voided' || status === 'failed' || status === 'cancelled') return sum;
+      return sum + this.toAmountNumber(payment?.amount ?? payment?.origin_amount);
+    }, 0);
+  }
+  toAmountNumber(value) {
+    if (typeof value === 'number') return Number.isFinite(value) ? value : 0;
+    if (typeof value !== 'string') return 0;
+    const parsed = Number(value.replace(/[^\d.-]/g, ''));
+    return Number.isFinite(parsed) ? parsed : 0;
+  }
+  async buildSmallTicketProductMap(order) {
+    const products = Array.isArray(order?.products) ? order.products : [];
+    const productIdSet = new Set();
+    products.forEach(product => {
+      const productId = product?.product_id ?? product?.id;
+      if (productId !== undefined && productId !== null && productId !== '') {
+        productIdSet.add(productId);
+      }
+      if (Array.isArray(product?.product_bundle)) {
+        product.product_bundle.forEach(bundle => {
+          const bundleProductId = bundle?.bundle_product_id ?? bundle?._bundle_product_id ?? bundle?.product_id;
+          if (bundleProductId !== undefined && bundleProductId !== null && bundleProductId !== '') {
+            productIdSet.add(bundleProductId);
+          }
+        });
+      }
+    });
+    const productIds = Array.from(productIdSet);
+    if (!productIds.length || typeof this.products?.getProductById !== 'function') return {};
+    const entries = await Promise.all(productIds.map(async id => {
+      try {
+        const product = await this.products?.getProductById?.(Number(id));
+        return product ? [String(id), product] : null;
+      } catch (error) {
+        this.logWarning('buildSmallTicketProductMap: 查询本地商品失败', {
+          product_id: id,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        return null;
+      }
+    }));
+    return entries.reduce((map, entry) => {
+      if (!entry) return map;
+      const [id, product] = entry;
+      map[id] = product;
+      return map;
+    }, {});
+  }
+  collectSalesDetailProductIds(order) {
+    const products = Array.isArray(order?.products) ? order.products : [];
+    const productIds = new Set();
+    const addProductId = rawProductId => {
+      if (rawProductId === undefined || rawProductId === null || rawProductId === '') return;
+      const productId = Number(rawProductId);
+      if (Number.isFinite(productId)) productIds.add(productId);
+    };
+    products.forEach(product => {
+      addProductId(product?.product_id ?? product?.id);
+      if (Array.isArray(product?.product_bundle)) {
+        product.product_bundle.forEach(bundle => {
+          addProductId(bundle?.bundle_product_id ?? bundle?._bundle_product_id ?? bundle?.product_id);
+        });
+      }
+    });
+    return Array.from(productIds);
+  }
+  async buildSalesDetailProductSnapshotMap(order) {
+    const productIds = this.collectSalesDetailProductIds(order);
+    const getSnapshots = this.products?.getProductSnapshotsByIds;
+    if (!productIds.length || typeof getSnapshots !== 'function') return {};
+    try {
+      return await getSnapshots.call(this.products, productIds);
+    } catch (error) {
+      this.logWarning('buildSalesDetailProductSnapshotMap: 查询本地商品快照失败', {
+        product_ids: productIds,
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return {};
+    }
+  }
+  withProductCatalogSnapshots(product, snapshotMap) {
+    if (!product || typeof product !== 'object') return product;
+    const rawProductId = product?.product_id ?? product?.id;
+    if (rawProductId === undefined || rawProductId === null || rawProductId === '') return product;
+    const productId = Number(rawProductId);
+    if (!Number.isFinite(productId)) return product;
+    const snapshot = snapshotMap[String(productId)];
+    if (!snapshot) return product;
+    const shouldFillCover = (product.product_cover === undefined || product.product_cover === null || product.product_cover === '') && snapshot.cover !== undefined && snapshot.cover !== null && snapshot.cover !== '';
+    const metadata = product.metadata && typeof product.metadata === 'object' ? product.metadata : {};
+    const shouldFillHolderConfig = (metadata.holder_config === undefined || metadata.holder_config === null) && snapshot.holder_config !== undefined && snapshot.holder_config !== null;
+    if (!shouldFillCover && !shouldFillHolderConfig) return product;
+    return {
+      ...product,
+      ...(shouldFillCover ? {
+        product_cover: snapshot.cover
+      } : {}),
+      ...(shouldFillHolderConfig ? {
+        metadata: {
+          ...metadata,
+          holder_config: snapshot.holder_config
+        }
+      } : {})
+    };
+  }
+  withBundleCatalogSnapshots(product, snapshotMap) {
+    if (!Array.isArray(product?.product_bundle)) return product;
+    let hasChanged = false;
+    const productBundle = product.product_bundle.map(bundle => {
+      if (!bundle || typeof bundle !== 'object') return bundle;
+      const rawProductId = bundle?.bundle_product_id ?? bundle?._bundle_product_id ?? bundle?.product_id;
+      if (rawProductId === undefined || rawProductId === null || rawProductId === '') return bundle;
+      const productId = Number(rawProductId);
+      if (!Number.isFinite(productId)) return bundle;
+      const snapshot = snapshotMap[String(productId)];
+      const shouldFillCover = (bundle.cover === undefined || bundle.cover === null || bundle.cover === '') && snapshot?.cover !== undefined && snapshot.cover !== null && snapshot.cover !== '';
+      if (!shouldFillCover) return bundle;
+      hasChanged = true;
+      return {
+        ...bundle,
+        cover: snapshot.cover
+      };
+    });
+    if (!hasChanged) return product;
+    return {
+      ...product,
+      product_bundle: productBundle
+    };
+  }
+  async withSalesDetailProductSnapshots(order) {
+    const products = Array.isArray(order?.products) ? order.products : null;
+    if (!products?.length) return order;
+    const snapshotMap = await this.buildSalesDetailProductSnapshotMap(order);
+    if (!Object.keys(snapshotMap).length) return order;
+    let hasChanged = false;
+    const enrichedProducts = products.map(product => {
+      const productWithBundleSnapshots = this.withBundleCatalogSnapshots(product, snapshotMap);
+      const nextProduct = this.withProductCatalogSnapshots(productWithBundleSnapshots, snapshotMap);
+      if (nextProduct !== product) hasChanged = true;
+      return nextProduct;
+    });
+    if (!hasChanged) return order;
+    const enrichedOrder = {
+      ...order,
+      products: enrichedProducts
+    };
+    return enrichedOrder;
+  }
+  withPendingSyncProductTitles(order, productMap) {
+    const products = Array.isArray(order.products) ? order.products : null;
+    if (!products?.length) return order;
+    return {
+      ...order,
+      products: products.map(product => ({
+        ...product,
+        product_title: this.buildProductTitleSnapshot(product, productMap)
+      }))
+    };
+  }
+  buildProductTitleSnapshot(product, productMap) {
+    const productId = product.product_id ?? product.id;
+    const fallbackProduct = productId !== undefined && productId !== null ? productMap[productId] || productMap[String(productId)] : null;
+    const ownTitle = product.product_title || product.title || product.name || product.product?.title;
+    const fallbackTitle = fallbackProduct?.product_title || fallbackProduct?.title || fallbackProduct?.name || fallbackProduct?.format_title || fallbackProduct?.product?.title;
+    const currentLocale = this.getProductTitleSnapshotCurrentLocale();
+    const autoTitle = this.resolveFirstProductTitleValue(ownTitle) || this.resolveFirstProductTitleValue(fallbackTitle);
+    return PRODUCT_TITLE_SNAPSHOT_KEYS.reduce((snapshot, key) => {
+      snapshot[key] = this.resolveProductTitleValue(ownTitle, key, currentLocale) || this.resolveProductTitleValue(fallbackTitle, key, currentLocale) || (key === 'auto' || key === 'original' ? autoTitle : null);
+      return snapshot;
+    }, {});
+  }
+  getProductTitleSnapshotCurrentLocale() {
+    const shopInfo = this.getSmallTicketShopInfo();
+    const rawLocale = shopInfo.primary_locale || this.getAppData('locale') || this.getAppData('language') || this.core.context?.locale || this.core.context?.language;
+    return this.normalizeProductTitleSnapshotLocale(rawLocale);
+  }
+  normalizeProductTitleSnapshotLocale(value) {
+    if (typeof value !== 'string' || !value) return null;
+    const normalized = value.replace('_', '-');
+    const matchedKey = PRODUCT_TITLE_SNAPSHOT_KEYS.find(key => key === normalized);
+    return matchedKey ?? null;
+  }
+  resolveProductTitleValue(value, key, currentLocale) {
+    if (value === undefined || value === null || value === '') return null;
+    if (typeof value !== 'object') {
+      const title = String(value);
+      if (key === 'auto' || key === 'original') return title;
+      if (key === currentLocale && this.canAssignStringProductTitleToLocale(title, currentLocale)) return title;
+      return null;
+    }
+    const normalizedKey = key.replace('-', '_');
+    const dashedKey = key.replace('_', '-');
+    const rawValue = value[key] ?? value[normalizedKey] ?? value[dashedKey] ?? (key === 'auto' ? value.default : undefined);
+    if (rawValue === undefined || rawValue === null || rawValue === '') return null;
+    if (typeof rawValue === 'object') return this.resolveFirstProductTitleValue(rawValue);
+    return String(rawValue);
+  }
+  canAssignStringProductTitleToLocale(title, locale) {
+    if (!locale) return false;
+    if (locale === 'zh-CN' || locale === 'zh-HK' || locale === 'kitchen') {
+      return this.hasCjkText(title);
+    }
+    if (locale === 'ja') return /[\u3040-\u30ff]/.test(title) || this.hasCjkText(title);
+    if (locale === 'en' || locale === 'pt') return !this.hasCjkText(title);
+    return false;
+  }
+  hasCjkText(value) {
+    return /[\u3400-\u9fff]/.test(value);
+  }
+  resolveFirstProductTitleValue(value) {
+    if (value === undefined || value === null || value === '') return null;
+    if (typeof value !== 'object') return String(value);
+    const preferredKeys = ['auto', 'en', 'original', 'zh-CN', 'zh_CN', 'zh-HK', 'zh_HK', 'kitchen', 'ja', 'pt', 'default'];
+    for (const key of preferredKeys) {
+      const rawValue = value[key];
+      if (rawValue !== undefined && rawValue !== null && rawValue !== '') return String(rawValue);
+    }
+    const firstValue = Object.values(value).find(item => item !== undefined && item !== null && item !== '');
+    return firstValue === undefined ? null : String(firstValue);
+  }
+  getPaymentCodeKey(code) {
+    if (code === undefined || code === null) return '';
+    return String(code).trim().toUpperCase();
+  }
+  isBlankPaymentName(name) {
+    if (name === undefined || name === null) return true;
+    if (typeof name === 'string') return name.trim() === '';
+    return false;
+  }
+  shouldLookupPaymentMethodNameByCode(code) {
+    const codeKey = this.getPaymentCodeKey(code);
+    if (!codeKey) return false;
+    const builtInNameTokens = ['CASH', 'EFTPOS', 'CARD', 'WALLET', 'GIFT'];
+    return !builtInNameTokens.some(token => codeKey.includes(token));
+  }
+  async enrichPaymentNamesByCode(order) {
+    const payments = Array.isArray(order?.payments) ? order.payments : [];
+    const hasMissingName = payments.some(payment => this.isBlankPaymentName(payment?.name) && this.shouldLookupPaymentMethodNameByCode(payment?.code));
+    if (!hasMissingName) return order;
+    try {
+      const paymentModule = await this.getPaymentRouteModule();
+      const payMethods = await paymentModule.getPayMethodListAsync();
+      const nameByCode = new Map();
+      for (const method of payMethods || []) {
+        const codeKey = this.getPaymentCodeKey(method?.code);
+        const name = this.resolveFirstProductTitleValue(method?.name);
+        if (codeKey && name) nameByCode.set(codeKey, name);
+      }
+      let hasResolvedName = false;
+      const enrichedPayments = payments.map(payment => {
+        if (!this.isBlankPaymentName(payment?.name)) return payment;
+        if (!this.shouldLookupPaymentMethodNameByCode(payment?.code)) return payment;
+        const name = nameByCode.get(this.getPaymentCodeKey(payment?.code));
+        if (!name) return payment;
+        hasResolvedName = true;
+        return {
+          ...payment,
+          name
+        };
+      });
+      if (!hasResolvedName) return order;
+      return {
+        ...order,
+        payments: enrichedPayments
+      };
+    } catch (error) {
+      this.logWarning('enrichPaymentNamesByCode: 支付方式名称回填失败', {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return order;
+    }
+  }
+  async withLocalSmallTicketData(order, options) {
+    if (!this.shouldBuildSmallTicketData(order)) return order;
+    if (options?.requireFullyPaid && !this.isSalesOrderFullyPaid(order)) return order;
+    try {
+      const enrichedOrder = await this.enrichPaymentNamesByCode(order);
+      const productMap = options?.productMap ?? (await this.buildSmallTicketProductMap(enrichedOrder));
+      const smallTicketData = (0, _smallTicket.buildSmallTicketData)({
+        order: enrichedOrder,
+        shopInfo: this.getSmallTicketShopInfo(),
+        productMap
+      });
+      return {
+        ...enrichedOrder,
+        payment_info: {
+          ...(enrichedOrder.payment_info || {}),
+          small_ticket_data: smallTicketData
+        }
+      };
+    } catch (error) {
+      this.logError('withLocalSmallTicketData: 生成本地小票数据失败', {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return order;
+    }
+  }
+  handleOrderSalesDetail = async ({
+    url,
+    data,
+    path
+  }) => {
+    const requestPath = this.parseRequestPath(url, path);
+    const lookup = this.extractOrderSalesDetailLookup(requestPath);
+    this.logInfo('handleOrderSalesDetail: 开始处理', {
+      url,
+      path: requestPath,
+      lookup
+    });
+    if (!lookup) {
+      this.logWarning('handleOrderSalesDetail: lookup 缺失', {
+        url,
+        path: requestPath
+      });
+      return {
+        code: 400,
+        status: false,
+        message: '订单 lookup 缺失',
+        data: null
+      };
+    }
+    if (!this.order) {
+      this.logError('handleOrderSalesDetail: Order 模块未注册');
+      return {
+        code: 500,
+        status: false,
+        message: 'Order 模块未注册',
+        data: null
+      };
+    }
+    if (!this.shouldForceRemoteSalesDetail(data)) {
+      const localOrder = await this.order.getLocalOrderByLookup(lookup);
+      if (localOrder) {
+        const enrichedOrder = await this.withSalesDetailProductSnapshots(localOrder);
+        this.logInfo('handleOrderSalesDetail: 命中本地订单', {
+          lookup
+        });
+        return {
+          code: 200,
+          status: true,
+          message: '',
+          data: enrichedOrder
+        };
+      }
+    }
+    if (!this.app?.request) {
+      this.logError('handleOrderSalesDetail: app.request 不可用');
+      return {
+        code: 500,
+        status: false,
+        message: 'app.request 不可用',
+        data: null
+      };
+    }
+    const backendPath = this.buildOrderSalesDetailBackendPath(lookup, data);
+    try {
+      const response = await this.app.request.get(backendPath, {
+        lookup_mode: 'multi'
+      }, {
+        isShopApi: true,
+        customToast: () => {}
+      });
+      const fresh = response?.data ?? response;
+      if (!fresh || typeof fresh !== 'object' || fresh.order_id == null) {
+        this.logInfo('handleOrderSalesDetail: 后端返回订单为空', {
+          lookup,
+          backendPath
+        });
+        return {
+          code: 500,
+          status: false,
+          message: '后端返回订单为空',
+          data: null
+        };
+      }
+      await this.order.upsertOrdersFromRemote([fresh]);
+      const savedOrder = await this.order.getLocalOrderByLookup(lookup);
+      if (!savedOrder) {
+        this.logError('handleOrderSalesDetail: 订单写入后回读失败', {
+          lookup
+        });
+        return {
+          code: 500,
+          status: false,
+          message: '订单写入后回读失败',
+          data: null
+        };
+      }
+      this.logInfo('handleOrderSalesDetail: 远端订单已同步到本地', {
+        lookup
+      });
+      const enrichedOrder = await this.withSalesDetailProductSnapshots(savedOrder);
+      return {
+        code: 200,
+        status: true,
+        message: '',
+        data: enrichedOrder
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logInfo('handleOrderSalesDetail: 请求失败', {
+        lookup,
+        backendPath,
+        error: errorMessage
+      });
+      return {
+        code: 500,
+        status: false,
+        message: errorMessage,
+        data: null
+      };
+    }
+  };
+
+  /**
+   * 解析 order_ids 入参，兼容 url query / data 字段、字符串(csv) / 数组两种形态。
+   * 自动 trim、去空、按字符串去重，输出归一化后的字符串数组。
+   *
+   * @example
+   * // url: /update/localOrder?order_ids=1,2,2,, → ['1','2']
+   * this.parseOrderIdsParam(url, undefined)
+   *
+   * @example
+   * // data: { order_ids: [1, '2', null] } → ['1','2']
+   * this.parseOrderIdsParam('', { order_ids: [1, '2', null] })
+   */
+  parseOrderIdsParam(url, data) {
+    const collected = [];
+    const pushRaw = raw => {
+      if (raw === undefined || raw === null) return;
+      if (Array.isArray(raw)) {
+        raw.forEach(pushRaw);
+        return;
+      }
+      const str = String(raw).trim();
+      if (!str) return;
+      // csv 兼容：单个字符串值里也允许逗号分隔
+      str.split(',').forEach(piece => {
+        const v = piece.trim();
+        if (v) collected.push(v);
+      });
+    };
+    if (data && typeof data === 'object') {
+      pushRaw(data.order_ids);
+    }
+    pushRaw(this.extractQueryParam(url, 'order_ids'));
+    const seen = new Set();
+    const result = [];
+    for (const id of collected) {
+      if (seen.has(id)) continue;
+      seen.add(id);
+      result.push(id);
+    }
+    return result;
+  }
+
+  /**
+   * 批量代理刷新 / 合并订单到本地：并发拉详情 → 单次合并 → 单次 emit。
+   * - 单笔失败不影响其他成功项
+   * - 没有任何成功项时不触发 emit / 落库
+   *
+   * @example
+   * await this.handleUpdateLocalOrdersBatch(['96971', '96972'])
+   */
+  async handleUpdateLocalOrdersBatch(orderIds) {
+    this.logInfo('handleUpdateLocalOrdersBatch: 开始处理', {
+      count: orderIds.length,
+      orderIds
+    });
+    if (!this.order) {
+      this.logError('handleUpdateLocalOrdersBatch: Order 模块未注册');
+      return {
+        code: 500,
+        status: false,
+        message: 'Order 模块未注册',
+        data: null
+      };
+    }
+    if (!this.app?.request) {
+      this.logError('handleUpdateLocalOrdersBatch: app.request 不可用');
+      return {
+        code: 500,
+        status: false,
+        message: 'app.request 不可用',
+        data: null
+      };
+    }
+
+    // 拉取前先记录"本地是否已存在"，用于区分 overwritten / inserted
+    const existedBefore = new Map();
+    for (const id of orderIds) {
+      existedBefore.set(id, !!this.order.getOrderByOrderId(id));
+    }
+
+    // 走 orderDataSource 的批量 HTTP 通道，一次请求拉回多笔详情
+    let fetched = [];
+    try {
+      fetched = await this.order.fetchOrdersByHttp(orderIds);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logError('handleUpdateLocalOrdersBatch: 批量拉取失败', {
+        message
+      });
+      return {
+        code: 500,
+        status: false,
+        message,
+        data: null
+      };
+    }
+
+    // 按返回结果中的 order_id 建索引，未命中即视为单笔失败
+    const fetchedMap = new Map();
+    for (const order of fetched) {
+      const oid = order?.order_id;
+      if (oid === undefined || oid === null) continue;
+      fetchedMap.set(String(oid), order);
+    }
+    const freshOrders = [];
+    const succeedIds = [];
+    const failed = [];
+    for (const id of orderIds) {
+      const fresh = fetchedMap.get(id);
+      if (fresh) {
+        freshOrders.push(fresh);
+        succeedIds.push(id);
+      } else {
+        failed.push({
+          order_id: id,
+          message: '后端未返回该订单详情'
+        });
+      }
+    }
+    if (freshOrders.length > 0) {
+      try {
+        // 单次合并：内部完成 store 更新 + SQLite 落库 + 仅 emit 一次 onOrdersChanged
+        await this.order.upsertOrdersFromRemote(freshOrders);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.logError('handleUpdateLocalOrdersBatch: 合并写入失败', {
+          message
+        });
+        return {
+          code: 500,
+          status: false,
+          message,
+          data: null
+        };
+      }
+    }
+    const overwritten = succeedIds.filter(id => existedBefore.get(id));
+    const inserted = succeedIds.filter(id => !existedBefore.get(id));
+    this.logInfo('handleUpdateLocalOrdersBatch: 完成', {
+      total: orderIds.length,
+      overwrittenCount: overwritten.length,
+      insertedCount: inserted.length,
+      failedCount: failed.length
+    });
+    return {
+      code: 200,
+      status: true,
+      message: '',
+      data: {
+        overwritten,
+        inserted,
+        failed
+      }
+    };
+  }
+
+  /**
+   * 从 url 中解析指定 query 参数，兼容相对路径与绝对路径
+   */
+  extractQueryParam(url, key) {
+    if (!url) return null;
+    try {
+      const target = url.startsWith('http') ? new URL(url) : new URL(url, 'http://placeholder.local');
+      const value = target.searchParams.get(key);
+      return value ?? null;
+    } catch {
+      const queryIndex = url.indexOf('?');
+      if (queryIndex < 0) return null;
+      const query = url.slice(queryIndex + 1);
+      for (const pair of query.split('&')) {
+        if (!pair) continue;
+        const [rawKey, rawValue = ''] = pair.split('=');
+        try {
+          if (decodeURIComponent(rawKey) === key) {
+            return decodeURIComponent(rawValue);
+          }
+        } catch {
+          if (rawKey === key) return rawValue;
+        }
+      }
+      return null;
+    }
+  }
+  extractOrderSalesDetailLookup(url) {
+    const path = this.parseRequestPath(url);
+    const match = path.match(/^\/shop\/order\/sales\/([^/?#]+)$/);
+    return match?.[1] ? decodeURIComponent(match[1]) : null;
+  }
+  shouldForceRemoteSalesDetail(data) {
+    return data?.forceRemote === true || data?.force_remote === true;
+  }
+  buildOrderSalesDetailBackendPath(lookup, data) {
+    const rawWith = data && typeof data === 'object' ? data.with : undefined;
+    const withFields = Array.isArray(rawWith) && rawWith.length > 0 ? rawWith : ['products', 'scheduleEvents'];
+    const searchParams = new URLSearchParams();
+    withFields.forEach(field => {
+      if (field === undefined || field === null || field === '') return;
+      searchParams.append('with[]', String(field));
+    });
+    searchParams.append('lookup_mode', 'multi');
+    const query = searchParams.toString();
+    return `/shop/order/sales/${encodeURIComponent(lookup)}${query ? `?${query}` : ''}`;
+  }
+  extractOrderDataFromCheckoutResponse(response) {
+    const candidates = [response?.data?.order, response?.data?.sales, response?.data, response?.order, response?.sales, response];
+    for (const candidate of candidates) {
+      if (!candidate || typeof candidate !== 'object') continue;
+      if (candidate.order_id !== undefined && candidate.order_id !== null) {
+        return candidate;
+      }
+    }
+    return null;
+  }
+  getCheckoutExternalSaleNumber(data, payload) {
+    const candidates = [payload?.external_sale_number, data?.external_sale_number, payload?.data?.external_sale_number];
+    const value = candidates.find(candidate => candidate !== undefined && candidate !== null && candidate !== '');
+    return value === undefined ? undefined : String(value);
+  }
+  buildCheckoutSyncSuccessPatch(fresh) {
+    if (!fresh) return {};
+    const patch = {};
+    if (fresh.order_id !== undefined && fresh.order_id !== null) patch.order_id = fresh.order_id;
+    if (fresh.order_number !== undefined && fresh.order_number !== null) {
+      patch.order_number = fresh.order_number;
+    }
+    return patch;
+  }
+  buildSyncedOrderForPrint(params) {
+    const {
+      syncedOrder,
+      checkoutResponseOrder
+    } = params;
+    if (!checkoutResponseOrder || typeof checkoutResponseOrder !== 'object') return syncedOrder;
+    const printableOrder = {
+      ...syncedOrder
+    };
+    const responseOrder = checkoutResponseOrder;
+    if (responseOrder.order_id !== undefined && responseOrder.order_id !== null) {
+      printableOrder.order_id = responseOrder.order_id;
+    }
+    if (responseOrder.payment_status !== undefined && responseOrder.payment_status !== null) {
+      printableOrder.payment_status = responseOrder.payment_status;
+    }
+    if (responseOrder.expect_amount !== undefined && responseOrder.expect_amount !== null) {
+      printableOrder.expect_amount = responseOrder.expect_amount;
+    }
+    if (responseOrder.machine_code_print_info_v2 !== undefined) {
+      printableOrder.machine_code_print_info_v2 = responseOrder.machine_code_print_info_v2;
+    }
+    if (responseOrder.payment_info && typeof responseOrder.payment_info === 'object') {
+      printableOrder.payment_info = {
+        ...(syncedOrder.payment_info || {}),
+        ...responseOrder.payment_info
+      };
+    }
+    return printableOrder;
+  }
+  isMergeableCheckoutOrder(order, externalSaleNumber) {
+    if (!order || typeof order !== 'object') return false;
+    const orderExternalSaleNumber = order.external_sale_number;
+    if (externalSaleNumber && orderExternalSaleNumber !== undefined && orderExternalSaleNumber !== null && String(orderExternalSaleNumber) !== externalSaleNumber) {
+      return false;
+    }
+    if (externalSaleNumber && (orderExternalSaleNumber === undefined || orderExternalSaleNumber === null || orderExternalSaleNumber === '')) {
+      return false;
+    }
+    return Array.isArray(order.products) || Array.isArray(order.bookings) || Array.isArray(order.payments) || !!order.summary || order.order_number !== undefined || order.payment_status !== undefined || order.status !== undefined;
+  }
+  normalizeCheckoutResponse(response) {
+    if (response && typeof response === 'object' && (response.code !== undefined || response.status !== undefined)) {
+      return response;
+    }
+    return {
+      code: 200,
+      status: true,
+      message: '',
+      data: response
+    };
+  }
+  withSyncedOrderIdInCheckoutResponse(response, syncedOrder) {
+    const normalized = this.normalizeCheckoutResponse(response);
+    const orderId = syncedOrder?.order_id;
+    if (orderId === undefined || orderId === null) return normalized;
+    if (!normalized?.data || typeof normalized.data !== 'object') return normalized;
+    return {
+      ...normalized,
+      data: {
+        ...normalized.data,
+        order_id: normalized.data.order_id ?? orderId
+      }
+    };
+  }
+  isCheckoutResponseRejected(response) {
+    const normalized = this.normalizeCheckoutResponse(response);
+    const isErrorCode = normalized?.code !== undefined && normalized.code !== 200 && normalized.code !== '200';
+    const isErrorStatus = normalized?.status === false || typeof normalized?.status === 'number' && normalized.status >= 400;
+    const isErrorSuccess = normalized?.success === false;
+    return isErrorCode || isErrorStatus || isErrorSuccess;
+  }
+  getUnknownErrorMessage(error) {
+    if (error instanceof Error && error.message) return error.message;
+    if (typeof error === 'string') return error;
+    const candidates = [error?.message, error?.response?.data?.message, error?.data?.message, error?.response?.body?.message, error?.body?.message];
+    const message = candidates.find(candidate => typeof candidate === 'string' && candidate !== '');
+    if (message) return message;
+    const normalized = this.normalizeUnknownError(error);
+    if (typeof normalized === 'string') return normalized;
+    try {
+      return JSON.stringify(normalized);
+    } catch {
+      return String(error);
+    }
+  }
+  normalizeUnknownError(error) {
+    if (error instanceof Error) {
+      const normalized = {
+        name: error.name,
+        message: error.message,
+        stack: error.stack
+      };
+      const record = error;
+      if (record.response?.data !== undefined) normalized.responseData = record.response.data;
+      if (record.data !== undefined) normalized.data = record.data;
+      if (record.response?.body !== undefined) normalized.responseBody = record.response.body;
+      if (record.body !== undefined) normalized.body = record.body;
+      return this.safeJsonClone(normalized);
+    }
+    if (!error || typeof error !== 'object') return String(error);
+    return this.safeJsonClone(error);
+  }
+  safeJsonClone(value) {
+    const seen = new WeakSet();
+    try {
+      return JSON.parse(JSON.stringify(value, (_key, current) => {
+        if (!current || typeof current !== 'object') return current;
+        if (seen.has(current)) return '[Circular]';
+        seen.add(current);
+        return current;
+      }));
+    } catch {
+      return String(value);
+    }
+  }
+  extractBackendErrorResponse(error) {
+    const candidates = [error?.response?.data, error?.data, error?.response?.body, error?.body];
+    return candidates.find(candidate => this.isExplicitBackendErrorResponse(candidate)) || null;
+  }
+  isExplicitBackendErrorResponse(candidate) {
+    if (!candidate || typeof candidate !== 'object') return false;
+    return candidate.code !== undefined || candidate.status !== undefined || typeof candidate.message === 'string';
+  }
+
+  /**
+   * 从 url 或路由 path 解析 pathname（不含 query，去掉末尾 /）
+   */
+  parseRequestPath(url, routePath) {
+    const raw = routePath || url;
+    const noQuery = raw.split('?')[0] || '';
+    try {
+      const pathname = url.startsWith('http') ? new URL(url).pathname : noQuery;
+      return pathname.replace(/\/$/, '') || pathname;
+    } catch {
+      return noQuery.replace(/\/$/, '');
+    }
+  }
+
+  /**
+   * 解析平面图 GET 路径为查询上下文
+   */
+  resolveFloorPlanQueryContext(path, base) {
+    if (path === base) {
+      return {
+        kind: 'list'
+      };
+    }
+    if (!path.startsWith(`${base}/`)) {
+      return null;
+    }
+    const after = path.slice(base.length + 1);
+    if (after === 'unsubscribe') {
+      return null;
+    }
+    if (after.startsWith('code/')) {
+      const code = decodeURIComponent(after.slice('code/'.length));
+      if (!code) return null;
+      return {
+        kind: 'code',
+        code
+      };
+    }
+    if (/^\d+$/.test(after)) {
+      return {
+        kind: 'id',
+        id: after
+      };
+    }
+    return null;
+  }
+
+  /**
+   * GET /shop/schedule/floor-plan* 前缀路由：读本地 store；支持 subscriberId + callback 订阅更新
+   */
+  handleFloorPlanGet = async ({
+    url,
+    data,
+    config,
+    path: routePath
+  }) => {
+    const base = '/shop/schedule/floor-plan';
+    const path = this.parseRequestPath(url, routePath);
+    if (path === `${base}/unsubscribe` || path === `${base}/code/unsubscribe`) {
+      const subscriberId = data?.subscriberId;
+      if (subscriberId) {
+        this.floorPlanQuerySubscribers.delete(subscriberId);
+        this.logInfo('handleFloorPlanGet: 已取消订阅', {
+          subscriberId,
+          remaining: this.floorPlanQuerySubscribers.size
+        });
+      }
+      return {
+        code: 200,
+        message: 'ok',
+        status: true
+      };
+    }
+    const {
+      callback,
+      subscriberId
+    } = config || {};
+    const ctx = this.resolveFloorPlanQueryContext(path, base);
+    if (!ctx) {
+      return {
+        status: false,
+        code: 404,
+        message: 'Not Found',
+        data: null
+      };
+    }
+    if (subscriberId && typeof callback === 'function') {
+      this.floorPlanQuerySubscribers.set(subscriberId, {
+        callback,
+        context: ctx
+      });
+      this.logInfo('handleFloorPlanGet: 已注册订阅者', {
+        subscriberId,
+        kind: ctx.kind,
+        total: this.floorPlanQuerySubscribers.size
       });
+    }
+    return this.computeFloorPlanQueryResult(ctx);
+  };
+  computeFloorPlanQueryResult(context) {
+    if (!this.floor_plan) {
+      return {
+        status: false,
+        code: 500,
+        message: 'Floor plan 模块未注册',
+        data: null
+      };
+    }
+    if (context.kind === 'list') {
       return {
+        status: true,
         code: 200,
-        data: {
-          ...response.data,
-          list: list?.list || []
-        },
         message: '',
-        status: true
+        data: this.floor_plan.getSortedList()
       };
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      this.logError('fetchBookingListFromAPI: 请求失败', {
-        error: errorMessage
-      });
+    }
+    if (context.kind === 'id') {
+      const item = this.floor_plan.getById(context.id);
+      if (!item) {
+        return {
+          status: false,
+          code: 404,
+          message: 'Not Found',
+          data: null
+        };
+      }
       return {
-        code: 500,
-        message: errorMessage,
-        data: {
-          list: [],
-          count: 0
-        },
-        status: false
+        status: true,
+        code: 200,
+        message: '',
+        data: item
       };
     }
+    const item = this.floor_plan.getByCode(context.code);
+    if (!item) {
+      return {
+        status: false,
+        code: 404,
+        message: 'Not Found',
+        data: null
+      };
+    }
+    return {
+      status: true,
+      code: 200,
+      message: '',
+      data: item
+    };
   }
 
   /**
-   * 处理预约列表查询
-   * 今天：注册订阅者 + 本地数据筛选；非今天：清理订阅者 + 走真实 API
+   * 平面图数据变更后向所有 GET 订阅者推送最新结果
    */
-  handleBookingList = async ({
-    url,
-    method,
-    data,
-    config
-  }) => {
-    const queryPayload = data && typeof data === 'object' ? {
-      ...data
-    } : {};
-    const {
-      callback,
-      subscriberId
-    } = config || {};
-    const isToday = this.isBookingQueryForToday(queryPayload);
-    this.logInfo('handleBookingList: 开始处理预约列表请求', {
-      data: queryPayload,
-      isToday
+  async recomputeAndNotifyFloorPlanQuery() {
+    if (this.floorPlanQuerySubscribers.size === 0) return;
+    this.logInfo('recomputeAndNotifyFloorPlanQuery: 开始推送', {
+      subscriberCount: this.floorPlanQuerySubscribers.size
     });
-    if (isToday) {
-      if (subscriberId && typeof callback === 'function') {
-        this.bookingQuerySubscribers.set(subscriberId, {
-          callback,
-          context: queryPayload
-        });
-        this.logInfo('handleBookingList: 已注册订阅者（今天）', {
-          subscriberId,
-          totalSubscribers: this.bookingQuerySubscribers.size
+    for (const [subscriberId, sub] of this.floorPlanQuerySubscribers.entries()) {
+      try {
+        const result = this.computeFloorPlanQueryResult(sub.context);
+        sub.callback(result);
+        this.logInfo('recomputeAndNotifyFloorPlanQuery: 已推送', {
+          subscriberId
         });
-      }
-      return this.computeBookingQueryResult(queryPayload);
-    } else {
-      if (subscriberId) {
-        this.bookingQuerySubscribers.delete(subscriberId);
-        this.logInfo('handleBookingList: 已清理订阅者（非今天）', {
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.logError('recomputeAndNotifyFloorPlanQuery: 推送失败', {
           subscriberId,
-          remaining: this.bookingQuerySubscribers.size
+          error: errorMessage
         });
       }
-      return this.fetchBookingListFromAPI(queryPayload);
     }
-  };
+  }
 
   /**
-   * 处理资源列表查询
-   * 转发到资源模块去
+   * 取消平面图 GET 订阅（也可走 GET .../unsubscribe + subscriberId）
    */
-  handleResourceList = async ({
-    url,
-    method,
-    data,
-    config
-  }) => {
-    const list = this.resource?.getResources({
-      skip: data?.skip || 1,
-      num: data?.num || 10
-    });
-    return {
-      code: 200,
-      data: {
-        list,
-        count: list?.length || 0
-      },
-      message: '',
-      status: true
-    };
-  };
+  removeFloorPlanQuerySubscriber(subscriberId) {
+    if (subscriberId) {
+      this.floorPlanQuerySubscribers.delete(subscriberId);
+      this.logInfo('removeFloorPlanQuerySubscriber: 已移除', {
+        subscriberId,
+        remaining: this.floorPlanQuerySubscribers.size
+      });
+    }
+  }
 
   /**
    * 取消预约列表查询订阅（HTTP 路由入口）
@@ -961,9 +4382,11 @@ class Server {
     } = 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 {
@@ -1004,7 +4427,8 @@ class Server {
       rawCount: rawList.length,
       filteredCount: result.count,
       size: result.size,
-      skip: result.skip
+      skip: result.skip,
+      rejected: result.rejected
     });
     return {
       code: 200,
@@ -1048,6 +4472,39 @@ class Server {
     };
   }
 
+  /**
+   * 规范商品扩展类型过滤参数。
+   *
+   * @example
+   * const types = this.normalizeProductExtensionTypes(['product_add_time']);
+   */
+  normalizeProductExtensionTypes(extension_type) {
+    if (!Array.isArray(extension_type)) return [];
+    return extension_type.map(item => String(item || '').trim()).filter(Boolean);
+  }
+
+  /**
+   * 请求包含 product_add_time 时，按传入 extension_type 数组配置过滤商品。
+   *
+   * @example
+   * const list = this.filterProductsByExtensionTypes(products, ['product_add_time']);
+   */
+  filterProductsByExtensionTypes(products, extension_type) {
+    const extensionTypes = this.normalizeProductExtensionTypes(extension_type);
+    if (!extensionTypes.includes('product_add_time')) return products;
+    return products.filter(product => extensionTypes.includes(String(product?.extension_type || '')));
+  }
+
+  /**
+   * 判断本次查询是否需要跳过餐牌过滤，直接按扩展类型拉商品。
+   *
+   * @example
+   * const skipMenu = this.shouldQueryProductsByExtensionTypes(['product_add_time']);
+   */
+  shouldQueryProductsByExtensionTypes(extension_type) {
+    return this.normalizeProductExtensionTypes(extension_type).includes('product_add_time');
+  }
+
   /**
    * 商品查询的核心计算逻辑（编排 Products、Menu、Schedule 模块）
    * 供 handleProductQuery 首次返回及 pubsub 变更推送复用
@@ -1059,71 +4516,189 @@ class Server {
     const tTotal = performance.now();
     const {
       menu_list_ids,
+      ids,
       schedule_date,
-      schedule_datetime
+      schedule_datetime,
+      customer_id,
+      extension_type,
+      product_id,
+      strategy_context
     } = context;
+    const queryIds = Array.isArray(ids) ? ids.map(id => Number(id)).filter(id => Number.isFinite(id)) : [];
+    const formatterContext = this.buildProductFormatterContext({
+      schedule_date,
+      schedule_datetime,
+      customer_id,
+      strategy_context
+    });
     this.logInfo('computeProductQueryResult 开始', {
       menuListIdsCount: menu_list_ids?.length ?? 0,
+      ids: queryIds,
       schedule_datetime,
       schedule_date,
+      customer_id,
+      extension_type,
+      product_id,
+      strategyContextKeys: strategy_context ? Object.keys(strategy_context) : [],
       changedIds: options?.changedIds
     });
     if (!this.products) {
       this.logError('computeProductQueryResult: Products 模块未注册');
       return {
         message: 'Products 模块未注册',
-        data: {
-          list: [],
-          count: 0
-        }
+        data: this.buildProductQueryResultPayload([], 0)
+      };
+    }
+    if (queryIds.length > 0) {
+      const uniqueIds = Array.from(new Set(queryIds));
+      const tPrice = performance.now();
+      const productsWithPrice = await this.products.getProductsWithPrice(schedule_date, formatterContext, {
+        changedIds: options?.changedIds,
+        productIds: uniqueIds
+      });
+      (0, _product.perfMark)('computeQuery.getProductsWithPrice(ids)', performance.now() - tPrice, {
+        count: productsWithPrice.length,
+        ids: uniqueIds
+      });
+      const filteredProducts = productsWithPrice.filter(p => uniqueIds.includes(Number(p?.id))).filter(p => (p?.status || 'published') === 'published');
+      const extensionFilteredProducts = this.filterProductsByExtensionTypes(filteredProducts, extension_type);
+      (0, _product.perfMark)('computeProductQueryResult', performance.now() - tTotal, {
+        mode: 'ids',
+        ids: uniqueIds,
+        count: extensionFilteredProducts.length
+      });
+      this.logInfo('computeProductQueryResult 完成（ids）', {
+        ids: uniqueIds,
+        count: extensionFilteredProducts.length
+      });
+      return {
+        code: 200,
+        data: this.buildProductQueryResultPayload(extensionFilteredProducts),
+        message: '',
+        status: true
+      };
+    }
+
+    // 单商品：复用 getProductsWithPrice + 发布状态过滤，不要求 Menu/Schedule（schedule 仍传入格式化上下文）
+    if (product_id != null && Number.isFinite(Number(product_id))) {
+      const pid = Number(product_id);
+      const tPrice = performance.now();
+      const allProductsWithPrice = await this.products.getProductsWithPrice(schedule_date, formatterContext, {
+        changedIds: options?.changedIds
+      });
+      (0, _product.perfMark)('computeQuery.getProductsWithPrice(single)', performance.now() - tPrice, {
+        count: allProductsWithPrice.length,
+        productId: pid
+      });
+      const published = this.filterProductsByExtensionTypes(allProductsWithPrice.filter(p => (p?.status || 'published') === 'published'), extension_type);
+      const item = published.find(p => Number(p.id) === pid) ?? null;
+      (0, _product.perfMark)('computeProductQueryResult', performance.now() - tTotal, {
+        mode: 'single',
+        productId: pid,
+        found: !!item
+      });
+      this.logInfo('computeProductQueryResult 完成（单商品）', {
+        productId: pid,
+        found: !!item
+      });
+      return {
+        code: 200,
+        data: item,
+        message: item ? '' : '商品不存在或未发布',
+        status: true
+      };
+    }
+    if (this.shouldQueryProductsByExtensionTypes(extension_type)) {
+      const tPrice = performance.now();
+      let filteredProducts = await this.products.getProductsWithPrice(schedule_date, formatterContext, {
+        changedIds: options?.changedIds
+      });
+      (0, _product.perfMark)('computeQuery.getProductsWithPrice(extensionType)', performance.now() - tPrice, {
+        count: filteredProducts.length,
+        extension_type
+      });
+      const tStatus = performance.now();
+      const beforeStatusCount = filteredProducts.length;
+      filteredProducts = filteredProducts.filter(p => (p?.status || 'published') === 'published');
+      (0, _product.perfMark)('computeQuery.filterByStatus(extensionType)', performance.now() - tStatus, {
+        before: beforeStatusCount,
+        after: filteredProducts.length
+      });
+      const tExtensionType = performance.now();
+      const beforeExtensionTypeCount = filteredProducts.length;
+      filteredProducts = this.filterProductsByExtensionTypes(filteredProducts, extension_type);
+      (0, _product.perfMark)('computeQuery.filterByExtensionType(extensionType)', performance.now() - tExtensionType, {
+        before: beforeExtensionTypeCount,
+        after: filteredProducts.length,
+        extension_type
+      });
+      const tSort = performance.now();
+      filteredProducts = filteredProducts.sort((a, b) => {
+        const sortDiff = Number(b.sort) - Number(a.sort);
+        if (sortDiff !== 0) return sortDiff;
+        return (a.title || '').localeCompare(b.title || '');
+      });
+      (0, _product.perfMark)('computeQuery.sort(extensionType)', performance.now() - tSort, {
+        count: filteredProducts.length
+      });
+      (0, _product.perfMark)('computeProductQueryResult', performance.now() - tTotal, {
+        mode: 'extensionType',
+        filteredCount: filteredProducts.length
+      });
+      this.logInfo('computeProductQueryResult 完成（extension_type）', {
+        filteredCount: filteredProducts.length,
+        extension_type
+      });
+      return {
+        code: 200,
+        data: this.buildProductQueryResultPayload(filteredProducts),
+        message: '',
+        status: true
       };
     }
     if (!this.menu) {
       this.logError('computeProductQueryResult: Menu 模块未注册');
       return {
         message: 'Menu 模块未注册',
-        data: {
-          list: [],
-          count: 0
-        }
+        data: this.buildProductQueryResultPayload([], 0)
       };
     }
     if (!this.schedule) {
       this.logError('computeProductQueryResult: Schedule 模块未注册');
       return {
         message: 'Schedule 模块未注册',
-        data: {
-          list: [],
-          count: 0
-        }
+        data: this.buildProductQueryResultPayload([], 0)
       };
     }
     let activeMenuList = [];
     if (menu_list_ids && Array.isArray(menu_list_ids) && menu_list_ids.length > 0) {
       const tMenu = performance.now();
-      const menuList = this.menu.getMenuByIds(menu_list_ids);
-      activeMenuList = menuList.filter(menu => {
-        return this.schedule?.getDateIsInSchedule(schedule_datetime, menu.schedule) || false;
-      });
+      const getActiveMenus = () => this.menu.getMenuByIds(menu_list_ids).filter(menu => this.schedule?.getDateIsInSchedule(schedule_datetime, menu.schedule) || false);
+      activeMenuList = getActiveMenus();
+      if (!activeMenuList.length && (await this.refreshMenuScheduleCacheAfterEmptyResult())) {
+        activeMenuList = getActiveMenus();
+      }
       (0, _product.perfMark)('computeQuery.filterActiveMenu', performance.now() - tMenu, {
-        totalMenu: menuList.length,
+        totalMenu: menu_list_ids.length,
         activeMenu: activeMenuList.length
       });
     }
-    const tPrice = performance.now();
-    const allProductsWithPrice = await this.products.getProductsWithPrice(schedule_date, {
-      scheduleModule: this.getSchedule()
-    }, {
-      changedIds: options?.changedIds
-    });
-    (0, _product.perfMark)('computeQuery.getProductsWithPrice', performance.now() - tPrice, {
-      count: allProductsWithPrice.length
-    });
     const tFilter = performance.now();
-    let filteredProducts = this.filterProductsByMenuConfig(allProductsWithPrice, activeMenuList);
+    const productScope = this.getProductScopeByMenuConfig(activeMenuList);
+    const scopedProductIds = this.products.getProductIdsByScope(productScope);
     (0, _product.perfMark)('computeQuery.filterByMenu', performance.now() - tFilter, {
-      before: allProductsWithPrice.length,
-      after: filteredProducts.length
+      scopedProductCount: scopedProductIds.length,
+      activeMenuCount: activeMenuList.length,
+      isAllProducts: !!productScope.isAllProducts
+    });
+    const tPrice = performance.now();
+    let filteredProducts = scopedProductIds.length > 0 ? await this.products.getProductsWithPrice(schedule_date, formatterContext, {
+      changedIds: options?.changedIds,
+      productIds: productScope.isAllProducts ? undefined : scopedProductIds
+    }) : [];
+    (0, _product.perfMark)('computeQuery.getProductsWithPrice', performance.now() - tPrice, {
+      count: filteredProducts.length,
+      scopedProductCount: scopedProductIds.length
     });
     const tStatus = performance.now();
     const beforeStatusCount = filteredProducts.length;
@@ -1132,6 +4707,14 @@ class Server {
       before: beforeStatusCount,
       after: filteredProducts.length
     });
+    const tExtensionType = performance.now();
+    const beforeExtensionTypeCount = filteredProducts.length;
+    filteredProducts = this.filterProductsByExtensionTypes(filteredProducts, extension_type);
+    (0, _product.perfMark)('computeQuery.filterByExtensionType', performance.now() - tExtensionType, {
+      before: beforeExtensionTypeCount,
+      after: filteredProducts.length,
+      extension_type
+    });
     const tSort = performance.now();
     filteredProducts = filteredProducts.sort((a, b) => {
       const sortDiff = Number(b.sort) - Number(a.sort);
@@ -1142,26 +4725,41 @@ class Server {
       count: filteredProducts.length
     });
     (0, _product.perfMark)('computeProductQueryResult', performance.now() - tTotal, {
-      originalCount: allProductsWithPrice.length,
+      scopedProductCount: scopedProductIds.length,
       filteredCount: filteredProducts.length,
       activeMenuCount: activeMenuList.length
     });
     this.logInfo('computeProductQueryResult 完成', {
-      originalCount: allProductsWithPrice.length,
+      scopedProductCount: scopedProductIds.length,
       filteredCount: filteredProducts.length,
       activeMenuCount: activeMenuList.length
     });
     return {
       code: 200,
-      data: {
-        list: filteredProducts,
-        count: filteredProducts.length
-      },
+      data: this.buildProductQueryResultPayload(filteredProducts),
       message: '',
       status: true
     };
   }
 
+  /**
+   * 构建商品格式化上下文。
+   *
+   * 智能定价条件使用全量 menuList/scheduleList；Product Query 顶层参数只保留筛选商品集合所需字段。
+   */
+  buildProductFormatterContext(context) {
+    const scheduleModule = this.getSchedule();
+    return {
+      scheduleModule,
+      schedule_datetime: context.schedule_datetime,
+      customer_id: context.customer_id,
+      strategy_context: context.strategy_context,
+      menuList: this.menu?.getMenuList?.() || [],
+      scheduleList: scheduleModule?.getScheduleList?.() || [],
+      dataVariantEvaluator: this.core.context?.dataVariantEvaluator
+    };
+  }
+
   /**
    * 数据变更后，遍历所有订阅者重新计算查询结果并通过 callback 推送
    * 由 ProductsModule 的 onProductsSyncCompleted 事件触发
@@ -1198,15 +4796,24 @@ class Server {
    */
   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);
+        const callbackEndAt = Date.now();
         this.logInfo('recomputeAndNotifyOrderQuery: 已推送', {
-          subscriberId
+          subscriberId,
+          computeDurationMs: computeEndAt - computeStartAt,
+          callbackDurationMs: callbackEndAt - callbackStartAt,
+          totalDurationMs: callbackEndAt - computeStartAt
         });
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
@@ -1216,6 +4823,114 @@ class Server {
         });
       }
     }
+    const notifyEndAt = Date.now();
+    this.logInfo('recomputeAndNotifyOrderQuery: 推送完成', {
+      subscriberCount: this.orderQuerySubscribers.size,
+      totalNotifyDurationMs: notifyEndAt - notifyStartAt
+    });
+  }
+
+  /**
+   * 订单变更后通知 sales 搜索订阅者。
+   * 仅回传当前查询已返回订单号集合中的变更订单。
+   *
+   * @example
+   * this.notifySalesSearchSubscribers({ list: [], changedOrders: [order], source: 'pubsub.bodyUpsert' })
+   */
+  notifySalesSearchSubscribers(payload) {
+    if (this.salesSearchSubscribers.size === 0) return;
+    const changedOrders = this.extractChangedOrdersFromPayload(payload);
+    if (changedOrders.length === 0) {
+      return;
+    }
+    // 如果当前开启了 checkout 弹窗，先不进行刷新，下面的代码会导致在全局搜索页调用 bookingTicket.destroy()
+    // 导致模块被销毁 ，checkout 弹窗永远无法关闭
+    if (window.isPaymentModalPluginOpen) return;
+    for (const [subscriberId, subscriber] of this.salesSearchSubscribers.entries()) {
+      try {
+        const changedVisibleOrders = changedOrders.filter(order => {
+          const orderId = this.getSalesSearchOrderId(order);
+          return !!orderId && subscriber.visibleOrderIds.has(orderId);
+        });
+        if (changedVisibleOrders.length === 0) {
+          continue;
+        }
+        subscriber.callback(this.buildSalesSearchDeltaResponse(subscriber, changedVisibleOrders));
+        this.logInfo('notifySalesSearchSubscribers: 已推送 delta', {
+          subscriberId,
+          kind: subscriber.kind,
+          count: changedVisibleOrders.length
+        });
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.logError('notifySalesSearchSubscribers: 推送失败', {
+          subscriberId,
+          error: errorMessage
+        });
+      }
+    }
+  }
+
+  /**
+   * 从订单变更事件中提取明确 delta。
+   *
+   * @example
+   * const list = this.extractChangedOrdersFromPayload(payload)
+   */
+  extractChangedOrdersFromPayload(payload) {
+    if (!payload || Array.isArray(payload)) return [];
+    return Array.isArray(payload.changedOrders) ? payload.changedOrders : [];
+  }
+
+  /**
+   * 构建与当前搜索接口一致的 delta 响应。
+   *
+   * @example
+   * const response = this.buildSalesSearchDeltaResponse(subscriber, [order])
+   */
+  buildSalesSearchDeltaResponse(subscriber, changedOrders) {
+    if (subscriber.kind === 'aggregate') {
+      return this.buildAggregateSalesSearchDeltaResponse(subscriber, changedOrders);
+    }
+    const data = subscriber.lastResponseData || {};
+    return {
+      code: 200,
+      status: true,
+      message: '',
+      data: {
+        ...data,
+        list: changedOrders
+      }
+    };
+  }
+
+  /**
+   * 构建聚合搜索接口的 sales 分组 delta 响应。
+   *
+   * @example
+   * const response = this.buildAggregateSalesSearchDeltaResponse(subscriber, [order])
+   */
+  buildAggregateSalesSearchDeltaResponse(subscriber, changedOrders) {
+    const data = subscriber.lastResponseData || {};
+    const results = Array.isArray(data?.results) ? data.results : [];
+    const hasSalesGroup = results.some(item => item?.module === 'sales');
+    const nextResults = hasSalesGroup ? results.map(item => item?.module === 'sales' ? {
+      ...item,
+      list: changedOrders
+    } : item) : [{
+      module: 'sales',
+      list: changedOrders,
+      count: changedOrders.length
+    }];
+    return {
+      code: 200,
+      status: true,
+      message: '',
+      data: {
+        ...data,
+        results: nextResults
+      }
+    };
   }
 
   /**
@@ -1244,31 +4959,29 @@ class Server {
   }
 
   /**
-   * 根据餐牌配置过滤商品
-   * @param products 所有商品列表
-   * @param activeMenuList 生效的餐牌列表
-   * @returns 过滤后的商品列表
+   * 根据餐牌配置提取轻量商品范围。
    * @private
    */
-  filterProductsByMenuConfig(products, activeMenuList) {
-    // 如果没有生效的餐牌，返回空数组
+  getProductScopeByMenuConfig(activeMenuList) {
     if (!activeMenuList || activeMenuList.length === 0) {
-      this.logInfo('filterProductsByMenuConfig: 没有生效的餐牌，返回空数组', {
-        productCount: products.length,
+      this.logInfo('getProductScopeByMenuConfig: 没有生效的餐牌，返回空数组', {
         activeMenuCount: 0
       });
-      return [];
+      return {
+        productIds: [],
+        collectionIds: []
+      };
     }
 
     // 收集允许的商品 IDs 和集合 IDs
-    let allowedProductIds = new Set();
-    let allowedCollectionIds = new Set();
+    const allowedProductIds = new Set();
+    const allowedCollectionIds = new Set();
     let hasProductAll = false;
     for (const menu of activeMenuList) {
       const config = menu.partyroom_package;
       if (!config) {
         console.warn('[Server] 餐牌缺少 partyroom_package 配置:', menu);
-        this.logWarning('filterProductsByMenuConfig: 餐牌缺少 partyroom_package 配置', {
+        this.logWarning('getProductScopeByMenuConfig: 餐牌缺少 partyroom_package 配置', {
           menuId: menu.form_record_id,
           menuName: menu.name
         });
@@ -1277,7 +4990,7 @@ class Server {
 
       // 如果有任何一个餐牌是 product_all，则返回所有商品
       if (config.type === 'product_all') {
-        this.logInfo('filterProductsByMenuConfig: 餐牌允许所有商品', {
+        this.logInfo('getProductScopeByMenuConfig: 餐牌允许所有商品', {
           menuId: menu.form_record_id,
           menuName: menu.name,
           configType: config.type
@@ -1290,7 +5003,7 @@ class Server {
       if (config.type === 'products' && Array.isArray(config.products)) {
         const productIds = config.products.map(item => item.product_id);
         productIds.forEach(id => id && allowedProductIds.add(id));
-        this.logInfo('filterProductsByMenuConfig: 餐牌允许指定商品', {
+        this.logInfo('getProductScopeByMenuConfig: 餐牌允许指定商品', {
           menuId: menu.form_record_id,
           menuName: menu.name,
           configType: config.type,
@@ -1302,7 +5015,7 @@ class Server {
       if (config.type === 'product_collection' && Array.isArray(config.products)) {
         const collectionIds = config.products.map(item => item.product_collection_id);
         collectionIds.forEach(id => id && allowedCollectionIds.add(id));
-        this.logInfo('filterProductsByMenuConfig: 餐牌允许商品集合', {
+        this.logInfo('getProductScopeByMenuConfig: 餐牌允许商品集合', {
           menuId: menu.form_record_id,
           menuName: menu.name,
           configType: config.type,
@@ -1313,49 +5026,32 @@ class Server {
 
     // 如果有餐牌允许所有商品，返回所有商品
     if (hasProductAll) {
-      this.logInfo('filterProductsByMenuConfig: 返回所有商品（product_all）', {
-        productCount: products.length
-      });
-      return products;
+      this.logInfo('getProductScopeByMenuConfig: 返回所有商品 scope（product_all）');
+      return {
+        isAllProducts: true
+      };
     }
 
     // 如果没有收集到任何商品 ID 和集合 ID，返回空数组
     if (allowedProductIds.size === 0 && allowedCollectionIds.size === 0) {
-      this.logWarning('filterProductsByMenuConfig: 没有允许的商品和集合', {
-        productCount: products.length,
+      this.logWarning('getProductScopeByMenuConfig: 没有允许的商品和集合', {
         activeMenuCount: activeMenuList.length
       });
-      return [];
+      return {
+        productIds: [],
+        collectionIds: []
+      };
     }
     const allowedProductIdsArray = Array.from(allowedProductIds);
     const allowedCollectionIdsArray = Array.from(allowedCollectionIds);
-    this.logInfo('filterProductsByMenuConfig: 收集到的允许规则', {
+    this.logInfo('getProductScopeByMenuConfig: 收集到的允许规则', {
       allowedProductCount: allowedProductIds.size,
       allowedCollectionCount: allowedCollectionIds.size
     });
-
-    // 过滤商品
-    const filteredProducts = products.filter(product => {
-      // 1. 检查商品 ID 是否在允许列表中
-      if (allowedProductIds.has(product.id)) {
-        return true;
-      }
-
-      // 2. 检查商品是否属于允许的集合
-      if (allowedCollectionIds.size > 0 && Array.isArray(product.collection)) {
-        const hasMatchingCollection = product.collection.some(col => allowedCollectionIds.has(col.id));
-        if (hasMatchingCollection) {
-          return true;
-        }
-      }
-      return false;
-    });
-    this.logInfo('filterProductsByMenuConfig: 过滤完成', {
-      originalCount: products.length,
-      filteredCount: filteredProducts.length,
-      removedCount: products.length - filteredProducts.length
-    });
-    return filteredProducts;
+    return {
+      productIds: allowedProductIdsArray,
+      collectionIds: allowedCollectionIdsArray
+    };
   }
 
   /**