@svadmin/core 0.34.2 → 0.36.0

package/src/provider-bundle.ts

@@ -0,0 +1,183 @@
+import type {
+  AgentProvider,
+  ChatProvider,
+} from './chatProvider.svelte';
+import type { AuditLogProvider } from './audit';
+import type { AccessControlProvider } from './permissions.svelte';
+import type { LiveProvider } from './live.svelte';
+import type { RouterProvider } from './router-provider';
+import type {
+  AuthProvider,
+  BaseRecord,
+  CreateManyParams,
+  CreateManyResult,
+  CreateParams,
+  CreateResult,
+  CustomParams,
+  CustomResult,
+  DataProvider,
+  DeleteManyParams,
+  DeleteManyResult,
+  DeleteParams,
+  DeleteResult,
+  GetListParams,
+  GetListResult,
+  GetManyParams,
+  GetManyResult,
+  GetOneParams,
+  GetOneResult,
+  NotificationProvider,
+  TaskProvider,
+  UpdateManyParams,
+  UpdateManyResult,
+  UpdateParams,
+  UpdateResult,
+} from './types';
+
+export type DataProviderInput = DataProvider | Record<string, DataProvider>;
+
+/**
+ * 一等 Provider 配置对象。字段名与现有独立 provider API 保持一致，
+ * 因此调用方可以渐进地从多个 props 迁移为一个 typed bundle。
+ */
+export interface ProviderBundle {
+  readonly dataProvider: DataProviderInput;
+  readonly authProvider?: AuthProvider | null;
+  readonly accessControlProvider?: AccessControlProvider | null;
+  readonly liveProvider?: LiveProvider;
+  readonly auditLogProvider?: AuditLogProvider | null;
+  readonly notificationProvider?: NotificationProvider | null;
+  readonly chatProvider?: ChatProvider | null;
+  readonly agentProvider?: AgentProvider | null;
+  readonly taskProvider?: TaskProvider;
+  readonly routerProvider?: RouterProvider;
+  readonly tenantAdapter?: TenantAdapter;
+}
+
+/** 保留传入对象的精确类型，同时执行 ProviderBundle 的编译期校验。 */
+export function createProviderBundle<const TBundle extends ProviderBundle>(bundle: TBundle): TBundle {
+  return bundle;
+}
+
+export type TenantId = string | number;
+export type TenantCacheIdentity = string | number;
+
+/** 请求树内的租户状态；不得通过模块级变量在 SSR 请求之间共享。 */
+export interface TenantContext {
+  readonly tenantId: TenantId;
+  readonly meta?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * 将标准 TenantContext 投影到具体后端所需的 provider meta 与 cache identity。
+ * Core 始终额外写入标准 `tenantId`，adapter 不能覆盖该字段。
+ */
+export interface TenantAdapter {
+  readonly getProviderMeta?: (tenant: TenantContext) => Readonly<Record<string, unknown>>;
+  readonly getCacheIdentity?: (tenant: TenantContext) => TenantCacheIdentity;
+}
+
+export interface TenantCacheKey {
+  readonly __svadminTenant: TenantCacheIdentity;
+}
+
+export const defaultTenantAdapter: Required<TenantAdapter> = {
+  getProviderMeta: (tenant) => tenant.meta ?? {},
+  getCacheIdentity: (tenant) => tenant.tenantId,
+};
+
+export function resolveTenantProviderMeta(
+  tenant: TenantContext,
+  adapter: TenantAdapter = defaultTenantAdapter,
+): Record<string, unknown> {
+  return {
+    ...(tenant.meta ?? {}),
+    ...(adapter.getProviderMeta?.(tenant) ?? {}),
+    tenantId: tenant.tenantId,
+  };
+}
+
+export function createTenantCacheKey(
+  tenant: TenantContext,
+  adapter: TenantAdapter = defaultTenantAdapter,
+): TenantCacheKey {
+  return {
+    __svadminTenant: adapter.getCacheIdentity?.(tenant) ?? tenant.tenantId,
+  };
+}
+
+export function isTenantCacheKey(value: unknown): value is TenantCacheKey {
+  return Boolean(
+    value
+      && typeof value === 'object'
+      && Object.keys(value).length === 1
+      && '__svadminTenant' in value
+      && (typeof value.__svadminTenant === 'string' || typeof value.__svadminTenant === 'number'),
+  );
+}
+
+export interface ProviderMetaInput {
+  readonly resource?: string;
+  readonly meta?: Record<string, unknown>;
+}
+
+export type ProviderMetaResolver = (input: ProviderMetaInput) => Record<string, unknown> | undefined;
+
+/**
+ * 为 DataProvider 的所有标准操作增量注入 meta；未声明的扩展字段仍由原 provider 保留。
+ */
+export function withProviderMeta(provider: DataProvider, resolveMeta: ProviderMetaResolver): DataProvider {
+  const adapted: DataProvider = {
+    ...provider,
+    getList: <TData extends BaseRecord = BaseRecord>(params: GetListParams): Promise<GetListResult<TData>> =>
+      provider.getList<TData>({ ...params, meta: resolveMeta(params) }),
+    getOne: <TData extends BaseRecord = BaseRecord>(params: GetOneParams): Promise<GetOneResult<TData>> =>
+      provider.getOne<TData>({ ...params, meta: resolveMeta(params) }),
+    create: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: CreateParams<TVariables>): Promise<CreateResult<TData>> =>
+      provider.create<TData, TVariables>({ ...params, meta: resolveMeta(params) }),
+    update: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: UpdateParams<TVariables>): Promise<UpdateResult<TData>> =>
+      provider.update<TData, TVariables>({ ...params, meta: resolveMeta(params) }),
+    deleteOne: <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: DeleteParams<TVariables>): Promise<DeleteResult<TData>> =>
+      provider.deleteOne<TData, TVariables>({ ...params, meta: resolveMeta(params) }),
+    getApiUrl: () => provider.getApiUrl(),
+  };
+
+  const getMany = provider.getMany?.bind(provider);
+  if (getMany) {
+    adapted.getMany = <TData extends BaseRecord = BaseRecord>(params: GetManyParams): Promise<GetManyResult<TData>> =>
+      getMany<TData>({ ...params, meta: resolveMeta(params) });
+  }
+  const createMany = provider.createMany?.bind(provider);
+  if (createMany) {
+    adapted.createMany = <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: CreateManyParams<TVariables>): Promise<CreateManyResult<TData>> =>
+      createMany<TData, TVariables>({ ...params, meta: resolveMeta(params) });
+  }
+  const updateMany = provider.updateMany?.bind(provider);
+  if (updateMany) {
+    adapted.updateMany = <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: UpdateManyParams<TVariables>): Promise<UpdateManyResult<TData>> =>
+      updateMany<TData, TVariables>({ ...params, meta: resolveMeta(params) });
+  }
+  const deleteMany = provider.deleteMany?.bind(provider);
+  if (deleteMany) {
+    adapted.deleteMany = <TData extends BaseRecord = BaseRecord, TVariables = unknown>(params: DeleteManyParams<TVariables>): Promise<DeleteManyResult<TData>> =>
+      deleteMany<TData, TVariables>({ ...params, meta: resolveMeta(params) });
+  }
+  const custom = provider.custom?.bind(provider);
+  if (custom) {
+    adapted.custom = <TData = unknown, TVariables = unknown>(params: CustomParams<TVariables>): Promise<CustomResult<TData>> =>
+      custom<TData, TVariables>({ ...params, meta: resolveMeta(params) });
+  }
+
+  return adapted;
+}
+
+export function withTenantDataProvider(
+  provider: DataProvider,
+  tenant: TenantContext,
+  adapter: TenantAdapter = defaultTenantAdapter,
+): DataProvider {
+  return withProviderMeta(provider, ({ meta }) => ({
+    ...(meta ?? {}),
+    ...resolveTenantProviderMeta(tenant, adapter),
+  }));
+}

package/src/query-hooks.svelte.ts

@@ -109,7 +109,12 @@ export function useList<TData extends BaseRecord = BaseRecord, TError = HttpErro
     const filters = [...parentFilters, ...(explicitFilters ?? [])];
 
     return {
-      queryKey: [opts.dataProviderName, resource, 'list', pagination, sorters, filters, meta],
+      queryKey: adminContext.queryKeys(resource, opts.dataProviderName).data.list(resource, {
+        pagination,
+        sorters,
+        filters,
+        meta,
+      }),
       queryFn: async () => provider.getList<TData>({
         resource,
         pagination,
@@ -150,12 +155,24 @@ export function useList<TData extends BaseRecord = BaseRecord, TError = HttpErro
     if (query.isSuccess && query.dataUpdatedAt > lastSuccessAt) {
       lastSuccessAt = query.dataUpdatedAt;
       if (opts.successNotification) {
-        fireSuccessNotification(opts.successNotification, '', query.data, undefined, getResource());
+        fireSuccessNotification({
+          config: opts.successNotification,
+          defaultMessage: '',
+          data: query.data,
+          resource: getResource(),
+          provider: adminContext.notificationProvider,
+        });
       }
     } else if (query.isError && query.errorUpdatedAt > lastErrorAt) {
       lastErrorAt = query.errorUpdatedAt;
       checkError(query.error, adminContext);
-      fireErrorNotification(opts.errorNotification, 'Fetch failed', query.error, getResource());
+      fireErrorNotification({
+        config: opts.errorNotification,
+        defaultMessage: 'Fetch failed',
+        error: query.error,
+        resource: getResource(),
+        provider: adminContext.notificationProvider,
+      });
     }
   });
 
@@ -195,7 +212,9 @@ export function useOne<TData extends BaseRecord = BaseRecord, TError = HttpError
     const queryOptions = opts.queryOptions;
 
     return {
-      queryKey: [opts.dataProviderName, resource, 'one', id, opts.meta],
+      queryKey: adminContext.queryKeys(resource, opts.dataProviderName).data.one(resource, id ?? '', {
+        meta: cloneQueryKeyPart(opts.meta),
+      }),
       queryFn: async () => {
         if (id == null) throw new Error('useOne requires an id');
         const result = await provider.getOne<TData>({
@@ -238,12 +257,24 @@ export function useOne<TData extends BaseRecord = BaseRecord, TError = HttpError
     if (query.isSuccess && query.dataUpdatedAt > lastSuccessAt) {
       lastSuccessAt = query.dataUpdatedAt;
       if (opts.successNotification) {
-        fireSuccessNotification(opts.successNotification, '', query.data, undefined, getResource());
+        fireSuccessNotification({
+          config: opts.successNotification,
+          defaultMessage: '',
+          data: query.data,
+          resource: getResource(),
+          provider: adminContext.notificationProvider,
+        });
       }
     } else if (query.isError && query.errorUpdatedAt > lastErrorAt) {
       lastErrorAt = query.errorUpdatedAt;
       checkError(query.error, adminContext);
-      fireErrorNotification(opts.errorNotification, 'Fetch failed', query.error, getResource());
+      fireErrorNotification({
+        config: opts.errorNotification,
+        defaultMessage: 'Fetch failed',
+        error: query.error,
+        resource: getResource(),
+        provider: adminContext.notificationProvider,
+      });
     }
   });
 
@@ -300,7 +331,10 @@ export function useMany<TData extends BaseRecord = BaseRecord, TError = HttpErro
     const provider = adminContext.getDataProviderForResource(resource, dataProviderName);
 
     return {
-      queryKey: [dataProviderName, resource, 'many', ids, meta],
+      queryKey: adminContext.queryKeys(resource, dataProviderName).data.many(resource, {
+        ids: cloneQueryKeyPart(ids),
+        meta: cloneQueryKeyPart(meta),
+      }),
       queryFn: async () => {
         if (!ids.length) return { data: [] };
         if (provider.getMany) {
@@ -341,12 +375,24 @@ export function useMany<TData extends BaseRecord = BaseRecord, TError = HttpErro
     if (query.isSuccess && query.dataUpdatedAt > lastSuccessAt) {
       lastSuccessAt = query.dataUpdatedAt;
       if (opts.successNotification) {
-        fireSuccessNotification(opts.successNotification, '', query.data, undefined, opts.resource);
+        fireSuccessNotification({
+          config: opts.successNotification,
+          defaultMessage: '',
+          data: query.data,
+          resource: opts.resource,
+          provider: adminContext.notificationProvider,
+        });
       }
     } else if (query.isError && query.errorUpdatedAt > lastErrorAt) {
       lastErrorAt = query.errorUpdatedAt;
       checkError(query.error, adminContext);
-      fireErrorNotification(opts.errorNotification, 'Fetch failed', query.error, opts.resource);
+      fireErrorNotification({
+        config: opts.errorNotification,
+        defaultMessage: 'Fetch failed',
+        error: query.error,
+        resource: opts.resource,
+        provider: adminContext.notificationProvider,
+      });
     }
   });
 

package/src/query-keys.ts

@@ -1,21 +1,127 @@
-export const keys = () => {
-  let _dataProviderName: string | undefined = undefined;
-  let _resource = '';
-  let _action = '';
-  let _params: unknown = undefined;
-
-  const builder = {
-    data: (name: string | undefined) => { _dataProviderName = name; return builder; },
-    resource: (name: string) => { _resource = name; return builder; },
-    action: (name: string) => { _action = name; return builder; },
-    params: (params: unknown) => { _params = params; return builder; },
-    get: (): unknown[] => {
-      const parts: unknown[] = [_dataProviderName, _resource];
-      if (_action) parts.push(_action);
-      if (_params !== undefined) parts.push(_params);
-      return parts;
-    }
+export const NAMESPACE = 'svadmin';
+export const VERSION = 2;
+
+export type QueryKind = 'data' | 'task' | 'access' | 'custom';
+export type QueryDataAction = 'list' | 'infiniteList' | 'one' | 'many' | 'select' | 'selectDefaults';
+export type QueryTaskAction = 'list' | 'one';
+type TenantId = string | number;
+
+type BaseDescriptor = {
+  readonly namespace: typeof NAMESPACE;
+  readonly version: typeof VERSION;
+  readonly provider: string;
+  readonly tenant?: TenantId;
+  readonly resource?: string;
+  readonly id?: string | number;
+  readonly params?: unknown;
+  readonly method?: string;
+};
+
+export type QueryDescriptorData = BaseDescriptor & { readonly kind: 'data'; readonly action: QueryDataAction };
+export type QueryDescriptorTask = BaseDescriptor & { readonly kind: 'task'; readonly action: QueryTaskAction };
+export type QueryDescriptorAccess = BaseDescriptor & { readonly kind: 'access'; readonly action?: 'can' };
+export type QueryDescriptorCustom = BaseDescriptor & { readonly kind: 'custom'; readonly action?: string };
+export type QueryDescriptor = QueryDescriptorData | QueryDescriptorTask | QueryDescriptorAccess | QueryDescriptorCustom;
+export type QueryKey = readonly [descriptor: QueryDescriptor];
+
+export type QueryKeysContext = { readonly provider?: string; readonly tenant?: TenantId; readonly resource?: string; readonly action?: string; readonly id?: string | number; readonly params?: unknown; readonly method?: string };
+export type QueryMatcher = { readonly provider?: string; readonly tenant?: TenantId; readonly resource?: string; readonly action?: string; readonly id?: string | number; readonly method?: string; readonly kind?: QueryKind };
+export type DataQueryMatcher = Omit<QueryMatcher, 'kind'> & { readonly resource: string };
+export type QueryKeysBuilder = {
+  data: { list(resource: string, params?: unknown): QueryKey; infiniteList(resource: string, params?: unknown): QueryKey; one(resource: string, id: string | number, params?: unknown): QueryKey; many(resource: string, params: unknown): QueryKey; select(resource: string, params?: unknown): QueryKey; selectDefaults(resource: string, params?: unknown): QueryKey; };
+  task: { list(params?: unknown): QueryKey; one(id: string | number): QueryKey };
+  access: { can(resource?: string, params?: unknown): QueryKey };
+  custom: { call(resource: string, id: string | number, method?: string, params?: unknown): QueryKey };
+};
+
+function withDefaultProvider(value: string | undefined): string { return value === undefined ? 'default' : value; }
+function assertProvider(provider: string): void { if (!provider.length) throw new Error('provider must be a non-empty string'); }
+
+function makeDescriptor(value: { kind: 'data'; provider?: string; tenant?: TenantId; resource?: string; action: QueryDataAction; id?: string | number; params?: unknown; method?: string; }): QueryDescriptorData;
+function makeDescriptor(value: { kind: 'task'; provider?: string; tenant?: TenantId; resource?: string; action: QueryTaskAction; id?: string | number; params?: unknown; method?: string; }): QueryDescriptorTask;
+function makeDescriptor(value: { kind: 'access'; provider?: string; tenant?: TenantId; resource?: string; action?: 'can'; id?: string | number; params?: unknown; method?: string; }): QueryDescriptorAccess;
+function makeDescriptor(value: { kind: 'custom'; provider?: string; tenant?: TenantId; resource?: string; id?: string | number; action?: string; params?: unknown; method?: string; }): QueryDescriptorCustom;
+function makeDescriptor(value: { kind: QueryKind; provider?: string; tenant?: TenantId; resource?: string; action?: string; id?: string | number; params?: unknown; method?: string; }): QueryDescriptor {
+  const provider = withDefaultProvider(value.provider);
+  assertProvider(provider);
+
+  const base = { namespace: NAMESPACE, version: VERSION, provider, tenant: value.tenant, resource: value.resource, id: value.id, params: value.params, method: value.method } as const;
+  if (value.kind === 'data') return { ...base, kind: 'data', action: value.action } as QueryDescriptorData;
+  if (value.kind === 'task') return { ...base, kind: 'task', action: value.action as QueryTaskAction } as QueryDescriptorTask;
+  if (value.kind === 'access') return { ...base, kind: 'access', action: value.action as 'can' | undefined } as QueryDescriptorAccess;
+  return { ...base, kind: 'custom', action: value.action } as QueryDescriptorCustom;
+}
+
+export function keys(context: QueryKeysContext = {}): QueryKeysBuilder {
+  const base = { provider: withDefaultProvider(context.provider), tenant: context.tenant, resource: context.resource, id: context.id, params: context.params, method: context.method };
+  return {
+    data: {
+      list: (resource, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'list', id: base.id, params, method: base.method })],
+      infiniteList: (resource, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'infiniteList', id: base.id, params, method: base.method })],
+      one: (resource, id, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'one', id, params, method: base.method })],
+      many: (resource, params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'many', params, method: base.method })],
+      select: (resource, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'select', id: base.id, params, method: base.method })],
+      selectDefaults: (resource, params = base.params) => [makeDescriptor({ kind: 'data', provider: base.provider, tenant: base.tenant, resource, action: 'selectDefaults', id: base.id, params, method: base.method })],
+    },
+    task: {
+      list: (params = base.params) => [makeDescriptor({ kind: 'task', provider: base.provider, tenant: base.tenant, resource: base.resource, action: 'list', id: base.id, params, method: base.method })],
+      one: (id) => [makeDescriptor({ kind: 'task', provider: base.provider, tenant: base.tenant, resource: base.resource, action: 'one', id, method: base.method })],
+    },
+    access: { can: (resource = base.resource, params = base.params) => [makeDescriptor({ kind: 'access', provider: base.provider, tenant: base.tenant, resource, action: 'can', id: base.id, params, method: base.method })] },
+    custom: { call: (resource, id, method, params) => [makeDescriptor({ kind: 'custom', provider: base.provider, tenant: base.tenant, resource, id, method, params, action: 'call' })] },
   };
+}
 
-  return builder;
+export const queryKeys: QueryKeysBuilder = {
+  data: {
+    list: (resource, params) => keys().data.list(resource, params),
+    infiniteList: (resource, params) => keys().data.infiniteList(resource, params),
+    one: (resource, id, params) => keys().data.one(resource, id, params),
+    many: (resource, params) => keys().data.many(resource, params),
+    select: (resource, params) => keys().data.select(resource, params),
+    selectDefaults: (resource, params) => keys().data.selectDefaults(resource, params),
+  },
+  task: { list: (params) => keys().task.list(params), one: (id) => keys().task.one(id) },
+  access: { can: (resource, params) => keys().access.can(resource, params) },
+  custom: { call: (resource, id, method, params) => keys().custom.call(resource, id, method, params) },
 };
+
+export function parseQueryKey(value: unknown): QueryDescriptor | undefined {
+  if (!Array.isArray(value) || value.length !== 1) return;
+  const candidate = value[0];
+  if (!candidate || typeof candidate !== 'object') return;
+  const descriptor = candidate as QueryDescriptor;
+  if (descriptor.namespace !== NAMESPACE || descriptor.version !== VERSION || typeof descriptor.provider !== 'string' || !descriptor.provider.length) return;
+  if (descriptor.tenant !== undefined && typeof descriptor.tenant !== 'string' && typeof descriptor.tenant !== 'number') return;
+  if (descriptor.resource !== undefined && typeof descriptor.resource !== 'string') return;
+  if (descriptor.id !== undefined && typeof descriptor.id !== 'string' && typeof descriptor.id !== 'number') return;
+  if (descriptor.method !== undefined && typeof descriptor.method !== 'string') return;
+  if (descriptor.kind === 'data' && ['list', 'infiniteList', 'one', 'many', 'select', 'selectDefaults'].includes(descriptor.action)) return descriptor;
+  if (descriptor.kind === 'task' && ['list', 'one'].includes(descriptor.action)) return descriptor;
+  if (descriptor.kind === 'access' && (descriptor.action === undefined || descriptor.action === 'can')) return descriptor;
+  if (descriptor.kind === 'custom' && (descriptor.action === undefined || typeof descriptor.action === 'string')) return descriptor;
+}
+
+export function isQueryKey(value: unknown): value is QueryKey { return parseQueryKey(value) !== undefined; }
+
+function has(value: QueryMatcher, key: keyof QueryMatcher): boolean { return Object.prototype.hasOwnProperty.call(value, key); }
+function matchField(descriptor: QueryDescriptor, matcher: QueryMatcher, key: keyof QueryMatcher): boolean {
+  if (!has(matcher, key)) return true;
+  if (matcher[key] === undefined) return !(key in descriptor) || (descriptor as Record<string, unknown>)[key] === undefined;
+  return (descriptor as Record<string, unknown>)[key] === matcher[key];
+}
+
+export function queryKeyMatches(queryKey: readonly unknown[], matcher: QueryMatcher = {}): boolean {
+  const parsed = parseQueryKey(queryKey);
+  if (!parsed) return false;
+  if (matcher.kind !== undefined && matcher.kind !== parsed.kind) return false;
+  if (has(matcher, 'provider')) {
+    if (matcher.provider === undefined) return parsed.provider === 'default';
+    if (matcher.provider !== parsed.provider) return false;
+  }
+  return matchField(parsed, matcher, 'tenant') && matchField(parsed, matcher, 'resource') && matchField(parsed, matcher, 'action') && matchField(parsed, matcher, 'id') && matchField(parsed, matcher, 'method');
+}
+
+export function dataQueryMatches(queryKey: readonly unknown[], matcher: DataQueryMatcher): boolean {
+  return queryKeyMatches(queryKey, { ...matcher, kind: 'data' });
+}

package/src/task-hooks.svelte.ts

@@ -2,6 +2,10 @@ import { createMutation, createQuery, useQueryClient } from '@tanstack/svelte-qu
 import { getAdminOptions } from './options.svelte';
 import { captureAdminContext } from './context.svelte';
 import type { AdminContextAccessor } from './context.svelte';
+import {
+  resolveTenantProviderMeta,
+} from './provider-bundle';
+import { queryKeyMatches } from './query-keys';
 import { checkError, createOvertimeTracker, fireErrorNotification, fireSuccessNotification } from './hook-utils.svelte';
 import type { NotificationConfig, OvertimeOptions } from './hook-utils.svelte';
 import { useTranslation } from './i18n.svelte';
@@ -54,27 +58,44 @@ export function useSubmitTask<
   const mutation = createMutation<TaskHandle<TTask>, TError, UseSubmitTaskMutateParams<TTask>>(() => ({
     mutationFn: async (params) => {
       const provider = normalizeTaskProvider<TTask>(params.taskProvider, adminContext);
-      return provider.submit(params.taskName, params.options);
+      const providerMeta = adminContext.tenant
+        ? {
+            ...(params.options?.meta ?? {}),
+            ...resolveTenantProviderMeta(adminContext.tenant, adminContext.tenantAdapter),
+          }
+        : params.options?.meta;
+      const taskOptions = providerMeta === params.options?.meta
+        ? params.options
+        : { ...params.options, meta: providerMeta };
+      return provider.submit(params.taskName, taskOptions);
     },
     onSuccess: (data, params, context) => {
-      fireSuccessNotification(
-        params.successNotification,
-        i18n.t('task.submitSuccess'),
+      fireSuccessNotification({
+        config: params.successNotification,
+        defaultMessage: i18n.t('task.submitSuccess'),
         data,
-        params.options,
-        params.taskName,
-      );
-      void queryClient.invalidateQueries({ queryKey: ['taskList'] });
+        values: params.options,
+        resource: params.taskName,
+        provider: adminContext.notificationProvider,
+      });
+      void queryClient.invalidateQueries({
+        predicate: (query) => queryKeyMatches(query.queryKey, {
+          ...adminContext.queryKeyMatcher(),
+          kind: 'task',
+          action: 'list',
+        }),
+      });
       options.mutationOptions?.onSuccess?.(data, params, context);
     },
     onError: (error, params, context) => {
       checkError(error, adminContext);
-      fireErrorNotification(
-        params.errorNotification,
-        i18n.t('task.submitFailed'),
+      fireErrorNotification({
+        config: params.errorNotification,
+        defaultMessage: i18n.t('task.submitFailed'),
         error,
-        params.taskName,
-      );
+        resource: params.taskName,
+        provider: adminContext.notificationProvider,
+      });
       options.mutationOptions?.onError?.(error, params, context);
     },
   }));
@@ -109,7 +130,7 @@ export function useTask<TTask extends TaskRecord = TaskRecord, TError = HttpErro
     const provider = normalizeTaskProvider<TTask>(options.taskProvider, adminContext);
     const queryOptions = options.queryOptions;
     return {
-      queryKey: ['task', options.taskId],
+      queryKey: adminContext.queryKeys().task.one(options.taskId ?? ''),
       queryFn: async () => {
         if (!options.taskId) throw new Error('useTask requires a taskId');
         return provider.get(options.taskId);
@@ -131,12 +152,24 @@ export function useTask<TTask extends TaskRecord = TaskRecord, TError = HttpErro
     if (query.isSuccess && query.dataUpdatedAt > lastSuccessAt) {
       lastSuccessAt = query.dataUpdatedAt;
       if (options.successNotification) {
-        fireSuccessNotification(options.successNotification, '', query.data, undefined, options.taskId);
+        fireSuccessNotification({
+          config: options.successNotification,
+          defaultMessage: '',
+          data: query.data,
+          resource: options.taskId,
+          provider: adminContext.notificationProvider,
+        });
       }
     } else if (query.isError && query.errorUpdatedAt > lastErrorAt) {
       lastErrorAt = query.errorUpdatedAt;
       checkError(query.error, adminContext);
-      fireErrorNotification(options.errorNotification, i18n.t('task.fetchFailed'), query.error, options.taskId);
+      fireErrorNotification({
+        config: options.errorNotification,
+        defaultMessage: i18n.t('task.fetchFailed'),
+        error: query.error,
+        resource: options.taskId,
+        provider: adminContext.notificationProvider,
+      });
     }
   });
 
@@ -176,7 +209,10 @@ export function useTaskList<TTask extends TaskRecord = TaskRecord, TError = Http
     const provider = normalizeTaskProvider<TTask>(options.taskProvider, adminContext);
     const queryOptions = options.queryOptions;
     return {
-      queryKey: ['taskList', options.dlq ? 'dlq' : 'default', options.params],
+      queryKey: adminContext.queryKeys().task.list({
+        list: options.dlq ? 'dlq' : 'default',
+        params: options.params,
+      }),
       queryFn: async () => {
         if (options.dlq) {
           if (!provider.listDlq) throw new Error('TaskProvider does not implement listDlq');
@@ -202,12 +238,25 @@ export function useTaskList<TTask extends TaskRecord = TaskRecord, TError = Http
     if (query.isSuccess && query.dataUpdatedAt > lastSuccessAt) {
       lastSuccessAt = query.dataUpdatedAt;
       if (options.successNotification) {
-        fireSuccessNotification(options.successNotification, '', query.data, options.params, options.dlq ? 'taskDlq' : 'tasks');
+        fireSuccessNotification({
+          config: options.successNotification,
+          defaultMessage: '',
+          data: query.data,
+          values: options.params,
+          resource: options.dlq ? 'taskDlq' : 'tasks',
+          provider: adminContext.notificationProvider,
+        });
       }
     } else if (query.isError && query.errorUpdatedAt > lastErrorAt) {
       lastErrorAt = query.errorUpdatedAt;
       checkError(query.error, adminContext);
-      fireErrorNotification(options.errorNotification, i18n.t('task.fetchListFailed'), query.error, options.dlq ? 'taskDlq' : 'tasks');
+      fireErrorNotification({
+        config: options.errorNotification,
+        defaultMessage: i18n.t('task.fetchListFailed'),
+        error: query.error,
+        resource: options.dlq ? 'taskDlq' : 'tasks',
+        provider: adminContext.notificationProvider,
+      });
     }
   });
 

package/src/types.ts

@@ -382,6 +382,28 @@ export type MutationMode = 'pessimistic' | 'optimistic' | 'undoable';
 
 // ─── ResourceDefinition ───────────────────────────────────────
 
+/** 声明资源使用的传输协议；具体 URL/序列化行为由对应 provider 实现。 */
+export interface ResourceTransportConfig {
+  readonly type: string;
+  readonly endpoint?: string;
+  readonly options?: Readonly<Record<string, unknown>>;
+}
+
+/** 声明资源使用的后端 adapter，不在 Core 内绑定具体运行时实现。 */
+export interface ResourceAdapterConfig {
+  readonly name: string;
+  readonly version?: string;
+  readonly options?: Readonly<Record<string, unknown>>;
+}
+
+/** 每资源的 provider 选择与声明性 transport/adapter 元数据。 */
+export interface ResourceProviderConfig {
+  readonly dataProviderName?: string;
+  readonly transport?: string | ResourceTransportConfig;
+  readonly adapter?: string | ResourceAdapterConfig;
+  readonly meta?: Readonly<Record<string, unknown>>;
+}
+
 export interface ResourceDefinition {
   name: string;
   /** Unique identifier — use when multiple resources share the same `name` but target different DataProviders */
@@ -401,6 +423,9 @@ export interface ResourceDefinition {
   menuOrder?: number;
   /** Navigation group name — resources with the same group are displayed in a collapsible section */
   group?: string;
+  /** DataProvider 选择及声明性 transport/adapter 元数据。 */
+  provider?: ResourceProviderConfig;
+  /** @deprecated 新代码优先使用 `provider.dataProviderName` 选择 DataProvider。 */
   meta?: Record<string, unknown> & { dataProviderName?: string; parent?: string };
 }