@pisell/pisellos 2.2.291 → 2.2.293

package/lib/modules/Order/index.d.ts

@@ -3,7 +3,7 @@ import { BaseModule } from '../BaseModule';
 import { OrderModuleAPI, CommitOrderParams, UpdateOrderBookingParams, UpdateOrderProductParams, UpdateOrderProductQuantityParams, CancelOrderParams, ChangeBookingStatusParams, CheckoutOrderParams } from './types';
 import { CartItem } from '../Cart/types';
 import { type SubmitPayloadEnhancer } from './utils';
-import type { OrderAmountSnapshot, AddProductBookingInput, AddProductToOrderOptions, OrderIdentitySnapshot, OrderPaymentSource, OrderSnapshot, OrderSyncState, SyncPaymentsToOrderParams, SyncPaymentsToOrderResult, SubmitSalesOrderParams, OrderProduct, OrderProductIdentity, OrderSummary, OrderTempOrder, OrderPaymentData, OrderPaymentUpdateOptions, OrderPaymentUpdateResult, SendCustomerPayLinkParams, UpdateTempOrderCustomerInput, OrderCustomerPatch, OrderCustomerView, ReplaceTempOrderOptions, OrderPromotionEvaluator, OrderGiftSelectResolver, OrderUnfulfilledPromotion, OrderLastGiftActions, RemoveProductsFromOrderOptions } from './types';
+import type { OrderAmountSnapshot, AddProductBookingInput, AddProductToOrderOptions, OrderIdentitySnapshot, OrderPaymentSource, OrderSnapshot, OrderSyncState, SyncPaymentsToOrderParams, SyncPaymentsToOrderResult, SubmitSalesOrderParams, OrderProduct, OrderProductIdentity, OrderSummary, OrderTempOrder, OrderPaymentData, OrderPaymentUpdateOptions, OrderPaymentUpdateResult, SendCustomerPayLinkParams, UpdateTempOrderCustomerInput, OrderCustomerPatch, OrderCustomerView, ReplaceTempOrderOptions, OrderPromotionEvaluator, OrderGiftSelectResolver, OrderUnfulfilledPromotion, OrderLastGiftActions, RemoveProductsFromOrderOptions, SalesNote, SalesNotesMutationSnapshot, SetSalesNoteInput, PickupReferenceMode, ShopServiceData, ShopServiceType } from './types';
 import type { ICustomer } from '../AccountList/types';
 import type { Discount } from '../Discount/types';
 import { UnavailableReason } from '../Rules/types';
@@ -301,9 +301,24 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     updateTempOrderNote(note: string, sync: boolean): string | Promise<string>;
     syncTempOrderNoteToRemote(orderId: number | string, note: string): Promise<string>;
     getTempOrderNote(): string;
+    private ensureSalesNotesRuntimeState;
+    private ensureSalesNotesLoadedForMutation;
+    private normalizeSalesNoteUuid;
+    private getSalesNotePrimaryRelation;
+    private removeSalesNotesForMissingProductLines;
+    private setSalesNoteOnTempOrder;
+    getSalesNotes(): SalesNote[];
+    createSalesNotesMutationSnapshot(): SalesNotesMutationSnapshot;
+    restoreSalesNotesMutationSnapshot(snapshot: SalesNotesMutationSnapshot): void;
+    setSalesNote(input: SetSalesNoteInput): Promise<SalesNote>;
+    removeSalesNote(uuid: string): Promise<void>;
+    clearSalesNotes(): Promise<void>;
     updateTempOrderShopDiscount(amount: string | number): string;
     updateTempOrderDepositAmount(amount: string | number): OrderSummary;
     updateTempOrderBuzzer(buzzer: string): string;
+    private updateTempOrderShopServiceData;
+    updateTempOrderPickupReferenceMode(mode: PickupReferenceMode): ShopServiceData;
+    updateTempOrderServiceType(serviceType: ShopServiceType): ShopServiceData;
     updateTempOrderContactsInfo(contactsInfo: Record<string, any> | null): Record<string, any> | null;
     private buildTempOrderCustomer;
     private isCustomerBoundDiscount;
@@ -454,7 +469,7 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     removeProductFromOrder(identity: OrderProductIdentity, options?: RemoveProductsFromOrderOptions): Promise<OrderProduct[]>;
     /**
      * 仅清空购物车行（products / bookings），不重置整单。
-     * 用于「仅清空商品」；客户、备注、支付等协议字段保持不变。
+     * 普通整单 note 保持不变；以商品行为主体的 Sales Notes 同步删除。
      */
     clearOrderCartLines(): Promise<OrderTempOrder>;
     buildCurrentSubmitPayloadForLocalPrint(params?: {
@@ -591,4 +606,4 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     getOrderInfo(order_id: number): Promise<any>;
     getVouchers(): any[];
 }
-export type { AddProductToOrderOptions, RemoveProductsFromOrderOptions, UpdateOrderBookingParams, UpdateOrderProductParams, UpdateOrderProductQuantityParams, } from './types';
+export type { AddProductToOrderOptions, RemoveProductsFromOrderOptions, SalesNote, SalesNoteDraftInput, SalesNoteLocalizedSelection, SalesNoteLocalizedText, SalesNoteRelation, SalesNoteTextInput, SetSalesNoteInput, UpdateOrderBookingParams, UpdateOrderProductParams, UpdateOrderProductQuantityParams, } from './types';

package/lib/modules/Order/index.js

@@ -9,6 +9,7 @@ var _types = require("./types");
 var _utils = require("./utils");
 var _utils2 = require("../Product/utils");
 var _dayjs = _interopRequireDefault(require("dayjs"));
+var _salesNotes = require("./salesNotes");
 var _paymentUtils = require("./payment-utils");
 var _paymentNumber = require("../../utils/payment-number");
 var _cartPromotion = require("../../solution/BaseSales/utils/cartPromotion");
@@ -904,6 +905,7 @@ class OrderModule extends _BaseModule.BaseModule {
     this.store.tempOrder = {
       ...this.store.tempOrder,
       products: [...this.store.tempOrder.products],
+      notes: [...(this.store.tempOrder.notes || [])],
       bookings: this.store.tempOrder.bookings ? [...this.store.tempOrder.bookings] : []
     };
     this.persistTempOrder();
@@ -2236,6 +2238,179 @@ class OrderModule extends _BaseModule.BaseModule {
   getTempOrderNote() {
     return this.store.tempOrder?.note || '';
   }
+  ensureSalesNotesRuntimeState(tempOrder) {
+    const hadNotesSnapshot = Array.isArray(tempOrder.notes);
+    if (!Array.isArray(tempOrder.notes)) tempOrder.notes = [];
+    if (!tempOrder._extend || typeof tempOrder._extend !== 'object') {
+      tempOrder._extend = {
+        productsByUid: {}
+      };
+    }
+    if (!tempOrder._extend.salesNotesState) {
+      tempOrder._extend.salesNotesState = {
+        loaded: hadNotesSnapshot,
+        dirty: false
+      };
+    }
+    return tempOrder._extend.salesNotesState;
+  }
+  ensureSalesNotesLoadedForMutation(tempOrder) {
+    const state = this.ensureSalesNotesRuntimeState(tempOrder);
+    if (state.loaded) return;
+    if (tempOrder.order_id === null || tempOrder.order_id === undefined) {
+      state.loaded = true;
+      tempOrder.notes = [];
+      return;
+    }
+    throw new Error('[Order Notes] 当前订单 Notes 尚未完整加载，禁止提交部分快照');
+  }
+  normalizeSalesNoteUuid(value, field) {
+    const uuid = String(value ?? '').trim();
+    if (!uuid) throw new Error(`[Order Notes] ${field} 不能为空`);
+    if (uuid.length > 255) {
+      throw new Error(`[Order Notes] ${field} 不能超过 255 个字符`);
+    }
+    return uuid;
+  }
+  getSalesNotePrimaryRelation(note) {
+    return note.note_relations.find(relation => relation.is_primary === 1) || null;
+  }
+  removeSalesNotesForMissingProductLines(tempOrder) {
+    const state = this.ensureSalesNotesRuntimeState(tempOrder);
+    if (!state.loaded || !Array.isArray(tempOrder.notes) || tempOrder.notes.length === 0) {
+      return;
+    }
+    const remainingProductUids = new Set((tempOrder.products || []).map(product => product.metadata?.unique_identification_number || product.unique_identification_number).filter(uid => typeof uid === 'string' && uid.length > 0));
+    const nextNotes = tempOrder.notes.filter(note => {
+      const primary = this.getSalesNotePrimaryRelation(note);
+      if (!primary || primary.target_type !== 'order_detail') return true;
+      return remainingProductUids.has(primary.target_uuid);
+    });
+    if (nextNotes.length === tempOrder.notes.length) return;
+    tempOrder.notes = nextNotes;
+    state.dirty = true;
+  }
+  setSalesNoteOnTempOrder(tempOrder, input) {
+    this.ensureSalesNotesLoadedForMutation(tempOrder);
+    const note_type = String(input.note_type || '').trim();
+    const policy = (0, _salesNotes.getSalesNotePolicy)(note_type);
+    if (!policy) {
+      throw new Error(`[Order Notes] 当前未注册备注类型: ${note_type || '(empty)'}`);
+    }
+    if (input.target?.target_type !== 'order_detail') {
+      throw new Error('[Order Notes] 本期只支持 order_detail 作为主体');
+    }
+    const target_uuid = this.normalizeSalesNoteUuid(input.target.target_uuid, 'target_uuid');
+    const targetProductExists = (tempOrder.products || []).some(product => {
+      const productLineUid = product.metadata?.unique_identification_number || product.unique_identification_number;
+      return String(productLineUid ?? '') === target_uuid;
+    });
+    if (!targetProductExists) {
+      throw new Error('[Order Notes] 目标商品行不存在');
+    }
+    const text = (0, _salesNotes.buildSalesNoteText)(input.text);
+    const notes = tempOrder.notes || [];
+    // 当前 allergy policy 固定同一商品行只保留一条；业务调用方不参与去重规则。
+    const existingIndex = policy.uniquePerPrimaryTarget ? notes.findIndex(note => {
+      const primary = this.getSalesNotePrimaryRelation(note);
+      return note.note_type === note_type && primary?.target_type === 'order_detail' && primary.target_uuid === target_uuid;
+    }) : -1;
+    const existing = existingIndex >= 0 ? notes[existingIndex] : null;
+    const existingPrimary = existing?.note_relations.find(relation => relation.is_primary === 1 && relation.target_type === 'order_detail');
+    const existingOrderRelation = existing?.note_relations.find(relation => relation.is_primary === 0 && relation.target_type === 'order');
+    const note = {
+      uuid: existing?.uuid || (0, _utils.createUuidV4)(),
+      note_type: policy.note_type,
+      content: {
+        text
+      },
+      importance: policy.importance,
+      note_relations: [{
+        uuid: existingPrimary?.uuid || (0, _utils.createUuidV4)(),
+        relation_type: policy.primary_relation_type,
+        target_type: 'order_detail',
+        target_uuid,
+        is_primary: 1
+      }, {
+        uuid: existingOrderRelation?.uuid || (0, _utils.createUuidV4)(),
+        relation_type: policy.secondary_order_relation_type,
+        target_type: 'order',
+        target_uuid: String(tempOrder.shop_order_number ?? ''),
+        is_primary: 0
+      }]
+    };
+    const duplicateIndex = notes.findIndex((item, index) => item.uuid === note.uuid && index !== existingIndex);
+    if (duplicateIndex >= 0) {
+      throw new Error('[Order Notes] uuid 已被其他 Note 使用');
+    }
+    tempOrder.notes = existingIndex >= 0 ? notes.map((item, index) => index === existingIndex ? note : item) : [...notes, note];
+    const state = this.ensureSalesNotesRuntimeState(tempOrder);
+    state.loaded = true;
+    state.dirty = true;
+    return note;
+  }
+  getSalesNotes() {
+    const tempOrder = this.ensureTempOrder();
+    this.ensureSalesNotesRuntimeState(tempOrder);
+    return (0, _lodashEs.cloneDeep)(tempOrder.notes || []);
+  }
+  createSalesNotesMutationSnapshot() {
+    const tempOrder = this.ensureTempOrder();
+    const state = this.ensureSalesNotesRuntimeState(tempOrder);
+    return {
+      orderIdentity: {
+        orderId: tempOrder.order_id ?? null,
+        externalSaleNumber: String(tempOrder.external_sale_number || '')
+      },
+      notes: (0, _lodashEs.cloneDeep)(tempOrder.notes || []),
+      state: (0, _lodashEs.cloneDeep)(state)
+    };
+  }
+  restoreSalesNotesMutationSnapshot(snapshot) {
+    if (!snapshot || !Array.isArray(snapshot.notes) || !snapshot.orderIdentity || typeof snapshot.orderIdentity.externalSaleNumber !== 'string' || typeof snapshot.state?.loaded !== 'boolean' || typeof snapshot.state?.dirty !== 'boolean') {
+      throw new Error('[Order Notes] 无效的 mutation snapshot');
+    }
+    const tempOrder = this.store.tempOrder;
+    if (!tempOrder) throw new Error('[Order Notes] 当前订单不存在');
+    const snapshotOrderId = snapshot.orderIdentity.orderId;
+    const currentOrderId = tempOrder.order_id;
+    const hasSnapshotOrderId = snapshotOrderId !== null && snapshotOrderId !== undefined && String(snapshotOrderId).trim().length > 0;
+    const hasCurrentOrderId = currentOrderId !== null && currentOrderId !== undefined && String(currentOrderId).trim().length > 0;
+    const isSameOrder = hasSnapshotOrderId && hasCurrentOrderId ? String(snapshotOrderId) === String(currentOrderId) : Boolean(snapshot.orderIdentity.externalSaleNumber) && snapshot.orderIdentity.externalSaleNumber === String(tempOrder.external_sale_number || '');
+    if (!isSameOrder) {
+      throw new Error('[Order Notes] 当前订单已切换，拒绝恢复旧订单快照');
+    }
+    this.ensureSalesNotesRuntimeState(tempOrder);
+    tempOrder.notes = (0, _lodashEs.cloneDeep)(snapshot.notes);
+    tempOrder._extend.salesNotesState = (0, _lodashEs.cloneDeep)(snapshot.state);
+    this.notifyTempOrderChanged();
+  }
+  async setSalesNote(input) {
+    const tempOrder = this.ensureTempOrder();
+    const note = this.setSalesNoteOnTempOrder(tempOrder, input);
+    this.notifyTempOrderChanged();
+    return (0, _lodashEs.cloneDeep)(note);
+  }
+  async removeSalesNote(uuid) {
+    const tempOrder = this.ensureTempOrder();
+    this.ensureSalesNotesLoadedForMutation(tempOrder);
+    const normalizedUuid = this.normalizeSalesNoteUuid(uuid, 'uuid');
+    const notes = tempOrder.notes || [];
+    const nextNotes = notes.filter(note => note.uuid !== normalizedUuid);
+    if (nextNotes.length === notes.length) return;
+    tempOrder.notes = nextNotes;
+    const state = this.ensureSalesNotesRuntimeState(tempOrder);
+    state.dirty = true;
+    this.notifyTempOrderChanged();
+  }
+  async clearSalesNotes() {
+    const tempOrder = this.ensureTempOrder();
+    tempOrder.notes = [];
+    const state = this.ensureSalesNotesRuntimeState(tempOrder);
+    state.loaded = true;
+    state.dirty = true;
+    this.notifyTempOrderChanged();
+  }
   updateTempOrderShopDiscount(amount) {
     const tempOrder = this.ensureTempOrder();
     const discount = _decimal.default.max(new _decimal.default(Number(amount) || 0), 0).toDecimalPlaces(2).toFixed(2);
@@ -2275,6 +2450,31 @@ class OrderModule extends _BaseModule.BaseModule {
     this.persistTempOrder();
     return tempOrder.buzzer;
   }
+  updateTempOrderShopServiceData(patch) {
+    const tempOrder = this.ensureTempOrder();
+    const metadata = tempOrder.metadata && typeof tempOrder.metadata === 'object' && !Array.isArray(tempOrder.metadata) ? tempOrder.metadata : {};
+    const currentShopServiceData = metadata.shop_service_data && typeof metadata.shop_service_data === 'object' && !Array.isArray(metadata.shop_service_data) ? metadata.shop_service_data : {};
+    const shopServiceData = {
+      ...currentShopServiceData,
+      ...patch
+    };
+    tempOrder.metadata = {
+      ...metadata,
+      shop_service_data: shopServiceData
+    };
+    this.persistTempOrder();
+    return shopServiceData;
+  }
+  updateTempOrderPickupReferenceMode(mode) {
+    return this.updateTempOrderShopServiceData({
+      pickup_reference_mode: mode
+    });
+  }
+  updateTempOrderServiceType(serviceType) {
+    return this.updateTempOrderShopServiceData({
+      service_type: serviceType
+    });
+  }
   updateTempOrderContactsInfo(contactsInfo) {
     const tempOrder = this.ensureTempOrder();
     tempOrder.contacts_info = contactsInfo && typeof contactsInfo === 'object' && !Array.isArray(contactsInfo) ? contactsInfo : null;
@@ -2864,6 +3064,7 @@ class OrderModule extends _BaseModule.BaseModule {
     const matchedProduct = matchedIndex === -1 ? null : tempOrder.products[matchedIndex];
     const existedFingerprint = matchedProduct ? (0, _utils3.buildProductLineFingerprint)((0, _utils.getProductSkuOptions)(matchedProduct), matchedProduct.product_bundle) : '';
     const commitProductLine = shouldMerge => {
+      let committedProduct;
       if (matchedIndex === -1 || !matchedProduct || !shouldMerge) {
         this.captureProductRuntime(tempOrder, productToAdd, normalizedIncoming);
         if (linked) {
@@ -2879,6 +3080,7 @@ class OrderModule extends _BaseModule.BaseModule {
         } else {
           tempOrder.products = [...tempOrder.products, normalizedIncoming];
         }
+        committedProduct = normalizedIncoming;
       } else {
         const targetProduct = matchedProduct;
         const targetUid = targetProduct.metadata?.unique_identification_number;
@@ -2914,6 +3116,7 @@ class OrderModule extends _BaseModule.BaseModule {
           num: nextNum
         };
         this.captureProductRuntime(tempOrder, productToAdd, tempOrder.products[matchedIndex], targetUid);
+        committedProduct = tempOrder.products[matchedIndex];
         if (matchedIndex !== tempOrder.products.length - 1) {
           const mergedProduct = tempOrder.products[matchedIndex];
           tempOrder.products = [...tempOrder.products.slice(0, matchedIndex), ...tempOrder.products.slice(matchedIndex + 1), mergedProduct];
@@ -2922,10 +3125,10 @@ class OrderModule extends _BaseModule.BaseModule {
       if (linked) {
         tempOrder.bookings = [...(tempOrder.bookings || []), linked.booking];
       }
+      return committedProduct;
     };
     if (!matchedProduct) {
-      commitProductLine(false);
-      return;
+      return commitProductLine(false);
     }
     const shouldMerge = this.shouldMergeProductToOrder({
       incomingProduct: productToAdd,
@@ -2940,7 +3143,7 @@ class OrderModule extends _BaseModule.BaseModule {
     if (shouldMerge && typeof shouldMerge === 'object' && typeof shouldMerge.then === 'function') {
       return Promise.resolve(shouldMerge).then(commitProductLine);
     }
-    commitProductLine(shouldMerge);
+    return commitProductLine(shouldMerge);
   }
 
   /**
@@ -2952,36 +3155,102 @@ class OrderModule extends _BaseModule.BaseModule {
    */
   async addProductToOrder(product, booking, options) {
     const tempOrder = this.ensureTempOrder();
+    const salesNoteDrafts = (options?.salesNotes || []).map(draft => ({
+      note_type: String(draft.note_type || '').trim(),
+      text: {
+        kind: 'resolved',
+        text: (0, _salesNotes.buildSalesNoteText)(draft.text)
+      }
+    }));
+    const mutationSnapshot = salesNoteDrafts.length > 0 ? {
+      products: (0, _lodashEs.cloneDeep)(tempOrder.products || []),
+      bookings: (0, _lodashEs.cloneDeep)(tempOrder.bookings || []),
+      notes: (0, _lodashEs.cloneDeep)(tempOrder.notes || []),
+      extend: (0, _lodashEs.cloneDeep)(tempOrder._extend || {})
+    } : null;
+    const attachSalesNoteDrafts = orderProduct => {
+      if (!salesNoteDrafts.length) return;
+      const productLineUid = orderProduct.metadata?.unique_identification_number || orderProduct.unique_identification_number;
+      if (!productLineUid) {
+        throw new Error('[Order Notes] 商品行缺少 unique_identification_number');
+      }
+      salesNoteDrafts.forEach(draft => {
+        this.setSalesNoteOnTempOrder(tempOrder, {
+          note_type: draft.note_type,
+          target: {
+            target_type: 'order_detail',
+            target_uuid: String(productLineUid)
+          },
+          text: draft.text
+        });
+      });
+    };
+    const rollbackProductAndNotesMutation = () => {
+      if (!mutationSnapshot) return;
+      tempOrder.products = mutationSnapshot.products;
+      tempOrder.bookings = mutationSnapshot.bookings;
+      tempOrder.notes = mutationSnapshot.notes;
+      tempOrder._extend = mutationSnapshot.extend;
+    };
     const insertAfterProductUid = options?.insertAfterProductUid;
     const anchorIndex = booking && insertAfterProductUid ? tempOrder.products.findIndex(line => {
       const uid = line.metadata?.unique_identification_number || line.unique_identification_number;
       return uid !== undefined && uid !== null && String(uid) === String(insertAfterProductUid);
     }) : -1;
     let insertAtIndex = anchorIndex >= 0 ? anchorIndex + 1 : undefined;
-    if (booking) {
-      const productRecord = product;
-      const splitCount = (0, _utils3.getSafeProductNum)(productRecord.num ?? productRecord.product_quantity ?? 1);
-      if (splitCount > 1) {
-        for (let i = 0; i < splitCount; i += 1) {
-          const singleLine = (0, _lodashEs.cloneDeep)(productRecord);
-          singleLine.num = 1;
-          delete singleLine.product_quantity;
-          const appendResult = this.appendProductLineToTempOrder(tempOrder, singleLine, (0, _lodashEs.cloneDeep)(booking), {
+    try {
+      if (booking) {
+        const productRecord = product;
+        const splitCount = (0, _utils3.getSafeProductNum)(productRecord.num ?? productRecord.product_quantity ?? 1);
+        if (splitCount > 1) {
+          for (let i = 0; i < splitCount; i += 1) {
+            const singleLine = (0, _lodashEs.cloneDeep)(productRecord);
+            const singleBooking = (0, _lodashEs.cloneDeep)(booking);
+            singleLine.num = 1;
+            delete singleLine.product_quantity;
+            if (i > 0) {
+              delete singleLine.unique_identification_number;
+              delete singleLine.identity_key;
+              if (singleLine.metadata) {
+                singleLine.metadata = {
+                  ...singleLine.metadata
+                };
+                delete singleLine.metadata.unique_identification_number;
+                delete singleLine.metadata.identity_key;
+              }
+              delete singleBooking.booking_uid;
+              if (singleBooking.metadata) {
+                singleBooking.metadata = {
+                  ...singleBooking.metadata
+                };
+                delete singleBooking.metadata.unique_identification_number;
+              }
+            }
+            const committedProduct = await this.appendProductLineToTempOrder(tempOrder, singleLine, singleBooking, {
+              insertAtIndex,
+              disableMerge: options?.disableMerge
+            });
+            attachSalesNoteDrafts(committedProduct);
+            if (insertAtIndex !== undefined) insertAtIndex += 1;
+          }
+        } else {
+          const committedProduct = await this.appendProductLineToTempOrder(tempOrder, product, (0, _lodashEs.cloneDeep)(booking), {
             insertAtIndex,
             disableMerge: options?.disableMerge
           });
-          if (appendResult) await appendResult;
-          if (insertAtIndex !== undefined) insertAtIndex += 1;
+          attachSalesNoteDrafts(committedProduct);
         }
-        await this.finalizeProductOrderMutation(tempOrder);
-        return tempOrder.products;
+      } else {
+        const committedProduct = await this.appendProductLineToTempOrder(tempOrder, product, undefined, {
+          insertAtIndex,
+          disableMerge: options?.disableMerge
+        });
+        attachSalesNoteDrafts(committedProduct);
       }
+    } catch (error) {
+      rollbackProductAndNotesMutation();
+      throw error;
     }
-    const appendResult = this.appendProductLineToTempOrder(tempOrder, product, booking, {
-      insertAtIndex,
-      disableMerge: options?.disableMerge
-    });
-    if (appendResult) await appendResult;
     await this.finalizeProductOrderMutation(tempOrder);
     this.logInfo('addProductToOrder success', {
       product_id: product.product_id,
@@ -3426,10 +3695,12 @@ class OrderModule extends _BaseModule.BaseModule {
    */
   async removeProductsFromOrder(identities, options) {
     const tempOrder = this.ensureTempOrder();
-    this.repairDuplicateProductLineIdentities(tempOrder);
     if (!identities.length) {
       return tempOrder.products;
     }
+    // 商品删除会同步删除以商品行为主关系的 Notes；快照不完整时禁止产生孤儿 Relation。
+    this.ensureSalesNotesLoadedForMutation(tempOrder);
+    this.repairDuplicateProductLineIdentities(tempOrder);
     const productsBeforeRemove = tempOrder.products || [];
     const bookingsBeforeRemove = tempOrder.bookings || [];
     const preserveDisplayPosition = options?.preserveDisplayPosition;
@@ -3489,6 +3760,7 @@ class OrderModule extends _BaseModule.BaseModule {
         tempOrder.products = nextProductIndex >= 0 ? [...productsWithoutRemaining.slice(0, nextProductIndex), remainingProduct, ...productsWithoutRemaining.slice(nextProductIndex)] : [...productsWithoutRemaining, remainingProduct];
       }
     }
+    this.removeSalesNotesForMissingProductLines(tempOrder);
     await this.finalizeAfterProductsMutation(tempOrder);
     this.logInfo('removeProductsFromOrder success', {
       identities
@@ -3501,12 +3773,14 @@ class OrderModule extends _BaseModule.BaseModule {
 
   /**
    * 仅清空购物车行（products / bookings），不重置整单。
-   * 用于「仅清空商品」；客户、备注、支付等协议字段保持不变。
+   * 普通整单 note 保持不变；以商品行为主体的 Sales Notes 同步删除。
    */
   async clearOrderCartLines() {
     const tempOrder = this.ensureTempOrder();
+    this.ensureSalesNotesLoadedForMutation(tempOrder);
     tempOrder.products = [];
     tempOrder.bookings = [];
+    this.removeSalesNotesForMissingProductLines(tempOrder);
     this.syncTempOrderHolderFromBookings(tempOrder);
     if (tempOrder._extend && typeof tempOrder._extend === 'object') {
       tempOrder._extend = {
@@ -3709,6 +3983,12 @@ class OrderModule extends _BaseModule.BaseModule {
       this.logSubmitBackendRejected(result, payload);
       return result;
     }
+    const isLocalPendingSubmit = this.isLocalPendingSubmitResult(result);
+    // need_sync=1 仅表示已进入本地同步队列，不能视为远端已确认 Notes。
+    if (Object.prototype.hasOwnProperty.call(payload, 'notes') && !isLocalPendingSubmit) {
+      const salesNotesState = this.ensureSalesNotesRuntimeState(tempOrder);
+      salesNotesState.dirty = false;
+    }
     const submittedOrderId = this.extractOrderIdFromSubmitResult(result);
     this.logInfo('runSubmitTempOrder: 提交成功', {
       submittedOrderId,
@@ -3722,9 +4002,10 @@ class OrderModule extends _BaseModule.BaseModule {
       tempOrder.order_id = submittedOrderId;
       const resultRecord = result;
       await this.markLocalOrderSynced(submittedOrderId, resultRecord?.data || resultRecord || {});
-    } else if (this.isLocalPendingSubmitResult(result)) {
+    }
+    if (isLocalPendingSubmit) {
       this.store.syncState = 'local';
-    } else {
+    } else if (submittedOrderId === null || submittedOrderId === undefined) {
       this.store.syncState = 'submitted';
     }
     return result;
@@ -4110,7 +4391,7 @@ class OrderModule extends _BaseModule.BaseModule {
       params.forceRemote = false;
     }
     const res = await this.request.get(`/order/sales/${encodeURIComponent(lookup)}`, {
-      with: ['products', 'bookings', 'payments', 'customer', 'summary', 'contacts_info', 'refunds'],
+      with: ['products', 'bookings', 'payments', 'customer', 'summary', 'contacts_info', 'refunds', 'notes'],
       ...(params.forceRemote ? {
         forceRemote: true
       } : {})
@@ -4163,7 +4444,8 @@ class OrderModule extends _BaseModule.BaseModule {
     const isMergedSalesDetailHydrate = options?.source === 'mergedSalesDetail';
     const nextTempOrder = this.normalizeTempOrderForRuntime(raw, {
       // merge 前已只给远端商品补标记；这里不能把本地未提交商品一并变成 saved item。
-      makeEditMark: !isSessionStorageHydrate && !isMergedSalesDetailHydrate
+      makeEditMark: !isSessionStorageHydrate && !isMergedSalesDetailHydrate,
+      allowUnresolvedSalesNotes: isSessionStorageHydrate
     });
     this.store.tempOrder = nextTempOrder;
     if (isSessionStorageHydrate) {
@@ -4385,6 +4667,17 @@ class OrderModule extends _BaseModule.BaseModule {
     nextTempOrder.payments = Array.isArray(raw.payments) ? raw.payments.map(p => ({
       ...(p || {})
     })) : [];
+    const rawHasSalesNotes = Object.prototype.hasOwnProperty.call(raw, 'notes');
+    const restoredSalesNotesState = raw._extend?.salesNotesState;
+    const allowUnresolvedSalesNotes = options?.allowUnresolvedSalesNotes === true || restoredSalesNotesState?.dirty === true || Number(raw.is_draft_order || 0) === 1;
+    const decodedSalesNotes = rawHasSalesNotes ? (0, _salesNotes.decodeSalesNotesSnapshot)(raw.notes, {
+      allowUnresolvedOrderTarget: allowUnresolvedSalesNotes
+    }) : {
+      notes: [],
+      complete: false
+    };
+    const hasUnresolvedSalesNoteOrderTarget = decodedSalesNotes.notes.some(note => note.note_relations.some(relation => relation.is_primary === 0 && relation.relation_type === 'related_to' && relation.target_type === 'order' && relation.target_uuid === ''));
+    nextTempOrder.notes = decodedSalesNotes.notes;
     nextTempOrder.surcharges = Array.isArray(raw.surcharges) ? raw.surcharges.map(s => ({
       ...(s || {})
     })) : [];
@@ -4404,6 +4697,10 @@ class OrderModule extends _BaseModule.BaseModule {
       productsByUid: {}
     };
     const tempOrderExtend = nextTempOrder._extend;
+    tempOrderExtend.salesNotesState = {
+      loaded: rawHasSalesNotes ? decodedSalesNotes.complete : restoredSalesNotesState?.loaded === true,
+      dirty: decodedSalesNotes.complete && (restoredSalesNotesState?.dirty === true || allowUnresolvedSalesNotes && hasUnresolvedSalesNoteOrderTarget)
+    };
     const productsByUid = tempOrderExtend.productsByUid || {};
     for (const [index, product] of nextTempOrder.products.entries()) {
       const uid = product.metadata?.unique_identification_number;
@@ -4578,7 +4875,7 @@ class OrderModule extends _BaseModule.BaseModule {
   }
   async getOrderInfo(order_id) {
     const res = await this.request.get(`/order/sales/${order_id}`, {
-      with: ['products', 'bookings']
+      with: ['products', 'bookings', 'notes']
     }, {
       osServer: true
     });

package/lib/modules/Order/salesNotes.d.ts

@@ -0,0 +1,31 @@
+import type { SalesNote, SalesNoteProtocol, SalesNoteTextInput } from './types';
+export interface SalesNotePolicy {
+    note_type: string;
+    importance: string;
+    uniquePerPrimaryTarget: boolean;
+    primary_relation_type: 'about';
+    secondary_order_relation_type: 'related_to';
+}
+export declare function getSalesNotePolicy(note_type: string): SalesNotePolicy | null;
+export declare function buildSalesNoteText(input: SalesNoteTextInput): Record<string, string>;
+export interface SalesNoteValidationOptions {
+    allowUnresolvedOrderTarget?: boolean;
+    expectedOrderTargetUuid?: string;
+    productTargetUuids?: ReadonlySet<string>;
+}
+export type EncodeSalesNotesOptions = SalesNoteValidationOptions;
+export declare function encodeSalesNotes(notes: SalesNote[], options?: EncodeSalesNotesOptions): SalesNoteProtocol[];
+export interface DecodedSalesNotesSnapshot {
+    notes: SalesNote[];
+    complete: boolean;
+}
+export interface DecodeSalesNotesOptions {
+    allowUnresolvedOrderTarget?: boolean;
+}
+export declare function decodeSalesNotesSnapshot(value: unknown, options?: DecodeSalesNotesOptions): DecodedSalesNotesSnapshot;
+export declare function decodeSalesNotes(value: unknown, options?: DecodeSalesNotesOptions): SalesNote[];
+export declare function finalizeSalesNotesForCheckout(params: {
+    notes: unknown;
+    shopOrderNumber: unknown;
+    productTargetUuids: string[];
+}): SalesNoteProtocol[];