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

package/composables/auth/useAuth.ts

@@ -0,0 +1,278 @@
+/**
+ * @description 权限核心 composable，基于 provide/inject 实现全局单例
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import { computed, inject, reactive, type App, type InjectionKey } from 'vue';
+import type { AuthOptions, AuthReturn, AuthState, Permission, PermissionScope, UserInfo } from './types';
+import { createStorageAdapter, type StorageAdapter } from '../storage/createStorageAdapter';
+
+// ────────────────────────────────────────────────────────────────────────────
+// Inject key
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 内部 provide 结构，包含 auth 实例与 onUnauthorized 回调 */
+interface AuthProvide {
+  auth: AuthReturn;
+  onUnauthorized: (() => void) | undefined;
+}
+
+/** provide/inject 使用的唯一 symbol key，避免命名冲突 */
+const AUTH_INJECT_KEY: InjectionKey<AuthProvide> = Symbol('kine-design:auth');
+
+// ────────────────────────────────────────────────────────────────────────────
+// scope 层级映射（数值越大权限越宽）
+// ────────────────────────────────────────────────────────────────────────────
+
+const SCOPE_LEVEL: Record<string, number> = {
+  own: 1,
+  department: 2,
+  all: 3,
+  '*': Infinity,
+};
+
+/**
+ * 检查权限持有的 scope 是否满足所需 scope。
+ * 层级：all > department > own，'*' 匹配所有。
+ */
+function isScopeSatisfied(
+  permScope: PermissionScope | undefined,
+  requiredScope: PermissionScope,
+): boolean {
+  // 权限 scope 未声明时视为 'all'（无范围限制）
+  const permLevel = SCOPE_LEVEL[permScope ?? 'all'] ?? 0;
+  const requiredLevel = SCOPE_LEVEL[requiredScope] ?? 0;
+  return permLevel >= requiredLevel;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部：判断单条权限是否命中
+// ────────────────────────────────────────────────────────────────────────────
+
+function matchesPermission(
+  perm: Permission,
+  resource: string,
+  action: string,
+  scope: PermissionScope | undefined,
+): boolean {
+  // 资源不匹配直接跳过
+  if (perm.resource !== resource) return false;
+
+  // action: '*' 的权限匹配所有操作
+  const actionMatched = perm.action === '*' || perm.action === action;
+  if (!actionMatched) return false;
+
+  // 不需要检查 scope
+  if (scope === undefined) return true;
+
+  return isScopeSatisfied(perm.scope, scope);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Storage key 常量
+// ────────────────────────────────────────────────────────────────────────────
+
+const STORAGE_KEY_TOKEN = 'kine_auth_token';
+const STORAGE_KEY_USER = 'kine_auth_user';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部：构建 AuthReturn
+// ────────────────────────────────────────────────────────────────────────────
+
+function buildAuthReturn(
+  state: AuthState,
+  options: AuthOptions,
+  adapter: StorageAdapter | null,
+): AuthReturn {
+  const user = computed(() => state.user);
+  const permissions = computed(() => state.permissions);
+  const token = computed(() => state.token);
+  const isAuthenticated = computed(() => state.user !== null && state.token !== null);
+
+  function can(resource: string, action: string, scope?: PermissionScope): boolean {
+    if (!state.permissions) return false;
+    return state.permissions.some(p => matchesPermission(p, resource, action, scope));
+  }
+
+  /** 将当前状态写入 storage */
+  function persistToStorage(): void {
+    if (!adapter) return;
+    adapter.set(STORAGE_KEY_TOKEN, state.token);
+    adapter.set(STORAGE_KEY_USER, state.user);
+  }
+
+  /** 清除 storage 中的认证数据 */
+  function clearStorage(): void {
+    if (!adapter) return;
+    adapter.remove(STORAGE_KEY_TOKEN);
+    adapter.remove(STORAGE_KEY_USER);
+  }
+
+  async function login(): Promise<void> {
+    const result = await options.fetchUser();
+    state.user = result.user;
+    state.permissions = result.permissions;
+    state.token = result.token;
+    persistToStorage();
+  }
+
+  function loginWith(result: { user: UserInfo; permissions: Permission[]; token: string }): void {
+    state.user = result.user;
+    state.permissions = result.permissions;
+    state.token = result.token;
+    persistToStorage();
+  }
+
+  function logout(): void {
+    state.user = null;
+    state.permissions = [];
+    state.token = null;
+    clearStorage();
+  }
+
+  let restoring: Promise<void> | null = null;
+
+  async function restore(): Promise<void> {
+    if (!adapter) return;
+    // 防止并发调用（如 mount + tab 激活同时触发）
+    if (restoring) return restoring;
+
+    restoring = doRestore();
+    try {
+      await restoring;
+    } finally {
+      restoring = null;
+    }
+  }
+
+  async function doRestore(): Promise<void> {
+    const storedToken = adapter!.get<string>(STORAGE_KEY_TOKEN);
+    const storedUser = adapter!.get<AuthState['user']>(STORAGE_KEY_USER);
+
+    // storage 中没有有效数据，跳过
+    if (!storedToken || !storedUser) return;
+
+    // 先恢复到 reactive state（让 UI 能立即渲染）
+    state.token = storedToken;
+    state.user = storedUser;
+
+    // 调用 fetchUser 验证 token 是否仍然有效
+    try {
+      const result = await options.fetchUser();
+      state.user = result.user;
+      state.permissions = result.permissions;
+      state.token = result.token;
+      persistToStorage();
+    } catch {
+      // 验证失败，清除所有状态
+      state.user = null;
+      state.permissions = [];
+      state.token = null;
+      clearStorage();
+    }
+  }
+
+  return { user, permissions, token, isAuthenticated, can, login, loginWith, logout, restore };
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// createAuth — 应用初始化时调用一次
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 创建全局 auth 实例并安装到 Vue App。
+ * 应在 main.ts 中调用一次，之后所有组件可通过 useAuth() 获取。
+ *
+ * @example
+ * ```ts
+ * // main.ts
+ * import { createApp } from 'vue';
+ * import { createAuth } from '@kine-design/crud';
+ *
+ * const app = createApp(App);
+ * createAuth(app, {
+ *   fetchUser: () => http.get('/api/me'),
+ *   onUnauthorized: () => router.push('/login'),
+ * });
+ * app.mount('#app');
+ * ```
+ */
+export function createAuth(app: App, options: AuthOptions): AuthReturn {
+  const state = reactive<AuthState>({
+    user: null,
+    permissions: [],
+    token: null,
+  });
+
+  // 根据配置创建 storage adapter（false 或不传时为 null，纯内存模式）
+  const storageType = options.storage ?? false;
+  const adapter = storageType !== false ? createStorageAdapter(storageType) : null;
+
+  const auth = buildAuthReturn(state, options, adapter);
+
+  // ── 跨 tab 同步（仅 localStorage 有效）──────────────────────────────────
+  if (storageType === 'local' && typeof window !== 'undefined') {
+    const onStorageChange = (e: StorageEvent) => {
+      if (e.key !== STORAGE_KEY_TOKEN) return;
+      // 其他 tab 清除了 token → 本 tab 也登出
+      if (e.newValue === null) {
+        state.user = null;
+        state.permissions = [];
+        state.token = null;
+      }
+    };
+    window.addEventListener('storage', onStorageChange);
+
+    // app.unmount 时清理监听器，防止泄漏
+    const origUnmount = app.unmount.bind(app);
+    app.unmount = () => {
+      window.removeEventListener('storage', onStorageChange);
+      origUnmount();
+    };
+  }
+
+  // 将 auth 实例注入 Vue 组件树，同时挂载 onUnauthorized 回调供 authGuard 使用
+  app.provide(AUTH_INJECT_KEY, { auth, onUnauthorized: options.onUnauthorized });
+
+  return auth;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// useAuth — 任意组件中使用
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 在组件中获取全局 auth 实例。
+ * 必须在 createAuth() 已安装的 App 子树内调用。
+ *
+ * @throws 若 createAuth() 尚未调用，抛出清晰的错误提示。
+ *
+ * @example
+ * ```ts
+ * const { isAuthenticated, can, login } = useAuth();
+ * if (!can('order', 'delete')) { ... }
+ * ```
+ */
+export function useAuth(): AuthReturn {
+  const provided = inject(AUTH_INJECT_KEY);
+  if (!provided) {
+    throw new Error('[useAuth] 未找到 auth 实例，请先在根 App 调用 createAuth()。');
+  }
+  return provided.auth;
+}
+
+/**
+ * 内部使用：获取完整 provide 对象（含 onUnauthorized 回调），供 authGuard 使用。
+ * 不作为公开 API 导出。
+ */
+export function useAuthProvide(): AuthProvide {
+  const provided = inject(AUTH_INJECT_KEY);
+  if (!provided) {
+    throw new Error('[useAuthProvide] 未找到 auth 实例，请先在根 App 调用 createAuth()。');
+  }
+  return provided;
+}

package/composables/auth/vCan.ts

@@ -0,0 +1,95 @@
+/**
+ * @description v-can 自定义指令，无权限时隐藏元素
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { Directive, DirectiveBinding } from 'vue';
+import type { AuthReturn, PermissionScope } from './types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 指令绑定值类型
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 对象写法：v-can="{ resource: 'order', action: 'delete', scope: 'all' }" */
+export interface CanBindingObject {
+  resource: string;
+  action: string;
+  scope?: PermissionScope;
+}
+
+/**
+ * 字符串写法：v-can="'order:delete'" 或 v-can="'order:delete:all'"
+ * 格式：`resource:action` 或 `resource:action:scope`
+ */
+export type CanBinding = CanBindingObject | string;
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部辅助
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 将字符串简写解析为标准对象 */
+function parseBinding(value: CanBinding): CanBindingObject {
+  if (typeof value === 'object') return value;
+
+  const parts = value.split(':');
+  const resource = parts[0] ?? '';
+  const action = parts[1] ?? '';
+  const scope = parts[2] as PermissionScope | undefined;
+  return { resource, action, scope };
+}
+
+/** 根据权限检查结果更新元素可见性 */
+function applyVisibility(el: HTMLElement, auth: AuthReturn, binding: CanBinding): void {
+  const { resource, action, scope } = parseBinding(binding);
+  const allowed = auth.can(resource, action, scope);
+  el.style.display = allowed ? '' : 'none';
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// createVCan — 工厂函数，需绑定 auth 实例
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 创建 v-can 自定义指令。
+ * 需要传入 useAuth() 返回的 auth 实例。
+ *
+ * @example
+ * ```ts
+ * // main.ts
+ * import { useAuth, createVCan } from '@kine-design/crud';
+ *
+ * const app = createApp(App);
+ * createAuth(app, { fetchUser });
+ *
+ * // 需在 createAuth 之后调用（此时 inject 上下文已就绪）
+ * // 推荐在根组件 setup 中注册，或通过 auth 实例直接传入
+ * const auth = createAuth(app, { fetchUser });
+ * app.directive('can', createVCan(auth));
+ * ```
+ *
+ * 用法：
+ * ```html
+ * <!-- 对象写法 -->
+ * <button v-can="{ resource: 'order', action: 'delete' }">删除</button>
+ *
+ * <!-- 字符串简写 -->
+ * <button v-can="'order:delete'">删除</button>
+ *
+ * <!-- 带 scope -->
+ * <button v-can="'order:delete:all'">删除（全量权限）</button>
+ * ```
+ */
+export function createVCan(auth: AuthReturn): Directive<HTMLElement, CanBinding> {
+  return {
+    mounted(el: HTMLElement, binding: DirectiveBinding<CanBinding>): void {
+      applyVisibility(el, auth, binding.value);
+    },
+    updated(el: HTMLElement, binding: DirectiveBinding<CanBinding>): void {
+      applyVisibility(el, auth, binding.value);
+    },
+  };
+}

package/composables/defineRepository.ts

@@ -0,0 +1,224 @@
+/**
+ * @description 数据层核心 — 封装 TanStack Query Vue，业务代码不直接碰 TanStack Query
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import { computed, isRef, toRef, type MaybeRef } from 'vue';
+import {
+  useQuery,
+  useMutation,
+  useQueryClient,
+} from '@tanstack/vue-query';
+import type {
+  EntityId,
+  ListParams,
+  MutationOptions,
+  Repository,
+  RepositoryEndpoints,
+  UseDetailReturn,
+  UseListReturn,
+  UseMutationReturn,
+} from './types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部辅助
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 将 MaybeRef 统一转为 Ref，保证 query key 的响应性。
+ * Vue 3.3+ toRef() 支持直接传入原始值。
+ */
+function normalizeRef<T>(value: MaybeRef<T>) {
+  return isRef(value) ? value : toRef(() => value as T);
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// defineRepository
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 定义一个领域数据仓库。
+ *
+ * @param domain  领域 key，用于 query key 命名空间与缓存失效边界。
+ * @param endpoints  原始 API 函数集合。
+ *
+ * @example
+ * ```ts
+ * const orderRepo = defineRepository('order', {
+ *   list:   (params) => http.get('/api/orders', params),
+ *   detail: (id)     => http.get(`/api/orders/${id}`),
+ *   create: (data)   => http.post('/api/orders', data),
+ *   update: (id, data) => http.put(`/api/orders/${id}`, data),
+ *   remove: (id)     => http.delete(`/api/orders/${id}`),
+ * });
+ *
+ * // 列表
+ * const { data, isLoading } = orderRepo.useList(searchParams);
+ *
+ * // 跨领域联动
+ * const { mutate } = orderRepo.useUpdate({ invalidates: ['customer'] });
+ * ```
+ */
+export function defineRepository<
+  TList = unknown,
+  TDetail = unknown,
+  TCreateInput = unknown,
+  TCreateOutput = unknown,
+  TUpdateInput = unknown,
+  TUpdateOutput = unknown,
+>(
+  domain: string,
+  endpoints: RepositoryEndpoints<TList, TDetail, TCreateInput, TCreateOutput, TUpdateInput, TUpdateOutput>,
+): Repository<TList, TDetail, TCreateInput, TCreateOutput, TUpdateInput, TUpdateOutput> {
+
+  // ── useList ───────────────────────────────────────────────────────────────
+
+  const useList = (params?: MaybeRef<ListParams>): UseListReturn<TList> => {
+    const paramsRef = normalizeRef<ListParams>(params ?? {});
+
+    const query = useQuery({
+      // query key 包含 params，params 变化时自动重新请求
+      queryKey: computed(() => [domain, 'list', paramsRef.value]),
+      queryFn: () => {
+        if (!endpoints.list) {
+          return Promise.reject(new Error(`[defineRepository:${domain}] list endpoint 未定义`));
+        }
+        return endpoints.list(paramsRef.value);
+      },
+    });
+
+    return {
+      data: computed(() => query.data.value),
+      isLoading: computed(() => query.isLoading.value),
+      isFetching: computed(() => query.isFetching.value),
+      isError: computed(() => query.isError.value),
+      error: computed(() => query.error.value),
+      refetch: () => { query.refetch(); },
+    };
+  };
+
+  // ── useDetail ─────────────────────────────────────────────────────────────
+
+  const useDetail = (id: MaybeRef<EntityId>): UseDetailReturn<TDetail> => {
+    const idRef = normalizeRef(id);
+
+    const query = useQuery({
+      queryKey: computed(() => [domain, 'detail', idRef.value]),
+      queryFn: () => {
+        if (!endpoints.detail) {
+          return Promise.reject(new Error(`[defineRepository:${domain}] detail endpoint 未定义`));
+        }
+        return endpoints.detail(idRef.value);
+      },
+      // id 为空时不发请求
+      enabled: computed(() => idRef.value !== undefined && idRef.value !== null && idRef.value !== ''),
+    });
+
+    return {
+      data: computed(() => query.data.value),
+      isLoading: computed(() => query.isLoading.value),
+      isFetching: computed(() => query.isFetching.value),
+      isError: computed(() => query.isError.value),
+      error: computed(() => query.error.value),
+      refetch: () => { query.refetch(); },
+    };
+  };
+
+  // ── 内部：失效当前领域 + 跨领域联动 ──────────────────────────────────────
+
+  function buildInvalidateHandler(options?: MutationOptions) {
+    return async (queryClient: ReturnType<typeof useQueryClient>) => {
+      // 失效当前领域所有 query（list + detail + 任意子 key）
+      await queryClient.invalidateQueries({ queryKey: [domain] });
+
+      // 跨领域联动：失效显式声明的其他领域
+      if (options?.invalidates?.length) {
+        await Promise.all(
+          options.invalidates.map(d =>
+            queryClient.invalidateQueries({ queryKey: [d] }),
+          ),
+        );
+      }
+    };
+  }
+
+  // ── useCreate ─────────────────────────────────────────────────────────────
+
+  const useCreate = (options?: MutationOptions): UseMutationReturn<TCreateInput, TCreateOutput> => {
+    const queryClient = useQueryClient();
+    const invalidate = buildInvalidateHandler(options);
+
+    const mutation = useMutation<TCreateOutput, Error, TCreateInput>({
+      mutationFn: (data: TCreateInput) => {
+        if (!endpoints.create) {
+          return Promise.reject(new Error(`[defineRepository:${domain}] create endpoint 未定义`));
+        }
+        return endpoints.create(data);
+      },
+      onSuccess: () => invalidate(queryClient),
+    });
+
+    return {
+      // 类型断言：确保签名与泛型约束一致
+      mutate: ((data: TCreateInput) => mutation.mutateAsync(data)) as UseMutationReturn<TCreateInput, TCreateOutput>['mutate'],
+      isPending: computed(() => mutation.isPending.value),
+      isError: computed(() => mutation.isError.value),
+      error: computed(() => mutation.error.value),
+    };
+  };
+
+  // ── useUpdate ─────────────────────────────────────────────────────────────
+
+  const useUpdate = (options?: MutationOptions): UseMutationReturn<{ id: EntityId; data: TUpdateInput }, TUpdateOutput> => {
+    const queryClient = useQueryClient();
+    const invalidate = buildInvalidateHandler(options);
+
+    const mutation = useMutation<TUpdateOutput, Error, { id: EntityId; data: TUpdateInput }>({
+      mutationFn: ({ id, data }) => {
+        if (!endpoints.update) {
+          return Promise.reject(new Error(`[defineRepository:${domain}] update endpoint 未定义`));
+        }
+        return endpoints.update(id, data);
+      },
+      onSuccess: () => invalidate(queryClient),
+    });
+
+    return {
+      mutate: ((variables: { id: EntityId; data: TUpdateInput }) =>
+        mutation.mutateAsync(variables)) as UseMutationReturn<{ id: EntityId; data: TUpdateInput }, TUpdateOutput>['mutate'],
+      isPending: computed(() => mutation.isPending.value),
+      isError: computed(() => mutation.isError.value),
+      error: computed(() => mutation.error.value),
+    };
+  };
+
+  // ── useRemove ─────────────────────────────────────────────────────────────
+
+  const useRemove = (options?: MutationOptions): UseMutationReturn<EntityId, void> => {
+    const queryClient = useQueryClient();
+    const invalidate = buildInvalidateHandler(options);
+
+    const mutation = useMutation<void, Error, EntityId>({
+      mutationFn: (id: EntityId) => {
+        if (!endpoints.remove) {
+          return Promise.reject(new Error(`[defineRepository:${domain}] remove endpoint 未定义`));
+        }
+        return endpoints.remove(id);
+      },
+      onSuccess: () => invalidate(queryClient),
+    });
+
+    return {
+      mutate: ((id: EntityId) => mutation.mutateAsync(id)) as UseMutationReturn<EntityId, void>['mutate'],
+      isPending: computed(() => mutation.isPending.value),
+      isError: computed(() => mutation.isError.value),
+      error: computed(() => mutation.error.value),
+    };
+  };
+
+  return { useList, useDetail, useCreate, useUpdate, useRemove };
+}

package/composables/error/createErrorHandler.ts

@@ -0,0 +1,46 @@
+/**
+ * @description 全局错误处理器，注册 Vue app.config.errorHandler 统一捕获未处理错误
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { App } from 'vue';
+import type { ErrorHandlerOptions } from './types';
+import { ERROR_HANDLER_INJECT_KEY } from './types';
+import { dispatchError } from './dispatchError';
+
+// ────────────────────────────────────────────────────────────────────────────
+// createErrorHandler — 应用初始化时调用
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 创建全局错误处理器并安装到 Vue App。
+ * 注册 app.config.errorHandler 统一捕获未处理错误，
+ * 并通过 provide 将配置注入组件树供 useErrorHandler() 使用。
+ *
+ * @example
+ * ```ts
+ * // main.ts
+ * import { createApp } from 'vue';
+ * import { createErrorHandler } from '@kine-design/crud';
+ *
+ * const app = createApp(App);
+ * createErrorHandler(app, {
+ *   feedbackHandler: myFeedbackHandler,
+ *   unauthorizedStrategy: 'redirect',
+ * });
+ * app.mount('#app');
+ * ```
+ */
+export function createErrorHandler(app: App, options: ErrorHandlerOptions = {}): void {
+  // 注册 Vue 全局错误处理
+  app.config.errorHandler = (err) => {
+    dispatchError(err, options);
+  };
+
+  // 将配置注入组件树
+  app.provide(ERROR_HANDLER_INJECT_KEY, options);
+}