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

package/composables/storage/createStorageAdapter.ts

@@ -0,0 +1,72 @@
+/**
+ * @description 命令式 Storage 适配器，供 Auth 等模块做持久化
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { StorageType } from './types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// StorageAdapter 接口
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface StorageAdapter {
+  /** 读取并反序列化，key 不存在时返回 null */
+  get<T>(key: string): T | null;
+  /** 序列化并写入 */
+  set<T>(key: string, value: T): void;
+  /** 移除指定 key */
+  remove(key: string): void;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// createStorageAdapter
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 创建非响应式的命令式 Storage 适配器。
+ * 内部直接操作 localStorage / sessionStorage，JSON 序列化。
+ *
+ * @example
+ * ```ts
+ * const adapter = createStorageAdapter('local');
+ * adapter.set('user', { name: '阿怪' });
+ * const user = adapter.get<{ name: string }>('user');
+ * adapter.remove('user');
+ * ```
+ */
+export function createStorageAdapter(storageType: StorageType): StorageAdapter {
+  function resolveStorage(): Storage | null {
+    if (typeof window === 'undefined') return null;
+    return storageType === 'local' ? window.localStorage : window.sessionStorage;
+  }
+
+  return {
+    get<T>(key: string): T | null {
+      const storage = resolveStorage();
+      if (!storage) return null;
+      const raw = storage.getItem(key);
+      if (raw === null) return null;
+      try {
+        return JSON.parse(raw) as T;
+      } catch {
+        return raw as T;
+      }
+    },
+
+    set<T>(key: string, value: T): void {
+      const storage = resolveStorage();
+      if (!storage) return;
+      storage.setItem(key, typeof value === 'string' ? value : JSON.stringify(value));
+    },
+
+    remove(key: string): void {
+      const storage = resolveStorage();
+      if (!storage) return;
+      storage.removeItem(key);
+    },
+  };
+}

package/composables/storage/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @description 响应式 Storage 模块统一导出
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export { useStorage } from './useStorage';
+export { createStorageAdapter } from './createStorageAdapter';
+export type { StorageAdapter } from './createStorageAdapter';
+export type { StorageType, StorageOptions, UseStorageReturn } from './types';

package/composables/storage/types.ts

@@ -0,0 +1,30 @@
+/**
+ * @description 响应式 Storage 模块类型定义
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { Ref } from 'vue';
+
+// ────────────────────────────────────────────────────────────────────────────
+// Storage 类型
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 存储类型：localStorage 或 sessionStorage */
+export type StorageType = 'local' | 'session';
+
+/** useStorage 配置项 */
+export interface StorageOptions<T> {
+  /** 自定义序列化函数，默认 JSON.stringify */
+  serializer?: (value: T) => string;
+  /** 自定义反序列化函数，默认 JSON.parse */
+  deserializer?: (raw: string) => T;
+  /** 是否监听跨 tab 同步（仅 localStorage 有效），默认 true */
+  listenCrossTab?: boolean;
+}
+
+/** useStorage 返回值 */
+export type UseStorageReturn<T> = Ref<T | null>;

package/composables/storage/useStorage.ts

@@ -0,0 +1,108 @@
+/**
+ * @description 响应式 Storage composable，自动序列化与跨 tab 同步
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import { ref, watch, onUnmounted, type Ref } from 'vue';
+import type { StorageOptions, StorageType, UseStorageReturn } from './types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 内部辅助
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 根据 StorageType 获取对应的 Web Storage 实例，SSR 环境返回 null */
+function resolveStorage(storageType: StorageType): Storage | null {
+  if (typeof window === 'undefined') return null;
+  return storageType === 'local' ? window.localStorage : window.sessionStorage;
+}
+
+/** 默认序列化：string 直接返回，其余 JSON.stringify */
+function defaultSerializer<T>(value: T): string {
+  return typeof value === 'string' ? value : JSON.stringify(value);
+}
+
+/** 默认反序列化：尝试 JSON.parse，失败则返回原始字符串 */
+function defaultDeserializer<T>(raw: string): T {
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return raw as T;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// useStorage
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 返回一个与 Web Storage 双向绑定的响应式 Ref。
+ *
+ * - 读取时从 storage 反序列化并缓存到内存
+ * - 写入时自动序列化并存入 storage，设为 null 时 removeItem
+ * - localStorage 默认监听 storage 事件实现跨 tab 同步
+ * - SSR 安全：服务端降级为纯内存 ref
+ *
+ * @example
+ * ```ts
+ * const token = useStorage<string>('auth-token');
+ * token.value = 'xxx';          // 自动写入 localStorage
+ * token.value = null;           // 自动 removeItem
+ * ```
+ */
+export function useStorage<T>(
+  key: string,
+  defaultValue?: T,
+  storageType: StorageType = 'local',
+  options: StorageOptions<T> = {},
+): UseStorageReturn<T> {
+  const storage = resolveStorage(storageType);
+  const serialize = options.serializer ?? defaultSerializer;
+  const deserialize = options.deserializer ?? defaultDeserializer;
+  const listenCrossTab = options.listenCrossTab ?? true;
+
+  // ── 初始化：从 storage 读取或使用默认值 ──────────────────────────────────
+
+  function readFromStorage(): T | null {
+    if (!storage) return defaultValue ?? null;
+    const raw = storage.getItem(key);
+    if (raw === null) return defaultValue ?? null;
+    return deserialize(raw);
+  }
+
+  const data: Ref<T | null> = ref(readFromStorage()) as Ref<T | null>;
+
+  // ── watch：值变化时写入 storage ────────────────────────────────────────
+
+  watch(data, (newValue) => {
+    if (!storage) return;
+    if (newValue === null || newValue === undefined) {
+      storage.removeItem(key);
+    } else {
+      storage.setItem(key, serialize(newValue));
+    }
+  }, { deep: true });
+
+  // ── 跨 tab 同步（仅 localStorage） ────────────────────────────────────
+
+  let onStorageChange: ((e: StorageEvent) => void) | null = null;
+
+  if (storage && storageType === 'local' && listenCrossTab && typeof window !== 'undefined') {
+    onStorageChange = (e: StorageEvent) => {
+      if (e.key !== key || e.storageArea !== storage) return;
+      data.value = e.newValue === null ? (defaultValue ?? null) : deserialize(e.newValue);
+    };
+    window.addEventListener('storage', onStorageChange);
+
+    onUnmounted(() => {
+      if (onStorageChange) {
+        window.removeEventListener('storage', onStorageChange);
+      }
+    });
+  }
+
+  return data;
+}

package/composables/store/defineUserStore.ts

@@ -0,0 +1,122 @@
+/**
+ * @description 用户 Store 工厂，基于 Pinia + Auth 实现登录/登出/权限管理
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import { computed } from 'vue';
+import { defineStore } from 'pinia';
+import { useAuth } from '../auth/useAuth';
+import type { Permission, PermissionScope, UserInfo } from '../auth/types';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 类型定义
+// ────────────────────────────────────────────────────────────────────────────
+
+/** loginApi 返回的登录结果 */
+export interface LoginResult {
+  user: UserInfo;
+  permissions: Permission[];
+  token: string;
+}
+
+/** defineUserStore 的配置选项 */
+export interface UserStoreOptions {
+  /** 登录 API 调用 */
+  loginApi: (credentials: { account: string; password: string }) => Promise<LoginResult>;
+  /** 登录成功后的回调（通常用于跳转首页） */
+  onLoginSuccess?: () => void;
+  /** 登出后的回调（通常用于跳转登录页） */
+  onLogoutSuccess?: () => void;
+}
+
+/** defineUserStore 返回的 store 实例类型（Pinia 会自动解包 ComputedRef） */
+export interface UserStore {
+  /** 当前用户 */
+  readonly user: UserInfo | null;
+  /** 是否已登录 */
+  readonly isLoggedIn: boolean;
+  /** 当前 token */
+  readonly token: string | null;
+  /** 权限列表 */
+  readonly permissions: Permission[];
+  /** 权限检查 */
+  can: (resource: string, action: string, scope?: PermissionScope) => boolean;
+  /** 完整登录流程：调 loginApi → auth.loginWith() → 持久化 → onLoginSuccess */
+  login: (account: string, password: string) => Promise<void>;
+  /** 登出：auth.logout() → onLogoutSuccess */
+  logout: () => void;
+  /** 启动时恢复状态：从 storage 恢复 → fetchUser 验证 */
+  initUser: () => Promise<void>;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// defineUserStore — 工厂函数
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 创建用户 Store 的工厂函数。
+ * 返回一个 Pinia useStore 函数，调用时返回 UserStore 实例。
+ *
+ * 内部消费 useAuth() 获取底层 auth 状态，所有数据源于 auth 的 reactive state，
+ * Pinia store 仅作为组合层，不重复持有状态。
+ *
+ * @example
+ * ```ts
+ * // stores/user.ts
+ * import { defineUserStore } from '@kine-design/crud';
+ *
+ * export const useUserStore = defineUserStore({
+ *   loginApi: (creds) => http.post('/api/login', creds),
+ *   onLoginSuccess: () => router.push('/'),
+ *   onLogoutSuccess: () => router.push('/login'),
+ * });
+ *
+ * // 组件中
+ * const userStore = useUserStore();
+ * await userStore.login('admin', '123456');
+ * ```
+ */
+export function defineUserStore(options: UserStoreOptions): () => UserStore {
+  const { loginApi, onLoginSuccess, onLogoutSuccess } = options;
+
+  const useStore = defineStore('kine-user', () => {
+    const auth = useAuth();
+
+    // ── 来自 auth 的计算属性 ─────────────────────────────────────────────
+    const user = computed(() => auth.user.value);
+    const isLoggedIn = computed(() => auth.isAuthenticated.value);
+    const token = computed(() => auth.token.value);
+    const permissions = computed(() => auth.permissions.value);
+
+    // ── 权限检查（直接委托 auth） ────────────────────────────────────────
+    function can(resource: string, action: string, scope?: PermissionScope): boolean {
+      return auth.can(resource, action, scope);
+    }
+
+    // ── 登录：调 loginApi → 注入 auth → 回调 ────────────────────────────
+    async function login(account: string, password: string): Promise<void> {
+      const result = await loginApi({ account, password });
+      auth.loginWith(result);
+      onLoginSuccess?.();
+    }
+
+    // ── 登出：清除 auth → 回调 ──────────────────────────────────────────
+    function logout(): void {
+      auth.logout();
+      onLogoutSuccess?.();
+    }
+
+    // ── 初始化：从 storage 恢复 auth 状态 ────────────────────────────────
+    async function initUser(): Promise<void> {
+      await auth.restore();
+    }
+
+    return { user, isLoggedIn, token, permissions, can, login, logout, initUser };
+  });
+
+  return useStore as () => UserStore;
+}

package/composables/store/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @description store 模块 barrel export
+ * @author 阿怪
+ * @date 2026/3/15
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+export { defineUserStore } from './defineUserStore';
+export type { UserStoreOptions, UserStore, LoginResult } from './defineUserStore';

package/composables/types.ts

@@ -0,0 +1,118 @@
+/**
+ * @description defineRepository 类型定义
+ * @author 阿怪
+ * @date 2026/2/26
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+
+import type { MaybeRef } from 'vue';
+
+// ────────────────────────────────────────────────────────────────────────────
+// 基础类型
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 通用列表请求参数 */
+export type ListParams = Record<string, unknown>;
+
+/** 通用 ID 类型 */
+export type EntityId = string | number;
+
+// ────────────────────────────────────────────────────────────────────────────
+// Endpoint 定义 — 业务层传入的原始 API 函数
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface RepositoryEndpoints<
+  TList,
+  TDetail,
+  TCreateInput,
+  TCreateOutput,
+  TUpdateInput,
+  TUpdateOutput,
+> {
+  /** 列表查询 */
+  list?: (params: ListParams) => Promise<TList>;
+  /** 单条详情查询 */
+  detail?: (id: EntityId) => Promise<TDetail>;
+  /** 创建 */
+  create?: (data: TCreateInput) => Promise<TCreateOutput>;
+  /** 更新 */
+  update?: (id: EntityId, data: TUpdateInput) => Promise<TUpdateOutput>;
+  /** 删除 */
+  remove?: (id: EntityId) => Promise<void>;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Mutation 选项
+// ────────────────────────────────────────────────────────────────────────────
+
+/** mutation 共用选项 */
+export interface MutationOptions {
+  /**
+   * 跨领域缓存失效声明。
+   * mutation 成功后除自身领域外，还会额外失效这些领域的所有 query。
+   */
+  invalidates?: string[];
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// useList / useDetail 返回类型（透传 TanStack 的核心字段）
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * useList 返回值（只暴露业务层常用字段，屏蔽 TanStack 底层细节）。
+ * 需要更多字段时可在此扩展。
+ */
+export interface UseListReturn<TData> {
+  data: import('vue').ComputedRef<TData | undefined>;
+  isLoading: import('vue').ComputedRef<boolean>;
+  isFetching: import('vue').ComputedRef<boolean>;
+  isError: import('vue').ComputedRef<boolean>;
+  error: import('vue').ComputedRef<Error | null>;
+  refetch: () => void;
+}
+
+/** useDetail 返回值 */
+export interface UseDetailReturn<TData> {
+  data: import('vue').ComputedRef<TData | undefined>;
+  isLoading: import('vue').ComputedRef<boolean>;
+  isFetching: import('vue').ComputedRef<boolean>;
+  isError: import('vue').ComputedRef<boolean>;
+  error: import('vue').ComputedRef<Error | null>;
+  refetch: () => void;
+}
+
+/** useMutation 返回值（create / update / remove 共用） */
+export interface UseMutationReturn<TVariables, TData> {
+  mutate: TVariables extends void
+    ? () => Promise<TData>
+    : (variables: TVariables) => Promise<TData>;
+  isPending: import('vue').ComputedRef<boolean>;
+  isError: import('vue').ComputedRef<boolean>;
+  error: import('vue').ComputedRef<Error | null>;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// Repository 实例接口
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface Repository<
+  TList,
+  TDetail,
+  TCreateInput,
+  TCreateOutput,
+  TUpdateInput,
+  TUpdateOutput,
+> {
+  /** 列表 query hook */
+  useList: (params?: MaybeRef<ListParams>) => UseListReturn<TList>;
+  /** 详情 query hook */
+  useDetail: (id: MaybeRef<EntityId>) => UseDetailReturn<TDetail>;
+  /** 创建 mutation hook */
+  useCreate: (options?: MutationOptions) => UseMutationReturn<TCreateInput, TCreateOutput>;
+  /** 更新 mutation hook */
+  useUpdate: (options?: MutationOptions) => UseMutationReturn<{ id: EntityId; data: TUpdateInput }, TUpdateOutput>;
+  /** 删除 mutation hook */
+  useRemove: (options?: MutationOptions) => UseMutationReturn<EntityId, void>;
+}

package/dist/components/crudPage/KCrudPage.d.ts

@@ -0,0 +1,14 @@
+import { PropType } from 'vue';
+import { CrudPageConfig } from '../../composables/page/types';
+declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    config: {
+        type: PropType<CrudPageConfig>;
+        required: true;
+    };
+}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    config: {
+        type: PropType<CrudPageConfig>;
+        required: true;
+    };
+}>> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/components/crudPage/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @description KCrudPage barrel export
+ * @author 阿怪
+ * @date 2026/3/22
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export { default as KCrudPage } from './KCrudPage';

package/dist/components/editableTable/KEditableTable.d.ts

@@ -0,0 +1,146 @@
+import { PropType } from 'vue';
+export interface EditableColumn {
+    /** 字段名 */
+    param: string;
+    /** 列标题 */
+    label: string;
+    /** 列宽 */
+    width?: string;
+    /** 输入类型 */
+    editType?: 'text' | 'number' | 'select' | 'search' | 'readonly';
+    /** select 类型的选项 */
+    options?: Array<{
+        label: string;
+        value: string | number;
+    }>;
+    /** 对齐方式 */
+    align?: 'left' | 'center' | 'right';
+    /** 是否在汇总行中求和 */
+    summary?: boolean;
+    /** 汇总行格式化 */
+    summaryFormat?: (sum: number) => string;
+}
+export interface EditableTableRow {
+    /** 行唯一标识 */
+    _id: string | number;
+    /** 行数据 */
+    [key: string]: unknown;
+}
+declare const _default: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    /** 列定义 */
+    columns: {
+        type: PropType<EditableColumn[]>;
+        required: true;
+    };
+    /** 行数据（v-model） */
+    modelValue: {
+        type: PropType<EditableTableRow[]>;
+        default: () => never[];
+    };
+    /** 标题 */
+    title: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 是否显示序号列 */
+    showIndex: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 是否显示操作列 */
+    showActions: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 是否显示汇总行 */
+    showSummary: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 汇总行标签 */
+    summaryLabel: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 新增行按钮文本 */
+    addText: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 是否可新增 */
+    addable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 币种前缀（用于金额汇总展示） */
+    currencyPrefix: {
+        type: StringConstructor;
+        default: string;
+    };
+}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, ("add" | "update:modelValue" | "remove")[], "add" | "update:modelValue" | "remove", import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    /** 列定义 */
+    columns: {
+        type: PropType<EditableColumn[]>;
+        required: true;
+    };
+    /** 行数据（v-model） */
+    modelValue: {
+        type: PropType<EditableTableRow[]>;
+        default: () => never[];
+    };
+    /** 标题 */
+    title: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 是否显示序号列 */
+    showIndex: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 是否显示操作列 */
+    showActions: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 是否显示汇总行 */
+    showSummary: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 汇总行标签 */
+    summaryLabel: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 新增行按钮文本 */
+    addText: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** 是否可新增 */
+    addable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** 币种前缀（用于金额汇总展示） */
+    currencyPrefix: {
+        type: StringConstructor;
+        default: string;
+    };
+}>> & Readonly<{
+    "onUpdate:modelValue"?: ((...args: any[]) => any) | undefined;
+    onRemove?: ((...args: any[]) => any) | undefined;
+    onAdd?: ((...args: any[]) => any) | undefined;
+}>, {
+    title: string;
+    modelValue: EditableTableRow[];
+    showIndex: boolean;
+    showActions: boolean;
+    showSummary: boolean;
+    summaryLabel: string;
+    addText: string;
+    addable: boolean;
+    currencyPrefix: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/components/editableTable/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @description editableTable barrel export
+ * @author 阿怪
+ * @date 2026/3/22
+ * @version v0.0.1
+ *
+ * 江湖的业务千篇一律，复杂的代码好几百行。
+ */
+export { default as KEditableTable } from './KEditableTable';
+export type { EditableColumn, EditableTableRow } from './KEditableTable';