@kine-design/crud 0.0.1-beta.2 → 0.0.1-beta.21

package/composables/router/types.ts

@@ -0,0 +1,128 @@
+/**
+ * @description 路由管理层类型定义
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+// ────────────────────────────────────────────────────────────────────────────
+// 路由 meta 约定
+// ────────────────────────────────────────────────────────────────────────────
+
+/** CRUD 路由 meta 约定，注入到 vue-router RouteRecordRaw.meta */
+export interface CrudRouteMeta {
+  /** CRUD 操作类型声明 */
+  crud?: {
+    /** 实体名，如 'Order'、'User' */
+    entity: string;
+    /** 操作类型 */
+    op: 'list' | 'new' | 'modify' | 'detail';
+  };
+  /** 权限声明，供鉴权守卫使用 */
+  can?: {
+    /** 权限资源名 */
+    resource: string;
+    /** 操作名 */
+    action: string;
+  };
+  /** 是否需要登录，默认 true */
+  requiresAuth?: boolean;
+  /** 页面标题（面包屑、tab 标题用） */
+  title?: string;
+  /** 图标标识 */
+  icon?: string;
+  /** 是否缓存组件（keep-alive），默认 false */
+  keepAlive?: boolean;
+  /** 不显示在菜单中，默认 false */
+  hidden?: boolean;
+  /** 菜单排序权重，数值越小越靠前 */
+  sort?: number;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// defineCrudRoutes 配置
+// ────────────────────────────────────────────────────────────────────────────
+
+/** defineCrudRoutes 输入配置 */
+export interface CrudRouteConfig {
+  /** 实体名，如 'Order'、'User'，用于 meta.crud.entity 和路由 name 前缀 */
+  name: string;
+  /** 基础路径，如 '/order' */
+  path: string;
+  /** 页面标题，用于自动生成各操作页面的 meta.title */
+  title?: string;
+  /** 图标标识，自动继承到各操作路由的 meta.icon */
+  icon?: string;
+  /** 列表页组件动态导入函数 */
+  list?: () => Promise<unknown>;
+  /** 新建页组件动态导入函数 */
+  new?: () => Promise<unknown>;
+  /** 编辑页组件动态导入函数 */
+  modify?: () => Promise<unknown>;
+  /** 详情页组件动态导入函数 */
+  detail?: () => Promise<unknown>;
+  /** 权限资源名，默认取 name.toLowerCase() */
+  permission?: string;
+}
+
+/**
+ * 兼容 vue-router RouteRecordRaw 结构的普通对象类型。
+ * 不直接引入 vue-router，避免强绑定。
+ */
+export interface CrudRouteRecord {
+  /** 路由路径 */
+  path: string;
+  /** 路由名称 */
+  name: string;
+  /** 组件动态导入函数 */
+  component: () => Promise<unknown>;
+  /** 路由 meta */
+  meta: CrudRouteMeta;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Tab 管理
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 路由 tab 项 */
+export interface TabItem {
+  /** 路由完整路径，作为唯一标识 */
+  path: string;
+  /** tab 显示标题 */
+  title: string;
+  /** 组件 name，用于 keep-alive include 列表 */
+  name: string;
+  /** 是否可关闭 */
+  closable: boolean;
+}
+
+/** 最小化路由位置信息，用于 addTabFromRoute */
+export interface RouteLocationLike {
+  path: string;
+  name?: string | symbol;
+  meta: CrudRouteMeta & Record<string, unknown>;
+}
+
+/** useTabStore 返回的 store 实例 */
+export interface TabStore {
+  /** 当前已打开的 tab 列表 */
+  tabs: import('vue').Ref<TabItem[]>;
+  /** 当前激活的 tab path */
+  activeTab: import('vue').Ref<string>;
+  /** 用于 keep-alive :include 绑定的组件名列表 */
+  cachedNames: import('vue').ComputedRef<string[]>;
+  /** 添加 tab，已存在时仅激活 */
+  addTab: (tab: TabItem) => void;
+  /** 从路由对象自动提取 title/path/name 创建 tab */
+  addTabFromRoute: (route: RouteLocationLike) => void;
+  /** 关闭指定 tab，自动激活相邻 tab，返回应导航到的路径（无需导航时返回 undefined） */
+  removeTab: (path: string) => string | undefined;
+  /** 关闭除指定路径之外的所有可关闭 tab */
+  removeOthers: (path: string) => void;
+  /** 关闭所有可关闭 tab，保留不可关闭的 */
+  removeAll: () => void;
+  /** 切换激活的 tab */
+  setActive: (path: string) => void;
+}

package/composables/router/useMenuFromRoutes.ts

@@ -0,0 +1,109 @@
+/**
+ * @description 从路由配置自动生成导航菜单数据
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import { computed, type ComputedRef } from 'vue';
+import type { NavMenuData } from '../../components/navMenu';
+import type { CrudRouteMeta } from './types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 局部类型（不引入 vue-router 依赖）
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 最小化 RouteRecordRaw，只声明本文件用到的字段 */
+interface RouteRecord {
+  path: string;
+  name?: string | symbol;
+  meta?: CrudRouteMeta & Record<string, unknown>;
+  children?: RouteRecord[];
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// useMenuFromRoutes
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 从 vue-router 路由配置自动生成 KNavMenu 所需的菜单数据。
+ *
+ * - 过滤 meta.hidden === true 的路由
+ * - 用 meta.title 作为 label，meta.icon 作为 icon
+ * - 支持嵌套路由 → 嵌套菜单
+ * - 按 meta.sort 升序排序（未设置排序权重的排在最后）
+ *
+ * @param routes 路由配置数组（RouteRecordRaw[]）
+ * @returns 响应式菜单数据
+ *
+ * @example
+ * ```ts
+ * import { useMenuFromRoutes } from '@kine-design/crud';
+ *
+ * const menuData = useMenuFromRoutes(router.getRoutes());
+ * ```
+ */
+export function useMenuFromRoutes(routes: RouteRecord[]): ComputedRef<NavMenuData[]> {
+  return computed(() => transformRoutes(routes));
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部辅助
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 递归转换路由 → 菜单数据 */
+function transformRoutes(routes: RouteRecord[]): NavMenuData[] {
+  const result: NavMenuData[] = [];
+
+  for (const route of routes) {
+    const meta = route.meta;
+
+    // 隐藏路由不生成菜单
+    if (meta?.hidden) continue;
+
+    // 没有 title 的路由无法显示，跳过
+    const label = meta?.title;
+    if (!label) continue;
+
+    const key = typeof route.name === 'string' ? route.name : route.path;
+
+    const item: NavMenuData = {
+      key,
+      label,
+      path: route.path,
+      icon: meta?.icon,
+    };
+
+    // 递归处理子路由
+    if (route.children?.length) {
+      const children = transformRoutes(route.children);
+      if (children.length > 0) {
+        item.children = children;
+        // 有子菜单的分类节点不设置 path（避免点击跳转）
+        delete item.path;
+      }
+    }
+
+    result.push(item);
+  }
+
+  // 按 meta.sort 升序排序，未设置的排到最后
+  return result.sort((a, b) => {
+    const sortA = findSort(routes, a.key);
+    const sortB = findSort(routes, b.key);
+    return sortA - sortB;
+  });
+}
+
+/** 从路由配置中查找对应 key 的排序权重 */
+function findSort(routes: RouteRecord[], key: string | number): number {
+  for (const route of routes) {
+    const routeKey = typeof route.name === 'string' ? route.name : route.path;
+    if (routeKey === key) {
+      return route.meta?.sort ?? Infinity;
+    }
+  }
+  return Infinity;
+}

package/composables/router/useTabStore.ts

@@ -0,0 +1,183 @@
+/**
+ * @description 路由 tab 管理 — 基于 provide/inject，支持 keep-alive
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import {
+  ref,
+  computed,
+  provide,
+  inject,
+  type InjectionKey,
+} from 'vue';
+import type { TabItem, TabStore, RouteLocationLike } from './types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// Injection key
+// ────────────────────────────────────────────────────────────────────────────
+
+const TAB_STORE_KEY: InjectionKey<TabStore> = Symbol('tab-store');
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部：创建 store 实例
+// ────────────────────────────────────────────────────────────────────────────
+
+function createTabStoreInstance(): TabStore {
+  const tabs = ref<TabItem[]>([]);
+  const activeTab = ref<string>('');
+
+  /** keep-alive include 列表，只缓存当前打开的 tab 对应的组件 */
+  const cachedNames = computed<string[]>(() =>
+    tabs.value.map(tab => tab.name),
+  );
+
+  /**
+   * 添加 tab。
+   * - 已存在（path 相同）：仅激活，不重复添加
+   * - 不存在：追加到列表末尾并激活
+   */
+  const addTab = (tab: TabItem): void => {
+    const exists = tabs.value.some(t => t.path === tab.path);
+    if (!exists) {
+      tabs.value.push(tab);
+    }
+    activeTab.value = tab.path;
+  };
+
+  /**
+   * 从路由对象自动提取信息创建 tab。
+   * 自动从 meta.title 取标题，从 route.name 取组件名。
+   */
+  const addTabFromRoute = (route: RouteLocationLike): void => {
+    const meta = route.meta;
+    const title = meta.title ?? (typeof route.name === 'string' ? route.name : route.path);
+    const name = typeof route.name === 'string' ? route.name : route.path;
+
+    addTab({
+      path: route.path,
+      title,
+      name,
+      closable: true,
+    });
+  };
+
+  /**
+   * 关闭指定 tab。
+   * - 关闭后自动激活相邻 tab（优先后一个，其次前一个）
+   * - 不可关闭的 tab 忽略此操作
+   * - 返回应导航到的路径（当关闭的是当前激活 tab 时），无需导航返回 undefined
+   */
+  const removeTab = (path: string): string | undefined => {
+    const index = tabs.value.findIndex(t => t.path === path);
+    if (index === -1) return undefined;
+
+    const target = tabs.value[index];
+    if (!target.closable) return undefined;
+
+    tabs.value.splice(index, 1);
+
+    // 激活相邻 tab，并返回导航目标
+    if (activeTab.value === path) {
+      const nextTab = tabs.value[index] ?? tabs.value[index - 1];
+      activeTab.value = nextTab ? nextTab.path : '';
+      return activeTab.value || undefined;
+    }
+
+    return undefined;
+  };
+
+  /**
+   * 关闭除指定 path 之外的所有可关闭 tab。
+   * 不可关闭的 tab 始终保留。
+   */
+  const removeOthers = (path: string): void => {
+    tabs.value = tabs.value.filter(t => !t.closable || t.path === path);
+    // 若当前激活的 tab 被关闭，则激活保留的目标 tab
+    if (!tabs.value.some(t => t.path === activeTab.value)) {
+      activeTab.value = path;
+    }
+  };
+
+  /**
+   * 关闭所有可关闭 tab，保留不可关闭的（如首页/固定 tab）。
+   */
+  const removeAll = (): void => {
+    tabs.value = tabs.value.filter(t => !t.closable);
+    // 激活第一个保留的 tab，若全部清空则置空
+    const first = tabs.value[0];
+    activeTab.value = first ? first.path : '';
+  };
+
+  /** 切换激活的 tab */
+  const setActive = (path: string): void => {
+    activeTab.value = path;
+  };
+
+  return {
+    tabs,
+    activeTab,
+    cachedNames,
+    addTab,
+    addTabFromRoute,
+    removeTab,
+    removeOthers,
+    removeAll,
+    setActive,
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 公开 API
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 在 App 根组件（或布局组件）调用，创建并 provide 全局 tab store 实例。
+ *
+ * @example
+ * ```vue
+ * <!-- App.vue -->
+ * <script setup>
+ * import { createTabStore } from '@kine-design/crud';
+ * const tabStore = createTabStore();
+ * </script>
+ *
+ * <template>
+ *   <router-view v-slot="{ Component }">
+ *     <keep-alive :include="tabStore.cachedNames.value">
+ *       <component :is="Component" />
+ *     </keep-alive>
+ *   </router-view>
+ * </template>
+ * ```
+ */
+export function createTabStore(): TabStore {
+  const store = createTabStoreInstance();
+  provide(TAB_STORE_KEY, store);
+  return store;
+}
+
+/**
+ * 在子组件中 inject 使用 tab store。
+ * 必须在 createTabStore() 调用的后代组件中使用。
+ *
+ * @throws 若在 createTabStore() 之外的组件树中调用，会抛出错误提示
+ *
+ * @example
+ * ```ts
+ * const tabStore = useTabStore();
+ * tabStore.addTab({ path: '/order', title: '订单列表', name: 'Order', closable: true });
+ * ```
+ */
+export function useTabStore(): TabStore {
+  const store = inject(TAB_STORE_KEY);
+  if (!store) {
+    throw new Error(
+      '[useTabStore] 未找到 tab store 实例，请确保在父级组件中调用了 createTabStore()',
+    );
+  }
+  return store;
+}

package/composables/search/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @description search composables barrel export
+ * @author 阿怪
+ * @date 2026/3/22
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export { useAutoCompleteSearch } from './useAutoCompleteSearch';
+export type { AutoCompleteSearchOptions, AutoCompleteSearchReturn } from './useAutoCompleteSearch';

package/composables/search/useAutoCompleteSearch.ts

@@ -0,0 +1,161 @@
+/**
+ * @description AutoComplete 搜索 hook — 基于 defineRepository 的 useList，为 KAutoComplete 提供搜索能力
+ * @author 阿怪
+ * @date 2026/3/22
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * 将孟加拉项目的 useAutoComplete 升级：
+ * - 不再直接传 getList 函数，而是传 requestClient + api 路径
+ * - 统一使用 crud 层的请求体系
+ * - 返回 KAutoComplete 组件可直接消费的 props
+ */
+
+import { ref, shallowRef, type Ref, type ShallowRef } from 'vue';
+import { useRequestClient } from '../../setup';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 类型
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface AutoCompleteSearchOptions<T = any> {
+  /** API 路径，如 '/supplier' */
+  api: string;
+  /** 搜索参数名，如 'nameLike'，输入值会赋给这个 key */
+  searchKey: string;
+  /** 显示字段名，如 'supplierName'，用于回填输入框 */
+  labelKey: string;
+  /** 值字段名，默认 'id' */
+  valueKey?: string;
+  /** 每次搜索返回条数，默认 5 */
+  pageSize?: number;
+  /** 额外的固定查询参数 */
+  extraParams?: Record<string, unknown>;
+  /** 自定义过滤函数 */
+  filter?: (item: T) => boolean;
+  /** 自定义映射函数，将 API 返回的数据转换为 AutoComplete 需要的格式 */
+  mapFn?: (item: T) => { label: string; value: string | number; raw: T };
+}
+
+export interface AutoCompleteSearchReturn<T = any> {
+  /** 输入框绑定值 */
+  inputValue: Ref<string>;
+  /** 建议列表 */
+  suggestions: ShallowRef<Array<{ label: string; value: string | number; raw: T }>>;
+  /** 加载状态 */
+  loading: Ref<boolean>;
+  /** 当前选中的原始数据 */
+  selected: ShallowRef<T | null>;
+  /** 搜索回调，绑定给 KAutoComplete 的 onSearch / fetchSuggestions */
+  onSearch: (query: string) => Promise<void>;
+  /** 选中回调 */
+  onSelect: (item: { label: string; value: string | number; raw: T }) => void;
+  /** 清空选中 */
+  onClear: () => void;
+  /** 手动设置选中值（用于表单回填） */
+  setValue: (label: string, data: T | null) => void;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 实现
+// ────────────────────────────────────────────────────────────────────────────
+
+export function useAutoCompleteSearch<T = any>(
+  options: AutoCompleteSearchOptions<T>,
+): AutoCompleteSearchReturn<T> {
+  const {
+    api,
+    searchKey,
+    labelKey,
+    valueKey = 'id',
+    pageSize = 5,
+    extraParams,
+    filter,
+    mapFn,
+  } = options;
+
+  const client = useRequestClient();
+
+  const inputValue = ref('');
+  const suggestions = shallowRef([]) as ShallowRef<Array<{ label: string; value: string | number; raw: T }>>;
+  const loading = ref(false);
+  const selected = shallowRef(null) as ShallowRef<T | null>;
+
+  /** 默认映射函数 */
+  const defaultMapFn = (item: T): { label: string; value: string | number; raw: T } => ({
+    label: String((item as any)[labelKey] ?? ''),
+    value: (item as any)[valueKey],
+    raw: item,
+  });
+
+  const mapper = mapFn ?? defaultMapFn;
+
+  /** 执行搜索 */
+  const onSearch = async (query: string) => {
+    loading.value = true;
+    try {
+      const params: Record<string, unknown> = {
+        page: 1,
+        pageSize,
+        ...extraParams,
+      };
+
+      if (query) {
+        params[searchKey] = query;
+      }
+
+      const res = await client.get<any>(api, { params });
+      let list: T[] = [];
+
+      // 兼容 { data: { data: [...] } } 和 { data: [...] } 两种返回格式
+      if (res?.data?.data && Array.isArray(res.data.data)) {
+        list = res.data.data;
+      } else if (res?.data && Array.isArray(res.data)) {
+        list = res.data;
+      } else if (Array.isArray(res)) {
+        list = res;
+      }
+
+      if (filter) {
+        list = list.filter(filter);
+      }
+
+      suggestions.value = list.map(mapper);
+    } catch {
+      suggestions.value = [];
+    } finally {
+      loading.value = false;
+    }
+  };
+
+  /** 选中项 */
+  const onSelect = (item: { label: string; value: string | number; raw: T }) => {
+    selected.value = item.raw;
+    inputValue.value = item.label;
+  };
+
+  /** 清空 */
+  const onClear = () => {
+    selected.value = null;
+    inputValue.value = '';
+    suggestions.value = [];
+  };
+
+  /** 手动设置值（编辑页回填） */
+  const setValue = (label: string, data: T | null) => {
+    inputValue.value = label;
+    selected.value = data;
+  };
+
+  return {
+    inputValue,
+    suggestions,
+    loading,
+    selected,
+    onSearch,
+    onSelect,
+    onClear,
+    setValue,
+  };
+}

package/composables/setupCrud.ts

@@ -0,0 +1,43 @@
+/**
+ * @description @kine-design/crud 一键安装函数，注册 VueQueryPlugin
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { App } from 'vue';
+import { VueQueryPlugin, type VueQueryPluginOptions } from '@tanstack/vue-query';
+
+/**
+ * 在 Vue App 实例上安装 CRUD 基础设施（TanStack Query）。
+ *
+ * @example
+ * ```ts
+ * // main.ts
+ * import { createApp } from 'vue';
+ * import { setupCrud } from '@kine-design/crud';
+ *
+ * const app = createApp(App);
+ * setupCrud(app);
+ * app.mount('#app');
+ * ```
+ */
+export function setupCrud(app: App, options?: VueQueryPluginOptions): void {
+  app.use(VueQueryPlugin, {
+    queryClientConfig: {
+      defaultOptions: {
+        queries: {
+          // 窗口重新聚焦时不自动重新请求，业务层按需覆盖
+          refetchOnWindowFocus: false,
+          // 失败后重试 1 次
+          retry: 1,
+          // 数据保鲜时间 1 分钟
+          staleTime: 1000 * 60,
+        },
+      },
+    },
+    ...options,
+  });
+}