@pisell/pisellos 2.3.94 → 2.3.96

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();
@@ -1006,19 +1008,26 @@ class OrderModule extends _BaseModule.BaseModule {
   normalizeDepositAmount(amount) {
     return _decimal.default.max(new _decimal.default(Number(amount) || 0), 0).toDecimalPlaces(2).toFixed(2);
   }
-  getLastOrderDepositSnapshot() {
-    const lastOrderInfo = this.store.lastOrderInfo;
-    if (!lastOrderInfo || typeof lastOrderInfo !== 'object') return null;
-    const rawDepositAmount = lastOrderInfo.deposit_amount ?? lastOrderInfo.summary?.deposit_amount;
+  normalizeDepositFlag(value) {
+    if (value === 0 || value === '0') return 0;
+    if (value === 1 || value === '1') return 1;
+    return null;
+  }
+  getHistoricalDepositSnapshot(source) {
+    if (!source || typeof source !== 'object') return null;
+    const record = source;
+    const rawDepositAmount = record.deposit_amount ?? record.summary?.deposit_amount;
     const depositAmount = this.normalizeDepositAmount(rawDepositAmount ?? 0);
-    const hasDepositAmount = new _decimal.default(depositAmount).gt(0);
-    const isDeposit = Number(lastOrderInfo.is_deposit) === 1 || hasDepositAmount;
-    if (!isDeposit || !hasDepositAmount) return null;
+    if (!new _decimal.default(depositAmount).gt(0)) return null;
     return {
-      isDeposit: 1,
+      // 兼容历史数据：旧快照缺少 is_deposit 时，沿用正定金金额的推导规则。
+      isDeposit: this.normalizeDepositFlag(record.is_deposit) ?? 1,
       depositAmount
     };
   }
+  getLastOrderDepositSnapshot() {
+    return this.getHistoricalDepositSnapshot(this.store.lastOrderInfo);
+  }
   getLastOrderSubmitSnapshot() {
     const lastOrderInfo = this.store.lastOrderInfo;
     if (!lastOrderInfo || typeof lastOrderInfo !== 'object') return {};
@@ -1066,7 +1075,7 @@ class OrderModule extends _BaseModule.BaseModule {
       }
     };
     tempOrder.deposit_amount = snapshot.depositAmount;
-    tempOrder.is_deposit = tempOrder.is_deposit === 0 && new _decimal.default(tempOrder.deposit_amount || 0).gt(0) ? 0 : snapshot.isDeposit;
+    tempOrder.is_deposit = snapshot.isDeposit;
     return nextSummary;
   }
   isDepositOrder(tempOrder, depositAmount) {
@@ -1603,10 +1612,17 @@ class OrderModule extends _BaseModule.BaseModule {
       ...(0, _lodashEs.cloneDeep)(snapshot.summary || {})
     };
     const shouldUseManualDepositOverride = Boolean(manualDepositOverride && manualDepositOverride.productStructuralFingerprint === this.buildOrderProductsStructuralFingerprint(tempOrder.products));
+    const historicalDepositSnapshot = this.getHistoricalDepositSnapshot(snapshot);
     if (shouldUseManualDepositOverride) {
       summary = this.applyDepositAmountToSummary(tempOrder, summary, manualDepositOverride.amount);
-    } else if (manualDepositOverride) {
-      this.clearManualDepositOverride(tempOrder);
+    } else {
+      if (manualDepositOverride) {
+        this.clearManualDepositOverride(tempOrder);
+      }
+      if (historicalDepositSnapshot) {
+        summary = this.applyDepositAmountToSummary(tempOrder, summary, historicalDepositSnapshot.depositAmount);
+        tempOrder.is_deposit = historicalDepositSnapshot.isDeposit;
+      }
     }
     const isPayableAmountUnchanged = this.isSnapshotPayableAmountUnchanged(tempOrder, snapshot, summary);
     if (!isPayableAmountUnchanged) return null;
@@ -1623,8 +1639,8 @@ class OrderModule extends _BaseModule.BaseModule {
       tempOrder.surcharges = (0, _lodashEs.cloneDeep)(snapshot.surcharges);
     }
     tempOrder.surcharge_fee = summary.surcharge_fee || tempOrder.surcharge_fee;
-    tempOrder.deposit_amount = summary.deposit_amount || '0.00';
-    tempOrder.is_deposit = summary.deposit_amount !== '0.00' ? 1 : 0;
+    tempOrder.deposit_amount = this.normalizeDepositAmount(summary.deposit_amount || 0);
+    tempOrder.is_deposit = shouldUseManualDepositOverride ? new _decimal.default(tempOrder.deposit_amount).gt(0) ? 1 : 0 : historicalDepositSnapshot?.isDeposit ?? (new _decimal.default(tempOrder.deposit_amount).gt(0) ? 1 : 0);
     const previousSummary = this.store.summary;
     this.store.summary = summary;
     this.updateTempOrderPaymentStatus(tempOrder, {
@@ -2081,7 +2097,7 @@ class OrderModule extends _BaseModule.BaseModule {
     const isExistingDepositDisabled = tempOrder.is_deposit === 0 && new _decimal.default(tempOrder.deposit_amount || 0).gt(0);
     tempOrder.deposit_amount = depositAmount;
     tempOrder.is_deposit = hasDepositAmount && !isExistingDepositDisabled ? 1 : 0;
-    return this.applyLastOrderDepositSnapshot(tempOrder, nextSummary);
+    return shouldUseManualDepositOverride ? nextSummary : this.applyLastOrderDepositSnapshot(tempOrder, nextSummary);
   }
   async recalculateSummary(options) {
     const tempOrder = options?.createIfMissing ? this.ensureTempOrder() : this.store.tempOrder;
@@ -2222,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);
@@ -2261,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;
@@ -2850,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) {
@@ -2865,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;
@@ -2900,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];
@@ -2908,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,
@@ -2926,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);
   }
 
   /**
@@ -2938,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,
@@ -3412,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;
@@ -3475,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
@@ -3487,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 = {
@@ -3695,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,
@@ -3708,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;
@@ -4096,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
       } : {})
@@ -4149,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) {
@@ -4187,6 +4483,7 @@ class OrderModule extends _BaseModule.BaseModule {
       externalSaleNumber: nextTempOrder.external_sale_number
     };
     const rawSummary = raw.summary && typeof raw.summary === 'object' ? raw.summary : {};
+    const historicalDepositSnapshot = this.getHistoricalDepositSnapshot(sourceLastOrderInfo);
     const summarySurcharges = Array.isArray(rawSummary.surcharges) ? rawSummary.surcharges.map(s => ({
       ...(s || {})
     })) : (0, _lodashEs.cloneDeep)(nextTempOrder.surcharges || []);
@@ -4205,6 +4502,10 @@ class OrderModule extends _BaseModule.BaseModule {
         surcharges: (0, _lodashEs.cloneDeep)(nextTempOrder.surcharges || []),
         shop_discount: nextTempOrder.shop_discount || '0.00',
         productFingerprint: this.buildOrderProductsFingerprint(nextTempOrder.products || []),
+        ...(historicalDepositSnapshot ? {
+          is_deposit: historicalDepositSnapshot.isDeposit,
+          deposit_amount: historicalDepositSnapshot.depositAmount
+        } : {}),
         // merged record 的 summary 仍是远端旧值，保留快照仅用于完整重算的价格清理基线。
         ...(isMergedSalesDetailHydrate ? {
           requiresFullSummaryRecalculation: true
@@ -4366,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 || {})
     })) : [];
@@ -4385,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;
@@ -4559,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[];