@qhr123/sa2kit 0.1.1 → 0.2.0

package/README.md

@@ -1,4 +1,4 @@
-# React Utils Kit
+# SA2Kit
 
 A modern, type-safe React utility library with cross-platform support for building scalable applications.
 
@@ -12,15 +12,17 @@ A modern, type-safe React utility library with cross-platform support for buildi
 - 🎯 **React Hooks** - Custom hooks for common patterns
 - 📝 **Logger System** - Unified logging with multiple adapters
 - 💾 **Storage Adapters** - Universal storage abstraction
+- 📁 **File Upload** - Complete file management with progress tracking
+- 📊 **Data Export** - Flexible export to CSV, Excel, JSON formats
 
 ## Installation
 
 ```bash
-npm install @react-utils-kit/core
+npm install @qhr123/sa2kit
 # or
-yarn add @react-utils-kit/core
+yarn add @qhr123/sa2kit
 # or
-pnpm add @react-utils-kit/core
+pnpm add @qhr123/sa2kit
 ```
 
 ## Quick Start
@@ -28,7 +30,7 @@ pnpm add @react-utils-kit/core
 ### Logger
 
 ```typescript
-import { logger, createLogger, LogLevel } from '@react-utils-kit/core/logger';
+import { logger, createLogger, LogLevel } from '@qhr123/sa2kit/logger';
 
 // Use default logger
 logger.info('Application started');
@@ -47,7 +49,7 @@ apiLogger.info('API request completed');
 ### Utility Functions
 
 ```typescript
-import { stringUtils, arrayUtils, fileUtils } from '@react-utils-kit/core/utils';
+import { stringUtils, arrayUtils, fileUtils } from '@qhr123/sa2kit/utils';
 
 // String utilities
 const capitalized = stringUtils.capitalize('hello world');
@@ -65,7 +67,7 @@ const isValid = fileUtils.isValidFilename('document.pdf');
 ### React Hooks
 
 ```typescript
-import { useLocalStorage, useAsyncStorage } from '@react-utils-kit/core/hooks';
+import { useLocalStorage, useAsyncStorage } from '@qhr123/sa2kit/hooks';
 
 function MyComponent() {
   // Persistent state with localStorage
@@ -78,12 +80,80 @@ function MyComponent() {
 }
 ```
 
+### File Upload
+
+```typescript
+import { universalFileClient } from '@qhr123/sa2kit/universalFile';
+
+// Upload a file with progress tracking
+const uploadFile = async (file: File) => {
+  const fileMetadata = await universalFileClient.uploadFile(
+    {
+      file,
+      moduleId: 'user-avatars',
+      businessId: 'user-123',
+      permission: 'public',
+    },
+    (progress) => {
+      console.log(`Upload progress: ${progress.progress}%`);
+      console.log(`Speed: ${progress.speed} bytes/sec`);
+    }
+  );
+
+  console.log('File uploaded:', fileMetadata.id);
+  return fileMetadata;
+};
+
+// Query files
+const files = await universalFileClient.queryFiles({
+  moduleId: 'user-avatars',
+  pageSize: 20,
+});
+
+// Get file URL
+const fileUrl = await universalFileClient.getFileUrl(fileId);
+```
+
+### Data Export
+
+```typescript
+import { universalExportClient } from '@qhr123/sa2kit/universalExport';
+
+// Export data to CSV
+const exportData = async () => {
+  const result = await universalExportClient.exportData({
+    configId: 'my-export-config',
+    dataSource: async () => [
+      { id: 1, name: 'John', email: 'john@example.com' },
+      { id: 2, name: 'Jane', email: 'jane@example.com' },
+    ],
+    format: 'csv',
+    callbacks: {
+      onProgress: (progress) => {
+        console.log(`Export progress: ${progress.progress}%`);
+      },
+      onSuccess: (result) => {
+        console.log('Export completed:', result.fileName);
+        // Download the file
+        const url = URL.createObjectURL(result.fileBlob!);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = result.fileName;
+        a.click();
+      },
+    },
+  });
+};
+```
+
 ## Documentation
 
 - [Logger Documentation](./docs/logger.md)
 - [Utility Functions](./docs/utils.md)
 - [React Hooks](./docs/hooks.md)
 - [Storage Adapters](./docs/storage.md)
+- [File Upload Service](./docs/universalFile.md)
+- [Data Export Service](./docs/universalExport.md)
 
 ## Examples
 

package/dist/universalExport/index.d.mts

@@ -0,0 +1,517 @@
+/**
+ * 通用导出服务类型定义
+ *
+ * 定义了导出功能的核心接口和类型
+ */
+/** 导出格式类型 */
+type ExportFormat = 'csv' | 'excel' | 'json';
+/** 字段类型 */
+type FieldType = 'string' | 'number' | 'date' | 'boolean' | 'array' | 'object';
+/** 字段对齐方式 */
+type FieldAlignment = 'left' | 'center' | 'right';
+/** 导出状态 */
+type ExportStatus = 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
+/** 分组模式 */
+type GroupingMode = 'merge' | 'separate' | 'nested';
+/** 分组处理类型 */
+type GroupValueProcessing = 'first' | 'last' | 'concat' | 'sum' | 'count' | 'custom';
+/** 导出字段定义 */
+interface ExportField {
+    /** 字段键名 */
+    key: string;
+    /** 字段显示名称 */
+    label: string;
+    /** 字段类型 */
+    type: FieldType;
+    /** 是否启用 */
+    enabled: boolean;
+    /** 字段宽度 */
+    width?: number;
+    /** 对齐方式 */
+    alignment?: FieldAlignment;
+    /** 格式化函数 */
+    formatter?: (value: any) => string;
+    /** 排序权重 */
+    sortOrder?: number;
+    /** 是否必填 */
+    required?: boolean;
+    /** 字段描述 */
+    description?: string;
+    /** 自定义样式 */
+    style?: Record<string, any>;
+}
+/** 分组字段配置 */
+interface GroupingField {
+    /** 分组字段键名 */
+    key: string;
+    /** 分组字段显示名称 */
+    label: string;
+    /** 分组模式 */
+    mode: GroupingMode;
+    /** 其他字段的值处理方式 */
+    valueProcessing: GroupValueProcessing;
+    /** 自定义处理函数 */
+    customProcessor?: (values: any[]) => any;
+    /** 是否显示分组行 */
+    showGroupHeader: boolean;
+    /** 分组行模板 */
+    groupHeaderTemplate?: string;
+    /** 是否合并单元格（仅Excel格式支持） */
+    mergeCells: boolean;
+}
+/** 分组配置 */
+interface GroupingConfig {
+    /** 是否启用分组 */
+    enabled: boolean;
+    /** 分组字段列表（支持多级分组） */
+    fields: GroupingField[];
+    /** 分组后是否保持原始顺序 */
+    preserveOrder: boolean;
+    /** 空值处理方式 */
+    nullValueHandling: 'skip' | 'group' | 'separate';
+    /** 空值分组名称 */
+    nullGroupName?: string;
+}
+/** 导出配置 */
+interface ExportConfig {
+    /** 配置ID */
+    id: string;
+    /** 配置名称 */
+    name: string;
+    /** 配置描述 */
+    description?: string;
+    /** 导出格式 */
+    format: ExportFormat;
+    /** 字段定义 */
+    fields: ExportField[];
+    /** 分组配置 */
+    grouping?: GroupingConfig;
+    /** 文件名模板 */
+    fileNameTemplate: string;
+    /** 是否包含表头 */
+    includeHeader: boolean;
+    /** 分隔符 */
+    delimiter: string;
+    /** 编码格式 */
+    encoding: string;
+    /** 是否添加BOM */
+    addBOM: boolean;
+    /** 最大行数限制 */
+    maxRows?: number;
+    /** 创建时间 */
+    createdAt: Date;
+    /** 更新时间 */
+    updatedAt: Date;
+    /** 模块标识 */
+    moduleId: string;
+    /** 业务标识 */
+    businessId?: string;
+    /** 创建者ID */
+    createdBy?: string;
+}
+/** 导出请求 */
+interface ExportRequest {
+    /** 导出配置ID或配置对象 */
+    configId: string | ExportConfig;
+    /** 数据源 */
+    dataSource: string | (() => Promise<any[]>);
+    /** 查询参数 */
+    queryParams?: Record<string, any>;
+    /** 自定义字段映射 */
+    fieldMapping?: Record<string, string>;
+    /** 过滤条件 */
+    filters?: ExportFilter[];
+    /** 排序条件 */
+    sortBy?: ExportSort[];
+    /** 分页参数 */
+    pagination?: {
+        page: number;
+        pageSize: number;
+    };
+    /** 自定义文件名 */
+    customFileName?: string;
+    /** 回调函数 */
+    callbacks?: {
+        onProgress?: (progress: ExportProgress) => void;
+        onSuccess?: (result: ExportResult) => void;
+        onError?: (error: ExportError) => void;
+    };
+}
+/** 导出过滤器 */
+interface ExportFilter {
+    /** 字段名 */
+    field: string;
+    /** 操作符 */
+    operator: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'startsWith' | 'endsWith' | 'in' | 'notIn';
+    /** 值 */
+    value: any;
+}
+/** 导出排序 */
+interface ExportSort {
+    /** 字段名 */
+    field: string;
+    /** 排序方向 */
+    direction: 'asc' | 'desc';
+}
+/** 导出进度 */
+interface ExportProgress {
+    /** 导出ID */
+    exportId: string;
+    /** 状态 */
+    status: ExportStatus;
+    /** 进度百分比 */
+    progress: number;
+    /** 已处理行数 */
+    processedRows: number;
+    /** 总行数 */
+    totalRows: number;
+    /** 开始时间 */
+    startTime: Date;
+    /** 预计完成时间 */
+    estimatedEndTime?: Date;
+    /** 当前处理的数据 */
+    currentData?: any;
+    /** 错误信息 */
+    error?: string;
+}
+/** 导出结果 */
+interface ExportResult {
+    /** 导出ID */
+    exportId: string;
+    /** 文件名 */
+    fileName: string;
+    /** 文件大小 */
+    fileSize: number;
+    /** 文件URL */
+    fileUrl?: string;
+    /** 文件Blob */
+    fileBlob?: Blob;
+    /** 导出行数 */
+    exportedRows: number;
+    /** 开始时间 */
+    startTime: Date;
+    /** 完成时间 */
+    endTime: Date;
+    /** 耗时(毫秒) */
+    duration: number;
+    /** 统计信息 */
+    statistics?: {
+        totalRows: number;
+        filteredRows: number;
+        exportedRows: number;
+        skippedRows: number;
+    };
+}
+/** 导出错误 */
+interface ExportError {
+    /** 错误代码 */
+    code: string;
+    /** 错误消息 */
+    message: string;
+    /** 错误详情 */
+    details?: Record<string, any>;
+    /** 错误时间 */
+    timestamp: Date;
+}
+/** 通用导出服务配置 */
+interface UniversalExportServiceConfig {
+    /** 默认导出格式 */
+    defaultFormat: ExportFormat;
+    /** 默认分隔符 */
+    defaultDelimiter: string;
+    /** 默认编码 */
+    defaultEncoding: string;
+    /** 是否默认添加BOM */
+    defaultAddBOM: boolean;
+    /** 最大文件大小限制(字节) */
+    maxFileSize: number;
+    /** 最大行数限制 */
+    maxRowsLimit: number;
+    /** 并发导出数量限制 */
+    maxConcurrentExports: number;
+    /** 导出超时时间(毫秒) */
+    exportTimeout: number;
+    /** 缓存配置 */
+    cache: {
+        /** 配置缓存TTL(秒) */
+        configTTL: number;
+        /** 结果缓存TTL(秒) */
+        resultTTL: number;
+    };
+}
+/** 导出服务基础异常 */
+declare class ExportServiceError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, any> | undefined;
+    constructor(message: string, code: string, details?: Record<string, any> | undefined);
+}
+/** 导出配置错误 */
+declare class ExportConfigError extends ExportServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/** 导出数据处理错误 */
+declare class ExportDataError extends ExportServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/** 导出文件生成错误 */
+declare class ExportFileError extends ExportServiceError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/** 导出事件类型 */
+type ExportEventType = 'export:start' | 'export:progress' | 'export:complete' | 'export:error' | 'export:cancel' | 'config:save' | 'config:delete';
+/** 导出事件 */
+interface ExportEvent {
+    /** 事件类型 */
+    type: ExportEventType;
+    /** 导出ID */
+    exportId: string;
+    /** 事件时间 */
+    timestamp: Date;
+    /** 事件数据 */
+    data?: Record<string, any>;
+    /** 错误信息 */
+    error?: string;
+}
+/** 导出事件监听器 */
+type ExportEventListener = (event: ExportEvent) => void | Promise<void>;
+/** 字段映射函数 */
+type FieldMapper<T = any> = (item: T, index: number) => Record<string, any>;
+/** 数据转换函数 */
+type DataTransformer<T = any, R = any> = (data: T[]) => R[];
+/** 验证函数 */
+type Validator<T = any> = (data: T) => boolean | string;
+/** 格式化函数 */
+type Formatter<T = any> = (value: T) => string;
+
+/**
+ * 通用导出服务客户端SDK
+ *
+ * 提供与后端API交互的客户端接口
+ */
+
+interface UniversalExportClientConfig {
+    /** API基础URL */
+    baseUrl?: string;
+    /** 请求超时时间(毫秒) */
+    timeout?: number;
+    /** 自定义请求头 */
+    headers?: Record<string, string>;
+}
+/**
+ * 通用导出服务客户端
+ */
+declare class UniversalExportClient {
+    private config;
+    constructor(config?: UniversalExportClientConfig);
+    /**
+     * 获取模块的导出配置列表
+     */
+    getConfigsByModule(moduleId: string, businessId?: string): Promise<ExportConfig[]>;
+    /**
+     * 创建导出配置
+     */
+    createConfig(config: Omit<ExportConfig, 'id' | 'createdAt' | 'updatedAt'>): Promise<ExportConfig>;
+    /**
+     * 更新导出配置
+     */
+    updateConfig(configId: string, updates: Partial<ExportConfig>): Promise<ExportConfig>;
+    /**
+     * 删除导出配置
+     */
+    deleteConfig(configId: string): Promise<void>;
+    /**
+     * 触发数据导出
+     */
+    exportData(request: Omit<ExportRequest, 'callbacks'>): Promise<ExportResult>;
+    /**
+     * 查询导出进度
+     */
+    getExportProgress(exportId: string): Promise<ExportProgress>;
+    /**
+     * 下载导出文件
+     */
+    downloadExportFile(exportId: string): Promise<Blob>;
+    /**
+     * 获取请求头
+     */
+    private getHeaders;
+    /**
+     * 带超时的fetch请求
+     */
+    private fetchWithTimeout;
+    /**
+     * 转换API返回的配置数据
+     */
+    private transformConfigFromAPI;
+    /**
+     * 转换API返回的配置列表
+     */
+    private transformConfigsFromAPI;
+    /**
+     * 转换API返回的导出结果
+     */
+    private transformExportResultFromAPI;
+    /**
+     * 转换API返回的进度数据
+     */
+    private transformProgressFromAPI;
+}
+/**
+ * 默认客户端实例
+ */
+declare const universalExportClient: UniversalExportClient;
+/**
+ * 创建自定义客户端实例
+ */
+declare function createExportClient(config?: UniversalExportClientConfig): UniversalExportClient;
+
+/**
+ * 通用导出服务常量定义
+ */
+
+/** 模块版本 */
+declare const UNIVERSAL_EXPORT_VERSION = "1.0.0";
+/** 模块名称 */
+declare const UNIVERSAL_EXPORT_NAME = "@lyricnote/universal-export";
+/** 默认导出格式 */
+declare const DEFAULT_EXPORT_FORMAT: ExportFormat;
+/** 默认CSV分隔符 */
+declare const DEFAULT_CSV_DELIMITER = ",";
+/** 默认编码格式 */
+declare const DEFAULT_ENCODING = "utf-8";
+/** 默认是否添加BOM */
+declare const DEFAULT_ADD_BOM = true;
+/** 默认最大文件大小(字节) - 100MB */
+declare const DEFAULT_MAX_FILE_SIZE: number;
+/** 默认最大行数限制 */
+declare const DEFAULT_MAX_ROWS = 100000;
+/** 默认并发导出数量 */
+declare const DEFAULT_MAX_CONCURRENT_EXPORTS = 5;
+/** 默认导出超时时间(毫秒) - 5分钟 */
+declare const DEFAULT_EXPORT_TIMEOUT = 300000;
+/** 默认配置缓存TTL(秒) - 1小时 */
+declare const DEFAULT_CONFIG_CACHE_TTL = 3600;
+/** 默认结果缓存TTL(秒) - 30分钟 */
+declare const DEFAULT_RESULT_CACHE_TTL = 1800;
+/** 导出格式对应的文件扩展名 */
+declare const EXPORT_FORMAT_EXTENSIONS: Record<ExportFormat, string>;
+/** 导出格式对应的MIME类型 */
+declare const EXPORT_FORMAT_MIME_TYPES: Record<ExportFormat, string>;
+/** API基础路径 */
+declare const API_BASE_PATH = "/api/universal-export";
+/** API端点 */
+declare const API_ENDPOINTS: {
+    /** 获取配置列表 */
+    readonly GET_CONFIGS: "/api/universal-export/configs";
+    /** 创建配置 */
+    readonly CREATE_CONFIG: "/api/universal-export/configs";
+    /** 更新配置 */
+    readonly UPDATE_CONFIG: (configId: string) => string;
+    /** 删除配置 */
+    readonly DELETE_CONFIG: (configId: string) => string;
+    /** 触发导出 */
+    readonly EXPORT_DATA: "/api/universal-export/export";
+    /** 查询导出进度 */
+    readonly GET_PROGRESS: (exportId: string) => string;
+    /** 下载导出文件 */
+    readonly DOWNLOAD_FILE: (exportId: string) => string;
+};
+/** 错误代码 */
+declare const ERROR_CODES: {
+    /** 导出配置错误 */
+    readonly EXPORT_CONFIG_ERROR: "EXPORT_CONFIG_ERROR";
+    /** 导出数据错误 */
+    readonly EXPORT_DATA_ERROR: "EXPORT_DATA_ERROR";
+    /** 导出文件错误 */
+    readonly EXPORT_FILE_ERROR: "EXPORT_FILE_ERROR";
+    /** 网络错误 */
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    /** 超时错误 */
+    readonly TIMEOUT_ERROR: "TIMEOUT_ERROR";
+    /** 未授权 */
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    /** 服务器错误 */
+    readonly SERVER_ERROR: "SERVER_ERROR";
+};
+
+/**
+ * 通用导出服务工具函数
+ */
+
+/**
+ * 生成导出文件名
+ */
+declare function generateExportFileName(template: string, format: ExportFormat): string;
+/**
+ * 验证文件名是否合法
+ */
+declare function validateFileName(fileName: string): boolean;
+/**
+ * 清理文件名，移除非法字符
+ */
+declare function sanitizeFileName(fileName: string): string;
+/**
+ * 转义CSV字段
+ */
+declare function escapeCSVField(value: string, delimiter?: string): string;
+/**
+ * 解析CSV字段
+ */
+declare function parseCSVField(field: string): string;
+/**
+ * 内置格式化器集合
+ */
+declare const DEFAULT_FORMATTERS: Record<string, Formatter>;
+/**
+ * 应用格式化器
+ */
+declare function applyFormatter(value: any, formatter?: Formatter, type?: string): string;
+/**
+ * 验证导出配置
+ */
+declare function validateExportConfig(config: any): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * 验证导出请求
+ */
+declare function validateExportRequest(request: any): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * 格式化文件大小
+ */
+declare function formatFileSize(bytes: number): string;
+/**
+ * 格式化持续时间
+ */
+declare function formatDuration(milliseconds: number): string;
+/**
+ * 计算预计完成时间
+ */
+declare function estimateEndTime(startTime: Date, processedRows: number, totalRows: number): Date | undefined;
+/**
+ * 获取嵌套对象的值
+ */
+declare function getNestedValue(obj: any, path: string): any;
+/**
+ * 设置嵌套对象的值
+ */
+declare function setNestedValue(obj: any, path: string, value: any): void;
+/**
+ * 创建导出错误对象
+ */
+declare function createExportError(code: string, message: string, details?: Record<string, any>): {
+    code: string;
+    message: string;
+    details?: Record<string, any>;
+    timestamp: Date;
+};
+/**
+ * 格式化错误消息
+ */
+declare function formatErrorMessage(error: unknown): string;
+
+export { API_BASE_PATH, API_ENDPOINTS, DEFAULT_ADD_BOM, DEFAULT_CONFIG_CACHE_TTL, DEFAULT_CSV_DELIMITER, DEFAULT_ENCODING, DEFAULT_EXPORT_FORMAT, DEFAULT_EXPORT_TIMEOUT, DEFAULT_FORMATTERS, DEFAULT_MAX_CONCURRENT_EXPORTS, DEFAULT_MAX_FILE_SIZE, DEFAULT_MAX_ROWS, DEFAULT_RESULT_CACHE_TTL, type DataTransformer, ERROR_CODES, EXPORT_FORMAT_EXTENSIONS, EXPORT_FORMAT_MIME_TYPES, type ExportConfig, ExportConfigError, ExportDataError, type ExportError, type ExportEvent, type ExportEventListener, type ExportEventType, type ExportField, ExportFileError, type ExportFilter, type ExportFormat, type ExportProgress, type ExportRequest, type ExportResult, ExportServiceError, type ExportSort, type ExportStatus, type FieldAlignment, type FieldMapper, type FieldType, type Formatter, type GroupValueProcessing, type GroupingConfig, type GroupingField, type GroupingMode, UNIVERSAL_EXPORT_NAME, UNIVERSAL_EXPORT_VERSION, UniversalExportClient, type UniversalExportClientConfig, type UniversalExportServiceConfig, type Validator, applyFormatter, createExportClient, createExportError, escapeCSVField, estimateEndTime, formatDuration, formatErrorMessage, formatFileSize, generateExportFileName, getNestedValue, parseCSVField, sanitizeFileName, setNestedValue, universalExportClient, validateExportConfig, validateExportRequest, validateFileName };