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

package/composables/request/types.ts

@@ -0,0 +1,226 @@
+/**
+ * @description 请求模块类型定义
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+// ────────────────────────────────────────────────────────────────────────────
+// 请求方法
+// ────────────────────────────────────────────────────────────────────────────
+
+export type RequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 控制策略
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface ControlPolicy {
+  /** 防抖延迟（毫秒） */
+  debounce?: number;
+  /** 节流间隔（毫秒） */
+  throttle?: number;
+  /** 是否去重（相同请求复用同一个 Promise） */
+  deduplicate?: boolean;
+  /** 优先级，数值越大越优先 */
+  priority?: number;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 缓存策略 — discriminated union
+// ────────────────────────────────────────────────────────────────────────────
+
+export type CachePolicy =
+  | { type: 'none' }
+  | { type: 'cacheFirst'; maxAge: number }
+  | { type: 'staleWhileRevalidate'; maxAge: number };
+
+// ────────────────────────────────────────────────────────────────────────────
+// 重试策略 — discriminated union
+// ────────────────────────────────────────────────────────────────────────────
+
+export type RetryPolicy =
+  | { type: 'none' }
+  | { type: 'fixed'; maxAttempts: number; delay: number }
+  | { type: 'exponential'; maxAttempts: number; initialDelay: number; multiplier: number; maxDelay: number };
+
+// ────────────────────────────────────────────────────────────────────────────
+// 生命周期
+// ────────────────────────────────────────────────────────────────────────────
+
+/** vue: 跟随组件生命周期自动取消；persistent: 不自动取消；manual: 手动控制 */
+export type Lifecycle = 'vue' | 'persistent' | 'manual';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 请求配置
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface RequestConfig {
+  lifecycle?: Lifecycle;
+  control?: ControlPolicy;
+  cache?: CachePolicy;
+  retry?: RetryPolicy;
+  /** 单次请求超时（毫秒） */
+  timeout?: number;
+  /** 包含重试在内的总超时（毫秒） */
+  totalTimeout?: number;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 响应包装
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface WrappedResponse<T> {
+  success: boolean;
+  data: T;
+  message: string;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 错误类型
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 业务错误：后端返回 success=false */
+export class BusinessError extends Error {
+  override readonly name = 'BusinessError';
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+/** 网络错误 — discriminated union */
+export type NetworkError =
+  | { type: 'invalidURL'; url: string }
+  | { type: 'timeout' }
+  | { type: 'httpError'; status: number; statusText: string }
+  | { type: 'decodingFailed'; reason: string }
+  | { type: 'aborted' }
+  | { type: 'unknown'; error: unknown };
+
+/** 将 NetworkError 包装为可 throw 的 Error */
+export class NetworkRequestError extends Error {
+  override readonly name = 'NetworkRequestError';
+  readonly detail: NetworkError;
+
+  constructor(detail: NetworkError) {
+    super(networkErrorMessage(detail));
+    this.detail = detail;
+  }
+}
+
+function networkErrorMessage(e: NetworkError): string {
+  switch (e.type) {
+    case 'invalidURL': return `无效的 URL: ${e.url}`;
+    case 'timeout': return '请求超时';
+    case 'httpError': return `HTTP ${e.status} ${e.statusText}`;
+    case 'decodingFailed': return `解码失败: ${e.reason}`;
+    case 'aborted': return '请求已取消';
+    case 'unknown': return `未知错误: ${String(e.error)}`;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 用户反馈接口
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface UserFeedbackHandler {
+  showSuccess(message: string): void;
+  showError(message: string): void;
+  showWarning(message: string): void;
+  handleAuthenticationFailure(): void;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Transport 传输层接口
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface TransportRequest {
+  url: string;
+  method: RequestMethod;
+  headers: Record<string, string>;
+  body?: BodyInit | null;
+  signal?: AbortSignal;
+  timeout?: number;
+  /** 上传进度回调（仅 XHR 支持） */
+  onUploadProgress?: (event: { loaded: number; total: number }) => void;
+}
+
+export interface TransportResponse {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  body: ReadableStream<Uint8Array> | null;
+  /** 读取响应文本 */
+  text(): Promise<string>;
+  /** 读取响应 JSON */
+  json<T = unknown>(): Promise<T>;
+  /** 读取响应 Blob */
+  blob(): Promise<Blob>;
+}
+
+export interface Transport {
+  send(request: TransportRequest): Promise<TransportResponse>;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 请求客户端配置
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface RequestOptions {
+  /** 基础 URL，所有请求自动拼接 */
+  baseURL?: string;
+  /** 默认请求头 */
+  headers?: Record<string, string>;
+  /** 获取 token 的函数 */
+  getToken?: () => string | null | undefined;
+  /** 401 时的回调 */
+  onUnauthorized?: () => void;
+  /** 默认请求配置 */
+  defaultConfig?: RequestConfig;
+  /** 传输层实现，默认使用 fetchTransport */
+  transport?: Transport;
+  /** 用户反馈处理器 */
+  feedback?: UserFeedbackHandler;
+  /** 响应拦截器 */
+  responseInterceptor?: <T>(data: T) => T;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 编排器
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface OrchestratorNode<T = unknown> {
+  id: string;
+  execute: () => Promise<T>;
+  dependencies: string[];
+}
+
+export type FailureStrategy = 'failFast' | 'continueOnError';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 上传
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface UploadOptions {
+  /** 上传接口 URL */
+  url: string;
+  /** 自定义请求头 */
+  headers?: Record<string, string>;
+  /** 文件字段名，默认 'file' */
+  fieldName?: string;
+  /** 附加表单数据 */
+  data?: Record<string, string>;
+  /** 进度回调 */
+  onProgress?: (percent: number) => void;
+}
+
+export interface UploaderOptions {
+  /** 基础 URL */
+  baseURL?: string;
+  /** 获取 token */
+  getToken?: () => string | null | undefined;
+  /** 默认请求头 */
+  headers?: Record<string, string>;
+}

package/composables/request/upload.ts

@@ -0,0 +1,146 @@
+/**
+ * @description 上传模块 — 基于 XHR 的文件上传
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import { ref, type Ref } from 'vue';
+import type { UploaderOptions, UploadOptions, WrappedResponse } from './types';
+import { BusinessError, NetworkRequestError } from './types';
+import { XhrTransport } from './transport/xhrTransport';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 上传结果
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface UploadHandle<T = unknown> {
+  /** 上传进度（0-100） */
+  progress: Ref<number>;
+  /** 取消上传 */
+  abort(): void;
+  /** 上传结果 Promise */
+  promise: Promise<T>;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// createUploader
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface Uploader {
+  /** 上传单个文件 */
+  upload<T = unknown>(file: File, options: UploadOptions): UploadHandle<T>;
+  /** 上传多个文件 */
+  uploadMultiple<T = unknown>(files: File[], options: UploadOptions): UploadHandle<T>;
+}
+
+export function createUploader(uploaderOptions: UploaderOptions = {}): Uploader {
+  const transport = new XhrTransport();
+
+  function buildURL(url: string): string {
+    if (url.startsWith('http')) return url;
+    return `${uploaderOptions.baseURL ?? ''}${url}`;
+  }
+
+  function buildHeaders(options: UploadOptions): Record<string, string> {
+    const headers: Record<string, string> = { ...uploaderOptions.headers, ...options.headers };
+    const token = uploaderOptions.getToken?.();
+    if (token) {
+      headers['Authorization'] = `Bearer ${token}`;
+    }
+    // FormData 不设置 Content-Type，浏览器自动添加 boundary
+    return headers;
+  }
+
+  function doUpload<T>(formData: FormData, options: UploadOptions): UploadHandle<T> {
+    const progress = ref(0);
+    const abortController = new AbortController();
+
+    const promise = transport.send({
+      url: buildURL(options.url),
+      method: 'POST',
+      headers: buildHeaders(options),
+      body: formData,
+      signal: abortController.signal,
+      onUploadProgress: (event) => {
+        const percent = event.total > 0 ? Math.round((event.loaded / event.total) * 100) : 0;
+        progress.value = percent;
+        options.onProgress?.(percent);
+      },
+    }).then(async (response) => {
+      // HTTP 错误
+      if (response.status < 200 || response.status >= 300) {
+        throw new NetworkRequestError({
+          type: 'httpError',
+          status: response.status,
+          statusText: response.statusText,
+        });
+      }
+
+      const contentType = response.headers['content-type'] ?? '';
+      if (contentType.includes('application/json')) {
+        const json = await response.json<WrappedResponse<T> | T>();
+        if (isWrappedResponse<T>(json)) {
+          if (!json.success) throw new BusinessError(json.message || '上传失败');
+          return json.data;
+        }
+        return json as T;
+      }
+
+      return await response.text() as unknown as T;
+    });
+
+    return {
+      progress,
+      abort: () => abortController.abort('上传已取消'),
+      promise,
+    };
+  }
+
+  return {
+    upload<T>(file: File, options: UploadOptions): UploadHandle<T> {
+      const fieldName = options.fieldName ?? 'file';
+      const formData = new FormData();
+      formData.append(fieldName, file);
+
+      // 附加数据
+      if (options.data) {
+        for (const [key, value] of Object.entries(options.data)) {
+          formData.append(key, value);
+        }
+      }
+
+      return doUpload<T>(formData, options);
+    },
+
+    uploadMultiple<T>(files: File[], options: UploadOptions): UploadHandle<T> {
+      const fieldName = options.fieldName ?? 'files';
+      const formData = new FormData();
+      files.forEach(file => formData.append(fieldName, file));
+
+      if (options.data) {
+        for (const [key, value] of Object.entries(options.data)) {
+          formData.append(key, value);
+        }
+      }
+
+      return doUpload<T>(formData, options);
+    },
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部辅助
+// ────────────────────────────────────────────────────────────────────────────
+
+function isWrappedResponse<T>(value: unknown): value is WrappedResponse<T> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'success' in value &&
+    'data' in value &&
+    typeof (value as Record<string, unknown>).success === 'boolean'
+  );
+}

package/composables/router/createRouterGuard.ts

@@ -0,0 +1,134 @@
+/**
+ * @description 整合路由守卫 — 认证 + 权限 + tab 联动
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { AuthReturn } from '../auth/types';
+import type { TabStore, CrudRouteMeta } from './types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 局部 vue-router 类型声明（不引入 vue-router 依赖）
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 最小化 RouteLocationNormalized */
+interface RouteLocation {
+  path: string;
+  name?: string | symbol;
+  meta: CrudRouteMeta & Record<string, unknown>;
+}
+
+/** 导航结果：undefined 表示放行，string 表示跳转目标路径 */
+type NavigationResult = string | undefined;
+
+/** beforeEach 守卫函数签名 */
+export type RouterGuard = (
+  to: RouteLocation,
+  from: RouteLocation,
+) => NavigationResult | Promise<NavigationResult>;
+
+// ────────────────────────────────────────────────────────────────────────────
+// 选项
+// ────────────────────────────────────────────────────────────────────────────
+
+/** createRouterGuard 配置选项 */
+export interface RouterGuardOptions {
+  /** useAuth() 返回值，用于认证和权限检查 */
+  auth: AuthReturn;
+  /** tab store 实例，传入后自动在导航时 addTab */
+  tabStore?: TabStore;
+  /** 登录页路径，默认 '/login' */
+  loginPath?: string;
+  /** 权限不足跳转路径，默认 '/403' */
+  forbiddenPath?: string;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// createRouterGuard
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 创建整合路由守卫，统一处理认证、权限、tab 联动。
+ *
+ * 守卫逻辑顺序：
+ * 1. 已登录用户访问 loginPath 时重定向到首页
+ * 2. 权限检查（meta.can）
+ * 3. 登录检查（meta.requiresAuth !== false）
+ * 4. 自动 addTab（如果传入 tabStore）
+ *
+ * @example
+ * ```ts
+ * import { useAuth, createRouterGuard } from '@kine-design/crud';
+ * import { createTabStore } from '@kine-design/crud';
+ *
+ * const auth = useAuth();
+ * const tabStore = createTabStore();
+ * const guard = createRouterGuard({ auth, tabStore, loginPath: '/login' });
+ * router.beforeEach(guard);
+ * ```
+ */
+export function createRouterGuard(options: RouterGuardOptions): RouterGuard {
+  const {
+    auth,
+    tabStore,
+    loginPath = '/login',
+    forbiddenPath = '/403',
+  } = options;
+
+  return (to: RouteLocation): NavigationResult => {
+    const meta = to.meta;
+
+    // ── 1. 已登录用户访问登录页，重定向到首页 ────────────────────────────
+    if (to.path === loginPath && auth.isAuthenticated.value) {
+      return '/';
+    }
+
+    // ── 2. 路由级权限检查 ────────────────────────────────────────────────
+    if (meta.can) {
+      const { resource, action } = meta.can;
+      if (!auth.can(resource, action)) {
+        if (to.path === forbiddenPath) return undefined;
+        return forbiddenPath;
+      }
+    }
+
+    // ── 3. 登录检查（requiresAuth 默认为 true）──────────────────────────
+    const requiresAuth = meta.requiresAuth !== false;
+    if (requiresAuth && !auth.isAuthenticated.value) {
+      if (to.path === loginPath) return undefined;
+      return loginPath;
+    }
+
+    // ── 4. 自动添加 tab ─────────────────────────────────────────────────
+    if (tabStore) {
+      addTabFromRoute(tabStore, to);
+    }
+
+    // 放行
+    return undefined;
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// addTabFromRoute
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 从路由对象自动提取信息创建 tab。
+ * 也可独立使用，不依赖 createRouterGuard。
+ */
+export function addTabFromRoute(tabStore: TabStore, route: RouteLocation): 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;
+
+  tabStore.addTab({
+    path: route.path,
+    title,
+    name,
+    closable: true,
+  });
+}

package/composables/router/defineCrudRoutes.ts

@@ -0,0 +1,116 @@
+/**
+ * @description CRUD 路由便利函数 — 根据实体配置批量生成路由记录
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { CrudRouteConfig, CrudRouteRecord } from './types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部辅助
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 路由操作配置项 */
+interface OpSpec {
+  /** 操作类型 */
+  op: 'list' | 'new' | 'modify' | 'detail';
+  /** 相对于 basePath 的后缀，空字符串表示直接用 basePath */
+  suffix: string;
+  /** 权限 action */
+  action: 'read' | 'create' | 'update';
+  /** 组件动态导入函数 */
+  component: (() => Promise<unknown>) | undefined;
+  /** 操作类型中文后缀，用于自动拼接 title */
+  titleSuffix: string;
+  /** 列表页默认缓存，其他默认不缓存 */
+  keepAlive: boolean;
+  /** 是否隐藏菜单（新建/编辑/详情不显示在导航中） */
+  hidden: boolean;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// defineCrudRoutes
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 根据实体配置生成标准 CRUD 路由记录数组。
+ *
+ * 生成规则：
+ * - list   → `path`            (action: 'read')
+ * - new    → `path/new`        (action: 'create')
+ * - modify → `path/:id/edit`   (action: 'update')
+ * - detail → `path/:id`        (action: 'read')
+ *
+ * 未传入 component 的操作不会生成对应路由。
+ *
+ * @example
+ * ```ts
+ * const orderRoutes = defineCrudRoutes({
+ *   name: 'Order',
+ *   path: '/order',
+ *   list:   () => import('./views/Order.vue'),
+ *   new:    () => import('./views/NewOrder.vue'),
+ *   modify: () => import('./views/ModifyOrder.vue'),
+ *   detail: () => import('./views/DetailOrder.vue'),
+ *   permission: 'order',
+ * });
+ * ```
+ */
+export function defineCrudRoutes(config: CrudRouteConfig): CrudRouteRecord[] {
+  const { name, path, permission, title, icon } = config;
+  const resource = permission ?? name.toLowerCase();
+
+  // 规范化 basePath，确保以 / 开头、不以 / 结尾
+  const basePath = path.replace(/\/+$/, '');
+
+  const opSpecs: OpSpec[] = [
+    { op: 'list',   suffix: '',          action: 'read',   component: config.list,   titleSuffix: '', keepAlive: true,  hidden: false },
+    { op: 'new',    suffix: '/new',       action: 'create', component: config.new,    titleSuffix: ' - 新建', keepAlive: false, hidden: true },
+    { op: 'modify', suffix: '/:id/edit',  action: 'update', component: config.modify, titleSuffix: ' - 编辑', keepAlive: false, hidden: true },
+    { op: 'detail', suffix: '/:id',       action: 'read',   component: config.detail, titleSuffix: ' - 详情', keepAlive: false, hidden: true },
+  ];
+
+  const routes: CrudRouteRecord[] = [];
+
+  for (const spec of opSpecs) {
+    // 未提供组件则跳过
+    if (!spec.component) continue;
+
+    routes.push({
+      path: basePath + spec.suffix,
+      // 路由名称格式：EntityOp，如 OrderList、OrderNew
+      name: `${name}${capitalize(spec.op)}`,
+      component: spec.component,
+      meta: {
+        crud: {
+          entity: name,
+          op: spec.op,
+        },
+        // 仅在显式传入 permission 时生成权限检查
+        ...(permission ? { can: { resource, action: spec.action } } : undefined),
+        requiresAuth: true,
+        // 自动填充 title：基于 config.title + 操作类型后缀
+        ...(title ? { title: `${title}${spec.titleSuffix}` } : undefined),
+        // 继承 config.icon
+        ...(icon ? { icon } : undefined),
+        keepAlive: spec.keepAlive,
+        hidden: spec.hidden,
+      },
+    });
+  }
+
+  return routes;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部工具
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 首字母大写 */
+function capitalize(str: string): string {
+  if (!str) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/composables/router/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @description 路由管理层 barrel export
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export { defineCrudRoutes } from './defineCrudRoutes';
+export { createTabStore, useTabStore } from './useTabStore';
+export { useMenuFromRoutes } from './useMenuFromRoutes';
+export { createRouterGuard, addTabFromRoute } from './createRouterGuard';
+export type { RouterGuard, RouterGuardOptions } from './createRouterGuard';
+export type {
+  CrudRouteMeta,
+  CrudRouteConfig,
+  CrudRouteRecord,
+  TabItem,
+  TabStore,
+  RouteLocationLike,
+} from './types';