@pisell/pisellos 2.3.93 → 2.3.95

package/dist/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[];

package/dist/modules/Order/salesNotes.js

@@ -0,0 +1,492 @@
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
+function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _iterableToArray(iter) { if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter); }
+function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) return _arrayLikeToArray(arr); }
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it.return != null) it.return(); } finally { if (didErr) throw err; } } }; }
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+var MAX_UUID_LENGTH = 255;
+var LOCALIZED_NOTE_LOCALES = ['en', 'zh-CN', 'zh-HK', 'ja', 'pt'];
+var UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+ * 备注业务规则统一注册在 OS；调用方只传 note_type、目标行和原始文本。
+ * 后续新增备注类型时在这里增加 policy，不把 importance / Relation 规则下放给 UI。
+ */
+var SALES_NOTE_POLICIES = {
+  allergy: {
+    note_type: 'allergy',
+    importance: 'high',
+    uniquePerPrimaryTarget: true,
+    primary_relation_type: 'about',
+    secondary_order_relation_type: 'related_to'
+  }
+};
+export function getSalesNotePolicy(note_type) {
+  return SALES_NOTE_POLICIES[note_type] || null;
+}
+function normalizeUuid(value, field, options) {
+  var uuid = String(value !== null && value !== void 0 ? value : '').trim();
+  if (!uuid && !(options !== null && options !== void 0 && options.allowEmpty)) {
+    throw new Error("[Order Notes] ".concat(field, " \u4E0D\u80FD\u4E3A\u7A7A"));
+  }
+  if (uuid.length > MAX_UUID_LENGTH) {
+    throw new Error("[Order Notes] ".concat(field, " \u4E0D\u80FD\u8D85\u8FC7 ").concat(MAX_UUID_LENGTH, " \u4E2A\u5B57\u7B26"));
+  }
+  return uuid;
+}
+function normalizeEntityUuid(value, field) {
+  var uuid = normalizeUuid(value, field);
+  if (!UUID_V4_PATTERN.test(uuid)) {
+    throw new Error("[Order Notes] ".concat(field, " \u5FC5\u987B\u4E3A UUID v4"));
+  }
+  return uuid;
+}
+function normalizeTextRecord(value) {
+  if (!value || _typeof(value) !== 'object' || Array.isArray(value)) return {};
+  return Object.entries(value).reduce(function (result, _ref) {
+    var _ref2 = _slicedToArray(_ref, 2),
+      locale = _ref2[0],
+      text = _ref2[1];
+    if (typeof text === 'string') result[locale] = text;
+    return result;
+  }, {});
+}
+function normalizeLocalizedLabel(label) {
+  if (typeof label === 'string') {
+    var text = label.trim();
+    return text ? {
+      default: text
+    } : {};
+  }
+  return Object.entries(label || {}).reduce(function (result, _ref3) {
+    var _ref4 = _slicedToArray(_ref3, 2),
+      locale = _ref4[0],
+      value = _ref4[1];
+    var text = String(value !== null && value !== void 0 ? value : '').trim();
+    if (text) result[locale] = text;
+    return result;
+  }, {});
+}
+function getLocaleCandidates(locale) {
+  var raw = String(locale || '').trim();
+  var normalized = raw.replace(/_/g, '-');
+  var base = normalized.split('-')[0];
+  return Array.from(new Set([raw, normalized, base].filter(Boolean)));
+}
+function normalizeLocaleLookupKey(locale) {
+  return String(locale || '').trim().replace(/_/g, '-').toLowerCase();
+}
+function resolveLocalizedLabel(label, locale) {
+  var _entries$find, _entries$;
+  if (typeof label === 'string') return label.trim();
+  var normalized = normalizeLocalizedLabel(label);
+  var entries = Object.entries(normalized);
+  var lowerCaseLookup = new Map(entries.map(function (_ref5) {
+    var _ref6 = _slicedToArray(_ref5, 2),
+      key = _ref6[0],
+      value = _ref6[1];
+    return [normalizeLocaleLookupKey(key), value];
+  }));
+  var _iterator = _createForOfIteratorHelper(getLocaleCandidates(locale)),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var candidate = _step.value;
+      var matched = lowerCaseLookup.get(normalizeLocaleLookupKey(candidate));
+      if (matched) return matched;
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  var localeBase = normalizeLocaleLookupKey(locale).split('-')[0];
+  var sameLanguage = (_entries$find = entries.find(function (_ref7) {
+    var _ref8 = _slicedToArray(_ref7, 1),
+      key = _ref8[0];
+    return normalizeLocaleLookupKey(key).split('-')[0] === localeBase;
+  })) === null || _entries$find === void 0 ? void 0 : _entries$find[1];
+  return sameLanguage || lowerCaseLookup.get('en') || lowerCaseLookup.get('zh-cn') || lowerCaseLookup.get('default') || ((_entries$ = entries[0]) === null || _entries$ === void 0 ? void 0 : _entries$[1]) || '';
+}
+function joinNoteParts(parts) {
+  return parts.map(function (part) {
+    return String(part !== null && part !== void 0 ? part : '');
+  }).filter(function (part) {
+    return part.trim().length > 0;
+  }).join(',');
+}
+export function buildSalesNoteText(input) {
+  var _input$input2;
+  if (input.kind === 'plain') {
+    var _input$input;
+    var text = String((_input$input = input.input) !== null && _input$input !== void 0 ? _input$input : '');
+    if (!text.trim()) throw new Error('[Order Notes] 备注输入不能为空');
+    return {
+      'zh-CN': '',
+      original: text
+    };
+  }
+  if (input.kind === 'resolved') {
+    var _text = normalizeTextRecord(input.text);
+    if (!Object.values(_text).some(function (value) {
+      return value.trim();
+    })) {
+      throw new Error('[Order Notes] 备注文本不能为空');
+    }
+    return _text;
+  }
+  var inputText = String((_input$input2 = input.input) !== null && _input$input2 !== void 0 ? _input$input2 : '');
+  var seenIds = new Set();
+  var selections = (input.selections || []).filter(function (selection) {
+    var _selection$id;
+    var id = String((_selection$id = selection === null || selection === void 0 ? void 0 : selection.id) !== null && _selection$id !== void 0 ? _selection$id : '').trim();
+    if (!id || seenIds.has(id)) return false;
+    seenIds.add(id);
+    return true;
+  });
+  if (!selections.length && !inputText.trim()) {
+    throw new Error('[Order Notes] 过敏选项和补充说明不能同时为空');
+  }
+  var result = {};
+  var _iterator2 = _createForOfIteratorHelper(LOCALIZED_NOTE_LOCALES),
+    _step2;
+  try {
+    var _loop = function _loop() {
+      var locale = _step2.value;
+      result[locale] = joinNoteParts([].concat(_toConsumableArray(selections.map(function (selection) {
+        return resolveLocalizedLabel(selection.label, locale);
+      })), [inputText]));
+    };
+    for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+      _loop();
+    }
+  } catch (err) {
+    _iterator2.e(err);
+  } finally {
+    _iterator2.f();
+  }
+  result.original = joinNoteParts([].concat(_toConsumableArray(selections.map(function (selection) {
+    return resolveLocalizedLabel(selection.label, input.locale);
+  })), [inputText]));
+  return result;
+}
+function validateSalesNote(note) {
+  var _note$content;
+  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  normalizeEntityUuid(note.uuid, 'Note uuid');
+  var note_type = String(note.note_type || '').trim();
+  var policy = getSalesNotePolicy(note_type);
+  if (!policy) {
+    throw new Error("[Order Notes] \u5F53\u524D\u672A\u6CE8\u518C\u5907\u6CE8\u7C7B\u578B: ".concat(note_type || '(empty)'));
+  }
+  if (note.importance !== policy.importance) {
+    throw new Error("[Order Notes] ".concat(note_type, " importance \u5FC5\u987B\u4E3A ").concat(policy.importance));
+  }
+  var text = (_note$content = note.content) === null || _note$content === void 0 ? void 0 : _note$content.text;
+  if (!text || _typeof(text) !== 'object' || Array.isArray(text) || Object.values(text).some(function (value) {
+    return typeof value !== 'string';
+  }) || !Object.values(text).some(function (value) {
+    return value.trim();
+  })) {
+    throw new Error('[Order Notes] content.text 不能为空');
+  }
+  if (!Array.isArray(note.note_relations) || note.note_relations.length === 0) {
+    throw new Error('[Order Notes] note_relations 不能为空');
+  }
+  var relationUuids = new Set();
+  var primaryCount = 0;
+  var orderRelationCount = 0;
+  var _iterator3 = _createForOfIteratorHelper(note.note_relations),
+    _step3;
+  try {
+    for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+      var relation = _step3.value;
+      var relationUuid = normalizeEntityUuid(relation.uuid, 'Relation uuid');
+      if (relationUuids.has(relationUuid)) {
+        throw new Error('[Order Notes] 同一 Note 内 Relation uuid 不能重复');
+      }
+      relationUuids.add(relationUuid);
+      if (relation.is_primary !== 0 && relation.is_primary !== 1) {
+        throw new Error('[Order Notes] is_primary 只允许整数 0 或 1');
+      }
+      if (relation.relation_type !== 'about' && relation.relation_type !== 'related_to') {
+        throw new Error('[Order Notes] relation_type 不合法');
+      }
+      if (relation.target_type !== 'order' && relation.target_type !== 'order_detail') {
+        throw new Error('[Order Notes] target_type 不合法');
+      }
+      if (relation.is_primary === 1) {
+        primaryCount += 1;
+        if (relation.relation_type !== policy.primary_relation_type || relation.target_type !== 'order_detail') {
+          throw new Error('[Order Notes] 主关系必须使用 about + order_detail');
+        }
+        var targetUuid = normalizeUuid(relation.target_uuid, 'Relation target_uuid');
+        if (options.productTargetUuids && !options.productTargetUuids.has(targetUuid)) {
+          throw new Error('[Order Notes] 商品 Relation target_uuid 不属于当前订单');
+        }
+        continue;
+      }
+      if (relation.target_type === 'order' && relation.relation_type === policy.secondary_order_relation_type) {
+        orderRelationCount += 1;
+        var _targetUuid = normalizeUuid(relation.target_uuid, 'Relation target_uuid', {
+          allowEmpty: options.allowUnresolvedOrderTarget === true
+        });
+        if (options.expectedOrderTargetUuid !== undefined && _targetUuid !== options.expectedOrderTargetUuid) {
+          throw new Error('[Order Notes] 订单 Relation target_uuid 与 shop_order_number 不一致');
+        }
+        continue;
+      }
+      throw new Error('[Order Notes] 非主体关系必须使用 related_to + order');
+    }
+  } catch (err) {
+    _iterator3.e(err);
+  } finally {
+    _iterator3.f();
+  }
+  if (primaryCount !== 1) {
+    throw new Error('[Order Notes] 每条 Note 必须且只能有一个主关系');
+  }
+  if (orderRelationCount !== 1) {
+    throw new Error('[Order Notes] 每条商品 Note 必须且只能有一个订单冗余关系');
+  }
+}
+export function encodeSalesNotes(notes) {
+  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  var entityUuids = new Set();
+  var uniquePolicyTargets = new Set();
+  return (notes || []).map(function (note) {
+    var _note$content2;
+    validateSalesNote(note, options);
+    var noteUuid = normalizeEntityUuid(note.uuid, 'Note uuid');
+    if (entityUuids.has(noteUuid)) {
+      throw new Error('[Order Notes] Note/Relation uuid 不能重复');
+    }
+    entityUuids.add(noteUuid);
+    var note_type = String(note.note_type).trim();
+    var noteRelations = note.note_relations.map(function (relation) {
+      var relationUuid = normalizeEntityUuid(relation.uuid, 'Relation uuid');
+      if (entityUuids.has(relationUuid)) {
+        throw new Error('[Order Notes] Note/Relation uuid 不能重复');
+      }
+      entityUuids.add(relationUuid);
+      var allowEmptyTarget = options.allowUnresolvedOrderTarget === true && relation.is_primary === 0 && relation.relation_type === 'related_to' && relation.target_type === 'order';
+      return {
+        uuid: relationUuid,
+        relation_type: relation.relation_type,
+        target_type: relation.target_type,
+        target_uuid: normalizeUuid(relation.target_uuid, 'Relation target_uuid', {
+          allowEmpty: allowEmptyTarget
+        }),
+        is_primary: relation.is_primary
+      };
+    });
+    var primaryRelation = noteRelations.find(function (relation) {
+      return relation.is_primary === 1;
+    });
+    var policy = getSalesNotePolicy(note_type);
+    if (policy.uniquePerPrimaryTarget) {
+      var policyTargetKey = [note_type, primaryRelation.target_type, primaryRelation.target_uuid].join(':');
+      if (uniquePolicyTargets.has(policyTargetKey)) {
+        throw new Error('[Order Notes] 同一商品行不能重复提交同类型 Note');
+      }
+      uniquePolicyTargets.add(policyTargetKey);
+    }
+    return {
+      uuid: noteUuid,
+      note_type: note_type,
+      content: {
+        text: _objectSpread({}, ((_note$content2 = note.content) === null || _note$content2 === void 0 ? void 0 : _note$content2.text) || {})
+      },
+      importance: note.importance,
+      note_relations: noteRelations
+    };
+  });
+}
+function decodeRelation(value) {
+  var _raw$uuid, _raw$target_uuid;
+  if (!value || _typeof(value) !== 'object' || Array.isArray(value)) return null;
+  var raw = value;
+  var uuid = String((_raw$uuid = raw.uuid) !== null && _raw$uuid !== void 0 ? _raw$uuid : '').trim();
+  var target_uuid = String((_raw$target_uuid = raw.target_uuid) !== null && _raw$target_uuid !== void 0 ? _raw$target_uuid : '').trim();
+  var relation_type = raw.relation_type;
+  var target_type = raw.target_type;
+  var is_primary = raw.is_primary;
+  if (!uuid || relation_type !== 'about' && relation_type !== 'related_to' || target_type !== 'order' && target_type !== 'order_detail' || is_primary !== 0 && is_primary !== 1) {
+    return null;
+  }
+  return {
+    uuid: uuid,
+    relation_type: relation_type,
+    target_type: target_type,
+    target_uuid: target_uuid,
+    is_primary: is_primary
+  };
+}
+export function decodeSalesNotesSnapshot(value) {
+  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  if (!Array.isArray(value)) return {
+    notes: [],
+    complete: false
+  };
+  var notes = [];
+  var entityUuids = new Set();
+  var uniquePolicyTargets = new Set();
+  var complete = true;
+  var _iterator4 = _createForOfIteratorHelper(value),
+    _step4;
+  try {
+    for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
+      var _raw$uuid2, _raw$note_type, _raw$importance, _raw$content;
+      var item = _step4.value;
+      if (!item || _typeof(item) !== 'object' || Array.isArray(item)) {
+        complete = false;
+        continue;
+      }
+      var raw = item;
+      var uuid = String((_raw$uuid2 = raw.uuid) !== null && _raw$uuid2 !== void 0 ? _raw$uuid2 : '').trim();
+      var note_type = String((_raw$note_type = raw.note_type) !== null && _raw$note_type !== void 0 ? _raw$note_type : '').trim();
+      var importance = String((_raw$importance = raw.importance) !== null && _raw$importance !== void 0 ? _raw$importance : '').trim();
+      var rawText = (_raw$content = raw.content) === null || _raw$content === void 0 ? void 0 : _raw$content.text;
+      var text = normalizeTextRecord(rawText);
+      if (!rawText || _typeof(rawText) !== 'object' || Array.isArray(rawText) || Object.keys(text).length !== Object.keys(rawText).length) {
+        complete = false;
+        continue;
+      }
+      var rawNoteRelations = Array.isArray(raw.note_relations) ? raw.note_relations : null;
+      var noteRelations = rawNoteRelations ? rawNoteRelations.map(function (relation) {
+        return decodeRelation(relation);
+      }).filter(function (relation) {
+        return relation !== null;
+      }) : [];
+      if (!rawNoteRelations || noteRelations.length !== rawNoteRelations.length) {
+        complete = false;
+        continue;
+      }
+      var note = {
+        uuid: uuid,
+        note_type: note_type,
+        content: {
+          text: text
+        },
+        importance: importance,
+        note_relations: noteRelations
+      };
+      try {
+        validateSalesNote(note, {
+          allowUnresolvedOrderTarget: options.allowUnresolvedOrderTarget
+        });
+        if (entityUuids.has(note.uuid)) {
+          complete = false;
+          continue;
+        }
+        entityUuids.add(note.uuid);
+        var hasDuplicateRelationUuid = false;
+        var _iterator5 = _createForOfIteratorHelper(note.note_relations),
+          _step5;
+        try {
+          for (_iterator5.s(); !(_step5 = _iterator5.n()).done;) {
+            var relation = _step5.value;
+            if (entityUuids.has(relation.uuid)) {
+              hasDuplicateRelationUuid = true;
+              break;
+            }
+          }
+        } catch (err) {
+          _iterator5.e(err);
+        } finally {
+          _iterator5.f();
+        }
+        if (hasDuplicateRelationUuid) {
+          complete = false;
+          continue;
+        }
+        note.note_relations.forEach(function (relation) {
+          return entityUuids.add(relation.uuid);
+        });
+        var policy = getSalesNotePolicy(note.note_type);
+        var primaryRelation = note.note_relations.find(function (relation) {
+          return relation.is_primary === 1;
+        });
+        if (policy !== null && policy !== void 0 && policy.uniquePerPrimaryTarget && primaryRelation) {
+          var policyTargetKey = [note.note_type, primaryRelation.target_type, primaryRelation.target_uuid].join(':');
+          if (uniquePolicyTargets.has(policyTargetKey)) {
+            complete = false;
+            continue;
+          }
+          uniquePolicyTargets.add(policyTargetKey);
+        }
+        notes.push(note);
+      } catch (_unused) {
+        complete = false;
+      }
+    }
+  } catch (err) {
+    _iterator4.e(err);
+  } finally {
+    _iterator4.f();
+  }
+  return {
+    notes: notes,
+    complete: complete
+  };
+}
+export function decodeSalesNotes(value) {
+  var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  return decodeSalesNotesSnapshot(value, options).notes;
+}
+export function finalizeSalesNotesForCheckout(params) {
+  if (!Array.isArray(params.notes)) {
+    throw new Error('[Order Notes] checkout notes 必须为数组');
+  }
+  if (params.notes.length === 0) return [];
+  var shopOrderNumber = normalizeUuid(params.shopOrderNumber, 'shop_order_number');
+  var productTargetUuids = new Set();
+  var _iterator6 = _createForOfIteratorHelper(params.productTargetUuids || []),
+    _step6;
+  try {
+    for (_iterator6.s(); !(_step6 = _iterator6.n()).done;) {
+      var rawTargetUuid = _step6.value;
+      var targetUuid = normalizeUuid(rawTargetUuid, '商品 target_uuid');
+      if (productTargetUuids.has(targetUuid)) {
+        throw new Error('[Order Notes] 商品行业务标识不能重复');
+      }
+      productTargetUuids.add(targetUuid);
+    }
+  } catch (err) {
+    _iterator6.e(err);
+  } finally {
+    _iterator6.f();
+  }
+  var decoded = decodeSalesNotesSnapshot(params.notes, {
+    allowUnresolvedOrderTarget: true
+  });
+  if (!decoded.complete || decoded.notes.length !== params.notes.length) {
+    throw new Error('[Order Notes] checkout Notes 快照不完整');
+  }
+  var finalizedNotes = decoded.notes.map(function (note) {
+    return _objectSpread(_objectSpread({}, note), {}, {
+      content: {
+        text: _objectSpread({}, note.content.text)
+      },
+      note_relations: note.note_relations.map(function (relation) {
+        return _objectSpread(_objectSpread({}, relation), relation.is_primary === 0 && relation.relation_type === 'related_to' && relation.target_type === 'order' ? {
+          target_uuid: shopOrderNumber
+        } : {});
+      })
+    });
+  });
+  return encodeSalesNotes(finalizedNotes, {
+    expectedOrderTargetUuid: shopOrderNumber,
+    productTargetUuids: productTargetUuids
+  });
+}

package/dist/modules/Order/types.d.ts

@@ -8,6 +8,13 @@ import type { PaymentItem } from '../Payment/types';
 import type { ICustomer } from '../AccountList/types';
 import type { OrderProductDiscountItem } from '../../server/modules/order/types';
 export type { OrderProductDiscountItem } from '../../server/modules/order/types';
+export type PickupReferenceMode = 'counter_pickup' | 'table_service';
+export type ShopServiceType = 'dine_in' | 'takeaway';
+export interface ShopServiceData {
+    pickup_reference_mode?: PickupReferenceMode;
+    service_type?: ShopServiceType | '';
+    [key: string]: any;
+}
 export declare enum OrderHooks {
     OnOrderCreate = "order:onOrderCreate",
     OnOrderUpdate = "order:onOrderUpdate",
@@ -238,6 +245,72 @@ export interface OrderSummary {
     tax_title?: string;
     tax_rate?: number;
 }
+export type SalesNoteRelationType = 'about' | 'related_to';
+export type SalesNoteTargetType = 'order' | 'order_detail';
+export type SalesNoteLocalizedText = string | Record<string, string>;
+export interface SalesNoteLocalizedSelection {
+    id: string;
+    label: SalesNoteLocalizedText;
+}
+export type SalesNoteTextInput = {
+    kind: 'localizedSelections';
+    selections: SalesNoteLocalizedSelection[];
+    locale: string;
+    input?: string;
+} | {
+    kind: 'plain';
+    input: string;
+} | {
+    kind: 'resolved';
+    text: Record<string, string>;
+};
+export interface SalesNoteRelation {
+    uuid: string;
+    relation_type: SalesNoteRelationType;
+    target_type: SalesNoteTargetType;
+    target_uuid: string;
+    is_primary: 0 | 1;
+}
+export interface SalesNote {
+    uuid: string;
+    note_type: string;
+    content: {
+        text: Record<string, string>;
+    };
+    importance: string;
+    note_relations: SalesNoteRelation[];
+}
+export interface SalesNoteTarget {
+    target_type: 'order_detail';
+    target_uuid: string;
+}
+export interface SetSalesNoteInput {
+    note_type: string;
+    target: SalesNoteTarget;
+    text: SalesNoteTextInput;
+}
+export interface SalesNoteDraftInput {
+    note_type: string;
+    text: SalesNoteTextInput;
+}
+export interface SalesNotesRuntimeState {
+    loaded: boolean;
+    dirty: boolean;
+}
+/**
+ * Sales Notes 乐观写入前的可恢复快照。
+ * 该对象应视为 opaque token，只用于原样传回 restoreSalesNotesMutationSnapshot。
+ */
+export interface SalesNotesMutationSnapshot {
+    orderIdentity: {
+        orderId: number | string | null;
+        externalSaleNumber: string;
+    };
+    notes: SalesNote[];
+    state: SalesNotesRuntimeState;
+}
+export type SalesNoteProtocolRelation = SalesNoteRelation;
+export type SalesNoteProtocol = SalesNote;
 export interface OrderTempOrder {
     order_id: number | null;
     external_sale_number: string;
@@ -277,6 +350,7 @@ export interface OrderTempOrder {
     created_at: string | undefined;
     request_unique_idempotency_token?: string;
     products: OrderProduct[];
+    notes: SalesNote[];
     bookings: any[];
     payments: any[];
     surcharges: any[];
@@ -289,6 +363,7 @@ export interface OrderTempOrder {
     summary?: OrderSummary;
     _extend?: {
         productsByUid?: Record<string, Record<string, any>>;
+        salesNotesState?: SalesNotesRuntimeState;
         [key: string]: any;
     };
 }
@@ -297,7 +372,7 @@ export interface OrderSubmitProduct extends Omit<OrderProduct, 'unique_identific
     payment_price: string;
     product_sku: OrderProductSku;
 }
-export interface OrderSubmitPayload extends Omit<OrderTempOrder, 'platform' | 'products' | '_extend' | 'customer' | 'discount_list' | 'created_at'> {
+export interface OrderSubmitPayload extends Omit<OrderTempOrder, 'platform' | 'products' | 'notes' | '_extend' | 'customer' | 'discount_list' | 'created_at'> {
     platform: string;
     created_at?: string | undefined;
     request_unique_idempotency_token?: string;
@@ -306,6 +381,7 @@ export interface OrderSubmitPayload extends Omit<OrderTempOrder, 'platform' | 'p
         form_record_id: number | string;
     }>;
     products: OrderSubmitProduct[];
+    notes?: SalesNoteProtocol[];
     summary?: OrderSummary;
     small_ticket_data_flag?: number;
 }
@@ -334,6 +410,8 @@ export interface AddProductToOrderOptions {
     insertAfterProductUid?: string;
     /** 跳过同商品/规格匹配，始终新增购物车行。 */
     disableMerge?: boolean;
+    /** 商品行 UID 落定后，由 OrderModule 原子绑定到该行的 Sales Notes 草稿。 */
+    salesNotes?: SalesNoteDraftInput[];
 }
 /**
  * 删除商品后的可选位置保持策略。
@@ -749,9 +827,17 @@ export interface OrderModuleAPI {
     updateTempOrderShopDiscount: (amount: string | number) => string;
     updateTempOrderDepositAmount: (amount: string | number) => OrderSummary;
     updateTempOrderCustomer: (customer: UpdateTempOrderCustomerInput) => OrderSnapshot['customer'];
+    updateTempOrderPickupReferenceMode: (mode: PickupReferenceMode) => ShopServiceData;
+    updateTempOrderServiceType: (serviceType: ShopServiceType) => ShopServiceData;
     updateTempOrderBuzzer: (buzzer: string) => string;
     updateTempOrderContactsInfo: (contactsInfo: Record<string, any> | null) => Record<string, any> | null;
     addProductToOrder: (product: Partial<OrderProduct> & OrderProductIdentity, booking?: AddProductBookingInput, options?: AddProductToOrderOptions) => Promise<OrderProduct[]>;
+    getSalesNotes: () => SalesNote[];
+    createSalesNotesMutationSnapshot: () => SalesNotesMutationSnapshot;
+    restoreSalesNotesMutationSnapshot: (snapshot: SalesNotesMutationSnapshot) => void;
+    setSalesNote: (input: SetSalesNoteInput) => Promise<SalesNote>;
+    removeSalesNote: (uuid: string) => Promise<void>;
+    clearSalesNotes: () => Promise<void>;
     updateOrderProduct: (params: UpdateOrderProductParams) => Promise<OrderProduct[]>;
     /** 批量更新购物车行，末尾仅触发一次促销重算与 summary 刷新 */
     updateOrderProducts: (paramsList: UpdateOrderProductParams[]) => Promise<OrderProduct[]>;
@@ -899,10 +985,10 @@ export interface OrderModuleAPI {
     /** 读取上次 applyPromotion 产出的赠品操作 diff（toAdd / toReduce / toRemove） */
     getLastGiftActions: () => OrderLastGiftActions | null;
     /**
-   * 取消订单
-   * @param params 取消订单参数
-   * @returns 后端返回结果
-   */
+     * 取消订单
+     * @param params 取消订单参数
+     * @returns 后端返回结果
+     */
     cancelOrder: (params: CancelOrderParams) => Promise<any>;
     /**
      * 变更预约状态