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

package/composables/error/defaultFeedbackHandler.ts

@@ -0,0 +1,76 @@
+/**
+ * @description 默认用户反馈处理器，基于 KMessage 显示 toast
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { UserFeedbackHandler } from './types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 尝试获取 KMessage
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 懒加载 useMessage，避免循环依赖和 SSR 问题。
+ * 如果 kine-ui 不可用则降级到 console。
+ */
+function tryGetMessageApi() {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { useMessage } = require('@kine-design/ui');
+    return useMessage();
+  } catch {
+    return null;
+  }
+}
+
+/** 缓存 message 实例 */
+let messageApi: ReturnType<typeof tryGetMessageApi> = undefined;
+
+function getMessageApi() {
+  if (messageApi === undefined) {
+    messageApi = tryGetMessageApi();
+  }
+  return messageApi;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 默认反馈处理器
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 默认的 UserFeedbackHandler 实现 */
+export const defaultFeedbackHandler: UserFeedbackHandler = {
+  showSuccess(message: string) {
+    const api = getMessageApi();
+    if (api) {
+      api.success(message);
+    } else {
+      console.log(`[success] ${message}`);
+    }
+  },
+
+  showError(message: string) {
+    const api = getMessageApi();
+    if (api) {
+      api.error(message);
+    } else {
+      console.error(`[error] ${message}`);
+    }
+  },
+
+  showWarning(message: string) {
+    const api = getMessageApi();
+    if (api) {
+      api.warning(message);
+    } else {
+      console.warn(`[warning] ${message}`);
+    }
+  },
+
+  handleAuthenticationFailure() {
+    console.warn('[auth] 认证失败，请重新登录');
+  },
+};

package/composables/error/dispatchError.ts

@@ -0,0 +1,70 @@
+/**
+ * @description 错误分发逻辑，根据错误类型选择对应的处理方式
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import { BusinessError, NetworkRequestError } from '../request/types';
+import type { ErrorHandlerOptions } from './types';
+import { defaultFeedbackHandler } from './defaultFeedbackHandler';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 根据错误类型分发处理
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 统一的错误分发逻辑。
+ * createErrorHandler 和 useErrorHandler 共用此函数。
+ */
+export function dispatchError(error: unknown, options: ErrorHandlerOptions): void {
+  const feedback = options.feedbackHandler ?? defaultFeedbackHandler;
+
+  // 业务错误：后端返回 success=false
+  if (error instanceof BusinessError) {
+    options.onBusinessError?.(error);
+    feedback.showError(error.message);
+    return;
+  }
+
+  // 网络错误：HTTP 异常、超时、取消等
+  if (error instanceof NetworkRequestError) {
+    const detail = error.detail;
+    options.onNetworkError?.(detail);
+
+    switch (detail.type) {
+      case 'httpError':
+        if (detail.status === 401) {
+          feedback.handleAuthenticationFailure();
+          return;
+        }
+        if (detail.status === 403) {
+          feedback.showWarning('权限不足，无法执行此操作');
+          return;
+        }
+        feedback.showError(`请求失败 (${detail.status})`);
+        return;
+      case 'timeout':
+        feedback.showWarning('请求超时，请稍后重试');
+        return;
+      case 'aborted':
+        // 用户主动取消，静默处理
+        return;
+      case 'invalidURL':
+        feedback.showError(`无效的请求地址: ${detail.url}`);
+        return;
+      case 'decodingFailed':
+        feedback.showError('数据解析失败');
+        return;
+      case 'unknown':
+        feedback.showError('网络异常，请检查网络连接');
+        return;
+    }
+  }
+
+  // 其他未知错误
+  const message = error instanceof Error ? error.message : String(error);
+  feedback.showError(message || '发生了未知错误');
+}

package/composables/error/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @description 全局错误处理模块统一导出
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+// ── 类型导出 ──────────────────────────────────────────────────────────────
+
+export type {
+  ErrorLevel,
+  UnauthorizedStrategy,
+  ErrorHandlerOptions,
+  UserFeedbackHandler,
+  NetworkError,
+} from './types';
+
+export { BusinessError, NetworkRequestError } from './types';
+
+// ── 默认反馈处理器 ────────────────────────────────────────────────────────
+
+export { defaultFeedbackHandler } from './defaultFeedbackHandler';
+
+// ── 全局错误处理 ──────────────────────────────────────────────────────────
+
+export { createErrorHandler } from './createErrorHandler';
+
+// ── 组件级错误处理 ────────────────────────────────────────────────────────
+
+export { useErrorHandler } from './useErrorHandler';

package/composables/error/types.ts

@@ -0,0 +1,57 @@
+/**
+ * @description 全局错误处理模块类型定义
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+// 复用请求模块已有的错误类型和用户反馈接口
+export type {
+  NetworkError,
+  UserFeedbackHandler,
+} from '../request/types';
+
+export { BusinessError, NetworkRequestError } from '../request/types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 错误等级
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 错误反馈等级，对应不同的 UI 展示样式 */
+export type ErrorLevel = 'info' | 'warning' | 'error' | 'success';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 未授权处理策略
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 401 未授权时的处理方式 */
+export type UnauthorizedStrategy = 'redirect' | 'dialog';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 错误处理配置
+// ────────────────────────────────────────────────────────────────────────────
+
+import type { InjectionKey } from 'vue';
+import type { UserFeedbackHandler, NetworkError } from '../request/types';
+import { BusinessError } from '../request/types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// Inject key
+// ────────────────────────────────────────────────────────────────────────────
+
+/** provide/inject 使用的唯一 symbol key，避免命名冲突 */
+export const ERROR_HANDLER_INJECT_KEY: InjectionKey<ErrorHandlerOptions> = Symbol('kine-design:error-handler');
+
+/** createErrorHandler 配置项 */
+export interface ErrorHandlerOptions {
+  /** 用户反馈处理器，默认使用 defaultFeedbackHandler */
+  feedbackHandler?: UserFeedbackHandler;
+  /** 未授权处理策略，默认 'redirect' */
+  unauthorizedStrategy?: UnauthorizedStrategy;
+  /** 业务错误自定义处理，返回 true 表示已处理（跳过默认行为） */
+  onBusinessError?: (error: BusinessError) => void;
+  /** 网络错误自定义处理 */
+  onNetworkError?: (error: NetworkError) => void;
+}

package/composables/error/useErrorHandler.ts

@@ -0,0 +1,41 @@
+/**
+ * @description 组件级错误处理 composable，基于 provide/inject 获取全局配置
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import { inject } from 'vue';
+import { ERROR_HANDLER_INJECT_KEY } from './types';
+import { dispatchError } from './dispatchError';
+
+// ────────────────────────────────────────────────────────────────────────────
+// useErrorHandler — 组件中手动调用
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 在组件中获取错误处理能力。
+ * 如果 createErrorHandler() 未安装，使用默认配置降级处理。
+ *
+ * @example
+ * ```ts
+ * const { handleError } = useErrorHandler();
+ *
+ * try {
+ *   await fetchSomething();
+ * } catch (e) {
+ *   handleError(e);
+ * }
+ * ```
+ */
+export function useErrorHandler(): { handleError: (error: unknown) => void } {
+  const options = inject(ERROR_HANDLER_INJECT_KEY, {});
+
+  return {
+    handleError(error: unknown) {
+      dispatchError(error, options);
+    },
+  };
+}

package/composables/form/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @description form composables barrel export
+ * @author 阿怪
+ * @date 2026/3/22
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export { useFormPage } from './useFormPage';
+export type { UseFormPageOptions, UseFormPageReturn } from './useFormPage';
+export { renderFormField } from './renderFormField';
+export type {
+  FormFieldType,
+  FormFieldConfig,
+  FormPageConfig,
+  DetailTableConfig,
+  MasterDetailPageConfig,
+} from './types';

package/composables/form/renderFormField.tsx

@@ -0,0 +1,119 @@
+/**
+ * @description renderFormField — 表单字段渲染共享函数
+ * @author 阿怪
+ * @date 2026/3/22
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ *
+ * 抽取自 KFormPage / KMasterDetailPage 的 renderField，消除重复。
+ * KFormPage 和 KMasterDetailPage 均通过此函数渲染主表单字段。
+ */
+import type { FormFieldConfig } from './types';
+import KInput from 'kine-ui/components/input/KInput.tsx';
+import KSelect from 'kine-ui/components/select/KSelect.tsx';
+
+/**
+ * 渲染单个表单字段控件。
+ *
+ * @param field        字段配置
+ * @param formData     响应式表单数据对象（reactive）
+ * @param errors       当前校验错误集合（已解包，非 Ref）
+ * @param validateField 触发单字段校验的函数
+ * @param slots        组件 slots，用于支持 `field-{param}` 自定义插槽
+ */
+export function renderFormField(
+  field: FormFieldConfig,
+  formData: Record<string, unknown>,
+  errors: Record<string, string>,
+  validateField: (param: string) => void,
+  slots: Record<string, ((...args: unknown[]) => unknown) | undefined>,
+) {
+  // 优先使用自定义插槽
+  const customSlot = slots[`field-${field.param}`];
+  if (customSlot) {
+    return customSlot({ formData, field, error: errors[field.param] });
+  }
+
+  const error = errors[field.param];
+  const val = formData[field.param];
+  const onBlur = () => validateField(field.param);
+
+  switch (field.type) {
+    case 'textarea':
+      return (
+        <KInput
+          type="textarea"
+          class={['k-fp-input--error-wrap', error && 'k-fp-input--error', field.disabled && 'k-fp-input--disabled'].filter(Boolean)}
+          modelValue={val as string}
+          placeholder={field.placeholder ?? `请输入${field.label}`}
+          disabled={field.disabled}
+          readonly={field.readonly}
+          onUpdate:modelValue={(v: string) => { formData[field.param] = v; }}
+          onBlur={onBlur}
+        />
+      );
+
+    case 'number':
+      return (
+        <div class="k-fp-input-wrapper">
+          {field.prefix && <span class="k-fp-input-prefix">{field.prefix}</span>}
+          <KInput
+            type="number"
+            class={['k-fp-input', error && 'k-fp-input--error', field.disabled && 'k-fp-input--disabled'].filter(Boolean)}
+            modelValue={val as string | number}
+            placeholder={field.placeholder ?? `请输入${field.label}`}
+            disabled={field.disabled}
+            readonly={field.readonly}
+            onUpdate:modelValue={(v: string) => { formData[field.param] = v; }}
+            onBlur={onBlur}
+          />
+          {field.suffix && <span class="k-fp-input-suffix">{field.suffix}</span>}
+        </div>
+      );
+
+    case 'select':
+      return (
+        <KSelect
+          class={['k-fp-select-wrap', error && 'k-fp-input--error'].filter(Boolean)}
+          modelValue={val}
+          options={field.options ?? []}
+          optionParam="label"
+          valueParam="value"
+          placeholder={field.placeholder ?? `请选择${field.label}`}
+          disabled={field.disabled}
+          readonly={field.readonly}
+          onUpdate:modelValue={(v: unknown) => {
+            formData[field.param] = v;
+            validateField(field.param);
+          }}
+        />
+      );
+
+    case 'switch':
+      return (
+        <label class="k-fp-switch">
+          <input
+            type="checkbox"
+            checked={!!val}
+            disabled={field.disabled}
+            onChange={(e: Event) => { formData[field.param] = (e.target as HTMLInputElement).checked; }}
+          />
+          <span class="k-fp-switch-track" />
+        </label>
+      );
+
+    default:
+      return (
+        <KInput
+          class={['k-fp-input--error-wrap', error && 'k-fp-input--error', field.disabled && 'k-fp-input--disabled'].filter(Boolean)}
+          modelValue={val as string}
+          placeholder={field.placeholder ?? `请输入${field.label}`}
+          disabled={field.disabled}
+          readonly={field.readonly}
+          onUpdate:modelValue={(v: string) => { formData[field.param] = v; }}
+          onBlur={onBlur}
+        />
+      );
+  }
+}

package/composables/form/types.ts

@@ -0,0 +1,129 @@
+/**
+ * @description FormPage / MasterDetailPage 配置类型定义
+ * @author 阿怪
+ * @date 2026/3/22
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { EditableColumn } from '../../components/editableTable';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 表单字段配置
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 表单字段类型 */
+export type FormFieldType =
+  | 'text'
+  | 'number'
+  | 'select'
+  | 'date'
+  | 'textarea'
+  | 'switch'
+  | 'autocomplete'
+  | 'custom';
+
+/** 表单字段配置 */
+export interface FormFieldConfig {
+  /** 字段名，对应数据对象的 key */
+  param: string;
+  /** 标签文本 */
+  label: string;
+  /** 字段类型 */
+  type?: FormFieldType;
+  /** 占位文本 */
+  placeholder?: string;
+  /** 是否必填 */
+  required?: boolean;
+  /** 是否禁用 */
+  disabled?: boolean;
+  /** 是否只读 */
+  readonly?: boolean;
+  /** 跨列数（默认 1，textarea 常用 'full' 表示占满整行） */
+  span?: number | 'full';
+  /** select 类型的选项 */
+  options?: Array<{ label: string; value: string | number }>;
+  /** autocomplete 的 fetchSuggestions */
+  fetchSuggestions?: (query: string) => Promise<Array<{ label: string; value: string | number }>>;
+  /** number 类型的前缀（如 ¥） */
+  prefix?: string;
+  /** number 类型的后缀（如 米、件） */
+  suffix?: string;
+  /** textarea 的行数 */
+  rows?: number;
+  /** textarea 的最大字数 */
+  maxLength?: number;
+  /** 自定义校验函数 */
+  validator?: (value: unknown, formData: Record<string, unknown>) => string | undefined;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// FormPage 配置
+// ────────────────────────────────────────────────────────────────────────────
+
+/** SimpleFormPage 完整配置 */
+export interface FormPageConfig {
+  /** 页面标题 */
+  title: string;
+  /** API 路径 */
+  api: string;
+  /** 表单字段定义 */
+  fields: FormFieldConfig[];
+  /** 列数布局（默认 2） */
+  columns?: 1 | 2 | 3;
+  /** 主键字段（编辑模式下从路由取 id，默认 'id'） */
+  rowKey?: string;
+  /** 保存成功后跳转路径 */
+  redirectPath?: string;
+  /** 是否显示"保存草稿"按钮 */
+  showDraft?: boolean;
+  /** 提交按钮文本 */
+  submitText?: string;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// MasterDetailPage 配置
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 子表配置 */
+export interface DetailTableConfig {
+  /** 子表标题 */
+  title: string;
+  /** 子表字段名（对应主表数据中的数组字段） */
+  param: string;
+  /** 列定义（复用 EditableColumn） */
+  columns: EditableColumn[];
+  /** 是否显示汇总行 */
+  showSummary?: boolean;
+  /** 汇总行标签 */
+  summaryLabel?: string;
+  /** 币种前缀 */
+  currencyPrefix?: string;
+  /** 新增行按钮文本 */
+  addText?: string;
+}
+
+/** MasterDetailPage 完整配置 */
+export interface MasterDetailPageConfig {
+  /** 页面标题 */
+  title: string;
+  /** API 路径 */
+  api: string;
+  /** 面包屑路径 */
+  breadcrumb?: Array<{ label: string; path?: string }>;
+  /** 主表字段定义 */
+  fields: FormFieldConfig[];
+  /** 主表列数布局（默认 3） */
+  columns?: 1 | 2 | 3;
+  /** 子表配置（支持多个子表） */
+  detailTables: DetailTableConfig[];
+  /** 主键字段 */
+  rowKey?: string;
+  /** 保存成功后跳转路径 */
+  redirectPath?: string;
+  /** 是否显示"保存草稿"按钮 */
+  showDraft?: boolean;
+  /** 提交按钮文本 */
+  submitText?: string;
+}