@svadmin/core 0.41.1 → 0.42.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/core",
-  "version": "0.41.1",
+  "version": "0.42.1",
   "author": "zuohuadong",
   "repository": {
     "type": "git",

package/src/form-hooks.svelte.ts

@@ -14,6 +14,7 @@ import type { BaseRecord, MutationMode, KnownResources } from './types';
 import { checkError } from './hook-utils.svelte';
 import { toast } from './toast.svelte';
 import { deepMerge, invalidateByScopes } from './mutation-hooks.svelte';
+import { appendListQueryFromPath } from './url-sync';
 
 // ─── Types ───────────────────────────────────────────────────────────
 
@@ -652,14 +653,15 @@ export function useForm<
   }));
 
   function doRedirect(to: 'list' | 'edit' | 'show' | false) {
-    const path = adminContext.currentPath().split('?')[0];
+    const currentPath = adminContext.currentPath();
+    const path = currentPath.split('?')[0];
     const parts = path.split('/');
     const resIdx = parts.lastIndexOf(String(resource));
     const base = resIdx >= 0 ? parts.slice(0, resIdx + 1).join('/') : `/${resource}`;
 
-    if (to === 'list') void adminContext.navigate(base);
-    else if (to === 'edit' && currentId) void adminContext.navigate(`${base}/edit/${currentId}`);
-    else if (to === 'show' && currentId) void adminContext.navigate(`${base}/show/${currentId}`);
+    if (to === 'list') void adminContext.navigate(appendListQueryFromPath(base, currentPath));
+    else if (to === 'edit' && currentId) void adminContext.navigate(appendListQueryFromPath(`${base}/edit/${currentId}`, currentPath));
+    else if (to === 'show' && currentId) void adminContext.navigate(appendListQueryFromPath(`${base}/show/${currentId}`, currentPath));
   }
 
   // ─── Submit ─────────────────────────────────────────────────────

package/src/hooks.svelte.ts

@@ -22,14 +22,19 @@ export type { OvertimeResult, OvertimeOptions, NotificationConfig } from './hook
 import { createQuery, createInfiniteQuery, createMutation, useQueryClient } from '@tanstack/svelte-query';
 import { getAdminOptions } from './options.svelte';
 import { captureAdminContext } from './context.svelte';
-import { queryKeyMatches } from './query-keys';
+import { dataQueryMatches, queryKeyMatches } from './query-keys';
+import type { QueryMatcher } from './query-keys';
 import { useParsed } from './useParsed.svelte';
 import { createOvertimeTracker, createLiveSubscription, fireSuccessNotification, fireErrorNotification, checkError } from './hook-utils.svelte';
 import { invalidateByScopes, publishLiveEvent } from './mutation-hooks.svelte';
 import type { NotificationConfig, OvertimeOptions, LiveSubscriptionParams } from './hook-utils.svelte';
-import type { BaseRecord, HttpError, Pagination, Sort, Filter, DataProvider, KnownResources } from './types';
+import { DeleteManyPartialError, UndoError } from './types';
+import type { BaseRecord, HttpError, Pagination, Sort, Filter, DataProvider, KnownResources, MutationMode } from './types';
 import type { LiveMode, LiveEvent } from './live.svelte';
 import { auditWithProvider } from './audit';
+import { useTranslation } from './i18n.svelte';
+import { toast } from './toast.svelte';
+import type { MutationCallbacks } from './mutation-hooks.svelte';
 
 // ─── useInfiniteList ────────────────────────────────────────────────
 
@@ -493,25 +498,175 @@ export function useUpdateMany<TData extends BaseRecord = BaseRecord, TError = Ht
   return { mutation, get overtime() { return createOvertimeTracker(() => mutation.isPending, options.overtimeOptions ?? adminOptions.overtime); } };
 }
 
-export function useDeleteMany<TData extends BaseRecord = BaseRecord, TError = HttpError>(options: { resource?: KnownResources; overtimeOptions?: OvertimeOptions } = {}) {
+export interface UseDeleteManyOptions {
+  resource?: KnownResources;
+  mutationMode?: MutationMode;
+  undoableTimeout?: number;
+  mutationOptions?: MutationCallbacks;
+  overtimeOptions?: OvertimeOptions;
+  successNotification?: NotificationConfig;
+  errorNotification?: NotificationConfig;
+}
+
+export interface UseDeleteManyMutateParams {
+  resource?: KnownResources;
+  ids: (string | number)[];
+  mutationMode?: MutationMode;
+  undoableTimeout?: number;
+  meta?: Record<string, unknown>;
+  dataProviderName?: string;
+  invalidates?: string[] | false;
+  onCancel?: () => void;
+  successNotification?: NotificationConfig;
+  errorNotification?: NotificationConfig;
+}
+
+interface DeleteManyMutationContext {
+  _svadmin_ctx?: boolean;
+  userContext?: unknown;
+  previousQueries?: [readonly unknown[], unknown][];
+}
+
+export function useDeleteMany<TData extends BaseRecord = BaseRecord, TError = HttpError>(options: UseDeleteManyOptions = {}) {
   const adminContext = captureAdminContext();
   const parsed = useParsed();
   const resource = options.resource ?? parsed.resource ?? '';
   const adminOptions = getAdminOptions();
   const queryClient = useQueryClient();
+  const i18n = useTranslation();
+  const mutationMode = options.mutationMode ?? adminOptions.mutationMode ?? 'pessimistic';
+  const undoableTimeout = options.undoableTimeout ?? adminOptions.undoableTimeout ?? 5000;
+
+  const removeIdsFromCache = (
+    resName: string,
+    ids: (string | number)[],
+    dataProviderName?: string,
+  ) => {
+    const matcher = adminContext.queryKeyMatcher(resName, dataProviderName);
+    const dataMatch = (queryKey: readonly unknown[], fields: QueryMatcher = {}) => dataQueryMatches(queryKey, {
+      ...matcher,
+      resource: resName,
+      ...fields,
+    });
+    const primaryKey = adminContext.getResource(resName).primaryKey ?? 'id';
+    const deletedIds = new Set(ids.map(String));
+    const removeFromCollection = (old: unknown): unknown => {
+      if (!old || typeof old !== 'object' || !('data' in old)) return old;
+      const current = old as { data: Record<string, unknown>[]; total?: number };
+      if (!Array.isArray(current.data)) return old;
+      const filtered = current.data.filter((item) => !deletedIds.has(String(item[primaryKey])));
+      const removedCount = current.data.length - filtered.length;
+      return {
+        ...current,
+        data: filtered,
+        total: current.total == null ? current.total : Math.max(0, current.total - removedCount),
+      };
+    };
+    const removeFromInfiniteCollection = (old: unknown): unknown => {
+      if (!old || typeof old !== 'object' || !('pages' in old)) return old;
+      const current = old as {
+        pages: { data: Record<string, unknown>[]; total?: number }[];
+        pageParams?: unknown[];
+      };
+      if (!Array.isArray(current.pages)) return old;
+
+      const removedIds = new Set<string>();
+      for (const page of current.pages) {
+        if (!Array.isArray(page.data)) continue;
+        for (const item of page.data) {
+          const itemId = String(item[primaryKey]);
+          if (deletedIds.has(itemId)) removedIds.add(itemId);
+        }
+      }
 
-  const mutation = createMutation<{ data: TData[] }, TError, { resource?: KnownResources; ids: (string | number)[]; meta?: Record<string, unknown>; dataProviderName?: string }>(() => ({
+      return {
+        ...current,
+        pages: current.pages.map((page) => ({
+          ...page,
+          data: Array.isArray(page.data)
+            ? page.data.filter((item) => !deletedIds.has(String(item[primaryKey])))
+            : page.data,
+          total: page.total == null ? page.total : Math.max(0, page.total - removedIds.size),
+        })),
+      };
+    };
+
+    queryClient.setQueriesData({
+      predicate: (query) => ['list', 'select', 'selectDefaults'].some((action) => dataMatch(query.queryKey, { action })),
+    }, removeFromCollection);
+    queryClient.setQueriesData({
+      predicate: (query) => dataMatch(query.queryKey, { action: 'infiniteList' }),
+    }, removeFromInfiniteCollection);
+    queryClient.setQueriesData({
+      predicate: (query) => dataMatch(query.queryKey, { action: 'many' }),
+    }, removeFromCollection);
+  };
+
+  const mutation = createMutation<{ data: TData[] }, TError | DeleteManyPartialError, UseDeleteManyMutateParams, DeleteManyMutationContext>(() => ({
     mutationFn: async (params) => {
       const resName = params.resource ?? resource;
+      const effectiveMutationMode = params.mutationMode ?? mutationMode;
+      const effectiveUndoableTimeout = params.undoableTimeout ?? undoableTimeout;
+      if (effectiveMutationMode === 'undoable') {
+        await new Promise<void>((resolve, reject) => {
+          toast.undoable(i18n.t('common.actionCanBeUndone'), effectiveUndoableTimeout, () => {
+            params.onCancel?.();
+            reject(new UndoError());
+          }, resolve);
+        });
+      }
       const provider = adminContext.getDataProviderForResource(resName, params.dataProviderName);
       if (provider.deleteMany) return await provider.deleteMany<TData>({ resource: resName, ids: params.ids, meta: params.meta });
-      const results = await Promise.all(params.ids.map(id => provider.deleteOne<TData>({ resource: resName, id, meta: params.meta })));
-      return { data: results.map(r => r.data) };
+      const settled = await Promise.allSettled(
+        params.ids.map(id => provider.deleteOne<TData>({ resource: resName, id, meta: params.meta })),
+      );
+      const succeededIds: (string | number)[] = [];
+      const failedIds: (string | number)[] = [];
+      const causes: unknown[] = [];
+      const data: TData[] = [];
+      settled.forEach((result, index) => {
+        const id = params.ids[index];
+        if (result.status === 'fulfilled') {
+          succeededIds.push(id);
+          data.push(result.value.data);
+        } else {
+          failedIds.push(id);
+          causes.push(result.reason);
+        }
+      });
+      if (failedIds.length > 0) {
+        if (succeededIds.length > 0) {
+          throw new DeleteManyPartialError(succeededIds, failedIds, causes);
+        }
+        throw causes[0] ?? new Error('Delete many failed');
+      }
+      return { data };
     },
-    onSuccess: (data, params) => {
+    onMutate: async (params) => {
+      const userContext = typeof options.mutationOptions?.onMutate === 'function'
+        ? await options.mutationOptions.onMutate(params)
+        : undefined;
+      const effectiveMutationMode = params.mutationMode ?? mutationMode;
+      if (effectiveMutationMode === 'pessimistic') return { _svadmin_ctx: true, userContext };
+      const resName = params.resource ?? resource;
+      const matcher = adminContext.queryKeyMatcher(resName, params.dataProviderName);
+      const dataMatch = (queryKey: readonly unknown[], fields: QueryMatcher = {}) => dataQueryMatches(queryKey, {
+        ...matcher,
+        resource: resName,
+        ...fields,
+      });
+
+      await queryClient.cancelQueries({ predicate: (query) => dataMatch(query.queryKey) });
+      const previousQueries = queryClient.getQueriesData({ predicate: (query) => dataMatch(query.queryKey) });
+      removeIdsFromCache(resName, params.ids, params.dataProviderName);
+
+      return { _svadmin_ctx: true, userContext, previousQueries };
+    },
+    onSuccess: (data, params, context) => {
       const resName = params.resource ?? resource;
+      const extractedContext = context?._svadmin_ctx ? context.userContext : context;
       fireSuccessNotification({
-        config: undefined,
+        config: params.successNotification ?? options.successNotification,
         defaultMessage: 'Deleted successfully',
         data: data.data,
         resource: resName,
@@ -522,35 +677,81 @@ export function useDeleteMany<TData extends BaseRecord = BaseRecord, TError = Ht
         adminContext.auditLogProvider,
       );
       publishLiveEvent(resName, 'deleted', params.ids, adminContext);
+      for (const id of params.ids) {
+        queryClient.removeQueries({
+          predicate: (query) => queryKeyMatches(query.queryKey, {
+            ...adminContext.queryKeyMatcher(resName, params.dataProviderName),
+            kind: 'data',
+            resource: resName,
+            action: 'one',
+            id,
+          }),
+        });
+      }
+      if (typeof options.mutationOptions?.onSuccess === 'function') {
+        options.mutationOptions.onSuccess(data, params, extractedContext);
+      }
     },
-    onError: (error, params) => {
-      checkError(error, adminContext);
+    onError: (error, params, context) => {
+      if (context?.previousQueries) {
+        for (const [queryKey, data] of context.previousQueries) queryClient.setQueryData(queryKey, data);
+      }
+      if (error instanceof UndoError) return;
+      const resName = params.resource ?? resource;
+      if (error instanceof DeleteManyPartialError) {
+        removeIdsFromCache(resName, error.succeededIds, params.dataProviderName);
+        for (const id of error.succeededIds) {
+          queryClient.removeQueries({
+            predicate: (query) => queryKeyMatches(query.queryKey, {
+              ...adminContext.queryKeyMatcher(resName, params.dataProviderName),
+              kind: 'data',
+              resource: resName,
+              action: 'one',
+              id,
+            }),
+          });
+        }
+        auditWithProvider(
+          {
+            action: 'delete',
+            resource: resName,
+            outcome: 'failure',
+            details: { succeededIds: error.succeededIds, failedIds: error.failedIds },
+            meta: adminContext.getProviderMeta(resName),
+          },
+          adminContext.auditLogProvider,
+        );
+        publishLiveEvent(resName, 'deleted', error.succeededIds, adminContext);
+      }
+      const authError = error instanceof DeleteManyPartialError
+        ? (error.causes[0] ?? error)
+        : error;
+      checkError(authError, adminContext);
       fireErrorNotification({
-        config: undefined,
+        config: params.errorNotification ?? options.errorNotification,
         defaultMessage: 'Delete many failed',
         error,
-        resource: params.resource ?? resource,
+        resource: resName,
         provider: adminContext.notificationProvider,
       });
+      const extractedContext = context?._svadmin_ctx ? context.userContext : context;
+      if (typeof options.mutationOptions?.onError === 'function') {
+        options.mutationOptions.onError(error, params, extractedContext);
+      }
     },
-    onSettled: (_d, _e, params) => {
+    onSettled: (_data, error, params, context) => {
+      if (error instanceof UndoError) return;
       const resName = params.resource ?? resource;
       invalidateByScopes({
         queryClient,
         resource: resName,
+        scopes: params.invalidates,
         defaults: ['list', 'many'],
         matcher: adminContext.queryKeyMatcher(resName, params.dataProviderName),
       });
-      for (const id of params.ids) {
-        queryClient.removeQueries({
-          predicate: (q) => queryKeyMatches(q.queryKey, {
-            ...adminContext.queryKeyMatcher(resName, params.dataProviderName),
-            kind: 'data',
-            resource: resName,
-            action: 'one',
-            id,
-          }),
-        });
+      const extractedContext = context?._svadmin_ctx ? context.userContext : context;
+      if (typeof options.mutationOptions?.onSettled === 'function') {
+        options.mutationOptions.onSettled(_data, error, params, extractedContext);
       }
     },
   }));

package/src/i18n.svelte.ts

@@ -22,8 +22,9 @@ const baseLocales: Record<string, Record<string, string>> = {
     'common.delete': '删除',
     'common.batchDeletePartialFail': '批量删除部分失败：{failed}/{total} 条未成功',
     'common.batchDeleteSuccess': '成功删除 {count} 条记录',
+    'common.batchDeleteFailed': '批量删除失败，未删除 {count} 条记录',
     'common.selectedItems': '已选择 {count} 项',
-    'common.clearSelection': '取消选择',
+    'common.clearSelection': '清除选择',
     'common.density': '表格密度',
     'common.densityCompact': '紧凑',
     'common.densityComfortable': '宽松',
@@ -45,7 +46,11 @@ const baseLocales: Record<string, Record<string, string>> = {
     'common.autoSaving': '自动保存中...',
     'common.autoSaved': '已自动保存',
     'common.selectAll': '全选',
+    'common.selectRow': '选择记录 {id}',
     'common.batchDelete': '批量删除 ({count})',
+    'common.selectedCount': '已选择 {count} 条记录',
+    'common.processing': '处理中...',
+    'common.openFullDetail': '完整详情',
     'common.unsavedChanges': '有未保存的修改，确定离开吗？',
     'common.unsaved': '未保存',
     'common.deleteConfirm': '确定要删除这条记录吗？此操作不可撤销。',
@@ -53,9 +58,11 @@ const baseLocales: Record<string, Record<string, string>> = {
     'common.confirmAction': '确认操作',
     'common.operationSuccess': '操作成功',
     'common.operationFailed': '操作失败',
+    'common.accessDenied': '无权查看此记录',
     'common.createSuccess': '创建成功',
     'common.updateSuccess': '更新成功',
     'common.deleteSuccess': '删除成功',
+    'common.actionCanBeUndone': '操作已提交，可在倒计时结束前撤销',
     'common.loginFailed': '登录失败',
     'common.home': '首页',
     'common.logout': '退出登录',
@@ -90,6 +97,11 @@ const baseLocales: Record<string, Record<string, string>> = {
     'common.back': '返回',
     'common.step': '步骤',
     'common.columns': '列',
+    'common.savedViews': '视图',
+    'common.savedViewsHint': '将当前筛选、搜索、排序、分页和列布局保存在此浏览器。',
+    'common.currentView': '当前未保存视图',
+    'common.viewName': '视图名称',
+    'common.saveView': '保存',
     'common.perPage': '每页',
     'common.copyId': '复制 ID',
     'common.showMore': '展开更多',
@@ -670,6 +682,7 @@ const baseLocales: Record<string, Record<string, string>> = {
     'common.delete': 'Delete',
     'common.batchDeletePartialFail': 'Batch delete partially failed: {failed}/{total} unsuccessful',
     'common.batchDeleteSuccess': 'Successfully deleted {count} records',
+    'common.batchDeleteFailed': 'Batch delete failed; {count} records were not deleted',
     'common.selectedItems': '{count} selected',
     'common.clearSelection': 'Clear selection',
     'common.density': 'Table density',
@@ -693,7 +706,11 @@ const baseLocales: Record<string, Record<string, string>> = {
     'common.autoSaving': 'Auto-saving...',
     'common.autoSaved': 'Saved',
     'common.selectAll': 'Select All',
+    'common.selectRow': 'Select record {id}',
     'common.batchDelete': 'Batch Delete ({count})',
+    'common.selectedCount': '{count} records selected',
+    'common.processing': 'Processing...',
+    'common.openFullDetail': 'Full details',
     'common.unsavedChanges': 'You have unsaved changes. Leave anyway?',
     'common.unsaved': 'Unsaved',
     'common.deleteConfirm': 'Are you sure you want to delete this record? This cannot be undone.',
@@ -701,9 +718,11 @@ const baseLocales: Record<string, Record<string, string>> = {
     'common.confirmAction': 'Confirm Action',
     'common.operationSuccess': 'Operation successful',
     'common.operationFailed': 'Operation failed',
+    'common.accessDenied': 'You do not have access to this record',
     'common.createSuccess': 'Created successfully',
     'common.updateSuccess': 'Updated successfully',
     'common.deleteSuccess': 'Deleted successfully',
+    'common.actionCanBeUndone': 'Action submitted. You can undo it before the countdown ends.',
     'common.loginFailed': 'Login failed',
     'common.home': 'Home',
     'common.logout': 'Log out',
@@ -738,6 +757,11 @@ const baseLocales: Record<string, Record<string, string>> = {
     'common.back': 'Back',
     'common.step': 'Step',
     'common.columns': 'Columns',
+    'common.savedViews': 'Views',
+    'common.savedViewsHint': 'Save filters, search, sorting, pagination, and column layout in this browser.',
+    'common.currentView': 'Current unsaved view',
+    'common.viewName': 'View name',
+    'common.saveView': 'Save',
     'common.perPage': 'per page',
     'common.copyId': 'Copy ID',
     'common.showMore': 'Show more',

package/src/index.ts

@@ -70,10 +70,16 @@ export {
 } from './hooks.svelte';
 export { matchRoute, navigate, currentPath, setActiveRouterProvider, beforeEach, afterEach, resetRouter } from './router';
 export type { RouteGuard } from './router';
-export { readURLState, writeURLState } from './url-sync';
+export {
+  appendListQuery,
+  appendListQueryFromPath,
+  readURLState,
+  sanitizeListQueryParams,
+  writeURLState,
+} from './url-sync';
 export { setAccessControlProvider, getAccessControlProvider, getAccessControlOptions, canAccessAsync, createFeatureGate } from './permissions.svelte';
 export { useLive, useSubscription, usePublish } from './live.svelte';
-export { toast, getToastQueue, consumeToastQueue, getPromiseQueue, consumePromiseQueue, resetToast } from './toast.svelte';
+export { toast, getToastQueue, consumeToastQueue, getPromiseQueue, consumePromiseQueue, getToasts, removeToast, resetToast } from './toast.svelte';
 export {
   notify,
   notifyWithProvider,
@@ -120,7 +126,7 @@ export type { AdminOptions, TextTransformers, OvertimeConfig } from './options.s
 export { checkError } from './hook-utils.svelte';
 export type { NotificationConfig, OvertimeOptions, OvertimeResult, LiveSubscriptionParams } from './hook-utils.svelte';
 
-export { HttpError, UndoError } from './types';
+export { DeleteManyPartialError, HttpError, UndoError } from './types';
 export type {
   DataProvider, AuthProvider, NotificationProvider, MutationMode,
   ValidationErrors, HttpErrorOptions, CrudOperator, LogicalFilter, FieldFilter,
@@ -189,6 +195,7 @@ export { TableState } from './table-state.svelte';
 export type { TableStateOptions } from './table-state.svelte';
 export type { UseInfiniteListOptions } from './hooks.svelte';
 export type { UseSelectOptions } from './hooks.svelte';
+export type { UseDeleteManyOptions, UseDeleteManyMutateParams } from './hooks.svelte';
 export type { UseFormReturn } from './form-hooks.svelte';
 export type {
   TaskProvider,

package/src/mutation-hooks.svelte.ts

@@ -91,7 +91,7 @@ interface MutationContext {
   previousQueries?: [readonly unknown[], unknown][];
 }
 
-interface MutationCallbacks {
+export interface MutationCallbacks {
   onMutate?: (variables: unknown) => unknown | Promise<unknown>;
   onSuccess?: (data: unknown, variables: unknown, context: unknown) => void;
   onError?: (error: unknown, variables: unknown, context: unknown) => void;
@@ -464,8 +464,6 @@ export function useDelete<TData extends BaseRecord = BaseRecord, TError = HttpEr
       
       const pk = adminContext.getResource(resName).primaryKey ?? 'id';
       
-      if (targetId != null) queryClient.removeQueries({ predicate: (q) => dataMatch(q.queryKey, { action: 'one', id: targetId }) });
-
       queryClient.setQueriesData({ predicate: (q) => dataMatch(q.queryKey, { action: 'list' }) }, (old: unknown) => {
         if (!old || typeof old !== 'object' || !('data' in old)) return old;
         const o = old as { data: Record<string, unknown>[]; total?: number };

package/src/routing-hooks.svelte.ts

@@ -1,5 +1,6 @@
 import { captureAdminContext } from './context.svelte';
 import { useParsed } from './useParsed.svelte';
+import { sanitizeListQueryParams } from './url-sync';
 
 // ─── routing-hooks.svelte.ts ───────────────────────────────────
 
@@ -118,13 +119,19 @@ export function useResource(resourceName?: string) {
 export function useNavigation() {
   const go = useGo();
   const parsed = useParsed();
+  const listQuery = (resource?: string) => {
+    const target = resource ?? parsed.resourcePath ?? parsed.resource;
+    const targetResource = target?.split('/').filter(Boolean).at(-1);
+    if (targetResource && parsed.resource && targetResource !== parsed.resource) return {};
+    return sanitizeListQueryParams(parsed.params ?? {});
+  };
 
   return {
-    create: (resource?: string) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'create' }),
-    edit: (resource?: string, id?: string | number) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'edit', id: id ?? parsed.id }),
-    clone: (resource?: string, id?: string | number) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'clone', id: id ?? parsed.id }),
-    show: (resource?: string, id?: string | number) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'show', id: id ?? parsed.id }),
-    list: (resource?: string) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'list' }),
+    create: (resource?: string) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'create', query: listQuery(resource) }),
+    edit: (resource?: string, id?: string | number) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'edit', id: id ?? parsed.id, query: listQuery(resource) }),
+    clone: (resource?: string, id?: string | number) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'clone', id: id ?? parsed.id, query: listQuery(resource) }),
+    show: (resource?: string, id?: string | number) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'show', id: id ?? parsed.id, query: listQuery(resource) }),
+    list: (resource?: string) => go({ type: 'push', resource: resource ?? parsed.resourcePath ?? parsed.resource, action: 'list', query: listQuery(resource) }),
     push: (url: string) => go({ to: url, type: 'push' }),
     replace: (url: string) => go({ to: url, type: 'replace' }),
     goBack: useBack(),

package/src/types.ts

@@ -45,6 +45,25 @@ export class UndoError extends Error {
   }
 }
 
+/** Raised when a delete-many fallback removed some records but not all. */
+export class DeleteManyPartialError extends Error {
+  readonly succeededIds: (string | number)[];
+  readonly failedIds: (string | number)[];
+  readonly causes: unknown[];
+
+  constructor(
+    succeededIds: (string | number)[],
+    failedIds: (string | number)[],
+    causes: unknown[] = [],
+  ) {
+    super(`Delete many partially failed: ${failedIds.length}/${succeededIds.length + failedIds.length} failed`);
+    this.name = 'DeleteManyPartialError';
+    this.succeededIds = [...succeededIds];
+    this.failedIds = [...failedIds];
+    this.causes = [...causes];
+  }
+}
+
 // ─── Base Types ───────────────────────────────────────────────
 
 export type BaseRecord = Record<string, unknown>;

package/src/url-sync.ts

@@ -39,6 +39,49 @@ function parseFilters(value: string): Filter[] | undefined {
   }
 }
 
+function positiveIntegerParam(value: string | undefined, max: number): string | undefined {
+  if (!value || !/^\d+$/.test(value)) return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 && parsed <= max ? String(parsed) : undefined;
+}
+
+/**
+ * 保留从列表进入 CRUD 页面时可安全恢复的查询状态。
+ * 未知参数不会跨页面传播，避免把 detail、tenantId 或敏感参数带入记录路由。
+ */
+export function sanitizeListQueryParams(params: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {};
+  const page = positiveIntegerParam(params['page'], 1_000_000);
+  const pageSize = positiveIntegerParam(params['pageSize'], 1_000);
+  const sort = params['sort']?.trim();
+  const search = params['q'];
+  const filters = params['filters'] ? parseFilters(params['filters']) : undefined;
+
+  if (page) result['page'] = page;
+  if (pageSize) result['pageSize'] = pageSize;
+  if (sort && sort.length <= 256) {
+    result['sort'] = sort;
+    if (params['order'] === 'asc' || params['order'] === 'desc') result['order'] = params['order'];
+  }
+  if (search && search.length <= 1_000) result['q'] = search;
+  if (filters) result['filters'] = JSON.stringify(filters);
+  if (params['records'] === '1') result['records'] = '1';
+
+  return result;
+}
+
+export function appendListQuery(path: string, params: Record<string, string>): string {
+  const query = new URLSearchParams(sanitizeListQueryParams(params)).toString();
+  if (!query) return path;
+  return `${path}${path.includes('?') ? '&' : '?'}${query}`;
+}
+
+export function appendListQueryFromPath(path: string, currentPath: string): string {
+  const queryString = currentPath.split('?')[1];
+  if (!queryString) return path;
+  return appendListQuery(path, Object.fromEntries(new URLSearchParams(queryString)));
+}
+
 export interface URLState {
   page?: number;
   pageSize?: number;
@@ -46,6 +89,7 @@ export interface URLState {
   sortOrder?: 'asc' | 'desc';
   search?: string;
   filters?: Filter[];
+  detailId?: string;
 }
 
 export function readURLState(adminContext: AdminContextAccessor = captureAdminContext()): URLState {
@@ -77,12 +121,16 @@ export function readURLState(adminContext: AdminContextAccessor = captureAdminCo
     if (filters) state.filters = filters;
   }
 
+  const detailId = params['detail'];
+  if (detailId) state.detailId = detailId;
+
   return state;
 }
 
 export function writeURLState(
   state: URLState,
   adminContext: AdminContextAccessor = captureAdminContext(),
+  type: 'push' | 'replace' = 'replace',
 ): void {
   if (typeof window === 'undefined') return;
   const rp = adminContext.routerProvider;
@@ -124,6 +172,11 @@ export function writeURLState(
     }
   }
 
+  if ('detailId' in state) {
+    if (state.detailId) params['detail'] = state.detailId;
+    else delete params['detail'];
+  }
+
   // Prevent redundant navigation if nothing actually changed
   const qsOld = new URLSearchParams(current.params).toString();
   const qsNew = new URLSearchParams(params).toString();
@@ -132,7 +185,7 @@ export function writeURLState(
     rp.go({
       to: current.pathname,
       query: params,
-      type: 'replace'
+      type,
     });
   }
 }