@pisell/pisellos 2.3.138 → 2.3.140

package/lib/shared/receipt/small-ticket.js

@@ -10,6 +10,46 @@ var _decimal = _interopRequireDefault(require("decimal.js"));
 var _pickupTiming = require("../../modules/Order/pickupTiming");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 const DEFAULT_LOCALES = ['en', 'zh_CN'];
+
+// Attach provenance to a private copy BEFORE any locale-dependent filtering.
+// Symbols survive the existing spread-based normalization, never enter JSON,
+// and leave both the caller's snapshot and the default native contract intact.
+const RECEIPT_SOURCE = Symbol('customerReceiptSource');
+function copyReceiptSource(value, path = 'order') {
+  if (Array.isArray(value)) return value.map((item, index) => copyReceiptSource(item, `${path}/${index}`));
+  if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) return value;
+  const id = value.metadata?.unique_identification_number ?? value.product_uid ?? value.booking_uid ?? value.order_payment_id ?? value.payment_number ?? value.order_refund_id ?? value.refund_number ?? value.id;
+  const source = Object.fromEntries(Object.entries(value).map(([key, item]) => [key, copyReceiptSource(item, `${path}/${key}`)]));
+  // Retain the original occurrence even when a catalogue ID appears twice.
+  return {
+    ...source,
+    [RECEIPT_SOURCE]: `${path}${id != null ? `@${encodeURIComponent(String(id))}` : ''}`
+  };
+}
+function receiptKey(source, kind, valueKind = 'shared') {
+  const key = source?.[RECEIPT_SOURCE];
+  return typeof key === 'string' ? {
+    receipt_key: `${key}#${kind}`,
+    receipt_value_kind: valueKind
+  } : {};
+}
+function receiptSourceIndex(source, index) {
+  return source?.[RECEIPT_SOURCE] ? {
+    receipt_source_index: index
+  } : {};
+}
+function removePrivateReceiptSource(value) {
+  if (!value || typeof value !== 'object') return;
+  delete value[RECEIPT_SOURCE];
+  Object.values(value).forEach(removePrivateReceiptSource);
+}
+function receiptTimeKey(source, kind) {
+  const identity = receiptKey(source, kind);
+  return identity.receipt_key ? {
+    ...identity,
+    receipt_item_kind: 'shared'
+  } : {};
+}
 const SERVICE_TYPE_LABEL_KEYS = {
   takeaway: 'takeAway',
   pick_up: 'pickUp',
@@ -247,11 +287,11 @@ const LABELS = {
   }
 };
 function buildSmallTicketData(params) {
-  const order = params.order || {};
+  const order = params.includeReceiptKeys ? copyReceiptSource(params.order || {}) : params.order || {};
   const shopInfo = params.shopInfo || {};
   const locales = resolveLocales(shopInfo, params.locales);
   const productMap = params.productMap || {};
-  return locales.reduce((data, locale) => {
+  const result = locales.reduce((data, locale) => {
     data[locale] = buildLocaleData({
       order,
       shopInfo,
@@ -260,6 +300,8 @@ function buildSmallTicketData(params) {
     });
     return data;
   }, {});
+  if (params.includeReceiptKeys) removePrivateReceiptSource(result);
+  return result;
 }
 function hasSmallTicketData(value) {
   return !!value && typeof value === 'object' && Object.keys(value).length > 0;
@@ -310,7 +352,10 @@ function buildLocaleData(params) {
       locale,
       currencySymbol
     }),
-    tickets: Array.isArray(order.tickets) ? order.tickets : [],
+    tickets: Array.isArray(order.tickets) ? order.tickets.map(group => Array.isArray(group) ? group.map(row => row && typeof row === 'object' ? {
+      ...row,
+      ...receiptKey(row, 'ticket')
+    } : row) : group) : [],
     source_shop: [],
     refund_data: buildRefundData({
       order,
@@ -354,7 +399,7 @@ function buildBaseData(params) {
 function buildProducts(order, locale, productMap) {
   const products = Array.isArray(order.products) ? order.products : [];
   const allergyByProductUid = buildProductAllergyMap(order, locale);
-  return products.map(rawProduct => {
+  return products.map((rawProduct, sourceIndex) => {
     const product = restoreReceiptDiscountHierarchy(rawProduct);
     const quantity = toNumber(product.product_quantity ?? product.quantity ?? product.num ?? 1, 1);
     const originalPrice = product.original_price ?? product.selling_price ?? product.payment_price ?? product.price ?? 0;
@@ -399,6 +444,10 @@ function buildProducts(order, locale, productMap) {
     const resolvedCombinations = Array.isArray(product.combinations) && product.combinations.length ? normalizeExistingCombinations(product.combinations, locale, currencySymbol) : combinations;
     const shouldIncludeBasePrice = options.length > 0 || resolvedCombinations.length > 0 || hasProductDiscount(product, extensionList);
     return {
+      ...receiptKey(rawProduct, 'product'),
+      ...(rawProduct[RECEIPT_SOURCE] ? {
+        receipt_source_index: sourceIndex
+      } : {}),
       product_title: productTitle,
       product_quantity: quantity,
       selling_price: formatMoney(sellingPrice, currencySymbol),
@@ -542,6 +591,7 @@ function normalizeProductDiscounts(params) {
     const totalAmount = new _decimal.default(toMoneyNumber(amount)).mul(isAggregatedBundleDiscount || isEntitlementPass ? 1 : quantity);
     const formattedAmount = isMarkup ? formatMoney(totalAmount.abs(), currencySymbol) : formatNegativeMoney(totalAmount, currencySymbol);
     return {
+      ...receiptKey(discount, 'discount'),
       item: title,
       value: formattedAmount,
       isMarkup
@@ -581,6 +631,7 @@ function buildProductExtensionList(params) {
     locale,
     currencySymbol
   }), ...(quantity > 1 ? [{
+    ...receiptTimeKey(product, 'quantity-price'),
     item: buildProductQuantityPriceText({
       quantity,
       currencySymbol,
@@ -588,7 +639,10 @@ function buildProductExtensionList(params) {
     }),
     value: ''
   }] : [])];
-  const productExtensionList = extensionList.length ? extensionList : normalizeArray(product.extension_list);
+  const productExtensionList = extensionList.length ? extensionList : normalizeArray(product.extension_list).map(row => ({
+    ...row,
+    ...receiptKey(row, 'extension')
+  }));
   return [...productExtensionList, ...discountList];
 }
 function buildProductOpenWeightRows(params) {
@@ -605,10 +659,12 @@ function buildProductOpenWeightRows(params) {
   const rows = [];
   if (hasTare) {
     rows.push({
+      ...receiptKey(product, 'gross'),
       item: `${manualFlag}${label(locale, 'gross')}: ${productSku.weight ?? 0}${unit}`,
       value: ''
     });
     rows.push({
+      ...receiptKey(product, 'tare'),
       item: `${label(locale, 'tare')}: ${productSku.tare_weight}${unit}`,
       value: ''
     });
@@ -617,6 +673,7 @@ function buildProductOpenWeightRows(params) {
   const unitPrice = productSku.unit_price ?? 0;
   const netItem = `${netWeight} ${unit} NET @ ${currencySymbol}${unitPrice}/${unit}`;
   rows.push({
+    ...receiptTimeKey(product, 'net-weight'),
     item: hasTare ? netItem : `${manualFlag}${netItem}`,
     value: ''
   });
@@ -672,7 +729,7 @@ function normalizeProductOptions(params) {
     parentProduct
   } = params;
   const rawOptions = Array.isArray(params.options) ? params.options : Array.isArray(product.options) ? product.options : Array.isArray(product.product_sku?.option) ? product.product_sku.option : [];
-  return rawOptions.map(option => {
+  return rawOptions.map((option, sourceIndex) => {
     const price = option.original_price ?? option.add_price ?? option.price;
     const quantity = toNumber(option.num ?? option.quantity ?? 1, 1);
     const value = option.value ?? option.option ?? option.item;
@@ -682,6 +739,8 @@ function normalizeProductOptions(params) {
       locale
     });
     return {
+      ...receiptKey(option, 'option'),
+      ...receiptSourceIndex(option, sourceIndex),
       name,
       ...(option.num !== undefined || option.quantity !== undefined ? {
         num: quantity
@@ -705,7 +764,7 @@ function normalizeProductCombinations(params) {
     parentProduct
   } = params;
   const bundles = Array.isArray(product.product_bundle) ? product.product_bundle : [];
-  return bundles.map(bundle => {
+  return bundles.map((bundle, sourceIndex) => {
     const combinationsOptions = normalizeProductOptions({
       product: {},
       locale,
@@ -735,6 +794,8 @@ function normalizeProductCombinations(params) {
     });
     const shouldIncludeBasePrice = combinationsOptions.length > 0 || nestedCombinations.length > 0 || hasProductDiscount(bundle, extensionList);
     return {
+      ...receiptKey(bundle, 'combination'),
+      ...receiptSourceIndex(bundle, sourceIndex),
       product_title: baseTitle,
       product_quantity: quantity,
       price: formattedPrice,
@@ -762,7 +823,7 @@ function normalizeProductCombinations(params) {
   });
 }
 function normalizeExistingCombinations(combinations, locale, currencySymbol) {
-  return combinations.map(combination => {
+  return combinations.map((combination, sourceIndex) => {
     if (!combination || typeof combination !== 'object' || Array.isArray(combination)) {
       return combination;
     }
@@ -799,6 +860,8 @@ function normalizeExistingCombinations(combinations, locale, currencySymbol) {
     const shouldIncludeBasePrice = normalizedOptions.length > 0 || nestedCombinations.length > 0 || hasProductDiscount(combination, extensionList);
     return {
       ...snapshot,
+      ...receiptKey(combination, 'combination'),
+      ...receiptSourceIndex(combination, sourceIndex),
       ...(productTitle ? {
         product_title: productTitle
       } : {}),
@@ -1072,6 +1135,7 @@ function buildFees(params) {
     const value = surcharge.amount ?? surcharge.value ?? surcharge.total_amount;
     if (!isNonZero(value)) continue;
     fees.push({
+      ...receiptKey(surcharge, 'surcharge'),
       item: getLocalizedValue(surcharge.name || surcharge.title || surcharge.item, locale),
       value: formatMoney(value, currencySymbol)
     });
@@ -1079,6 +1143,7 @@ function buildFees(params) {
   const discountAmount = firstPresentValue(order.shop_discount, summary.discount_amount, order.discount_amount);
   if (isNonZero(discountAmount)) {
     fees.push({
+      ...receiptKey(order, 'order-discount'),
       item: label(locale, 'orderDiscount'),
       value: formatNegativeMoney(discountAmount, currencySymbol)
     });
@@ -1095,6 +1160,7 @@ function buildFees(params) {
   const payProcessingFee = financials.payProcessingFee;
   if (isNonZero(payProcessingFee)) {
     fees.push({
+      ...receiptKey(order, 'payment-processing-fee'),
       item: label(locale, 'payProcessingFee'),
       value: formatMoney(payProcessingFee, currencySymbol)
     });
@@ -1176,12 +1242,15 @@ function calculateProductOriginalAmount(order) {
 }
 function buildCustomer(order, locale) {
   return [{
+    ...receiptKey(order, 'customer.contactName'),
     item: label(locale, 'contactName'),
     value: normalizeCustomerDisplayValue(order.customer_name || order.customer?.name || order.customer?.display_name)
   }, {
+    ...receiptKey(order, 'customer.contactMobile'),
     item: label(locale, 'contactMobile'),
     value: stringify(order.phone || order.customer?.phone)
   }, {
+    ...receiptKey(order, 'customer.email'),
     item: label(locale, 'email'),
     value: stringify(order.email || order.customer?.email)
   }];
@@ -1197,6 +1266,7 @@ function buildDelivery(order, locale) {
   const serviceTypeLabelKey = resolveServiceTypeLabelKey(serviceType);
   if (!serviceTypeLabelKey) return [];
   const items = [{
+    ...receiptKey(order, 'service-type'),
     item: label(locale, serviceTypeLabelKey),
     value: '',
     size: 2
@@ -1205,6 +1275,7 @@ function buildDelivery(order, locale) {
     const pickupTime = formatPickupBookingStart(order.bookings, locale);
     if (pickupTime) {
       items.push({
+        ...receiptTimeKey(order, 'pickup-time'),
         item: pickupTime,
         value: '',
         size: 2
@@ -1215,6 +1286,7 @@ function buildDelivery(order, locale) {
   const handoverTime = firstPresentValue(order.handover_time, order.handover_at, order.pickup_time, order.pickup_at, order.scheduled_pickup_time, order.delivery_time, order.delivery_at, order.scheduled_delivery_time, order.fulfillment_time, order.fulfillment_at, order.metadata?.handover_time, order.metadata?.handover_at, order.metadata?.pickup_time, order.metadata?.pickup_at, order.metadata?.scheduled_pickup_time, order.metadata?.delivery_time, order.metadata?.delivery_at, order.metadata?.scheduled_delivery_time, order.metadata?.fulfillment_time, order.metadata?.fulfillment_at);
   if (isPresentId(handoverTime)) {
     items.push({
+      ...receiptKey(order, 'handover-time'),
       item: label(locale, 'handoverTime'),
       value: formatDateTime(handoverTime, locale)
     });
@@ -1254,6 +1326,7 @@ function buildAppointment(order, locale) {
   const tableName = order.table_name || order.metadata?.table_name || order.metadata?.table?.name || order.form_data?.table_name;
   if (!tableName) return [];
   return [{
+    ...receiptKey(order, 'table', 'text'),
     item: label(locale, 'table'),
     value: getLocalizedValue(tableName, locale)
   }];
@@ -1289,18 +1362,22 @@ function buildAppointmentRows(params) {
   const resourceText = formatBookingResources(resolveBookingResourcesForReceipt(booking, allResources, bookingCount), locale);
   const holder = getLocalizedValue(booking.holder?.name ?? booking.metadata?.holder?.name, locale).trim();
   return [{
+    ...receiptKey(booking, 'booking-id'),
     item: label(locale, 'bookingId'),
     value: bookingId,
     ...association
   }, {
+    ...receiptKey(booking, 'booking-time', 'shared'),
     item: label(locale, 'bookingDateTime'),
     value: bookingTime,
     ...association
   }, {
+    ...receiptKey(booking, 'booking-resource', 'text'),
     item: label(locale, 'bookingResource'),
     value: resourceText,
     ...association
   }, {
+    ...receiptKey(booking, 'booking-holder', 'text'),
     item: label(locale, 'bookingHolder'),
     value: holder,
     ...association
@@ -1386,6 +1463,7 @@ function compareOptionalValues(left, right) {
 }
 function buildResources(order, locale) {
   return normalizeArray(order.resources || order.resource_list).map(resource => ({
+    ...receiptKey(resource, 'resource', 'text'),
     id: resource.id || resource.resource_id || '',
     code: '',
     title: getLocalizedValue(resource.title || resource.name, locale),
@@ -1431,12 +1509,14 @@ function buildRefundData(params) {
     const methodName = paymentMethodName(payment, params.locale) || label(params.locale, 'refund');
     const amount = firstPresentValue(refund.amount, refund.refund_amount, refund.total_amount) ?? 0;
     const items = [{
+      ...receiptKey(refund, 'refund'),
       item: methodName,
       value: formatNegativeMoney(amount, params.currencySymbol)
     }];
     const occurredAt = firstPresentValue(refund.refund_time, refund.refunded_at, refund.created_at, refund.updated_at);
     if (isPresentId(occurredAt)) {
       items.push({
+        ...receiptTimeKey(refund, 'refund-time'),
         item: formatDateTime(occurredAt, params.locale),
         value: ''
       });
@@ -1551,15 +1631,18 @@ function buildProductDiscountAssets(params) {
     const name = getProductWalletDiscountName(asset, params.locale);
     const assetTime = getProductWalletDiscountTime(asset) ?? fallbackAssetTime;
     const timeRow = isPresentId(assetTime) ? {
+      ...receiptTimeKey(asset.records[0], 'asset-time'),
       item: formatDateTime(assetTime, params.locale),
       value: ''
     } : null;
     if (asset.type === 'entitlement_pass') {
       const remaining = getProductEntitlementBalance(asset);
       return [[{
+        ...receiptKey(asset.records[0], 'asset-name'),
         item: name,
         value: ''
       }, ...(remaining ? [{
+        ...receiptKey(asset.records[0], 'entitlementRemaining'),
         item: label(params.locale, 'entitlementRemaining'),
         value: formatEntitlementUses(remaining, params.locale)
       }] : []), ...(timeRow ? [timeRow] : [])]];
@@ -1567,15 +1650,18 @@ function buildProductDiscountAssets(params) {
     const percent = getProductWalletDiscountPercent(asset);
     if (percent) {
       return [[{
+        ...receiptKey(asset.records[0], 'asset-discount'),
         item: appendPercentToVoucherName(name, percent),
         value: formatVoucherDiscount(percent, params.locale)
       }, ...(timeRow ? [timeRow] : [])]];
     }
     const balance = getProductWalletMoneyBalance(asset);
     return [[{
+      ...receiptKey(asset.records[0], 'asset-name'),
       item: name,
       value: ''
     }, ...(balance ? [{
+      ...receiptKey(asset.records[0], 'balance'),
       item: label(params.locale, 'balance'),
       value: formatMoney(balance, params.currencySymbol)
     }] : []), ...(timeRow ? [timeRow] : [])]];
@@ -1737,18 +1823,21 @@ function buildPointCardSnapshotAssets(params) {
       codes: []
     })) return [];
     const rows = [{
+      ...receiptKey(pointCard, 'asset-name'),
       item: appendMaskedCardCode(stringify(pointCard.product_name).trim() || label(params.locale, 'pointCard'), pointCard.code),
       value: ''
     }];
     const remainingPoints = getPointCardSnapshotRemainingPoints(pointCard);
     if (remainingPoints) {
       rows.push({
+        ...receiptKey(pointCard, 'remainingPoints'),
         item: label(params.locale, 'remainingPoints'),
         value: trimDecimal(remainingPoints)
       });
     }
     if (isPresentId(snapshotTime)) {
       rows.push({
+        ...receiptTimeKey(pointCard, 'asset-time'),
         item: formatDateTime(snapshotTime, params.locale),
         value: ''
       });
@@ -1797,18 +1886,21 @@ function buildVirtualCurrencySnapshotAssets(params) {
       codes: []
     })) return [];
     const rows = [{
+      ...receiptKey(virtualCurrency, 'asset-name'),
       item: stringify(virtualCurrency.product_name).trim(),
       value: ''
     }];
     const balance = getVirtualCurrencySnapshotBalance(virtualCurrency);
     if (balance) {
       rows.push({
+        ...receiptKey(virtualCurrency, 'balance'),
         item: label(params.locale, 'balance'),
         value: formatVirtualCurrencyBalance(balance, getVirtualCurrencySnapshotUnit(virtualCurrency, params.locale))
       });
     }
     if (isPresentId(snapshotTime)) {
       rows.push({
+        ...receiptTimeKey(virtualCurrency, 'asset-time'),
         item: formatDateTime(snapshotTime, params.locale),
         value: ''
       });
@@ -1903,15 +1995,18 @@ function buildVoucherAssets(params) {
     const name = getVoucherAssetName(voucher, params.locale);
     const assetTime = firstPresentValue(voucher.updated_at, voucher.created_at, voucher.collection_time, fallbackAssetTime);
     const timeRow = isPresentId(assetTime) ? {
+      ...receiptTimeKey(voucher, 'asset-time'),
       item: formatDateTime(assetTime, params.locale),
       value: ''
     } : null;
     if (isEntitlementVoucher(voucher)) {
       const remaining = getEntitlementBalance(voucher.metadata?.balance, voucher.balance);
       return [[{
+        ...receiptKey(voucher, 'asset-name'),
         item: name,
         value: ''
       }, ...(remaining ? [{
+        ...receiptKey(voucher, 'entitlementRemaining'),
         item: label(params.locale, 'entitlementRemaining'),
         value: formatEntitlementUses(remaining, params.locale)
       }] : []), ...(timeRow ? [timeRow] : [])]];
@@ -1919,9 +2014,11 @@ function buildVoucherAssets(params) {
     if (isTicketVoucher(voucher)) {
       const validity = getVoucherValidity(voucher, params.locale);
       return [[{
+        ...receiptKey(voucher, 'asset-name'),
         item: name,
         value: ''
       }, ...(validity ? [{
+        ...receiptKey(voucher, 'validity'),
         item: label(params.locale, 'validity'),
         value: validity
       }] : [])]];
@@ -1929,15 +2026,18 @@ function buildVoucherAssets(params) {
     const percent = getVoucherDiscountPercent(voucher);
     if (percent) {
       return [[{
+        ...receiptKey(voucher, 'asset-discount'),
         item: appendPercentToVoucherName(name, percent),
         value: formatVoucherDiscount(percent, params.locale)
       }, ...(timeRow ? [timeRow] : [])]];
     }
     const balance = getVoucherBalance(voucher);
     return [[{
+      ...receiptKey(voucher, 'asset-name'),
       item: name,
       value: ''
     }, {
+      ...receiptKey(voucher, 'balance'),
       item: label(params.locale, 'balance'),
       value: formatMoney(balance, params.currencySymbol)
     }, ...(timeRow ? [timeRow] : [])]];
@@ -2071,6 +2171,7 @@ function buildPaymentItems(params) {
   } = params;
   const serviceFee = getPaymentServiceFee(payment);
   const items = [{
+    ...receiptKey(payment, 'payment'),
     item: paymentMethodName(payment, locale),
     value: includePaymentAmount ? formatMoney(resolveReceiptPaymentAmount(payment, serviceFee), currencySymbol) : ''
   }];
@@ -2081,6 +2182,7 @@ function buildPaymentItems(params) {
   }));
   if (serviceFee.gt(0)) {
     items.push({
+      ...receiptKey(payment, 'surchargeIncluded'),
       item: label(locale, 'surchargeIncluded'),
       value: formatMoney(serviceFee, currencySymbol)
     });
@@ -2100,16 +2202,21 @@ function buildPaymentItems(params) {
     const remainingAmount = payment.remaining_amount ?? payment.balance ?? payment.metadata?.remaining_amount;
     if (remainingAmount !== undefined && remainingAmount !== null) {
       items.push({
+        ...receiptKey(payment, 'remainingAmount'),
         item: label(locale, 'remainingAmount'),
         value: formatMoney(remainingAmount, currencySymbol)
       });
     }
   }
   items.push({
+    ...receiptTimeKey(payment, 'payment-time'),
     item: formatDateTime(payment.paid_at || payment.created_at || payment.updated_at || new Date(), locale),
     value: ''
   });
-  return items;
+  return items.map(item => item.receipt_key ? {
+    ...item,
+    receipt_key: `${item.receipt_key}/${includeFundRecordBalance ? 'wallet' : 'history'}`
+  } : item);
 }
 function getPaymentServiceFee(payment) {
   return new _decimal.default(toMoneyNumber(payment.service_fee));
@@ -2130,9 +2237,11 @@ function buildCashChangePaymentItems(params) {
   } = params;
   if (!shouldDisplayCashChange(payment)) return [];
   return [{
+    ...receiptKey(payment, 'cashReceived'),
     item: label(locale, 'cashReceived'),
     value: formatMoney(payment.metadata.actual_paid_amount, currencySymbol)
   }, {
+    ...receiptKey(payment, 'changeDue'),
     item: label(locale, 'changeDue'),
     value: formatMoney(payment.metadata.change_given_amount, currencySymbol)
   }];
@@ -2169,12 +2278,14 @@ function buildFundRecordPaymentItems(params) {
     const usedPoints = new _decimal.default(toMoneyNumber(usingBeforeValue)).minus(toMoneyNumber(usingAfterValue));
     if (includeUsage) {
       items.push({
+        ...receiptKey(payment, 'redeemPoints'),
         item: label(locale, 'redeemPoints'),
         value: trimDecimal(usedPoints)
       });
     }
     if (includeBalance) {
       items.push({
+        ...receiptKey(payment, 'remainingPoints'),
         item: label(locale, 'remainingPoints'),
         value: trimDecimal(new _decimal.default(toMoneyNumber(usingAfterValue)))
       });
@@ -2185,12 +2296,14 @@ function buildFundRecordPaymentItems(params) {
     if (virtualCurrencyUnit !== undefined) {
       if (!isNumericAmount(usingAfterValue)) return items;
       items.push({
+        ...receiptKey(payment, 'balance'),
         item: label(locale, 'balance'),
         value: formatVirtualCurrencyBalance(new _decimal.default(usingAfterValue), virtualCurrencyUnit)
       });
       return items;
     }
     items.push({
+      ...receiptKey(payment, 'balance'),
       item: label(locale, 'balance'),
       value: formatMoney(usingAfterValue, currencySymbol)
     });

package/lib/solution/OrderInvoicePreview/index.d.ts

@@ -1,5 +1,7 @@
 import type { Module, ModuleOptions, PisellCore } from '../../types';
 import { BaseModule } from '../../modules/BaseModule';
+import { type CustomerInvoiceLanguageCode, type CustomerInvoiceLanguageOption } from '../../shared/receipt/customerInvoiceLanguages';
+export type { CustomerInvoiceLanguageCode, CustomerInvoiceLanguageOption, } from '../../shared/receipt/customerInvoiceLanguages';
 import type { InvoiceLayoutConfig } from '../../modules/OpenData';
 import { type SmallTicketData } from '../../shared/receipt/small-ticket';
 export interface OrderInvoicePreviewInput {
@@ -19,6 +21,9 @@ export interface OrderInvoicePreviewResult {
     sourceRevision: string;
     generatedAt: string;
     locale: string;
+    secondaryLocale?: string;
+    languageOptions: CustomerInvoiceLanguageOption[];
+    selectedLanguage: CustomerInvoiceLanguageCode;
     orderId: string | number;
     source: Record<string, any>;
     shop: Record<string, any>;
@@ -40,6 +45,7 @@ export declare class OrderInvoicePreviewImpl extends BaseModule implements Modul
     private disposed;
     private input?;
     private activeKey;
+    private languageSelection?;
     private pending?;
     private snapshotCache;
     constructor(name?: string);
@@ -51,6 +57,10 @@ export declare class OrderInvoicePreviewImpl extends BaseModule implements Modul
     private loadContext;
     private loadSource;
     prepare(input: OrderInvoicePreviewInput): Promise<OrderInvoicePreviewResult>;
+    private getSelectionScope;
+    private documentIdentity;
+    /** Switch only the ready receipt projection; no fetching or rebuilding data. */
+    selectLanguage(code: string): OrderInvoicePreviewResult;
     retry(): Promise<OrderInvoicePreviewResult>;
     destroy(): void;
 }

package/lib/solution/OrderInvoicePreview/index.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.OrderInvoicePreviewImpl = void 0;
 var _BaseModule = require("../../modules/BaseModule");
 var _loadCustomerInvoiceLayout = require("../../shared/receipt/loadCustomerInvoiceLayout");
+var _customerInvoiceLanguages = require("../../shared/receipt/customerInvoiceLanguages");
 var _smallTicket = require("../../shared/receipt/small-ticket");
 var _loadSalesOrderSnapshot = require("../../shared/sales/loadSalesOrderSnapshot");
 var _loadPaymentMethods = require("../../shared/payment/loadPaymentMethods");
@@ -25,6 +26,8 @@ class OrderInvoicePreviewImpl extends _BaseModule.BaseModule {
   disposed = false;
   input;
   activeKey = '';
+  // Hosts retain this readonly instance while the same order modal is closed.
+  languageSelection;
   pending;
   snapshotCache = new Map();
   constructor(name = 'orderInvoicePreview') {
@@ -56,7 +59,7 @@ class OrderInvoicePreviewImpl extends _BaseModule.BaseModule {
       cache = new Map();
       contextCaches.set(this.request, cache);
     }
-    const key = JSON.stringify([input.tenantId, input.shopId, input.identity, input.locale]);
+    const key = JSON.stringify([input.tenantId, input.shopId, input.identity]);
     const cached = cache.get(key);
     if (cached) return cached;
     const task = Promise.all([this.request.get('/shop/show', {}, {
@@ -115,6 +118,7 @@ class OrderInvoicePreviewImpl extends _BaseModule.BaseModule {
       if (this.state.status === 'ready' && this.state.result) return Promise.resolve(this.state.result);
     }
     if (this.input && this.getScope(this.input) !== this.getScope(input)) this.snapshotCache.clear();
+    if (this.languageSelection?.scope !== this.getSelectionScope(input)) this.languageSelection = undefined;
     this.input = input;
     this.activeKey = key;
     const generation = ++this.generation;
@@ -124,7 +128,7 @@ class OrderInvoicePreviewImpl extends _BaseModule.BaseModule {
       error: null
     });
     const task = (async () => {
-      const [snapshot, context, layout] = await Promise.all([this.loadSource(input), this.loadContext(input), (0, _loadCustomerInvoiceLayout.loadCustomerInvoiceLayout)(this.request, input)]);
+      const [snapshot, context, template] = await Promise.all([this.loadSource(input), this.loadContext(input), (0, _loadCustomerInvoiceLayout.loadCustomerInvoiceTemplate)(this.request, input)]);
       const source = (0, _loadPaymentMethods.withPaymentMethodNames)(snapshot, context.methods);
       const getData = this.core.getPlugin('app')?.getData?.();
       if (getData?.('shop_id') != null && String(getData('shop_id')) !== String(input.shopId)) throw new Error('Invoice shop changed');
@@ -139,21 +143,29 @@ class OrderInvoicePreviewImpl extends _BaseModule.BaseModule {
         } : {})
       };
       if (generation !== this.generation || this.disposed) throw new Error('Invoice request superseded');
-      const requestedLocale = input.locale.toLowerCase().replace(/_/g, '-');
-      const locale = requestedLocale.startsWith('zh-tw') || requestedLocale.startsWith('zh-hk') ? 'zh_HK' : requestedLocale.startsWith('zh') ? 'zh_CN' : requestedLocale.startsWith('ja') ? 'ja' : requestedLocale.startsWith('pt') ? 'pt' : 'en';
+      const languageOptions = (0, _customerInvoiceLanguages.resolveCustomerInvoiceLanguages)(template.language, input.locale);
+      const remembered = this.languageSelection?.code;
+      const selected = languageOptions.find(option => option.code === remembered) || languageOptions[0];
+      const locale = selected.locales[0];
       const result = {
-        identity: key,
+        identity: this.documentIdentity(key, selected.code),
+        languageOptions,
+        selectedLanguage: selected.code,
+        ...(selected.locales[1] ? {
+          secondaryLocale: selected.locales[1]
+        } : {}),
         orderId: input.orderId,
         sourceRevision: input.sourceRevision,
         generatedAt: new Date().toISOString(),
         locale,
         source,
         shop,
-        layout,
+        layout: template.layout,
         smallTicketData: (0, _smallTicket.buildSmallTicketData)({
           order: source,
           shopInfo: shop,
-          locales: [locale]
+          locales: [...new Set(languageOptions.flatMap(option => option.locales))],
+          includeReceiptKeys: true
         })
       };
       this.publish({
@@ -177,6 +189,47 @@ class OrderInvoicePreviewImpl extends _BaseModule.BaseModule {
     this.pending = task;
     return task;
   }
+  getSelectionScope(input) {
+    return JSON.stringify([this.getScope(input), input.orderId]);
+  }
+  documentIdentity(key, language) {
+    return JSON.stringify([key, language]);
+  }
+
+  /** Switch only the ready receipt projection; no fetching or rebuilding data. */
+  selectLanguage(code) {
+    if (this.disposed) throw new Error('Invoice preview disposed');
+    const current = this.state.result;
+    if (this.state.status !== 'ready' || !current || !this.input) throw new Error('Invoice preview is not ready');
+    const currentShop = this.core.getPlugin('app')?.getData?.()?.('shop_id');
+    if (currentShop != null && String(currentShop) !== String(this.input.shopId)) throw new Error('Invoice shop changed');
+    const selected = current.languageOptions.find(option => option.code === code);
+    if (!selected) throw new Error('Invoice language is unavailable');
+    this.languageSelection = {
+      scope: this.getSelectionScope(this.input),
+      code: selected.code
+    };
+    if (selected.code === current.selectedLanguage) return current;
+    const {
+      secondaryLocale: _previousSecondary,
+      ...rest
+    } = current;
+    const result = {
+      ...rest,
+      identity: this.documentIdentity(this.activeKey, selected.code),
+      selectedLanguage: selected.code,
+      locale: selected.locales[0],
+      ...(selected.locales[1] ? {
+        secondaryLocale: selected.locales[1]
+      } : {})
+    };
+    this.publish({
+      status: 'ready',
+      result,
+      error: null
+    });
+    return result;
+  }
   retry() {
     if (!this.input) return Promise.reject(new Error('Invoice input is missing'));
     return this.prepare(this.input);