@pisell/pisellos 2.1.130 → 2.1.131

package/lib/solution/ScanOrder/index.js

@@ -35,8 +35,12 @@ __export(ScanOrder_exports, {
 module.exports = __toCommonJS(ScanOrder_exports);
 var import_BaseModule = require("../../modules/BaseModule");
 var import_types = require("./types");
+var import_Order = require("../../modules/Order");
+var import_types2 = require("../../modules/Account/types");
+var import_types3 = require("../RegisterAndLogin/types");
+var import_decimal = __toESM(require("decimal.js"));
 var import_utils = require("./utils");
-var import_types2 = require("../BookingByStep/types");
+var import_types4 = require("../BookingByStep/types");
 var import_ProductList = require("../../modules/ProductList");
 var import_Schedule = require("../../modules/Schedule");
 var import_getDateIsInSchedule = require("../../modules/Schedule/getDateIsInSchedule");
@@ -74,6 +78,9 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
     this.itemRuleRuntimeConfig = {};
     /** 最近一次 checkResourceAvailable 从预约规则 link 拉取的商品快照 */
     this.enabledReservationRuleProducts = [];
+    this.loginEffectDisposers = [];
+    this.customerLoginRefreshInFlight = null;
+    this.customerLoginRefreshIdInFlight = null;
   }
   getScanOrderLoggerContext() {
     return {
@@ -157,6 +164,119 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
       }
     });
   }
+  normalizeCustomerId(value) {
+    const customerId = Number(value);
+    if (!Number.isFinite(customerId) || customerId <= 0)
+      return null;
+    return customerId;
+  }
+  resolveCustomerIdFromLoginPayload(payload) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i;
+    const candidates = [
+      payload == null ? void 0 : payload.customerId,
+      payload == null ? void 0 : payload.customer_id,
+      payload == null ? void 0 : payload.id,
+      (_a = payload == null ? void 0 : payload.user) == null ? void 0 : _a.customerId,
+      (_b = payload == null ? void 0 : payload.user) == null ? void 0 : _b.customer_id,
+      (_c = payload == null ? void 0 : payload.user) == null ? void 0 : _c.id,
+      (_e = (_d = payload == null ? void 0 : payload.user) == null ? void 0 : _d._origin) == null ? void 0 : _e.customer_id,
+      (_f = payload == null ? void 0 : payload.account) == null ? void 0 : _f.customerId,
+      (_g = payload == null ? void 0 : payload.account) == null ? void 0 : _g.customer_id,
+      (_h = payload == null ? void 0 : payload.account) == null ? void 0 : _h.id,
+      (_i = payload == null ? void 0 : payload._origin) == null ? void 0 : _i.customer_id
+    ];
+    for (const candidate of candidates) {
+      const customerId = this.normalizeCustomerId(candidate);
+      if (customerId)
+        return customerId;
+    }
+    return null;
+  }
+  clearLoginEffectListeners() {
+    for (const dispose of this.loginEffectDisposers) {
+      dispose();
+    }
+    this.loginEffectDisposers = [];
+  }
+  registerLoginEffect(event, callback) {
+    var _a;
+    const effects = (_a = this.core) == null ? void 0 : _a.effects;
+    if (!(effects == null ? void 0 : effects.on))
+      return;
+    effects.on(event, callback);
+    this.loginEffectDisposers.push(() => {
+      if (typeof effects.off === "function") {
+        effects.off(event, callback);
+      }
+    });
+  }
+  registerCustomerLoginListeners() {
+    this.clearLoginEffectListeners();
+    const createHandleLogin = () => async (payload) => {
+      const customerId = this.resolveCustomerIdFromLoginPayload(payload);
+      if (!customerId)
+        return;
+      await this.refreshOrderMarketingAfterLogin({ customerId });
+    };
+    this.registerLoginEffect(
+      _ScanOrderImpl.PISELL1_LOGIN_SUCCESS,
+      createHandleLogin()
+    );
+    this.registerLoginEffect(import_types2.AccountHooks.OnLogin, createHandleLogin());
+    this.registerLoginEffect(
+      import_types3.RegisterAndLoginHooks.onLoginSuccess,
+      createHandleLogin()
+    );
+  }
+  async refreshOrderMarketingAfterLogin(params) {
+    if (!this.store.order)
+      throw new Error("order 模块未初始化");
+    if (this.customerLoginRefreshInFlight) {
+      if (this.customerLoginRefreshIdInFlight === params.customerId) {
+        await this.customerLoginRefreshInFlight;
+        return;
+      }
+      await this.customerLoginRefreshInFlight;
+    }
+    this.customerLoginRefreshIdInFlight = params.customerId;
+    const refreshTask = (async () => {
+      await this.store.order.loadDiscountConfig({
+        customerId: params.customerId
+      });
+      await this.store.order.recalculateSummary({ createIfMissing: true });
+      this.store.order.persistTempOrder();
+      await this.refreshItemRuleQuantityLimits();
+      await this.refreshCartValidationPassed();
+    })();
+    this.customerLoginRefreshInFlight = refreshTask;
+    try {
+      await refreshTask;
+    } catch (error) {
+      throw error;
+    } finally {
+      if (this.customerLoginRefreshInFlight === refreshTask) {
+        this.customerLoginRefreshInFlight = null;
+        this.customerLoginRefreshIdInFlight = null;
+      }
+    }
+  }
+  /** 与 `otherParams.cacheId` 一致，供宿主在 URL 变化时判断是否需要重新注册模块 */
+  getCacheId() {
+    return this.cacheId;
+  }
+  async destroyRegisteredChildModules() {
+    const modules = [
+      this.store.schedule,
+      this.store.salesSummary,
+      this.store.order,
+      this.store.products,
+      this.store.scanOrderLogger
+    ];
+    for (const mod of modules) {
+      if (mod && typeof mod.destroy === "function")
+        await Promise.resolve(mod.destroy());
+    }
+  }
   async initialize(core, options = {}) {
     var _a, _b, _c, _d, _e, _f;
     this.logMethodStart("initialize");
@@ -195,7 +315,7 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
     ];
     moduleArr.forEach((step) => {
       var _a2, _b2, _c2, _d2, _e2, _f2;
-      const targetModule = (0, import_types2.createModule)(step, this.name);
+      const targetModule = (0, import_types4.createModule)(step, this.name);
       if (targetModule) {
         this.store[step] = targetModule;
         const initialState = step === "salesSummary" ? {
@@ -236,6 +356,7 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
         fatherModule: this.name
       }
     });
+    this.registerCustomerLoginListeners();
     console.log("[ScanOrder] 初始化开始");
     try {
       await ((_e = this.store.order) == null ? void 0 : _e.recalculateSummary({ createIfMissing: false }));
@@ -269,7 +390,10 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
   }
   async destroy() {
     this.logMethodStart("destroy");
+    this.clearLoginEffectListeners();
     await this.core.effects.emit(import_types.ScanOrderHooks.onDestroy, {});
+    await this.destroyRegisteredChildModules();
+    super.destroy();
     console.log("[ScanOrder] 已销毁");
     this.logMethodSuccess("destroy");
   }
@@ -494,6 +618,134 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
       throw error;
     }
   }
+  getDiscountList() {
+    if (!this.store.order)
+      return [];
+    return this.store.order.getDiscountList();
+  }
+  async scanCode(code, customerId) {
+    this.logMethodStart("scanCode", { code });
+    try {
+      if (!this.store.order)
+        throw new Error("order 模块未初始化");
+      const raw = await this.store.order.scanCode(code, customerId);
+      if (raw.isAvailable) {
+        await this.store.order.recalculateSummary({ createIfMissing: true });
+        this.store.order.persistTempOrder();
+      }
+      this.logMethodSuccess("scanCode", { isAvailable: raw.isAvailable });
+      return {
+        isAvailable: raw.isAvailable,
+        type: raw.type,
+        unavailableReason: raw.unavailableReason
+      };
+    } catch (error) {
+      this.logMethodError("scanCode", error);
+      throw error;
+    }
+  }
+  async setDiscountSelected(params) {
+    var _a, _b, _c, _d, _e;
+    this.logMethodStart("setDiscountSelected", params);
+    try {
+      if (!this.store.order)
+        throw new Error("order 模块未初始化");
+      const list = this.store.order.getDiscountList();
+      const updated = list.map(
+        (d) => d.id === params.discountId ? {
+          ...d,
+          isSelected: params.isSelected,
+          isManualSelect: !params.isSelected
+        } : d
+      );
+      const tempOrder = this.store.order.ensureTempOrder();
+      const orderStore = this.store.order.store || {};
+      const discountModule = orderStore.discount;
+      const rulesModule = orderStore.rules;
+      const holders = ((_a = tempOrder.holder) == null ? void 0 : _a.form_record_id) ? [{ form_record_id: tempOrder.holder.form_record_id }] : [];
+      let nextDiscountList = updated;
+      await (discountModule == null ? void 0 : discountModule.setDiscountList(updated));
+      if (rulesModule) {
+        const result = rulesModule.calcDiscount(
+          {
+            productList: tempOrder.products,
+            discountList: updated,
+            holders,
+            isFormSubject: !!((_b = tempOrder.holder) == null ? void 0 : _b.type) && tempOrder.holder.type === "form"
+          },
+          {
+            discountId: params.discountId,
+            isSelected: params.isSelected
+          }
+        ) || { productList: tempOrder.products, discountList: updated };
+        if (result == null ? void 0 : result.productList) {
+          tempOrder.products = result.productList;
+        }
+        if (result == null ? void 0 : result.discountList) {
+          nextDiscountList = result.discountList;
+          if (!params.isSelected) {
+            const beforeSelectedIds = new Set(
+              updated.filter((d) => d.isSelected).map((d) => d.id)
+            );
+            for (const d of nextDiscountList) {
+              if (d.isSelected && !beforeSelectedIds.has(d.id)) {
+                d.isSelected = false;
+              }
+            }
+          }
+        }
+      }
+      const selectedResourceIds = new Set(
+        nextDiscountList.filter((d) => d.isSelected).map((d) => d.id)
+      );
+      for (const product of tempOrder.products) {
+        if ((_c = product._origin) == null ? void 0 : _c.isManualDiscount)
+          continue;
+        product.discount_list = (product.discount_list || []).filter((pd) => {
+          var _a2;
+          const rid = ((_a2 = pd.discount) == null ? void 0 : _a2.resource_id) ?? pd.id;
+          return rid != null && selectedResourceIds.has(rid);
+        });
+        const totalPerUnitDiscount = (product.discount_list || []).reduce(
+          (sum, pd) => sum + (pd.amount || 0),
+          0
+        );
+        const optionSum = (0, import_utils2.sumOptionUnitPrice)(product.product_option_item);
+        const sourcePrice = ((_d = product.metadata) == null ? void 0 : _d.source_product_price) ?? (((_e = product.metadata) == null ? void 0 : _e.main_product_original_price) != null ? new import_decimal.default(Number(product.metadata.main_product_original_price) || 0).minus(optionSum).toFixed(2) : product.original_price ?? "0");
+        const newSourceSellingPrice = new import_decimal.default(Number(sourcePrice) || 0).minus(totalPerUnitDiscount).toDecimalPlaces(2).toString();
+        const newMainSellingPrice = new import_decimal.default(Number(newSourceSellingPrice) || 0).plus(optionSum).toDecimalPlaces(2).toFixed(2);
+        if (product.metadata) {
+          product.metadata.main_product_selling_price = newMainSellingPrice;
+          product.metadata.price_schema_version = 2;
+        }
+        product.selling_price = (0, import_utils2.composeLinePrice)({
+          mainPrice: newMainSellingPrice,
+          bundle: product.product_bundle
+        });
+      }
+      import_Order.OrderModule.populateSavedAmounts(tempOrder.products, nextDiscountList);
+      await (discountModule == null ? void 0 : discountModule.setDiscountList(nextDiscountList));
+      tempOrder.discount_list = (nextDiscountList || []).filter((d) => d.isSelected);
+      await this.store.order.recalculateSummary({ createIfMissing: true });
+      this.store.order.persistTempOrder();
+      this.logMethodSuccess("setDiscountSelected", params);
+    } catch (error) {
+      this.logMethodError("setDiscountSelected", error);
+      throw error;
+    }
+  }
+  async onCustomerLogin(params) {
+    this.logMethodStart("onCustomerLogin", { customerId: params.customerId });
+    try {
+      await this.refreshOrderMarketingAfterLogin({
+        customerId: params.customerId
+      });
+      this.logMethodSuccess("onCustomerLogin", { customerId: params.customerId });
+    } catch (error) {
+      this.logMethodError("onCustomerLogin", error);
+      throw error;
+    }
+  }
   // ScanOrder 提交 payload enhancer：
   // - 给所有 booking 注入 appointment_status: 'started'（扫码点餐语义）
   // - 给所有 booking 的 metadata 注入 resource_select_type（来自预约规则商品的 resource.type）
@@ -515,7 +767,7 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
       return 1;
     };
     return (payload, { bookingUuid, tempOrder }) => {
-      var _a;
+      var _a, _b;
       const resourceId = tempOrder.resource_id ?? (resourceState == null ? void 0 : resourceState.relationId);
       const pickOriginal = (value) => {
         if (value && typeof value === "object" && !Array.isArray(value)) {
@@ -536,20 +788,31 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
         metadata: {}
       } : void 0;
       const ruleProductUid = ruleProduct ? (0, import_utils2.createUuidV4)() : void 0;
-      const bookingCapacityValue = resolveResourceCapacity();
+      const rawCollectPax = (_b = tempOrder.metadata) == null ? void 0 : _b.collect_pax;
+      const hasCollectPaxForCapacity = rawCollectPax !== null && rawCollectPax !== void 0 && rawCollectPax !== "";
+      const bookingCapacityValue = hasCollectPaxForCapacity ? (0, import_utils2.normalizeSubmitCollectPaxValue)(rawCollectPax) : resolveResourceCapacity();
+      const bookingCapacityDimensionId = (0, import_utils.pickFirstCustomCapacityDimensionId)(this.enabledReservationRuleProducts) ?? 0;
       const nextBookings = (payload.bookings || []).map((booking, idx) => ({
         ...booking,
         appointment_status: "started",
         metadata: {
           ...booking.metadata || {},
           ...resourceSelectType ? { resource_select_type: resourceSelectType } : {},
-          ...resourceSelectType ? { capacity: [{ id: 0, value: bookingCapacityValue, name: "" }] } : {}
+          ...resourceSelectType ? {
+            capacity: [
+              {
+                id: bookingCapacityDimensionId,
+                value: bookingCapacityValue,
+                name: ""
+              }
+            ]
+          } : {}
         },
         ...idx === 0 && resourceEntry ? { resources: [resourceEntry] } : {},
         ...idx === 0 && ruleProductUid ? { product_uid: ruleProductUid } : {}
       }));
       const nextProducts = [...payload.products || []];
-      if (ruleProduct && ruleProductUid) {
+      if (ruleProduct && ruleProductUid && !tempOrder.order_id) {
         const sellingPrice = String(ruleProduct.price ?? "0.00");
         const originalPrice = String(
           ruleProduct.original_price ?? ruleProduct.price ?? "0.00"
@@ -655,6 +918,36 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
       throw error;
     }
   }
+  /**
+   * 设置单行商品备注（与整单 `updateTempOrderNote` 区分）。
+   * 多行同 SKU 时必须传入与删除/更新一致的 identity（如 `identity_key`）。
+   */
+  async setOrderProductLineNote(identity, note) {
+    this.logMethodStart("setOrderProductLineNote", {
+      product_id: identity.product_id,
+      product_variant_id: identity.product_variant_id
+    });
+    try {
+      const params = {
+        product_id: identity.product_id,
+        product_variant_id: identity.product_variant_id,
+        updates: { note: String(note || "") }
+      };
+      if (identity.identity_key !== void 0)
+        params.identity_key = identity.identity_key;
+      if (identity.product_option_item !== void 0) {
+        params.product_option_item = identity.product_option_item;
+      }
+      if (identity.product_bundle !== void 0)
+        params.product_bundle = identity.product_bundle;
+      const products = await this.updateProductInOrder(params);
+      this.logMethodSuccess("setOrderProductLineNote", { productCount: products.length });
+      return products;
+    } catch (error) {
+      this.logMethodError("setOrderProductLineNote", error);
+      throw error;
+    }
+  }
   async removeProductFromOrder(identity) {
     this.logMethodStart("removeProductFromOrder", {
       product_id: identity.product_id,
@@ -1035,7 +1328,7 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
     const relationId = (0, import_utils.toPositiveString)(detail == null ? void 0 : detail.form_record_id);
     const tableFormId = (0, import_utils.toPositiveString)(detail == null ? void 0 : detail.form_id);
     const formRecord = (detail == null ? void 0 : detail.form_record) ?? null;
-    const allowSnack = ((_b = (_a = this.otherParams) == null ? void 0 : _a.dineInConfig) == null ? void 0 : _b["workflow.allow_add_items"]) || false;
+    const allowSnack = ((_b = (_a = this.otherParams) == null ? void 0 : _a.dineInConfig) == null ? void 0 : _b["sale.allow_add_items"]) || false;
     const deskmateValid = false;
     const isExclusive = resourceSelectType === "single";
     const isFull = (0, import_utils.computeResourceIsFull)({
@@ -1394,10 +1687,10 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
   readUIStateBucket() {
     var _a;
     const key = this.getUIStateBucketKey();
-    if (!key || !((_a = this.window) == null ? void 0 : _a.sessionStorage))
+    if (!key || !((_a = this.window) == null ? void 0 : _a.localStorage))
       return {};
     try {
-      const raw = this.window.sessionStorage.getItem(key) || "{}";
+      const raw = this.window.localStorage.getItem(key) || "{}";
       const parsed = JSON.parse(raw);
       return parsed && typeof parsed === "object" ? parsed : {};
     } catch {
@@ -1407,10 +1700,10 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
   writeUIStateBucket(bucket) {
     var _a;
     const key = this.getUIStateBucketKey();
-    if (!key || !((_a = this.window) == null ? void 0 : _a.sessionStorage))
+    if (!key || !((_a = this.window) == null ? void 0 : _a.localStorage))
       return;
     try {
-      this.window.sessionStorage.setItem(key, JSON.stringify(bucket));
+      this.window.localStorage.setItem(key, JSON.stringify(bucket));
     } catch (error) {
       console.warn("[ScanOrder] writeUIStateBucket failed", error);
     }
@@ -1441,10 +1734,10 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
   clearUIState() {
     var _a;
     const key = this.getUIStateBucketKey();
-    if (!key || !((_a = this.window) == null ? void 0 : _a.sessionStorage))
+    if (!key || !((_a = this.window) == null ? void 0 : _a.localStorage))
       return;
     try {
-      this.window.sessionStorage.removeItem(key);
+      this.window.localStorage.removeItem(key);
     } catch (error) {
       console.warn("[ScanOrder] clearUIState failed", error);
     }
@@ -1499,11 +1792,19 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
   }
 };
 var ScanOrderImpl = _ScanOrderImpl;
-// ─── UI 状态缓存（按 cacheId 分桶，sessionStorage） ───
+ScanOrderImpl.PISELL1_LOGIN_SUCCESS = "pisell1.login.success";
+// ─── UI 状态缓存（按 cacheId 分桶，localStorage） ───
 //
 // 用于物料层持久化 UI 层面的轻量状态（如当前步骤、gate 标记、登录回跳意图等）。
 // 桶键：pisell.scanOrder.uiState:<cacheId>；内部以 JSON object 形式存储多个字段。
 // 无 cacheId 时所有方法自动降级为 no-op，上层不用判空。
+//
+// 之所以用 localStorage 而不是 sessionStorage：
+//   1. 与 Order 模块 openCache 下的 tempOrder 同栈，购物车在 / UIState 在，行为对齐；
+//   2. pisell1.login 整页 OAuth 跳转在 H5 壳 / iOS Safari 场景下可能丢 sessionStorage，
+//      导致登录回跳后 gate 标记失效、pax 弹窗重开、落点错误；localStorage 稳定不受影响。
+//   3. 失效由上层显式控制：提交成功 clearStepCache / entryContext 不一致 clearUIState /
+//      pendingStep 登录回调 deleteUIState，足够约束生命周期。
 ScanOrderImpl.UI_STATE_KEY_PREFIX = "pisell.scanOrder.uiState:";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/lib/solution/ScanOrder/types.d.ts

@@ -31,26 +31,70 @@ export interface ScanOrderOrderProductIdentity {
     product_id: number | null;
     product_variant_id: number;
     identity_key?: string;
+    /** 参与合并/匹配；与 remove 通配语义见 isSkuOnlyDeleteIdentity */
+    product_option_item?: any[];
+    product_bundle?: any[];
 }
 export interface ScanOrderOrderProduct extends ScanOrderOrderProductIdentity {
     order_detail_id: number | null;
     num: number;
     product_option_item: any[];
-    /** 券后单品单价（= 订单域实际成交单价）。未应用券时等同 original_price。 */
+    /**
+     * 券后 **行 composite 单价** = `metadata.main_product_selling_price`
+     *   + Σ((bundle.bundle_selling_price ?? bundle.price) × (bundle.num ?? 1))
+     *
+     * 新语义 v2 下 `metadata.main_product_selling_price` 已经**含 option**、含主商品折扣，
+     * 因此本字段不再叠加 option。未应用券时等同 `original_price`。
+     * Rules 钩子、主商品计税、Summary 统一读 metadata，不以此字段反推。
+     */
     selling_price: string;
-    /** 券前单品单价（= 店铺售价），不承载后台划线价语义。 */
+    /**
+     * 券前 **行 composite 单价** = `metadata.main_product_original_price`
+     *   + Σ(bundle 原价 × num)
+     *
+     * 新语义 v2 下 `metadata.main_product_original_price` 已经**含 option**、不含折扣。
+     * 不承载后台划线价语义。
+     */
     original_price: string;
     tax_fee: string;
     is_charge_tax: number;
     discount_list: any[];
     product_bundle: any[];
+    /**
+     * 行级扩展 metadata。价格相关的权威字段：
+     *
+     * - `source_product_price`：主商品/variant 基础价（已应用报价单），**不含 option、不含折扣**。
+     *   是派生 `main_product_*` 的唯一源。variant 分支优先读 `metadata.origin.variant[vid].price`。
+     * - `main_product_original_price` = `source_product_price + Σ(option.price × option.num)`，
+     *   **含 option、不含折扣**。
+     * - `main_product_selling_price` = `main_product_original_price − 主商品券 per-unit amount`，
+     *   **含 option、含主商品折扣**。Rules 钩子 / Summary / 计税均以此为主商品权威源。
+     * - `price_schema_version`（当前 = 2）：schema 版本 sentinel，用于跨端协商价格口径、
+     *   区分 v1 旧缓存以便 `normalizeOrderProduct` 触发迁移。
+     */
     metadata: Record<string, any>;
+    /** 商品行备注（如顾客对单品的特殊要求） */
+    note?: string;
     _origin?: Record<string, any>;
 }
+/**
+ * 出站 payload 版本的商品行。
+ *
+ * 与 tempOrder 内部 `ScanOrderOrderProduct` 的字段差异：
+ * - `product_option_item[*]`：内部为 `{ product_option_item_id, option_group_id, num, price, ... }`，
+ *   出站由 `normalizeSubmitProduct` 重命名为 `{ option_group_item_id, option_group_id, num }`
+ *   （后端 checkout 协议；丢弃 `price` 等运行时辅助字段）。
+ * - `product_bundle[*].option[*]`：同上重命名规则。
+ *
+ * 运行时（UI 显示、加购合并、指纹、持久化）全部消费内部字段名 `product_option_item_id`，
+ * 仅在 SDK 提交边界做一次出站映射，不影响 opaque identity 契约。
+ */
 export interface ScanOrderSubmitProduct extends Omit<ScanOrderOrderProduct, '_origin' | 'identity_key'> {
     /**
      * 出站兼容字段：SDK 内部不再消费 payment_price，
      * 仅在提交后端时由 selling_price 派生，保持原有后端契约。
+     * 新语义 v2 下 selling_price 是 composite（含 option、含 bundle、含主商品折扣），
+     * 因此 payment_price 同样是 composite。
      */
     payment_price: string;
 }
@@ -235,3 +279,9 @@ export interface ScanOrderLoggerRuntimeConfig {
 }
 export interface ScanOrderAddLogParams extends ScanOrderLogInput {
 }
+/** ScanOrder.scanCode 对外的轻量结果（不含 discountList，UI 在 resolve 后调 getDiscountList） */
+export interface ScanOrderScanCodeResult {
+    isAvailable: boolean;
+    type?: 'server' | string;
+    unavailableReason?: 'time_limit' | string;
+}

package/lib/solution/ScanOrder/utils.d.ts

@@ -82,9 +82,24 @@ export declare function buildItemRuleBusinessData(params: {
 }): ItemRuleBusinessData;
 export declare function attachItemRuleLimitsToTopLevelProducts<T>(productList: T, limits: QuantityLimitResult[]): T;
 /**
- * 判断两个商品 identity 是否匹配。
- * 当双方都没有 identity_key 时回退到 product_id + product_variant_id 比较（向后兼容）；
- * 一旦有一方携带 identity_key，则必须严格相等。
+ * 将选项行 / 套餐行归一成稳定 JSON，用于「同 SKU 是否合并」判断。
+ * 数组元素先按主键排序再序列化，避免顺序差异导致误判为不同行。
+ */
+export declare function buildProductLineFingerprint(productOptionItem?: unknown, productBundle?: unknown): string;
+/**
+ * removeProductFromOrder 仅传 SKU 时的通配 identity（对象上未声明选项键）。
+ * 与显式 `product_option_item: []` 区分：后者只匹配「无选项」行。
+ */
+export declare function isSkuOnlyDeleteIdentity(x: ScanOrderOrderProductIdentity): boolean;
+/**
+ * 判断两个商品 identity 是否匹配（不透明 identity 契约）。
+ *
+ * 调用约定：始终 `isIdentityMatch(line, callerIdentity)`。
+ * - 若 SKU（product_id + product_variant_id）不一致 → 不匹配。
+ * - **双方都带** `identity_key` → 严格字符串相等比较（不再猜测合成 key / metadata 桥接）。
+ *   这是 opaque identity 契约的标准路径：UI 删改时透传 SDK 回灌的 identity_key。
+ * - 否则（即至少一侧未声明 identity_key）→ 进入「SKU 通配 / 显式空选项 / 指纹」回退路径，
+ *   忽略线侧 identity_key，按内容语义匹配。这给「行已 opaque、调用方却想按 SKU 通配 / 选项指纹删除」留兼容入口。
  */
 export declare function isIdentityMatch(a: ScanOrderOrderProductIdentity, b: ScanOrderOrderProductIdentity): boolean;
 /**
@@ -93,10 +108,26 @@ export declare function isIdentityMatch(a: ScanOrderOrderProductIdentity, b: Sca
  */
 export declare function getProductIdentityIndex(products: ScanOrderOrderProduct[], identity: ScanOrderOrderProductIdentity): number;
 /**
- * 对外部传入的商品对象做归一化：
+ * 对外部传入的商品对象做归一化（v2 composite 语义）：
  * - 补全可选字段默认值（未传则使用兜底值，避免后续计算时因 undefined 导致异常）
  * - 对 num 调用 getSafeProductNum 做安全处理
  * - 保留 _origin 供后续业务流程（如促销规则）使用
+ *
+ * 价格字段语义（metadata 权威源 + composite 派生）：
+ * - `metadata.source_product_price`：主商品/variant 基础价（已应用报价单），**不含 option**、
+ *   **不含折扣**。是推导 main_product_* 的起点。variant 分支优先读 `metadata.origin.variant[vid].price`。
+ * - `metadata.main_product_original_price`：`source + Σ(option.price × option.num)`，**含 option**、
+ *   **不含折扣**。
+ * - `metadata.main_product_selling_price`：`main_product_original_price - 主商品券 per-unit amount`，
+ *   **含 option**、**含折扣**。
+ * - 行级 `selling_price` = `main_product_selling_price + Σ(bundle_selling_price × num)`。
+ * - 行级 `original_price` = `main_product_original_price + Σ(bundle 原价 × num)`。
+ *
+ * 迁移与幂等：
+ * - `metadata.price_schema_version === 2` → 已新语义归一化，保留 main_product_* 原值（保留折扣）。
+ * - 其它情况（v1 / 缺字段 / 无 metadata）→ 按"main_product_selling_price 曾是 main-only"的旧约定
+ *   反推 legacyDiscount，再以新 source + options 基准重算。最终统一打上 `price_schema_version: 2`。
+ * - 因此多次 normalize 不会重复叠加 option/bundle。
  */
 export declare function normalizeOrderProduct(product: Partial<ScanOrderOrderProduct> & ScanOrderOrderProductIdentity): ScanOrderOrderProduct;
 /**
@@ -112,7 +143,7 @@ export declare function hasCustomCapacityProduct(products: ProductData[]): boole
 /**
  * 根据预约规则商品的 resource.type 计算桌台是否已被"占满"。
  * - single：只要有 `lastOrderId` 即视为占用
- * - multiple：当前时间落在 `capacity_list[i]` 的 `[start_at, end_at]`（inclusive）内的 pax 之和 > 总容量
+ * - multiple：当前时间落在 `capacity_list[i]` 的 `[start_at, end_at]`（inclusive）内的 pax 之和 >= 总容量
  * - 其他（'capacity' / undefined）：返回 false，不施加限制
  */
 export declare function computeResourceIsFull(params: {
@@ -129,3 +160,8 @@ export declare function pickFirstCustomCapacityPaxBounds(products: ProductData[]
     min?: number;
     max?: number;
 } | undefined;
+/**
+ * 第一个 `capacity.type === 'custom'` 的商品，取其 `custom[0].id`（提交 booking metadata.capacity 维度 id）。
+ * 无匹配时返回 `undefined`，调用方应回退为 `0`。
+ */
+export declare function pickFirstCustomCapacityDimensionId(products: ProductData[]): string | number | undefined;