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

package/dist/stores/auth.d.ts

@@ -0,0 +1,56 @@
+import { type StoreApi } from 'zustand';
+import { type AdminLoginParams } from '../auth-gateway';
+import type { AdminUserInfo } from '../types';
+/**
+ * 令牌载荷
+ */
+export interface TokenPayload {
+    /**
+     * 令牌值
+     */
+    value: string;
+    /**
+     * 令牌过期时间
+     */
+    expiresAt?: number;
+}
+export interface AuthState {
+    accessToken: string | null;
+    accessTokenExpireAt: number | null;
+    userInfo: AdminUserInfo | null;
+    mfaOperationId: string | null;
+    loginLoading: boolean;
+    error: string | null;
+    login: (params: AdminLoginParams, onSuccess?: () => void, captcha?: {
+        id: string;
+        value: string;
+    }) => Promise<void>;
+    /**
+     * 完成 MFA 挑战：用 operation_id + TOTP 码调后端验证，通过则后端返回真 token，
+     * 复用登录成功流程（存 token / 拉用户信息 / 跳首页）。失败抛错。
+     */
+    completeMfaChallenge: (totpCode: string, onSuccess?: () => void) => Promise<void>;
+    /** 完成 OIDC SSO 登录：code+state 换令牌，复用登录成功流程；失败抛错 */
+    completeSsoLogin: (code: string, state: string, onSuccess?: () => void) => Promise<void>;
+    logout: (redirect?: boolean) => Promise<void>;
+    refreshToken: () => Promise<string>;
+    reauthenticate: () => void;
+    /** 强制登出：纯前端清除认证状态 + 跳转登录页，不调后端接口（用于 token 已失效场景） */
+    forceLogout: () => void;
+    setUserInfo: (info: AdminUserInfo) => void;
+    clearError: () => void;
+    $reset: () => void;
+}
+export declare const useAuthStore: import("zustand").UseBoundStore<Omit<StoreApi<AuthState>, "setState" | "persist"> & {
+    setState(partial: AuthState | Partial<AuthState> | ((state: AuthState) => AuthState | Partial<AuthState>), replace?: false | undefined): unknown;
+    setState(state: AuthState | ((state: AuthState) => AuthState), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<AuthState, {}, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void>;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: AuthState) => void) => () => void;
+        onFinishHydration: (fn: (state: AuthState) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<AuthState, {}, unknown>>;
+    };
+}>;

package/dist/stores/index.d.ts

@@ -0,0 +1,2 @@
+export * from './auth';
+export * from './user';

package/dist/stores/user.d.ts

@@ -0,0 +1,32 @@
+import type { AdminUserBasic } from '../types';
+export interface UserState {
+    userInfo: AdminUserBasic | null;
+    userRoles: string[];
+    accessCodes: string[];
+    hiddenFields: string[];
+    tenantId: string | null;
+    isLoggedIn: boolean;
+    setUserInfo: (info: AdminUserBasic | null) => void;
+    setUserRoles: (roles: string[]) => void;
+    setAccessCodes: (codes: string[]) => void;
+    setHiddenFields: (fields: string[]) => void;
+    isTenantUser: () => boolean;
+    $reset: () => void;
+}
+export declare const useUserStore: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<UserState>, "setState" | "persist"> & {
+    setState(partial: UserState | Partial<UserState> | ((state: UserState) => UserState | Partial<UserState>), replace?: false | undefined): unknown;
+    setState(state: UserState | ((state: UserState) => UserState), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<import("zustand/middleware").PersistOptions<UserState, {
+            userInfo: AdminUserBasic | null;
+        }, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void>;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: UserState) => void) => () => void;
+        onFinishHydration: (fn: (state: UserState) => void) => () => void;
+        getOptions: () => Partial<import("zustand/middleware").PersistOptions<UserState, {
+            userInfo: AdminUserBasic | null;
+        }, unknown>>;
+    };
+}>;

package/dist/transport/rest/captcha-headers.d.ts

@@ -0,0 +1,2 @@
+export declare function setCaptchaHeaders(id: string, value: string): void;
+export declare function consumeCaptchaHeaders(): Record<string, string> | null;

package/dist/transport/rest/index.d.ts

@@ -0,0 +1,8 @@
+export * from './captcha-headers';
+export * from './preset-interceptors';
+export * from './request-client';
+export * from './types';
+export * from './request-api';
+export * from './utils';
+export * from './pagination';
+export * from 'axios';

package/dist/transport/rest/modules/downloader.d.ts

@@ -0,0 +1,9 @@
+import type { AxiosRequestConfig } from 'axios';
+import type { RequestClient } from '../request-client';
+import type { RequestResponse } from '../types';
+declare class FileDownloader {
+    private client;
+    constructor(client: RequestClient);
+    download(url: string, config?: AxiosRequestConfig): Promise<RequestResponse<Blob>>;
+}
+export { FileDownloader };

package/dist/transport/rest/modules/interceptor.d.ts

@@ -0,0 +1,9 @@
+import type { AxiosInstance } from 'axios';
+import type { RequestInterceptorConfig, ResponseInterceptorConfig } from '../types';
+declare class InterceptorManager {
+    private axiosInstance;
+    constructor(instance: AxiosInstance);
+    addRequestInterceptor({ fulfilled, rejected, }?: RequestInterceptorConfig): void;
+    addResponseInterceptor<T = any>({ fulfilled, rejected, }?: ResponseInterceptorConfig<T>): void;
+}
+export { InterceptorManager };

package/dist/transport/rest/modules/uploader.d.ts

@@ -0,0 +1,10 @@
+import type { AxiosRequestConfig, AxiosResponse } from 'axios';
+import type { RequestClient } from '../request-client';
+declare class FileUploader {
+    private client;
+    constructor(client: RequestClient);
+    upload(url: string, data: {
+        file: Blob | File;
+    } & Record<string, any>, config?: AxiosRequestConfig): Promise<AxiosResponse>;
+}
+export { FileUploader };

package/dist/transport/rest/pagination.d.ts

@@ -0,0 +1,73 @@
+export declare class PaginationQuery {
+    paging?: {
+        page?: number;
+        pageSize?: number;
+    };
+    formValues?: Record<string, unknown> | null;
+    fieldMask?: string | string[] | null;
+    orderBy?: string[] | null;
+    isTenantUser: boolean;
+    constructor(data?: Partial<PaginationQuery>);
+    /**
+     * 移除对象中的 null 和 undefined 值
+     * @param obj - 需要清理的对象
+     * @returns 清理后的对象
+     */
+    private static removeNullUndefined;
+    /**
+     * key 末段是否已是 go-crud 支持的查询操作符（created_at__gte、type__not 等）。
+     * 这类 key 不能再叠加 __contains：go-crud 会把 `a__gte__contains`
+     * 解析成 `a CONTAINS value`，对时间/布尔列直接 SQL 报错（500），
+     * "排除"等语义也可能被静默反转。
+     *
+     * 下表与 go-crud `filter/operator_converter.go` 的 operatorMap 别名集
+     * 逐字对齐（含 i_* 前缀变体、数值比较长拼写/连字符拼写、is_not_null
+     * 拼写族、json_contains/array_contains/exists/search/exact/iexact）。
+     * 后端映射表变更时须同步此表；匹配前做小写归一（后端同）。此表缺项
+     * 会让对应后缀键被追加 __contains 而语义反转或 500（2026-09-13 修复的缺口）。
+     */
+    private static hasOperatorSuffix;
+    /**
+     * 创建列表查询 JSON 过滤字符串
+     *
+     * 后端 go-crud 的裸 `{"field": value}` 走 EQ 精确匹配；搜索框输入部分关键词
+     * 必须使用 `field__contains` 才是模糊匹配。这里约定：字符串值统一转
+     * `__contains`（contains 是完整值精确匹配的超集，对下拉枚举等完整值查询
+     * 结果一致），非字符串（数字/布尔）保持 EQ 精确语义。
+     * @param formValues - 查询表单值
+     * @param needCleanTenant - 是否需要清理租户字段
+     * @returns JSON 字符串或 undefined
+     */
+    private static makeQueryString;
+    /**
+     * 创建排序字符串
+     * @param orderBy - 排序字段数组
+     * @returns JSON 字符串或 undefined
+     */
+    private static makeOrderBy;
+    get noPaging(): boolean;
+    get orderByString(): string | undefined;
+    get queryString(): string | undefined;
+    private get formattedFieldMask();
+    toRawParams(): {
+        page: number | undefined;
+        pageSize: number | undefined;
+        noPaging: boolean;
+        fieldMask: string | undefined;
+        orderBy: string | undefined;
+        query: string | undefined;
+        sorting: undefined;
+        offset: undefined;
+        limit: undefined;
+        token: undefined;
+        filter: undefined;
+        filterExpr: undefined;
+    };
+}
+/**
+ * 分页查询结果类型
+ */
+export type PaginationResult<T> = {
+    items: T[];
+    total: number;
+};

package/dist/transport/rest/preset-interceptors.d.ts

@@ -0,0 +1,25 @@
+import type { RequestClient } from './request-client';
+import type { MakeErrorMessageFn, ResponseInterceptorConfig } from './types';
+/**
+ * 认证响应拦截器：处理 401 错误，支持自动刷新 token 和重新认证
+ * @param client 请求客户端实例
+ * @param doReAuthenticate 重新认证函数，返回 Promise<void>
+ * @param doRefreshToken 刷新 token 函数，返回 Promise<string>，成功时返回新的 token
+ * @param enableRefreshToken 是否启用刷新 token 功能
+ * @param formatToken 格式化 token 的函数，接受原始 token 字符串，返回格式化后的 token 字符串（如添加 "Bearer " 前缀），如果返回 null 则不设置 Authorization 头
+ * @returns 响应拦截器配置对象
+ */
+export declare const authenticateResponseInterceptor: ({ client, doReAuthenticate, doRefreshToken, enableRefreshToken, formatToken, }: {
+    client: RequestClient;
+    doReAuthenticate: () => Promise<void>;
+    doRefreshToken: () => Promise<string>;
+    enableRefreshToken: boolean;
+    formatToken: (token: string) => null | string;
+}) => ResponseInterceptorConfig;
+/**
+ * 错误消息拦截器：提取错误文本并回调
+ * @param makeErrorMessage 错误消息回调函数
+ * @param getErrorMsg 获取错误消息函数，默认为 getDefaultErrorMsg
+ * @returns 响应拦截器配置对象
+ */
+export declare const errorMessageResponseInterceptor: (makeErrorMessage?: MakeErrorMessageFn, getErrorMsg?: (error: unknown) => string) => ResponseInterceptorConfig;

package/dist/transport/rest/request-api.d.ts

@@ -0,0 +1,6 @@
+export declare function requestApi({ path, method, body, headers, }: {
+    path: string;
+    method: string;
+    body: null | string;
+    headers?: Record<string, string>;
+}): Promise<unknown>;

package/dist/transport/rest/request-client.d.ts

@@ -0,0 +1,87 @@
+import type { AxiosRequestConfig } from 'axios';
+import { FileDownloader } from './modules/downloader';
+import { InterceptorManager } from './modules/interceptor';
+import { FileUploader } from './modules/uploader';
+import type { RequestClientCallbacks, RequestClientOptions } from './types';
+declare class RequestClient {
+    private readonly instance;
+    /**
+     * 错误消息提取函数（由应用层注入，接入 i18n；未注入时回退到 getDefaultErrorMsg）。
+     * 仅基于 reason 翻译，不返回后端 message。
+     */
+    private readonly getErrorMsg;
+    addRequestInterceptor: InterceptorManager['addRequestInterceptor'];
+    addResponseInterceptor: InterceptorManager['addResponseInterceptor'];
+    download: FileDownloader['download'];
+    isRefreshing: boolean;
+    refreshTokenQueue: ((token: string) => void)[];
+    upload: FileUploader['upload'];
+    private static _instance;
+    /**
+     * 初始化全局单例（在 bootstrap 时调用一次）
+     */
+    static init(baseURL: string, callbacks: RequestClientCallbacks): void;
+    /**
+     * 获取全局单例
+     */
+    static getInstance(): RequestClient;
+    /**
+     * 构造函数，创建 Axios 实例并注册拦截器
+     * @param options - Axios 请求配置
+     * @param callbacks - 业务回调接口（token、认证、错误处理），由应用层注入
+     */
+    constructor(options?: RequestClientOptions, callbacks?: RequestClientCallbacks);
+    /**
+     * 格式化令牌
+     */
+    private formatToken;
+    /**
+     * 注册所有内置拦截器
+     */
+    private setupInterceptors;
+    /**
+     * 请求拦截器：注入 Authorization Token
+     */
+    private useTokenInterceptor;
+    /**
+     * 请求拦截器：注入 X-Request-ID 和 XMLHttpRequest 标识
+     */
+    private useRequestIdInterceptor;
+    /**
+     * 请求拦截器：注入 Accept-Language
+     */
+    private useLocaleInterceptor;
+    /**
+     * 响应拦截器：解构响应数据（只返回 data 部分）
+     */
+    private useResponseDataInterceptor;
+    /**
+     * 401 认证拦截器：自动刷新 Token 或跳转登录页
+     */
+    private useAuthInterceptor;
+    /**
+     * 统一错误消息拦截器：提取错误文本并回调
+     */
+    private useErrorMessageInterceptor;
+    /**
+     * DELETE请求方法
+     */
+    delete<T = never>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * GET请求方法
+     */
+    get<T = never>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * POST请求方法
+     */
+    post<T = never>(url: string, data?: never, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * PUT请求方法
+     */
+    put<T = never>(url: string, data?: never, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * 通用的请求方法
+     */
+    request<T>(url: string, config: AxiosRequestConfig): Promise<T>;
+}
+export { RequestClient };

package/dist/transport/rest/types.d.ts

@@ -0,0 +1,38 @@
+import type { AxiosResponse, CreateAxiosDefaults, InternalAxiosRequestConfig } from 'axios';
+type RequestResponse<T = any> = AxiosResponse<T>;
+type RequestContentType = 'application/json;charset=utf-8' | 'application/octet-stream;charset=utf-8' | 'application/x-www-form-urlencoded;charset=utf-8' | 'multipart/form-data;charset=utf-8';
+type RequestClientOptions = CreateAxiosDefaults;
+interface RequestInterceptorConfig {
+    fulfilled?: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig<any> | Promise<InternalAxiosRequestConfig<any>>;
+    rejected?: (error: any) => any;
+}
+interface ResponseInterceptorConfig<T = any> {
+    fulfilled?: (response: AxiosResponse<T>) => AxiosResponse | Promise<AxiosResponse>;
+    rejected?: (error: any) => any;
+}
+type MakeErrorMessageFn = (message: string, error: any) => void;
+interface HttpResponse {
+    code: number;
+    reason: string;
+    message: string;
+    metadata: object;
+}
+/**
+ * 请求客户端回调接口
+ * 由应用层（bootstrap）注入具体实现，基础设施层不感知业务逻辑
+ */
+interface RequestClientCallbacks {
+    /** 获取当前 access token */
+    getToken: () => string | null;
+    /** 获取当前语言标识（如 zh-CN、en-US） */
+    getLocale?: () => string;
+    /** 刷新 token，返回新的 access token */
+    refreshToken: () => Promise<string>;
+    /** Token 彻底失效时的处理（登出 + 跳转登录页） */
+    onReAuthenticate: (redirect?: boolean) => Promise<void>;
+    /** 错误消息处理（弹窗、toast 等） */
+    onError?: (message: string) => void;
+    /** 从错误对象中提取用户友好的错误消息（可接入 i18n） */
+    getErrorMsg?: (error: unknown) => string;
+}
+export type { RequestClientCallbacks, HttpResponse, MakeErrorMessageFn, RequestClientOptions, RequestContentType, RequestInterceptorConfig, RequestResponse, ResponseInterceptorConfig, };

package/dist/transport/rest/utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 创建更新掩码字符串
+ * @param keys - 字段键名数组
+ * @returns 逗号分隔的字符串
+ */
+export declare function makeUpdateMask(keys: string[]): string;
+/**
+ * 默认的请求 ID 生成器
+ */
+export declare function defaultIdGenerator(): string;
+/**
+ * 默认的错误消息提取（不依赖 i18n，纯逻辑 fallback）
+ * 仅基于 reason；不再回退到后端 message 字段（该字段后续将被移除）。
+ * 如需 i18n 翻译，通过 RequestClientCallbacks.getErrorMsg 注入。
+ */
+export declare function getDefaultErrorMsg(error: unknown): string;

package/dist/transport/sse/event.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SSE 事件名注册表（react 端副本）。
+ *
+ * 真相源是后端 `backend/pkg/sseevent/sseevent.go`：它把常量写进帧的 `event:` 行，
+ * 这里按同名注册回调，中间没有编译期检查（`SSEEventName` 带 `| string`，等于不约束）。
+ * 新增事件要两边同时改；已发布事件的取值不可改——改名等于对线上前端静默断流。
+ */
+export declare const SSE_EVENT: {
+    /**
+     * 站内信收件行推送。
+     *
+     * data 为 `InternalMessageRecipient` 的 protojson：camelCase 键（`messageId` /
+     * `recipientUserId` / `createdAt`），`status` 是枚举名字符串（`RECEIVED` / `READ`），
+     * 与 REST 收件箱接口返回的形状一致。
+     */
+    readonly Notification: "notification";
+    /**
+     * AI 对话流式片段推送。
+     *
+     * data 为 `ChatChunkEvent` 的 protojson：camelCase 键（`conversationId` /
+     * `seq` / `delta`）。一次对话产生多个 chunk 帧，按 conversationId 归组、
+     * seq 顺序累积渲染；POST /admin/v1/ai/chat/completions 的同步响应携带
+     * 完整回复，以响应为准校正累积文本。
+     */
+    readonly AIChatChunk: "ai_chat_chunk";
+    /**
+     * AI 对话的工具调用可见化推送。
+     *
+     * data 为 `ChatToolEvent` 的 protojson：camelCase 键（`conversationId` /
+     * `name` / `arguments` / `result`）。模型每发起一次本地工具调用并执行完成
+     * 后推一帧；工具轮不进消息落库（落库的 assistant 消息只有最终答案），
+     * 本事件是前端展示"模型正在调工具"的唯一信息源（尽力而为，丢帧可容忍）。
+     */
+    readonly AIChatTool: "ai_chat_tool";
+    /**
+     * AI Agent 试运行实时推送。
+     *
+     * data 为 `AgentRunEvent` 的 protojson：camelCase 键（`runId` / `appId` /
+     * `seq` / `phase`（node_start|node_end|error|done） / `nodeId` / `summary` /
+     * `status`）。一次试运行产生多帧；Run 同步响应携带完整 trace 与终态，
+     * 以响应为准校正（尽力而为，丢帧可容忍）。streamId 与对话同为发起用户流。
+     */
+    readonly AgentRun: "ai_agent_run";
+};

package/dist/transport/sse/index.d.ts

@@ -0,0 +1,5 @@
+import { SSEClient } from './sse_client';
+export * from './sse_client';
+export * from './types';
+export * from './event';
+export declare const globalSSEClient: SSEClient;

package/dist/transport/sse/sse_client.d.ts

@@ -0,0 +1,76 @@
+import type { SSEClientConfig, SSEConnectionStatus, SSEEventHandler, SSEEventName } from './types';
+/**
+ * SSE客户端
+ */
+export declare class SSEClient {
+    private abortController;
+    private config;
+    private eventSource;
+    private handlers;
+    private status;
+    private readonly transport;
+    constructor(config: SSEClientConfig);
+    /**
+     * 解析数据（自动处理 JSON 格式）
+     * @param rawData
+     * @private
+     */
+    private parseData;
+    /**
+     * 触发事件监听器
+     * @param eventName
+     * @param data
+     * @param event
+     * @private
+     */
+    private triggerHandler;
+    /**
+     * 通过 EventSource 建立 SSE 连接
+     * @param url 连接 URL
+     * @private
+     */
+    _connectByEventSource(url: string): void;
+    /**
+     * 通过 fetchEventSource 建立 SSE 连接（支持更灵活的配置和控制）
+     * @param url 连接 URL
+     * @private
+     */
+    _connectByFetchEventSource(url: string): Promise<void>;
+    /**
+     * 关闭 SSE 连接
+     */
+    close(): void;
+    /**
+     * 建立 SSE 连接
+     * @param url 可选连接 URL，默认为配置中的 URL
+     */
+    connect(url?: string): Error | null;
+    /**
+     * 获取当前连接状态
+     */
+    getStatus(): SSEConnectionStatus;
+    /**
+     * 移除事件监听器
+     * @param eventName
+     * @param handler
+     */
+    off<T = unknown>(eventName: SSEEventName, handler?: SSEEventHandler<T>): void;
+    /**
+     * 注册事件监听器（支持泛型指定数据类型）
+     * @param eventName
+     * @param handler
+     */
+    on<T = unknown>(eventName: SSEEventName, handler: SSEEventHandler<T>): void;
+    /**
+     * 关闭当前连接并使用新的 URL / headers 重新连接
+     * 适用于 token 刷新后需要携带新凭证的场景
+     * @param url 可选的新连接 URL，默认沿用配置中的 URL
+     */
+    reconnect(url?: string): void;
+    /**
+     * 动态设置/更新请求头（不会影响正在进行中的连接，下次 connect 时生效）
+     * 注意：EventSource 模式不支持自定义请求头，此方法仅对 fetch-event-source 模式生效
+     * @param headers 键值对，会浅合并到当前 headers 配置中
+     */
+    setHeaders(headers: Record<string, string>): void;
+}

package/dist/transport/sse/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SSE 事件类型（区分默认事件和自定义事件）
+ */
+export type SSEEventName = 'error' | 'message' | 'open' | string;
+/**
+ * SSE 事件回调函数类型（T 为数据类型）
+ */
+export type SSEEventHandler<T = unknown> = (data: T, event: MessageEvent) => void;
+/**
+ * SSE 连接实现方式
+ */
+export type SSETransport = 'event-source' | 'fetch-event-source';
+/**
+ * SSE 客户端配置
+ */
+export interface SSEClientConfig {
+    url: string;
+    withCredentials?: boolean;
+    reconnectDelay?: number;
+    autoParseJson?: boolean;
+    headers?: Record<string, string>;
+    transport?: SSETransport;
+}
+/**
+ * SSE 连接状态
+ */
+export type SSEConnectionStatus = 'connected' | 'connecting' | 'disconnected' | 'error';

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 包内基础类型（自 go-wind-admin 的 src/types/global.d.ts 迁入）。
+ *
+ * 宿主应用保留自己的全局 `UserInfo`/`BasicUserInfo` 声明即可——它们与本包的
+ * AdminUserInfo 结构兼容（宿主接口字段为必填，赋给本包可选字段类型天然可赋值），
+ * 无需 declaration merging。
+ */
+/** 用户信息基础形状（与宿主 BasicUserInfo 对齐） */
+export interface AdminUserBasic {
+    [key: string]: any;
+    /** 头像 */
+    avatar: string;
+    /** 用户id（后端 uint64，proto3 JSON 下为字符串） */
+    id: string;
+    /** 用户昵称 */
+    nickname: string;
+    /** 用户实名 */
+    realname: string;
+    /** 用户角色 */
+    roles?: string[];
+    /** 租户id（后端 uint64，proto3 JSON 下为字符串） */
+    tenantId: string;
+    /** 用户名 */
+    username: string;
+}
+/** 包内认证/用户 store 消费的用户信息形状 */
+export interface AdminUserInfo extends AdminUserBasic {
+    /** 用户描述 */
+    description?: string;
+    /** 首页地址 */
+    homePath?: string;
+    /** accessToken */
+    token?: string;
+}
+/**
+ * React Router 路由 handle 元数据类型。
+ * 用于 useMatches() 获取路由附加信息（自宿主全局声明迁入）。
+ */
+export interface RouteHandle {
+    title?: string;
+    icon?: string;
+    authority?: string[];
+    [key: string]: any;
+}

package/dist/utils/color.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 生成基于字符串的固定随机色（HSL模式，保证饱和度和明度适中）
+ *
+ * 浅底色（l=85）：只能配深色墨（最差色相对深色墨仍 ≥11:1），配白字不可读。
+ * @param str
+ */
+export declare const getRandomColor: (str: string) => string;
+/**
+ * 根据首字母生成固定随机色（头像实底色，前景固定近白）
+ *
+ * 明度取 28% 是量出来的：本函数的产物一律配 antd/EP 头像的白字，而 hsl 同饱和度下
+ * 45% 明度是"两种墨都不合格"的死区（360 个色相里最差 white 2.03 / dark 2.01）；
+ * 28% + s60 保证任意色相下白字 ≥4.86:1（判据与换算见 docs/design-language.md §2.1）。
+ * @param char
+ */
+export declare const getCharColor: (char: string) => string;
+export declare function hexToRgb(hex: string): [number, number, number];
+export declare function rgbToHex(r: number, g: number, b: number): string;
+/** 解析 `#rgb`/`#rrggbb`/`hsl(h s% l%)`/`hsl(h, s%, l%)` 为 [r,g,b]（0-255）；无法识别返回 null */
+export declare function parseColor(c: string): [number, number, number] | null;
+/**
+ * 与 CSS `color-mix(in srgb, base pct%, other)` 同口径的 JS 版本。
+ * 存在的理由：antd 的 token 值（colorLink、Menu.itemSelectedColor 等）会被 antd 再做
+ * 一次色彩运算，不能填 `var(--gowind-*)`，所以「语义色作文字」的降档/升档要在 TS 里算一遍；
+ * 比例与 vue-element 端 `styles/vendors/_element-plus.scss` §3 完全一致，改动须同步两处。
+ */
+export declare function mixColor(base: string, other: string, pct: number): string;

package/dist/utils/date.d.ts

@@ -0,0 +1,5 @@
+export declare function formatDate(dateString: string | undefined): string;
+export declare const formatDateTime: (timestamp?: any) => string;
+export declare const DATE_FORMAT = "YYYY-MM-DD";
+export declare const TIME_FORMAT = "YYYY-MM-DD HH:mm:ss";
+export declare const TIME_PICKER_FORMAT = "HH:mm:ss";

package/dist/utils/diff.d.ts

@@ -0,0 +1,6 @@
+declare function arraysEqual<T>(a: T[], b: T[]): boolean;
+type DiffResult<T> = Partial<{
+    [K in keyof T]: T[K] extends object ? DiffResult<T[K]> : T[K];
+}>;
+declare function diff<T extends Record<string, any>>(obj1: T, obj2: T): DiffResult<T>;
+export { arraysEqual, diff };

package/dist/utils/index.d.ts

@@ -0,0 +1,9 @@
+export * from './merge';
+export * from './inference';
+export * from './utils';
+export * from './nprogress';
+export * from './date';
+export * from './color';
+export * from './url';
+export * from './diff';
+export * from './tree';