@pisell/pisellos 2.2.314 → 2.2.316

package/lib/server/modules/form/index.js

@@ -0,0 +1,73 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.FormModule = void 0;
+var _BaseModule = require("../../../modules/BaseModule");
+var _types = require("./types");
+const FORM_LIST_URL = '/shop/form/simple/list';
+
+/**
+ * 表单定义缓存。数据源负责 HTTP 与 Ably 订阅；本模块仅向 OS 消费方公开只读标题映射。
+ */
+class FormModule extends _BaseModule.BaseModule {
+  defaultName = 'form';
+  defaultVersion = '1.0.0';
+  store;
+  dataSource;
+  refreshTimer;
+  async initialize(core, options) {
+    this.core = core;
+    const initialStore = options?.store;
+    this.store = {
+      list: Array.isArray(initialStore?.list) ? initialStore.list : [],
+      map: initialStore?.map instanceof Map ? initialStore.map : new Map()
+    };
+    const FormDataSource = this.core.serverOptions?.All_DATA_SOURCES?.FormDataSource;
+    this.dataSource = FormDataSource ? new FormDataSource() : undefined;
+    if (this.dataSource) {
+      await this.dataSource.run({
+        pubsub: {
+          callback: () => this.scheduleRefresh()
+        }
+      });
+    }
+  }
+  async preload() {
+    await this.refresh();
+  }
+  getTitleMap() {
+    return this.store.list.reduce((result, item) => {
+      if (item.id !== undefined && item.id !== null && item.title) result[String(item.id)] = item.title;
+      return result;
+    }, {});
+  }
+  scheduleRefresh() {
+    if (this.refreshTimer) clearTimeout(this.refreshTimer);
+    this.refreshTimer = setTimeout(() => void this.refresh(), 300);
+  }
+  async refresh() {
+    try {
+      const response = this.dataSource ? await this.dataSource.run({
+        http: {
+          url: FORM_LIST_URL
+        }
+      }) : await this.core.getPlugin('request')?.get(FORM_LIST_URL);
+      const data = response?.data;
+      const list = Array.isArray(data) ? data : data?.list || data?.data || [];
+      if (!Array.isArray(list)) return;
+      this.store.list = list;
+      this.store.map = new Map(this.store.list.map(item => [String(item.id), item]));
+      await this.core.effects.emit(_types.FormHooks.onChanged, this.getTitleMap());
+    } catch {
+      // 接口尚未发布或临时失败时保留现有缓存，展示层会回退订单历史标题。
+    }
+  }
+  async destroy() {
+    if (this.refreshTimer) clearTimeout(this.refreshTimer);
+    this.dataSource?.destroy?.();
+  }
+}
+exports.FormModule = FormModule;
+var _default = exports.default = FormModule;

package/lib/server/modules/form/types.d.ts

@@ -0,0 +1,13 @@
+export interface FormDefinition {
+    id: string | number;
+    code?: string;
+    title?: Record<string, string> | string;
+    [key: string]: unknown;
+}
+export interface FormState {
+    list: FormDefinition[];
+    map: Map<string, FormDefinition>;
+}
+export declare const FormHooks: {
+    readonly onChanged: "form:onChanged";
+};

package/lib/server/modules/form/types.js

@@ -0,0 +1,9 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.FormHooks = void 0;
+const FormHooks = exports.FormHooks = {
+  onChanged: 'form:onChanged'
+};

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

@@ -24,4 +24,7 @@ export { FloorPlanHooks } from './floor-plan/types';
 export { ResourceModule, resourceModule } from './resource';
 export type { ResourceState, ResourceData, ResourceId, ResourceBooking, ResourcePageQuery, ResourcePageResult, QueryOptions, ScheduleEventResource, } from './resource';
 export { ResourceHooks } from './resource';
+export { FormModule } from './form';
+export type { FormDefinition, FormState } from './form/types';
+export { FormHooks } from './form/types';
 export type { RouteHandler, HttpMethod, RouteDefinition, Router, ModuleRegistryConfig, } from '../types';

package/lib/server/modules/index.js

@@ -15,6 +15,18 @@ Object.defineProperty(exports, "FloorPlanModule", {
     return _floorPlan.FloorPlanModule;
   }
 });
+Object.defineProperty(exports, "FormHooks", {
+  enumerable: true,
+  get: function () {
+    return _types6.FormHooks;
+  }
+});
+Object.defineProperty(exports, "FormModule", {
+  enumerable: true,
+  get: function () {
+    return _form.FormModule;
+  }
+});
 Object.defineProperty(exports, "MenuHooks", {
   enumerable: true,
   get: function () {
@@ -105,4 +117,6 @@ var _types4 = require("./order/types");
 var _payment = require("./payment");
 var _floorPlan = require("./floor-plan");
 var _types5 = require("./floor-plan/types");
-var _resource = require("./resource");
+var _resource = require("./resource");
+var _form = require("./form");
+var _types6 = require("./form/types");

package/lib/server/modules/order/index.d.ts

@@ -105,6 +105,8 @@ export declare class OrderModule extends BaseModule implements Module {
     getOrderByOrderId(orderId: OrderId): OrderData | undefined;
     private buildLocalPaymentOrderLogContext;
     getLocalOrderFromMemoryByLookup(lookup: OrderId): OrderData | null;
+    /** Read-only payment gate lookup; never hydrate the whole order list on a miss. */
+    getLocalOrderForPaymentReadiness(lookup: OrderId): Promise<OrderData | null>;
     getLocalOrderByLookup(lookup: OrderId, options?: {
         operationId?: string;
     }): Promise<OrderData | null>;
@@ -123,11 +125,24 @@ export declare class OrderModule extends BaseModule implements Module {
         paymentNumber: OrderId;
         operationId?: string;
         updates: Record<string, any>;
+        finalizeUnsuccessful?: boolean;
     }): Promise<{
         order: OrderData;
         payment: Record<string, any>;
         previousPayment: Record<string, any>;
     } | null>;
+    finalizeLocalEftposPayment(params: {
+        saleId: OrderId;
+        paymentNumber: OrderId;
+        result: 'failed' | 'not_started';
+        failedTransactionNumbers: string[];
+    }): Promise<{
+        order: OrderData;
+        payment: Record<string, any>;
+        previousPayment: Record<string, any>;
+    } | null>;
+    /** Only a successful full detail GET may release the persisted payment gate. */
+    completeLocalPaymentRefresh(fresh: OrderData): Promise<OrderData>;
     loadOrdersByServer(options?: {
         trigger?: string;
     }): Promise<OrderData[]>;
@@ -311,6 +326,10 @@ export declare class OrderModule extends BaseModule implements Module {
     private getIdentifiedPendingPayments;
     private shouldProtectLocalOrderFromRemoteSnapshot;
     private getUnmatchedIdentifiedPendingPayments;
+    /** 关系数组是完整快照，不能拼接或按商品子项生成 UID；扩展字段整体保留。 */
+    private applyHolderRelationsSnapshot;
+    /** 全量拉取缺少关系字段时，仍保留同一订单已有的关系快照。 */
+    private preserveOmittedHolderRelations;
     private mergeOrderRecords;
     private summarizeDuplicateOrders;
     private logDuplicateOrders;

package/lib/server/modules/order/index.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.OrderModule = void 0;
 var _lodashEs = require("lodash-es");
+var _localEftposState = require("../../../modules/Order/localEftposState");
 var _dayjs = _interopRequireDefault(require("dayjs"));
 var _BaseModule = require("../../../modules/BaseModule");
 var _orderCollectionIdentity = require("../../../modules/Order/utils/orderCollectionIdentity");
@@ -259,9 +260,9 @@ class OrderModule extends _BaseModule.BaseModule {
   mergeAuthoritativeOrderCollection(field, existing, incoming, uidRemaps = [], options = {}) {
     const kind = ORDER_COLLECTION_KIND_BY_FIELD[field];
     const existingItems = Array.isArray(existing) ? existing : [];
-    if (field === 'payments' && options.preserveIdentifiedPendingPayments) {
+    if (field === 'payments' && (options.preserveIdentifiedPendingPayments || existingItems.some(_localEftposState.isLocalFinalizedPayment))) {
       return (0, _paymentUtils.mergeOrderPaymentListsByIdentity)(existingItems, incoming, {
-        preserveUnmatchedExistingWhen: _paymentUtils.isIdentifiedPendingOrderPayment
+        preserveUnmatchedExistingWhen: payment => options.preserveIdentifiedPendingPayments === true && (0, _paymentUtils.isIdentifiedPendingOrderPayment)(payment) || (0, _localEftposState.isLocalFinalizedPayment)(payment)
       });
     }
     return incoming.map(incomingItem => {
@@ -288,6 +289,7 @@ class OrderModule extends _BaseModule.BaseModule {
     const existingRecord = existing;
     const incomingRecord = incoming;
     const uidRemaps = [];
+    this.applyHolderRelationsSnapshot(reconciled, existing, incoming);
     for (const field of ORDER_AUTHORITATIVE_COLLECTION_FIELDS) {
       if (!Array.isArray(incomingRecord[field])) continue;
       reconciled[field] = this.mergeAuthoritativeOrderCollection(field, existingRecord[field], incomingRecord[field], uidRemaps);
@@ -364,7 +366,7 @@ class OrderModule extends _BaseModule.BaseModule {
         continue;
       }
 
-      // 远端商品成员确实发生增删时必须落库，避免内存已更新但 SQLite 仍被回声窗口跳过。
+      // 远端商品成员或 Holder 关系确实变化时必须落库，避免被回声窗口跳过。
       if (forceWriteStorageKeys.has(storageKey)) {
         toWrite.push(order);
         continue;
@@ -637,6 +639,42 @@ class OrderModule extends _BaseModule.BaseModule {
     const memoryOrder = this.store.list.find(order => this.isOrderLookupMatch(order, key));
     return memoryOrder || null;
   }
+
+  /** Read-only payment gate lookup; never hydrate the whole order list on a miss. */
+  async getLocalOrderForPaymentReadiness(lookup) {
+    if (lookup === undefined || lookup === null || lookup === '') return null;
+    const memoryOrder = this.getLocalOrderFromMemoryByLookup(lookup);
+    if (memoryOrder) return memoryOrder;
+    if (typeof this.dbManager?.find !== 'function') {
+      return this.getLocalOrderByLookup(lookup);
+    }
+    const key = this.getIdKey(lookup);
+    const fields = ['order_id', 'external_sale_number', 'order_number', 'shop_order_number', 'shop_full_order_number'];
+    const candidates = [];
+    for (const column of fields) {
+      // Match getAll's storage-key ordering even when aliases collide across rows.
+      // Let query errors reach the payment gate rather than treating them as a miss.
+      const rows = await this.dbManager.find(INDEXDB_STORE_NAME, {
+        filters: [{
+          column,
+          op: '=',
+          value: key
+        }],
+        orderBy: [{
+          column: '__order_storage_key',
+          dir: 'asc'
+        }],
+        limit: 1
+      });
+      if (rows?.[0] && this.isOrderLookupMatch(rows[0], key)) candidates.push(rows[0]);
+    }
+    candidates.sort((left, right) => {
+      const leftKey = String(left.__order_storage_key ?? this.getOrderStorageKey(left));
+      const rightKey = String(right.__order_storage_key ?? this.getOrderStorageKey(right));
+      return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+    });
+    return candidates.length ? this.normalizeOrderForMemoryList(candidates[0], 'paymentReadiness.sqlite') : null;
+  }
   async getLocalOrderByLookup(lookup, options = {}) {
     const key = this.getIdKey(lookup);
     const logContext = {
@@ -753,6 +791,13 @@ class OrderModule extends _BaseModule.BaseModule {
       return null;
     }
     const previousPayment = (0, _lodashEs.cloneDeep)(found.payment);
+    if (params.finalizeUnsuccessful && (found.payment.status === 'paid' || found.payment.metadata?.transactions?.some(transaction => transaction.status === 'success') || (0, _localEftposState.isLocalFinalizedPayment)(found.payment))) {
+      return {
+        order: found.order,
+        payment: found.payment,
+        previousPayment
+      };
+    }
     const nextPayment = (0, _paymentUtils.mergeOrderPaymentRecord)(found.payment, {
       ...params.updates,
       updated_at: params.updates.updated_at || (0, _dayjs.default)().format('YYYY-MM-DD HH:mm:ss')
@@ -762,6 +807,13 @@ class OrderModule extends _BaseModule.BaseModule {
       payments: (found.order.payments || []).map((payment, index) => index === found.paymentIndex ? nextPayment : payment),
       updated_at: (0, _dayjs.default)().format('YYYY-MM-DD HH:mm:ss')
     };
+    if (params.finalizeUnsuccessful && this.hasRealOrderId(found.order) && Number(found.order.need_sync || 0) === 0 && !(nextOrder.payments || []).some(_paymentUtils.isPendingOrderPayment)) {
+      nextOrder.is_draft_order = 0;
+      nextOrder.metadata = {
+        ...nextOrder.metadata,
+        [_localEftposState.LOCAL_EFTPOS_REFRESH_REQUIRED]: true
+      };
+    }
     const paymentContext = {
       ...logContext,
       matched_by: found.matchedBy,
@@ -813,6 +865,60 @@ class OrderModule extends _BaseModule.BaseModule {
       previousPayment
     };
   }
+  async finalizeLocalEftposPayment(params) {
+    const found = await this.getLocalPayment(params);
+    if (!found) throw new Error('未找到本地支付记录');
+    const transactions = found.payment.metadata?.transactions || [];
+    if (transactions.some(transaction => transaction.status !== 'fail' && transaction.status !== 'success' && !params.failedTransactionNumbers.includes(String(transaction.number)))) {
+      throw new Error('仍有结果未知的交易，保留待确认支付');
+    }
+    if (params.result === 'not_started' && transactions.length > 0 && !(0, _localEftposState.isLocalFinalizedPayment)(found.payment) && found.payment.status !== 'paid') {
+      throw new Error('支付已有交易记录，不能按未发起交易结束');
+    }
+    return this.updateLocalPayment({
+      ...params,
+      finalizeUnsuccessful: true,
+      updates: {
+        status: 'voided',
+        metadata: {
+          [_localEftposState.LOCAL_EFTPOS_FINALIZED]: true,
+          transactions: params.failedTransactionNumbers.map(number => ({
+            number,
+            status: 'fail'
+          }))
+        }
+      }
+    });
+  }
+
+  /** Only a successful full detail GET may release the persisted payment gate. */
+  async completeLocalPaymentRefresh(fresh) {
+    const existing = await this.getLocalOrderByLookup(fresh.order_id);
+    if (!existing || !(0, _localEftposState.requiresLocalPaymentRefresh)(existing)) {
+      await this.upsertOrdersFromRemote([fresh]);
+      return (await this.getLocalOrderByLookup(fresh.order_id)) || fresh;
+    }
+    if (this.isPendingSyncOrder(existing) || this.isDraftOrder(existing) || (existing.payments || []).some(_paymentUtils.isPendingOrderPayment)) {
+      throw new Error('订单仍有未结束支付或待同步改动，暂不能刷新');
+    }
+    if (!Array.isArray(fresh.products) || !fresh.summary) {
+      throw new Error('远端订单详情不完整，请重新刷新');
+    }
+    const nextOrder = this.mergeOrderRecords(existing, this.normalizeRemoteSyncedOrder(fresh));
+    nextOrder.metadata = {
+      ...nextOrder.metadata
+    };
+    delete nextOrder.metadata[_localEftposState.LOCAL_EFTPOS_REFRESH_REQUIRED];
+    // Do not publish/clear the gate in memory until SQLite has accepted the full snapshot.
+    await this.updateOrderInSQLite(nextOrder, 'completeLocalPaymentRefresh', {
+      throwOnError: true
+    });
+    const index = this.findOrderIndexByIdentity(this.store.list, existing);
+    this.store.list = index < 0 ? [...this.store.list, nextOrder] : this.store.list.map((order, i) => i === index ? nextOrder : order);
+    this.syncOrdersMap();
+    await this.emitOrdersChanged([nextOrder], 'completeLocalPaymentRefresh');
+    return nextOrder;
+  }
   async loadOrdersByServer(options = {}) {
     let orderList = [];
     let hasFetchedRemoteSnapshot = false;
@@ -1234,6 +1340,7 @@ class OrderModule extends _BaseModule.BaseModule {
       if (matchIndex >= 0) {
         const existingOrder = updatedList[matchIndex];
         const reconciledDraftOrder = this.preserveExistingBusinessCodeForDraft(existingOrder, draftOrder);
+        this.applyHolderRelationsSnapshot(reconciledDraftOrder, existingOrder, draftOrder);
         const mergedOrder = this.mergeOrderRecords(existingOrder, reconciledDraftOrder);
         const nextOrder = {
           ...mergedOrder,
@@ -1512,7 +1619,10 @@ class OrderModule extends _BaseModule.BaseModule {
       const hasSingleId = routeInfo.hasSingleId;
       const normalizedBody = this.normalizeOrderSyncPayload(msg.body || msg.data);
       if (routeInfo.route === 'bodyUpsert' && normalizedBody) {
-        upsertOrders.set(this.getIdKey(normalizedBody.order_id), normalizedBody);
+        const orderKey = this.getIdKey(normalizedBody.order_id);
+        const previousBody = upsertOrders.get(orderKey);
+        if (previousBody) this.applyHolderRelationsSnapshot(normalizedBody, previousBody, normalizedBody);
+        upsertOrders.set(orderKey, normalizedBody);
         return;
       }
       if (hasBatchIds) refreshIds.push(...routeInfo.batchIds);else if (routeInfo.route === 'httpRefresh.singleId' && singleId !== null) refreshIds.push(singleId);else if (routeInfo.route === 'httpRefresh.relationIds') refreshIds.push(...routeInfo.batchIds);
@@ -1705,6 +1815,9 @@ class OrderModule extends _BaseModule.BaseModule {
           const mergedStorageKey = this.getOrderStorageKey(mergedOrder);
           if (mergedStorageKey) forceWriteStorageKeys.add(mergedStorageKey);
         }
+        if (nextStorageKey && !(0, _lodashEs.isEqual)(existingOrder.holder_relations, mergedOrder.holder_relations)) {
+          forceWriteStorageKeys.add(nextStorageKey);
+        }
         // 合并后身份字段可能新增（如挂单拿到 order_id），同步登记到索引，
         // 供同批后续 fresh 命中同一槽位，避免重复插入
         this.registerOrderIdentityKeys(identityKeyToIndex, mergedOrder, adjustedMatchIndex);
@@ -1997,7 +2110,7 @@ class OrderModule extends _BaseModule.BaseModule {
     return payments.filter(payment => (0, _paymentUtils.isIdentifiedPendingOrderPayment)(payment));
   }
   shouldProtectLocalOrderFromRemoteSnapshot(order) {
-    return this.isPendingSyncOrder(order) || this.isDraftOrder(order) || this.getIdentifiedPendingPayments(order).length > 0;
+    return this.isPendingSyncOrder(order) || this.isDraftOrder(order) || this.getIdentifiedPendingPayments(order).length > 0 || (0, _localEftposState.requiresLocalPaymentRefresh)(order) || (order.payments || []).some(_localEftposState.isLocalFinalizedPayment);
   }
   getUnmatchedIdentifiedPendingPayments(existing, incoming) {
     const existingPayments = Array.isArray(existing) ? existing : [];
@@ -2005,6 +2118,38 @@ class OrderModule extends _BaseModule.BaseModule {
     const incomingIdentityKeys = new Set(incomingPayments.flatMap(payment => (0, _paymentUtils.getOrderPaymentIdentityKeys)(payment)));
     return existingPayments.filter(payment => (0, _paymentUtils.isIdentifiedPendingOrderPayment)(payment) && !(0, _paymentUtils.getOrderPaymentIdentityKeys)(payment).some(key => incomingIdentityKeys.has(key)));
   }
+
+  /** 关系数组是完整快照，不能拼接或按商品子项生成 UID；扩展字段整体保留。 */
+  applyHolderRelationsSnapshot(target, existing, incoming) {
+    if (Array.isArray(incoming.holder_relations)) {
+      target.holder_relations = (0, _lodashEs.cloneDeep)(incoming.holder_relations);
+    } else if (Array.isArray(existing.holder_relations)) {
+      target.holder_relations = (0, _lodashEs.cloneDeep)(existing.holder_relations);
+    } else {
+      delete target.holder_relations;
+    }
+  }
+
+  /** 全量拉取缺少关系字段时，仍保留同一订单已有的关系快照。 */
+  preserveOmittedHolderRelations(incomingOrders, existingOrders) {
+    const existingByIdentity = new Map();
+    for (const order of existingOrders) {
+      if (!Array.isArray(order.holder_relations)) continue;
+      for (const key of this.getOrderIdentityMatchKeys(order)) {
+        existingByIdentity.set(key, order);
+      }
+    }
+    return incomingOrders.map(order => {
+      if (Array.isArray(order.holder_relations)) return order;
+      const existingOrder = this.getOrderIdentityMatchKeys(order).map(key => existingByIdentity.get(key)).find(Boolean);
+      if (!existingOrder) return order;
+      const nextOrder = {
+        ...order
+      };
+      this.applyHolderRelationsSnapshot(nextOrder, existingOrder, order);
+      return nextOrder;
+    });
+  }
   mergeOrderRecords(existing, incoming) {
     const preferred = this.pickPreferredOrder(existing, incoming);
     const secondary = preferred === existing ? incoming : existing;
@@ -2019,6 +2164,12 @@ class OrderModule extends _BaseModule.BaseModule {
     const secondaryRecord = secondary;
     const existingRecord = existing;
     const incomingRecord = incoming;
+    if ((0, _localEftposState.requiresLocalPaymentRefresh)(existing)) {
+      mergedRecord.metadata = {
+        ...mergedRecord.metadata,
+        [_localEftposState.LOCAL_EFTPOS_REFRESH_REQUIRED]: true
+      };
+    }
     const childUidRemaps = [];
     for (const field of fieldsToPreserve) {
       if (!this.isBlankIdentityValue(preferredRecord[field])) {
@@ -2041,6 +2192,7 @@ class OrderModule extends _BaseModule.BaseModule {
     if (Object.prototype.hasOwnProperty.call(incomingRecord, 'order_meta_list')) {
       mergedRecord.order_meta_list = (0, _lodashEs.cloneDeep)(incomingRecord.order_meta_list);
     }
+    this.applyHolderRelationsSnapshot(merged, existing, incoming);
 
     // 子项数组遵循完整快照语义：incoming 自有且为数组（包括 []）时权威替换；
     // 字段缺席或不是数组时视为稀疏 patch，继续保留 existing。
@@ -2482,7 +2634,7 @@ class OrderModule extends _BaseModule.BaseModule {
   async replaceOrdersSnapshotInSQLite(orderList, source, protectedOrdersBeforeRemoteFetch = []) {
     if (!this.dbManager) {
       return {
-        orders: this.compactOrderListByIdentity(orderList.map(order => this.normalizeRemoteSyncedOrder(order)), `${source}.snapshotNoDb`).list,
+        orders: this.compactOrderListByIdentity(this.preserveOmittedHolderRelations(orderList, this.store.list).map(order => this.normalizeRemoteSyncedOrder(order)), `${source}.snapshotNoDb`).list,
         persisted: false
       };
     }
@@ -2492,6 +2644,7 @@ class OrderModule extends _BaseModule.BaseModule {
     try {
       await this.runInOrderSQLiteSaveQueue(async () => {
         const existingOrders = typeof this.dbManager.getAll === 'function' ? await this.dbManager.getAll(INDEXDB_STORE_NAME) : [];
+        const remoteSnapshotWithHolderRelations = this.preserveOmittedHolderRelations(remoteSnapshot, [...protectedOrdersBeforeRemoteFetch, ...(existingOrders || [])]);
         const protectedLocalOrders = protectedOrdersBeforeRemoteFetch.map(order => this.normalizeOrderCollectionsForIngress(order, `${source}.protectedBeforeRemoteFetch`)).filter(order => this.shouldProtectLocalOrderFromRemoteSnapshot(order));
         for (const rawCurrentOrder of existingOrders || []) {
           const currentOrder = this.normalizeOrderCollectionsForIngress(rawCurrentOrder, `${source}.currentSQLite`);
@@ -2507,7 +2660,7 @@ class OrderModule extends _BaseModule.BaseModule {
           }
           if (currentNeedsProtection) protectedLocalOrders.push(currentOrder);
         }
-        const orderListSnapshot = this.mergeRemoteSnapshotWithPendingOrders(remoteSnapshot, protectedLocalOrders);
+        const orderListSnapshot = this.mergeRemoteSnapshotWithPendingOrders(remoteSnapshotWithHolderRelations, protectedLocalOrders);
         mergedSnapshot = this.compactOrderListByIdentity(orderListSnapshot, `${source}.sqliteSnapshot`).list;
         this.logInfo('replaceOrdersSnapshotInSQLite-开始', {
           source,

package/lib/server/modules/order/types.d.ts

@@ -1,4 +1,5 @@
 import type { ScheduleEventResource } from '../resource/types';
+import type { OrderHolderRelation } from '../../../modules/Order/types';
 /**
  * Order 模块主键类型（对齐标准 Sales 协议的 order_id）
  */
@@ -448,6 +449,8 @@ export interface OrderData {
     contacts_info?: unknown[];
     /** 订单级主体参数 */
     holder?: Record<string, unknown> | null;
+    /** 非预约商品 Holder 关系完整快照；缺席表示本次回包未提供 */
+    holder_relations?: OrderHolderRelation[];
     /** 订单前端扩展快照 */
     order_meta_list?: {
         point_cards_snapshot?: Array<{
@@ -463,6 +466,7 @@ export interface OrderData {
             id: number | string;
             tag: 'virtual_currency';
             product_id?: number | string;
+            code?: string;
             product_name: string;
             par_value: string;
             used_par_value: string;

package/lib/server/modules/products/index.d.ts

@@ -3,6 +3,7 @@ import { BaseModule } from '../../../modules/BaseModule';
 import { ProductData } from '../../../modules/Product/types';
 import type { RouteDefinition } from '../../types';
 import { ProductIdScope, type ProductSnapshot, ProductFormatter, ProductFormatterContext } from './types';
+import type { CommittedProducts, ReplicatedProducts } from './types';
 /**
  * Products 模块 - 用于获取和管理完整的商品详细数据
  * 相比 ProductList 模块，Products 会获取所有详细信息并缓存
@@ -40,6 +41,26 @@ export declare class ProductsModule extends BaseModule implements Module {
     private productIndexDBSaveQueue;
     /** 最近一次智能定价评估提取的 schedule 变价时间点（HH:mm），供 Server 订阅定时刷新使用 */
     private lastScheduleTimePoints;
+    private committedProductState?;
+    private productReplicationSourceGeneration;
+    private productPersistenceFailed;
+    private runtimeSyncMode;
+    private runtimeSyncGeneration;
+    private requestReplicaRefresh?;
+    private replicaApplyQueue;
+    private productSyncQueue;
+    private replicaPriceDirtyIds;
+    /** Installed after initial preload; initial cache/network loading stays unchanged. */
+    setRuntimeSyncMode(mode: 'normal' | 'memoryReplica', requestRefresh?: (trigger: string) => Promise<void>): Promise<void>;
+    isMemoryReplica(): boolean;
+    /** Read persisted data once on the main screen to establish a committed baseline. */
+    enableProductReplicationSource(): Promise<void>;
+    /** Release the extra catalog without changing the normal product store or persistence. */
+    disableProductReplicationSource(): void;
+    getCommittedProductSnapshot(): CommittedProducts | null;
+    private recordProductCommit;
+    applyReplicatedProducts(change: ReplicatedProducts): Promise<void>;
+    private refreshFromReplica;
     constructor(name?: string, version?: string);
     initialize(core: PisellCore, options: any): Promise<void>;
     /**
@@ -230,7 +251,10 @@ export declare class ProductsModule extends BaseModule implements Module {
      * 根据 ID 列表删除商品（用于 pubsub 同步删除场景）
      * 同时更新 store.list、store.map、IndexDB 和价格缓存
      */
-    removeProductsByIds(ids: number[]): Promise<void>;
+    removeProductsByIds(ids: number[], options?: {
+        skipIndexDB?: boolean;
+        skipEmit?: boolean;
+    }): Promise<void>;
     /**
      * 重新从服务器加载全量商品列表并更新本地 store
      * 用于 pubsub 同步 create / update / batch_update 场景
@@ -261,13 +285,8 @@ export declare class ProductsModule extends BaseModule implements Module {
      * await this.replaceProductsSnapshotInIndexDB(list, 'loadProductsByServer')
      */
     private replaceProductsSnapshotInIndexDB;
-    /**
-     * 增量 upsert 商品到 IndexDB，不清空表；用于 pubsub 批次合并后的变更商品。
-     *
-     * @example
-     * await this.patchProductsInIndexDB(changedProducts, 'pubsub.processProductSyncMessages', mergeActions)
-     */
     private patchProductsInIndexDB;
+    private persistProductDelta;
     /**
      * 同步更新商品 Map 缓存
      * 将 list 中的商品同步到 map，以 id 为 key
@@ -309,6 +328,7 @@ export declare class ProductsModule extends BaseModule implements Module {
      * Server 层监听该事件后对变更商品增量执行 prepareProductsWithPrice 并更新缓存
      */
     private processProductSyncMessages;
+    private processProductSyncBatch;
     /**
      * 通过 SSE 按 ids 增量拉取商品数据
      * 请求 GET /shop/core/stream?type=product&ids={ids}
@@ -342,6 +362,7 @@ export declare class ProductsModule extends BaseModule implements Module {
      * 销毁同步资源（取消 pubsub 订阅、清除定时器）
      */
     destroyProductSync(): void;
+    destroy(): void;
     /**
      * 获取模块的路由定义
      * Products 模块暂不提供路由，由 Server 层统一处理