@pisell/pisellos 2.2.189 → 2.2.191

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

@@ -2,6 +2,44 @@ import { Module, ModuleOptions, PisellCore } from '../../../types';
 import { BaseModule } from '../../../modules/BaseModule';
 import type { RouteDefinition } from '../../types';
 import { OrderData, OrderId } from './types';
+/** 订单模块流程调试日志条目 */
+interface OrderFlowLogEntry {
+    ts: string;
+    step: string;
+    metadata?: Record<string, unknown>;
+}
+/** 单笔订单 SQLite 写入记录 */
+interface OrderWriteStatEntry {
+    ts: string;
+    writeSeq: number;
+    source: string;
+    writeMethod: string;
+    orderId: OrderId | null;
+    storageKey: string;
+    mergeAction?: 'insert' | 'update' | 'snapshot' | 'singleUpdate';
+}
+declare global {
+    interface Window {
+        /** 订单模块流程调试日志，可在 DevTools 直接查看 */
+        __orderModuleFlowLogs?: OrderFlowLogEntry[];
+        /** 按 storageKey 聚合的 SQLite 写入次数，便于排查重复写 */
+        __orderModuleWriteStats?: Record<string, OrderWriteStatEntry[]>;
+        /** 清空订单流程调试日志 */
+        clearOrderModuleFlowLogs?: () => void;
+        /** 导出订单流程调试日志 JSON 字符串 */
+        exportOrderModuleFlowLogs?: () => string;
+        /** 导出按订单聚合的写入统计 */
+        exportOrderModuleWriteStats?: () => string;
+        /** 汇总写入次数 Top N（默认 20） */
+        summarizeOrderModuleWrites?: (topN?: number) => Array<{
+            storageKey: string;
+            orderId: OrderId | null;
+            writeCount: number;
+            sources: string[];
+            lastWriteAt: string;
+        }>;
+    }
+}
 /**
  * Order 模块 - 基础框架
  */
@@ -19,6 +57,12 @@ export declare class OrderModule extends BaseModule implements Module {
     private logger;
     private storage;
     private orderSQLiteSaveQueue;
+    /** 全局递增的 SQLite 写入序号，便于日志关联同一次操作 */
+    private orderFlowWriteSeq;
+    /** 按 storageKey 记录最近一次 SQLite 写入来源与时间，用于去重 */
+    private recentSqliteWriteByStorageKey;
+    /** 最近一次 SSE 全量拉取完成时间 */
+    private lastServerFullFetchAtMs;
     constructor(name?: string, version?: string);
     initialize(core: PisellCore, options?: ModuleOptions): Promise<void>;
     /**
@@ -33,6 +77,60 @@ export declare class OrderModule extends BaseModule implements Module {
      * @param metadata 日志元数据
      */
     private logError;
+    /**
+     * 初始化 window 上的订单流程调试日志数组及辅助方法。
+     *
+     * @example
+     * window.clearOrderModuleFlowLogs()
+     * // 操作完成后：
+     * copy(window.exportOrderModuleFlowLogs?.() || '[]')
+     */
+    private initOrderFlowLogs;
+    /**
+     * 写入 window 订单流程调试日志。
+     *
+     * @example
+     * this.pushOrderFlowLog('mergeOrdersToStore.start', { count: 3 })
+     */
+    private pushOrderFlowLog;
+    /** 当前内存 store 快照信息，供流程日志使用 */
+    private getOrderStoreSnapshot;
+    /**
+     * 记录一次 SQLite 写入到 window 统计，用于排查同一订单被多次写入的原因。
+     *
+     * @example
+     * this.trackOrderWrite('upsertOrdersFromRemote', 'bulkUpdate', orders, 'insert')
+     */
+    private trackOrderWrite;
+    /**
+     * 记录订单最近一次 SQLite 写入，供 pubsub 回声去重使用。
+     *
+     * @example
+     * this.recordRecentSqliteWrite('upsertOrdersFromRemote', orders)
+     */
+    private recordRecentSqliteWrite;
+    /**
+     * 过滤 pubsub 触发的冗余 SQLite patch（业务 API 刚写入过的 update 回声）。
+     *
+     * @example
+     * const { toWrite, skipped } = this.filterRedundantPatchOrders('pubsub.bodyUpsert', orders, mergeActions)
+     */
+    private filterRedundantPatchOrders;
+    /**
+     * 过滤 pubsub HTTP 增量拉取 ids：本地刚由业务 API 写入的单可跳过 HTTP。
+     *
+     * @example
+     * const ids = this.filterRedundantHttpRefreshIds([99331, 99332])
+     */
+    private filterRedundantHttpRefreshIds;
+    /**
+     * 解析 pubsub 消息会走哪条同步分支，便于对照为何触发 HTTP 重拉或 body 直写。
+     *
+     * @example
+     * this.resolveSyncMessageRoute(msg)
+     * // => { route: 'httpRefresh.batchIds', ... }
+     */
+    private resolveSyncMessageRoute;
     private getOrderSyncThrottleMs;
     preload(): Promise<void>;
     getOrders(): OrderData[];
@@ -120,6 +218,14 @@ export declare class OrderModule extends BaseModule implements Module {
     private normalizeOrderSyncPayload;
     private uniqueOrderIds;
     private getIdKey;
+    /**
+     * 解析订单 SQLite 主键，规则与宿主 OrderDataSource.getOrderStorageKey 一致。
+     *
+     * @example
+     * const key = this.getOrderStorageKey({ order_id: 1001, external_sale_number: 'S-1001' })
+     * // => 'S-1001'
+     */
+    private getOrderStorageKey;
     /**
      * 当前订单拉取窗口：
      * - 优先使用 createdAtQuery.sales_time_between（已按营业日边界初始化）
@@ -132,22 +238,35 @@ export declare class OrderModule extends BaseModule implements Module {
     private setStorageItem;
     private loadOrdersFromSQLite;
     /**
-     * 串行执行订单 SQLite 保存任务，保证 clear + bulkAdd 组合不会被其它订单保存插入。
+     * 串行执行订单 SQLite 写入任务，避免快照替换与增量 upsert 并发交错。
      *
      * @example
      * await this.runInOrderSQLiteSaveQueue(async () => {
-     *   await this.dbManager.clear(INDEXDB_STORE_NAME)
-     *   await this.dbManager.bulkAdd(INDEXDB_STORE_NAME, orders)
+     *   await this.dbManager.bulkUpdate(INDEXDB_STORE_NAME, orders)
      * })
      */
     private runInOrderSQLiteSaveQueue;
     /**
-     * 保存订单列表到 SQLite，内部会先清空 orders 表再批量写入当前快照。
+     * 批量增量 upsert 订单到 SQLite，不清空表；用于 pubsub / HTTP 增量合并。
+     *
+     * @example
+     * await this.patchOrdersInSQLite(freshOrders)
+     */
+    private patchOrdersInSQLite;
+    /**
+     * 单条 upsert 订单到 SQLite；用于 overwriteExistingOrder 等单条覆盖场景。
+     *
+     * @example
+     * await this.updateOrderInSQLite(freshOrder)
+     */
+    private updateOrderInSQLite;
+    /**
+     * 全量快照替换 orders 表（clear + bulkAdd），用于 SSE 全量拉取与营业日窗口裁剪。
      *
      * @example
-     * await this.saveOrdersToSQLite(this.store.list)
+     * await this.replaceOrdersSnapshotInSQLite(orderList)
      */
-    private saveOrdersToSQLite;
+    private replaceOrdersSnapshotInSQLite;
     /**
      * 清空订单模块的内存数据和本地 SQLite 订单表。
      *
@@ -156,3 +275,4 @@ export declare class OrderModule extends BaseModule implements Module {
      */
     clear(): Promise<void>;
 }
+export {};