feat: 统一恢复管理端列表上下文

- 统一列表路由状态、分页初始化与安全返回契约

- 接入知识库、工作流、插件、审批、Skill、Agent、Bot、反馈和定时任务链路

- 补齐公共能力与关键返回路径自动化测试

easyflow-ui-admin/app/src/router/__tests__/detail-return-navigation.test.ts

@@ -1,78 +1,59 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
 import { describe, expect, it } from 'vitest';
 
 function readViewSource(relativePath: string) {
-  return readFileSync(resolve('app/src/views', relativePath), 'utf8');
+  const workspaceViews = resolve('app/src/views');
+  const viewsRoot = existsSync(workspaceViews)
+    ? workspaceViews
+    : resolve('src/views');
+  return readFileSync(resolve(viewsRoot, relativePath), 'utf8');
 }
 
 describe('detail return navigation', () => {
   it.each([
-    ['system/sysFeedback/sysFeedbackDetail.vue', '/sys/sysFeedback'],
-    ['system/sysJob/SysJobLogList.vue', '/sys/sysJob'],
-    ['ai/workflow/WorkflowDesign.vue', '/ai/workflow'],
-    ['ai/workflow/components/WorkflowChatPage.vue', '/ai/workflow'],
-    ['ai/workflow/execute/WorkflowExecResultList.vue', '/ai/workflow'],
-  ])('returns %s to its fixed parent list', (relativePath, parentPath) => {
-    const source = readViewSource(relativePath);
+    [
+      'ai/documentCollection/DocumentCollection.vue',
+      'ai/documentCollection/Document.vue',
+    ],
+    ['ai/skill/SkillList.vue', 'ai/skill/SkillDetail.vue'],
+    ['ai/agents/AgentList.vue', 'ai/agents/AgentDesigner.vue'],
+    ['ai/bots/index.vue', 'ai/bots/pages/setting/index.vue'],
+    [
+      'system/approval/ApprovalManage.vue',
+      'system/approval/ApprovalDetail.vue',
+    ],
+    ['system/sysJob/SysJobList.vue', 'system/sysJob/SysJobLogList.vue'],
+    [
+      'system/sysFeedback/sysFeedbackList.vue',
+      'system/sysFeedback/sysFeedbackDetail.vue',
+    ],
+    ['ai/workflow/WorkflowList.vue', 'ai/workflow/WorkflowDesign.vue'],
+    [
+      'ai/workflow/WorkflowList.vue',
+      'ai/workflow/components/WorkflowChatPage.vue',
+    ],
+    ['ai/plugin/Plugin.vue', 'ai/plugin/PluginTools.vue'],
+    ['ai/plugin/PluginToolTable.vue', 'ai/plugin/PluginToolEdit.vue'],
+  ])(
+    'passes an exact return target from %s and validates it in %s',
+    (listPath, detailPath) => {
+      expect(readViewSource(listPath)).toContain('withListReturnTo');
+      expect(readViewSource(detailPath)).toContain('navigateBackToList');
+    },
+  );
 
-    expect(source).not.toMatch(/router\.(?:back|go)\s*\(/);
-    expect(source).toContain(`path: '${parentPath}'`);
-  });
-
-  it('returns approval details to the originating approval tab', () => {
-    const detailSource = readViewSource('system/approval/ApprovalDetail.vue');
-    const listSource = readViewSource('system/approval/ApprovalManage.vue');
-
-    expect(detailSource).not.toMatch(/router\.(?:back|go)\s*\(/);
-    expect(detailSource).toContain("path: '/sys/approval'");
-    expect(detailSource).toContain('query: { tab }');
-    expect(listSource).toContain('tab: activeTab.value');
-  });
-
-  it('returns workflow design to the originating list page and filters', () => {
-    const detailSource = readViewSource('ai/workflow/WorkflowDesign.vue');
-    const listSource = readViewSource('ai/workflow/WorkflowList.vue');
-
-    expect(detailSource).toContain(
-      'parseWorkflowDesignReturnState(route.query)',
-    );
-    expect(detailSource).toContain(
-      'query: buildWorkflowListRouteQuery(listState)',
-    );
-    expect(listSource).toContain('buildWorkflowDesignReturnQuery');
-    expect(listSource).toContain('getPageState');
-  });
-
-  it('returns plugin tool editing to its plugin tool list with a safe fallback', () => {
-    const editSource = readViewSource('ai/plugin/PluginToolEdit.vue');
-    const toolsSource = readViewSource('ai/plugin/PluginTools.vue');
-    const pluginListSource = readViewSource('ai/plugin/Plugin.vue');
-    const listSource = readViewSource('ai/plugin/PluginToolTable.vue');
-
-    expect(editSource).not.toMatch(/router\.(?:back|go)\s*\(/);
-    expect(editSource).toContain("path: '/ai/plugin/tools'");
-    expect(editSource).toContain("path: '/ai/plugin'");
-    expect(editSource).toContain('buildPluginToolsRouteQueryFromEdit');
-    expect(toolsSource).toContain('parsePluginToolsReturnState');
-    expect(toolsSource).toContain('buildPluginListRouteQuery');
-    expect(pluginListSource).toContain('buildPluginToolsReturnQuery');
-    expect(listSource).toContain('pluginId: props.pluginId');
-    expect(listSource).toContain('...route.query');
-  });
-
-  it('returns execution steps to the filtered execution record list', () => {
-    const stepSource = readViewSource(
-      'ai/workflow/execute/WorkflowExecStepList.vue',
-    );
+  it('preserves the nested execution-record list before opening a step', () => {
     const recordSource = readViewSource(
       'ai/workflow/execute/WorkflowExecResultList.vue',
     );
+    const stepSource = readViewSource(
+      'ai/workflow/execute/WorkflowExecStepList.vue',
+    );
 
-    expect(stepSource).not.toMatch(/router\.(?:back|go)\s*\(/);
-    expect(stepSource).toContain("name: 'ExecRecord'");
-    expect(stepSource).toContain('query: workflowId ? { workflowId } : {}');
-    expect(recordSource).toContain('workflowId: $route.query.workflowId');
+    expect(recordSource).toContain('withListReturnTo(currentListFullPath())');
+    expect(stepSource).toContain('navigateBackToList');
+    expect(stepSource).toContain("['/ai/workflow/executeRecords']");
   });
 });

easyflow-ui-admin/app/src/router/list-return-context.test.ts

@@ -0,0 +1,54 @@
+import { createMemoryHistory, createRouter } from 'vue-router';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  readListReturnTo,
+  resolveListReturnPath,
+  withListReturnTo,
+} from './list-return-context';
+
+function createTestRouter() {
+  return createRouter({
+    history: createMemoryHistory(),
+    routes: [
+      { component: {}, path: '/items' },
+      { component: {}, path: '/other' },
+    ],
+  });
+}
+
+describe('list return context', () => {
+  it('round trips an exact internal list URL', () => {
+    const router = createTestRouter();
+    const query = withListReturnTo('/items?pageNumber=4&keyword=月报', {
+      id: '7',
+    });
+
+    expect(readListReturnTo(query as any)).toBe(
+      '/items?pageNumber=4&keyword=月报',
+    );
+    expect(
+      resolveListReturnPath(router, query as any, ['/items'], '/items'),
+    ).toBe('/items?pageNumber=4&keyword=月报');
+  });
+
+  it.each([
+    'https://example.com/items?pageNumber=4',
+    '//example.com/items?pageNumber=4',
+    '/other?pageNumber=4',
+    '/missing?pageNumber=4',
+    '/items#unsafe',
+    String.raw`/items\unsafe`,
+    `/items?value=${'x'.repeat(4096)}`,
+  ])('rejects an unsafe or unrelated return target: %s', (returnTo) => {
+    expect(
+      resolveListReturnPath(
+        createTestRouter(),
+        { returnTo },
+        ['/items'],
+        '/items',
+      ),
+    ).toBe('/items');
+  });
+});

easyflow-ui-admin/app/src/router/list-return-context.ts

@@ -0,0 +1,105 @@
+import type { LocationQuery, LocationQueryRaw, Router } from 'vue-router';
+
+const LIST_RETURN_QUERY_KEY = 'returnTo';
+const MAX_LIST_RETURN_LENGTH = 4096;
+
+function hasUnsafeReturnCharacter(value: string): boolean {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0) || 0;
+    if (character === '\\' || codePoint <= 31 || codePoint === 127) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function readListReturnTo(query: LocationQuery): string {
+  const value = query[LIST_RETURN_QUERY_KEY];
+  const normalized = Array.isArray(value) ? value[0] : value;
+  return normalized === null || normalized === undefined
+    ? ''
+    : String(normalized);
+}
+
+function withListReturnTo(
+  returnTo: string,
+  query: LocationQueryRaw = {},
+): LocationQueryRaw {
+  return {
+    ...query,
+    [LIST_RETURN_QUERY_KEY]: returnTo,
+  };
+}
+
+function resolveListReturnPath(
+  router: Router,
+  query: LocationQuery,
+  allowedListPaths: readonly string[],
+  fallbackPath: string,
+): string {
+  const raw = readListReturnTo(query);
+  if (
+    !raw ||
+    raw.length > MAX_LIST_RETURN_LENGTH ||
+    !raw.startsWith('/') ||
+    raw.startsWith('//') ||
+    hasUnsafeReturnCharacter(raw)
+  ) {
+    return fallbackPath;
+  }
+
+  try {
+    const parsed = new URL(raw, 'https://easyflow.local');
+    if (parsed.origin !== 'https://easyflow.local' || parsed.hash) {
+      return fallbackPath;
+    }
+    if (!allowedListPaths.includes(parsed.pathname)) {
+      return fallbackPath;
+    }
+    const resolved = router.resolve(raw);
+    return resolved.matched.length > 0 ? resolved.fullPath : fallbackPath;
+  } catch {
+    return fallbackPath;
+  }
+}
+
+function resolveHistoryBackPath(router: Router): string {
+  if (typeof window === 'undefined') return '';
+  const raw = window.history.state?.back;
+  if (typeof raw !== 'string' || !raw) return '';
+  const hashIndex = raw.indexOf('#');
+  const candidate = hashIndex === -1 ? raw : raw.slice(hashIndex + 1);
+  if (!candidate.startsWith('/')) return '';
+  try {
+    return router.resolve(candidate).fullPath;
+  } catch {
+    return '';
+  }
+}
+
+async function navigateBackToList(
+  router: Router,
+  query: LocationQuery,
+  allowedListPaths: readonly string[],
+  fallbackPath: string,
+): Promise<void> {
+  const target = resolveListReturnPath(
+    router,
+    query,
+    allowedListPaths,
+    fallbackPath,
+  );
+  if (resolveHistoryBackPath(router) === target) {
+    router.back();
+    return;
+  }
+  await router.replace(target);
+}
+
+export {
+  LIST_RETURN_QUERY_KEY,
+  navigateBackToList,
+  readListReturnTo,
+  resolveListReturnPath,
+  withListReturnTo,
+};