@nocobase/flow-engine 2.2.0-beta.6 → 2.2.0-beta.8

package/src/flowContext.ts

@@ -9,7 +9,7 @@
 
 import { ISchema } from '@formily/json-schema';
 import { observable } from '@formily/reactive';
-import { APIClient, RequestOptions } from '@nocobase/sdk';
+import type { APIClient, RequestOptions } from '@nocobase/sdk';
 import type { Router } from '@remix-run/router';
 import axios from 'axios';
 import { MessageInstance } from 'antd/es/message/interface';
@@ -39,9 +39,11 @@ import {
   extractUsedVariablePaths,
   FlowExitException,
   FLOW_ENGINE_NAMESPACE,
+  createOpenViewRouteState,
   isCtxDatePathPrefix,
   isCssFile,
   prepareRunJsCode,
+  RUNJS_OPEN_VIEW_ROUTE_STATE,
   resolveCtxDatePath,
   resolveDefaultParams,
   resolveExpressions,
@@ -51,6 +53,7 @@ import { FlowExitAllException } from './utils/exceptions';
 import { enqueueVariablesResolve, JSONValue } from './utils/params-resolvers';
 import type { RecordRef } from './utils/serverContextParams';
 import { buildServerContextParams as _buildServerContextParams } from './utils/serverContextParams';
+import { getDirtyAwareApiClient } from './utils/dirtyAwareApiClient';
 import { inferRecordRef } from './utils/variablesParams';
 import { FlowView, FlowViewer } from './views/FlowView';
 import { RunJSContextRegistry, getModelClassName, type RunJSVersion } from './runjs-context/registry';
@@ -2909,19 +2912,20 @@ export class FlowContext {
 
     // 静态值
     if ('value' in options) {
-      return options.value;
+      return key === 'api' ? getDirtyAwareApiClient(options.value, currentContext) : options.value;
     }
 
     // get 方法
     if (options.get) {
       if (options.cache === false) {
-        return options.get(currentContext);
+        const value = options.get(currentContext);
+        return key === 'api' ? getDirtyAwareApiClient(value, currentContext) : value;
       }
 
       const cacheKey = options.observable ? '_observableCache' : '_cache';
 
       if (key in this[cacheKey]) {
-        return this[cacheKey][key];
+        return key === 'api' ? getDirtyAwareApiClient(this[cacheKey][key], currentContext) : this[cacheKey][key];
       }
 
       if (this._pending[key]) return this._pending[key];
@@ -2939,7 +2943,7 @@ export class FlowContext {
           (v) => {
             this[cacheKey][key] = v;
             delete this._pending[key];
-            return v;
+            return key === 'api' ? getDirtyAwareApiClient(v, currentContext) : v;
           },
           (err) => {
             delete this._pending[key];
@@ -2951,7 +2955,7 @@ export class FlowContext {
 
       // sync 直接缓存
       this[cacheKey][key] = result;
-      return result;
+      return key === 'api' ? getDirtyAwareApiClient(result, currentContext) : result;
     }
 
     return undefined;
@@ -3074,7 +3078,7 @@ class BaseFlowEngineContext extends FlowContext {
     this.defineMethod('getModel', (modelName: string, searchInPreviousEngines?: boolean) => {
       return this.engine.getModel(modelName, searchInPreviousEngines);
     });
-    this.defineMethod('request', (options: RequestOptions) => {
+    this.defineMethod('request', function (this: FlowContext, options: RequestOptions) {
       const app = this.app as { getApiUrl?: (pathname?: string) => string } | undefined;
       if (typeof options?.url === 'string' && shouldBypassApiClient(options.url, app)) {
         return axios.request(options);
@@ -3429,7 +3433,19 @@ export class FlowEngineContext extends BaseFlowEngineContext {
       }),
     });
     this.defineProperty('role', {
-      get: () => this.api?.auth?.role,
+      get: () => {
+        const currentRole = this.api?.auth?.role;
+        if (currentRole !== '__union__') {
+          return currentRole;
+        }
+        const roles = this.user?.roles;
+        if (!Array.isArray(roles)) {
+          return [];
+        }
+        return roles
+          .map((role: { name?: string }) => role?.name)
+          .filter((name: string | undefined): name is string => !!name);
+      },
       cache: false,
       // 注意：使用惰性 meta 工厂，避免在 i18n 尚未注入时提前求值导致无法翻译
       meta: Object.assign(() => ({ type: 'string', title: this.t('Current role'), sort: 990 }), {
@@ -4588,6 +4604,27 @@ export class FlowRunJSContext extends FlowContext {
     this.defineProperty('ReactDOM', { value: ReactDOMShim });
 
     setupRunJSLibs(this);
+    this.defineMethod('openView', async function (uid: string, options?: Record<PropertyKey, unknown>) {
+      const delegateOpenView = (
+        delegate as FlowContext & {
+          openView?: (uid: string, options?: Record<PropertyKey, unknown>) => Promise<unknown>;
+        }
+      ).openView;
+
+      if (typeof delegateOpenView !== 'function') {
+        throw new Error('ctx.openView is not available in current context.');
+      }
+
+      const routeState = createOpenViewRouteState(options);
+      if (!routeState) {
+        return delegateOpenView(uid, options);
+      }
+
+      return delegateOpenView(uid, {
+        ...(options || {}),
+        [RUNJS_OPEN_VIEW_ROUTE_STATE]: routeState,
+      });
+    });
 
     // Convenience: ctx.render(<App />[, container])
     // - container defaults to ctx.element if available

package/src/locale/en-US.json

@@ -56,6 +56,7 @@
   "Replace current block with template?": "Replace current block with template?",
   "Replaced with template block": "Replaced with template block",
   "Render failed": "Render failed",
+  "Response record": "Response record",
   "Step configuration": "Step configuration",
   "Step parameter configuration": "Step parameter configuration",
   "Step with key {{stepKey}} not found": "Step with key {{stepKey}} not found",

package/src/locale/zh-CN.json

@@ -60,6 +60,7 @@
   "Other blocks": "其他区块",
   "Previous step": "上一步",
   "Render failed": "渲染失败",
+  "Response record": "响应结果记录",
   "Step configuration": "步骤配置",
   "Step parameter configuration": "步骤参数配置",
   "Step with key {{stepKey}} not found": "未找到key为 {{stepKey}} 的步骤",

package/src/resources/apiResource.ts

@@ -9,6 +9,7 @@
 
 import { APIClient } from '@nocobase/sdk';
 import { FlowContext } from '../flowContext';
+import { getDirtyAwareApiClient } from '../utils/dirtyAwareApiClient';
 import { FlowResource, ResourceError } from './flowResource';
 
 export class APIResource<TData = any> extends FlowResource<TData> {
@@ -33,7 +34,7 @@ export class APIResource<TData = any> extends FlowResource<TData> {
   }
 
   setAPIClient(api: APIClient) {
-    this.api = api;
+    this.api = getDirtyAwareApiClient(api, this.context) as APIClient;
     return this;
   }
 

package/src/resources/baseRecordResource.ts

@@ -12,7 +12,7 @@ import _ from 'lodash';
 import { APIResource } from './apiResource';
 import { FilterItem } from './filterItem';
 import { ResourceError } from './flowResource';
-import { DATA_SOURCE_DIRTY_EVENT } from '../views/viewEvents';
+import { markDataSourceDirty } from '../utils/dataSourceDirty';
 
 export abstract class BaseRecordResource<TData = any> extends APIResource<TData> {
   protected resourceName: string;
@@ -142,28 +142,11 @@ export abstract class BaseRecordResource<TData = any> extends APIResource<TData>
    * Used to coordinate "refresh on active" across view stacks.
    */
   protected markDataSourceDirty(resourceName?: string) {
-    const engine = this.context.engine;
-    if (!engine) return;
-
-    const dataSourceKey = this.getDataSourceKey() || 'main';
-    const resName = resourceName || this.getResourceName();
-    if (!resName) return;
-
-    const affectedResourceNames = new Set<string>([String(resName)]);
-    // Optional safety: association resources like "users.profile" may impact parent collection views.
-    if (typeof resName === 'string' && resName.includes('.')) {
-      affectedResourceNames.add(resName.split('.')[0]);
-    }
-
-    for (const name of affectedResourceNames) {
-      engine.markDataSourceDirty(dataSourceKey, name);
-    }
-
-    // Signal current view to re-evaluate dirty blocks (e.g., same-view sibling refresh).
-    // This is emitted on the *current* engine emitter (view-scoped) so it won't affect other views.
-    engine.emitter?.emit?.(DATA_SOURCE_DIRTY_EVENT, {
-      dataSourceKey,
-      resourceNames: Array.from(affectedResourceNames),
+    markDataSourceDirty({
+      engine: this.context.engine,
+      dataSourceKey: this.getDataSourceKey(),
+      resourceName: resourceName || this.getResourceName(),
+      includePreviousEngines: true,
     });
   }
 

package/src/resources/multiRecordResource.ts

@@ -10,6 +10,7 @@
 import { observable } from '@formily/reactive';
 import { AxiosRequestConfig } from 'axios';
 import _ from 'lodash';
+import { SKIP_DATA_SOURCE_DIRTY } from '../utils/dirtyAwareApiClient';
 import { BaseRecordResource } from './baseRecordResource';
 
 export class MultiRecordResource<TDataItem = any> extends BaseRecordResource<TDataItem[]> {
@@ -113,7 +114,10 @@ export class MultiRecordResource<TDataItem = any> extends BaseRecordResource<TDa
 
   async create(data: TDataItem, options?: AxiosRequestConfig & { refresh?: boolean }): Promise<void> {
     const config = this.mergeRequestConfig({ data }, this.createActionOptions, options);
-    const res = await this.runAction('create', config);
+    const res = await this.runAction('create', {
+      ...config,
+      [SKIP_DATA_SOURCE_DIRTY]: true,
+    });
     this.markDataSourceDirty();
     this.emit('saved', data);
     if (options?.refresh !== false) {
@@ -146,7 +150,10 @@ export class MultiRecordResource<TDataItem = any> extends BaseRecordResource<TDa
       this.updateActionOptions,
       options,
     );
-    await this.runAction('update', config);
+    await this.runAction('update', {
+      ...config,
+      [SKIP_DATA_SOURCE_DIRTY]: true,
+    });
     this.markDataSourceDirty();
     this.emit('saved', data);
     await this.refresh();
@@ -172,7 +179,10 @@ export class MultiRecordResource<TDataItem = any> extends BaseRecordResource<TDa
       },
       options,
     );
-    await this.runAction('destroy', config);
+    await this.runAction('destroy', {
+      ...config,
+      [SKIP_DATA_SOURCE_DIRTY]: true,
+    });
     this.markDataSourceDirty();
     const currentPage = this.getPage();
     const lastPage = Math.ceil((this.getCount() - _.castArray(filterByTk).length) / this.getPageSize());

package/src/resources/singleRecordResource.ts

@@ -9,6 +9,7 @@
 
 import { AxiosRequestConfig } from 'axios';
 import _ from 'lodash';
+import { SKIP_DATA_SOURCE_DIRTY } from '../utils/dirtyAwareApiClient';
 import { BaseRecordResource } from './baseRecordResource';
 
 export class SingleRecordResource<TData = any> extends BaseRecordResource<TData> {
@@ -43,6 +44,7 @@ export class SingleRecordResource<TData = any> extends BaseRecordResource<TData>
     const res = await this.runAction(actionName, {
       ...config,
       data: result,
+      [SKIP_DATA_SOURCE_DIRTY]: true,
     });
     // Mark as dirty before emitting/refreshing so other views can refresh when activated.
     this.markDataSourceDirty();
@@ -62,7 +64,10 @@ export class SingleRecordResource<TData = any> extends BaseRecordResource<TData>
       },
       options,
     );
-    await this.runAction('destroy', config);
+    await this.runAction('destroy', {
+      ...config,
+      [SKIP_DATA_SOURCE_DIRTY]: true,
+    });
     this.markDataSourceDirty();
     this.setData(null);
   }

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

@@ -0,0 +1,392 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { FlowContext } from '../../flowContext';
+import { FlowEngine } from '../../flowEngine';
+import { createViewScopedEngine } from '../../ViewScopedFlowEngine';
+import { DATA_SOURCE_DIRTY_EVENT } from '../../views/viewEvents';
+import { getDirtyAwareApiClient, SKIP_DATA_SOURCE_DIRTY } from '../dirtyAwareApiClient';
+
+type TestRequestOptions = {
+  url?: string;
+  resource?: string;
+  action?: string;
+  headers?: Record<string, string>;
+  params?: unknown;
+};
+
+type TestResource = Record<string, (...args: unknown[]) => Promise<unknown>>;
+
+type TestApi = {
+  auth: { locale: string };
+  request: (config: TestRequestOptions) => Promise<unknown>;
+  resource: (name: string, of?: unknown, headers?: Record<string, string>, cancel?: boolean) => TestResource;
+};
+
+function getWrappedApi(engine: FlowEngine, api: TestApi): TestApi {
+  return getDirtyAwareApiClient(api, engine.context) as TestApi;
+}
+
+describe('dirtyAwareApiClient', () => {
+  it('should return non-api values as-is', () => {
+    const context = new FlowContext();
+    const value = { request: vi.fn() };
+
+    expect(getDirtyAwareApiClient(value, context)).toBe(value);
+  });
+
+  it('should mark the resource dirty after mutating resource actions succeed', async () => {
+    const engine = new FlowEngine();
+    const list = vi.fn(async () => ({ data: { data: [] } }));
+    const update = vi.fn(async () => ({ data: { data: { id: 1 } } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({ list, update })),
+    };
+    const wrappedApi = getWrappedApi(engine, api);
+
+    await wrappedApi.resource('posts').list();
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(0);
+
+    await wrappedApi.resource('posts').update({ filterByTk: 1, values: { title: 't' } });
+
+    expect(update).toHaveBeenCalledTimes(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+    expect(getDirtyAwareApiClient(api, engine.context)).toBe(wrappedApi);
+  });
+
+  it('should not double-wrap an already dirty-aware api', async () => {
+    const engine = new FlowEngine();
+    const update = vi.fn(async () => ({ data: { data: { id: 1 } } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({ update })),
+    };
+
+    const wrappedApi = getWrappedApi(engine, api);
+    const wrappedAgain = getDirtyAwareApiClient(wrappedApi, engine.context) as TestApi;
+    await wrappedAgain.resource('posts').update({ filterByTk: 1 });
+
+    expect(wrappedAgain).toBe(wrappedApi);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should not mark dirty for read actions', async () => {
+    const nonMutatingActions = [
+      'get',
+      'getSystemSettings',
+      'list',
+      'listByUser',
+      'query',
+      'count',
+      'check',
+      'preview',
+      'test',
+      'find',
+      'exists',
+      'aggregate',
+      'listMine',
+      'parents',
+      'children',
+      'search',
+      'send',
+      'testConnection',
+      'refresh',
+      'run',
+      'runById',
+      'unknownCustomAction',
+    ];
+
+    for (const actionName of nonMutatingActions) {
+      const engine = new FlowEngine();
+      const api: TestApi = {
+        auth: { locale: 'zh-CN' },
+        request: vi.fn(async () => ({ data: { ok: true } })),
+        resource: vi.fn(() => ({
+          [actionName]: vi.fn(async () => ({ data: { data: [] } })),
+        })),
+      };
+
+      await getWrappedApi(engine, api).resource('posts')[actionName]();
+
+      expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(0);
+    }
+  });
+
+  it('should mark dirty for known mutating action variants', async () => {
+    const mutatingActions = [
+      'create',
+      'execute',
+      'updateOrCreate',
+      'firstOrCreate',
+      'setFields',
+      'updateProfile',
+      'saveAsTemplate',
+      'remove/abc',
+    ];
+
+    for (const actionName of mutatingActions) {
+      const engine = new FlowEngine();
+      const api: TestApi = {
+        auth: { locale: 'zh-CN' },
+        request: vi.fn(async () => ({ data: { ok: true } })),
+        resource: vi.fn(() => ({
+          [actionName]: vi.fn(async () => ({ data: { ok: true } })),
+        })),
+      };
+
+      await getWrappedApi(engine, api).resource('posts')[actionName]();
+
+      expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+    }
+  });
+
+  it('should not mark dirty when a mutating action fails', async () => {
+    const engine = new FlowEngine();
+    const update = vi.fn(async () => {
+      throw new Error('update failed');
+    });
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({ update })),
+    };
+
+    await expect(getWrappedApi(engine, api).resource('posts').update({ filterByTk: 1 })).rejects.toThrow(
+      'update failed',
+    );
+
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(0);
+  });
+
+  it('should mark association resource and parent collection dirty', async () => {
+    const engine = new FlowEngine();
+    const dirtyEvents: Array<{ dataSourceKey: string; resourceNames: string[] }> = [];
+    engine.emitter.on(DATA_SOURCE_DIRTY_EVENT, (event) => dirtyEvents.push(event));
+    const add = vi.fn(async () => ({ data: { data: null } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({ add })),
+    };
+
+    await getWrappedApi(engine, api)
+      .resource('users.roles', 1, { 'x-data-source': 'external' })
+      .add({ values: [1, 2] });
+
+    expect(engine.getDataSourceDirtyVersion('external', 'users.roles')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('external', 'users')).toBe(1);
+    expect(dirtyEvents).toEqual([{ dataSourceKey: 'external', resourceNames: ['users.roles', 'users'] }]);
+  });
+
+  it('should mark resource-action request mutations dirty after success', async () => {
+    const engine = new FlowEngine();
+    const request = vi.fn(async () => ({ data: { ok: true } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request,
+      resource: vi.fn(),
+    };
+
+    await getWrappedApi(engine, api).request({
+      resource: 'posts',
+      action: 'update',
+      headers: { 'X-Data-Source': 'analytics' },
+      params: { filterByTk: 1 },
+    });
+
+    expect(request).toHaveBeenCalledTimes(1);
+    expect(engine.getDataSourceDirtyVersion('analytics', 'posts')).toBe(1);
+  });
+
+  it('should mark URL-form resource mutations dirty after success', 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 wrappedApi = getWrappedApi(engine, api);
+
+    await wrappedApi.request({ url: 'posts:update' });
+    await wrappedApi.request({
+      url: '/api/posts:update?filterByTk=1',
+      headers: { 'x-data-source': 'external' },
+    });
+    await wrappedApi.request({
+      url: '/api/posts/1/tags:set',
+      headers: { 'X-Data-Source': 'analytics' },
+    });
+
+    expect(request).toHaveBeenCalledTimes(3);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('external', 'posts')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('analytics', 'posts.tags')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('analytics', 'posts')).toBe(1);
+  });
+
+  it('should resolve data source resource URLs to the nested data source target', async () => {
+    const engine = new FlowEngine();
+    const request = vi.fn(async () => ({ data: { ok: true } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request,
+      resource: vi.fn(),
+    };
+
+    await getWrappedApi(engine, api).request({
+      url: 'dataSources/external/collections:update',
+    });
+
+    expect(request).toHaveBeenCalledTimes(1);
+    expect(engine.getDataSourceDirtyVersion('external', 'collections')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'dataSources.collections')).toBe(0);
+    expect(engine.getDataSourceDirtyVersion('main', 'dataSources')).toBe(0);
+  });
+
+  it('should resolve dataSources resourceOf requests to the nested data source target', async () => {
+    const engine = new FlowEngine();
+    const request = vi.fn(async () => ({ data: { ok: true } }));
+    const update = vi.fn(async () => ({ data: { ok: true } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request,
+      resource: vi.fn(() => ({ update })),
+    };
+    const wrappedApi = getWrappedApi(engine, api);
+
+    await wrappedApi.request({
+      resource: 'dataSources.collections',
+      resourceOf: 'external',
+      action: 'update',
+    } as TestRequestOptions & { resourceOf: string });
+    await wrappedApi.resource('dataSources.roles', 'external').update({ values: { allow: true } });
+    await wrappedApi.resource('dataSources/external/roles').update({ values: { allow: false } });
+
+    expect(engine.getDataSourceDirtyVersion('external', 'collections')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('external', 'roles')).toBe(2);
+    expect(engine.getDataSourceDirtyVersion('main', 'dataSources.collections')).toBe(0);
+    expect(engine.getDataSourceDirtyVersion('main', 'dataSources.roles')).toBe(0);
+  });
+
+  it('should skip dirty marking and strip the internal skip flag from raw requests', async () => {
+    const engine = new FlowEngine();
+    const request = vi.fn(async () => ({ data: { ok: true } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request,
+      resource: vi.fn(),
+    };
+
+    await getWrappedApi(engine, api).request({
+      url: 'posts:update',
+      [SKIP_DATA_SOURCE_DIRTY]: true,
+    } as TestRequestOptions & { [SKIP_DATA_SOURCE_DIRTY]: boolean });
+
+    expect(request).toHaveBeenCalledTimes(1);
+    expect(request.mock.calls[0][0]).not.toHaveProperty(SKIP_DATA_SOURCE_DIRTY);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(0);
+  });
+
+  it('should strip configured API base from URL-form mutations', async () => {
+    const engine = new FlowEngine();
+    const request = vi.fn(async () => ({ data: { ok: true } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request,
+      resource: vi.fn(),
+    };
+    engine.context.defineProperty('app', {
+      value: {
+        getApiUrl(pathname = '') {
+          return `https://app.example.com/foo/api/${pathname.replace(/^\//, '')}`;
+        },
+      },
+    });
+    const wrappedApi = getWrappedApi(engine, api);
+
+    await wrappedApi.request({ url: '/foo/api/posts:update' });
+    await wrappedApi.request({
+      url: 'https://app.example.com/foo/api/users/1/roles:set',
+      headers: { 'x-data-source': 'external' },
+    });
+
+    expect(request).toHaveBeenCalledTimes(2);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('main', 'foo.api.posts')).toBe(0);
+    expect(engine.getDataSourceDirtyVersion('external', 'users.roles')).toBe(1);
+    expect(engine.getDataSourceDirtyVersion('external', 'users')).toBe(1);
+  });
+
+  it('should not mark URL-form resource dirty for reads, failed mutations, or external URLs', async () => {
+    const engine = new FlowEngine();
+    const request = vi
+      .fn()
+      .mockResolvedValueOnce({ data: { data: [] } })
+      .mockResolvedValueOnce({ data: { data: [] } })
+      .mockRejectedValueOnce(new Error('request failed'))
+      .mockResolvedValueOnce({ data: { ok: true } })
+      .mockResolvedValueOnce({ data: { ok: true } });
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request,
+      resource: vi.fn(),
+    };
+    const wrappedApi = getWrappedApi(engine, api);
+
+    await wrappedApi.request({ url: 'posts:list' });
+    await wrappedApi.request({ url: '/api/posts:parents' });
+    await expect(wrappedApi.request({ url: '/api/posts:update' })).rejects.toThrow('request failed');
+    await wrappedApi.request({ url: 'https://example.com/api/posts:update' });
+    await wrappedApi.request({ url: '//example.com/api/posts:update' });
+
+    expect(request).toHaveBeenCalledTimes(5);
+    expect(engine.getDataSourceDirtyVersion('main', 'posts')).toBe(0);
+  });
+
+  it('should mark opener engine dirty when called from a scoped view context', async () => {
+    const root = new FlowEngine();
+    const scoped = createViewScopedEngine(root);
+    const update = vi.fn(async () => ({ data: { data: { id: 1 } } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({ update })),
+    };
+
+    await getWrappedApi(scoped, api)
+      .resource('posts')
+      .update({ filterByTk: 1, values: { title: 't' } });
+
+    expect(root.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+    expect(scoped.context.engine.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+
+  it('should not double-mark when the context exposes a scoped engine proxy', async () => {
+    const root = new FlowEngine();
+    const scoped = createViewScopedEngine(root);
+    const context = new FlowContext();
+    const update = vi.fn(async () => ({ data: { data: { id: 1 } } }));
+    const api: TestApi = {
+      auth: { locale: 'zh-CN' },
+      request: vi.fn(async () => ({ data: { ok: true } })),
+      resource: vi.fn(() => ({ update })),
+    };
+    context.defineProperty('engine', { value: scoped });
+
+    await (getDirtyAwareApiClient(api, context) as TestApi).resource('posts').update({ filterByTk: 1 });
+
+    expect(root.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+    expect(scoped.getDataSourceDirtyVersion('main', 'posts')).toBe(1);
+  });
+});