@pisell/pisellos 1.0.142 → 1.0.143

package/lib/model/strategy/adapter/itemRule/examples.d.ts

@@ -0,0 +1,79 @@
+import type { StrategyConfig } from '../../type';
+/**
+ * 场景：火锅店扫码点餐，要求小料数量 >= 成人人数，自动添加到购物车
+ *
+ * WHEN: Always active
+ * THEN:
+ *   - Quantity Check: 小料最少数量 = Adult Pax
+ *   - Prefill Cart: 自动添加小料 x Adult Pax
+ */
+export declare const MIN_CONDIMENT_PER_PERSON_STRATEGY: StrategyConfig;
+/**
+ * 场景：包子限量供应，每桌最多3份（含加单累计），肉包和菜包合计
+ *
+ * WHEN: Always active
+ * THEN:
+ *   - Quantity Check: 肉包 + 菜包 合计 <= 3，scope=cumulative
+ */
+export declare const MAX_BUNS_PER_TABLE_STRATEGY: StrategyConfig;
+/**
+ * 场景：堂食必须选择一个锅底（按商品匹配），自动预填默认锅底
+ *
+ * WHEN: Service Type = Dine-in
+ * THEN:
+ *   - Quantity Check: 指定锅底商品精确1份
+ *   - Prefill Cart: 自动添加默认锅底 x 1
+ */
+export declare const HOTPOT_BASE_REQUIRED_STRATEGY: StrategyConfig;
+/**
+ * 场景：4 款锅底里任选至少 1 款，不自动预填，不限制多选上限
+ *
+ * WHEN: Always active
+ * THEN:
+ *   - Quantity Check: 4 个锅底商品合计数量 >= 1 （OR 组语义）
+ *
+ * 说明：
+ *   - targets 里放多个 product_id 时，ItemRuleAdapter 会把它们视为 OR 组，
+ *     仅校验「合计数量」，不会要求每款各自满足 min。
+ *   - ScanOrder 工具层 buildQuantityLimitIndex 会跳过多目标规则的
+ *     单品索引，避免 UI 把组级 min 误当作每张商品卡的减号下限，
+ *     锁死用户切换锅底的操作。
+ */
+export declare const HOTPOT_BASE_PICK_ONE_STRATEGY: StrategyConfig;
+/**
+ * ItemRuleEvaluator 简洁调用示例
+ *
+ * 覆盖方法：
+ * - setStrategyConfigs
+ * - getStrategyConfigs
+ * - evaluate
+ * - getQuantityLimits
+ * - validateCart
+ * - getPrefillItems
+ */
+export declare function quickUseItemRuleEvaluator(): {
+    configCount: number;
+    evaluation: import("./type").ItemRuleEvaluationResult;
+    quantityLimits: import("./type").QuantityLimitResult[];
+    validation: {
+        passed: boolean;
+        failures: import("./type").QuantityCheckResult[];
+    };
+    prefillItems: import("./type").PrefillItemResult[];
+};
+/**
+ * ItemRuleEvaluator 完整可运行 Demo
+ *
+ * 说明：
+ * 1) 首次提交：触发 first_submission_only + cumulative + 条件规则
+ * 2) 追加提交：演示 first_submission_only 不再触发
+ * 3) 覆盖 strategyConfigs 临时传入：演示按需仅评估部分规则
+ */
+export declare function runItemRuleEvaluatorDemo(): {
+    firstEvaluation: import("./type").ItemRuleEvaluationResult;
+    validateResult: {
+        passed: boolean;
+        failures: import("./type").QuantityCheckResult[];
+    };
+    prefillItems: import("./type").PrefillItemResult[];
+};

package/lib/model/strategy/adapter/itemRule/examples.js

@@ -0,0 +1,316 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/model/strategy/adapter/itemRule/examples.ts
+var examples_exports = {};
+__export(examples_exports, {
+  HOTPOT_BASE_PICK_ONE_STRATEGY: () => HOTPOT_BASE_PICK_ONE_STRATEGY,
+  HOTPOT_BASE_REQUIRED_STRATEGY: () => HOTPOT_BASE_REQUIRED_STRATEGY,
+  MAX_BUNS_PER_TABLE_STRATEGY: () => MAX_BUNS_PER_TABLE_STRATEGY,
+  MIN_CONDIMENT_PER_PERSON_STRATEGY: () => MIN_CONDIMENT_PER_PERSON_STRATEGY,
+  quickUseItemRuleEvaluator: () => quickUseItemRuleEvaluator,
+  runItemRuleEvaluatorDemo: () => runItemRuleEvaluatorDemo
+});
+module.exports = __toCommonJS(examples_exports);
+var import_evaluator = require("./evaluator");
+var import_type = require("./type");
+var MIN_CONDIMENT_PER_PERSON_STRATEGY = {
+  metadata: {
+    id: "RULE_MIN_CONDIMENT_PER_PERSON",
+    name: {
+      "zh-CN": "每人至少一份小料",
+      en: "Min 1 Condiment per person"
+    },
+    type: "item_rule",
+    description: {
+      "zh-CN": "火锅小料数量不少于成人人数，自动添加",
+      en: "Condiment count must be at least adult pax, auto-added to cart"
+    }
+  },
+  conditions: {
+    operator: "and",
+    rules: [],
+    actionIds: ["quantity_check_condiment", "prefill_condiment"]
+  },
+  actions: [
+    {
+      id: "quantity_check_condiment",
+      type: import_type.ITEM_RULE_ACTION_TYPES.QUANTITY_CHECK,
+      value: null,
+      target: "cart",
+      priority: 10,
+      config: {
+        targetType: "product",
+        targets: [{ product_id: 10001 }, { product_id: 10002 }],
+        quantityRules: [
+          { comparison: "minimum", source: "total_pax" }
+        ],
+        scope: "first_submission_only",
+        validationMessage: {
+          "zh-CN": "小料至少需要 {min} 份（每位成人一份）",
+          en: "Condiment requires at least {min} items (one per adult)"
+        }
+      }
+    },
+    {
+      id: "prefill_condiment",
+      type: import_type.ITEM_RULE_ACTION_TYPES.PREFILL_CART,
+      value: null,
+      target: "cart",
+      priority: 5,
+      config: {
+        products: [
+          {
+            product_id: 10001,
+            quantityFrom: "total_pax"
+          }
+        ]
+      }
+    }
+  ]
+};
+var MAX_BUNS_PER_TABLE_STRATEGY = {
+  metadata: {
+    id: "RULE_MAX_BUNS_PER_TABLE",
+    name: {
+      "zh-CN": "每桌限量供应3份包子",
+      en: "3 Buns limit per table"
+    },
+    type: "item_rule",
+    description: {
+      "zh-CN": "肉包和菜包合计每桌不超过3份，含加单累计",
+      en: "Max 3 buns per table (pork + veggie combined, cumulative)"
+    }
+  },
+  conditions: {
+    operator: "and",
+    rules: [],
+    actionIds: ["quantity_check_buns"]
+  },
+  actions: [
+    {
+      id: "quantity_check_buns",
+      type: import_type.ITEM_RULE_ACTION_TYPES.QUANTITY_CHECK,
+      value: null,
+      target: "cart",
+      priority: 10,
+      config: {
+        targetType: "product",
+        targets: [
+          { product_id: 20001 },
+          { product_id: 20002 }
+        ],
+        quantityRules: [
+          { comparison: "maximum", source: "fixed", value: 3 }
+        ],
+        scope: "cumulative",
+        validationMessage: {
+          "zh-CN": "包子每桌限量 {max} 份（含加单累计）",
+          en: "Buns are limited to {max} per table (cumulative)"
+        }
+      }
+    }
+  ]
+};
+var HOTPOT_BASE_REQUIRED_STRATEGY = {
+  metadata: {
+    id: "RULE_HOTPOT_BASE_REQUIRED",
+    name: {
+      "zh-CN": "锅底必选",
+      en: "Hotpot base required"
+    },
+    type: "item_rule",
+    description: {
+      "zh-CN": "堂食必须选择一个锅底",
+      en: "Hotpot base is mandatory for dine-in"
+    }
+  },
+  conditions: {
+    operator: "and",
+    rules: [
+      {
+        type: "operator",
+        dimension: "context",
+        field: "serviceType",
+        operator: "=",
+        value: "dine-in"
+      }
+    ],
+    actionIds: ["quantity_check_base", "prefill_base"]
+  },
+  actions: [
+    {
+      id: "quantity_check_base",
+      type: import_type.ITEM_RULE_ACTION_TYPES.QUANTITY_CHECK,
+      value: null,
+      target: "cart",
+      priority: 10,
+      config: {
+        targetType: "product",
+        targets: [{ product_id: 30001 }],
+        quantityRules: [
+          { comparison: "exact", source: "fixed", value: 1 }
+        ],
+        scope: "first_submission_only",
+        validationMessage: {
+          "zh-CN": "请选择 {exact} 个锅底",
+          en: "Please select exactly {exact} hotpot base"
+        }
+      }
+    },
+    {
+      id: "prefill_base",
+      type: import_type.ITEM_RULE_ACTION_TYPES.PREFILL_CART,
+      value: null,
+      target: "cart",
+      priority: 5,
+      config: {
+        products: [
+          {
+            product_id: 30001,
+            quantityFrom: "fixed",
+            quantity: 1
+          }
+        ]
+      }
+    }
+  ]
+};
+var HOTPOT_BASE_PICK_ONE_STRATEGY = {
+  metadata: {
+    id: "RULE_HOTPOT_BASE_PICK_ONE",
+    name: {
+      "zh-CN": "锅底必选（四选一）",
+      en: "Hotpot base required (pick any)"
+    },
+    type: "item_rule",
+    description: {
+      "zh-CN": "4 款锅底任选至少 1 份",
+      en: "Pick at least 1 hotpot base from the available options"
+    }
+  },
+  conditions: {
+    operator: "and",
+    rules: [],
+    actionIds: ["quantity_check_hotpot_base_group"]
+  },
+  actions: [
+    {
+      id: "quantity_check_hotpot_base_group",
+      type: import_type.ITEM_RULE_ACTION_TYPES.QUANTITY_CHECK,
+      value: null,
+      target: "cart",
+      priority: 10,
+      config: {
+        targetType: "product",
+        targets: [
+          { product_id: 30001 },
+          { product_id: 30002 },
+          { product_id: 30003 },
+          { product_id: 30004 }
+        ],
+        quantityRules: [
+          { comparison: "minimum", source: "fixed", value: 1 }
+        ],
+        scope: "first_submission_only",
+        validationMessage: {
+          "zh-CN": "请至少选择 {min} 款锅底",
+          en: "Please select at least {min} hotpot base"
+        }
+      }
+    }
+  ]
+};
+function quickUseItemRuleEvaluator() {
+  const evaluator = new import_evaluator.ItemRuleEvaluator();
+  evaluator.setStrategyConfigs([
+    MIN_CONDIMENT_PER_PERSON_STRATEGY,
+    MAX_BUNS_PER_TABLE_STRATEGY,
+    HOTPOT_BASE_REQUIRED_STRATEGY
+  ]);
+  const businessData = {
+    pax: { total: 3, adult: 3, child: 0 },
+    serviceType: "dine-in",
+    cartItems: [
+      { product_id: 10001, quantity: 1 },
+      { product_id: 20001, quantity: 2 },
+      { product_id: 20002, quantity: 1 }
+    ],
+    historicalItems: [{ product_id: 20001, quantity: 1 }],
+    submissionIndex: 0
+  };
+  return {
+    configCount: evaluator.getStrategyConfigs().length,
+    evaluation: evaluator.evaluate(businessData),
+    quantityLimits: evaluator.getQuantityLimits(businessData),
+    validation: evaluator.validateCart(businessData),
+    prefillItems: evaluator.getPrefillItems(businessData)
+  };
+}
+function runItemRuleEvaluatorDemo() {
+  const evaluator = new import_evaluator.ItemRuleEvaluator();
+  evaluator.setStrategyConfigs([
+    MIN_CONDIMENT_PER_PERSON_STRATEGY
+    // MAX_BUNS_PER_TABLE_STRATEGY,
+    // HOTPOT_BASE_REQUIRED_STRATEGY,
+  ]);
+  const firstSubmissionData = {
+    pax: { total: 4, adult: 3, child: 1 },
+    serviceType: "dine-in",
+    submissionIndex: 0,
+    cartItems: [
+      { product_id: 10001, quantity: 3 }
+      // { product_id: 20001, quantity: 2 },
+      // { product_id: 20002, quantity: 1 },
+    ],
+    historicalItems: [{ product_id: 20001, quantity: 1 }]
+  };
+  const additionalSubmissionData = {
+    ...firstSubmissionData,
+    submissionIndex: 1
+  };
+  const firstEvaluation = evaluator.evaluate(firstSubmissionData);
+  const additionalEvaluation = evaluator.evaluate(additionalSubmissionData);
+  const quantityLimits = evaluator.getQuantityLimits(firstSubmissionData);
+  const validateResult = evaluator.validateCart(firstSubmissionData);
+  const prefillItems = evaluator.getPrefillItems(firstSubmissionData);
+  const baseOnlyEvaluation = evaluator.evaluate({
+    ...firstSubmissionData,
+    strategyConfigs: [HOTPOT_BASE_REQUIRED_STRATEGY]
+  });
+  return {
+    // configuredRuleIds: evaluator
+    //   .getStrategyConfigs()
+    //   .map((config) => config.metadata.id),
+    firstEvaluation,
+    // additionalEvaluation,
+    // quantityLimits,
+    validateResult,
+    prefillItems
+    // baseOnlyEvaluation,
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HOTPOT_BASE_PICK_ONE_STRATEGY,
+  HOTPOT_BASE_REQUIRED_STRATEGY,
+  MAX_BUNS_PER_TABLE_STRATEGY,
+  MIN_CONDIMENT_PER_PERSON_STRATEGY,
+  quickUseItemRuleEvaluator,
+  runItemRuleEvaluatorDemo
+});

package/lib/model/strategy/adapter/itemRule/index.d.ts

@@ -0,0 +1,5 @@
+export { ItemRuleEvaluator } from './evaluator';
+export { ItemRuleAdapter } from './adapter';
+export { default } from './adapter';
+export { MIN_CONDIMENT_PER_PERSON_STRATEGY, MAX_BUNS_PER_TABLE_STRATEGY, HOTPOT_BASE_REQUIRED_STRATEGY, HOTPOT_BASE_PICK_ONE_STRATEGY, quickUseItemRuleEvaluator, runItemRuleEvaluatorDemo, } from './examples';
+export * from './type';

package/lib/model/strategy/adapter/itemRule/index.js

@@ -0,0 +1,60 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/model/strategy/adapter/itemRule/index.ts
+var itemRule_exports = {};
+__export(itemRule_exports, {
+  HOTPOT_BASE_PICK_ONE_STRATEGY: () => import_examples.HOTPOT_BASE_PICK_ONE_STRATEGY,
+  HOTPOT_BASE_REQUIRED_STRATEGY: () => import_examples.HOTPOT_BASE_REQUIRED_STRATEGY,
+  ItemRuleAdapter: () => import_adapter.ItemRuleAdapter,
+  ItemRuleEvaluator: () => import_evaluator.ItemRuleEvaluator,
+  MAX_BUNS_PER_TABLE_STRATEGY: () => import_examples.MAX_BUNS_PER_TABLE_STRATEGY,
+  MIN_CONDIMENT_PER_PERSON_STRATEGY: () => import_examples.MIN_CONDIMENT_PER_PERSON_STRATEGY,
+  default: () => import_adapter2.default,
+  quickUseItemRuleEvaluator: () => import_examples.quickUseItemRuleEvaluator,
+  runItemRuleEvaluatorDemo: () => import_examples.runItemRuleEvaluatorDemo
+});
+module.exports = __toCommonJS(itemRule_exports);
+var import_evaluator = require("./evaluator");
+var import_adapter = require("./adapter");
+var import_adapter2 = __toESM(require("./adapter"));
+var import_examples = require("./examples");
+__reExport(itemRule_exports, require("./type"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HOTPOT_BASE_PICK_ONE_STRATEGY,
+  HOTPOT_BASE_REQUIRED_STRATEGY,
+  ItemRuleAdapter,
+  ItemRuleEvaluator,
+  MAX_BUNS_PER_TABLE_STRATEGY,
+  MIN_CONDIMENT_PER_PERSON_STRATEGY,
+  quickUseItemRuleEvaluator,
+  runItemRuleEvaluatorDemo,
+  ...require("./type")
+});

package/lib/model/strategy/adapter/itemRule/type.d.ts

@@ -0,0 +1,225 @@
+import type { StrategyConfig, EvaluationResult } from '../../type';
+export declare const ITEM_RULE_ACTION_TYPES: {
+    /** 数量校验 */
+    readonly QUANTITY_CHECK: "QUANTITY_CHECK";
+    /** 预填购物车 */
+    readonly PREFILL_CART: "PREFILL_CART";
+};
+export type ItemRuleActionType = (typeof ITEM_RULE_ACTION_TYPES)[keyof typeof ITEM_RULE_ACTION_TYPES];
+export declare const ITEM_RULE_TEMPLATES: {
+    /** 空白规则 */
+    readonly BLANK: "blank";
+    /** 人数关联最少量（每人至少N份） */
+    readonly MINIMUM_PER_PERSON: "minimum_per_person";
+    /** 每桌限量 */
+    readonly MAXIMUM_PER_TABLE: "maximum_per_table";
+    /** 必选商品 */
+    readonly MUST_INCLUDE: "must_include";
+};
+export type ItemRuleTemplate = (typeof ITEM_RULE_TEMPLATES)[keyof typeof ITEM_RULE_TEMPLATES];
+/** 数量比较类型 */
+export type QuantityComparison = 'minimum' | 'maximum' | 'exact' | 'must_include';
+/** 数量来源 */
+export type QuantitySource = 'total_pax' | 'adult_pax' | 'fixed';
+/** 目标类型（当前仅支持按商品） */
+export type TargetType = 'product';
+/** 作用范围 */
+export type RuleScope = 'each_submission' | 'first_submission_only' | 'subsequent_only' | 'cumulative';
+/**
+ * 单条数量规则
+ *
+ * 例如：Minimum + Total Pax 表示"最少数量 = 总人数"
+ * 例如：Maximum + Fixed + 10 表示"最多10份"
+ */
+export interface QuantityRule {
+    /** 比较方式 */
+    comparison: QuantityComparison;
+    /** 数量来源 */
+    source: QuantitySource;
+    /** 固定值（当 source 为 'fixed' 时使用） */
+    value?: number;
+}
+/**
+ * Quantity Check Action 的详细配置
+ *
+ * 存储在 ActionEffect.config 中
+ */
+export interface QuantityCheckConfig {
+    /** 目标类型 */
+    targetType: TargetType;
+    /** 目标商品 ID 列表 */
+    targets: TargetItem[];
+    /** 数量规则列表（多条规则同时生效） */
+    quantityRules: QuantityRule[];
+    /** 作用范围 */
+    scope: RuleScope;
+    /** 校验失败时的提示语，支持 {min} {max} 占位符，支持多语言 */
+    validationMessage?: string | Record<string, string>;
+}
+/** 目标项 */
+export interface TargetItem {
+    /** 目标商品 ID */
+    product_id: number;
+    /** 变体 ID */
+    product_variant_id?: number;
+}
+/**
+ * 预填商品项
+ */
+export interface PrefillProduct {
+    /** 商品 ID */
+    product_id: number;
+    /** 变体 ID（可选，0 或不填表示无变体/默认） */
+    product_variant_id?: number;
+    /** 数量来源 */
+    quantityFrom: QuantitySource;
+    /** 固定数量（当 quantityFrom 为 'fixed' 时使用） */
+    quantity?: number;
+}
+/**
+ * Prefill Cart Action 的详细配置
+ *
+ * 存储在 ActionEffect.config 中
+ */
+export interface PrefillCartConfig {
+    /** 要预填的商品列表 */
+    products: PrefillProduct[];
+}
+/**
+ * 购物车商品摘要
+ */
+export interface CartItemSummary {
+    /** 商品 ID */
+    product_id: number;
+    /** 变体 ID */
+    product_variant_id?: number;
+    /** 数量 */
+    quantity: number;
+}
+/**
+ * 就餐人数信息
+ */
+export interface PaxInfo {
+    /** 总人数 */
+    total: number;
+    /** 成人人数 */
+    adult: number;
+    /** 儿童人数 */
+    child: number;
+}
+/**
+ * ItemRule 评估器的输入业务数据
+ */
+export interface ItemRuleBusinessData {
+    /** 就餐人数 */
+    pax: PaxInfo;
+    /** 当前购物车商品列表 */
+    cartItems: CartItemSummary[];
+    /** 历史订单商品列表（用于 cumulative scope，主订单+加单的商品汇总） */
+    historicalItems?: CartItemSummary[];
+    /** 服务类型（如 'dine-in', 'takeaway'） */
+    serviceType?: string;
+    /** 当前提交次数（0=首次提交, >0=追加提交） */
+    submissionIndex?: number;
+    /** 策略配置列表（可选，如果不传则使用 setStrategyConfigs 设置的） */
+    strategyConfigs?: StrategyConfig[];
+    /** 自定义属性（会合并到 context.attributes） */
+    custom?: Record<string, any>;
+}
+/**
+ * 单个 Quantity Check 的校验结果
+ */
+export interface QuantityCheckResult {
+    /** 规则 ID（对应 ActionEffect.id） */
+    ruleId: string;
+    /** 是否通过校验 */
+    passed: boolean;
+    /** 目标类型 */
+    targetType: TargetType;
+    /** 目标列表 */
+    targets: TargetItem[];
+    /** 当前购物车中的实际数量 */
+    actualQuantity: number;
+    /** 要求的最小数量（根据规则计算后的值） */
+    requiredMin?: number;
+    /** 要求的最大数量 */
+    requiredMax?: number;
+    /** 要求的精确数量 */
+    requiredExact?: number;
+    /** 是否必须包含（must_include） */
+    mustInclude?: boolean;
+    /** 格式化后的校验提示语 */
+    validationMessage?: string;
+    /** 作用范围 */
+    scope: RuleScope;
+    /** 未通过的具体规则 */
+    failedRules?: QuantityRule[];
+}
+/**
+ * 单个 Prefill Cart 的预填结果
+ */
+export interface PrefillItemResult {
+    /** 规则 ID（对应 ActionEffect.id） */
+    ruleId: string;
+    /** 商品 ID */
+    product_id: number;
+    /** 变体 ID */
+    product_variant_id?: number;
+    /** 应添加的数量 */
+    quantity: number;
+}
+/**
+ * 单条规则的数量限制（不含校验结果，仅描述配置中的约束）
+ */
+export interface QuantityLimitResult {
+    /** 规则 ID（对应 ActionEffect.id） */
+    ruleId: string;
+    /** 目标类型 */
+    targetType: TargetType;
+    /** 目标列表 */
+    targets: TargetItem[];
+    /** 要求的最小数量 */
+    requiredMin?: number;
+    /** 要求的最大数量（规则配置的原始上限，用于 UI 文案展示） */
+    requiredMax?: number;
+    /**
+     * 当前提交剩余可选的最大数量。
+     *
+     * 仅在 scope='cumulative' 且存在 requiredMax 时计算：
+     *   remainingMax = max(0, requiredMax - historicalItems 中目标商品累计数量)
+     *
+     * 非 cumulative 场景不设置此字段；调用方用于限制加购上限时，
+     * 应优先读取本字段，未定义时回退到 requiredMax。
+     */
+    remainingMax?: number;
+    /** 要求的精确数量 */
+    requiredExact?: number;
+    /** 是否必须包含 */
+    mustInclude?: boolean;
+    /** 作用范围 */
+    scope: RuleScope;
+    /**
+     * 校验失败时的提示语（已做 {min}/{max}/{exact} 占位符替换）。
+     * 当 rawValidationMessage 为多语言对象时，后端不做 locale 选择，
+     * 默认按 en → Object.values()[0] 的顺序兜底，前端可再根据自身 locale
+     * 读取 rawValidationMessage 做精确匹配。
+     */
+    validationMessage?: string;
+    /** 原始多语言模板，前端可根据自身 locale 做二次选择 */
+    rawValidationMessage?: string | Record<string, string>;
+}
+/**
+ * ItemRule 评估器的完整输出结果
+ */
+export interface ItemRuleEvaluationResult {
+    /** 所有数量校验结果 */
+    quantityChecks: QuantityCheckResult[];
+    /** 需要预填的商品列表 */
+    prefillItems: PrefillItemResult[];
+    /** 所有校验是否全部通过 */
+    allPassed: boolean;
+    /** 未通过的校验列表 */
+    failedChecks: QuantityCheckResult[];
+    /** 原始策略评估结果列表 */
+    rawResults: EvaluationResult[];
+}