@go-wind/admin-react 0.0.0-stage → 0.2.0

package/dist/router/types/index.d.ts

@@ -0,0 +1,207 @@
+import type { RouteObject } from "react-router-dom";
+import React, { type ComponentType } from "react";
+import type { ReactNode } from "react";
+export type IconName = string;
+export type IconType = IconName | ComponentType<{
+    className?: string;
+    style?: React.CSSProperties;
+}>;
+export type BadgeVariant = 'default' | 'primary' | 'success' | 'warning' | 'destructive' | string;
+export type BadgeType = 'dot' | 'normal';
+export type { AccessModeType } from '../../preferences/types/layout';
+/**
+ * 后端返回的路由对象（组件路径为字符串）
+ */
+export interface BackendRoute extends Omit<AppRouteObject, 'element' | 'children'> {
+    component?: string;
+    children?: BackendRoute[];
+}
+/**
+ * generateRoutesByBackend 的选项。只声明后端生成器实际消费的字段——
+ * 此前这里的 staticRoutes/mode 等字段从未被消费，形成"传了也没用"的误导性签名。
+ */
+export interface GenerateRoutesOptions {
+    /** 从后端拉取菜单路由树（component 为字符串路径） */
+    fetchMenuListAsync?: () => Promise<BackendRoute[]>;
+    /** 布局组件映射（component 字符串 → React 组件） */
+    layoutMap?: ComponentRecord;
+    /** 页面组件映射（view 路径 → React 组件） */
+    pageMap?: ComponentRecord;
+}
+export interface GenerateRoutesResult {
+    routes: AppRouteObject[];
+    menus: AppMenu[];
+}
+export interface RouteMeta {
+    title?: string;
+    icon?: IconType;
+    activeIcon?: IconType;
+    authority?: string[];
+    ignoreAccess?: boolean;
+    hideInMenu?: boolean;
+    hideInTab?: boolean;
+    hideInBreadcrumb?: boolean;
+    hideChildrenInMenu?: boolean;
+    menuVisibleWithForbidden?: boolean;
+    activePath?: string;
+    affixTab?: boolean;
+    affixTabOrder?: number;
+    keepAlive?: boolean;
+    loaded?: boolean;
+    link?: string;
+    iframeSrc?: string;
+    openInNewWindow?: boolean;
+    order?: number;
+    query?: Record<string, any>;
+    maxNumOfOpenTab?: number;
+    badge?: string;
+    badgeType?: 'dot' | 'normal';
+    badgeVariants?: BadgeVariant;
+    [key: string]: any;
+}
+export interface AppRoute extends Omit<RouteObject, 'meta' | 'children' | 'element'> {
+    name: string;
+    path: string;
+    redirect?: string;
+    index?: boolean;
+    meta?: RouteMeta;
+    children?: AppRoute[];
+    element?: ReactNode;
+    componentPath?: string;
+    parent?: string;
+    parents?: string[];
+}
+/**
+ * AppRouteObject = RouteObject + meta + 业务字段
+ * 用于替代原生的 RouteObject，携带业务元数据
+ */
+export interface AppRouteObject extends Omit<RouteObject, 'children'> {
+    name?: string;
+    path?: string;
+    meta?: RouteMeta;
+    redirect?: string;
+    icon?: IconType;
+    activeIcon?: IconType;
+    disabled?: boolean;
+    show?: boolean;
+    order?: number;
+    children?: AppRouteObject[];
+    parent?: string;
+    parents?: string[];
+    componentPath?: string;
+    element?: ReactNode;
+}
+export interface AppMenuBadge {
+    badge?: string;
+    badgeType?: BadgeType;
+    badgeVariants?: BadgeVariant;
+}
+export interface AppMenu extends AppMenuBadge {
+    name: string;
+    path: string;
+    label: string;
+    icon?: IconType;
+    activeIcon?: IconType;
+    order?: number;
+    badge?: string;
+    badgeType?: 'dot' | 'normal';
+    badgeVariants?: BadgeVariant;
+    disabled?: boolean;
+    show?: boolean;
+    parent?: string;
+    parents?: string[];
+    children?: AppMenu[];
+    authority?: string[];
+    menuVisibleWithForbidden?: boolean;
+    meta?: RouteMeta;
+    [key: string]: any;
+}
+export type ComponentRecordType = Record<string, ComponentType<any>>;
+export type ComponentRecord = Record<string, ComponentType<any>>;
+export interface GenerateMenuAndRoutesOptions {
+    fetchMenuListAsync?: () => Promise<BackendRoute[]>;
+    forbiddenElement?: React.ReactNode;
+    layoutMap?: ComponentRecordType;
+    pageMap?: ComponentRecordType;
+    permissions?: string[];
+    roles?: string[];
+    routes: AppRouteObject[];
+    autoInjectRedirect?: boolean;
+    autoSort?: boolean;
+    /** 登录落地兜底路径（宿主注入，如 ROUTES.DEFAULT_HOME）；后端模式下无可见菜单时使用 */
+    defaultHomePath?: string;
+}
+/**
+ * 路由模块的默认导出类型
+ * 每个动态导入的路由文件应默认导出 AppRouteObject[]
+ */
+export interface RouteModuleType {
+    default: AppRouteObject[];
+}
+/**
+ * Vite glob 导入的动态模块类型
+ * 兼容 .tsx/.ts 文件 + 默认导出
+ */
+export type RouteModuleRecord = Record<string, RouteModuleType | AppRouteObject[] | (() => Promise<RouteModuleType>)>;
+export declare const isAppRoute: (route: any) => route is AppRouteObject;
+export interface MenuRecordBadgeRaw {
+    /**
+     * 徽标
+     */
+    badge?: string;
+    /**
+     * 徽标类型
+     */
+    badgeType?: "dot" | "normal";
+    /**
+     * 徽标颜色
+     */
+    badgeVariants?: "destructive" | "primary" | string;
+}
+/**
+ * 菜单原始对象
+ */
+export interface MenuRecordRaw extends MenuRecordBadgeRaw {
+    /**
+     * 激活时的图标名
+     */
+    activeIcon?: string;
+    /**
+     * 子菜单
+     */
+    children?: MenuRecordRaw[];
+    /**
+     * 是否禁用菜单
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 图标名
+     */
+    icon?: IconType;
+    /**
+     * 菜单名
+     */
+    name: string;
+    /**
+     * 排序号
+     */
+    order?: number;
+    /**
+     * 父级路径
+     */
+    parent?: string;
+    /**
+     * 所有父级路径
+     */
+    parents?: string[];
+    /**
+     * 菜单路径，唯一，可当作key
+     */
+    path: string;
+    /**
+     * 是否显示菜单
+     * @default true
+     */
+    show?: boolean;
+}

package/dist/router/utils/index.d.ts

@@ -0,0 +1,8 @@
+export * from './inject-redirect';
+export * from './lazy';
+export * from './loader';
+export * from './menu';
+export * from './merge-route-modules';
+export * from './reset-routes';
+export * from './sort-routes';
+export * from './transform-meta-to-handle';

package/dist/router/utils/inject-redirect.d.ts

@@ -0,0 +1,6 @@
+import type { AppRoute } from "../../router/types";
+/**
+ * 自动注入重定向
+ * 规则：父路由有子路由且未配置 redirect 时，指向第一个子路由
+ */
+export declare const injectRedirects: (routes: AppRoute[]) => AppRoute[];

package/dist/router/utils/lazy.d.ts

@@ -0,0 +1,11 @@
+import { type ComponentType } from 'react';
+/**
+ * 创建懒加载路由元素
+ * 自动包裹 Suspense + Spin fallback
+ *
+ * @param loader Vite 动态导入函数，如 () => import('@/pages/dashboard')
+ * @returns 可直接赋值给 route.element 的 ReactNode
+ */
+export declare const createLazyRoute: (loader: () => Promise<{
+    default: ComponentType<any>;
+}>) => import("react").JSX.Element;

package/dist/router/utils/loader.d.ts

@@ -0,0 +1,14 @@
+import type { AppRouteObject } from '../types';
+/**
+ * 展平模块导出（兼容 default / 具名导出）
+ * 纯函数，无副作用，可单元测试
+ */
+export declare const extractRoutes: (module: any) => AppRouteObject[];
+/**
+ * 过滤无效路由（开发环境调试用）
+ */
+export declare const filterValidRoutes: (routes: AppRouteObject[]) => AppRouteObject[];
+/**
+ * 根据权限过滤路由树
+ */
+export declare const filterRoutesByPermission: (routes: AppRouteObject[], permissions: string[]) => AppRouteObject[];

package/dist/router/utils/menu.d.ts

@@ -0,0 +1,5 @@
+import type { ProLayoutProps } from '@ant-design/pro-components';
+import type { AppRouteObject } from '../../router/types';
+type MenuRoute = AppRouteObject;
+export declare const transformRoutesToMenu: (routes: MenuRoute[], permissions: string[], parentPath?: string) => NonNullable<ProLayoutProps["route"]>["routes"];
+export {};

package/dist/router/utils/merge-route-modules.d.ts

@@ -0,0 +1,23 @@
+import type { AppRouteObject, RouteModuleRecord, RouteModuleType } from "../../router";
+/**
+ * 合并动态路由模块的默认导出
+ *
+ * @param routeModules - Vite import.meta.glob 返回的模块对象
+ * @param options - 可选配置
+ * @returns 合并后的路由配置数组（AppRouteObject[]）
+ *
+ * @example
+ *
+ */
+export declare function mergeRouteModules(routeModules: RouteModuleRecord, options?: {
+    /** 是否过滤空模块 */
+    filterEmpty?: boolean;
+    /** 是否按路径排序 */
+    sortByPath?: boolean;
+}): AppRouteObject[];
+/**
+ * 异步合并动态路由模块（用于 lazy 加载）
+ * @param routeModules - Vite import.meta.glob 返回的异步模块对象
+ * @returns Promise<AppRouteObject[]>
+ */
+export declare function mergeRouteModulesAsync(routeModules: Record<string, () => Promise<RouteModuleType | AppRouteObject[]>>): Promise<AppRouteObject[]>;

package/dist/router/utils/reset-routes.d.ts

@@ -0,0 +1,18 @@
+import type { AppRouteObject } from "../../router/types";
+/**
+ * 重置可访问路由（保留白名单）
+ *
+ * ⚠️ React Router v6+ 不支持运行时修改路由，
+ * 此函数返回过滤后的路由树，需配合 createBrowserRouter 重新创建 router
+ *
+ * @param allRoutes - 当前完整路由树（含动态路由）
+ * @param staticRouteNames - 静态路由白名单（保留这些路由）
+ * @returns 过滤后的路由树（仅含白名单路由）
+ */
+export declare function resetAccessibleRoutes(allRoutes: AppRouteObject[], staticRouteNames: string[]): AppRouteObject[];
+/**
+ * 提取路由树中所有有效的 name（用于生成白名单）
+ * @param routes - 路由树
+ * @returns 有效的路由 name 数组
+ */
+export declare function extractRouteNames(routes: AppRouteObject[]): string[];

package/dist/router/utils/sort-routes.d.ts

@@ -0,0 +1,5 @@
+import type { AppRoute } from "../../router/types";
+/**
+ * 递归排序路由树（按 meta.order 升序）
+ */
+export declare const sortRoutes: (routes: AppRoute[]) => AppRoute[];

package/dist/router/utils/transform-meta-to-handle.d.ts

@@ -0,0 +1,11 @@
+import type { AppRouteObject, RouteMeta } from '../types';
+import type { RouteHandle } from '../../types';
+/**
+ * 将 meta 转换为 React Router 的 handle
+ * 这样 useMatches() 就能获取到路由元数据
+ */
+export declare function transformMetaToHandle(meta?: RouteMeta): RouteHandle | undefined;
+/**
+ * 递归转换路由配置，将 meta 映射到 handle
+ */
+export declare function transformRoutesWithHandle(routes: AppRouteObject[]): AppRouteObject[];

package/dist/storage/index.d.ts

@@ -0,0 +1,2 @@
+export { StorageManager } from "./storage.class";
+export * from "./storage.types";

package/dist/storage/storage.class.d.ts

@@ -0,0 +1,125 @@
+import type { BatchGetOptions, BatchProgressCallback, BatchResult, BatchSetItem, IStorageCache, StorageManagerOptions, StorageMetrics, SyncMessage } from "./storage.types";
+declare class StorageManager implements IStorageCache {
+    private readonly prefix;
+    private readonly storage;
+    private readonly options;
+    private readonly defaultTTL?;
+    private readonly tabId;
+    private channel;
+    private metrics;
+    private metricsDebounceTimer;
+    private readonly onMetricsCallback?;
+    private onSyncCallback?;
+    constructor(options?: StorageManagerOptions);
+    /**
+     * 获取完整存储键（安全添加前缀）
+     */
+    private getFullKey;
+    private getMetaKey;
+    private readMeta;
+    private writeMeta;
+    /**
+     * 访问时更新元数据（访问次数和最后访问时间）
+     */
+    private updateMetaOnAccess;
+    /**
+     * 设置时更新元数据
+     */
+    private updateMetaOnSet;
+    /**
+     * 移除元数据
+     */
+    private removeMeta;
+    private getAllMeta;
+    /**
+     * 安全解析存储值
+     */
+    private parseValue;
+    /**
+     * 序列化存储值
+     */
+    private serializeValue;
+    /**
+     * 获取存储项
+     */
+    getItem<T>(key: string, defaultValue?: T | null): T | null;
+    /**
+     * 设置存储项
+     */
+    setItem<T>(key: string, value: T, ttl?: number | null): void;
+    /**
+     * 移除存储项
+     */
+    removeItem(key: string): void;
+    /**
+     * 检查键是否存在且未过期
+     */
+    hasItem(key: string): boolean;
+    /**
+     * 清除所有带前缀的项（使用倒序遍历避免索引错位）
+     */
+    clear(): void;
+    /**
+     * 清除所有过期项
+     */
+    clearExpiredItems(): void;
+    /**
+     * 获取存储键（带前缀过滤）
+     */
+    key(index: number): string | null;
+    /**
+     * 获取有效存储项数量（带前缀过滤）
+     */
+    length(): number;
+    /**
+     * 获取底层 Storage 实例（用于高级操作）
+     */
+    getRawStorage(): Storage | null;
+    /**
+     * 批量获取存储项
+     * @param keys 要获取的键数组
+     * @param options 获取选项
+     * @param onProgress 进度回调（每处理完一个项触发）
+     * @returns Promise<Record<string, T | null>> 键值映射
+     */
+    getItems<T>(keys: string[], options?: BatchGetOptions, onProgress?: BatchProgressCallback): Promise<Record<string, T | null>>;
+    /**
+     * 批量设置存储项
+     * @param items 键值对映射，值可以是普通值或 BatchSetItem 配置
+     * @param onProgress 进度回调
+     * @returns Promise<BatchResult<T>> 操作结果统计
+     */
+    setItems<T>(items: Record<string, T | BatchSetItem<T>>, onProgress?: BatchProgressCallback): Promise<BatchResult<T>>;
+    /**
+     * 批量移除存储项
+     * @param keys 要移除的键数组
+     * @returns Promise<{ removed: string[]; failed: Record<string, Error> }>
+     */
+    removeItems(keys: string[]): Promise<{
+        removed: string[];
+        failed: Record<string, Error>;
+    }>;
+    /**
+     * 批量检查键是否存在（且未过期）
+     * @param keys 要检查的键数组
+     * @returns Promise<Record<string, boolean>>
+     */
+    hasItems(keys: string[]): Promise<Record<string, boolean>>;
+    /**
+     * 内部方法：标准化批量设置的值配置
+     */
+    private _normalizeBatchValue;
+    private checkAndEvict;
+    private sortByEvictionPriority;
+    private initSync;
+    private handleSyncMessage;
+    private broadcast;
+    onSync(callback: (event: SyncMessage) => void): () => void;
+    private trackMetric;
+    private updateHitRate;
+    private debounceReportMetrics;
+    private updateQuotaUsage;
+    getMetrics(): StorageMetrics;
+    resetMetrics(): void;
+}
+export { StorageManager };

package/dist/storage/storage.types.d.ts

@@ -0,0 +1,199 @@
+/**
+ * 存储类型
+ */
+export type StorageType = "localStorage" | "sessionStorage";
+/**
+ * 缓存驱逐策略
+ * - lru: 最近最少使用 (Least Recently Used)
+ * - lfu: 最不经常使用 (Least Frequently Used)
+ * - hybrid: 混合策略（结合 LRU 和 LFU）
+ */
+export type EvictionStrategy = "lru" | "lfu" | "hybrid";
+/**
+ * 存储元数据
+ * @description 用于跟踪每个存储项的状态信息，支持智能缓存管理
+ */
+export interface StorageMeta {
+    /** 过期时间戳 (null=永久有效) */
+    e: number | null;
+    /** 原始数据大小 (bytes) */
+    s: number;
+    /** 访问次数 (用于 LFU 策略) */
+    a: number;
+    /** 最后访问时间戳 (用于 LRU 策略) */
+    t: number;
+    /** 是否已压缩 */
+    c: boolean;
+}
+/**
+ * 存储性能指标
+ * @description 用于监控存储使用情况和分析性能瓶颈
+ */
+export interface StorageMetrics {
+    /** 命中次数 */
+    hits: number;
+    /** 未命中次数 */
+    misses: number;
+    /** 过期清理次数 */
+    expirations: number;
+    /** 设置操作次数 */
+    sets: number;
+    /** 错误次数 */
+    errors: number;
+    /** 配额使用量 (bytes) */
+    quotaUsageBytes: number;
+    /** 命中率 (0-1) */
+    hitRate: number;
+}
+/**
+ * 多标签页同步消息
+ * @description 用于在不同标签页之间同步存储状态
+ */
+export interface SyncMessage {
+    /** 操作类型 */
+    type: "set" | "remove" | "clear";
+    /** 存储键名 */
+    key: string;
+    /** 标签页 ID */
+    tabId: string;
+    /** 时间戳 */
+    ts: number;
+}
+/**
+ * 存储管理器配置选项
+ * @description 用于初始化 StorageManager 实例时的配置参数
+ */
+export interface StorageManagerOptions {
+    /** 存储键名前缀，用于隔离不同模块的数据 */
+    prefix?: string;
+    /** 存储类型：localStorage 或 sessionStorage */
+    storageType?: StorageType;
+    /** 触发压缩的阈值 (bytes)，默认 1024 */
+    compressionThreshold?: number;
+    /** 缓存驱逐策略，默认 "hybrid" */
+    evictionStrategy?: EvictionStrategy;
+    /** 最大存储项数 (0=不限)，默认 0 */
+    maxItems?: number;
+    /** 最大使用量 (MB)，默认 10 */
+    maxUsageMB?: number;
+    /** 默认过期时间 (ms)，null 表示永不过期 */
+    defaultTTL?: number | null;
+    /** 是否开启多标签页同步，默认 true */
+    enableSync?: boolean;
+    /** 指标变化回调函数 */
+    onMetrics?: (metrics: StorageMetrics) => void;
+    /** 同步事件回调函数 */
+    onSync?: (event: SyncMessage) => void;
+}
+/**
+ * 存储项结构（旧版，保留用于兼容）
+ * @deprecated 请使用 StorageValue 替代
+ */
+export interface StorageItem<T> {
+    /** 过期时间戳 */
+    expiry?: number;
+    /** 存储的值 */
+    value: T;
+}
+/**
+ * 存储值结构
+ * @description 封装数据和过期信息的标准格式
+ */
+export interface StorageValue<T> {
+    /** 存储的实际数据 */
+    data: T;
+    /** 过期时间戳 (null=永不过期) */
+    expiry: number | null;
+}
+/**
+ * 批量设置项的配置
+ * @description 用于在批量设置时为每个项指定独立的 TTL
+ */
+export interface BatchSetItem<T> {
+    /** 要存储的值 */
+    value: T;
+    /** 过期时间 (ms)，覆盖默认 TTL */
+    ttl?: number | null;
+}
+/**
+ * 批量获取的选项
+ * @description 控制批量获取操作的行为
+ */
+export interface BatchGetOptions {
+    /** 是否跳过过期项（默认 true，自动清理过期数据） */
+    skipExpired?: boolean;
+    /** 是否返回原始解析结果（用于调试，默认 false） */
+    includeRaw?: boolean;
+}
+/**
+ * 批量操作结果
+ * @description 包含批量操作的执行结果统计
+ */
+export interface BatchResult<T> {
+    /** 成功设置的项 */
+    success: Record<string, T>;
+    /** 失败的项及对应的错误信息 */
+    failed: Record<string, Error>;
+    /** 因过期被清理的键列表 */
+    expired: string[];
+}
+/**
+ * 批量操作进度回调
+ * @description 用于实时监控批量操作的执行进度
+ */
+export type BatchProgressCallback = (progress: {
+    /** 当前已处理的项目数 */
+    current: number;
+    /** 总项目数 */
+    total: number;
+    /** 当前处理的键名 */
+    key: string;
+    /** 处理状态 */
+    status: "success" | "failed" | "expired";
+}) => void;
+/**
+ * 存储缓存接口
+ * @description 定义存储管理器的基本操作契约
+ */
+export interface IStorageCache {
+    /** 清除所有存储项 */
+    clear(): void;
+    /** 清除所有过期项 */
+    clearExpiredItems(): void;
+    /**
+     * 获取指定索引的键名
+     * @param index - 索引位置
+     * @returns 键名或 null
+     */
+    key(index: number): string | null;
+    /**
+     * 获取存储项数量
+     * @returns 存储项总数
+     */
+    length(): number;
+    /**
+     * 移除指定键的存储项
+     * @param key - 存储键名
+     */
+    removeItem(key: string): void;
+    /**
+     * 设置存储项
+     * @param key - 存储键名
+     * @param value - 要存储的值
+     * @param ttl - 过期时间 (ms)，可选
+     */
+    setItem<T>(key: string, value: T, ttl?: number | null): void;
+    /**
+     * 获取存储项
+     * @param key - 存储键名
+     * @param defaultValue - 默认值，当键不存在时返回
+     * @returns 存储的值或默认值
+     */
+    getItem<T>(key: string, defaultValue?: T | null): T | null;
+    /**
+     * 检查键是否存在且未过期
+     * @param key - 存储键名
+     * @returns 是否存在
+     */
+    hasItem(key: string): boolean;
+}