@pisell/pisellos 2.2.302 → 2.2.303

package/lib/server/index.js

@@ -27,6 +27,9 @@ 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 _salesNotes = require("../modules/Order/salesNotes");
+var _orderCollectionIdentity = require("../modules/Order/utils/orderCollectionIdentity");
+var _OpenData = require("../modules/OpenData");
 var _modules = require("./modules");
 Object.keys(_modules).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;
@@ -41,6 +44,8 @@ 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';
 
 // 重新导出类型供外部使用
 
@@ -572,7 +577,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');
@@ -588,7 +602,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 后端明确失败`, {
@@ -627,7 +643,7 @@ class Server {
     } = params;
     const normalizedData = await this.normalizeCheckoutSubmitData(params.data, title);
     const numberedData = await this.ensureCheckoutOrderNumbers(normalizedData, title);
-    const checkoutData = this.applyCheckoutFulfillmentBuzzer(numberedData, title);
+    const checkoutData = this.normalizeCheckoutCollections(this.applyCheckoutFulfillmentBuzzer(numberedData, title));
     const remoteCheckoutData = this.buildRemoteCheckoutData(checkoutData, title);
     const deviceHeaders = await this.buildCheckoutDeviceHeaders(title);
     if (!this.app?.request?.post) {
@@ -675,7 +691,9 @@ class Server {
         checkoutData,
         syncedOrder: printableSyncedOrder,
         response,
-        deviceId: params.deviceId
+        deviceId: params.deviceId,
+        invoiceLayoutConfig: params.invoiceLayoutConfig,
+        invoiceTemplateSettings: params.invoiceTemplateSettings
       });
     }
     return {
@@ -701,6 +719,7 @@ class Server {
     if (!next || typeof next !== 'object') return next;
     const record = next;
     delete record[OS_FULFILLMENT_REF_MODE_FIELD];
+    delete record[OS_INVOICE_LAYOUT_CONFIG_FIELD];
     this.applyKioskCheckoutOperator(record);
     if (!Array.isArray(record.payments)) return next;
     const originalPayments = record.payments;
@@ -1302,6 +1321,10 @@ class Server {
       method: 'post',
       path: '/shop/local/print-order',
       handler: this.handleLocalPrintOrder.bind(this)
+    }, {
+      method: 'post',
+      path: '/shop/local/order-receipt-snapshot',
+      handler: this.handleLocalOrderReceiptSnapshot.bind(this)
     }, {
       method: 'post',
       path: '/shop/local/getLocalPayment',
@@ -2151,10 +2174,12 @@ class Server {
 
   /**
    * 预约查询是否走本地：
+   * - 日历周/月/资源视图通过 compact_fields 显式标识，始终走远端；
    * - 当 sales_time_between 的开始和结束都不是今天时，走远端；
    * - 其余情况走本地。
    */
   shouldUseLocalBookingQuery(data) {
+    if (data?.compact_fields === true) return false;
     const range = data?.sales_time_between;
     if (!Array.isArray(range) || range.length < 2) return true;
     return !this.isRangeBothNotToday(range[0], range[1]);
@@ -3426,6 +3451,80 @@ 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 = {
@@ -3587,14 +3686,16 @@ class Server {
     };
     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;
+    if (!needsShopOrderNumber && !needsShopFullOrderNumber) {
+      return this.finalizeCheckoutSalesNotes(next, title);
+    }
     const idGenerator = this.getIdGeneratorPlugin();
     if (!idGenerator) {
       this.logWarning(`${title}: idGenerator 插件不可用，无法生成订单号`, {
         needsShopOrderNumber,
         needsShopFullOrderNumber
       });
-      return next;
+      return this.finalizeCheckoutSalesNotes(next, title);
     }
     try {
       if (needsShopOrderNumber && idGenerator.generateShopOrderNumber) {
@@ -3616,7 +3717,38 @@ class Server {
         error: error instanceof Error ? error.message : String(error)
       });
     }
-    return next;
+    return this.finalizeCheckoutSalesNotes(next, title);
+  }
+
+  /**
+   * Notes 允许在本地草稿阶段暂存空订单目标；checkout 的统一出口负责用最终
+   * shop_order_number 完成绑定并校验，保证后端请求、pending、设备任务和打印
+   * 都使用同一份完整快照。
+   */
+  finalizeCheckoutSalesNotes(data, title) {
+    if (!data || typeof data !== 'object') return data;
+    if (!Object.prototype.hasOwnProperty.call(data, 'notes')) return data;
+    if (data.notes === undefined || data.notes === null) return data;
+    if (!Array.isArray(data.notes)) {
+      throw new Error('[Order Notes] checkout notes 必须为数组');
+    }
+    if (data.notes.length === 0) return data;
+    const productTargetUuids = (Array.isArray(data.products) ? data.products : []).map(product => product?.metadata?.unique_identification_number ?? product?.unique_identification_number).filter(targetUuid => targetUuid !== undefined && targetUuid !== null && String(targetUuid).trim().length > 0).map(targetUuid => String(targetUuid));
+    const shopOrderNumber = String(data.shop_order_number ?? '').trim();
+    const notes = (0, _salesNotes.finalizeSalesNotesForCheckout)({
+      notes: data.notes,
+      shopOrderNumber,
+      productTargetUuids
+    });
+    this.logInfo(`${title}: checkout Notes 已绑定订单号`, {
+      shop_order_number: shopOrderNumber,
+      note_count: notes.length
+    });
+    return {
+      ...data,
+      shop_order_number: shopOrderNumber,
+      notes
+    };
   }
   async dispatchCheckoutSyncTask(params) {
     this.registerDeviceTaskActions();
@@ -3634,6 +3766,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
         },
@@ -3669,6 +3803,7 @@ class Server {
         device_id: params.deviceId ?? deviceId,
         payload: {
           type: params.isManualPrint ? '0' : '99',
+          template_settings: this.normalizePrintInvoiceTemplateSettings(params.invoiceTemplateSettings),
           data: params.receiptOnly ? {
             order_id: printIdentity,
             small_ticket_data: params.syncedOrder?.payment_info?.small_ticket_data,
@@ -3712,7 +3847,8 @@ class Server {
       };
     }
     const printableOrder = await this.withLocalSmallTicketData(params.order, {
-      requireFullyPaid: params.requireFullyPaid
+      requireFullyPaid: params.requireFullyPaid,
+      invoiceTemplateSettings: params.invoiceTemplateSettings
     });
     if (!(0, _smallTicket.hasSmallTicketData)(printableOrder.payment_info?.small_ticket_data)) {
       return {
@@ -3730,7 +3866,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,
@@ -3750,11 +3888,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,
@@ -3766,13 +3928,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) {
@@ -3797,24 +3959,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,
@@ -3833,7 +3996,9 @@ class Server {
         order: printableOrder,
         response: null,
         requireFullyPaid: false,
-        isManualPrint: true
+        isManualPrint: true,
+        invoiceLayoutConfig,
+        invoiceTemplateSettings
       });
       return {
         code: 200,
@@ -3860,6 +4025,99 @@ class Server {
       };
     }
   };
+  normalizeRequestedReceiptLocales(value) {
+    if (!Array.isArray(value)) return [];
+    return Array.from(new Set(value.filter(locale => typeof locale === 'string').map(locale => locale.trim()).filter(Boolean)));
+  }
+  handleLocalOrderReceiptSnapshot = async ({
+    data
+  }) => {
+    const input = data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+    const lookup = this.getLocalPrintOrderLookup(input);
+    if (lookup === undefined) {
+      return {
+        code: 400,
+        status: false,
+        message: '订单 lookup 缺失',
+        data: {
+          small_ticket_data: null
+        }
+      };
+    }
+    if (!this.order?.getLocalOrderByLookup) {
+      return {
+        code: 500,
+        status: false,
+        message: 'Order 模块未注册',
+        data: {
+          small_ticket_data: null
+        }
+      };
+    }
+    try {
+      let sourceOrder = await this.order.getLocalOrderByLookup(lookup);
+      if (!sourceOrder) {
+        const remoteResult = await this.fetchAndPersistSalesOrderByLookup(lookup, {
+          with: ['all']
+        }, 'handleLocalOrderReceiptSnapshot');
+        if (!remoteResult.order) {
+          return {
+            code: remoteResult.code,
+            status: false,
+            message: remoteResult.message,
+            data: {
+              small_ticket_data: null
+            }
+          };
+        }
+        sourceOrder = remoteResult.order;
+      }
+      const paymentInfo = {
+        ...(sourceOrder.payment_info || {})
+      };
+      delete paymentInfo.small_ticket_data;
+      const rebuiltOrder = await this.withLocalSmallTicketData({
+        ...sourceOrder,
+        small_ticket_data_flag: 1,
+        payment_info: paymentInfo
+      }, {
+        locales: this.normalizeRequestedReceiptLocales(input.locales)
+      });
+      const smallTicketData = rebuiltOrder.payment_info?.small_ticket_data;
+      if (!(0, _smallTicket.hasSmallTicketData)(smallTicketData)) {
+        return {
+          code: 500,
+          status: false,
+          message: '本地小票 Snapshot 生成失败',
+          data: {
+            small_ticket_data: null
+          }
+        };
+      }
+      return {
+        code: 200,
+        status: true,
+        message: '',
+        data: {
+          small_ticket_data: smallTicketData
+        }
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logError('handleLocalOrderReceiptSnapshot: 生成失败', {
+        lookup,
+        error: message
+      });
+      return {
+        code: 500,
+        status: false,
+        message,
+        data: {
+          small_ticket_data: null
+        }
+      };
+    }
+  };
   handleMachinecodeBatchMeta = async ({
     data
   }) => {
@@ -4044,9 +4302,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,
@@ -4057,17 +4323,20 @@ class Server {
       return this.handleSyncCheckoutSubmit({
         backendPath,
         data,
-        title
+        title,
+        invoiceLayoutConfig,
+        invoiceTemplateSettings
       });
     }
     const normalizedData = await this.normalizeCheckoutSubmitData(data, title);
     const numberedData = await this.ensureCheckoutOrderNumbers(normalizedData, title);
-    const checkoutData = this.applyCheckoutFulfillmentBuzzer(numberedData, title);
+    const checkoutData = this.normalizeCheckoutCollections(this.applyCheckoutFulfillmentBuzzer(numberedData, title));
     const pendingResult = await this.handlePendingSyncCheckoutOrder({
       backendPath,
       data: checkoutData,
       title,
-      reason: 'checkout 已转入设备任务同步'
+      reason: 'checkout 已转入设备任务同步',
+      invoiceTemplateSettings
     });
     if (pendingResult?.status === true) {
       const pendingOrder = pendingResult.data;
@@ -4076,13 +4345,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) {
@@ -4100,7 +4373,9 @@ class Server {
     const {
       backendPath,
       data,
-      title
+      title,
+      invoiceLayoutConfig,
+      invoiceTemplateSettings
     } = params;
     if (!this.app?.request?.post) {
       this.logError(`${title}: sync checkout app.request 不可用`);
@@ -4116,7 +4391,9 @@ class Server {
         backendPath,
         data,
         title,
-        persistCheckoutDataWithResponse: true
+        persistCheckoutDataWithResponse: true,
+        invoiceLayoutConfig,
+        invoiceTemplateSettings
       });
       if (syncResult.rejected) {
         const normalized = this.normalizeCheckoutResponse(syncResult.errorResponse);
@@ -4134,7 +4411,9 @@ class Server {
           checkoutData: syncResult.checkoutData,
           order: syncedOrder,
           response: syncResult.normalizedResponse,
-          requireFullyPaid: true
+          requireFullyPaid: true,
+          invoiceLayoutConfig,
+          invoiceTemplateSettings
           // print_all 的 type=0 是收据打印；不要沿用同步成功后的券/手环打印 type=99。
         });
       }
@@ -4166,9 +4445,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,
@@ -4229,9 +4515,10 @@ class Server {
       backendPath,
       data,
       title,
-      reason
+      reason,
+      invoiceTemplateSettings
     } = params;
-    const pendingOrder = await this.buildPendingSyncCheckoutOrder(data);
+    const pendingOrder = await this.buildPendingSyncCheckoutOrder(data, invoiceTemplateSettings);
     if (!pendingOrder) {
       this.logError(`${title}: checkout 失败且订单缺少本地存储标识`, {
         backendPath,
@@ -4297,23 +4584,39 @@ class Server {
       };
     }
   }
-  async buildPendingSyncCheckoutOrder(data) {
+  async buildPendingSyncCheckoutOrder(data, invoiceTemplateSettings) {
     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 = {
+    const pendingOrder = this.normalizeCheckoutCollections({
       ...data,
       need_sync: 1,
       is_draft_order: 0
-    };
+    });
     const productMap = await this.buildSmallTicketProductMap(pendingOrder);
     const orderWithProductTitles = this.withPendingSyncProductTitles(pendingOrder, productMap);
     return this.withLocalSmallTicketData(orderWithProductTitles, {
       requireFullyPaid: true,
-      productMap
+      productMap,
+      invoiceTemplateSettings
     });
   }
 
+  /**
+   * Checkout 与本地小票必须消费同一份规范化子项快照。
+   * 商品/预约只折叠持久化 ID 或协议 UID 相同的行；支付额外兼容 payment_number。
+   */
+  normalizeCheckoutCollections(data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return data;
+    const normalized = (0, _orderCollectionIdentity.normalizeOrderCollections)(data, {
+      ensureUid: false
+    }).order;
+    if (Array.isArray(normalized.payments)) {
+      normalized.payments = (0, _paymentUtils.mergeOrderPaymentListsByIdentity)([], normalized.payments);
+    }
+    return normalized;
+  }
+
   /**
    * Android 结账自动小票由当前设备设置控制；其它平台保持原有行为。
    */
@@ -4631,11 +4934,27 @@ class Server {
     if (!this.shouldBuildSmallTicketData(order)) return order;
     if (options?.requireFullyPaid && !this.isSalesOrderFullyPaid(order)) return order;
     try {
-      const enrichedOrder = await this.enrichPaymentNamesByCode(order);
+      const normalizedCollections = (0, _orderCollectionIdentity.normalizeOrderCollections)(order, {
+        ensureUid: false
+      });
+      const normalizedOrder = normalizedCollections.order;
+      const collapsedDuplicateCounts = {
+        products: normalizedCollections.stats.product.collapsedDuplicateCount,
+        bookings: normalizedCollections.stats.booking.collapsedDuplicateCount,
+        payments: normalizedCollections.stats.payment.collapsedDuplicateCount
+      };
+      if (Object.values(collapsedDuplicateCounts).some(count => count > 0)) {
+        this.logWarning('withLocalSmallTicketData: 折叠重复订单子项', {
+          order_identifier: normalizedOrder.order_id ?? normalizedOrder.external_sale_number ?? normalizedOrder.shop_order_number ?? null,
+          collapsed_duplicate_counts: collapsedDuplicateCounts
+        });
+      }
+      const enrichedOrder = await this.enrichPaymentNamesByCode(normalizedOrder);
       const productMap = options?.productMap ?? (await this.buildSmallTicketProductMap(enrichedOrder));
       const smallTicketData = (0, _smallTicket.buildSmallTicketData)({
         order: enrichedOrder,
         shopInfo: this.getSmallTicketShopInfo(),
+        locales: [...(0, _OpenData.resolveInvoiceReceiptLocales)(options?.invoiceTemplateSettings), ...(options?.locales || [])],
         productMap
       });
       return {
@@ -4652,6 +4971,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,
@@ -4700,73 +5135,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
+    };
   };
 
   /**