@pisell/pisellos 0.0.568 → 0.10.1

package/dist/server/index.d.ts

@@ -3,10 +3,26 @@ import { MenuModule } from './modules/menu';
 import { QuotationModule } from './modules/quotation';
 import { ScheduleModuleEx } from './modules/schedule';
 import { ResourceModule } from './modules/resource';
+import { FloorPlanModule } from './modules/floor-plan';
+import { PaymentServerModule } from './modules/payment';
 import { PisellCore, ServerModuleConfig, InitializeServerOptions } from '../types';
 import type { RouteHandler, HttpMethod, RouteDefinition, Router, ModuleRegistryConfig, RequestSetting } from './types';
 import { OrderModule } from './modules/order';
 export type { RouteHandler, HttpMethod, RouteDefinition, Router, ModuleRegistryConfig, };
+/** Server 运行时诊断快照，用于排查订阅者是否持续增长。 */
+export interface ServerDiagnosticsSnapshot {
+    subscribers: {
+        productQuerySubscribers: number;
+        orderQuerySubscribers: number;
+        bookingQuerySubscribers: number;
+        bookingRemoteQuerySubscribers: number;
+        salesSearchSubscribers: number;
+        floorPlanQuerySubscribers: number;
+    };
+    caches: {
+        bookingRemoteCache: number;
+    };
+}
 /**
  * Server 类
  * 用于注册和管理服务端模块
@@ -21,17 +37,49 @@ declare class Server {
     schedule?: ScheduleModuleEx;
     resource?: ResourceModule;
     order?: OrderModule;
+    floor_plan?: FloorPlanModule;
+    payment?: PaymentServerModule;
+    private paymentRouteModule?;
+    private paymentRouteModuleInFlight?;
+    private quotationAvailableCache;
+    private quotationAvailableInFlight;
+    /** GET 前缀路由（最长前缀优先匹配） */
+    private prefixRouterGet;
     router: Router;
     private productQuerySubscribers;
+    /** subscriberId → 智能定价变价时间点定时器句柄（与 subscriber 分离存储，便于 clear） */
+    private productQueryScheduleTimers;
+    /** 餐牌筛选为空时才触发的菜单/日程缓存自愈，避免每次商品查询都请求远端。 */
+    private menuScheduleRefreshInFlight;
+    private lastMenuScheduleRefreshAt;
+    private readonly MENU_SCHEDULE_REFRESH_COOLDOWN_MS;
     private orderQuerySubscribers;
     private bookingQuerySubscribers;
+    private bookingRemoteQuerySubscribers;
+    private bookingRemoteCache;
+    private readonly BOOKING_REMOTE_CACHE_TTL_MS;
+    private readonly BOOKING_REMOTE_CACHE_MAX_ENTRIES;
+    private salesSearchSubscribers;
+    private deviceTaskActionsRegistered;
+    private floorPlanQuerySubscribers;
     private moduleRegistry;
     constructor(core: PisellCore);
+    /**
+     * 获取 Server 内部订阅者和缓存数量快照。
+     *
+     * @example
+     * const snapshot = pisellos.server?.getDiagnosticsSnapshot?.();
+     */
+    getDiagnosticsSnapshot(): ServerDiagnosticsSnapshot;
     /**
      * 注册路由
      * @param routes 路由定义数组
      */
     private registerRoutes;
+    /**
+     * 注册前缀路由（仅 GET）。匹配规则：path === prefix 或 path 以 prefix + '/' 开头；最长前缀优先。
+     */
+    private registerPrefixRoutes;
     /**
      * 注册单个模块并自动注册其路由
      * @param module 模块实例
@@ -72,6 +120,15 @@ declare class Server {
         config: ModuleRegistryConfig;
         shouldPreload: boolean;
     }[]>;
+    private registerDeviceTaskActions;
+    private handleSyncSalesTask;
+    private runCheckoutSync;
+    private omitCheckoutSyncMode;
+    private persistSyncedCheckoutOrder;
+    /**
+     * 将普通层 QuotationModule 的报价单计算能力桥接到 Server Products 模块。
+     */
+    private setupProductsQuotationPriceBridge;
     /**
      * 获取 Products 模块实例
      */
@@ -98,6 +155,12 @@ declare class Server {
      * 不影响当前界面展示，适用于切回前台、定时刷新等场景
      */
     refreshProductsInBackground(): Promise<void>;
+    /**
+     * 后台静默刷新订单数据
+     * 重新拉取全量 SSE 接口，更新本地数据后触发 onOrdersSyncCompleted
+     * 不影响当前界面展示，适用于切回前台、定时刷新等场景
+     */
+    refreshOrdersInBackground(): Promise<void>;
     /**
      * 清空所有server模块的IndexedDB缓存
      * @returns Promise<void>
@@ -144,15 +207,77 @@ declare class Server {
      * @private
      */
     private registerServerRoutes;
+    private getPaymentRouteModule;
+    private handlePaymentMethods;
+    private handleQuotationAvailable;
+    private fetchQuotationAvailableFromAPI;
+    private isSuccessfulRemoteResponse;
     /**
      * 根据 subscriberId 移除商品查询订阅者
      */
     removeProductQuerySubscriber(subscriberId?: string): void;
+    /**
+     * 构建商品 query 响应 data 段，附带智能定价 schedule_time_points 元数据。
+     */
+    private buildProductQueryResultPayload;
+    /**
+     * 是否启用商品 query 订阅的 schedule 时间点定时重算。
+     * strategy_context.enable_schedule_reload === false 时关闭。
+     */
+    private shouldScheduleProductQueryReload;
+    /**
+     * 清除指定 subscriber 的全部 schedule 定时器，防止重复 query 或 unsubscribe 后泄漏。
+     */
+    private clearSubscriberScheduleTimers;
+    /**
+     * 从 productQueryScheduleTimers 移除已触发的 timer 引用。
+     */
+    private removeScheduleTimerRef;
+    /**
+     * 计算 schedule 变价时间点到当前时刻的延迟（ms）。已过期返回 -1。
+     */
+    private computeScheduleTimePointDelayMs;
+    /**
+     * 定时重算前刷新 subscriber schedule 上下文：使用执行瞬间时间，禁止沿用首次 query 的 schedule_datetime。
+     */
+    private refreshSubscriberScheduleAtExecution;
+    /**
+     * 为 subscriber 注册智能定价 scheduleTimePoints 定时重算。
+     * 必须先 clearSubscriberScheduleTimers，再调用本方法。
+     */
+    private scheduleSubscriberTimePointReloads;
+    /**
+     * schedule 变价时间点定时器触发：刷新 schedule_datetime 后重算并 callback。
+     */
+    private onScheduleTimePointTimerFire;
+    /**
+     * 对单个商品 query 订阅者重算并推送（定时路径；不新建 schedule timer）。
+     */
+    private recomputeAndNotifySubscriber;
+    /**
+     * query 完成后为 subscriber 同步 schedule 定时器（先 clear 再 schedule）。
+     */
+    private syncProductQueryScheduleTimers;
     /**
      * 处理商品查询请求
      * 存储订阅者信息，便于数据变更时推送最新结果
      */
     private handleProductQuery;
+    /**
+     * ProductList callers such as standalone retail pages do not always have a selected schedule.
+     * In that case query against the current local time so menu availability can still be evaluated.
+     */
+    private resolveProductQueryScheduleContext;
+    /**
+     * OpenData 的关联餐牌可能已更新，而 server_menu/server_schedule 仍命中本地持久化缓存。
+     * 仅在当前筛选没有任何生效餐牌时刷新一次，并由调用方重新计算筛选结果。
+     */
+    private refreshMenuScheduleCacheAfterEmptyResult;
+    /**
+     * 按商品 id 查询单条（GET /shop/product/query/:productId）
+     * schedule_date 必填：query 或 data；schedule_datetime 可选。不走订阅。
+     */
+    private handleProductQueryById;
     /**
      * 取消商品查询订阅（HTTP 路由入口）
      */
@@ -167,11 +292,153 @@ declare class Server {
      */
     private handleUnsubscribeOrderQuery;
     /**
-     * 判断预约查询的 sales_time_between 起始日期是否为今天
+     * 处理 sales 单模块搜索：请求透传后端，仅在 OS 层维护已返回订单号集合。
+     *
+     * @example
+     * await this.handleSalesSearchModule({ url: '/shop/es/search/sales', method: 'post', data: { keyword: 'A' } })
      */
-    private isBookingQueryForToday;
+    private handleSalesSearchModule;
     /**
-     * 非今天的预约查询：通过真实 API 获取数据，再做 flattenOrdersToBookings 拆分
+     * 处理 sales 聚合搜索：请求透传后端，仅订阅 sales 分组的已返回订单号。
+     *
+     * @example
+     * await this.handleSalesSearchAggregate({ url: '/shop/es/search', method: 'post', data: { modules: [] } })
+     */
+    private handleSalesSearchAggregate;
+    /**
+     * 取消 sales 搜索订阅。
+     *
+     * @example
+     * await this.handleUnsubscribeSalesSearch({ data: { subscriberId: 'global-search-order' } } as any)
+     */
+    private handleUnsubscribeSalesSearch;
+    /**
+     * 执行 sales 搜索并登记可见订单号。
+     * 搜索参数完全透传后端，OS 不做过滤、筛选、排序。
+     *
+     * @example
+     * const result = await this.handleSalesSearchRequest('single', '/shop/es/search/sales', { keyword: '1001' }, {})
+     */
+    private handleSalesSearchRequest;
+    /**
+     * 透传调用后端 sales 搜索接口。
+     *
+     * @example
+     * const res = await this.fetchSalesSearchFromAPI('/shop/es/search/sales', { keyword: '1001' })
+     */
+    private fetchSalesSearchFromAPI;
+    /**
+     * 构建搜索订阅签名；页码变化不重置，可继续累计 visibleOrderIds。
+     *
+     * @example
+     * const signature = this.buildSalesSearchSignature('single', { keyword: 'A', page: 2 })
+     */
+    private buildSalesSearchSignature;
+    /**
+     * 移除页码参数，保留 page size、keyword、filters、sort 等查询语义参数。
+     *
+     * @example
+     * this.stripSalesSearchPageParams({ page: 2, per_page: 20, keyword: 'A' })
+     */
+    private stripSalesSearchPageParams;
+    /**
+     * 提取响应 data，兼容 OS 包装结构与后端直接响应结构。
+     *
+     * @example
+     * const data = this.extractSalesSearchResponseData(result)
+     */
+    private extractSalesSearchResponseData;
+    /**
+     * 从搜索响应中提取 sales 命中的订单号。
+     *
+     * @example
+     * const ids = this.extractSalesSearchOrderIds('single', result)
+     */
+    private extractSalesSearchOrderIds;
+    /**
+     * 查找聚合搜索响应中的 sales 分组。
+     *
+     * @example
+     * const group = this.findSalesSearchAggregateGroup({ results: [{ module: 'sales' }] })
+     */
+    private findSalesSearchAggregateGroup;
+    /**
+     * 从订单或搜索命中项中取订单号。
+     *
+     * @example
+     * const id = this.getSalesSearchOrderId({ order_id: 1001 })
+     */
+    private getSalesSearchOrderId;
+    /**
+     * 从查询值中提取 YYYY-MM-DD 日期串。
+     *
+     * @example
+     * this.extractQueryDate('2026-04-15 09:58:00') // => '2026-04-15'
+     */
+    private extractQueryDate;
+    /**
+     * 判断时间范围是否完整落在今天。
+     *
+     * @example
+     * this.isRangeFullyToday('2026-04-15', '2026-04-15') // => true
+     */
+    private isRangeFullyToday;
+    /**
+     * 判断时间范围是否「开始和结束都不是今天」。
+     *
+     * @example
+     * this.isRangeBothNotToday('2026-04-13', '2026-04-14') // => true
+     */
+    private isRangeBothNotToday;
+    /**
+     * 订单查询是否走本地：
+     * - 仅当 start_time 与 end_time 都是今天时，走本地；
+     * - 任意一端不是今天时，走云端，确保跨天查询能拉取非本地窗口数据。
+     */
+    private shouldUseLocalOrderQuery;
+    /**
+     * 预约查询是否走本地：
+     * - 当 sales_time_between 的开始和结束都不是今天时，走远端；
+     * - 其余情况走本地。
+     */
+    private shouldUseLocalBookingQuery;
+    /**
+     * 日历 SSE 精简 with：由调用方显式声明 compact_fields 决定
+     * - compact_fields === true → 精简字段（周/月视图）
+     * - 其余（false / 未传）→ ['all']（日视图/表格/平面图合并）
+     */
+    private resolveBookingSalesWith;
+    /**
+     * 日历 SSE 精简 select：渲染 + filterBookingsFromOrders 所需的主表字段
+     * business_code / payment_status 不直接用于渲染，但 matchOrder 过滤依赖
+     */
+    private resolveBookingSalesSelect;
+    /**
+     * 日历（compact_fields）场景下要直接在 SSE 层排除的订单类型：
+     * 这些类型不会出现在日历上，拉取它们只会浪费带宽并增加前端过滤成本。
+     */
+    private readonly BOOKING_SALES_COMPACT_EXCLUDE_TYPES;
+    private normalizeBookingRemoteQueryPayload;
+    /**
+     * 远端预约查询内存缓存开关：默认 false，仅显式 true 才启用。
+     */
+    private isBookingRemoteMemoryCacheEnabled;
+    private stableSerialize;
+    private buildBookingRemoteCacheKey;
+    private parseBookingSalesRangeMeta;
+    private readBookingRemoteCache;
+    private writeBookingRemoteCache;
+    private toOrderIdKey;
+    private markBookingRemoteCacheAllStale;
+    private buildBookingResponse;
+    private notifyBookingRemoteSubscribersByCacheKey;
+    private syncBookingRemoteCacheFromOrderChanges;
+    /**
+     * 非本地窗口的订单查询：走真实 API。
+     */
+    private fetchOrderListFromAPI;
+    /**
+     * 非今天的预约查询：通过 SSE 流式拉取订单，再做本地 booking 筛选展开
      */
     private fetchBookingListFromAPI;
     /**
@@ -184,6 +451,140 @@ declare class Server {
      * 转发到资源模块去
      */
     private handleResourceList;
+    /**
+     * 代理刷新 / 合并订单到本地（单笔 / 批量二合一）：
+     * - 入参（GET query 或 data 任一）：
+     *   - `order_id`：单笔模式，原有行为
+     *   - `order_ids`：批量模式，逗号分隔的 id 列表（如 `?order_ids=1,2,3`），数组也兼容
+     *   - 同时存在时优先批量
+     * - 单笔流程：后端 /order/sales/{id}?with[]=all → 本地有则覆盖、无则 merge → 落 SQLite → emit onOrdersChanged
+     * - 批量流程：并发拉取每笔详情 → 一次性 `upsertOrdersFromRemote` 合并写入 → 仅 emit 一次 onOrdersChanged，
+     *   单笔失败不影响其他成功项；返回 { overwritten, inserted, failed }
+     * - 监听级联：onOrdersChanged 触发订单 / 预约 / bookingRemoteCache 三路订阅者推送
+     *
+     * @example 单笔：GET /update/localOrder?order_id=96971
+     * @example 批量：GET /update/localOrder?order_ids=96971,96972,96973
+     */
+    private handleUpdateLocalOrder;
+    private handleOrderSalesCheckout;
+    private handleOrderCheckout;
+    private getDeviceTaskPlugin;
+    private getIdGeneratorPlugin;
+    private getAppData;
+    private getSmallTicketShopInfo;
+    private taskOk;
+    private taskFail;
+    private taskTimeout;
+    private getShortNumberOrDeviceId;
+    private buildCheckoutTaskIdempotencyKey;
+    private isBlankCheckoutValue;
+    private isLocalCheckoutOrderId;
+    private normalizeCheckoutSubmitData;
+    private ensureCheckoutOrderNumbers;
+    private dispatchCheckoutSyncTask;
+    private dispatchPrintOtherReceiptTask;
+    private buildPrintOtherReceiptIdempotencyKey;
+    private getPrintOrderIdentity;
+    private dispatchLocalReceiptPrint;
+    private shouldLookupLocalPrintOrder;
+    private getLocalPrintOrderLookup;
+    private handleLocalPrintOrder;
+    private handleMachinecodeBatchMeta;
+    private resolveMachinecodeBatchMetadataLookup;
+    private syncMachinecodeRedeemStatusToLocalOrder;
+    private handleOrderCheckoutSubmit;
+    private handleSyncCheckoutSubmit;
+    private handlePendingSyncCheckoutOrder;
+    private buildPendingSyncCheckoutOrder;
+    private shouldBuildSmallTicketData;
+    private shouldPrintSyncedOrder;
+    private hasPaymentStatus;
+    private isSalesOrderFullyPaid;
+    private sumPaidOrderPayments;
+    private toAmountNumber;
+    private buildSmallTicketProductMap;
+    private collectSalesDetailProductIds;
+    private buildSalesDetailProductSnapshotMap;
+    private withProductCatalogSnapshots;
+    private withBundleCatalogSnapshots;
+    private withSalesDetailProductSnapshots;
+    private withPendingSyncProductTitles;
+    private buildProductTitleSnapshot;
+    private getProductTitleSnapshotCurrentLocale;
+    private normalizeProductTitleSnapshotLocale;
+    private resolveProductTitleValue;
+    private canAssignStringProductTitleToLocale;
+    private hasCjkText;
+    private resolveFirstProductTitleValue;
+    private getPaymentCodeKey;
+    private isBlankPaymentName;
+    private shouldLookupPaymentMethodNameByCode;
+    private enrichPaymentNamesByCode;
+    private withLocalSmallTicketData;
+    private handleOrderSalesDetail;
+    /**
+     * 解析 order_ids 入参，兼容 url query / data 字段、字符串(csv) / 数组两种形态。
+     * 自动 trim、去空、按字符串去重，输出归一化后的字符串数组。
+     *
+     * @example
+     * // url: /update/localOrder?order_ids=1,2,2,, → ['1','2']
+     * this.parseOrderIdsParam(url, undefined)
+     *
+     * @example
+     * // data: { order_ids: [1, '2', null] } → ['1','2']
+     * this.parseOrderIdsParam('', { order_ids: [1, '2', null] })
+     */
+    private parseOrderIdsParam;
+    /**
+     * 批量代理刷新 / 合并订单到本地：并发拉详情 → 单次合并 → 单次 emit。
+     * - 单笔失败不影响其他成功项
+     * - 没有任何成功项时不触发 emit / 落库
+     *
+     * @example
+     * await this.handleUpdateLocalOrdersBatch(['96971', '96972'])
+     */
+    private handleUpdateLocalOrdersBatch;
+    /**
+     * 从 url 中解析指定 query 参数，兼容相对路径与绝对路径
+     */
+    private extractQueryParam;
+    private extractOrderSalesDetailLookup;
+    private shouldForceRemoteSalesDetail;
+    private buildOrderSalesDetailBackendPath;
+    private extractOrderDataFromCheckoutResponse;
+    private getCheckoutExternalSaleNumber;
+    private buildCheckoutSyncSuccessPatch;
+    private buildSyncedOrderForPrint;
+    private isMergeableCheckoutOrder;
+    private normalizeCheckoutResponse;
+    private withSyncedOrderIdInCheckoutResponse;
+    private isCheckoutResponseRejected;
+    private getUnknownErrorMessage;
+    private normalizeUnknownError;
+    private safeJsonClone;
+    private extractBackendErrorResponse;
+    private isExplicitBackendErrorResponse;
+    /**
+     * 从 url 或路由 path 解析 pathname（不含 query，去掉末尾 /）
+     */
+    private parseRequestPath;
+    /**
+     * 解析平面图 GET 路径为查询上下文
+     */
+    private resolveFloorPlanQueryContext;
+    /**
+     * GET /shop/schedule/floor-plan* 前缀路由：读本地 store；支持 subscriberId + callback 订阅更新
+     */
+    private handleFloorPlanGet;
+    private computeFloorPlanQueryResult;
+    /**
+     * 平面图数据变更后向所有 GET 订阅者推送最新结果
+     */
+    private recomputeAndNotifyFloorPlanQuery;
+    /**
+     * 取消平面图 GET 订阅（也可走 GET .../unsubscribe + subscriberId）
+     */
+    removeFloorPlanQuerySubscriber(subscriberId?: string): void;
     /**
      * 取消预约列表查询订阅（HTTP 路由入口）
      */
@@ -198,6 +599,27 @@ declare class Server {
      * 从订单中展开 bookings，再按条件筛选 + 分页
      */
     private computeBookingQueryResult;
+    /**
+     * 规范商品扩展类型过滤参数。
+     *
+     * @example
+     * const types = this.normalizeProductExtensionTypes(['product_add_time']);
+     */
+    private normalizeProductExtensionTypes;
+    /**
+     * 请求包含 product_add_time 时，按传入 extension_type 数组配置过滤商品。
+     *
+     * @example
+     * const list = this.filterProductsByExtensionTypes(products, ['product_add_time']);
+     */
+    private filterProductsByExtensionTypes;
+    /**
+     * 判断本次查询是否需要跳过餐牌过滤，直接按扩展类型拉商品。
+     *
+     * @example
+     * const skipMenu = this.shouldQueryProductsByExtensionTypes(['product_add_time']);
+     */
+    private shouldQueryProductsByExtensionTypes;
     /**
      * 商品查询的核心计算逻辑（编排 Products、Menu、Schedule 模块）
      * 供 handleProductQuery 首次返回及 pubsub 变更推送复用
@@ -206,6 +628,12 @@ declare class Server {
      * @param options.changedIds 变更的商品 IDs，用于增量更新价格缓存
      */
     private computeProductQueryResult;
+    /**
+     * 构建商品格式化上下文。
+     *
+     * 智能定价条件使用全量 menuList/scheduleList；Product Query 顶层参数只保留筛选商品集合所需字段。
+     */
+    private buildProductFormatterContext;
     /**
      * 数据变更后，遍历所有订阅者重新计算查询结果并通过 callback 推送
      * 由 ProductsModule 的 onProductsSyncCompleted 事件触发
@@ -217,18 +645,44 @@ declare class Server {
      * 订单数据变更后，遍历订阅者重新计算并通过 callback 推送
      */
     private recomputeAndNotifyOrderQuery;
+    /**
+     * 订单变更后通知 sales 搜索订阅者。
+     * 仅回传当前查询已返回订单号集合中的变更订单。
+     *
+     * @example
+     * this.notifySalesSearchSubscribers({ list: [], changedOrders: [order], source: 'pubsub.bodyUpsert' })
+     */
+    private notifySalesSearchSubscribers;
+    /**
+     * 从订单变更事件中提取明确 delta。
+     *
+     * @example
+     * const list = this.extractChangedOrdersFromPayload(payload)
+     */
+    private extractChangedOrdersFromPayload;
+    /**
+     * 构建与当前搜索接口一致的 delta 响应。
+     *
+     * @example
+     * const response = this.buildSalesSearchDeltaResponse(subscriber, [order])
+     */
+    private buildSalesSearchDeltaResponse;
+    /**
+     * 构建聚合搜索接口的 sales 分组 delta 响应。
+     *
+     * @example
+     * const response = this.buildAggregateSalesSearchDeltaResponse(subscriber, [order])
+     */
+    private buildAggregateSalesSearchDeltaResponse;
     /**
      * 预约数据变更后，遍历订阅者重新计算并通过 callback 推送
      */
     private recomputeAndNotifyBookingQuery;
     /**
-     * 根据餐牌配置过滤商品
-     * @param products 所有商品列表
-     * @param activeMenuList 生效的餐牌列表
-     * @returns 过滤后的商品列表
+     * 根据餐牌配置提取轻量商品范围。
      * @private
      */
-    private filterProductsByMenuConfig;
+    private getProductScopeByMenuConfig;
     /**
      * 记录信息日志
      * @param title 日志标题