@nocobase/flow-engine 2.2.0-beta.10 → 2.2.0-beta.11

package/lib/utils/dirtyAwareApiClient.js

@@ -31,8 +31,10 @@ __export(dirtyAwareApiClient_exports, {
   getDirtyAwareApiClient: () => getDirtyAwareApiClient
 });
 module.exports = __toCommonJS(dirtyAwareApiClient_exports);
+var import_sdk = require("@nocobase/sdk");
 var import_dataSourceDirty = require("./dataSourceDirty");
 const SKIP_DATA_SOURCE_DIRTY = "__nocobaseSkipDataSourceDirty";
+const DIRTY_DISPATCH_TOKEN = Symbol("nocobaseDirtyDispatchToken");
 const dirtyAwareApiClientCache = /* @__PURE__ */ new WeakMap();
 const dirtyAwareApiClientProxies = /* @__PURE__ */ new WeakSet();
 const MUTATING_RESOURCE_ACTIONS = [
@@ -288,6 +290,43 @@ function resolveDirtyResourceAction(options, context) {
   return parseDirtyResourceActionFromUrl(options == null ? void 0 : options.url, context);
 }
 __name(resolveDirtyResourceAction, "resolveDirtyResourceAction");
+function getDirtyResourceActionDispatchKey(dirtyResourceAction, headers) {
+  if (!dirtyResourceAction) {
+    return void 0;
+  }
+  return JSON.stringify([
+    dirtyResourceAction.dataSourceKey || (0, import_dataSourceDirty.getDataSourceKeyFromHeaders)(headers),
+    dirtyResourceAction.resourceName,
+    dirtyResourceAction.actionName
+  ]);
+}
+__name(getDirtyResourceActionDispatchKey, "getDirtyResourceActionDispatchKey");
+function getRequestDispatchKey(options, context) {
+  return getDirtyResourceActionDispatchKey(resolveDirtyResourceAction(options, context), options.headers);
+}
+__name(getRequestDispatchKey, "getRequestDispatchKey");
+function getResourceDispatchKey(name, of, headers) {
+  const resourceName = String(name ?? "").trim();
+  if (!resourceName) {
+    return void 0;
+  }
+  return JSON.stringify([resourceName, String(of ?? ""), (0, import_dataSourceDirty.getDataSourceKeyFromHeaders)(headers)]);
+}
+__name(getResourceDispatchKey, "getResourceDispatchKey");
+function getMatchingRequestToken(token, requestKey) {
+  if (!token || !requestKey || token.requestKey && token.requestKey !== requestKey) {
+    return void 0;
+  }
+  return token;
+}
+__name(getMatchingRequestToken, "getMatchingRequestToken");
+function getMatchingResourceToken(token, resourceKey) {
+  if (!token || !resourceKey || token.resourceKey && token.resourceKey !== resourceKey) {
+    return void 0;
+  }
+  return token;
+}
+__name(getMatchingResourceToken, "getMatchingResourceToken");
 function markResourceActionDataSourceDirty(context, dirtyResourceAction, headers) {
   (0, import_dataSourceDirty.markDataSourceDirty)({
     engine: context.engine,
@@ -297,7 +336,19 @@ function markResourceActionDataSourceDirty(context, dirtyResourceAction, headers
   });
 }
 __name(markResourceActionDataSourceDirty, "markResourceActionDataSourceDirty");
-function createDirtyAwareResource(context, resource, resourceName, resourceOf, headers) {
+function markResourceActionDataSourceDirtyOnce(token, context, dirtyResourceAction, headers) {
+  if (token.skip || token.marked || !dirtyResourceAction || !isMutatingResourceAction(dirtyResourceAction.actionName)) {
+    return;
+  }
+  token.marked = true;
+  markResourceActionDataSourceDirty(context, dirtyResourceAction, headers);
+}
+__name(markResourceActionDataSourceDirtyOnce, "markResourceActionDataSourceDirtyOnce");
+function isObjectRecord(value) {
+  return !!value && typeof value === "object";
+}
+__name(isObjectRecord, "isObjectRecord");
+function createDirtyAwareResource(context, resource, resourceName, resourceOf, headers, requestTokenStack, parentToken) {
   return new Proxy(resource, {
     get(target, prop, receiver) {
       const original = Reflect.get(target, prop, receiver);
@@ -306,10 +357,38 @@ function createDirtyAwareResource(context, resource, resourceName, resourceOf, h
       }
       const action = original;
       return async (...args) => {
-        const result = await action(...args);
+        const actionOptions = isObjectRecord(args[1]) ? args[1] : void 0;
         const dirtyResourceAction = resolveDirtyResourceActionFromResource(resourceName, resourceOf, prop, context);
-        if (dirtyResourceAction) {
-          markResourceActionDataSourceDirty(context, dirtyResourceAction, headers);
+        const requestKey = getDirtyResourceActionDispatchKey(dirtyResourceAction, headers);
+        const resourceKey = getResourceDispatchKey(resourceName, resourceOf, headers);
+        const inheritedToken = getMatchingRequestToken(
+          actionOptions == null ? void 0 : actionOptions[DIRTY_DISPATCH_TOKEN],
+          requestKey
+        ) || getMatchingRequestToken(parentToken, requestKey);
+        const token = inheritedToken || { marked: false, skip: false };
+        const ownsToken = !inheritedToken;
+        token.requestKey ||= requestKey;
+        token.resourceKey ||= resourceKey;
+        if (actionOptions == null ? void 0 : actionOptions[SKIP_DATA_SOURCE_DIRTY]) {
+          token.skip = true;
+        }
+        const forwardedArgs = actionOptions || args[1] == null ? [
+          args[0],
+          {
+            ...actionOptions,
+            [DIRTY_DISPATCH_TOKEN]: token
+          }
+        ] : args;
+        let actionResult;
+        requestTokenStack.push({ key: requestKey, token });
+        try {
+          actionResult = Reflect.apply(action, receiver, forwardedArgs);
+        } finally {
+          requestTokenStack.pop();
+        }
+        const result = await actionResult;
+        if (ownsToken) {
+          markResourceActionDataSourceDirtyOnce(token, context, dirtyResourceAction, headers);
         }
         return result;
       };
@@ -318,31 +397,206 @@ function createDirtyAwareResource(context, resource, resourceName, resourceOf, h
 }
 __name(createDirtyAwareResource, "createDirtyAwareResource");
 function createDirtyAwareApiClient(api, context) {
+  const baseResource = api.resource;
+  const baseRequest = api.request;
+  const shouldUseResourceDispatchReceiver = baseResource === import_sdk.APIClient.prototype.resource;
+  const shouldUseRequestDispatchReceiver = baseRequest === import_sdk.APIClient.prototype.request;
+  const resourceTokenStack = [];
+  const requestTokenStack = [];
+  let hasResourceOverride = false;
+  let resourceOverride;
+  let hasRequestOverride = false;
+  let requestOverride;
+  const getCurrentResource = /* @__PURE__ */ __name(() => hasResourceOverride ? resourceOverride : resource, "getCurrentResource");
+  const getCurrentRequest = /* @__PURE__ */ __name(() => hasRequestOverride ? requestOverride : request, "getCurrentRequest");
+  const dispatchResource = /* @__PURE__ */ __name((token, args) => {
+    const resourceKey = getResourceDispatchKey(args[0], args[1], args[2]);
+    const activeToken = getMatchingResourceToken(token, resourceKey);
+    const shouldWrapActions = !!activeToken && hasResourceOverride;
+    if (activeToken) {
+      activeToken.resourceKey ||= resourceKey;
+      resourceTokenStack.push({ key: resourceKey, token: activeToken });
+    }
+    try {
+      const resourceInstance = Reflect.apply(getCurrentResource(), proxy, args);
+      if (!shouldWrapActions || !activeToken) {
+        return resourceInstance;
+      }
+      return new Proxy(resourceInstance, {
+        get(target, prop, receiver) {
+          const original = Reflect.get(target, prop, receiver);
+          if (typeof prop !== "string" || typeof original !== "function" || !isMutatingResourceAction(prop)) {
+            return original;
+          }
+          const action = original;
+          return (...actionArgs) => {
+            const actionOptions = isObjectRecord(actionArgs[1]) ? actionArgs[1] : void 0;
+            const forwardedArgs = actionOptions || actionArgs[1] == null ? [
+              actionArgs[0],
+              {
+                ...actionOptions,
+                [DIRTY_DISPATCH_TOKEN]: activeToken
+              }
+            ] : actionArgs;
+            resourceTokenStack.push({ key: resourceKey, token: activeToken });
+            requestTokenStack.push({ key: activeToken.requestKey, token: activeToken });
+            try {
+              return Reflect.apply(action, receiver, forwardedArgs);
+            } finally {
+              requestTokenStack.pop();
+              resourceTokenStack.pop();
+            }
+          };
+        }
+      });
+    } finally {
+      if (activeToken) {
+        resourceTokenStack.pop();
+      }
+    }
+  }, "dispatchResource");
+  const createDispatchReceiver = /* @__PURE__ */ __name((token) => {
+    const receiver = Object.create(api);
+    Object.defineProperties(receiver, {
+      request: {
+        configurable: true,
+        value: /* @__PURE__ */ __name((config) => {
+          const options = config;
+          const requestKey = getRequestDispatchKey(options, context);
+          const stackFrame = requestTokenStack.at(-1);
+          const activeToken = getMatchingRequestToken(options == null ? void 0 : options[DIRTY_DISPATCH_TOKEN], requestKey) || (requestKey && (stackFrame == null ? void 0 : stackFrame.key) === requestKey ? stackFrame.token : void 0) || getMatchingRequestToken(token, requestKey);
+          const { [DIRTY_DISPATCH_TOKEN]: _dirtyDispatchToken, ...cleanOptions } = options;
+          const configWithToken = activeToken ? { ...cleanOptions, [DIRTY_DISPATCH_TOKEN]: activeToken } : cleanOptions;
+          if (activeToken) {
+            activeToken.requestKey ||= requestKey;
+            requestTokenStack.push({ key: requestKey, token: activeToken });
+          }
+          try {
+            return Reflect.apply(getCurrentRequest(), proxy, [configWithToken]);
+          } finally {
+            if (activeToken) {
+              requestTokenStack.pop();
+            }
+          }
+        }, "value")
+      },
+      resource: {
+        configurable: true,
+        value: /* @__PURE__ */ __name((...args) => {
+          const resourceKey = getResourceDispatchKey(args[0], args[1], args[2]);
+          const stackFrame = resourceTokenStack.at(-1);
+          const activeToken = getMatchingResourceToken(token, resourceKey) || (resourceKey && (stackFrame == null ? void 0 : stackFrame.key) === resourceKey ? stackFrame.token : void 0);
+          return dispatchResource(activeToken, args);
+        }, "value")
+      }
+    });
+    return receiver;
+  }, "createDispatchReceiver");
   const resource = /* @__PURE__ */ __name((name, of, headers, cancel) => {
-    const targetResource = api.resource(name, of, headers, cancel);
-    return createDirtyAwareResource(context, targetResource, name, of, headers);
+    const resourceKey = getResourceDispatchKey(name, of, headers);
+    const stackFrame = resourceTokenStack.at(-1);
+    const parentToken = resourceKey && (stackFrame == null ? void 0 : stackFrame.key) === resourceKey ? stackFrame.token : void 0;
+    const receiver = createDispatchReceiver(parentToken);
+    const resourceInstance = Reflect.apply(baseResource, shouldUseResourceDispatchReceiver ? receiver : api, [
+      name,
+      of,
+      headers,
+      cancel
+    ]);
+    return createDirtyAwareResource(context, resourceInstance, name, of, headers, requestTokenStack, parentToken);
   }, "resource");
   const request = /* @__PURE__ */ __name((config) => {
     const options = config;
+    const requestKey = getRequestDispatchKey(options, context);
+    const stackFrame = requestTokenStack.at(-1);
+    const inheritedToken = getMatchingRequestToken(options == null ? void 0 : options[DIRTY_DISPATCH_TOKEN], requestKey) || (requestKey && (stackFrame == null ? void 0 : stackFrame.key) === requestKey ? stackFrame.token : void 0);
+    const token = inheritedToken || { marked: false, skip: false };
+    const ownsToken = !inheritedToken;
+    token.requestKey ||= requestKey;
+    if (typeof options.resource === "string") {
+      token.resourceKey ||= getResourceDispatchKey(options.resource, options.resourceOf, options.headers);
+    }
     const skipDataSourceDirty = options == null ? void 0 : options[SKIP_DATA_SOURCE_DIRTY];
-    const dirtyResourceAction = skipDataSourceDirty ? void 0 : resolveDirtyResourceAction(options, context);
-    const { [SKIP_DATA_SOURCE_DIRTY]: _skipDataSourceDirty, ...cleanConfig } = options;
-    return api.request(cleanConfig).then((result) => {
-      if (dirtyResourceAction && isMutatingResourceAction(dirtyResourceAction.actionName)) {
-        markResourceActionDataSourceDirty(context, dirtyResourceAction, options.headers);
+    if (skipDataSourceDirty) {
+      token.skip = true;
+    }
+    const dirtyResourceAction = resolveDirtyResourceAction(options, context);
+    const {
+      [DIRTY_DISPATCH_TOKEN]: _dirtyDispatchToken,
+      [SKIP_DATA_SOURCE_DIRTY]: _skipDataSourceDirty,
+      ...cleanConfig
+    } = options;
+    const receiver = createDispatchReceiver(token);
+    return Reflect.apply(baseRequest, shouldUseRequestDispatchReceiver ? receiver : api, [cleanConfig]).then((result) => {
+      if (ownsToken) {
+        markResourceActionDataSourceDirtyOnce(token, context, dirtyResourceAction, options.headers);
       }
       return result;
     });
   }, "request");
+  const isLockedOwnProperty = /* @__PURE__ */ __name((target, prop) => {
+    const descriptor = Reflect.getOwnPropertyDescriptor(target, prop);
+    return !!descriptor && !descriptor.configurable;
+  }, "isLockedOwnProperty");
   const proxy = new Proxy(api, {
     get(target, prop, receiver) {
       if (prop === "resource") {
-        return resource;
+        if (isLockedOwnProperty(target, prop)) {
+          return Reflect.get(target, prop, receiver);
+        }
+        return hasResourceOverride ? resourceOverride : resource;
       }
       if (prop === "request") {
-        return request;
+        if (isLockedOwnProperty(target, prop)) {
+          return Reflect.get(target, prop, receiver);
+        }
+        return hasRequestOverride ? requestOverride : request;
       }
       return Reflect.get(target, prop, receiver);
+    },
+    set(target, prop, value, receiver) {
+      if (prop === "resource") {
+        const descriptor = Reflect.getOwnPropertyDescriptor(target, prop);
+        if (descriptor && (!descriptor.configurable || !Reflect.isExtensible(target))) {
+          return false;
+        }
+        hasResourceOverride = true;
+        resourceOverride = value;
+        return true;
+      }
+      if (prop === "request") {
+        const descriptor = Reflect.getOwnPropertyDescriptor(target, prop);
+        if (descriptor && (!descriptor.configurable || !Reflect.isExtensible(target))) {
+          return false;
+        }
+        hasRequestOverride = true;
+        requestOverride = value;
+        return true;
+      }
+      return Reflect.set(target, prop, value, receiver);
+    },
+    deleteProperty(target, prop) {
+      if (prop !== "resource" && prop !== "request") {
+        return Reflect.deleteProperty(target, prop);
+      }
+      const descriptor = Reflect.getOwnPropertyDescriptor(target, prop);
+      if (descriptor && (!descriptor.configurable || !Reflect.isExtensible(target))) {
+        return false;
+      }
+      if (prop === "resource") {
+        hasResourceOverride = false;
+        resourceOverride = void 0;
+      } else {
+        hasRequestOverride = false;
+        requestOverride = void 0;
+      }
+      return true;
+    },
+    defineProperty(target, prop, descriptor) {
+      if (prop === "resource" || prop === "request") {
+        return false;
+      }
+      return Reflect.defineProperty(target, prop, descriptor);
     }
   });
   dirtyAwareApiClientProxies.add(proxy);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/flow-engine",
-  "version": "2.2.0-beta.10",
+  "version": "2.2.0-beta.11",
   "private": false,
   "description": "A standalone flow engine for NocoBase, managing workflows, models, and actions.",
   "main": "lib/index.js",
@@ -8,8 +8,8 @@
   "dependencies": {
     "@formily/antd-v5": "1.x",
     "@formily/reactive": "2.x",
-    "@nocobase/sdk": "2.2.0-beta.10",
-    "@nocobase/shared": "2.2.0-beta.10",
+    "@nocobase/sdk": "2.2.0-beta.11",
+    "@nocobase/shared": "2.2.0-beta.11",
     "ahooks": "^3.7.2",
     "axios": "^1.7.0",
     "dayjs": "^1.11.9",
@@ -37,5 +37,5 @@
   ],
   "author": "NocoBase Team",
   "license": "Apache-2.0",
-  "gitHead": "d572beec24de46df948f28db72b25303a63bf62d"
+  "gitHead": "8dab25af2bb83a81da68158d0dcf836f96103d61"
 }

package/src/utils/__tests__/dirtyAwareApiClient.test.ts

@@ -8,6 +8,7 @@
  */
 
 import { describe, expect, it, vi } from 'vitest';
+import { APIClient, type IResource, type RequestOptions } from '@nocobase/sdk';
 import { FlowContext } from '../../flowContext';
 import { FlowEngine } from '../../flowEngine';
 import { createViewScopedEngine } from '../../ViewScopedFlowEngine';
@@ -80,6 +81,326 @@ describe('dirtyAwareApiClient', () => {
     expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
   });
 
+  it('should keep request overrides local to the dirty-aware proxy', async () => {
+    const engine = new FlowEngine();
+    const request = vi.fn(async () => ({ data: { ok: true } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request,
+      resource: vi.fn(),
+    };
+    const originalRequest = api.request;
+    const wrappedApi = getWrappedApi(engine, api);
+    const delegatedRequest = wrappedApi.request.bind(wrappedApi);
+    const requestOverride = vi.fn((config: TestRequestOptions) => delegatedRequest(config));
+
+    wrappedApi.request = requestOverride;
+
+    await wrappedApi.request({ url: 'posts:list' });
+
+    expect(requestOverride).toHaveBeenCalledTimes(1);
+    expect(request).toHaveBeenCalledTimes(1);
+    expect(api.request).toBe(originalRequest);
+  });
+
+  it('should keep resource overrides local to the dirty-aware proxy', async () => {
+    const engine = new FlowEngine();
+    const update = vi.fn(async () => ({ data: { ok: true } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({ update })),
+    };
+    const originalResource = api.resource;
+    const wrappedApi = getWrappedApi(engine, api);
+    const delegatedResource = wrappedApi.resource.bind(wrappedApi);
+    const resourceOverride = vi.fn((...args: Parameters<TestApi['resource']>) => delegatedResource(...args));
+
+    wrappedApi.resource = resourceOverride;
+
+    await wrappedApi.resource('posts').update({ filterByTk: 1 });
+
+    expect(resourceOverride).toHaveBeenCalledTimes(1);
+    expect(update).toHaveBeenCalledTimes(1);
+    expect(api.resource).toBe(originalResource);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should route resource actions through the local request override without double-marking', async () => {
+    const engine = new FlowEngine();
+    const api = new APIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+    const delegatedRequest = wrappedApi.request.bind(wrappedApi);
+    const requestOverride = vi.fn((config: Parameters<APIClient['request']>[0]) => delegatedRequest(config));
+
+    wrappedApi.request = requestOverride as APIClient['request'];
+
+    await wrappedApi.resource('posts').update({ filterByTk: 1, values: { title: 'updated' } });
+
+    expect(requestOverride).toHaveBeenCalledTimes(1);
+    expect(transport).toHaveBeenCalledTimes(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should invoke custom request methods on the original api instance', async () => {
+    class StatefulRequestAPIClient extends APIClient {
+      #privateRequestCalls = 0;
+      publicRequestCalls = 0;
+
+      get privateRequestCalls() {
+        return this.#privateRequestCalls;
+      }
+
+      override request<T, R, D>(config: Parameters<APIClient['request']>[0]): Promise<R> {
+        this.#privateRequestCalls += 1;
+        this.publicRequestCalls += 1;
+        return super.request<T, R, D>(config);
+      }
+    }
+
+    const engine = new FlowEngine();
+    const api = new StatefulRequestAPIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+
+    await wrappedApi.resource('posts').update({ filterByTk: 1, values: { title: 'updated' } });
+
+    expect(transport).toHaveBeenCalledTimes(1);
+    expect(api.privateRequestCalls).toBe(1);
+    expect(api.publicRequestCalls).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should invoke custom resource methods on the original api instance', async () => {
+    class StatefulResourceAPIClient extends APIClient {
+      #privateResourceCalls = 0;
+      publicResourceCalls = 0;
+
+      get privateResourceCalls() {
+        return this.#privateResourceCalls;
+      }
+
+      override resource(...args: Parameters<APIClient['resource']>): IResource {
+        this.#privateResourceCalls += 1;
+        this.publicResourceCalls += 1;
+        return super.resource(...args);
+      }
+    }
+
+    const engine = new FlowEngine();
+    const api = new StatefulResourceAPIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+
+    await wrappedApi.request({
+      resource: 'posts',
+      action: 'update',
+      params: { filterByTk: 1, values: { title: 'updated' } },
+    });
+
+    expect(transport).toHaveBeenCalledTimes(1);
+    expect(api.privateResourceCalls).toBe(1);
+    expect(api.publicResourceCalls).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should keep one dirty mark when the request override rebuilds the config', async () => {
+    const engine = new FlowEngine();
+    const api = new APIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+    const delegatedRequest = wrappedApi.request.bind(wrappedApi);
+    const requestOverride = vi.fn((config: Parameters<APIClient['request']>[0]) => {
+      const { url, method, headers, params, data } = config as RequestOptions;
+      return delegatedRequest({ url, method, headers, params, data });
+    });
+
+    wrappedApi.request = requestOverride as APIClient['request'];
+
+    await wrappedApi.resource('posts').update({ filterByTk: 1, values: { title: 'updated' } });
+
+    expect(requestOverride).toHaveBeenCalledTimes(1);
+    expect(transport).toHaveBeenCalledTimes(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should keep nested mutations from a request override independent', async () => {
+    const engine = new FlowEngine();
+    const api = new APIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+    const delegatedRequest = wrappedApi.request.bind(wrappedApi);
+    const requestOverride = vi.fn(async (config: Parameters<APIClient['request']>[0]) => {
+      await delegatedRequest({ url: 'comments:create', method: 'post' });
+      return delegatedRequest(config);
+    });
+
+    wrappedApi.request = requestOverride as APIClient['request'];
+
+    await wrappedApi.resource('posts').update({ filterByTk: 1, values: { title: 'updated' } });
+
+    expect(requestOverride).toHaveBeenCalledTimes(1);
+    expect(transport).toHaveBeenCalledTimes(2);
+    expect(engine.getDataSourceDirtyVersion('main', 'comments')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should route structured requests through the local resource override without double-marking', async () => {
+    const engine = new FlowEngine();
+    const api = new APIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+    const delegatedResource = wrappedApi.resource.bind(wrappedApi);
+    const resourceOverride = vi.fn((...args: Parameters<APIClient['resource']>) => delegatedResource(...args));
+
+    wrappedApi.resource = resourceOverride;
+
+    await wrappedApi.request({
+      resource: 'posts',
+      action: 'update',
+      params: { filterByTk: 1, values: { title: 'updated' } },
+    });
+
+    expect(resourceOverride).toHaveBeenCalledTimes(1);
+    expect(transport).toHaveBeenCalledTimes(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should keep one dirty mark when the resource override delegates lazily', async () => {
+    const engine = new FlowEngine();
+    const api = new APIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+    const delegatedResource = wrappedApi.resource.bind(wrappedApi);
+    const resourceOverride = vi.fn(
+      (...args: Parameters<APIClient['resource']>): IResource => ({
+        update: async (...actionArgs: Parameters<IResource['update']>) => {
+          await Promise.resolve();
+          return delegatedResource(...args).update(...actionArgs);
+        },
+      }),
+    );
+
+    wrappedApi.resource = resourceOverride;
+
+    await wrappedApi.request({
+      resource: 'posts',
+      action: 'update',
+      params: { filterByTk: 1, values: { title: 'updated' } },
+    });
+
+    expect(resourceOverride).toHaveBeenCalledTimes(1);
+    expect(transport).toHaveBeenCalledTimes(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should keep nested mutations from a resource override independent', async () => {
+    const engine = new FlowEngine();
+    const api = new APIClient();
+    const transport = vi.spyOn(api.axios, 'request').mockResolvedValue({ data: { ok: true } });
+    const wrappedApi = getDirtyAwareApiClient(api, engine.context) as APIClient;
+    const delegatedResource = wrappedApi.resource.bind(wrappedApi);
+    let nestedMutation: Promise<unknown> | undefined;
+    const resourceOverride = vi.fn((...args: Parameters<APIClient['resource']>) => {
+      nestedMutation = delegatedResource('comments').create({ values: { body: 'nested' } });
+      return delegatedResource(...args);
+    });
+
+    wrappedApi.resource = resourceOverride;
+
+    await wrappedApi.request({
+      resource: 'posts',
+      action: 'update',
+      params: { filterByTk: 1, values: { title: 'updated' } },
+    });
+    await nestedMutation;
+
+    expect(resourceOverride).toHaveBeenCalledTimes(1);
+    expect(transport).toHaveBeenCalledTimes(2);
+    expect(engine.getDataSourceDirtyVersion('main', 'comments')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should clear local request and resource overrides when deleted', () => {
+    const engine = new FlowEngine();
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({})),
+    };
+    const wrappedApi = getWrappedApi(engine, api);
+    const defaultRequest = wrappedApi.request;
+    const defaultResource = wrappedApi.resource;
+
+    wrappedApi.request = vi.fn();
+    wrappedApi.resource = vi.fn();
+
+    expect(Reflect.deleteProperty(wrappedApi, 'request')).toBe(true);
+    expect(Reflect.deleteProperty(wrappedApi, 'resource')).toBe(true);
+    expect(wrappedApi.request).toBe(defaultRequest);
+    expect(wrappedApi.resource).toBe(defaultResource);
+  });
+
+  it('should reject request and resource descriptor overrides without mutating the raw api', () => {
+    const engine = new FlowEngine();
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({})),
+    };
+    const wrappedApi = getWrappedApi(engine, api);
+    const originalRequest = api.request;
+    const originalResource = api.resource;
+
+    expect(Reflect.defineProperty(wrappedApi, 'request', { value: vi.fn() })).toBe(false);
+    expect(Reflect.defineProperty(wrappedApi, 'resource', { value: vi.fn() })).toBe(false);
+    expect(() => Object.defineProperty(wrappedApi, 'request', { value: vi.fn() })).toThrow(TypeError);
+    expect(() => Object.defineProperty(wrappedApi, 'resource', { value: vi.fn() })).toThrow(TypeError);
+    expect(api.request).toBe(originalRequest);
+    expect(api.resource).toBe(originalResource);
+  });
+
+  it('should reject local overrides for own methods on a non-extensible raw api', () => {
+    const engine = new FlowEngine();
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({})),
+    };
+    const wrappedApi = getWrappedApi(engine, api);
+    const defaultMethods = {
+      request: wrappedApi.request,
+      resource: wrappedApi.resource,
+    };
+
+    Object.preventExtensions(api);
+
+    for (const methodName of ['request', 'resource'] as const) {
+      expect(Reflect.set(wrappedApi, methodName, vi.fn())).toBe(false);
+      expect(wrappedApi[methodName]).toBe(defaultMethods[methodName]);
+      expect(Reflect.deleteProperty(wrappedApi, methodName)).toBe(false);
+    }
+  });
+
+  it('should keep overrides isolated between flow contexts', () => {
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({})),
+    };
+    const firstContextApi = getDirtyAwareApiClient(api, new FlowContext()) as TestApi;
+    const secondContextApi = getDirtyAwareApiClient(api, new FlowContext()) as TestApi;
+    const secondRequest = secondContextApi.request;
+    const requestOverride = vi.fn();
+
+    firstContextApi.request = requestOverride;
+
+    expect(firstContextApi.request).toBe(requestOverride);
+    expect(secondContextApi.request).toBe(secondRequest);
+    expect(api.request).not.toBe(requestOverride);
+  });
+
   it('should not mark dirty for read actions', async () => {
     const nonMutatingActions = [
       'get',

package/src/utils/dirtyAwareApiClient.ts

@@ -7,13 +7,28 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import type { ActionParams, APIClient, IResource, RequestOptions } from '@nocobase/sdk';
+import { APIClient } from '@nocobase/sdk';
+import type { ActionParams, IResource, RequestOptions } from '@nocobase/sdk';
 import type { FlowContext } from '../flowContext';
 import { getDataSourceKeyFromHeaders, markDataSourceDirty } from './dataSourceDirty';
 
 type ResourceActionFn = (params?: ActionParams, opts?: unknown) => Promise<unknown>;
 
 export const SKIP_DATA_SOURCE_DIRTY = '__nocobaseSkipDataSourceDirty';
+// Carries one logical mutation through APIClient's request/resource cross-dispatch.
+const DIRTY_DISPATCH_TOKEN = Symbol('nocobaseDirtyDispatchToken');
+
+type DirtyDispatchToken = {
+  marked: boolean;
+  requestKey?: string;
+  resourceKey?: string;
+  skip: boolean;
+};
+
+type DirtyDispatchFrame = {
+  key?: string;
+  token: DirtyDispatchToken;
+};
 
 type ResourceRequestOptions = RequestOptions & {
   resource?: unknown;
@@ -21,6 +36,7 @@ type ResourceRequestOptions = RequestOptions & {
   action?: unknown;
   headers?: unknown;
   [SKIP_DATA_SOURCE_DIRTY]?: boolean;
+  [DIRTY_DISPATCH_TOKEN]?: DirtyDispatchToken;
 };
 
 type DirtyResourceAction = {
@@ -329,6 +345,53 @@ function resolveDirtyResourceAction(
   return parseDirtyResourceActionFromUrl(options?.url, context);
 }
 
+function getDirtyResourceActionDispatchKey(
+  dirtyResourceAction: DirtyResourceAction | undefined,
+  headers: unknown,
+): string | undefined {
+  if (!dirtyResourceAction) {
+    return undefined;
+  }
+  return JSON.stringify([
+    dirtyResourceAction.dataSourceKey || getDataSourceKeyFromHeaders(headers),
+    dirtyResourceAction.resourceName,
+    dirtyResourceAction.actionName,
+  ]);
+}
+
+function getRequestDispatchKey(options: ResourceRequestOptions, context: FlowContext): string | undefined {
+  return getDirtyResourceActionDispatchKey(resolveDirtyResourceAction(options, context), options.headers);
+}
+
+function getResourceDispatchKey(name: unknown, of: unknown, headers: unknown): string | undefined {
+  const resourceName = String(name ?? '').trim();
+  if (!resourceName) {
+    return undefined;
+  }
+  return JSON.stringify([resourceName, String(of ?? ''), getDataSourceKeyFromHeaders(headers)]);
+}
+
+function getMatchingRequestToken(
+  token: DirtyDispatchToken | undefined,
+  requestKey: string | undefined,
+): DirtyDispatchToken | undefined {
+  // A matching key prevents helper requests inside an override from sharing the outer mutation token.
+  if (!token || !requestKey || (token.requestKey && token.requestKey !== requestKey)) {
+    return undefined;
+  }
+  return token;
+}
+
+function getMatchingResourceToken(
+  token: DirtyDispatchToken | undefined,
+  resourceKey: string | undefined,
+): DirtyDispatchToken | undefined {
+  if (!token || !resourceKey || (token.resourceKey && token.resourceKey !== resourceKey)) {
+    return undefined;
+  }
+  return token;
+}
+
 function markResourceActionDataSourceDirty(
   context: FlowContext,
   dirtyResourceAction: DirtyResourceAction,
@@ -342,12 +405,31 @@ function markResourceActionDataSourceDirty(
   });
 }
 
+function markResourceActionDataSourceDirtyOnce(
+  token: DirtyDispatchToken,
+  context: FlowContext,
+  dirtyResourceAction: DirtyResourceAction | undefined,
+  headers: unknown,
+) {
+  if (token.skip || token.marked || !dirtyResourceAction || !isMutatingResourceAction(dirtyResourceAction.actionName)) {
+    return;
+  }
+  token.marked = true;
+  markResourceActionDataSourceDirty(context, dirtyResourceAction, headers);
+}
+
+function isObjectRecord(value: unknown): value is Record<PropertyKey, unknown> {
+  return !!value && typeof value === 'object';
+}
+
 function createDirtyAwareResource(
   context: FlowContext,
   resource: IResource,
   resourceName: string,
   resourceOf: unknown,
   headers: unknown,
+  requestTokenStack: DirtyDispatchFrame[],
+  parentToken?: DirtyDispatchToken,
 ): IResource {
   return new Proxy(resource, {
     get(target, prop, receiver) {
@@ -358,10 +440,42 @@ function createDirtyAwareResource(
 
       const action = original as ResourceActionFn;
       return async (...args: Parameters<ResourceActionFn>) => {
-        const result = await action(...args);
+        const actionOptions = isObjectRecord(args[1]) ? args[1] : undefined;
         const dirtyResourceAction = resolveDirtyResourceActionFromResource(resourceName, resourceOf, prop, context);
-        if (dirtyResourceAction) {
-          markResourceActionDataSourceDirty(context, dirtyResourceAction, headers);
+        const requestKey = getDirtyResourceActionDispatchKey(dirtyResourceAction, headers);
+        const resourceKey = getResourceDispatchKey(resourceName, resourceOf, headers);
+        const inheritedToken =
+          getMatchingRequestToken(
+            actionOptions?.[DIRTY_DISPATCH_TOKEN] as DirtyDispatchToken | undefined,
+            requestKey,
+          ) || getMatchingRequestToken(parentToken, requestKey);
+        const token = inheritedToken || { marked: false, skip: false };
+        const ownsToken = !inheritedToken;
+        token.requestKey ||= requestKey;
+        token.resourceKey ||= resourceKey;
+        if (actionOptions?.[SKIP_DATA_SOURCE_DIRTY]) {
+          token.skip = true;
+        }
+        const forwardedArgs: Parameters<ResourceActionFn> =
+          actionOptions || args[1] == null
+            ? [
+                args[0],
+                {
+                  ...actionOptions,
+                  [DIRTY_DISPATCH_TOKEN]: token,
+                },
+              ]
+            : args;
+        let actionResult: Promise<unknown>;
+        requestTokenStack.push({ key: requestKey, token });
+        try {
+          actionResult = Reflect.apply(action, receiver, forwardedArgs);
+        } finally {
+          requestTokenStack.pop();
+        }
+        const result = await actionResult;
+        if (ownsToken) {
+          markResourceActionDataSourceDirtyOnce(token, context, dirtyResourceAction, headers);
         }
         return result;
       };
@@ -370,34 +484,232 @@ function createDirtyAwareResource(
 }
 
 function createDirtyAwareApiClient(api: DirtyAwareAPIClient, context: FlowContext): APIClient {
+  const baseResource = api.resource;
+  const baseRequest = api.request;
+  // SDK methods use the dispatch receiver; custom methods keep the original instance for private fields and state.
+  const shouldUseResourceDispatchReceiver = baseResource === APIClient.prototype.resource;
+  const shouldUseRequestDispatchReceiver = baseRequest === APIClient.prototype.request;
+  // Stacks cover synchronous delegation; the symbol token survives async overrides that forward arguments.
+  const resourceTokenStack: DirtyDispatchFrame[] = [];
+  const requestTokenStack: DirtyDispatchFrame[] = [];
+  let hasResourceOverride = false;
+  let resourceOverride: unknown;
+  let hasRequestOverride = false;
+  let requestOverride: unknown;
+
+  const getCurrentResource = () => (hasResourceOverride ? resourceOverride : resource) as APIClient['resource'];
+  const getCurrentRequest = () => (hasRequestOverride ? requestOverride : request) as APIClient['request'];
+
+  const dispatchResource = (
+    token: DirtyDispatchToken | undefined,
+    args: Parameters<APIClient['resource']>,
+  ): IResource => {
+    const resourceKey = getResourceDispatchKey(args[0], args[1], args[2]);
+    const activeToken = getMatchingResourceToken(token, resourceKey);
+    const shouldWrapActions = !!activeToken && hasResourceOverride;
+    if (activeToken) {
+      activeToken.resourceKey ||= resourceKey;
+      resourceTokenStack.push({ key: resourceKey, token: activeToken });
+    }
+    try {
+      const resourceInstance = Reflect.apply(getCurrentResource(), proxy, args);
+      if (!shouldWrapActions || !activeToken) {
+        return resourceInstance;
+      }
+      return new Proxy(resourceInstance, {
+        get(target, prop, receiver) {
+          const original = Reflect.get(target, prop, receiver);
+          if (typeof prop !== 'string' || typeof original !== 'function' || !isMutatingResourceAction(prop)) {
+            return original;
+          }
+
+          const action = original as ResourceActionFn;
+          return (...actionArgs: Parameters<ResourceActionFn>) => {
+            const actionOptions = isObjectRecord(actionArgs[1]) ? actionArgs[1] : undefined;
+            const forwardedArgs: Parameters<ResourceActionFn> =
+              actionOptions || actionArgs[1] == null
+                ? [
+                    actionArgs[0],
+                    {
+                      ...actionOptions,
+                      [DIRTY_DISPATCH_TOKEN]: activeToken,
+                    },
+                  ]
+                : actionArgs;
+            resourceTokenStack.push({ key: resourceKey, token: activeToken });
+            requestTokenStack.push({ key: activeToken.requestKey, token: activeToken });
+            try {
+              return Reflect.apply(action, receiver, forwardedArgs);
+            } finally {
+              requestTokenStack.pop();
+              resourceTokenStack.pop();
+            }
+          };
+        },
+      });
+    } finally {
+      if (activeToken) {
+        resourceTokenStack.pop();
+      }
+    }
+  };
+
+  const createDispatchReceiver = (token?: DirtyDispatchToken): DirtyAwareAPIClient => {
+    const receiver = Object.create(api) as DirtyAwareAPIClient;
+    Object.defineProperties(receiver, {
+      request: {
+        configurable: true,
+        value: (<T, R, D>(config: APIClientRequestConfig): Promise<R> => {
+          const options = config as ResourceRequestOptions;
+          const requestKey = getRequestDispatchKey(options, context);
+          const stackFrame = requestTokenStack.at(-1);
+          const activeToken =
+            getMatchingRequestToken(options?.[DIRTY_DISPATCH_TOKEN], requestKey) ||
+            (requestKey && stackFrame?.key === requestKey ? stackFrame.token : undefined) ||
+            getMatchingRequestToken(token, requestKey);
+          const { [DIRTY_DISPATCH_TOKEN]: _dirtyDispatchToken, ...cleanOptions } = options;
+          const configWithToken = activeToken ? { ...cleanOptions, [DIRTY_DISPATCH_TOKEN]: activeToken } : cleanOptions;
+          if (activeToken) {
+            activeToken.requestKey ||= requestKey;
+            requestTokenStack.push({ key: requestKey, token: activeToken });
+          }
+          try {
+            return Reflect.apply(getCurrentRequest(), proxy, [configWithToken]) as Promise<R>;
+          } finally {
+            if (activeToken) {
+              requestTokenStack.pop();
+            }
+          }
+        }) as APIClient['request'],
+      },
+      resource: {
+        configurable: true,
+        value: ((...args: Parameters<APIClient['resource']>) => {
+          const resourceKey = getResourceDispatchKey(args[0], args[1], args[2]);
+          const stackFrame = resourceTokenStack.at(-1);
+          const activeToken =
+            getMatchingResourceToken(token, resourceKey) ||
+            (resourceKey && stackFrame?.key === resourceKey ? stackFrame.token : undefined);
+          return dispatchResource(activeToken, args);
+        }) as APIClient['resource'],
+      },
+    });
+    return receiver;
+  };
+
   const resource: APIClient['resource'] = (name, of, headers, cancel) => {
-    const targetResource = api.resource(name, of, headers, cancel);
-    return createDirtyAwareResource(context, targetResource, name, of, headers);
+    const resourceKey = getResourceDispatchKey(name, of, headers);
+    const stackFrame = resourceTokenStack.at(-1);
+    const parentToken = resourceKey && stackFrame?.key === resourceKey ? stackFrame.token : undefined;
+    const receiver = createDispatchReceiver(parentToken);
+    const resourceInstance = Reflect.apply(baseResource, shouldUseResourceDispatchReceiver ? receiver : api, [
+      name,
+      of,
+      headers,
+      cancel,
+    ]);
+    return createDirtyAwareResource(context, resourceInstance, name, of, headers, requestTokenStack, parentToken);
   };
 
   const request = (<T, R, D>(config: APIClientRequestConfig): Promise<R> => {
     const options = config as ResourceRequestOptions;
+    const requestKey = getRequestDispatchKey(options, context);
+    const stackFrame = requestTokenStack.at(-1);
+    const inheritedToken =
+      getMatchingRequestToken(options?.[DIRTY_DISPATCH_TOKEN], requestKey) ||
+      (requestKey && stackFrame?.key === requestKey ? stackFrame.token : undefined);
+    const token = inheritedToken || { marked: false, skip: false };
+    const ownsToken = !inheritedToken;
+    token.requestKey ||= requestKey;
+    if (typeof options.resource === 'string') {
+      token.resourceKey ||= getResourceDispatchKey(options.resource, options.resourceOf, options.headers);
+    }
     const skipDataSourceDirty = options?.[SKIP_DATA_SOURCE_DIRTY];
-    const dirtyResourceAction = skipDataSourceDirty ? undefined : resolveDirtyResourceAction(options, context);
-    const { [SKIP_DATA_SOURCE_DIRTY]: _skipDataSourceDirty, ...cleanConfig } = options;
-    return api.request<T, R, D>(cleanConfig as typeof config).then((result) => {
-      if (dirtyResourceAction && isMutatingResourceAction(dirtyResourceAction.actionName)) {
-        markResourceActionDataSourceDirty(context, dirtyResourceAction, options.headers);
+    if (skipDataSourceDirty) {
+      token.skip = true;
+    }
+    const dirtyResourceAction = resolveDirtyResourceAction(options, context);
+    const {
+      [DIRTY_DISPATCH_TOKEN]: _dirtyDispatchToken,
+      [SKIP_DATA_SOURCE_DIRTY]: _skipDataSourceDirty,
+      ...cleanConfig
+    } = options;
+    const receiver = createDispatchReceiver(token);
+    return (
+      Reflect.apply(baseRequest, shouldUseRequestDispatchReceiver ? receiver : api, [cleanConfig]) as Promise<R>
+    ).then((result) => {
+      if (ownsToken) {
+        markResourceActionDataSourceDirtyOnce(token, context, dirtyResourceAction, options.headers);
       }
       return result;
     });
   }) as APIClient['request'];
 
+  const isLockedOwnProperty = (target: DirtyAwareAPIClient, prop: PropertyKey) => {
+    const descriptor = Reflect.getOwnPropertyDescriptor(target, prop);
+    return !!descriptor && !descriptor.configurable;
+  };
+
   const proxy = new Proxy(api, {
     get(target, prop, receiver) {
       if (prop === 'resource') {
-        return resource;
+        if (isLockedOwnProperty(target, prop)) {
+          return Reflect.get(target, prop, receiver);
+        }
+        return hasResourceOverride ? resourceOverride : resource;
       }
       if (prop === 'request') {
-        return request;
+        if (isLockedOwnProperty(target, prop)) {
+          return Reflect.get(target, prop, receiver);
+        }
+        return hasRequestOverride ? requestOverride : request;
       }
       return Reflect.get(target, prop, receiver);
     },
+    set(target, prop, value, receiver) {
+      if (prop === 'resource') {
+        const descriptor = Reflect.getOwnPropertyDescriptor(target, prop);
+        if (descriptor && (!descriptor.configurable || !Reflect.isExtensible(target))) {
+          return false;
+        }
+        hasResourceOverride = true;
+        resourceOverride = value;
+        return true;
+      }
+      if (prop === 'request') {
+        const descriptor = Reflect.getOwnPropertyDescriptor(target, prop);
+        if (descriptor && (!descriptor.configurable || !Reflect.isExtensible(target))) {
+          return false;
+        }
+        hasRequestOverride = true;
+        requestOverride = value;
+        return true;
+      }
+      return Reflect.set(target, prop, value, receiver);
+    },
+    deleteProperty(target, prop) {
+      if (prop !== 'resource' && prop !== 'request') {
+        return Reflect.deleteProperty(target, prop);
+      }
+      const descriptor = Reflect.getOwnPropertyDescriptor(target, prop);
+      if (descriptor && (!descriptor.configurable || !Reflect.isExtensible(target))) {
+        return false;
+      }
+      if (prop === 'resource') {
+        hasResourceOverride = false;
+        resourceOverride = undefined;
+      } else {
+        hasRequestOverride = false;
+        requestOverride = undefined;
+      }
+      return true;
+    },
+    defineProperty(target, prop, descriptor) {
+      if (prop === 'resource' || prop === 'request') {
+        return false;
+      }
+      return Reflect.defineProperty(target, prop, descriptor);
+    },
   }) as APIClient;
   dirtyAwareApiClientProxies.add(proxy);
   return proxy;