@aithe/aithe-ui 26.2.3 → 26.3.1

package/dist/core/datahub/core/datahub-core.js

@@ -0,0 +1,441 @@
+/**
+ * @file DataHubCore - 核心调度器 / Core Dispatcher
+ * @description DataHub 的核心引擎，负责请求的完整生命周期管理：
+ *              1. 合并配置 → 2. 解析策略 → 3. 生成 traceId → 4. 请求拦截
+ *              → 5. 缓存检查 → 6. 去重/幂等 → 7. 适配器调用 → 8. 响应拦截
+ *              → 9. 缓存写入 → 10. 错误处理 → 11. loading 状态管理
+ *
+ *              设计原则：
+ *              - DataHub 只处理 HTTP 传输层，不关心业务协议
+ *              - 业务协议（code/message/data 等）由使用者在外部自行解析
+ *              - DataHubAdapterResponse.data 为原始 JSON，不做任何业务语义假设
+ *              - 适配器完全可插拔，核心不依赖任何具体适配器实现
+ *              - 策略自动识别，业务层无需关心缓存/去重/防重细节
+ *              - 统一错误处理，仅处理传输层异常
+ *
+ *              The core engine of DataHub, managing the complete request lifecycle.
+ *
+ *              Design principles:
+ *              - DataHub handles only the HTTP transport layer, not business protocols
+ *              - Business protocols (code/message/data, etc.) are interpreted by the consumer externally
+ *              - DataHubAdapterResponse.data is raw JSON with no assumed business semantics
+ *              - Adapters are fully pluggable; the core depends on no specific adapter implementation
+ *              - Strategy is auto-detected; the business layer need not worry about cache/dedup/idempotent details
+ *              - Unified error handling, only for transport-layer exceptions
+ */
+import { DataHubError as DataHubErrorClass } from '../../datahub/types';
+import { getBuiltinStyle, getBuiltinStyleNames } from './api-styles';
+import { FetchAdapter } from './adapter/fetch-adapter';
+import { MockAdapter } from './adapter/mock-adapter';
+import { resolveStrategy } from '../../datahub/config/strategy';
+import { cacheGet, cacheSet, cacheClear } from '../../datahub/utils/cache';
+import { dedupTrack, dedupClear } from '../../datahub/utils/dedup';
+import { loadingStart, loadingEnd, onLoadingChange, isLoading } from '../../datahub/utils/loading';
+import { idempotentGuard, idempotentClear } from '../../datahub/utils/idempotent';
+/** 默认配置项 / Default configuration values */
+const DEFAULT_CONFIG = {
+    /** 默认超时 30 秒 / Default timeout 30s */
+    defaultTimeout: 30000,
+    /** 默认缓存有效期 60 秒 / Default cache TTL 60s */
+    defaultCacheTTL: 60_000,
+    /** 默认使用 fetch 适配器 / Default to fetch adapter */
+    defaultAdapter: 'fetch',
+};
+/**
+ * DataHubCore - 核心调度器 / Core Dispatcher
+ * @description 管理适配器注册、API 注册、请求调度及中间件编排。
+ *              返回 DataHubAdapterResponse<T>，其中 data 为原始 JSON 解析结果，
+ *              不包含任何业务协议假设。使用者自行解析业务结构。
+ *              Manages adapter registration, API registration, request dispatch, and middleware orchestration.
+ *              Returns DataHubAdapterResponse<T>, where data is raw JSON-parsed result
+ *              without any business protocol assumptions. Consumers parse business structures themselves.
+ */
+export class DataHubCore {
+    /**
+     * @param config - 全局配置 / Global configuration
+     */
+    constructor(config = {}) {
+        /** 已注册的适配器映射，键为适配器名称 / Registered adapter map, keyed by adapter name */
+        this.adapters = new Map();
+        // ─── Loading 状态代理 / Loading State Proxy ───────────────────
+        /** 订阅 loading 状态变更 / Subscribe to loading state changes */
+        this.onLoadingChange = onLoadingChange;
+        /** 查询指定 URL 是否正在加载 / Check if the specified URL is currently loading */
+        this.isLoading = isLoading;
+        this.config = config;
+        // APIStyle 默认为空，不处理业务协议
+        // APIStyle defaults to undefined — no business protocol handling
+        // 内置注册两个零依赖适配器 / Register two zero-dependency built-in adapters
+        this.registerAdapter(new FetchAdapter());
+        this.registerAdapter(new MockAdapter());
+    }
+    // ─── 适配器管理 / Adapter Management ──────────────────────────
+    /**
+     * 注册适配器 / Register an adapter
+     * @param adapter - 适配器实例，需实现 DataHubAdapter 接口 / Adapter instance implementing DataHubAdapter
+     * @throws 如果同名适配器已存在，静默覆盖 / Silently overwrites if an adapter with the same name already exists
+     */
+    registerAdapter(adapter) {
+        this.adapters.set(adapter.name, adapter);
+    }
+    /**
+     * 获取已注册的适配器 / Get a registered adapter by name
+     * @param name - 适配器名称 / Adapter name
+     * @returns 适配器实例，未找到返回 undefined / Adapter instance, or undefined if not found
+     */
+    getAdapter(name) {
+        return this.adapters.get(name);
+    }
+    // ─── APIStyle 管理 / APIStyle Management ──────────────────────
+    /**
+     * 设置 APIStyle / Set APIStyle
+     * @param style - APIStyle 实例或内置风格名称（"default" | "k8s"）/ APIStyle instance or built-in style name
+     *
+     * @example
+     * // 使用内置风格 / Use built-in style
+     * dataHub.setAPIStyle('k8s');
+     *
+     * @example
+     * // 使用自定义风格 / Use custom style
+     * dataHub.setAPIStyle({
+     *   name: 'custom',
+     *   onRequest(req) { ... },
+     *   onResponse(res) { ... },
+     * });
+     */
+    setAPIStyle(style) {
+        if (typeof style === 'string') {
+            const builtin = getBuiltinStyle(style);
+            if (!builtin) {
+                throw new DataHubErrorClass({
+                    code: 'APIStyleNotFound',
+                    message: `Built-in APIStyle "${style}" is not found. Available: ${getBuiltinStyleNames().join(', ')}`,
+                });
+            }
+            this.apiStyle = builtin;
+        }
+        else {
+            this.apiStyle = style;
+        }
+    }
+    /**
+     * 获取当前 APIStyle / Get current APIStyle
+     * @returns 当前 APIStyle 实例 / Current APIStyle instance
+     */
+    getAPIStyle() {
+        return this.apiStyle;
+    }
+    /**
+     * 解析单次请求使用的 APIStyle：优先使用 options.apiStyle，否则回退到全局 this.apiStyle。
+     * 当 options.apiStyleRaw 为 true 时，返回 undefined 跳过 APIStyle 处理。
+     * Resolve the APIStyle for a single request: prefers options.apiStyle, falls back to this.apiStyle.
+     * Returns undefined when options.apiStyleRaw is true, skipping APIStyle processing.
+     */
+    resolveRequestStyle(options) {
+        if (options.apiStyle) {
+            if (typeof options.apiStyle === 'string') {
+                return getBuiltinStyle(options.apiStyle);
+            }
+            return options.apiStyle;
+        }
+        return this.apiStyle;
+    }
+    // ─── 核心请求方法 / Core Request Method ───────────────────────
+    /**
+     * 统一请求入口 / Unified request entry point
+     * @param url - 请求地址（相对路径会自动拼接 baseURL）/ Request URL (relative paths are auto-prepended with baseURL)
+     * @param data - 请求体数据 / Request body data
+     * @param options - 请求配置项 / Request options
+     * @returns DataHubAdapterResponse<T>，包含原始 JSON 响应体，业务协议由使用者自行解析
+     *          DataHubAdapterResponse<T> with raw JSON body — business protocol is interpreted by the consumer
+     *
+     * @example
+     * // 使用者自行定义业务协议 / Consumer defines their own business protocol
+     * interface BizResponse { code: string; message: string; data: unknown }
+     *
+     * const res = await dataHub.request('/order/query', { id: '1' });
+     * // res.ok — HTTP 是否成功 / whether HTTP succeeded
+     * // res.status — HTTP 状态码 / HTTP status code
+     * // res.data — 原始 JSON，由使用者按 BizResponse 自行解析 / raw JSON, interpreted by consumer as BizResponse
+     * const biz = res.data as BizResponse;
+     * if (biz.code === 'Ok') { /* handle success *\/ }
+     */
+    async request(url, data, options) {
+        // 1. 合并默认配置与用户配置 / Merge default config with user config
+        const merged = this.mergeOptions(options);
+        // 2. 拼接完整 URL / Resolve full URL
+        const fullUrl = this.resolveUrl(url);
+        // 3. 根据 URL 自动识别策略 / Auto-detect strategy based on URL
+        const strategy = resolveStrategy(fullUrl);
+        // 4. 生成或使用 traceId / Generate or use existing traceId
+        const traceId = merged.traceId ?? this.generateTraceId();
+        // 将 traceId 写入配置，供适配器使用 / Write traceId into options for adapter usage
+        merged.traceId = traceId;
+        // 合并全局 headers 并透传 traceId 和 locale
+        // Merge global headers and propagate traceId and locale
+        const traceHeaderKey = this.config.traceHeaderKey ?? 'X-B3-TraceId';
+        const localeHeaderKey = this.config.localeHeaderKey ?? 'X-Locale';
+        merged.headers = {
+            ...this.config.headers,
+            ...merged.headers,
+            [traceHeaderKey]: traceId,
+        };
+        if (this.config.getLocale) {
+            merged.headers[localeHeaderKey] = this.config.getLocale();
+        }
+        // 使用 APIStyle 封装请求体数据 / Wrap request data using APIStyle
+        const req = { url: fullUrl, data, options: merged };
+        const requestStyle = this.resolveRequestStyle(merged);
+        requestStyle?.onRequest(req);
+        // 5. 请求拦截器 / Request interceptor
+        if (this.config.onRequest) {
+            const intercepted = this.config.onRequest(req);
+            if (intercepted)
+                Object.assign(req, intercepted);
+        }
+        // 6. 缓存检查：查询类请求且未跳过缓存时，尝试命中缓存
+        // Cache check: for query requests without skipCache, try to hit cache
+        if (strategy.cacheable && !merged.skipCache) {
+            const cached = cacheGet(fullUrl, data);
+            if (cached)
+                return cached;
+        }
+        // 实际执行请求的内部函数 / Internal function that actually executes the request
+        const execute = async () => {
+            // 标记 loading 开始 / Mark loading start
+            loadingStart(fullUrl);
+            try {
+                // 7. 解析并调用适配器 / Resolve and call adapter
+                const adapter = this.resolveAdapter(merged);
+                const res = await adapter.request(req);
+                // 8. 响应拦截器 / Response interceptor
+                if (this.config.onResponse) {
+                    const intercepted = this.config.onResponse(res, req);
+                    if (intercepted)
+                        Object.assign(res, intercepted);
+                }
+                // 9. HTTP 传输层错误处理：HTTP 非 2xx 时，优先用 APIStyle 解析响应体
+                // HTTP transport error: when !res.ok, try APIStyle first, fall back to transport error
+                if (!res.ok) {
+                    if (requestStyle) {
+                        const result = requestStyle.onResponse(res);
+                        throw new DataHubErrorClass({
+                            code: result.code ?? `HTTP_${res.status}`,
+                            message: result.message || `HTTP request failed with status ${res.status}`,
+                            trace: traceId,
+                            status: res.status,
+                            url: fullUrl,
+                            data: res.data,
+                        });
+                    }
+                    throw this.createTransportError(res, traceId, fullUrl);
+                }
+                // 10. 使用 APIStyle 解析业务结果（code/message/data）
+                // Use APIStyle to parse business result (code/message/data)
+                if (requestStyle) {
+                    const result = requestStyle.onResponse(res);
+                    // 11. 业务错误处理：根据风格自定义的成功判断
+                    // Business error handling: success check defined by the style
+                    if (!requestStyle.isSuccess(result)) {
+                        throw new DataHubErrorClass({
+                            code: result.code,
+                            message: result.message || `error: ${result.code}`,
+                            trace: traceId,
+                            status: res.status,
+                            url: fullUrl,
+                        });
+                    }
+                    // 缓存写入：查询类请求成功后写入缓存
+                    // Cache write: write to cache after successful query request
+                    if (strategy.cacheable && !merged.skipCache) {
+                        const ttl = merged.cacheTTL ?? DEFAULT_CONFIG.defaultCacheTTL;
+                        cacheSet(fullUrl, data, res, ttl);
+                    }
+                    // 返回时 data 替换为业务数据 / Replace data with business data in response
+                    return { ...res, data: result.data };
+                }
+                // 缓存写入：查询类请求成功后写入缓存
+                // Cache write: write to cache after successful query request
+                if (strategy.cacheable && !merged.skipCache) {
+                    const ttl = merged.cacheTTL ?? DEFAULT_CONFIG.defaultCacheTTL;
+                    cacheSet(fullUrl, data, res, ttl);
+                }
+                // APIStyle 为空，直接返回原始响应 / No APIStyle, return raw response directly
+                return res;
+            }
+            catch (err) {
+                // 13. 统一错误处理：将各类异常转换为 DataHubError
+                // Unified error handling: convert all exceptions to DataHubError
+                const error = this.normalizeError(err, fullUrl, traceId);
+                if (this.config.onError) {
+                    this.config.onError(error, req);
+                }
+                throw error;
+            }
+            finally {
+                // 无论成功失败，标记 loading 结束 / Mark loading end regardless of success or failure
+                loadingEnd(fullUrl);
+            }
+        };
+        // 12. 去重处理：查询类请求自动合并相同并发请求
+        // Dedup: automatically merge identical concurrent query requests
+        if (strategy.dedupable && !merged.skipDedup) {
+            return dedupTrack(fullUrl, data, execute);
+        }
+        // 13. 幂等防护：提交类请求阻止重复提交
+        // Idempotent guard: block duplicate submissions for submit requests
+        if (strategy.idempotent && !merged.skipIdempotent) {
+            return idempotentGuard(fullUrl, data, execute);
+        }
+        // 14. 无需中间件，直接执行 / No middleware needed, execute directly
+        return execute();
+    }
+    // ─── 状态清理方法 / State Cleanup Methods ─────────────────────
+    /** 清空所有缓存 / Clear all cache */
+    clearCache() {
+        cacheClear();
+    }
+    /** 清空所有去重记录 / Clear all dedup records */
+    clearDedup() {
+        dedupClear();
+    }
+    /** 清空所有幂等锁 / Clear all idempotent locks */
+    clearIdempotent() {
+        idempotentClear();
+    }
+    // ─── 配置修改方法 / Configuration Modification Methods ─────────
+    /**
+     * 设置请求拦截器 / Set request interceptor
+     */
+    setRequestInterceptor(handler) {
+        this.config.onRequest = handler;
+    }
+    /**
+     * 设置响应拦截器 / Set response interceptor
+     */
+    setResponseInterceptor(handler) {
+        this.config.onResponse = handler;
+    }
+    /**
+     * 设置全局错误回调 / Set global error handler
+     */
+    setErrorHandler(handler) {
+        this.config.onError = handler;
+    }
+    /**
+     * 更新全局配置（合并方式） / Update global config (merge mode)
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * 获取当前配置（只读副本） / Get current config (read-only copy)
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    // ─── 私有方法 / Private Methods ───────────────────────────────
+    /**
+     * 解析适配器 / Resolve adapter
+     */
+    resolveAdapter(options) {
+        if (this.config.forceMock || options.mock) {
+            return this.adapters.get('mock') ?? this.adapters.get(DEFAULT_CONFIG.defaultAdapter);
+        }
+        const name = options.adapter ?? this.config.defaultAdapter ?? DEFAULT_CONFIG.defaultAdapter;
+        const adapter = this.adapters.get(name);
+        if (!adapter) {
+            throw new DataHubErrorClass({
+                code: 'AdapterNotFound',
+                message: `Adapter "${name}" is not registered`,
+            });
+        }
+        return adapter;
+    }
+    /**
+     * 拼接完整 URL / Resolve full URL
+     */
+    resolveUrl(url) {
+        if (this.config.baseURL && !url.startsWith('http')) {
+            let base = this.config.baseURL;
+            while (base.endsWith('/'))
+                base = base.slice(0, -1);
+            let path = url;
+            while (path.startsWith('/'))
+                path = path.slice(1);
+            return `${base}/${path}`;
+        }
+        return url;
+    }
+    /**
+     * 合并请求配置 / Merge request options
+     */
+    mergeOptions(options) {
+        return {
+            timeout: DEFAULT_CONFIG.defaultTimeout,
+            cacheTTL: DEFAULT_CONFIG.defaultCacheTTL,
+            ...options,
+        };
+    }
+    /**
+     * 生成 traceId / Generate traceId
+     */
+    generateTraceId() {
+        if (this.config.generateTraceId)
+            return this.config.generateTraceId();
+        if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+            return crypto.randomUUID();
+        }
+        const timestamp = (typeof performance === 'undefined' ? Date.now() : performance.now()).toString(36);
+        const bytes = new Uint8Array(8);
+        if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+            crypto.getRandomValues(bytes);
+        }
+        const random = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+        return timestamp + random;
+    }
+    /**
+     * 根据 HTTP 传输层错误创建 DataHubError / Create DataHubError from HTTP transport error
+     */
+    createTransportError(res, traceId, url) {
+        return new DataHubErrorClass({
+            code: `HTTP_${res.status}`,
+            message: `HTTP request failed with status ${res.status}`,
+            trace: traceId,
+            status: res.status,
+            url,
+            data: res.data,
+        });
+    }
+    /**
+     * 标准化错误：将各类异常统一转换为 DataHubError
+     * Normalize errors: convert all exception types to DataHubError uniformly
+     */
+    normalizeError(err, url, traceId) {
+        if (err instanceof DataHubErrorClass)
+            return err;
+        if (err instanceof DOMException && err.name === 'AbortError') {
+            return new DataHubErrorClass({
+                code: 'RequestAborted',
+                message: 'Request was aborted',
+                trace: traceId,
+                url,
+            });
+        }
+        if (err instanceof TypeError) {
+            return new DataHubErrorClass({
+                code: 'NetworkError',
+                message: err.message ?? 'Network error',
+                trace: traceId,
+                url,
+            });
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return new DataHubErrorClass({
+            code: 'UnknownError',
+            message,
+            trace: traceId,
+            url,
+        });
+    }
+}

package/dist/core/datahub/core/index.js

@@ -0,0 +1,7 @@
+/**
+ * @file Core 模块导出 / Core Module Exports
+ * @description 统一导出核心调度器和内置适配器。
+ *              Unified export of the core dispatcher and built-in adapters.
+ */
+export { DataHubCore } from './datahub-core';
+export { FetchAdapter, MockAdapter } from './adapter';

package/dist/core/datahub/index.js

@@ -0,0 +1,50 @@
+/**
+ * @file DataHub 数据中间层 — 对外出口 / DataHub Data Middleware — Public Exports
+ * @description 提供统一的导入入口，导出所有公开 API：
+ *              - 核心类：DataHubCore
+ *              - 内置适配器：FetchAdapter、MockAdapter
+ *              - 类型定义：所有 interface / type / class
+ *              - 工具函数：策略解析、缓存、去重、loading、幂等防护
+ *              - 默认实例：default export（推荐使用默认实例或 new DataHubCore()）
+ *
+ *              Note: DataHub handles only the HTTP transport layer, not business protocols.
+ *              DataHubAdapterResponse.data is raw JSON; business protocol is interpreted by the consumer.
+ *
+ * @example
+ * // 使用默认实例 / Use default instance
+ * import {dataHub} from './datahub';
+ * const res = await dataHub.request('/order/query', { id: '1' });
+ * // res.ok — HTTP 是否成功 / whether HTTP succeeded
+ * // res.data — 原始 JSON，由使用者自行解析业务协议 / raw JSON, consumer parses business protocol
+ *
+ * @example
+ * // 创建独立实例 / Create isolated instance
+ * import { DataHubCore } from './datahub';
+ * const hub = new DataHubCore({ baseURL: '/api' });
+ *
+ * @example
+ * // 扩展适配器 / Extend with custom adapter
+ * import { DataHubCore } from './datahub';
+ * const hub = new DataHubCore();
+ * hub.registerAdapter({ name: 'axios', async request(req) { ... } });
+ */
+// ─── 核心类 / Core Class ────────────────────────────────────────
+export { DataHubCore } from './core';
+// ─── 内置适配器 / Built-in Adapters ─────────────────────────────
+export { FetchAdapter, MockAdapter } from './core/adapter';
+export { getBuiltinStyle, getBuiltinStyleNames } from './core/api-styles';
+// ─── 错误类导出 / Error Class Export ────────────────────────────
+export { DataHubError } from './types';
+// ─── 策略解析 / Strategy Resolution ─────────────────────────────
+export { resolveStrategy } from './config/strategy';
+// ─── 工具函数导出 / Utility Function Exports ────────────────────
+export { isQueryAction, setQueryKeywords, getQueryKeywords } from './utils/is-query';
+export { buildKey } from './utils/common';
+export { cacheGet, cacheSet, cacheDelete, cacheClear } from './utils/cache';
+export { dedupTrack, dedupClear } from './utils/dedup';
+export { loadingStart, loadingEnd, isLoading, onLoadingChange } from './utils/loading';
+export { idempotentGuard, idempotentClear } from './utils/idempotent';
+// ─── 默认实例 / Default Instance ────────────────────────────────
+import { DataHubCore } from './core';
+/** 默认 DataHub 实例，开箱即用 / Default DataHub instance, ready to use out of the box */
+export const dataHub = new DataHubCore();

package/dist/core/datahub/types.d.ts

@@ -78,6 +78,8 @@ export interface DataHubRequestOptions {
     mock?: boolean;
     /** Mock 返回的业务数据 / Mock business data to return */
     mockData?: unknown;
+    /** Mock JSON 文件路径，用于加载本地 mock 数据文件 / Mock JSON file path for loading local mock data files */
+    mockPath?: string;
     /** Mock 延迟时间（毫秒），模拟网络耗时，默认 300 / Mock delay in ms simulating network latency, default 300 */
     mockDelay?: number;
     /** 手动指定 traceId，不传则自动生成 / Manually specified traceId, auto-generated if omitted */
@@ -166,6 +168,8 @@ export interface DataHubErrorDetail {
     status?: number;
     /** 请求 URL / Request URL */
     url?: string;
+    /** 原始响应体 / Raw response body */
+    data?: unknown;
 }
 /**
  * DataHub 统一错误类 / DataHub Unified Error Class
@@ -184,6 +188,8 @@ export declare class DataHubError extends Error {
     readonly status?: number;
     /** 请求 URL / Request URL */
     readonly url?: string;
+    /** 原始响应体 / Raw response body */
+    readonly data?: unknown;
     constructor(detail: DataHubErrorDetail);
 }
 /**

package/dist/core/datahub/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/datahub/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/datahub/types.ts"],"names":[],"mappings":"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"}

package/dist/core/datahub/types.js

@@ -0,0 +1,31 @@
+/**
+ * @file DataHub 类型定义 / DataHub Type Definitions
+ * @description 定义 DataHub 数据中间层的所有标准类型，包括 APIStyle 业务协议相关类型。
+ *
+ *              核心设计原则：
+ *              - DataHub 只负责 HTTP 传输层（请求/响应），不关心业务协议
+ *              - 业务协议（如 code/message/data 结构）由 APIStyle 封装
+ *              - 适配器只做 JSON 解析，不做业务语义判断
+ *
+ *              Defines all standard types for the DataHub middleware layer,
+ *              including APIStyle business protocol types.
+ */
+/**
+ * DataHub 统一错误类 / DataHub Unified Error Class
+ * @description 封装网络错误、中断错误、HTTP 错误等，提供统一的错误结构。
+ *              包含错误码、链路追踪 ID、HTTP 状态码和请求 URL 等信息。
+ *              Encapsulates network errors, abort errors, HTTP errors, etc.,
+ *              providing a unified error structure with error code, trace ID,
+ *              HTTP status code, and request URL.
+ */
+export class DataHubError extends Error {
+    constructor(detail) {
+        super(detail.message);
+        this.name = 'DataHubError';
+        this.code = detail.code;
+        this.trace = detail.trace;
+        this.status = detail.status;
+        this.url = detail.url;
+        this.data = detail.data;
+    }
+}

package/dist/core/datahub/utils/cache.js

@@ -0,0 +1,55 @@
+/**
+ * @file 内存缓存工具 / In-Memory Cache Utility
+ * @description 为查询类请求提供基于 TTL（Time-To-Live）的内存缓存。
+ *              缓存键由 URL + 请求数据序列化生成，确保相同参数命中同一缓存。
+ *              过期条目在读取时惰性删除，无需定时清理。
+ *              Provides TTL (Time-To-Live) based in-memory caching for query requests.
+ *              Cache keys are generated from URL + serialized request data, ensuring identical
+ *              parameters hit the same cache entry. Expired entries are lazily evicted on read,
+ *              requiring no periodic cleanup.
+ */
+import { buildKey } from './common';
+/** 内存缓存存储，键为 "url::data" 序列化字符串 / In-memory store, keyed by "url::data" serialized string */
+const store = new Map();
+/**
+ * 读取缓存 / Read from cache
+ * @param url - 请求地址 / Request URL
+ * @param data - 请求体数据 / Request body data
+ * @returns 缓存命中返回数据，未命中或已过期返回 null / Cached data on hit, null on miss or expiration
+ */
+export function cacheGet(url, data) {
+    const key = buildKey(url, data);
+    const entry = store.get(key);
+    if (!entry)
+        return null;
+    // 惰性删除：已过期的条目在读取时清除 / Lazy eviction: expired entries are removed on read
+    if (Date.now() > entry.expireAt) {
+        store.delete(key);
+        return null;
+    }
+    return entry.data;
+}
+/**
+ * 写入缓存 / Write to cache
+ * @param url - 请求地址 / Request URL
+ * @param data - 请求体数据 / Request body data
+ * @param value - 要缓存的数据 / Data to cache
+ * @param ttl - 缓存有效期（毫秒）/ Cache TTL in milliseconds
+ */
+export function cacheSet(url, data, value, ttl) {
+    const key = buildKey(url, data);
+    store.set(key, { data: value, expireAt: Date.now() + ttl });
+}
+/**
+ * 删除指定缓存条目 / Delete a specific cache entry
+ * @param url - 请求地址 / Request URL
+ * @param data - 请求体数据 / Request body data
+ * @returns 是否成功删除 / Whether the entry was successfully deleted
+ */
+export function cacheDelete(url, data) {
+    return store.delete(buildKey(url, data));
+}
+/** 清空所有缓存 / Clear all cache entries */
+export function cacheClear() {
+    store.clear();
+}

package/dist/core/datahub/utils/common.js

@@ -0,0 +1,23 @@
+/**
+ * @file 公共工具函数 / Common Utility Functions
+ * @description 提供 DataHub 内部各模块共享的工具函数，
+ *              避免在 cache、dedup、idempotent 等模块中重复实现。
+ *              当前提供 buildKey 函数，用于生成标准化的缓存/去重/幂等键。
+ *              Provides shared utility functions for DataHub internal modules,
+ *              avoiding duplicate implementations across cache, dedup, idempotent, etc.
+ *              Currently provides buildKey for generating standardized cache/dedup/idempotent keys.
+ */
+/**
+ * 生成标准化的键 / Generate a standardized key
+ * @param url - 请求地址 / Request URL
+ * @param data - 请求体数据 / Request body data
+ * @returns 唯一键，格式为 "url::JSON(data)" / Unique key in format "url::JSON(data)"
+ * @description 用于缓存、去重、幂等防护等模块的键生成，
+ *              确保相同 URL + 相同数据命中同一键。
+ *              Used for key generation in cache, dedup, idempotent guard modules,
+ *              ensuring identical URL + data hit the same key.
+ */
+export function buildKey(url, data) {
+    const serialized = data === undefined ? 'null' : JSON.stringify(data);
+    return `${url}::${serialized}`;
+}

package/dist/core/datahub/utils/dedup.d.ts

@@ -22,7 +22,7 @@
  * ]);
  * // r1 === r2，共享同一结果 / r1 === r2, sharing the same result
  */
-export declare function dedupTrack<T>(url: string, data: unknown | undefined, factory: () => Promise<T>): Promise<T>;
+export declare function dedupTrack<T>(url: string, data: unknown, factory: () => Promise<T>): Promise<T>;
 /** 清空所有去重记录（一般用于测试或重置状态）/ Clear all dedup records (typically for testing or state reset) */
 export declare function dedupClear(): void;
 //# sourceMappingURL=dedup.d.ts.map