@skyroc/scripts 2.5.0

package/templates/admin-shell/types/api/route.d.ts

@@ -0,0 +1,104 @@
+// oxlint-disable unicorn/require-module-specifiers
+/**
+ * 命名空间 Api.Route
+ *
+ * 后端 API 模块：路由模块
+ */
+declare global {
+  namespace Api.Route {
+    /** 后端返回的完整动态路由结构。 */
+    interface BackendRouteResponse {
+      /** 用户首页路由，后端原始响应是字符串，进入布局前再适配成 Router.RoutePath。 */
+      home?: string | null;
+      /** 用户可访问的后端路由树。 */
+      routes: BackendRoutePayload[];
+    }
+
+    /** 后端动态路由节点的原始响应。 */
+    interface BackendRoutePayload {
+      /** 子路由树。 */
+      children?: BackendRoutePayload[] | null;
+      /** Vue/React 后端菜单常见的 meta/handle 承载字段。 */
+      handle?: BackendRouteHandle | null;
+      /** 后端菜单 ID。没有时使用 name 或 path 作为运行时 id。 */
+      id?: number | string | null;
+      /** 顶层菜单分类 key。 */
+      layout?: Router.MenuCategoryKey | null;
+      /** 兼容常见后端菜单模型中的 meta 字段。 */
+      meta?: BackendRouteHandle | null;
+      /** 后端路由名。 */
+      name?: string | null;
+      /** 父级菜单 ID。 */
+      parentId?: number | string | null;
+      /** 后端路由路径。 */
+      path: string;
+      /** 后端重定向字段，布局菜单不会直接消费。 */
+      redirect?: string | null;
+    }
+
+    /** 后端动态路由默认携带的 URL search 参数。 */
+    interface BackendRouteQuery {
+      /** 参数 Key。 */
+      key: string;
+      /** 参数 Value。 */
+      value: string;
+    }
+
+    /** 后端动态路由节点的 meta/handle 字段。 */
+    interface BackendRouteHandle {
+      /** 隐藏页需要激活的菜单路径。 */
+      activeMenu?: string | null;
+      /** 标准菜单 badge。 */
+      badge?: Router.MenuBadge | null;
+      /** 是否常量路由。 */
+      constant?: boolean | null;
+      /** 自定义菜单 extra key。 */
+      extra?: Router.Extra | null;
+      /** 固定页签序号。 */
+      fixedIndexInTab?: number | null;
+      /** 是否在菜单中隐藏。 */
+      hideInMenu?: boolean | null;
+      /** 外链地址。 */
+      href?: string | null;
+      /** 国际化 key。 */
+      i18nKey?: I18n.I18nKey | null;
+      /** Iconify 图标名。 */
+      icon?: string | null;
+      /** 是否缓存页面。 */
+      keepAlive?: boolean | null;
+      /** 本地图标名。 */
+      localIcon?: string | null;
+      /** 是否允许同一路由多页签。 */
+      multiTab?: boolean | null;
+      /** 菜单排序。 */
+      order?: number | null;
+      /** 点击菜单进入页面时默认携带的 search 参数。 */
+      query?: BackendRouteQuery[] | null;
+      /** 允许访问该路由的角色。 */
+      roles?: string[] | null;
+      /** 菜单标题。 */
+      title?: string | null;
+      /** 菜单类型。 */
+      type?: Router.MenuType | null;
+      /** Iframe 或外部页面地址。 */
+      url?: string | null;
+    }
+
+    /** 布局运行时消费的动态路由节点。 */
+    interface BackendRoute extends Router.Meta {
+      children?: BackendRoute[] | null;
+
+      id: string;
+
+      layout?: Router.MenuCategoryKey | null;
+
+      parentId?: string | null;
+
+      path: Router.RoutePath;
+
+      query?: BackendRouteQuery[] | null;
+    }
+  }
+}
+
+export {};

package/templates/admin-shell/types/api/service.d.ts

@@ -0,0 +1,51 @@
+/** The API service namespace */
+declare global {
+  namespace Api.Service {
+    /** Other baseURL key */
+    type OtherBaseURLKey = 'demo';
+
+    interface ServiceConfigItem {
+      /** The backend service base url */
+      baseURL: string;
+      /** The proxy pattern of the backend service base url */
+      proxyPattern: string;
+    }
+
+    interface OtherServiceConfigItem extends ServiceConfigItem {
+      key: OtherBaseURLKey;
+    }
+
+    /** The backend service config */
+    interface ServiceConfig extends ServiceConfigItem {
+      /** Other backend service config */
+      other: OtherServiceConfigItem[];
+    }
+
+    interface SimpleServiceConfig extends Pick<ServiceConfigItem, 'baseURL'> {
+      other: Record<OtherBaseURLKey, string>;
+    }
+
+    /** The backend service response data */
+    type Response<T = unknown> = {
+      /** The backend service response code */
+      code: string;
+      /** The backend service response data */
+      data: T;
+      /** The backend service response message */
+      msg: string;
+    };
+
+    /** The demo backend service response data */
+    type DemoResponse<T = unknown> = {
+      /** The backend service response message */
+      message: string;
+      /** The backend service response data */
+      result: T;
+      /** The backend service response code */
+      status: string;
+    };
+  }
+}
+
+// oxlint-disable-next-line unicorn/require-module-specifiers
+export {};

package/templates/admin-shell/types/api/system-manage.d.ts

@@ -0,0 +1,160 @@
+// oxlint-disable unicorn/require-module-specifiers
+/**
+ * 命名空间 Api.SystemManage
+ *
+ * 后端 API 模块：系统管理模块
+ */
+declare global {
+  namespace Api.SystemManage {
+    /** 将查询表单字段转成可选且允许为空的接口查询参数。 */
+    type NullableSearchRecord<T> = {
+      [K in keyof T]?: T[K] | null;
+    };
+
+    /** 通用搜索参数 */
+    type CommonSearchParams = Pick<Api.Common.PaginatingCommonParams, 'current' | 'size'>;
+
+    /** 角色 */
+    type Role = Api.Common.CommonRecord<{
+      /** 角色编码 */
+      roleCode: string;
+      /** 角色描述 */
+      roleDesc: string;
+      /** 角色名称 */
+      roleName: string;
+    }>;
+
+    /** 角色搜索参数 */
+    type RoleSearchParams = NullableSearchRecord<Pick<Role, 'roleCode' | 'roleName' | 'status'> & CommonSearchParams>;
+
+    /** 角色列表 */
+    type RoleList = Api.Common.PaginatingQueryRecord<Role>;
+
+    /** 所有角色（简化版） */
+    type AllRole = Pick<Role, 'id' | 'roleCode' | 'roleName'>;
+
+    /**
+     * 用户性别
+     *
+     * - "1": 男
+     * - "2": 女
+     */
+    type UserGender = '1' | '2';
+
+    /** 用户 */
+    type User = Api.Common.CommonRecord<{
+      /** 用户昵称 */
+      nickName: string;
+      /** 用户邮箱 */
+      userEmail: string;
+      /** 用户性别 */
+      userGender: UserGender | null;
+      /** 用户名 */
+      userName: string;
+      /** 用户手机号 */
+      userPhone: string;
+      /** 用户角色编码集合 */
+      userRoles: string[];
+    }>;
+
+    /** 用户搜索参数 */
+    type UserSearchParams = NullableSearchRecord<
+      Pick<User, 'nickName' | 'status' | 'userEmail' | 'userGender' | 'userName' | 'userPhone'> & CommonSearchParams
+    >;
+
+    /** 用户列表 */
+    type UserList = Api.Common.PaginatingQueryRecord<User>;
+
+    /**
+     * 菜单类型
+     *
+     * - "1": 目录
+     * - "2": 菜单
+     */
+    type MenuType = '1' | '2';
+
+    /** 菜单按钮 */
+    type MenuButton = {
+      /**
+       * 按钮编码
+       *
+       * 可用于控制按钮权限
+       */
+      code: string;
+      /** 按钮描述 */
+      desc: string;
+    };
+
+    /** 菜单路由参数 */
+    type MenuRouteQuery = {
+      /** 参数 Key */
+      key: string;
+      /** 参数 Value */
+      value: string;
+    };
+
+    /** 菜单的路由属性 */
+    interface MenuPropsOfRoute {
+      /** 高亮的菜单路径 */
+      activeMenu?: Router.RoutePath | null;
+      /** 是否为常量路由 */
+      constant?: boolean | null;
+      /** 固定在页签中的序号 */
+      fixedIndexInTab?: number | null;
+      /** 是否隐藏菜单 */
+      hideInMenu?: boolean | null;
+      /** 外链地址 */
+      href?: string | null;
+      /** 国际化键 */
+      i18nKey?: I18n.I18nKey | null;
+      /** 是否缓存路由 */
+      keepAlive?: boolean | null;
+      /** 是否支持多页签 */
+      multiTab?: boolean | null;
+      /** 菜单排序 */
+      order?: number | null;
+      /** 路由参数 */
+      query?: MenuRouteQuery[] | null;
+    }
+
+    /** 菜单 */
+    type Menu = Api.Common.CommonRecord<{
+      /** 按钮列表 */
+      buttons?: MenuButton[] | null;
+      /** 子菜单 */
+      children?: Menu[] | null;
+      /** 组件路径 */
+      component?: string;
+      /** 图标名称（iconify 图标名或本地图标名） */
+      icon: string;
+      /** 菜单名称 */
+      menuName: string;
+      /** 菜单类型 */
+      menuType: MenuType;
+      /** 父级菜单 ID */
+      parentId: number;
+      /** 路由名称 */
+      routeName: string;
+      /** 路由路径 */
+      routePath: string;
+    }> &
+      MenuPropsOfRoute;
+
+    /** 菜单列表 */
+    type MenuList = Api.Common.PaginatingQueryRecord<Menu>;
+
+    /** 菜单树 */
+    type MenuTree = {
+      /** 子菜单树 */
+      children?: MenuTree[];
+      /** 菜单 ID */
+      id: number;
+      /** 菜单标签 */
+      label: string;
+      /** 父级菜单 ID */
+      pId: number;
+    };
+  }
+}
+
+export {};

package/templates/admin-shell/types/app/common.d.ts

@@ -0,0 +1,31 @@
+/** The common type namespace */
+declare global {
+  namespace Common {
+    /** The strategic pattern */
+    interface StrategicPattern {
+      /** If the condition is true, then call the action function */
+      callback: () => void;
+      /** The condition */
+      condition: boolean;
+    }
+
+    /**
+     * The option type
+     *
+     * @property value: The option value
+     * @property label: The option label
+     */
+    type Option<K = string, M = string> = { label: M; value: K };
+
+    type YesOrNo = 'N' | 'Y';
+
+    type EnableStatus = '1' | '2';
+
+    /** Add null to all properties */
+    type RecordNullable<T> = {
+      [K in keyof T]?: T[K] | null;
+    };
+  }
+}
+
+export {};

package/templates/admin-shell/types/app/global.d.ts

@@ -0,0 +1,71 @@
+// oxlint-disable unicorn/require-module-specifiers
+/** The global namespace */
+declare global {
+  namespace App.Global {
+    /**
+     * - The global dropdown key
+     * - CloseAll: close all tabs
+     * - CloseCurrent: close current tab
+     * - CloseLeft: close left tabs
+     * - CloseOther: close other tabs
+     * - CloseRight: close right tabs
+     * - Pin: pin tab
+     * - Unpin: unpin tab
+     */
+    type DropdownKey = 'closeAll' | 'closeCurrent' | 'closeLeft' | 'closeOther' | 'closeRight' | 'pin' | 'unpin';
+
+    type AntdMenu = NonNullable<import('antd').MenuProps['items']>[number];
+
+    /** The global tab */
+    type Tab = {
+      /** The tab fixed index */
+      fixedIndex?: number | null;
+      /** The tab route full path */
+      fullPath: string;
+      /** I18n key */
+      i18nKey?: I18n.I18nKey | null;
+      /**
+       * Tab icon
+       *
+       * Iconify icon
+       */
+      icon?: string | null;
+      /** The tab id */
+      id: string;
+      /** Whether the tab route should keep its page instance alive */
+      keepAlive?: boolean | null;
+      /** The tab label */
+      label: string;
+      /**
+       * Tab local icon
+       *
+       * Local icon
+       */
+      localIcon?: string | null;
+
+      /**
+       * The old tab label
+       *
+       * When reset the tab label, the tab label will be replaced by this value
+       */
+      oldLabel?: string | null;
+      /** The tab route path */
+      routePath: Router.RoutePath;
+    };
+
+    /** The global admin layout menu */
+
+    namespace AdminLayout {
+      interface HeaderProps {
+        /** Whether to show the logo */
+        showLogo?: boolean;
+        /** Whether to show the menu */
+        showMenu?: boolean;
+        /** Whether to show the menu toggler */
+        showMenuToggler?: boolean;
+      }
+    }
+  }
+}
+
+export {};

package/templates/admin-shell/types/app/menu.d.ts

@@ -0,0 +1,57 @@
+// oxlint-disable unicorn/require-module-specifiers
+/** The menu namespace */
+declare global {
+  namespace Menu {
+    interface CommonMenu {
+      /** The menu children */
+      children?: CommonMenu[];
+      /** The menu extra */
+      extra?: React.ReactNode;
+      /** The menu i18n key */
+      i18nKey?: I18n.I18nKey | null;
+      /** The menu icon */
+      icon?: React.ReactElement;
+      /**
+       * The menu key
+       *
+       * Equal to the route key
+       */
+      key: string;
+      /** The menu label */
+      label: React.ReactNode;
+      /**
+       * Menu order for sorting (using hyphen to avoid React DOM warning)
+       *
+       * @default 0
+       */
+      order?: number | null;
+      /** The tooltip title */
+      title?: string | null;
+      /**
+       * Menu type
+       *
+       * @default 'item'
+       */
+      type?: string;
+    }
+
+    interface QuickReferenceMenu extends Api.Route.BackendRoute {
+      /** 菜单深度层级，从 0 开始 */
+      depth?: number;
+
+      /** 菜单的 key */
+      key: string;
+
+      /** 父级菜单的 key 列表 */
+      parentKeys?: string[];
+    }
+
+    type QuickReferenceMenuMap = Map<Router.RoutePath, QuickReferenceMenu>;
+
+    type QuickReferenceMenus = Map<string, QuickReferenceMenuMap>;
+
+    type Menus = Map<Router.MenuCategoryKey, CommonMenu[]>;
+  }
+}
+
+export {};

package/templates/admin-shell/types/app/router.d.ts

@@ -0,0 +1,201 @@
+// oxlint-disable unicorn/require-module-specifiers
+/** The router namespace */
+declare global {
+  namespace Router {
+    type QueryClient = import('@tanstack/react-query').QueryClient;
+
+    interface RouteIdRegistry {}
+
+    type RouteId = keyof RouteIdRegistry extends never ? string : Extract<keyof RouteIdRegistry, string>;
+
+    interface RoutePathRegistry {}
+
+    type RoutePath = keyof RoutePathRegistry extends never ? string : Extract<keyof RoutePathRegistry, string>;
+
+    type Extra = keyof MenuExtraRegistry extends never ? string : Extract<keyof MenuExtraRegistry, string>;
+
+    interface MenuExtraRegistry {}
+
+    type MenuCategoryKey = keyof MenuCategoryRegistry extends never
+      ? string
+      : Extract<keyof MenuCategoryRegistry, string>;
+
+    interface MenuCategoryRegistry {}
+
+    type MenuBadgeType = 'dot' | 'normal';
+
+    type MenuBadgeValue = number | string | null;
+
+    type MenuBadgeVariant = 'default' | 'error' | 'info' | 'primary' | 'success' | 'warning';
+
+    type MenuType = 'divider' | 'group' | 'item';
+
+    interface MenuBadge {
+      /** Whether zero should still be rendered as badge content. */
+      showZero?: boolean;
+      /** Whether to render a dot badge or content badge. */
+      type?: MenuBadgeType;
+      /** Static badge content used when no dynamic value is provided. */
+      value?: MenuBadgeValue;
+      /** Key used to read dynamic badge content from the layout badge value map. */
+      valueKey?: string;
+      /** Visual status variant for the badge. */
+      variant?: MenuBadgeVariant;
+    }
+
+    interface Meta {
+      /** External link opened when the route is selected */
+      href?: string | null;
+
+      /**
+       * I18n key of the route
+       *
+       * It's used in i18n, if it is set, the title will be ignored
+       */
+      i18nKey?: I18n.I18nKey | null;
+
+      /** Whether to cache the route */
+      keepAlive?: boolean | null;
+
+      /**
+       * Menu configuration of the route
+       *
+       * It controls how the route is displayed in the menu
+       */
+      menu?: {
+        /**
+         * The menu key will be activated when entering the route
+         *
+         * It is usually used for detail pages or hidden routes
+         *
+         * Active strategy configuration
+         *
+         * It defines which menu should be activated when entering the route
+         */
+        activeMenu?: RoutePath | null;
+
+        /**
+         * Standard menu badge.
+         *
+         * It is used for common menu status like dot, count, new, and hot.
+         */
+        badge?: MenuBadge | null;
+
+        /**
+         * Custom menu extra component key.
+         *
+         * It is used for app-provided menu extra components that do not fit the standard badge model.
+         */
+        extra?: Extra | null;
+        /**
+         * Whether to hide the route in the menu
+         *
+         * If true, the route will not be rendered in the menu tree
+         */
+        hide?: boolean | null;
+
+        /**
+         * Iconify icon
+         *
+         * It can be used in the menu or breadcrumb
+         */
+        icon?: string | null;
+
+        /**
+         * Local icon
+         *
+         * In "src/assets/svg-icon", if it is set, the icon will be ignored
+         */
+        localIcon?: string | null;
+
+        /**
+         * Meta data of the menu
+         *
+         * It can be used to add meta data to the menu
+         */
+        meta?: { key: string; value: string }[] | null;
+
+        /**
+         * The menu order
+         *
+         * Smaller value means higher priority
+         */
+        order?: number | null;
+
+        /**
+         * Menu type
+         *
+         * @default 'item'
+         */
+        type?: MenuType | null;
+      };
+
+      /** Required permissions to access the route */
+      permissions?: string[] | null;
+
+      /** Default search params carried when this route is opened from a menu. */
+      query?: Api.Route.BackendRouteQuery[] | null;
+
+      /**
+       * Whether the route is required
+       *
+       * It can be used in permission or feature checks
+       */
+      requiresAuth?: boolean;
+
+      /**
+       * Tabs behavior configuration
+       *
+       * It controls how the route behaves in the tabs system
+       */
+      tab?: {
+        /** If set, the route will be fixed in tabs, and the value is the order of fixed tabs */
+        fixedIndex?: number | null;
+
+        /**
+         * Whether to allow multiple tabs for the same route
+         *
+         * By default, the same route path will use one tab, even with different query parameters
+         */
+        multi?: boolean | null;
+      };
+
+      /**
+       * Title of the route
+       *
+       * It can be used in document title
+       */
+      title?: string | null;
+
+      /** External page url rendered inside an iframe route */
+      url?: string | null;
+    }
+
+    interface RouterContext {
+      /** 获取系统首页路由路径 */
+      getHomeRoute: () => RoutePath;
+
+      /** 系统首页路由路径 */
+      homeRoute: RoutePath;
+      /**
+       * Initialize authentication information
+       *
+       * @returns The user information
+       */
+      initAuth: () => Promise<Api.Auth.UserInfo | null>;
+      /** Whether the authentication information has been initialized */
+      isAuthInitialized: boolean;
+      /** Whether the user is logged in */
+      isLoggedIn: boolean;
+      /** Logout user and clear authentication information */
+      logout: () => Promise<void>;
+
+      /** Query client */
+      queryClient: QueryClient;
+      /** User information */
+      userInfo?: Api.Auth.UserInfo;
+    }
+  }
+}
+
+export {};

package/templates/admin-shell/types/app/storage.d.ts

@@ -0,0 +1,10 @@
+/** Shared storage extension points */
+declare global {
+  namespace StorageType {
+    interface Session {}
+
+    interface Local {}
+  }
+}
+
+export {};