@pisell/pisellos 0.10.16 → 0.10.17

package/lib/server/index.js

@@ -27,6 +27,7 @@ var _filterBookings = require("./modules/order/utils/filterBookings");
 var _smallTicket = require("./utils/small-ticket");
 var _BaseSales = require("../solution/BaseSales");
 var _paymentUtils = require("../modules/Order/payment-utils");
+var _OpenData = require("../modules/OpenData");
 var _modules = require("./modules");
 Object.keys(_modules).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;
@@ -40,6 +41,10 @@ Object.keys(_modules).forEach(function (key) {
   });
 });
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+const OS_FULFILLMENT_REF_MODE_FIELD = '_os_fulfillment_ref_mode';
+const OS_INVOICE_LAYOUT_CONFIG_FIELD = '_os_invoice_layout_config';
+const OS_INVOICE_TEMPLATE_SETTINGS_FIELD = '_os_invoice_template_settings';
+
 // 重新导出类型供外部使用
 
 /** 商品查询订阅者 */
@@ -560,7 +565,16 @@ class Server {
   async handleSyncSalesTask(ctx) {
     const payload = ctx.task?.payload || {};
     const backendPath = payload.backendPath;
-    const data = payload.data;
+    const extractedInvoice = this.extractInvoiceLayoutConfig(payload.data, {
+      includePublicInvoice: true
+    });
+    const extractedTemplateSettings = this.extractInvoiceTemplateSettings(extractedInvoice.data, {
+      includePublicTemplateSettings: true
+    });
+    const data = extractedTemplateSettings.data;
+    const rawInvoiceLayoutConfig = payload.invoice ?? extractedInvoice.invoiceLayoutConfig;
+    const invoiceLayoutConfig = rawInvoiceLayoutConfig === undefined || rawInvoiceLayoutConfig === null ? undefined : this.normalizePrintInvoiceLayoutConfig(rawInvoiceLayoutConfig);
+    const invoiceTemplateSettings = this.normalizePrintInvoiceTemplateSettings(payload.template_settings ?? extractedTemplateSettings.invoiceTemplateSettings);
     const title = payload.title || 'sync_sales';
     if (!backendPath || !data) {
       return this.taskFail('INVALID_PAYLOAD', '缺少 backendPath 或 data');
@@ -576,7 +590,9 @@ class Server {
         title,
         externalSaleNumber: payload.external_sale_number,
         deviceId: ctx.task?.device_id,
-        persistCheckoutDataWithResponse: false
+        persistCheckoutDataWithResponse: false,
+        invoiceLayoutConfig,
+        invoiceTemplateSettings
       });
       if (syncResult.rejected) {
         this.logError(`${title}: sync_sales 后端明确失败`, {
@@ -614,7 +630,8 @@ class Server {
       title
     } = params;
     const normalizedData = await this.normalizeCheckoutSubmitData(params.data, title);
-    const checkoutData = await this.ensureCheckoutOrderNumbers(normalizedData, title);
+    const numberedData = await this.ensureCheckoutOrderNumbers(normalizedData, title);
+    const checkoutData = this.applyCheckoutFulfillmentBuzzer(numberedData, title);
     const remoteCheckoutData = this.buildRemoteCheckoutData(checkoutData, title);
     if (!this.app?.request?.post) {
       throw new Error('app.request 不可用');
@@ -658,7 +675,9 @@ class Server {
         checkoutData,
         syncedOrder: printableSyncedOrder,
         response,
-        deviceId: params.deviceId
+        deviceId: params.deviceId,
+        invoiceLayoutConfig: params.invoiceLayoutConfig,
+        invoiceTemplateSettings: params.invoiceTemplateSettings
       });
     }
     return {
@@ -683,6 +702,8 @@ class Server {
     const next = (0, _lodashEs.cloneDeep)(this.omitCheckoutSyncMode(data));
     if (!next || typeof next !== 'object') return next;
     const record = next;
+    delete record[OS_FULFILLMENT_REF_MODE_FIELD];
+    delete record[OS_INVOICE_LAYOUT_CONFIG_FIELD];
     if (!Array.isArray(record.payments)) return next;
     const originalPayments = record.payments;
     const filteredPayments = originalPayments.filter(payment => !(0, _paymentUtils.isPendingOrderPayment)(payment));
@@ -3342,6 +3363,158 @@ class Server {
   isLocalCheckoutOrderId(orderId) {
     return typeof orderId === 'string' && orderId.startsWith('LOCAL_');
   }
+  normalizePrintInvoiceLayoutConfig(value) {
+    if (value === undefined || value === null) {
+      return (0, _OpenData.getDefaultInvoiceLayoutConfig)();
+    }
+    let parsed = value;
+    if (typeof parsed === 'string') {
+      try {
+        parsed = JSON.parse(parsed);
+      } catch {
+        return (0, _OpenData.getDefaultInvoiceLayoutConfig)();
+      }
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return (0, _OpenData.getDefaultInvoiceLayoutConfig)();
+    }
+    const record = parsed;
+    if (!Array.isArray(record.module)) {
+      return (0, _OpenData.getDefaultInvoiceLayoutConfig)();
+    }
+    return {
+      ...(typeof record.locale === 'string' ? {
+        locale: record.locale
+      } : {}),
+      module: record.module.map(moduleConfig => moduleConfig && typeof moduleConfig === 'object' && !Array.isArray(moduleConfig) ? {
+        ...moduleConfig
+      } : moduleConfig)
+    };
+  }
+  extractInvoiceLayoutConfig(data, options) {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      return {
+        data
+      };
+    }
+    const record = data;
+    const rawInvoiceLayoutConfig = options?.includePublicInvoice ? record.invoice ?? record[OS_INVOICE_LAYOUT_CONFIG_FIELD] : record[OS_INVOICE_LAYOUT_CONFIG_FIELD];
+    const next = {
+      ...record
+    };
+    delete next[OS_INVOICE_LAYOUT_CONFIG_FIELD];
+    if (options?.includePublicInvoice) delete next.invoice;
+    return {
+      data: next,
+      ...(rawInvoiceLayoutConfig !== undefined && rawInvoiceLayoutConfig !== null ? {
+        invoiceLayoutConfig: this.normalizePrintInvoiceLayoutConfig(rawInvoiceLayoutConfig)
+      } : {})
+    };
+  }
+  normalizePrintInvoiceTemplateSettings(value) {
+    if (value === undefined || value === null) {
+      return (0, _OpenData.getDefaultInvoiceTemplateSettings)();
+    }
+    return (0, _OpenData.normalizeRawInvoiceTemplateSettings)(value);
+  }
+  extractInvoiceTemplateSettings(data, options) {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      return {
+        data
+      };
+    }
+    const record = data;
+    const rawInvoiceTemplateSettings = options?.includePublicTemplateSettings ? record.template_settings ?? record[OS_INVOICE_TEMPLATE_SETTINGS_FIELD] : record[OS_INVOICE_TEMPLATE_SETTINGS_FIELD];
+    const next = {
+      ...record
+    };
+    delete next[OS_INVOICE_TEMPLATE_SETTINGS_FIELD];
+    if (options?.includePublicTemplateSettings) delete next.template_settings;
+    return {
+      data: next,
+      ...(rawInvoiceTemplateSettings !== undefined && rawInvoiceTemplateSettings !== null ? {
+        invoiceTemplateSettings: this.normalizePrintInvoiceTemplateSettings(rawInvoiceTemplateSettings)
+      } : {})
+    };
+  }
+  applyCheckoutFulfillmentBuzzer(data, title) {
+    if (!data || typeof data !== 'object') return data;
+    const next = {
+      ...data
+    };
+    const refMode = String(next[OS_FULFILLMENT_REF_MODE_FIELD] || '').trim();
+    delete next[OS_FULFILLMENT_REF_MODE_FIELD];
+    if (!refMode) return next;
+    if (refMode === 'manual_input') {
+      this.logInfo(`${title}: fulfillment ref mode 保留手动 buzzer`, {
+        fulfillment_ref_mode: refMode,
+        has_buzzer: !this.isBlankCheckoutValue(next.buzzer)
+      });
+      return next;
+    }
+    if (refMode === 'resource_identifier') {
+      next.buzzer = this.buildCheckoutResourceIdentifierBuzzer(next.bookings);
+    } else if (refMode === 'sale_number') {
+      next.buzzer = this.isBlankCheckoutValue(next.shop_order_number) ? '' : String(next.shop_order_number);
+    } else if (refMode === 'short_number') {
+      next.buzzer = this.isBlankCheckoutValue(next.shop_full_order_number) ? '' : String(next.shop_full_order_number);
+    } else {
+      this.logWarning(`${title}: 未识别的 fulfillment ref mode，跳过 buzzer 自动填充`, {
+        fulfillment_ref_mode: refMode
+      });
+      return next;
+    }
+    this.logInfo(`${title}: fulfillment ref mode 已填充 buzzer`, {
+      fulfillment_ref_mode: refMode,
+      buzzer: next.buzzer
+    });
+    return next;
+  }
+  buildCheckoutResourceIdentifierBuzzer(bookings) {
+    if (!Array.isArray(bookings)) return '';
+    const values = [];
+    const seen = new Set();
+    const visitResource = (resource, fallbackName) => {
+      const identifier = this.getCheckoutResourceIdentifier(resource, fallbackName);
+      if (identifier && !seen.has(identifier)) {
+        seen.add(identifier);
+        values.push(identifier);
+      }
+      if (Array.isArray(resource?.children)) {
+        resource.children.forEach(child => visitResource(child));
+      }
+    };
+    bookings.forEach(booking => {
+      if (Array.isArray(booking?.resources)) {
+        booking.resources.forEach((resource, index) => {
+          visitResource(resource, index === 0 ? booking?.relation_form_name : undefined);
+        });
+      }
+    });
+    return values.join(',');
+  }
+  getCheckoutResourceIdentifier(resource, fallbackName) {
+    if (!resource || typeof resource !== 'object') return '';
+    const candidates = [resource.main_field, resource.name, resource.title, resource.metadata?.resource_name, resource.metadata?.name, fallbackName, resource.relation_id, resource.id];
+    for (const candidate of candidates) {
+      const value = this.stringifyCheckoutResourceIdentifier(candidate);
+      if (value) return value;
+    }
+    return '';
+  }
+  stringifyCheckoutResourceIdentifier(value) {
+    if (value === undefined || value === null) return '';
+    if (typeof value === 'string' || typeof value === 'number') {
+      return String(value).trim();
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) return '';
+    const localeCandidates = [value.original, value.auto, value.en, value['zh-CN'], value.zh_CN, value['zh-HK'], value.zh_HK];
+    for (const candidate of localeCandidates) {
+      const normalized = this.stringifyCheckoutResourceIdentifier(candidate);
+      if (normalized) return normalized;
+    }
+    return '';
+  }
   async normalizeCheckoutSubmitData(data, title) {
     if (!data || typeof data !== 'object') return data;
     const next = {
@@ -3472,6 +3645,8 @@ class Server {
         payload: {
           backendPath: params.backendPath,
           data: params.data,
+          invoice: this.normalizePrintInvoiceLayoutConfig(params.invoiceLayoutConfig),
+          template_settings: this.normalizePrintInvoiceTemplateSettings(params.invoiceTemplateSettings),
           external_sale_number: params.data?.external_sale_number,
           title: params.title
         },
@@ -3510,12 +3685,18 @@ class Server {
           data: params.receiptOnly ? {
             order_id: printIdentity,
             small_ticket_data: params.syncedOrder?.payment_info?.small_ticket_data,
+            invoice: this.normalizePrintInvoiceLayoutConfig(params.invoiceLayoutConfig),
+            template_settings: this.normalizePrintInvoiceTemplateSettings(params.invoiceTemplateSettings),
             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,
+            ...(params.invoiceLayoutConfig ? {
+              invoice: this.normalizePrintInvoiceLayoutConfig(params.invoiceLayoutConfig)
+            } : {}),
+            template_settings: this.normalizePrintInvoiceTemplateSettings(params.invoiceTemplateSettings),
             skip_receipt: true
           }
         },
@@ -3567,7 +3748,9 @@ class Server {
       syncedOrder: printableOrder,
       response: params.response,
       receiptOnly: true,
-      isManualPrint: params.isManualPrint
+      isManualPrint: params.isManualPrint,
+      invoiceLayoutConfig: params.invoiceLayoutConfig,
+      invoiceTemplateSettings: params.invoiceTemplateSettings
     });
     return {
       printed: true,
@@ -3587,11 +3770,35 @@ class Server {
     }
     return undefined;
   }
+  mergeLocalPrintOrderInput(localOrder, inputOrder) {
+    const definedInput = Object.fromEntries(Object.entries(inputOrder || {}).filter(([, value]) => value !== undefined));
+    return {
+      ...localOrder,
+      ...definedInput,
+      order_id: localOrder.order_id ?? definedInput.order_id ?? definedInput.orderId,
+      external_sale_number: localOrder.external_sale_number ?? definedInput.external_sale_number ?? definedInput.externalSaleNumber
+    };
+  }
   handleLocalPrintOrder = async ({
     data
   }) => {
     try {
-      const inputOrder = data?.order && typeof data.order === 'object' ? data.order : data;
+      const extractedRequest = this.extractInvoiceLayoutConfig(data, {
+        includePublicInvoice: true
+      });
+      const extractedRequestTemplateSettings = this.extractInvoiceTemplateSettings(extractedRequest.data, {
+        includePublicTemplateSettings: true
+      });
+      const requestOrder = extractedRequestTemplateSettings.data?.order;
+      const nestedOrder = requestOrder && typeof requestOrder === 'object' ? this.extractInvoiceLayoutConfig(requestOrder, {
+        includePublicInvoice: true
+      }) : null;
+      const nestedOrderTemplateSettings = nestedOrder ? this.extractInvoiceTemplateSettings(nestedOrder.data, {
+        includePublicTemplateSettings: true
+      }) : null;
+      const inputOrder = nestedOrderTemplateSettings?.data ?? extractedRequestTemplateSettings.data;
+      const invoiceLayoutConfig = extractedRequest.invoiceLayoutConfig ?? nestedOrder?.invoiceLayoutConfig;
+      const invoiceTemplateSettings = this.normalizePrintInvoiceTemplateSettings(extractedRequestTemplateSettings.invoiceTemplateSettings ?? nestedOrderTemplateSettings?.invoiceTemplateSettings);
       if (!inputOrder || typeof inputOrder !== 'object') {
         return {
           code: 400,
@@ -3603,13 +3810,13 @@ class Server {
           }
         };
       }
-      const shouldLookup = this.shouldLookupLocalPrintOrder(inputOrder) || this.shouldLookupLocalPrintOrder(data);
+      const shouldLookup = this.shouldLookupLocalPrintOrder(inputOrder) || this.shouldLookupLocalPrintOrder(extractedRequest.data);
       this.logInfo('handleLocalPrintOrder: 是否需要查找本地订单', {
         shouldLookup,
         inputOrder,
         data
       });
-      const lookup = shouldLookup ? this.getLocalPrintOrderLookup(inputOrder) ?? this.getLocalPrintOrderLookup(data) : undefined;
+      const lookup = shouldLookup ? this.getLocalPrintOrderLookup(inputOrder) ?? this.getLocalPrintOrderLookup(extractedRequest.data) : undefined;
       let sourceOrder = inputOrder;
       if (shouldLookup) {
         if (lookup === undefined) {
@@ -3634,24 +3841,25 @@ class Server {
             }
           };
         }
-        const localOrder = await this.order.getLocalOrderByLookup(lookup);
+        let localOrder = await this.order.getLocalOrderByLookup(lookup);
         if (!localOrder) {
-          return {
-            code: 404,
-            status: false,
-            message: '订单不存在',
-            data: {
-              printed: false,
-              order: null
-            }
-          };
+          const remoteResult = await this.fetchAndPersistSalesOrderByLookup(lookup, {
+            with: ['all']
+          }, 'handleLocalPrintOrder');
+          if (!remoteResult.order) {
+            return {
+              code: remoteResult.code,
+              status: false,
+              message: remoteResult.message,
+              data: {
+                printed: false,
+                order: null
+              }
+            };
+          }
+          localOrder = remoteResult.order;
         }
-        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
-        };
+        sourceOrder = this.mergeLocalPrintOrderInput(localOrder, inputOrder);
       }
       const checkoutData = await this.ensureCheckoutOrderNumbers({
         ...sourceOrder,
@@ -3670,7 +3878,9 @@ class Server {
         order: printableOrder,
         response: null,
         requireFullyPaid: false,
-        isManualPrint: true
+        isManualPrint: true,
+        invoiceLayoutConfig,
+        invoiceTemplateSettings
       });
       return {
         code: 200,
@@ -3881,9 +4091,17 @@ class Server {
   async handleOrderCheckoutSubmit(params) {
     const {
       backendPath,
-      data,
       title
     } = params;
+    const extractedInvoice = this.extractInvoiceLayoutConfig(params.data, {
+      includePublicInvoice: true
+    });
+    const extractedTemplateSettings = this.extractInvoiceTemplateSettings(extractedInvoice.data, {
+      includePublicTemplateSettings: true
+    });
+    const data = extractedTemplateSettings.data;
+    const invoiceLayoutConfig = extractedInvoice.invoiceLayoutConfig;
+    const invoiceTemplateSettings = this.normalizePrintInvoiceTemplateSettings(extractedTemplateSettings.invoiceTemplateSettings);
     this.logInfo(`${title}: 开始处理`, {
       backendPath,
       order_id: data?.order_id,
@@ -3894,11 +4112,14 @@ class Server {
       return this.handleSyncCheckoutSubmit({
         backendPath,
         data,
-        title
+        title,
+        invoiceLayoutConfig,
+        invoiceTemplateSettings
       });
     }
     const normalizedData = await this.normalizeCheckoutSubmitData(data, title);
-    const checkoutData = await this.ensureCheckoutOrderNumbers(normalizedData, title);
+    const numberedData = await this.ensureCheckoutOrderNumbers(normalizedData, title);
+    const checkoutData = this.applyCheckoutFulfillmentBuzzer(numberedData, title);
     const pendingResult = await this.handlePendingSyncCheckoutOrder({
       backendPath,
       data: checkoutData,
@@ -3912,13 +4133,17 @@ class Server {
           checkoutData,
           order: pendingOrder,
           response: pendingResult,
-          requireFullyPaid: true
+          requireFullyPaid: true,
+          invoiceLayoutConfig,
+          invoiceTemplateSettings
         });
       }
       await this.dispatchCheckoutSyncTask({
         backendPath,
         data: checkoutData,
-        title
+        title,
+        invoiceLayoutConfig,
+        invoiceTemplateSettings
       });
     }
     if (!pendingResult.data.order_id) {
@@ -3936,7 +4161,9 @@ class Server {
     const {
       backendPath,
       data,
-      title
+      title,
+      invoiceLayoutConfig,
+      invoiceTemplateSettings
     } = params;
     if (!this.app?.request?.post) {
       this.logError(`${title}: sync checkout app.request 不可用`);
@@ -3952,7 +4179,9 @@ class Server {
         backendPath,
         data,
         title,
-        persistCheckoutDataWithResponse: true
+        persistCheckoutDataWithResponse: true,
+        invoiceLayoutConfig,
+        invoiceTemplateSettings
       });
       if (syncResult.rejected) {
         const normalized = this.normalizeCheckoutResponse(syncResult.errorResponse);
@@ -3970,7 +4199,9 @@ class Server {
           checkoutData: syncResult.checkoutData,
           order: syncedOrder,
           response: syncResult.normalizedResponse,
-          requireFullyPaid: true
+          requireFullyPaid: true,
+          invoiceLayoutConfig,
+          invoiceTemplateSettings
           // print_all 的 type=0 是收据打印；不要沿用同步成功后的券/手环打印 type=99。
         });
       }
@@ -4002,9 +4233,16 @@ class Server {
   }
   async handleOrderDraftSubmit(params) {
     const {
-      data,
       title
     } = params;
+    const extractedInvoice = this.extractInvoiceLayoutConfig(params.data, {
+      includePublicInvoice: true
+    });
+    const {
+      data
+    } = this.extractInvoiceTemplateSettings(extractedInvoice.data, {
+      includePublicTemplateSettings: true
+    });
     this.logInfo(`${title}: 开始处理`, {
       order_id: data?.order_id,
       external_sale_number: data?.external_sale_number,
@@ -4488,6 +4726,122 @@ class Server {
       return order;
     }
   }
+  normalizeRemoteSalesOrderErrorCode(value) {
+    if (value === undefined || value === null || value === '') return 500;
+    const code = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(code) ? code : 500;
+  }
+  async fetchAndPersistSalesOrderByLookup(lookup, data, title) {
+    if (!this.order?.getLocalOrderByLookup || !this.order?.upsertOrdersFromRemote) {
+      this.logError(`${title}: Order 模块未注册`);
+      return {
+        code: 500,
+        message: 'Order 模块未注册',
+        order: null
+      };
+    }
+    if (!this.app?.request?.get) {
+      this.logError(`${title}: app.request 不可用`);
+      return {
+        code: 500,
+        message: 'app.request 不可用',
+        order: null
+      };
+    }
+    const backendPath = this.buildOrderSalesDetailBackendPath(String(lookup), data);
+    try {
+      const response = await this.app.request.get(backendPath, {
+        lookup_mode: 'multi'
+      }, {
+        isShopApi: true,
+        customToast: () => {}
+      });
+      if (this.isCheckoutResponseRejected(response)) {
+        const responseStatusCode = typeof response?.status === 'number' ? response.status : undefined;
+        const code = this.normalizeRemoteSalesOrderErrorCode(response?.code ?? responseStatusCode);
+        const message = response?.message || '后端拒绝订单查询';
+        this.logInfo(`${title}: 后端拒绝订单查询`, {
+          lookup,
+          backendPath,
+          code,
+          message
+        });
+        return {
+          code,
+          message,
+          order: null
+        };
+      }
+      const fresh = this.extractOrderDataFromCheckoutResponse(response);
+      if (!fresh || fresh.order_id === undefined || fresh.order_id === null || String(fresh.order_id).trim() === '') {
+        this.logInfo(`${title}: 后端返回订单为空`, {
+          lookup,
+          backendPath
+        });
+        return {
+          code: 500,
+          message: '后端返回订单为空',
+          order: null
+        };
+      }
+      await this.order.upsertOrdersFromRemote([fresh]);
+      let savedOrder = await this.order.getLocalOrderByLookup(lookup);
+      if (!savedOrder && fresh.order_id !== undefined && fresh.order_id !== null && String(fresh.order_id) !== String(lookup)) {
+        savedOrder = await this.order.getLocalOrderByLookup(fresh.order_id);
+      }
+      if (!savedOrder) {
+        this.logError(`${title}: 订单写入后回读失败`, {
+          lookup,
+          remote_order_id: fresh.order_id
+        });
+        return {
+          code: 500,
+          message: '订单写入后回读失败',
+          order: null
+        };
+      }
+      this.logInfo(`${title}: 远端订单已同步到本地`, {
+        lookup,
+        remote_order_id: fresh.order_id
+      });
+      return {
+        code: 200,
+        message: '',
+        order: savedOrder
+      };
+    } catch (error) {
+      const backendError = this.extractBackendErrorResponse(error);
+      const errorRecord = error;
+      const responseStatusCode = typeof errorRecord?.response?.status === 'number' ? errorRecord.response.status : undefined;
+      if (backendError || responseStatusCode !== undefined) {
+        const backendStatusCode = typeof backendError?.status === 'number' ? backendError.status : undefined;
+        const code = this.normalizeRemoteSalesOrderErrorCode(backendError?.code ?? backendStatusCode ?? responseStatusCode);
+        const message = backendError?.message || this.getUnknownErrorMessage(error);
+        this.logInfo(`${title}: 后端订单查询失败`, {
+          lookup,
+          backendPath,
+          code,
+          message
+        });
+        return {
+          code,
+          message,
+          order: null
+        };
+      }
+      const message = this.getUnknownErrorMessage(error);
+      this.logInfo(`${title}: 请求失败`, {
+        lookup,
+        backendPath,
+        error: message
+      });
+      return {
+        code: 500,
+        message,
+        order: null
+      };
+    }
+  }
   handleOrderSalesDetail = async ({
     url,
     data,
@@ -4536,73 +4890,22 @@ class Server {
         };
       }
     }
-    if (!this.app?.request) {
-      this.logError('handleOrderSalesDetail: app.request 不可用');
+    const remoteResult = await this.fetchAndPersistSalesOrderByLookup(lookup, data, 'handleOrderSalesDetail');
+    if (!remoteResult.order) {
       return {
-        code: 500,
+        code: remoteResult.code,
         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,
+        message: remoteResult.message,
         data: null
       };
     }
+    const enrichedOrder = await this.withSalesDetailProductSnapshots(remoteResult.order);
+    return {
+      code: 200,
+      status: true,
+      message: '',
+      data: enrichedOrder
+    };
   };
 
   /**