@pisell/pisellos 0.10.58 → 0.10.59

package/lib/index.d.ts

@@ -7,6 +7,7 @@ export * from './modules';
 export * from './plugins';
 export * from './solution';
 export * from './model';
+export * from './inventory';
 export { PisellOSCore } from './core';
 import PisellOSCore from './core';
 export default PisellOSCore;

package/lib/index.js

@@ -80,6 +80,18 @@ Object.keys(_model).forEach(function (key) {
     }
   });
 });
+var _inventory = require("./inventory");
+Object.keys(_inventory).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _inventory[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _inventory[key];
+    }
+  });
+});
 var _core = _interopRequireWildcard(require("./core"));
 var _smallTicket = require("./shared/receipt/small-ticket");
 Object.keys(_smallTicket).forEach(function (key) {

package/lib/inventory/index.d.ts

@@ -0,0 +1,92 @@
+/** Optional, instance-scoped sales inventory. Never stored in ProductData or order payloads. */
+export type InventoryRecord = Record<string, any>;
+export type InventoryRefreshReason = 'catalog-entry' | 'detail-open' | 'checkout' | 'manual';
+export interface InventoryAvailability {
+    status: 'ready' | 'loading' | 'stale' | 'error' | 'unmapped';
+    quantity?: number;
+    message?: string;
+}
+export interface InventorySelectionAvailability {
+    availability: InventoryAvailability;
+    /** Stock remaining after other cart lines using the same inventory key. */
+    availableQuantity: number;
+    /** The existing line can still be reduced when stock is unavailable. */
+    retainedQuantity: number;
+    maxQuantity: number;
+}
+export interface InventorySource {
+    readonly scopeKey: string;
+    assertCurrent(): void;
+    keyOf(product: InventoryRecord, variant?: InventoryRecord): string | undefined;
+    read(context: {
+        reason: InventoryRefreshReason;
+        signal: AbortSignal;
+    }): Promise<ReadonlyMap<string, {
+        quantity: number | null;
+        message?: string;
+    }>>;
+    message(reason: 'unavailable' | 'unmapped' | 'insufficient', values?: {
+        key: string;
+        quantity: number;
+    }): string;
+}
+export interface CheckoutInventoryLine {
+    readonly lineId: string;
+    readonly productId: string | number;
+    readonly variantId: string | number;
+    readonly quantity: number;
+    readonly inventoryKey: string;
+}
+export interface CheckoutRuntimeSnapshot {
+    readonly scopeKey: string;
+    readonly revision: number;
+    readonly lines: readonly CheckoutInventoryLine[];
+}
+export interface SalesCheckoutHooks {
+    beforeCheckout?(context: {
+        items: readonly InventoryRecord[];
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+export declare const salesGuardError: (message: string) => Error & {
+    code: string;
+};
+export declare class InventoryController {
+    private readonly source;
+    readonly identity: symbol;
+    readonly scopeKey: string;
+    private entries;
+    private lastQuantities;
+    private products;
+    private keys;
+    private catalogProducts;
+    private listeners;
+    private revision;
+    private state;
+    private pending?;
+    private disposed;
+    constructor(source: InventorySource);
+    getRevision: () => number;
+    subscribe: (listener: () => void) => () => void;
+    private publish;
+    private assertCurrent;
+    activate(): void;
+    dispose(): void;
+    invalidate(): void;
+    /** Catalog replaces identities; partial detail only merges its variants, never its prices. */
+    registerProducts(products: readonly InventoryRecord[], complete?: boolean): void;
+    /** Consumers share I/O; cancelling one detail does not cancel another consumer. */
+    refresh(context: {
+        reason: InventoryRefreshReason;
+        signal?: AbortSignal;
+        force?: boolean;
+    }): Promise<void>;
+    availabilityForKey(key?: string): InventoryAvailability;
+    availability(product: InventoryRecord, variantId?: string | number): InventoryAvailability;
+    private keyForLine;
+    /** Advisory UI limit only. The serialized cart guard remains authoritative. */
+    selectionAvailability(product: InventoryRecord, variantId: string | number, items: readonly InventoryRecord[], editingItem?: InventoryRecord): InventorySelectionAvailability;
+    private totals;
+    validate(proposed: readonly InventoryRecord[], current?: readonly InventoryRecord[], allowReductions?: boolean): void;
+    freezeCheckout(items: readonly InventoryRecord[]): CheckoutRuntimeSnapshot;
+}

package/lib/inventory/index.js

@@ -0,0 +1,280 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.salesGuardError = exports.InventoryController = void 0;
+/** Optional, instance-scoped sales inventory. Never stored in ProductData or order payloads. */
+
+const salesGuardError = message => Object.assign(new Error(message), {
+  code: 'SALES_GUARD_REJECTED'
+});
+exports.salesGuardError = salesGuardError;
+const cancelled = () => Object.assign(new Error('Inventory request cancelled'), {
+  name: 'AbortError'
+});
+const variantIdentity = (productId, variantId) => JSON.stringify([String(productId), String(variantId ?? 0)]);
+class InventoryController {
+  identity = Symbol('sales-inventory-instance');
+  scopeKey;
+  entries = new Map();
+  lastQuantities = new Map();
+  products = new Map();
+  keys = new Map();
+  catalogProducts = new Map();
+  listeners = new Set();
+  revision = 0;
+  state = 'stale';
+  pending;
+  disposed = false;
+  constructor(source) {
+    this.source = source;
+    this.scopeKey = source.scopeKey;
+  }
+  getRevision = () => this.revision;
+  subscribe = listener => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+  publish() {
+    this.revision += 1;
+    this.listeners.forEach(listener => {
+      try {
+        listener();
+      } catch {/* A view cannot interrupt a stock update. */}
+    });
+  }
+  assertCurrent(signal) {
+    if (this.disposed || signal?.aborted) throw cancelled();
+    this.source.assertCurrent();
+  }
+  activate() {
+    this.disposed = false;
+  }
+  dispose() {
+    this.disposed = true;
+    this.invalidate();
+  }
+  invalidate() {
+    this.pending?.controller.abort();
+    this.pending = undefined;
+    this.state = 'stale';
+    this.publish();
+  }
+
+  /** Catalog replaces identities; partial detail only merges its variants, never its prices. */
+  registerProducts(products, complete = false) {
+    this.assertCurrent();
+    let changed = false;
+    for (const product of products) {
+      const id = String(product.id ?? product.product_id);
+      if (complete && this.catalogProducts.get(id) === product) continue;
+      if (complete) this.catalogProducts.set(id, product);
+      const previous = this.products.get(id);
+      if (complete) for (const variantId of previous?.keys() || []) this.keys.delete(variantIdentity(id, variantId));
+      const variants = complete ? new Map() : new Map(previous);
+      const list = product.variant?.length ? product.variant : [{
+        id: 0,
+        code: product.code
+      }];
+      for (const variant of list) {
+        const variantId = String(variant.id ?? variant.product_variant_id ?? 0);
+        const key = this.source.keyOf(product, variant) ?? previous?.get(variantId);
+        variants.set(variantId, key);
+        this.keys.set(variantIdentity(id, variantId), key);
+      }
+      if (!previous || previous.size !== variants.size || [...variants].some(([id, key]) => previous.get(id) !== key)) changed = true;
+      this.products.set(id, variants);
+    }
+    if (changed) this.publish();
+  }
+
+  /** Consumers share I/O; cancelling one detail does not cancel another consumer. */
+  async refresh(context) {
+    this.assertCurrent(context.signal);
+    if (context.force) this.invalidate();
+    let read = this.pending;
+    if (!read) {
+      read = {
+        controller: new AbortController(),
+        consumers: 0,
+        promise: Promise.resolve()
+      };
+      const current = read;
+      this.pending = current;
+      this.state = 'loading';
+      this.publish();
+      current.promise = (async () => {
+        try {
+          const entries = await this.source.read({
+            reason: context.reason,
+            signal: current.controller.signal
+          });
+          this.assertCurrent(current.controller.signal);
+          if (this.pending !== current) throw cancelled();
+          this.entries = entries;
+          for (const [key, stock] of entries) if (stock.quantity !== null && Number.isSafeInteger(stock.quantity) && stock.quantity >= 0) this.lastQuantities.set(key, stock.quantity);
+          this.state = 'ready';
+        } catch (error) {
+          if (this.pending !== current || current.controller.signal.aborted) throw cancelled();
+          this.state = 'error';
+          throw error;
+        } finally {
+          if (this.pending === current) {
+            this.pending = undefined;
+            this.publish();
+          }
+        }
+      })();
+    }
+    read.consumers += 1;
+    try {
+      if (!context.signal) await read.promise;else await new Promise((resolve, reject) => {
+        const signal = context.signal;
+        const abort = () => reject(cancelled());
+        signal.addEventListener('abort', abort, {
+          once: true
+        });
+        read.promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+        if (signal.aborted) abort();
+      });
+      this.assertCurrent(context.signal);
+    } finally {
+      read.consumers -= 1;
+      if (this.pending === read && read.consumers === 0) this.invalidate();
+    }
+  }
+  availabilityForKey(key) {
+    const stock = key ? this.entries.get(key) : undefined;
+    const quantity = key ? this.lastQuantities.get(key) : undefined;
+    if (this.state !== 'ready') return {
+      status: this.state,
+      quantity,
+      message: this.source.message('unavailable')
+    };
+    if (!stock) return {
+      status: 'unmapped',
+      quantity,
+      message: this.source.message('unmapped')
+    };
+    if (stock.quantity === null || !Number.isSafeInteger(stock.quantity) || stock.quantity < 0) return {
+      status: 'error',
+      quantity,
+      message: stock.message || this.source.message('unavailable')
+    };
+    return {
+      status: 'ready',
+      quantity: stock.quantity
+    };
+  }
+  availability(product, variantId) {
+    const id = product.id ?? product.product_id;
+    if (variantId !== undefined && variantId !== null) return this.availabilityForKey(this.keys.get(variantIdentity(id, variantId)));
+    const keys = [...new Set(this.products.get(String(id))?.values() || [])];
+    const states = keys.map(key => this.availabilityForKey(key));
+    if (!states.length) return this.availabilityForKey();
+    const quantity = states.every(entry => entry.quantity !== undefined) ? states.reduce((sum, entry) => sum + entry.quantity, 0) : undefined;
+    const failed = states.find(entry => entry.status !== 'ready');
+    if (quantity !== undefined && !Number.isSafeInteger(quantity)) return {
+      status: 'error',
+      message: this.source.message('unavailable')
+    };
+    return {
+      status: failed?.status || 'ready',
+      quantity,
+      message: failed?.message
+    };
+  }
+  keyForLine(item) {
+    return this.keys.get(variantIdentity(item.product_id, item.product_variant_id ?? item.product_sku?.product_variant_id));
+  }
+  /** Advisory UI limit only. The serialized cart guard remains authoritative. */
+  selectionAvailability(product, variantId, items, editingItem) {
+    const identity = variantIdentity(product.id ?? product.product_id, variantId);
+    const key = this.keys.get(identity);
+    let availability = this.availabilityForKey(key);
+    let reserved = 0;
+    let retainedQuantity = 0;
+    for (const item of items) {
+      const matches = key ? this.keyForLine(item) === key : variantIdentity(item.product_id, item.product_variant_id ?? item.product_sku?.product_variant_id) === identity;
+      if (!matches) continue;
+      const count = Number(item.num ?? item.quantity);
+      if (!Number.isSafeInteger(count) || count < 0) {
+        availability = {
+          ...availability,
+          status: 'error',
+          message: this.source.message('unavailable')
+        };
+        continue;
+      }
+      if (item === editingItem) retainedQuantity = count;else reserved += count;
+    }
+    if (!Number.isSafeInteger(reserved)) {
+      availability = {
+        ...availability,
+        status: 'error',
+        message: this.source.message('unavailable')
+      };
+    }
+    const availableQuantity = availability.status === 'ready' ? Math.max(0, availability.quantity - reserved) : 0;
+    return {
+      availability,
+      availableQuantity,
+      retainedQuantity,
+      maxQuantity: Math.max(availableQuantity, retainedQuantity)
+    };
+  }
+  totals(items) {
+    const totals = new Map();
+    for (const item of items) {
+      const key = this.keyForLine(item);
+      const identity = key ? JSON.stringify(['inventory', key]) : variantIdentity(item.product_id, item.product_variant_id);
+      const quantity = Number(item.num ?? item.quantity);
+      if (!Number.isSafeInteger(quantity) || quantity < 0) throw salesGuardError(this.source.message('unavailable'));
+      if (!quantity) continue;
+      const total = (totals.get(identity)?.quantity || 0) + quantity;
+      if (!Number.isSafeInteger(total)) throw salesGuardError(this.source.message('unavailable'));
+      totals.set(identity, {
+        key,
+        quantity: total
+      });
+    }
+    return totals;
+  }
+  validate(proposed, current = [], allowReductions = true) {
+    this.assertCurrent();
+    const previous = this.totals(current);
+    for (const [identity, {
+      key,
+      quantity
+    }] of this.totals(proposed)) {
+      if (allowReductions && quantity <= (previous.get(identity)?.quantity || 0)) continue;
+      const stock = this.availabilityForKey(key);
+      if (stock.status !== 'ready') throw salesGuardError(stock.message || this.source.message('unavailable'));
+      if (quantity > stock.quantity) throw salesGuardError(this.source.message('insufficient', {
+        key: key,
+        quantity: stock.quantity
+      }));
+    }
+  }
+  freezeCheckout(items) {
+    if (!items.length || items.some(item => Number(item.num ?? item.quantity) <= 0)) {
+      throw salesGuardError(this.source.message('unavailable'));
+    }
+    this.validate(items, [], false);
+    return Object.freeze({
+      scopeKey: this.scopeKey,
+      revision: this.revision,
+      lines: Object.freeze(items.map((item, index) => Object.freeze({
+        lineId: String(item.metadata?.unique_identification_number ?? item.unique_identification_number ?? item.order_detail_id ?? index),
+        productId: item.product_id,
+        variantId: item.product_variant_id ?? item.product_sku?.product_variant_id ?? 0,
+        quantity: Number(item.num ?? item.quantity),
+        inventoryKey: this.keyForLine(item)
+      })))
+    });
+  }
+}
+exports.InventoryController = InventoryController;

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

@@ -4,7 +4,7 @@ import { OrderModuleAPI, CommitOrderParams, UpdateOrderBookingParams, UpdateOrde
 import { CartItem } from '../Cart/types';
 import { type SubmitPayloadEnhancer } from './utils';
 import { type PickupTimingBooking, type PickupTimingBookingInput } from './pickupTiming';
-import type { OrderAmountSnapshot, AddProductBookingInput, AddProductToOrderOptions, OrderIdentitySnapshot, OrderPaymentSource, OrderSnapshot, OrderSyncState, SyncPaymentsToOrderParams, SyncPaymentsToOrderResult, SubmitSalesOrderParams, OrderProduct, OrderProductIdentity, OrderSummary, OrderTempOrder, OrderPaymentData, OrderPaymentUpdateOptions, OrderPaymentUpdateResult, SendCustomerPayLinkParams, UpdateTempOrderCustomerInput, OrderCustomerPatch, OrderCustomerView, OrderCartIntentCommitContext, ReplaceTempOrderOptions, OrderPromotionEvaluator, OrderGiftSelectResolver, OrderUnfulfilledPromotion, OrderLastGiftActions, RemoveProductsFromOrderOptions, SalesNote, SalesNotesMutationSnapshot, SetSalesNoteInput, PickupReferenceMode, PointCardSnapshotMergeContext, PointCardSnapshotItem, ShopServiceData, ShopServiceType } from './types';
+import type { OrderAmountSnapshot, AddProductBookingInput, AddProductToOrderOptions, OrderIdentitySnapshot, OrderPaymentSource, OrderSnapshot, OrderSyncState, SyncPaymentsToOrderParams, SyncPaymentsToOrderResult, SubmitSalesOrderParams, OrderProduct, OrderProductIdentity, OrderSummary, OrderTempOrder, OrderPaymentData, OrderPaymentUpdateOptions, OrderPaymentUpdateResult, SendCustomerPayLinkParams, UpdateTempOrderCustomerInput, OrderCustomerPatch, OrderCustomerView, OrderHooksConfig, OrderCartIntentCommitContext, ReplaceTempOrderOptions, OrderPromotionEvaluator, OrderGiftSelectResolver, OrderUnfulfilledPromotion, OrderLastGiftActions, RemoveProductsFromOrderOptions, SalesNote, SalesNotesMutationSnapshot, SetSalesNoteInput, PickupReferenceMode, PointCardSnapshotMergeContext, PointCardSnapshotItem, ShopServiceData, ShopServiceType } from './types';
 import type { ICustomer } from '../AccountList/types';
 import type { Discount } from '../Discount/types';
 import { UnavailableReason } from '../Rules/types';
@@ -29,6 +29,12 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     private rulesHooksOverride?;
     private moduleHooksOverride?;
     private orderHooks?;
+    private cartCommandQueue;
+    private queueCartCommand;
+    /** Use the exact Order normalizers/merge rules on a private draft, not a second projection. */
+    private beginCartMutation;
+    /** Serializes checkout preparation with local cart commands; hydration remains outside this guard. */
+    prepareCheckout<T>(prepare: (items: OrderProduct[]) => Promise<T>): Promise<T>;
     private otherParams?;
     /** 评估器引用；由 SalesSdkProvider 注入，未注入时 applyPromotion 静默跳过 */
     private promotionEvaluator;
@@ -66,7 +72,11 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
      * @example
      * orderModule.updateOtherParams({ cacheId: 'cache-2', channel: 'pos' });
      */
-    updateOtherParams(params: Record<string, any>): void;
+    updateOtherParams(params: Record<string, any>, options?: {
+        hooks?: OrderHooksConfig;
+        changedParams?: Record<string, any>;
+        cover?: boolean;
+    }): void;
     /** Internal intent boundary shared with asynchronous scanner/detail flows. */
     createCartIntentCommitGuard(action: OrderCartIntentCommitContext['action'], tempOrder?: OrderTempOrder | null): () => void;
     /** PC/H5 属于在线店铺；其它或缺失平台统一沿用 POS 行为。 */
@@ -481,6 +491,7 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
      * // → tempOrder.products 新增 3 行，每行 num=1，bookings 3 条
      */
     addProductToOrder(product: Partial<OrderProduct> & OrderProductIdentity, booking?: AddProductBookingInput, options?: AddProductToOrderOptions): Promise<OrderProduct[]>;
+    private addProductToOrderDraft;
     /**
      * 批量添加商品行，所有行追加完成后只触发一次促销、折扣、summary 重算与持久化。
      *
@@ -496,6 +507,7 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     }>, options?: {
         skipEditDiscountConfigRefresh?: boolean;
     }): Promise<OrderProduct[]>;
+    private addProductsToOrderDraft;
     private getFullCoveragePassDiscounts;
     private hasEntitlementPassDiscount;
     private hasGoodPassDiscount;
@@ -507,8 +519,11 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     private isRestrictedCartProductUpdate;
     private applyOrderProductUpdateToTempOrder;
     updateOrderProduct(params: UpdateOrderProductParams): Promise<OrderProduct[]>;
+    private updateOrderProductDraft;
     updateOrderProducts(paramsList: UpdateOrderProductParams[]): Promise<OrderProduct[]>;
+    private updateOrderProductsDraft;
     updateOrderProductQuantity(params: UpdateOrderProductQuantityParams): Promise<OrderProduct[]>;
+    private updateOrderProductQuantityDraft;
     updateOrderBooking(params: UpdateOrderBookingParams): any[];
     /**
      * 商品行写路径收尾：促销 → 折扣 → 清洗 → summary → 持久化。
@@ -525,12 +540,14 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
      * await order.removeProductsFromOrder([identityA, identityB]);
      */
     removeProductsFromOrder(identities: OrderProductIdentity[], options?: RemoveProductsFromOrderOptions): Promise<OrderProduct[]>;
+    private removeProductsFromOrderDraft;
     removeProductFromOrder(identity: OrderProductIdentity, options?: RemoveProductsFromOrderOptions): Promise<OrderProduct[]>;
     /**
      * 仅清空购物车行（products / bookings），不重置整单。
      * 普通整单 note 保持不变；以商品行为主体的 Sales Notes 同步删除。
      */
     clearOrderCartLines(): Promise<OrderTempOrder>;
+    private clearOrderCartLinesDraft;
     /**
      * 切换购物车结算单位时清理所有会影响新币种的订单状态，但保留当前客户。
      */