oak-backend-base 4.1.27 → 4.1.29

package/lib/AppLoader.d.ts

@@ -19,6 +19,7 @@ export declare class AppLoader<ED extends EntityDict & BaseEntityDict, Cxt exten
     private watcherTimerId?;
     private scheduledJobs;
     private internalErrorHandlers;
+    private watcherExecutingData;
     regAllExceptionHandler(): void;
     /**
      * 注册一个内部错误处理器
@@ -32,9 +33,15 @@ export declare class AppLoader<ED extends EntityDict & BaseEntityDict, Cxt exten
     private requireSth;
     protected makeContext(cxtStr?: string, headers?: IncomingHttpHeaders): Promise<Cxt>;
     /**
-     * 后台启动的configuration，统一放在这里读取
+     *  获取数据库配置
+     * @returns  读取数据库配置
      */
-    private getConfiguration;
+    private getDbConfig;
+    /**
+     *  获取同步配置
+     * @returns  读取同步配置
+     */
+    private getSyncConfig;
     constructor(path: string, nsSubscribe?: Namespace, nsSocket?: Namespace, nsServer?: Namespace);
     protected registerTrigger(trigger: Trigger<ED, keyof ED, Cxt>): void;
     protected initTriggers(): void;
@@ -55,6 +62,30 @@ export declare class AppLoader<ED extends EntityDict & BaseEntityDict, Cxt exten
     }>][];
     protected operateInWatcher<T extends keyof ED>(entity: T, operation: ED[T]['Update'], context: Cxt, singleton?: true): Promise<OperationResult<ED>>;
     protected selectInWatcher<T extends keyof ED>(entity: T, selection: ED[T]['Selection'], context: Cxt, forUpdate?: true, singleton?: true): Promise<Partial<ED[T]["Schema"]>[]>;
+    /**
+     *  检查某个数据是否正在被watcher执行
+     * @param name  watcher名称
+     * @param dataId  数据ID
+     * @returns  如果没有正在执行则返回true，否则返回false
+     */
+    private checkDataExecuting;
+    /**
+     * 过滤出未在执行中的数据行，并标记为执行中
+     * @returns [过滤后的行, 是否有行被跳过]
+     */
+    private filterAndMarkExecutingRows;
+    /**
+     * 清理执行标记
+     */
+    private cleanupExecutingMarks;
+    /**
+     * 解析 filter 和 projection（支持函数或静态值）
+     */
+    private resolveFilterAndProjection;
+    /**
+     * 执行 WB 类型 watcher 的查询操作
+     */
+    private selectForWBWatcher;
     protected execWatcher(watcher: Watcher<ED, keyof ED, Cxt>): Promise<OperationResult<ED> | undefined>;
     protected getCheckpointTs(): number;
     protected checkpoint(): Promise<number>;

package/lib/AppLoader.js

@@ -30,6 +30,7 @@ class AppLoader extends types_1.AppLoader {
     watcherTimerId;
     scheduledJobs = {};
     internalErrorHandlers = new Array();
+    watcherExecutingData = new Map();
     regAllExceptionHandler() {
         const handlers = this.requireSth('lib/configuration/exception');
         if (Array.isArray(handlers)) {
@@ -92,20 +93,24 @@ class AppLoader extends types_1.AppLoader {
         return context;
     }
     /**
-     * 后台启动的configuration，统一放在这里读取
+     *  获取数据库配置
+     * @returns  读取数据库配置
      */
-    getConfiguration() {
-        const dbConfig = (0, dbPriority_1.getDbConfig)(this.path);
+    getDbConfig() {
+        return (0, dbPriority_1.getDbConfig)(this.path);
+    }
+    /**
+     *  获取同步配置
+     * @returns  读取同步配置
+     */
+    getSyncConfig() {
         const syncConfigFile = (0, path_1.join)(this.path, 'lib', 'configuration', 'sync.js');
         const syncConfigs = (0, fs_1.existsSync)(syncConfigFile) && require(syncConfigFile).default;
-        return {
-            dbConfig: dbConfig,
-            syncConfig: syncConfigs,
-        };
+        return syncConfigs;
     }
     constructor(path, nsSubscribe, nsSocket, nsServer) {
         super(path);
-        const { dbConfig } = this.getConfiguration();
+        const dbConfig = this.getDbConfig();
         const { storageSchema } = require(`${path}/lib/oak-app-domain/Storage`);
         const depGraph = (0, dependencyBuilder_1.analyzeDepedency)(process.cwd());
         this.externalDependencies = depGraph.ascOrder;
@@ -173,7 +178,7 @@ class AppLoader extends types_1.AppLoader {
     async mount(initialize) {
         const { path } = this;
         if (!initialize) {
-            const { syncConfig: syncConfig } = this.getConfiguration();
+            const syncConfig = this.getSyncConfig();
             if (syncConfig) {
                 this.synchronizer = new Synchronizer_1.default(syncConfig, this.dbStore.getSchema(), () => this.contextBuilder(this.dbStore));
             }
@@ -182,7 +187,7 @@ class AppLoader extends types_1.AppLoader {
         }
         const { importations, exportations } = require(`${path}/lib/ports/index`);
         (0, index_1.registerPorts)(importations || [], exportations || []);
-        this.dbStore.connect();
+        return this.dbStore.connect();
     }
     async unmount() {
         if (this.watcherTimerId) {
@@ -368,60 +373,172 @@ class AppLoader extends types_1.AppLoader {
             forUpdate,
         });
     }
+    /**
+     *  检查某个数据是否正在被watcher执行
+     * @param name  watcher名称
+     * @param dataId  数据ID
+     * @returns  如果没有正在执行则返回true，否则返回false
+     */
+    checkDataExecuting(name, dataId) {
+        let dataSet = this.watcherExecutingData.get(name);
+        if (!dataSet) {
+            dataSet = new Map();
+            this.watcherExecutingData.set(name, dataSet);
+        }
+        const existingTs = dataSet.get(dataId);
+        if (existingTs) {
+            const now = Date.now();
+            if (now - existingTs > 10 * 60 * 1000) {
+                console.error(`检测到执行器【${name}】的数据【${dataId}】标记超时（${Math.floor((now - existingTs) / 1000)}秒），请立即检查是否存在死循环或长时间阻塞的操作`);
+            }
+            return false;
+        }
+        dataSet.set(dataId, Date.now());
+        return true;
+    }
+    /**
+     * 过滤出未在执行中的数据行，并标记为执行中
+     * @returns [过滤后的行, 是否有行被跳过]
+     */
+    filterAndMarkExecutingRows(watcher, rows) {
+        if (watcher.exclusive !== true) {
+            // 不需要排他执行，直接返回所有行
+            return [rows, false];
+        }
+        const rowsWithoutExecuting = [];
+        let hasSkiped = false;
+        const watcherName = watcher.name;
+        for (const row of rows) {
+            if (!row.id) {
+                console.error(`实例【${process.env.OAK_INSTANCE_ID || '单机'}】执行器【${watcherName}】获取的数据没有ID，跳过此数据的并发检查处理：`, row);
+                rowsWithoutExecuting.push(row);
+                continue;
+            }
+            if (this.checkDataExecuting(watcherName, row.id)) {
+                rowsWithoutExecuting.push(row);
+            }
+            else {
+                hasSkiped = true;
+                console.warn(`实例【${process.env.OAK_INSTANCE_ID || '单机'}】执行器【${watcherName}】将跳过正在被执行的数据ID：【${row.id}】，请检查是否执行超时`);
+            }
+        }
+        return [rowsWithoutExecuting, hasSkiped];
+    }
+    /**
+     * 清理执行标记
+     */
+    cleanupExecutingMarks(watcherName, rows) {
+        for (const row of rows) {
+            if (row.id) {
+                const dataSet = this.watcherExecutingData.get(watcherName);
+                if (dataSet) {
+                    dataSet.delete(row.id);
+                }
+            }
+        }
+    }
+    /**
+     * 解析 filter 和 projection（支持函数或静态值）
+     */
+    async resolveFilterAndProjection(filter, projection) {
+        const filter2 = typeof filter === 'function' ? await filter() : (0, lodash_1.cloneDeep)(filter);
+        const projection2 = typeof projection === 'function' ? await projection() : (0, lodash_1.cloneDeep)(projection);
+        return [filter2, projection2];
+    }
+    /**
+     * 执行 WB 类型 watcher 的查询操作
+     */
+    async selectForWBWatcher(watcher, context) {
+        const { entity, projection, filter, singleton, forUpdate } = watcher;
+        const [filter2, projection2] = await this.resolveFilterAndProjection(filter, projection);
+        return await this.selectInWatcher(entity, {
+            data: projection2,
+            filter: filter2,
+        }, context, forUpdate, singleton);
+    }
     async execWatcher(watcher) {
         let result;
-        if (watcher.hasOwnProperty('type') && watcher.type === 'free') {
-            const selectContext = await this.makeContext();
-            const { entity, projection, fn, filter, singleton, forUpdate } = watcher;
-            const filter2 = typeof filter === 'function' ? await filter() : (0, lodash_1.cloneDeep)(filter);
-            const projection2 = typeof projection === 'function' ? await projection() : (0, lodash_1.cloneDeep)(projection);
-            const rows = await this.selectInWatcher(entity, {
-                data: projection2,
-                filter: filter2,
-            }, selectContext, forUpdate, singleton);
-            if (rows.length > 0) {
-                result = await fn(() => this.makeContext(), rows);
+        // BBWatcher：直接操作，无需查询
+        if (watcher.hasOwnProperty('actionData')) {
+            // 如果配置了 exclusive，BBWatcher 不支持
+            if (watcher.exclusive === true) {
+                console.warn(`BBWatcher【${watcher.name}】配置了 exclusive=true，但 BBWatcher 不支持排他执行，将忽略此配置，请使用 WBWatcher 或 WBFreeWatcher 来实现排他执行`);
             }
-            return result;
-        }
-        const context = await this.makeContext();
-        try {
-            if (watcher.hasOwnProperty('actionData')) {
+            const context = await this.makeContext();
+            try {
                 const { entity, action, filter, actionData, singleton } = watcher;
                 const filter2 = typeof filter === 'function' ? await filter() : (0, lodash_1.cloneDeep)(filter);
-                const data = typeof actionData === 'function' ? await (actionData)() : (0, lodash_1.cloneDeep)(actionData);
+                const data = typeof actionData === 'function' ? await actionData() : (0, lodash_1.cloneDeep)(actionData);
                 result = await this.operateInWatcher(entity, {
                     id: await (0, uuid_1.generateNewIdAsync)(),
                     action: action,
                     data,
                     filter: filter2,
                 }, context, singleton);
+                await context.commit();
+                return result;
             }
-            else {
-                const { entity, projection, fn, filter, singleton, forUpdate } = watcher;
-                const filter2 = typeof filter === 'function' ? await filter() : (0, lodash_1.cloneDeep)(filter);
-                const projection2 = typeof projection === 'function' ? await projection() : (0, lodash_1.cloneDeep)(projection);
-                const rows = await this.selectInWatcher(entity, {
-                    data: projection2,
-                    filter: filter2,
-                }, context, forUpdate, singleton);
-                if (rows.length > 0) {
-                    result = await fn(context, rows);
+            catch (err) {
+                if (err instanceof types_1.OakPartialSuccess) {
+                    await context.commit();
+                }
+                else {
+                    await context.rollback();
                 }
+                throw err;
+            }
+        }
+        // WBFreeWatcher 和 WBWatcher：查询后执行
+        const isFreeType = watcher.hasOwnProperty('type') &&
+            watcher.type === 'free';
+        // 1. 执行查询（WBFreeWatcher 使用独立 context）
+        const selectContext = isFreeType ? await this.makeContext() : await this.makeContext();
+        const rows = await this.selectForWBWatcher(watcher, selectContext);
+        if (isFreeType) {
+            await selectContext.commit();
+        }
+        // 2. 并发检查：过滤出未在执行中的数据
+        const [rowsWithoutExecuting, hasSkipped] = this.filterAndMarkExecutingRows(watcher, rows);
+        if (rowsWithoutExecuting.length === 0) {
+            if (!isFreeType) {
+                await selectContext.commit();
+            }
+            // 全部行都被跳过，直接返回，实际没有执行任何操作，hasSkipped也是其他执行流在处理
+            // this.cleanupExecutingMarks(watcher.name, hasSkipped);
+            if (hasSkipped) {
+                console.log(`执行器【${watcher.name}】本次没有可执行的数据行，全部数据行均被跳过`);
             }
-            await context.commit();
             return result;
         }
-        catch (err) {
-            if (err instanceof types_1.OakPartialSuccess) {
-                await context.commit();
+        // 3. 执行业务逻辑
+        try {
+            if (isFreeType) {
+                const { fn } = watcher;
+                result = await fn(() => this.makeContext(), rowsWithoutExecuting);
             }
             else {
-                await context.rollback();
+                const { fn } = watcher;
+                result = await fn(selectContext, rowsWithoutExecuting);
+                await selectContext.commit();
+            }
+            return result;
+        }
+        catch (err) {
+            if (!isFreeType) {
+                if (err instanceof types_1.OakPartialSuccess) {
+                    await selectContext.commit();
+                }
+                else {
+                    await selectContext.rollback();
+                }
             }
-            // 不能在这里publish，因为这个方法可能是在timer中调用，也可能是在routine中调用
             throw err;
         }
+        finally {
+            // 清理执行标记
+            this.cleanupExecutingMarks(watcher.name, rowsWithoutExecuting);
+            // 这里只需要清理被执行的行，因为被跳过的行本来就不是这一次执行被占用的。
+        }
     }
     getCheckpointTs() {
         const now = Date.now();

package/lib/DbStore.d.ts

@@ -2,6 +2,7 @@ import { DbConfiguration } from 'oak-db/src/types/configuration';
 import { EntityDict, StorageSchema, Trigger, Checker, SelectFreeEntities, UpdateFreeDict, AuthDeduceRelationMap, VolatileTrigger, OperateOption } from 'oak-domain/lib/types';
 import { EntityDict as BaseEntityDict } from 'oak-domain/lib/base-app-domain';
 import { BackendRuntimeContext } from 'oak-frontend-base/lib/context/BackendRuntimeContext';
+import { DbTypeSymbol } from './utils/dbPriority';
 import { CascadeStore } from 'oak-domain/lib/store/CascadeStore';
 import { DbStore } from 'oak-db/lib/types/dbStore';
 export type TriggerStore<ED extends EntityDict & BaseEntityDict, Cxt extends BackendRuntimeContext<ED>> = {
@@ -13,4 +14,6 @@ export type TriggerStore<ED extends EntityDict & BaseEntityDict, Cxt extends Bac
     independentCheckPoint(name: string, ts: number, instanceCount?: number, instanceId?: number): Promise<number>;
 };
 export type AppDbStore<ED extends EntityDict & BaseEntityDict, Cxt extends BackendRuntimeContext<ED>> = DbStore<ED, Cxt> & CascadeStore<ED> & TriggerStore<ED, Cxt>;
-export declare const createDbStore: <ED extends EntityDict & BaseEntityDict, Cxt extends BackendRuntimeContext<ED>>(storageSchema: StorageSchema<ED>, contextBuilder: () => Cxt, dbConfiguration: DbConfiguration, authDeduceRelationMap: AuthDeduceRelationMap<ED>, selectFreeEntities?: SelectFreeEntities<ED>, updateFreeDict?: UpdateFreeDict<ED>, onVolatileTrigger?: <T extends keyof ED>(entity: T, trigger: VolatileTrigger<ED, T, Cxt>, ids: string[], cxtStr: string, option: OperateOption) => Promise<void>) => AppDbStore<ED, Cxt>;
+export declare const createDbStore: <ED extends EntityDict & BaseEntityDict, Cxt extends BackendRuntimeContext<ED>>(storageSchema: StorageSchema<ED>, contextBuilder: () => Cxt, dbConfiguration: DbConfiguration & {
+    [DbTypeSymbol]?: string;
+}, authDeduceRelationMap: AuthDeduceRelationMap<ED>, selectFreeEntities?: SelectFreeEntities<ED>, updateFreeDict?: UpdateFreeDict<ED>, onVolatileTrigger?: <T extends keyof ED>(entity: T, trigger: VolatileTrigger<ED, T, Cxt>, ids: string[], cxtStr: string, option: OperateOption) => Promise<void>) => AppDbStore<ED, Cxt>;

package/lib/DbStore.js

@@ -5,8 +5,10 @@ const TriggerExecutor_1 = require("oak-domain/lib/store/TriggerExecutor");
 const RelationAuth_1 = require("oak-domain/lib/store/RelationAuth");
 const dbPriority_1 = require("./utils/dbPriority");
 const createDbStore = (storageSchema, contextBuilder, dbConfiguration, authDeduceRelationMap, selectFreeEntities = [], updateFreeDict = {}, onVolatileTrigger) => {
-    const BaseStoreClass = (0, dbPriority_1.getDbStoreClass)();
+    // TODO: 这里的类型检查会过不去，因为ts不知道上层已经实现这个抽象类。
+    const BaseStoreClass = (0, dbPriority_1.getDbStoreClass)(dbConfiguration);
     // 动态创建继承类
+    // @ts-ignore
     class DynamicDbStore extends BaseStoreClass {
         executor;
         relationAuth;

package/lib/Synchronizer.d.ts

@@ -2,12 +2,21 @@ import { EntityDict, StorageSchema, EndpointItem, SyncConfig } from 'oak-domain/
 import { VolatileTrigger } from 'oak-domain/lib/types/Trigger';
 import { EntityDict as BaseEntityDict } from 'oak-domain/lib/base-app-domain';
 import { BackendRuntimeContext } from 'oak-frontend-base/lib/context/BackendRuntimeContext';
+export type FetchFn = (url: string, options: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}, timeout?: number) => Promise<{
+    status: number;
+    json: () => Promise<any>;
+}>;
 export default class Synchronizer<ED extends EntityDict & BaseEntityDict, Cxt extends BackendRuntimeContext<ED>> {
     private config;
     private schema;
     private remotePullInfoMap;
     private channelDict;
     private contextBuilder;
+    private fetchFn;
     private pushAccessMap;
     private startChannel2;
     /**开始同步这些channel上的oper。注意，这时候即使某个channel上失败了，也不应影响本事务提交（其它的channel成功了） */
@@ -22,7 +31,7 @@ export default class Synchronizer<ED extends EntityDict & BaseEntityDict, Cxt ex
      */
     private trySynchronizeOpers;
     private makeCreateOperTrigger;
-    constructor(config: SyncConfig<ED, Cxt>, schema: StorageSchema<ED>, contextBuilder: () => Cxt);
+    constructor(config: SyncConfig<ED, Cxt>, schema: StorageSchema<ED>, contextBuilder: () => Cxt, fetchFn?: FetchFn);
     /**
      * 根据sync的定义，生成对应的 commit triggers
      * @returns

package/lib/Synchronizer.js

@@ -5,11 +5,11 @@ const crypto_1 = require("crypto");
 const types_1 = require("oak-domain/lib/types");
 const relationPath_1 = require("oak-domain/lib/utils/relationPath");
 const assert_1 = tslib_1.__importDefault(require("assert"));
-const path_1 = require("path");
 const lodash_1 = require("oak-domain/lib/utils/lodash");
 const filter_1 = require("oak-domain/lib/store/filter");
 const uuid_1 = require("oak-domain/lib/utils/uuid");
 const lodash_2 = require("lodash");
+const domain_1 = require("oak-domain/lib/utils/domain");
 const OAK_SYNC_HEADER_ENTITY = 'oak-sync-entity';
 const OAK_SYNC_HEADER_ENTITY_ID = 'oak-sync-entity-id';
 const OAK_SYNC_HEADER_TIMESTAMP = 'oak-sync-timestamp';
@@ -67,6 +67,7 @@ class Synchronizer {
     remotePullInfoMap = {};
     channelDict = {};
     contextBuilder;
+    fetchFn;
     pushAccessMap = {};
     async startChannel2(context, channel) {
         const { queue, api, selfEncryptInfo, entity, entityId, onFailed, timeout = 5000 } = channel;
@@ -78,12 +79,12 @@ class Synchronizer {
                 seq: ele.$$seq$$,
             }))), 'txnId:', context.getCurrentTxnId());
         }
-        const finalApi = (0, path_1.join)(api, selfEncryptInfo.id);
+        const finalApi = (0, domain_1.urlJoin)(api, selfEncryptInfo.id);
         channel.queue = [];
         try {
             const body = JSON.stringify(opers);
             const { ts, nonce, signature } = await sign(selfEncryptInfo.privateKey, body);
-            const res = await fetchWithTimeout(finalApi, {
+            const res = await this.fetchFn(finalApi, {
                 method: 'post',
                 headers: {
                     'Content-Type': 'application/json',
@@ -190,7 +191,7 @@ class Synchronizer {
         if (!this.channelDict[userId]) {
             // channel上缓存这些信息，暂不支持动态更新
             this.channelDict[userId] = {
-                api: (0, path_1.join)(url, 'endpoint', endpoint),
+                api: (0, domain_1.urlJoin)(url, 'endpoint', endpoint),
                 queue: [],
                 entity: remoteEntity,
                 entityId: remoteEntityId,
@@ -205,7 +206,7 @@ class Synchronizer {
             (0, assert_1.default)(this.channelDict[userId].onFailed === onFailed);
         }
         const channel = this.channelDict[userId];
-        (0, assert_1.default)(channel.api === (0, path_1.join)(url, 'endpoint', endpoint));
+        (0, assert_1.default)(channel.api === (0, domain_1.urlJoin)(url, 'endpoint', endpoint));
         (0, assert_1.default)(channel.entity === remoteEntity);
         (0, assert_1.default)(channel.entityId === remoteEntityId);
         if (channel.queue.find(ele => ele.oper.id === oper.id)) {
@@ -343,8 +344,19 @@ class Synchronizer {
             }, { dontCollect: true, forUpdate: true });
             dirtyOpers = dirtyOpers.filter(ele => !!ele[types_1.TriggerUuidAttribute]);
             if (dirtyOpers.length > 0) {
+                // 检查所有 channel 的 queue 是否已清空
                 for (const c in this.channelDict) {
-                    (0, assert_1.default)(this.channelDict[c].queue.length === 0);
+                    // 在生产环境不使用assert，而是清空队列，以防止脏数据堆积影响后续同步
+                    if (this.channelDict[c].queue.length > 0) {
+                        if (process.env.NODE_ENV !== 'production') {
+                            // 构建详细的错误信息
+                            const queuedOperIds = this.channelDict[c].queue.map(q => q.oper.id).join(', ');
+                            (0, assert_1.default)(false, `发现 channel ${c} 的 queue 未清空，包含 oper IDs: [${queuedOperIds}]`);
+                        }
+                        else {
+                            this.channelDict[c].queue = [];
+                        }
+                    }
                 }
                 const pushedIds = [];
                 const unPushedIds = [];
@@ -394,15 +406,45 @@ class Synchronizer {
     makeCreateOperTrigger() {
         const { config } = this;
         const { remotes, self } = config;
+        const entityActionMap = new Map();
         // 根据remotes定义，建立从entity到需要同步的远端结点信息的Map
         remotes.forEach((remote) => {
             const { getPushInfo, pushEntities: pushEntityDefs, endpoint, pathToUser, relationName: rnRemote, onFailed, timeout } = remote;
             if (pushEntityDefs) {
                 const pushEntities = [];
-                const endpoint2 = (0, path_1.join)(endpoint || 'sync', self.entity);
+                const endpoint2 = (0, domain_1.urlJoin)(endpoint || 'sync', self.entity);
                 for (const def of pushEntityDefs) {
                     const { pathToRemoteEntity, pathToSelfEntity, relationName, recursive, entity, actions, onSynchronized } = def;
                     pushEntities.push(entity);
+                    if (!entityActionMap.has(entity)) {
+                        entityActionMap.set(entity, {
+                            actions: new Set(),
+                            matchAllActions: false,
+                        });
+                    }
+                    const tracker = entityActionMap.get(entity);
+                    //如果当前定义是 wildcard（所有 action）
+                    if (!actions || actions.length === 0) {
+                        if (tracker.matchAllActions) {
+                            throw new Error(`PushEntityDef 配置错误：entity「${entity}」的所有 action 被定义了多次`);
+                        }
+                        if (tracker.actions.size > 0) {
+                            throw new Error(`PushEntityDef 配置错误：entity「${entity}」已定义特定 action「${Array.from(tracker.actions).join(', ')}」，不能再定义所有 action`);
+                        }
+                        tracker.matchAllActions = true;
+                    }
+                    else {
+                        // 如果当前定义是特定 action
+                        if (tracker.matchAllActions) {
+                            throw new Error(`PushEntityDef 配置错误：entity「${entity}」已定义所有 action，不能再定义特定 action「${actions.join(', ')}」`);
+                        }
+                        for (const action of actions) {
+                            if (tracker.actions.has(action)) {
+                                throw new Error(`PushEntityDef 配置错误：entity「${entity}」的action「${action}」被定义了多次`);
+                            }
+                            tracker.actions.add(action);
+                        }
+                    }
                     const relationName2 = relationName || rnRemote;
                     const path2 = pathToUser ? `${pathToRemoteEntity}.${pathToUser}` : pathToRemoteEntity;
                     (0, assert_1.default)(!recursive);
@@ -507,10 +549,11 @@ class Synchronizer {
         };
         return createOperTrigger;
     }
-    constructor(config, schema, contextBuilder) {
+    constructor(config, schema, contextBuilder, fetchFn) {
         this.config = config;
         this.schema = schema;
         this.contextBuilder = contextBuilder;
+        this.fetchFn = fetchFn || fetchWithTimeout;
     }
     /**
      * 根据sync的定义，生成对应的 commit triggers

package/lib/routines/update.d.ts

@@ -0,0 +1,65 @@
+import { EntityDict as TypeEntityDict, StorageSchema } from 'oak-domain/lib/types';
+import { AsyncContext } from 'oak-domain/lib/store/AsyncRowStore';
+import BackendRuntimeContext from 'oak-frontend-base/lib/context/BackendRuntimeContext';
+import { EntityDict as BaseEntityDict } from 'oak-domain/lib/base-app-domain';
+type EntityDict = TypeEntityDict & BaseEntityDict;
+/**
+ * 反向引用描述
+ * 用于记录哪些实体引用了当前实体，便于在删除或更新时维护引用完整性
+ */
+export type ReverseRefDesc<ED extends EntityDict> = {
+    type: 'ref' | 'refs';
+    attrName: string;
+    sourceEntity: keyof ED;
+};
+/**
+ * 更新计划配置
+ * 定义了数据同步的完整策略和生命周期钩子
+ */
+export type UpdatePlan<ED extends EntityDict> = {
+    dontCreateOper?: boolean;
+    plan: {
+        [entityName in keyof ED]: {
+            /**
+             * 是否允许数据唯一性冲突时使用新数据覆盖旧数据（仅data中冲突）
+             * @deprecated ID必须相同但会导致ID检查不通过，弃用
+             */
+            allowDataUniqueReWrite?: boolean;
+            /**
+             * 在插入数据库遇到唯一性冲突时的处理方式（数据库和data冲突）
+             * skip表示跳过插入新数据，会将新数据的反指关系更新到已有数据上
+             * update表示使用新数据更新已有数据，会自动更新现有数据的所有反指关系
+             * error表示抛出错误
+             */
+            onUniqueViolation?: 'skip' | 'update' | 'error';
+            /**
+             * 处理数据库中存在但是数据文件中不存在的数据的方式
+             * skip表示跳过不处理
+             * delete表示做逻辑删除，可能导致插入新数据时id冲突
+             * 设置为physicalDelete可以保证最强的一致性
+             */
+            onOnlyExistingInDb?: 'skip' | 'delete' | 'physicalDelete';
+        };
+    };
+    beforeCheck?: (options: {
+        context: BackendRuntimeContext<ED>;
+        data: {
+            [entityName in keyof ED]?: Array<Partial<ED[entityName]['CreateOperationData']>>;
+        };
+        reverseRefs: {
+            [entityName in keyof ED]?: ReverseRefDesc<ED>[];
+        };
+    }) => Promise<void>;
+    afterUpdate?: (options: {
+        context: BackendRuntimeContext<ED>;
+        data: {
+            [entityName in keyof EntityDict]?: Array<Partial<EntityDict[entityName]['CreateOperationData']>>;
+        };
+        reverseRefs: {
+            [entityName in keyof EntityDict]?: ReverseRefDesc<ED>[];
+        };
+    }) => Promise<void>;
+};
+export declare const createUpdatePlan: <ED extends EntityDict>(options: UpdatePlan<ED>) => <Cxt extends AsyncContext<ED>>(context: Cxt) => Promise<void>;
+export declare function checkPathValue(itemId: string, destEntity: keyof EntityDict, path: string, storageSchema: StorageSchema<EntityDict>): boolean;
+export {};