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

package/composables/form/useFormPage.ts

@@ -0,0 +1,183 @@
+/**
+ * @description useFormPage — 表单页数据管理 hook
+ * @author 阿怪
+ * @date 2026/3/22
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * 管理表单页的数据加载、字段状态、校验、提交。
+ * KFormPage 和 KMasterDetailPage 共用。
+ */
+
+import { ref, reactive, computed, onMounted, type Ref } from 'vue';
+import { useRoute, useRouter } from 'vue-router';
+import { useRequestClient } from '../../setup';
+import type { FormFieldConfig } from './types';
+
+export interface UseFormPageOptions {
+  /** API 路径 */
+  api: string;
+  /** 字段配置 */
+  fields: FormFieldConfig[];
+  /** 主键字段 */
+  rowKey?: string;
+  /** 保存成功后跳转路径 */
+  redirectPath?: string;
+}
+
+export interface UseFormPageReturn {
+  /** 表单数据 */
+  formData: Record<string, unknown>;
+  /** 是否编辑模式（路由有 id） */
+  isEdit: Ref<boolean>;
+  /** 加载中 */
+  loading: Ref<boolean>;
+  /** 提交中 */
+  submitting: Ref<boolean>;
+  /** 字段错误信息 */
+  errors: Ref<Record<string, string>>;
+  /** 校验全部字段 */
+  validate: () => boolean;
+  /** 校验单个字段 */
+  validateField: (param: string) => string | undefined;
+  /** 提交表单 */
+  submit: (extraData?: Record<string, unknown>) => Promise<boolean>;
+  /** 保存草稿（不校验必填） */
+  saveDraft: (extraData?: Record<string, unknown>) => Promise<boolean>;
+  /** 返回上一页 */
+  goBack: () => void;
+  /** 路由实例 */
+  router: ReturnType<typeof useRouter>;
+}
+
+export function useFormPage(options: UseFormPageOptions): UseFormPageReturn {
+  const { api, fields, rowKey = 'id', redirectPath } = options;
+
+  const route = useRoute();
+  const router = useRouter();
+  const client = useRequestClient();
+
+  const id = computed(() => route.params[rowKey] as string | undefined);
+  const isEdit = computed(() => !!id.value);
+
+  const loading = ref(false);
+  const submitting = ref(false);
+  const errors = ref<Record<string, string>>({});
+
+  // 初始化表单数据
+  const formData: Record<string, unknown> = reactive(
+    Object.fromEntries(fields.map(f => [f.param, f.type === 'switch' ? false : '']))
+  );
+
+  // ── 数据加载（编辑模式） ──────────────────────────
+
+  const loadData = async () => {
+    if (!id.value) return;
+    loading.value = true;
+    try {
+      const res = await client.get<any>(`${api}/${id.value}`);
+      const data = res?.data?.data ?? res?.data ?? res;
+      if (data && typeof data === 'object') {
+        for (const key of Object.keys(formData)) {
+          if (key in data) {
+            formData[key] = data[key];
+          }
+        }
+      }
+    } finally {
+      loading.value = false;
+    }
+  };
+
+  onMounted(() => {
+    if (isEdit.value) loadData();
+  });
+
+  // ── 校验 ──────────────────────────────────────────
+
+  const validateField = (param: string): string | undefined => {
+    const field = fields.find(f => f.param === param);
+    if (!field) return;
+
+    const value = formData[param];
+
+    // 自定义校验
+    if (field.validator) {
+      const msg = field.validator(value, formData);
+      if (msg) {
+        errors.value[param] = msg;
+        return msg;
+      }
+    }
+
+    // 必填校验
+    if (field.required) {
+      if (value === undefined || value === null || value === '') {
+        const msg = `请输入${field.label}`;
+        errors.value[param] = msg;
+        return msg;
+      }
+    }
+
+    // 清除错误
+    delete errors.value[param];
+    return undefined;
+  };
+
+  const validate = (): boolean => {
+    let valid = true;
+    for (const field of fields) {
+      const msg = validateField(field.param);
+      if (msg) valid = false;
+    }
+    return valid;
+  };
+
+  // ── 提交 ──────────────────────────────────────────
+
+  const doSubmit = async (skipRequiredCheck: boolean, extraData?: Record<string, unknown>): Promise<boolean> => {
+    if (!skipRequiredCheck && !validate()) return false;
+
+    submitting.value = true;
+    try {
+      const payload = { ...formData, ...extraData };
+
+      if (isEdit.value) {
+        await client.put(`${api}/${id.value}`, payload);
+      } else {
+        await client.post(api, payload);
+      }
+
+      if (redirectPath) {
+        router.push(redirectPath);
+      } else {
+        router.back();
+      }
+      return true;
+    } catch {
+      return false;
+    } finally {
+      submitting.value = false;
+    }
+  };
+
+  const submit = (extraData?: Record<string, unknown>) => doSubmit(false, extraData);
+  const saveDraft = (extraData?: Record<string, unknown>) => doSubmit(true, { ...extraData, status: 'draft' });
+
+  const goBack = () => router.back();
+
+  return {
+    formData,
+    isEdit,
+    loading,
+    submitting,
+    errors,
+    validate,
+    validateField,
+    submit,
+    saveDraft,
+    goBack,
+    router,
+  };
+}

package/composables/index.ts

@@ -0,0 +1,62 @@
+/**
+ * @description composables barrel export
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export { defineRepository } from './defineRepository';
+
+export { useAutoCompleteSearch } from './search';
+export type { AutoCompleteSearchOptions, AutoCompleteSearchReturn } from './search';
+export { setupCrud } from './setupCrud';
+export type {
+  EntityId,
+  ListParams,
+  MutationOptions,
+  Repository,
+  RepositoryEndpoints,
+  UseListReturn,
+  UseDetailReturn,
+  UseMutationReturn,
+} from './types';
+
+export {
+  defineCrudRoutes,
+  createTabStore,
+  useTabStore,
+  useMenuFromRoutes,
+  createRouterGuard,
+  addTabFromRoute,
+} from './router';
+export type {
+  CrudRouteMeta,
+  CrudRouteConfig,
+  CrudRouteRecord,
+  TabItem,
+  TabStore,
+  RouteLocationLike,
+  RouterGuard,
+  RouterGuardOptions,
+} from './router';
+
+export {
+  createAuth,
+  useAuth,
+  createAuthGuard,
+  createVCan,
+} from './auth';
+export type {
+  Permission,
+  PermissionScope,
+  UserInfo,
+  AuthState,
+  AuthOptions,
+  AuthReturn,
+  AuthGuardOptions,
+  BeforeEachGuard,
+  CanBinding,
+  CanBindingObject,
+} from './auth';

package/composables/page/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @description CrudPage composable barrel export
+ * @author 阿怪
+ * @date 2026/3/22
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export { useCrudPage } from './useCrudPage';
+export type { CrudPageConfig, CrudColumnConfig, CrudFilterConfig, StatusMapItem } from './types';

package/composables/page/types.ts

@@ -0,0 +1,62 @@
+/**
+ * @description CrudPage 配置驱动页面类型定义
+ * @author 阿怪
+ * @date 2026/3/22
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+/** 列配置 */
+export interface CrudColumnConfig {
+  /** 字段名，对应数据对象的 key */
+  param: string;
+  /** 列标题 */
+  label: string;
+  /** 列宽 */
+  width?: string;
+  /** 列类型，影响渲染方式 */
+  type?: 'text' | 'status' | 'date' | 'datetime' | 'image';
+}
+
+/** 筛选项配置 */
+export interface CrudFilterConfig {
+  /** 字段名，作为请求参数的 key */
+  param: string;
+  /** 筛选项标签 */
+  label: string;
+  /** 筛选项类型 */
+  type: 'input' | 'select';
+  /** select 类型的选项列表 */
+  options?: { label: string; value: string | number }[];
+  /** 占位文本 */
+  placeholder?: string;
+}
+
+/** 状态映射：字段值 → KTag 的 label + type */
+export type StatusMapItem = {
+  label: string;
+  type?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info';
+};
+
+/** CrudPage 完整配置 */
+export interface CrudPageConfig {
+  /** 页面标题 */
+  title: string;
+  /** API 路径（基于 createRequest 的 baseURL） */
+  api: string;
+  /** 列定义 */
+  columns: CrudColumnConfig[];
+  /** 筛选项定义，为空则不显示搜索区 */
+  filters?: CrudFilterConfig[];
+  /** 状态字段的值 → 显示文本 + 标签颜色 映射 */
+  statusMap?: Record<string, StatusMapItem>;
+  /** 每页条数，默认 20 */
+  pageSize?: number;
+  /** 行主键字段，默认 'id' */
+  rowKey?: string;
+  /** 详情页路由前缀，用于构建查看/编辑路由：`${detailPath}/${row[rowKey]}` */
+  detailPath?: string;
+  /** 图片列 src 转换函数，将原始值转为可访问 URL */
+  imageResolver?: (raw: string) => string;
+}

package/composables/page/useCrudPage.ts

@@ -0,0 +1,88 @@
+/**
+ * @description CrudPage composable — 配置驱动的列表页数据层
+ * @author 阿怪
+ * @date 2026/3/22
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import { ref, reactive, computed, onMounted } from 'vue';
+import { useRequestClient } from '../../setup';
+import type { CrudPageConfig } from './types';
+
+export function useCrudPage(config: CrudPageConfig) {
+  const client = useRequestClient();
+
+  const page = ref(1);
+  const pageSize = ref(config.pageSize ?? 20);
+  const total = ref(0);
+  const list = ref<Record<string, unknown>[]>([]);
+  const loading = ref(false);
+
+  // 筛选表单状态
+  const filters = reactive<Record<string, unknown>>({});
+  if (config.filters) {
+    for (const f of config.filters) {
+      filters[f.param] = undefined;
+    }
+  }
+
+  const totalPages = computed(() => Math.max(1, Math.ceil(total.value / pageSize.value)));
+
+  async function fetchData() {
+    loading.value = true;
+    try {
+      const params: Record<string, unknown> = {
+        page: page.value,
+        pageSize: pageSize.value,
+      };
+      for (const [k, v] of Object.entries(filters)) {
+        if (v !== undefined && v !== '' && v !== null) {
+          params[k] = v;
+        }
+      }
+      const res = await client.get<any>(config.api, params);
+      // 兼容包装格式 { success, data: { total, list } } 和裸格式 { total, list }
+      const payload = (res && typeof res === 'object' && 'success' in res) ? res.data : res;
+      list.value = payload?.items ?? payload?.list ?? [];
+      total.value = payload?.total ?? 0;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  function onPageChange(p: number) {
+    page.value = p;
+    fetchData();
+  }
+
+  function onSearch() {
+    page.value = 1;
+    fetchData();
+  }
+
+  function onReset() {
+    for (const key of Object.keys(filters)) {
+      filters[key] = undefined;
+    }
+    page.value = 1;
+    fetchData();
+  }
+
+  onMounted(fetchData);
+
+  return {
+    page,
+    pageSize,
+    total,
+    totalPages,
+    list,
+    loading,
+    filters,
+    fetchData,
+    onPageChange,
+    onSearch,
+    onReset,
+  };
+}

package/composables/request/composables.ts

@@ -0,0 +1,206 @@
+/**
+ * @description Vue Composables — 请求生命周期、轮询、批量加载
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import { onUnmounted, ref, type Ref } from 'vue';
+import type { RequestClient } from './createRequest';
+
+// ────────────────────────────────────────────────────────────────────────────
+// useRequest — 组件内自动管理请求生命周期
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 在组件 setup 中使用，onUnmounted 时自动取消所有 pending 请求。
+ * 返回经过生命周期管理的 client 代理。
+ */
+export function useRequest(client: RequestClient): RequestClient {
+  const controllers: AbortController[] = [];
+
+  // 注册清理
+  onUnmounted(() => {
+    for (const controller of controllers) {
+      controller.abort('组件已卸载');
+    }
+    controllers.length = 0;
+  });
+
+  // 代理 registerAbort，拦截所有请求的 AbortController
+  const proxiedClient: RequestClient = {
+    ...client,
+    registerAbortController: (controller: AbortController) => {
+      controllers.push(controller);
+      client.registerAbortController(controller);
+    },
+  };
+
+  return proxiedClient;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// usePolling — 轮询
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface UsePollingReturn<T> {
+  /** 最新数据 */
+  data: Ref<T | undefined>;
+  /** 是否正在轮询 */
+  isPolling: Ref<boolean>;
+  /** 错误信息 */
+  error: Ref<Error | null>;
+  /** 启动轮询 */
+  start(): void;
+  /** 停止轮询 */
+  stop(): void;
+}
+
+/**
+ * 轮询 composable。
+ * @param fn 每次执行的异步函数
+ * @param interval 轮询间隔（毫秒）
+ */
+export function usePolling<T>(fn: () => Promise<T>, interval: number): UsePollingReturn<T> {
+  const data = ref<T | undefined>() as Ref<T | undefined>;
+  const isPolling = ref(false);
+  const error = ref<Error | null>(null);
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  async function tick() {
+    try {
+      const result = await fn();
+      data.value = result;
+      error.value = null;
+    } catch (e) {
+      error.value = e instanceof Error ? e : new Error(String(e));
+    }
+
+    if (isPolling.value) {
+      timer = setTimeout(tick, interval);
+    }
+  }
+
+  function start() {
+    if (isPolling.value) return;
+    isPolling.value = true;
+    tick();
+  }
+
+  function stop() {
+    isPolling.value = false;
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+
+  onUnmounted(stop);
+
+  return { data, isPolling, error, start, stop };
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// useBatchLoader — 批量合并加载
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface BatchLoaderOptions {
+  /** 合并窗口时间（毫秒），默认 16ms（一帧） */
+  windowMs?: number;
+  /** 单批最大数量 */
+  maxBatchSize?: number;
+}
+
+export interface UseBatchLoaderReturn<K, V> {
+  /** 加载单个 key，自动合并到批次 */
+  load(key: K): Promise<V>;
+  /** 清空待执行队列 */
+  flush(): void;
+}
+
+/**
+ * 批量加载 composable，收集短时间内的请求合并执行。
+ *
+ * @param batchFn 批量执行函数，接收 keys 数组，返回对应 values 数组
+ * @param options 配置项
+ */
+export function useBatchLoader<K, V>(
+  batchFn: (keys: K[]) => Promise<V[]>,
+  options: BatchLoaderOptions = {},
+): UseBatchLoaderReturn<K, V> {
+  const windowMs = options.windowMs ?? 16;
+  const maxBatchSize = options.maxBatchSize ?? 100;
+
+  interface PendingEntry {
+    key: K;
+    resolve: (value: V) => void;
+    reject: (reason: unknown) => void;
+  }
+
+  let queue: PendingEntry[] = [];
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  async function executeBatch(batch: PendingEntry[]) {
+    try {
+      const keys = batch.map(e => e.key);
+      const values = await batchFn(keys);
+
+      if (values.length !== batch.length) {
+        const error = new Error(`[useBatchLoader] 批量函数返回 ${values.length} 个结果，期望 ${batch.length} 个`);
+        batch.forEach(e => e.reject(error));
+        return;
+      }
+
+      batch.forEach((entry, i) => entry.resolve(values[i]));
+    } catch (e) {
+      batch.forEach(entry => entry.reject(e));
+    }
+  }
+
+  function scheduleFlush() {
+    if (timer !== null) return;
+
+    timer = setTimeout(() => {
+      timer = null;
+      flush();
+    }, windowMs);
+  }
+
+  function flush() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+
+    while (queue.length > 0) {
+      const batch = queue.splice(0, maxBatchSize);
+      executeBatch(batch);
+    }
+  }
+
+  function load(key: K): Promise<V> {
+    return new Promise<V>((resolve, reject) => {
+      queue.push({ key, resolve, reject });
+
+      if (queue.length >= maxBatchSize) {
+        flush();
+      } else {
+        scheduleFlush();
+      }
+    });
+  }
+
+  onUnmounted(() => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    // 拒绝所有未执行的请求
+    queue.forEach(e => e.reject(new Error('组件已卸载')));
+    queue = [];
+  });
+
+  return { load, flush };
+}