@pisell/pisellos 2.2.301 → 2.2.303

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

@@ -4,6 +4,8 @@ export declare const ITEM_RULE_ACTION_TYPES: {
     readonly QUANTITY_CHECK: "QUANTITY_CHECK";
     /** 预填购物车 */
     readonly PREFILL_CART: "PREFILL_CART";
+    /** 加购前过敏信息确认 */
+    readonly ALLERGY_CHECK: "ALLERGY_CHECK";
 };
 export type ItemRuleActionType = (typeof ITEM_RULE_ACTION_TYPES)[keyof typeof ITEM_RULE_ACTION_TYPES];
 export declare const ITEM_RULE_TEMPLATES: {
@@ -63,6 +65,42 @@ export interface TargetItem {
     /** 变体 ID */
     product_variant_id?: number;
 }
+/** 策略展示文案，可由调用方按当前 locale 解析。 */
+export type ItemRuleLocalizedText = string | Record<string, string>;
+/** 内联过敏源选项。稳定 id 用于保存选择，label 只负责展示。 */
+export interface AllergyDataSourceItem {
+    id: string;
+    label: ItemRuleLocalizedText;
+}
+/** 当前仅支持随策略下发的内联过敏源。 */
+export interface AllergyDataSource {
+    type: 'inline';
+    items: AllergyDataSourceItem[];
+}
+/** 每个目标商品独立持有自己的过敏源，禁止跨商品合并。 */
+export interface AllergyTargetItem extends TargetItem {
+    dataSource: AllergyDataSource;
+}
+export type AllergyPromptScope = 'once_per_order_product';
+/** ALLERGY_CHECK Action 的商品级配置。 */
+export interface AllergyCheckConfig {
+    targetType: 'product';
+    targets: AllergyTargetItem[];
+    promptScope: AllergyPromptScope;
+    allowNote?: boolean;
+}
+/** 当前商品命中的单条过敏门禁要求。 */
+export interface AllergyRequirement {
+    strategyId: string;
+    ruleId: string;
+    priority: number;
+    targetType: 'product';
+    product_id: number;
+    product_variant_id?: number;
+    dataSource: AllergyDataSource;
+    promptScope: AllergyPromptScope;
+    allowNote: boolean;
+}
 /**
  * 预填商品项
  */
@@ -119,6 +157,10 @@ export interface ItemRuleBusinessData {
     historicalItems?: CartItemSummary[];
     /** 服务类型（如 'dine-in', 'takeaway'） */
     serviceType?: string;
+    /** 当前业务渠道（如 'kiosk', 'pos', 'online_store'） */
+    channel?: string;
+    /** 当前正在加入购物车的商品；ALLERGY_CHECK 只读取该商品的 Target。 */
+    currentProduct?: Pick<TargetItem, 'product_id' | 'product_variant_id'>;
     /** 当前提交次数（0=首次提交, >0=追加提交） */
     submissionIndex?: number;
     /** 策略配置列表（可选，如果不传则使用 setStrategyConfigs 设置的） */
@@ -216,6 +258,8 @@ export interface ItemRuleEvaluationResult {
     quantityChecks: QuantityCheckResult[];
     /** 需要预填的商品列表 */
     prefillItems: PrefillItemResult[];
+    /** 当前商品命中的过敏门禁要求；不同 Action/商品不会合并。 */
+    allergyRequirements: AllergyRequirement[];
     /** 所有校验是否全部通过 */
     allPassed: boolean;
     /** 未通过的校验列表 */

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

@@ -12,7 +12,9 @@ const ITEM_RULE_ACTION_TYPES = exports.ITEM_RULE_ACTION_TYPES = {
   /** 数量校验 */
   QUANTITY_CHECK: 'QUANTITY_CHECK',
   /** 预填购物车 */
-  PREFILL_CART: 'PREFILL_CART'
+  PREFILL_CART: 'PREFILL_CART',
+  /** 加购前过敏信息确认 */
+  ALLERGY_CHECK: 'ALLERGY_CHECK'
 };
 // ============================================
 // Rule Template 类型（创建规则时的起始模板）
@@ -56,6 +58,22 @@ const ITEM_RULE_TEMPLATES = exports.ITEM_RULE_TEMPLATES = {
 
 /** 目标项 */
 
+// ============================================
+// Allergy Check 相关类型
+// ============================================
+
+/** 策略展示文案，可由调用方按当前 locale 解析。 */
+
+/** 内联过敏源选项。稳定 id 用于保存选择，label 只负责展示。 */
+
+/** 当前仅支持随策略下发的内联过敏源。 */
+
+/** 每个目标商品独立持有自己的过敏源，禁止跨商品合并。 */
+
+/** ALLERGY_CHECK Action 的商品级配置。 */
+
+/** 当前商品命中的单条过敏门禁要求。 */
+
 // ============================================
 // Prefill Cart 相关类型
 // ============================================

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

@@ -1,46 +1 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "BUY_X_GET_Y_FREE_STRATEGY", {
-  enumerable: true,
-  get: function () {
-    return _examples.BUY_X_GET_Y_FREE_STRATEGY;
-  }
-});
-Object.defineProperty(exports, "ITEM_REWARD_STRATEGY", {
-  enumerable: true,
-  get: function () {
-    return _examples.ITEM_REWARD_STRATEGY;
-  }
-});
-Object.defineProperty(exports, "PromotionAdapter", {
-  enumerable: true,
-  get: function () {
-    return _adapter.PromotionAdapter;
-  }
-});
-Object.defineProperty(exports, "PromotionEvaluator", {
-  enumerable: true,
-  get: function () {
-    return _evaluator.PromotionEvaluator;
-  }
-});
-Object.defineProperty(exports, "X_ITEMS_FOR_Y_PRICE_STRATEGY", {
-  enumerable: true,
-  get: function () {
-    return _examples.X_ITEMS_FOR_Y_PRICE_STRATEGY;
-  }
-});
-Object.defineProperty(exports, "default", {
-  enumerable: true,
-  get: function () {
-    return _adapter.default;
-  }
-});
-var _evaluator = require("./evaluator");
-var _adapter = _interopRequireWildcard(require("./adapter"));
-var _examples = require("./examples");
-function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
-function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && Object.prototype.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+"use strict";

package/lib/modules/BookingContext/utils/buildCacheItemFromOrderLine.js

@@ -181,6 +181,7 @@ function buildCacheItemFromOrderLine(input) {
     booking,
     sourceProduct
   } = input;
+  const holderConfig = sourceProduct?.holder_config ?? sourceProduct?.origin?.holder_config ?? product.metadata?.holder_config;
   const resolvedId = product.product_id ?? sourceProduct?.id;
   const selling = Number(product.selling_price ?? 0);
   const original = Number(product.original_price ?? selling);
@@ -249,6 +250,9 @@ function buildCacheItemFromOrderLine(input) {
   }
   const base = {
     ...(sourceProduct || {}),
+    ...(holderConfig !== undefined && holderConfig !== null ? {
+      holder_config: holderConfig
+    } : {}),
     id: resolvedId,
     product_id: resolvedId,
     extension_type: sourceProduct?.extension_type ?? booking?.product?.extension_type ?? sourceProduct?.extension_type,

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

@@ -25,9 +25,11 @@ export declare class DiscountModule extends BaseModule implements Module, Discou
         with_wallet_pass_holder: 0 | 1;
         with_available_wallet_flag?: 0 | 1;
         with_available_wallet_pass_flag?: 0 | 1;
+        with_virtual_currency?: 0 | 1;
         request_timezone: string;
         order_id?: number | string;
     }): Promise<DiscountPrepareConfigResult>;
+    private normalizeVirtualCurrencyList;
     batchSearch(code: string, options?: {
         customerId?: number;
         orderId?: number;

package/lib/modules/Discount/index.js

@@ -80,21 +80,53 @@ class DiscountModule extends _BaseModule.BaseModule {
     const prepareConfig = await this.request.post(`/order/prepare/config`, {
       ...params,
       with_available_wallet_flag: params.with_available_wallet_flag ?? 1,
-      with_available_wallet_pass_flag: params.with_available_wallet_pass_flag ?? 1
+      with_available_wallet_pass_flag: params.with_available_wallet_pass_flag ?? 1,
+      with_virtual_currency: params.with_virtual_currency ?? 1
     });
     const rawDiscountList = [...(prepareConfig?.data?.good_pass_list || []), ...(prepareConfig?.data?.discount_card_list || [])];
     const availableWalletList = [...(prepareConfig?.data?.avaiable_wallet_list || []), ...(prepareConfig?.data?.available_wallet_list || [])];
     const availableWalletPassList = prepareConfig?.data?.available_wallet_pass_list || [];
     const availableWalletIds = this.normalizePositiveNumberIds([...availableWalletList.map(item => item?.wallet_id), ...availableWalletPassList.map(item => item?.product_id)]);
+    const virtualCurrencyList = this.normalizeVirtualCurrencyList(prepareConfig?.data?.virtual_currency_list);
     const goodPassList = this.filterEnabledDiscountList(rawDiscountList) || [];
 
     // this.setDiscountList(goodPassList);
 
     return {
       discountList: goodPassList,
-      availableWalletIds
+      availableWalletIds,
+      virtualCurrencyList,
+      availableWalletPassList: availableWalletPassList.map(item => ({
+        ...(item || {})
+      }))
     };
   }
+  normalizeVirtualCurrencyList(value) {
+    if (!Array.isArray(value)) return [];
+    return value.flatMap(item => {
+      const id = Number(item?.id);
+      const productId = Number(item?.product_id);
+      if (!Number.isFinite(id) || id <= 0 || !Number.isFinite(productId) || productId <= 0) {
+        return [];
+      }
+      const displayExtension = Array.isArray(item?.extension_data) ? item.extension_data.find(extension => extension?.field_key === 'virtual_currency_display') : undefined;
+      let display = displayExtension?.value;
+      if (typeof display === 'string') {
+        try {
+          display = JSON.parse(display);
+        } catch {
+          display = {};
+        }
+      }
+      return [{
+        ...item,
+        id,
+        product_id: productId,
+        balance: String(item?.balance ?? '0'),
+        virtual_currency_display: display && typeof display === 'object' && !Array.isArray(display) ? display : {}
+      }];
+    });
+  }
   async batchSearch(code, options) {
     const {
       customerId,

package/lib/modules/Discount/types.d.ts

@@ -68,9 +68,30 @@ export interface DiscountWithReason {
     discountList: Discount[];
     unavailableReasonKey: DiscountFilterRejectKey | null;
 }
+export interface WalletPassPrepareConfigItem {
+    id?: number | string | null;
+    tag?: string | null;
+    product_id?: number | string | null;
+    product_name?: string | null;
+    par_value?: string | number | null;
+    used_par_value?: string | number | null;
+    [key: string]: any;
+}
 export interface DiscountPrepareConfigResult {
     discountList: Discount[];
     availableWalletIds: number[];
+    virtualCurrencyList?: VirtualCurrencyAsset[];
+    availableWalletPassList?: WalletPassPrepareConfigItem[];
+}
+export interface VirtualCurrencyAsset extends Record<string, any> {
+    id: number;
+    product_id: number;
+    balance: string;
+    product_name?: string;
+    format_title?: Record<string, any>;
+    code?: string;
+    encoded?: string;
+    virtual_currency_display?: Record<string, any>;
 }
 interface ExtensionData {
     id: number;

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

@@ -1,9 +1,9 @@
 import { Module, PisellCore, ModuleOptions } from '../../types';
 import { BaseModule } from '../BaseModule';
 import type { ScheduleModule } from '../Schedule';
-import type { OpenDataConfig, OpenDataFetchParams, OpenDataAvailabilityResult } from './types';
+import type { OpenDataConfig, OpenDataFetchParams, OpenDataAvailabilityResult, InvoiceLayoutConfig, InvoiceTemplateSettings } from './types';
 export * from './types';
-export { computeAvailability } from './utils';
+export { computeAvailability, getDefaultInvoiceLayoutConfig, getDefaultInvoiceTemplateSettings, normalizeInvoiceLayoutConfig, normalizeInvoiceLayoutFromTemplateSettings, normalizeInvoiceTemplateSettings, normalizeRawInvoiceTemplateSettings, resolveInvoiceReceiptLocales, } from './utils';
 export declare class OpenDataModule extends BaseModule implements Module {
     protected defaultName: string;
     protected defaultVersion: string;
@@ -15,6 +15,10 @@ export declare class OpenDataModule extends BaseModule implements Module {
     private openCache;
     private fatherModule;
     private otherParams;
+    private fetchRevision;
+    private invoiceTemplateCacheRevision;
+    private invoiceTemplateDocumentCache;
+    private invoiceTemplateDocumentInFlight;
     constructor(name?: string, version?: string);
     initialize(core: PisellCore, options: ModuleOptions): Promise<void>;
     /**
@@ -24,8 +28,17 @@ export declare class OpenDataModule extends BaseModule implements Module {
      * openDataModule.updateOtherParams({ openCache: true, cacheId: 'cache-2' })
      */
     updateOtherParams(params: Record<string, any>): void;
+    private shouldSkipInvoiceTemplateDocument;
     fetchOpenData(params: OpenDataFetchParams): Promise<OpenDataConfig>;
     getOpenData(): OpenDataConfig | null;
+    getInvoiceLayoutConfig(): InvoiceLayoutConfig;
+    getInvoiceTemplateSettings(): InvoiceTemplateSettings;
+    ensureInvoiceTemplateSettings(target: string): Promise<InvoiceTemplateSettings>;
+    private commitInvoiceTemplateSettings;
+    private resolveInvoiceTemplateSettings;
+    private buildInvoiceTemplateCacheKey;
+    private fetchInvoiceTemplateDocument;
+    private logInvoiceTemplateDocumentFallback;
     getLastFetchedAt(): number | null;
     /** 清除内存与 sessionStorage 镜像中的 OpenData，供宿主切店时调用。 */
     clearCache(): void;

package/lib/modules/OpenData/index.js

@@ -5,7 +5,14 @@ Object.defineProperty(exports, "__esModule", {
 });
 var _exportNames = {
   OpenDataModule: true,
-  computeAvailability: true
+  computeAvailability: true,
+  getDefaultInvoiceLayoutConfig: true,
+  getDefaultInvoiceTemplateSettings: true,
+  normalizeInvoiceLayoutConfig: true,
+  normalizeInvoiceLayoutFromTemplateSettings: true,
+  normalizeInvoiceTemplateSettings: true,
+  normalizeRawInvoiceTemplateSettings: true,
+  resolveInvoiceReceiptLocales: true
 };
 exports.OpenDataModule = void 0;
 Object.defineProperty(exports, "computeAvailability", {
@@ -14,6 +21,48 @@ Object.defineProperty(exports, "computeAvailability", {
     return _utils.computeAvailability;
   }
 });
+Object.defineProperty(exports, "getDefaultInvoiceLayoutConfig", {
+  enumerable: true,
+  get: function () {
+    return _utils.getDefaultInvoiceLayoutConfig;
+  }
+});
+Object.defineProperty(exports, "getDefaultInvoiceTemplateSettings", {
+  enumerable: true,
+  get: function () {
+    return _utils.getDefaultInvoiceTemplateSettings;
+  }
+});
+Object.defineProperty(exports, "normalizeInvoiceLayoutConfig", {
+  enumerable: true,
+  get: function () {
+    return _utils.normalizeInvoiceLayoutConfig;
+  }
+});
+Object.defineProperty(exports, "normalizeInvoiceLayoutFromTemplateSettings", {
+  enumerable: true,
+  get: function () {
+    return _utils.normalizeInvoiceLayoutFromTemplateSettings;
+  }
+});
+Object.defineProperty(exports, "normalizeInvoiceTemplateSettings", {
+  enumerable: true,
+  get: function () {
+    return _utils.normalizeInvoiceTemplateSettings;
+  }
+});
+Object.defineProperty(exports, "normalizeRawInvoiceTemplateSettings", {
+  enumerable: true,
+  get: function () {
+    return _utils.normalizeRawInvoiceTemplateSettings;
+  }
+});
+Object.defineProperty(exports, "resolveInvoiceReceiptLocales", {
+  enumerable: true,
+  get: function () {
+    return _utils.resolveInvoiceReceiptLocales;
+  }
+});
 var _BaseModule = require("../BaseModule");
 var _utils = require("./utils");
 var _types = require("./types");
@@ -28,6 +77,25 @@ Object.keys(_types).forEach(function (key) {
     }
   });
 });
+function isRecord(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function resolveInvoiceDocumentId(value) {
+  if (typeof value === 'number') {
+    return Number.isSafeInteger(value) && value > 0 ? String(value) : null;
+  }
+  if (typeof value !== 'string') return null;
+  const normalized = value.trim();
+  if (!/^\d+$/.test(normalized)) return null;
+  const numericId = Number(normalized);
+  return Number.isSafeInteger(numericId) && numericId > 0 ? String(numericId) : null;
+}
+function isLegacyInvoiceTemplate(value) {
+  if (typeof value !== 'string' || value.trim().length === 0) return false;
+  const normalized = value.trim();
+  const numericLike = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i;
+  return !numericLike.test(normalized);
+}
 class OpenDataModule extends _BaseModule.BaseModule {
   defaultName = 'openData';
   defaultVersion = '1.0.0';
@@ -39,6 +107,10 @@ class OpenDataModule extends _BaseModule.BaseModule {
   openCache = false;
   fatherModule;
   otherParams = {};
+  fetchRevision = 0;
+  invoiceTemplateCacheRevision = 0;
+  invoiceTemplateDocumentCache = new Map();
+  invoiceTemplateDocumentInFlight = new Map();
   constructor(name, version) {
     super(name, version);
   }
@@ -47,6 +119,12 @@ class OpenDataModule extends _BaseModule.BaseModule {
     this.store = options.store;
     this.store.data = options.initialState?.data ?? null;
     this.store.lastFetchedAt = options.initialState?.lastFetchedAt ?? null;
+    // Document 解析结果只在当前模块实例内复用。页面刷新后即使恢复了原始
+    // OpenData，也必须重新查询一次 NocoBase，以取得当前模板内容。
+    this.store.invoiceTemplateSettings = null;
+    this.store.invoiceTemplateTarget = null;
+    this.store.invoiceTemplateDocumentId = null;
+    this.store.invoiceTemplateCacheKey = null;
     this.otherParams = options.otherParams || {};
     if (this.otherParams.cacheId) {
       this.openCache = this.otherParams.openCache ?? false;
@@ -74,7 +152,11 @@ class OpenDataModule extends _BaseModule.BaseModule {
     this.cacheId = this.otherParams.cacheId;
     this.fatherModule = this.otherParams.fatherModule;
   }
+  shouldSkipInvoiceTemplateDocument() {
+    return String(this.otherParams?.platform || '').trim().toLowerCase() === 'h5';
+  }
   async fetchOpenData(params) {
+    const fetchRevision = ++this.fetchRevision;
     const getData = this.appPlugin?.getData?.();
     const shopId = getData?.('shop_id');
     if (!shopId) throw new Error('[OpenDataModule] 无法获取 shop_id');
@@ -95,21 +177,166 @@ class OpenDataModule extends _BaseModule.BaseModule {
       throw new Error(response?.message || '获取 OpenData 配置失败');
     }
     const data = response?.data || {};
-    this.store.data = data;
-    this.store.lastFetchedAt = Date.now();
+    const resolvedInvoiceTemplate = await this.resolveInvoiceTemplateSettings(data, params.target);
+    // clearCache() 或后续请求发生后，旧响应不得复活已失效的 target 配置。
+    if (fetchRevision === this.fetchRevision) {
+      this.store.data = data;
+      this.store.lastFetchedAt = Date.now();
+      this.commitInvoiceTemplateSettings(params.target, resolvedInvoiceTemplate);
+    }
     return data;
   }
   getOpenData() {
     return this.store.data;
   }
+  getInvoiceLayoutConfig() {
+    return (0, _utils.normalizeInvoiceLayoutFromTemplateSettings)(this.getInvoiceTemplateSettings());
+  }
+  getInvoiceTemplateSettings() {
+    if (this.shouldSkipInvoiceTemplateDocument()) {
+      return (0, _utils.getDefaultInvoiceTemplateSettings)();
+    }
+    if (isRecord(this.store.invoiceTemplateSettings)) {
+      const documentId = resolveInvoiceDocumentId(this.store.data?.['documents.invoice_template']);
+      if (documentId) {
+        const target = this.store.invoiceTemplateTarget;
+        if (!target || this.store.invoiceTemplateCacheKey !== this.buildInvoiceTemplateCacheKey(target, documentId)) {
+          return (0, _utils.getDefaultInvoiceTemplateSettings)();
+        }
+      }
+      return (0, _utils.normalizeRawInvoiceTemplateSettings)(this.store.invoiceTemplateSettings);
+    }
+    if (isLegacyInvoiceTemplate(this.store.data?.['documents.invoice_template'])) {
+      return (0, _utils.normalizeInvoiceTemplateSettings)(this.store.data);
+    }
+    return (0, _utils.getDefaultInvoiceTemplateSettings)();
+  }
+  async ensureInvoiceTemplateSettings(target) {
+    const normalizedTarget = String(target || '').trim();
+    const config = this.store.data;
+    if (!normalizedTarget || !config) {
+      return (0, _utils.getDefaultInvoiceTemplateSettings)();
+    }
+    const fetchRevision = this.fetchRevision;
+    const resolved = await this.resolveInvoiceTemplateSettings(config, normalizedTarget);
+    if (fetchRevision !== this.fetchRevision || this.store.data !== config) {
+      return (0, _utils.getDefaultInvoiceTemplateSettings)();
+    }
+    this.commitInvoiceTemplateSettings(normalizedTarget, resolved);
+    return (0, _utils.normalizeRawInvoiceTemplateSettings)(resolved.settings);
+  }
+  commitInvoiceTemplateSettings(target, resolved) {
+    this.store.invoiceTemplateSettings = (0, _utils.normalizeRawInvoiceTemplateSettings)(resolved.settings);
+    this.store.invoiceTemplateTarget = target;
+    this.store.invoiceTemplateDocumentId = resolved.documentId;
+    this.store.invoiceTemplateCacheKey = resolved.cacheKey;
+  }
+  async resolveInvoiceTemplateSettings(config, target) {
+    if (this.shouldSkipInvoiceTemplateDocument()) {
+      return {
+        settings: (0, _utils.getDefaultInvoiceTemplateSettings)(),
+        documentId: null,
+        cacheKey: null
+      };
+    }
+    const rawTemplate = config['documents.invoice_template'];
+    const documentId = resolveInvoiceDocumentId(rawTemplate);
+    if (!documentId) {
+      return {
+        settings: isLegacyInvoiceTemplate(rawTemplate) ? (0, _utils.normalizeInvoiceTemplateSettings)(config) : (0, _utils.getDefaultInvoiceTemplateSettings)(),
+        documentId: null,
+        cacheKey: null
+      };
+    }
+    const cacheKey = this.buildInvoiceTemplateCacheKey(target, documentId);
+    if (this.store.invoiceTemplateTarget === target && this.store.invoiceTemplateDocumentId === documentId && this.store.invoiceTemplateCacheKey === cacheKey && isRecord(this.store.invoiceTemplateSettings)) {
+      return {
+        settings: (0, _utils.normalizeRawInvoiceTemplateSettings)(this.store.invoiceTemplateSettings),
+        documentId,
+        cacheKey
+      };
+    }
+    const cachedSettings = this.invoiceTemplateDocumentCache.get(cacheKey);
+    if (cachedSettings) {
+      return {
+        settings: (0, _utils.normalizeRawInvoiceTemplateSettings)(cachedSettings),
+        documentId,
+        cacheKey
+      };
+    }
+    let request = this.invoiceTemplateDocumentInFlight.get(cacheKey);
+    if (!request) {
+      const cacheRevision = this.invoiceTemplateCacheRevision;
+      request = this.fetchInvoiceTemplateDocument(documentId).catch(error => {
+        this.logInvoiceTemplateDocumentFallback(error, target, documentId);
+        return (0, _utils.getDefaultInvoiceTemplateSettings)();
+      }).then(settings => {
+        const normalized = (0, _utils.normalizeRawInvoiceTemplateSettings)(settings);
+        if (cacheRevision === this.invoiceTemplateCacheRevision) {
+          this.invoiceTemplateDocumentCache.set(cacheKey, normalized);
+        }
+        return normalized;
+      }).finally(() => {
+        if (this.invoiceTemplateDocumentInFlight.get(cacheKey) === request) {
+          this.invoiceTemplateDocumentInFlight.delete(cacheKey);
+        }
+      });
+      this.invoiceTemplateDocumentInFlight.set(cacheKey, request);
+    }
+    return {
+      settings: await request,
+      documentId,
+      cacheKey
+    };
+  }
+  buildInvoiceTemplateCacheKey(target, documentId) {
+    const getData = this.appPlugin?.getData?.();
+    return JSON.stringify([getData?.('tenant_id') ?? null, getData?.('shop_id') ?? null, target, documentId]);
+  }
+  async fetchInvoiceTemplateDocument(documentId) {
+    const response = await this.request.get(`/document:get?filterByTk=${encodeURIComponent(documentId)}`, {}, {
+      isNocobase: true,
+      prefix: false,
+      headers: {
+        'x-data-source': 'pisell2'
+      },
+      customToast: () => {}
+    });
+    const document = response?.data;
+    if (!document || resolveInvoiceDocumentId(document.id) !== documentId) {
+      throw new Error(`Invoice Document ${documentId} 返回的 ID 不匹配`);
+    }
+    if (document.deleted_at !== null && document.deleted_at !== undefined) {
+      throw new Error(`Invoice Document ${documentId} 已被删除`);
+    }
+    if (!isRecord(document.data) || !isRecord(document.data.template_settings)) {
+      throw new Error(`Invoice Document ${documentId} 缺少 template_settings`);
+    }
+    return (0, _utils.normalizeRawInvoiceTemplateSettings)(document.data.template_settings);
+  }
+  logInvoiceTemplateDocumentFallback(error, target, documentId) {
+    console.warn('[OpenDataModule] Invoice Document 加载失败，使用 DEFAULT', {
+      target,
+      documentId,
+      message: error instanceof Error ? error.message : String(error)
+    });
+  }
   getLastFetchedAt() {
     return this.store.lastFetchedAt ?? null;
   }
 
   /** 清除内存与 sessionStorage 镜像中的 OpenData，供宿主切店时调用。 */
   clearCache() {
+    this.fetchRevision += 1;
+    this.invoiceTemplateCacheRevision += 1;
+    this.invoiceTemplateDocumentCache.clear();
+    this.invoiceTemplateDocumentInFlight.clear();
     this.store.data = null;
     this.store.lastFetchedAt = null;
+    this.store.invoiceTemplateSettings = null;
+    this.store.invoiceTemplateTarget = null;
+    this.store.invoiceTemplateDocumentId = null;
+    this.store.invoiceTemplateCacheKey = null;
   }
   checkAvailability(scheduleModule) {
     const scheduleList = scheduleModule ? scheduleModule?.getScheduleListByIds(this.store.data?.['availability.operating_hours'] || []) : undefined;

package/lib/modules/OpenData/types.d.ts

@@ -8,6 +8,49 @@ export interface MultiLangObject {
     original?: string;
     [key: string]: string | undefined;
 }
+export declare const INVOICE_MODULE_KEYS: readonly ["reference", "brand", "custom_1", "order", "handover", "customer", "line_groups", "settlement", "custom_2", "payment", "card", "total_savings", "custom_3", "barcode"];
+export type InvoiceModuleKey = (typeof INVOICE_MODULE_KEYS)[number];
+/**
+ * Documents Registry 中的 Invoice 模块配置。
+ *
+ * 模块 key、显隐值及模块私有字段均由 Registry/Native 约定，OS 不做枚举收窄或改写。
+ */
+export interface InvoiceTemplateModuleConfig {
+    key: string;
+    is_show?: unknown;
+    [key: string]: unknown;
+}
+export interface InvoiceModuleConfig extends InvoiceTemplateModuleConfig {
+}
+export interface InvoiceLayoutConfig {
+    locale?: string;
+    module: InvoiceModuleConfig[];
+}
+export interface InvoiceTemplateSettings {
+    template: string;
+    language: Record<string, number>;
+    modules: InvoiceTemplateModuleConfig[];
+    [key: string]: unknown;
+}
+export interface InvoiceDocumentResponse {
+    data?: {
+        id?: number | string;
+        deleted_at?: string | null;
+        data?: {
+            template_settings?: unknown;
+        };
+    };
+}
+export type RawInvoiceEditConfig = string | {
+    language?: unknown;
+    modules?: unknown;
+    [key: string]: unknown;
+};
+export type RawInvoiceLayoutConfig = string | {
+    locale?: unknown;
+    module?: unknown[];
+    [key: string]: unknown;
+};
 export interface OpenDataConfig {
     'basic.enable'?: boolean;
     'basic.code'?: string | null;
@@ -45,11 +88,23 @@ export interface OpenDataConfig {
         label: string;
         value: number;
     }>;
+    'documents.invoice_template'?: string | number;
+    'documents.invoice_edit'?: RawInvoiceEditConfig;
+    /** @deprecated 仅保留旧调用方的类型兼容，Invoice 读取逻辑不再消费该字段。 */
+    'documents.invoice'?: RawInvoiceLayoutConfig;
+    /** @deprecated Invoice 读取逻辑只消费扁平的 documents.invoice_* 字段。 */
+    documents?: {
+        invoice?: RawInvoiceLayoutConfig;
+    };
     [key: string]: any;
 }
 export interface OpenDataState {
     data: OpenDataConfig | null;
     lastFetchedAt: number | null;
+    invoiceTemplateSettings?: InvoiceTemplateSettings | null;
+    invoiceTemplateTarget?: string | null;
+    invoiceTemplateDocumentId?: string | null;
+    invoiceTemplateCacheKey?: string | null;
 }
 export interface OpenDataFetchParams {
     scope: string;