@kine-design/crud 0.0.1-beta.1

package/dist/composables/auth/types.d.ts

@@ -0,0 +1,90 @@
+import { ComputedRef } from 'vue';
+/**
+ * @description 权限系统类型定义
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+/**
+ * 权限范围层级，从低到高：own < department < all
+ * '*' 表示通配，匹配任意 scope
+ */
+export type PermissionScope = 'own' | 'department' | 'all' | '*';
+/** 单条权限记录 */
+export interface Permission {
+    /** 资源标识，如 'order'、'user'、'report' */
+    resource: string;
+    /** 操作标识，如 'read'、'create'、'update'、'delete'，'*' 表示所有操作 */
+    action: string;
+    /** 数据范围，不传时表示不受范围限制 */
+    scope?: PermissionScope;
+}
+/** 当前登录用户信息 */
+export interface UserInfo {
+    id: string | number;
+    username: string;
+    /** 业务扩展字段 */
+    [key: string]: unknown;
+}
+/** Auth 响应式状态（内部使用） */
+export interface AuthState {
+    user: UserInfo | null;
+    permissions: Permission[];
+    token: string | null;
+}
+/** createAuth 初始化选项 */
+export interface AuthOptions {
+    /**
+     * 获取当前用户信息及权限列表。
+     * login() 和应用初始化时均会调用此函数。
+     */
+    fetchUser: () => Promise<{
+        user: UserInfo;
+        permissions: Permission[];
+        token: string;
+    }>;
+    /**
+     * 未登录时的处理回调（通常用于跳转登录页）。
+     * 不传时什么都不做。
+     */
+    onUnauthorized?: () => void;
+    /**
+     * 持久化存储类型。
+     * - 'local'：使用 localStorage，支持跨 tab 同步
+     * - 'session'：使用 sessionStorage
+     * - false（默认）：纯内存，不持久化
+     */
+    storage?: 'local' | 'session' | false;
+}
+/** useAuth() 的返回值类型 */
+export interface AuthReturn {
+    /** 当前用户，未登录时为 null */
+    user: ComputedRef<UserInfo | null>;
+    /** 当前权限列表 */
+    permissions: ComputedRef<Permission[]>;
+    /** 当前 token，未登录时为 null */
+    token: ComputedRef<string | null>;
+    /** 是否已认证（user 非 null 且 token 非 null） */
+    isAuthenticated: ComputedRef<boolean>;
+    /**
+     * 检查是否有指定权限。
+     * @param resource  资源标识
+     * @param action    操作标识
+     * @param scope     数据范围（不传时不检查 scope 层级）
+     */
+    can: (resource: string, action: string, scope?: PermissionScope) => boolean;
+    /** 调用 fetchUser 完成登录，更新 auth 状态 */
+    login: () => Promise<void>;
+    /** 直接注入登录结果到 auth 状态（供 defineUserStore 等外部流程使用） */
+    loginWith: (result: {
+        user: UserInfo;
+        permissions: Permission[];
+        token: string;
+    }) => void;
+    /** 清除 auth 状态（登出） */
+    logout: () => void;
+    /** 从 storage 恢复认证状态，供应用启动时调用 */
+    restore: () => Promise<void>;
+}

package/dist/composables/auth/useAuth.d.ts

@@ -0,0 +1,45 @@
+import { App } from 'vue';
+import { AuthOptions, AuthReturn } from './types';
+/**
+ * 创建全局 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 declare function createAuth(app: App, options: AuthOptions): AuthReturn;
+/** 内部 provide 结构，包含 auth 实例与 onUnauthorized 回调 */
+interface AuthProvide {
+    auth: AuthReturn;
+    onUnauthorized: (() => void) | undefined;
+}
+/**
+ * 在组件中获取全局 auth 实例。
+ * 必须在 createAuth() 已安装的 App 子树内调用。
+ *
+ * @throws 若 createAuth() 尚未调用，抛出清晰的错误提示。
+ *
+ * @example
+ * ```ts
+ * const { isAuthenticated, can, login } = useAuth();
+ * if (!can('order', 'delete')) { ... }
+ * ```
+ */
+export declare function useAuth(): AuthReturn;
+/**
+ * 内部使用：获取完整 provide 对象（含 onUnauthorized 回调），供 authGuard 使用。
+ * 不作为公开 API 导出。
+ */
+export declare function useAuthProvide(): AuthProvide;
+export {};

package/dist/composables/auth/vCan.d.ts

@@ -0,0 +1,44 @@
+import { Directive } from 'vue';
+import { 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;
+/**
+ * 创建 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 declare function createVCan(auth: AuthReturn): Directive<HTMLElement, CanBinding>;

package/dist/composables/defineRepository.d.ts

@@ -0,0 +1,25 @@
+import { Repository, RepositoryEndpoints } from './types';
+/**
+ * 定义一个领域数据仓库。
+ *
+ * @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 declare 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>;

package/dist/composables/error/createErrorHandler.d.ts

@@ -0,0 +1,22 @@
+import { App } from 'vue';
+import { ErrorHandlerOptions } from './types';
+/**
+ * 创建全局错误处理器并安装到 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 declare function createErrorHandler(app: App, options?: ErrorHandlerOptions): void;

package/dist/composables/error/defaultFeedbackHandler.d.ts

@@ -0,0 +1,3 @@
+import { UserFeedbackHandler } from './types';
+/** 默认的 UserFeedbackHandler 实现 */
+export declare const defaultFeedbackHandler: UserFeedbackHandler;

package/dist/composables/error/dispatchError.d.ts

@@ -0,0 +1,6 @@
+import { ErrorHandlerOptions } from './types';
+/**
+ * 统一的错误分发逻辑。
+ * createErrorHandler 和 useErrorHandler 共用此函数。
+ */
+export declare function dispatchError(error: unknown, options: ErrorHandlerOptions): void;

package/dist/composables/error/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @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/dist/composables/error/types.d.ts

@@ -0,0 +1,28 @@
+import { UserFeedbackHandler, NetworkError, BusinessError } from '../request/types';
+/**
+ * @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';
+/** provide/inject 使用的唯一 symbol key，避免命名冲突 */
+export declare const ERROR_HANDLER_INJECT_KEY: unique symbol;
+/** createErrorHandler 配置项 */
+export interface ErrorHandlerOptions {
+    /** 用户反馈处理器，默认使用 defaultFeedbackHandler */
+    feedbackHandler?: UserFeedbackHandler;
+    /** 未授权处理策略，默认 'redirect' */
+    unauthorizedStrategy?: UnauthorizedStrategy;
+    /** 业务错误自定义处理，返回 true 表示已处理（跳过默认行为） */
+    onBusinessError?: (error: BusinessError) => void;
+    /** 网络错误自定义处理 */
+    onNetworkError?: (error: NetworkError) => void;
+}

package/dist/composables/error/useErrorHandler.d.ts

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

package/dist/composables/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @description composables barrel export
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export { defineRepository } from './defineRepository';
+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/dist/composables/request/composables.d.ts

@@ -0,0 +1,44 @@
+import { Ref } from 'vue';
+import { RequestClient } from './createRequest';
+/**
+ * 在组件 setup 中使用，onUnmounted 时自动取消所有 pending 请求。
+ * 返回经过生命周期管理的 client 代理。
+ */
+export declare function useRequest(client: RequestClient): RequestClient;
+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 declare function usePolling<T>(fn: () => Promise<T>, interval: number): UsePollingReturn<T>;
+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 declare function useBatchLoader<K, V>(batchFn: (keys: K[]) => Promise<V[]>, options?: BatchLoaderOptions): UseBatchLoaderReturn<K, V>;

package/dist/composables/request/controlGate.d.ts

@@ -0,0 +1,21 @@
+import { ControlPolicy, RequestMethod } from './types';
+/** 根据请求方法、URL 和参数生成唯一的缓存 key */
+export declare function buildCacheKey(method: RequestMethod, url: string, body?: unknown): string;
+export declare class ControlGate {
+    /** 防抖：取消前一个 timer */
+    private debounceMap;
+    /** 节流：记录上次执行时间 */
+    private throttleMap;
+    /** 去重：共享同一个 Promise */
+    private deduplicateMap;
+    /**
+     * 通过控制门执行请求。
+     * 按配置依次应用防抖、节流、去重策略。
+     */
+    execute<T>(key: string, fn: () => Promise<T>, policy: ControlPolicy): Promise<T>;
+    /** 清理所有挂起的 timer 和状态 */
+    dispose(): void;
+    private withDebounce;
+    private waitThrottle;
+    private withDeduplicate;
+}

package/dist/composables/request/createRequest.d.ts

@@ -0,0 +1,31 @@
+import { RequestMethod, RequestOptions } from './types';
+import { RequestBuilder } from './requestBuilder';
+export interface RequestClient {
+    /** 简便方法，直接返回 Promise<T> */
+    send<T>(method: RequestMethod, url: string, body?: unknown): Promise<T>;
+    /** GET 请求 */
+    get<T>(url: string, params?: Record<string, unknown>): Promise<T>;
+    /** POST 请求 */
+    post<T>(url: string, body?: unknown): Promise<T>;
+    /** PUT 请求 */
+    put<T>(url: string, body?: unknown): Promise<T>;
+    /** PATCH 请求 */
+    patch<T>(url: string, body?: unknown): Promise<T>;
+    /** DELETE 请求 */
+    delete<T>(url: string, body?: unknown): Promise<T>;
+    /** 返回 RequestBuilder，支持链式配置 */
+    request(method: RequestMethod, url: string, body?: unknown): RequestBuilder;
+    /** 注册 AbortController，供外部管理请求取消 */
+    registerAbortController(controller: AbortController): void;
+    /** 取消所有 pending 请求 */
+    abortAll(): void;
+    /** 销毁客户端，清理所有资源 */
+    dispose(): void;
+}
+export declare function createRequest(options?: RequestOptions): RequestClient;
+/** 默认配置：适用于大多数场景 */
+export declare function createDefaultRequest(options?: RequestOptions): RequestClient;
+/** 严格配置：无重试、短超时 */
+export declare function createStrictRequest(options?: RequestOptions): RequestClient;
+/** 宽松配置：多重试、长超时 */
+export declare function createPermissiveRequest(options?: RequestOptions): RequestClient;

package/dist/composables/request/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @description 请求模块统一导出
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export type { RequestMethod, ControlPolicy, CachePolicy, RetryPolicy, Lifecycle, RequestConfig, WrappedResponse, NetworkError, UserFeedbackHandler, Transport, TransportRequest, TransportResponse, RequestOptions, OrchestratorNode, FailureStrategy, UploadOptions, UploaderOptions, } from './types';
+export { BusinessError, NetworkRequestError } from './types';
+export { ControlGate, buildCacheKey } from './controlGate';
+export { FetchTransport } from './transport/fetchTransport';
+export { XhrTransport } from './transport/xhrTransport';
+export { RequestBuilder } from './requestBuilder';
+export type { RequestBuilderContext } from './requestBuilder';
+export { createRequest, createDefaultRequest, createStrictRequest, createPermissiveRequest, } from './createRequest';
+export type { RequestClient } from './createRequest';
+export { orchestrate, createNode, after } from './orchestrator';
+export type { OrchestratorResult } from './orchestrator';
+export { useRequest, usePolling, useBatchLoader } from './composables';
+export type { UsePollingReturn, BatchLoaderOptions, UseBatchLoaderReturn } from './composables';
+export { createUploader } from './upload';
+export type { UploadHandle, Uploader } from './upload';

package/dist/composables/request/orchestrator.d.ts

@@ -0,0 +1,16 @@
+import { FailureStrategy, OrchestratorNode } from './types';
+export interface OrchestratorResult {
+    /** 所有成功节点的结果 */
+    results: Map<string, unknown>;
+    /** 失败节点的错误（仅 continueOnError 模式下存在） */
+    errors: Map<string, Error>;
+}
+/**
+ * 执行 DAG 编排。
+ * 拓扑排序 → 分层 → 同层 Promise.all 并发 → 收集结果。
+ */
+export declare function orchestrate(nodes: OrchestratorNode[], failureStrategy?: FailureStrategy): Promise<OrchestratorResult>;
+/** 创建编排节点 */
+export declare function createNode<T>(id: string, execute: () => Promise<T>, dependencies?: string[]): OrchestratorNode<T>;
+/** 声明依赖关系 — 返回带有 dependencies 的节点配置 */
+export declare function after(...deps: string[]): <T>(id: string, execute: () => Promise<T>) => OrchestratorNode<T>;

package/dist/composables/request/requestBuilder.d.ts

@@ -0,0 +1,34 @@
+import { CachePolicy, Lifecycle, RequestMethod, RetryPolicy, Transport } from './types';
+import { ControlGate } from './controlGate';
+export interface RequestBuilderContext {
+    transport: Transport;
+    controlGate: ControlGate;
+    baseURL: string;
+    defaultHeaders: Record<string, string>;
+    getToken?: () => string | null | undefined;
+    onUnauthorized?: () => void;
+    responseInterceptor?: <T>(data: T) => T;
+    /** 注册 abort controller，供生命周期管理 */
+    registerAbort?: (controller: AbortController) => void;
+}
+export declare class RequestBuilder {
+    private method;
+    private url;
+    private body;
+    private config;
+    private context;
+    private customHeaders;
+    constructor(context: RequestBuilderContext, method: RequestMethod, url: string, body?: unknown);
+    cache(policy: CachePolicy): this;
+    retry(policy: RetryPolicy): this;
+    debounce(delay: number): this;
+    throttle(interval: number): this;
+    deduplicate(enabled?: boolean): this;
+    timeout(ms: number): this;
+    totalTimeout(ms: number): this;
+    lifecycle(lc: Lifecycle): this;
+    priority(p: number): this;
+    headers(h: Record<string, string>): this;
+    execute<T>(): Promise<T>;
+    private executeTransport;
+}

package/dist/composables/request/transport/fetchTransport.d.ts

@@ -0,0 +1,4 @@
+import { Transport, TransportRequest, TransportResponse } from '../types';
+export declare class FetchTransport implements Transport {
+    send(request: TransportRequest): Promise<TransportResponse>;
+}

package/dist/composables/request/transport/xhrTransport.d.ts

@@ -0,0 +1,4 @@
+import { Transport, TransportRequest, TransportResponse } from '../types';
+export declare class XhrTransport implements Transport {
+    send(request: TransportRequest): Promise<TransportResponse>;
+}