fi-pool-server 0.1.0

package/dist/tools/query.d.ts

@@ -0,0 +1,163 @@
+/**
+ * 查询类工具（Query）
+ *
+ * 封装面向用户的数据查询操作，直接返回数据而不包装在 data 中。
+ *
+ * @module tools/query
+ */
+/**
+ * 列出所有股池，附带每个股池中的股票数量。
+ *
+ * @returns 股池列表，每个元素包含 pool 全部字段和 stockCount
+ *
+ * @example
+ * const pools = await listPools();
+ * pools.forEach(p => console.log(p.name, p.stockCount));
+ */
+export declare function listPools(): Promise<{
+    id: number;
+    name: string;
+    desc: string;
+    poolAnalysis: string;
+    poolSignal: number;
+    createdAt: string;
+    updatedAt: string;
+    stockCount: number;
+}[]>;
+/**
+ * 查询指定股池中的所有股票详情。
+ *
+ * 返回包含股票代码、名称、当前价格以及加入时间的列表。
+ *
+ * @param poolId - 股池 ID
+ * @returns 股池中的股票列表
+ *
+ * @example
+ * const stocks = await getPoolStocks(1);
+ * stocks.forEach(s => console.log(s.code, s.name));
+ */
+export declare function getPoolStocks(poolId: number): Promise<{
+    code: string;
+    name: string;
+    currentPrice: number;
+    addedAt: string;
+}[]>;
+/**
+ * 查询股票基本信息。
+ *
+ * @param code - 六位股票代码（如 '600519'）
+ * @returns 股票对象，未找到时返回 null
+ *
+ * @example
+ * const info = await getStockInfo('600519');
+ * if (info) console.log(info.name, info.currentPrice);
+ */
+export declare function getStockInfo(code: string): Promise<{
+    name: string;
+    updatedAt: string;
+    code: string;
+    currentPrice: number;
+}>;
+/**
+ * 查询指定股票的日行情数据。
+ *
+ * 可选的日期范围过滤。
+ *
+ * @param code - 股票代码
+ * @param startDate - 可选起始日期 'yyyy-MM-dd'（含），不指定则不限制起始
+ * @param endDate - 可选结束日期 'yyyy-MM-dd'（含），不指定则不限制结束
+ * @returns 日行情数据数组（按日期升序）
+ *
+ * @example
+ * const data = await getDailyInfo('600519', '2024-05-01', '2024-06-01');
+ */
+export declare function getDailyInfo(code: string, startDate?: string, endDate?: string): Promise<{
+    date: string;
+    id: number;
+    code: string;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}[]>;
+/**
+ * 查询指定股票指定日期的客观分析报告。
+ *
+ * @param code - 股票代码
+ * @param date - 报告日期 'yyyy-MM-dd'
+ * @param mode - 输出模式：
+ *   - 'overview'：仅返回 id, code, date, summary 等摘要字段
+ *   - 'full'（默认）：返回完整报告字段（含 indicators, signals 等）
+ * @returns 分析报告对象，未找到时返回 null
+ *
+ * @example
+ * const report = await getAnalysisReport('600519', '2024-06-01', 'overview');
+ */
+export declare function getAnalysisReport(code: string, date: string, mode?: 'overview' | 'full'): Promise<{
+    date: string;
+    id: number;
+    createdAt: string;
+    code: string;
+    summary: string;
+    indicators: string;
+    signals: string;
+} | {
+    id: number;
+    code: string;
+    date: string;
+    summary: string;
+    createdAt: string;
+} | null>;
+/**
+ * 查询指定股票指定日期的最终报告。
+ *
+ * @param code - 股票代码
+ * @param date - 报告日期 'yyyy-MM-dd'
+ * @param mode - 输出模式：
+ *   - 'overview'：仅返回 id, code, date, summary, pipelineId 等摘要字段
+ *   - 'full'（默认）：返回完整报告字段（含 fullReport, roleSummary 等）
+ * @returns 最终报告对象，未找到时返回 null
+ *
+ * @example
+ * const report = await getFinalReport('600519', '2024-06-01', 'full');
+ */
+export declare function getFinalReport(code: string, date: string, mode?: 'overview' | 'full'): Promise<{
+    date: string;
+    id: number;
+    createdAt: string;
+    code: string;
+    summary: string;
+    fullReport: string;
+    roleSummary: string;
+    pipelineId: string;
+} | {
+    id: number;
+    code: string;
+    date: string;
+    summary: string;
+    pipelineId: string;
+    createdAt: string;
+} | null>;
+/**
+ * 查看系统运行状态。
+ *
+ * 收集版本号、数据库大小、股票/股池数量、最新数据时间、
+ * LLM 连接状态及服务运行时长等信息。
+ *
+ * @returns 系统状态对象
+ *
+ * @example
+ * const status = await getSystemStatus();
+ * console.log(status.version, status.llmConnected);
+ */
+export declare function getSystemStatus(): Promise<{
+    version: string;
+    dbSize: string;
+    stocksTracked: number;
+    poolsCount: number;
+    lastDataUpdate: string;
+    llmConnected: boolean;
+    uptime: number;
+}>;
+//# sourceMappingURL=query.d.ts.map

package/dist/tools/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/tools/query.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH;;;;;;;;GAQG;AACH,wBAAsB,SAAS;;;;;;;;;KAE9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM;;;;;KAEjD;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM;;;;;GAE9C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;;;;;;;;;KAEpF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,UAAU,GAAG,MAAe;;;;;;;;;;;;;;UA0BrG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,UAAU,GAAG,MAAe;;;;;;;;;;;;;;;;UA2BlG;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe;;;;;;;;GAyCpC"}

package/dist/tools/query.js

@@ -0,0 +1,190 @@
+/**
+ * 查询类工具（Query）
+ *
+ * 封装面向用户的数据查询操作，直接返回数据而不包装在 data 中。
+ *
+ * @module tools/query
+ */
+import * as poolService from '../services/pool.js';
+import * as stockService from '../services/stock.js';
+import * as dailyInfoService from '../services/daily-info.js';
+import * as llmService from '../services/llm.js';
+import { getDatabase, getDbPath } from '../db/index.js';
+import { dailyAnalysisReport, finalReport, stock, pool } from '../db/schema.js';
+import { eq, and, sql } from 'drizzle-orm';
+import { VERSION } from '../index.js';
+import { existsSync, statSync } from 'fs';
+import { resolve } from 'path';
+/**
+ * 列出所有股池，附带每个股池中的股票数量。
+ *
+ * @returns 股池列表，每个元素包含 pool 全部字段和 stockCount
+ *
+ * @example
+ * const pools = await listPools();
+ * pools.forEach(p => console.log(p.name, p.stockCount));
+ */
+export async function listPools() {
+    return poolService.listPools();
+}
+/**
+ * 查询指定股池中的所有股票详情。
+ *
+ * 返回包含股票代码、名称、当前价格以及加入时间的列表。
+ *
+ * @param poolId - 股池 ID
+ * @returns 股池中的股票列表
+ *
+ * @example
+ * const stocks = await getPoolStocks(1);
+ * stocks.forEach(s => console.log(s.code, s.name));
+ */
+export async function getPoolStocks(poolId) {
+    return poolService.getPoolStocks(poolId);
+}
+/**
+ * 查询股票基本信息。
+ *
+ * @param code - 六位股票代码（如 '600519'）
+ * @returns 股票对象，未找到时返回 null
+ *
+ * @example
+ * const info = await getStockInfo('600519');
+ * if (info) console.log(info.name, info.currentPrice);
+ */
+export async function getStockInfo(code) {
+    return stockService.getStockByCode(code);
+}
+/**
+ * 查询指定股票的日行情数据。
+ *
+ * 可选的日期范围过滤。
+ *
+ * @param code - 股票代码
+ * @param startDate - 可选起始日期 'yyyy-MM-dd'（含），不指定则不限制起始
+ * @param endDate - 可选结束日期 'yyyy-MM-dd'（含），不指定则不限制结束
+ * @returns 日行情数据数组（按日期升序）
+ *
+ * @example
+ * const data = await getDailyInfo('600519', '2024-05-01', '2024-06-01');
+ */
+export async function getDailyInfo(code, startDate, endDate) {
+    return dailyInfoService.getDailyInfo(code, startDate, endDate);
+}
+/**
+ * 查询指定股票指定日期的客观分析报告。
+ *
+ * @param code - 股票代码
+ * @param date - 报告日期 'yyyy-MM-dd'
+ * @param mode - 输出模式：
+ *   - 'overview'：仅返回 id, code, date, summary 等摘要字段
+ *   - 'full'（默认）：返回完整报告字段（含 indicators, signals 等）
+ * @returns 分析报告对象，未找到时返回 null
+ *
+ * @example
+ * const report = await getAnalysisReport('600519', '2024-06-01', 'overview');
+ */
+export async function getAnalysisReport(code, date, mode = 'full') {
+    const db = getDatabase();
+    const row = db
+        .select()
+        .from(dailyAnalysisReport)
+        .where(and(eq(dailyAnalysisReport.code, code), eq(dailyAnalysisReport.date, date)))
+        .get();
+    if (!row)
+        return null;
+    if (mode === 'overview') {
+        return {
+            id: row.id,
+            code: row.code,
+            date: row.date,
+            summary: row.summary,
+            createdAt: row.createdAt,
+        };
+    }
+    return row;
+}
+/**
+ * 查询指定股票指定日期的最终报告。
+ *
+ * @param code - 股票代码
+ * @param date - 报告日期 'yyyy-MM-dd'
+ * @param mode - 输出模式：
+ *   - 'overview'：仅返回 id, code, date, summary, pipelineId 等摘要字段
+ *   - 'full'（默认）：返回完整报告字段（含 fullReport, roleSummary 等）
+ * @returns 最终报告对象，未找到时返回 null
+ *
+ * @example
+ * const report = await getFinalReport('600519', '2024-06-01', 'full');
+ */
+export async function getFinalReport(code, date, mode = 'full') {
+    const db = getDatabase();
+    const row = db
+        .select()
+        .from(finalReport)
+        .where(and(eq(finalReport.code, code), eq(finalReport.date, date)))
+        .get();
+    if (!row)
+        return null;
+    if (mode === 'overview') {
+        return {
+            id: row.id,
+            code: row.code,
+            date: row.date,
+            summary: row.summary,
+            pipelineId: row.pipelineId,
+            createdAt: row.createdAt,
+        };
+    }
+    return row;
+}
+/**
+ * 查看系统运行状态。
+ *
+ * 收集版本号、数据库大小、股票/股池数量、最新数据时间、
+ * LLM 连接状态及服务运行时长等信息。
+ *
+ * @returns 系统状态对象
+ *
+ * @example
+ * const status = await getSystemStatus();
+ * console.log(status.version, status.llmConnected);
+ */
+export async function getSystemStatus() {
+    const db = getDatabase();
+    // 统计股票数量
+    const stockCount = db.select({ count: sql `count(*)` }).from(stock).get()?.count ?? 0;
+    // 统计股池数量
+    const poolCount = db.select({ count: sql `count(*)` }).from(pool).get()?.count ?? 0;
+    // 获取最新行情更新时间
+    const latestDaily = db
+        .select({ maxDate: sql `max(${dailyAnalysisReport.date})` })
+        .from(dailyAnalysisReport)
+        .get();
+    // 数据库文件大小
+    let dbSize = '未知';
+    try {
+        const dbPath = resolve(getDbPath());
+        if (existsSync(dbPath)) {
+            const bytes = statSync(dbPath).size;
+            dbSize = bytes < 1024 * 1024
+                ? `${(bytes / 1024).toFixed(1)} KB`
+                : `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+        }
+    }
+    catch {
+        // 忽略文件大小错误
+    }
+    // 检查 LLM 连接
+    const llmConnected = await llmService.checkConnection().catch(() => false);
+    return {
+        version: VERSION,
+        dbSize,
+        stocksTracked: stockCount,
+        poolsCount: poolCount,
+        lastDataUpdate: latestDaily?.maxDate || '无数据',
+        llmConnected,
+        uptime: Math.floor(process.uptime()),
+    };
+}
+//# sourceMappingURL=query.js.map

package/dist/tools/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/tools/query.ts"],"names":[],"mappings":"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"}

package/dist/utils/http-client.d.ts

@@ -0,0 +1,87 @@
+/**
+ * HTTP 客户端工具模块
+ *
+ * 基于 Node.js 内置 fetch（Node 22+），提供带超时控制、
+ * 错误处理和重试机制的 HTTP 请求封装。
+ *
+ * @module http-client
+ */
+/**
+ * HTTP 请求错误
+ *
+ * 当服务端返回非 2xx 状态码时抛出，包含状态码、状态文本和响应体。
+ */
+export declare class HttpError extends Error {
+    /** HTTP 状态码 */
+    readonly status: number;
+    /** HTTP 状态文本 */
+    readonly statusText: string;
+    /** 响应体文本 */
+    readonly body: string;
+    constructor(status: number, statusText: string, body: string);
+}
+/**
+ * 发起 HTTP 请求并解析响应为 JSON
+ *
+ * @typeParam T    - 期望的 JSON 数据类型
+ * @param url     - 请求 URL
+ * @param options - 可选的 fetch 选项（method、headers、body 等）
+ * @param signal  - 可选的 AbortSignal，用于外部控制中止
+ * @param timeout - 超时毫秒数，默认 15s
+ * @returns 解析后的 JSON 数据
+ *
+ * @example
+ * ```typescript
+ * const data = await fetchJson<{ code: string; price: number }>(
+ *   'https://api.example.com/stock/600519'
+ * );
+ * ```
+ *
+ * @throws {HttpError}  当响应状态码非 2xx 时
+ * @throws {AbortError} 当请求超时或被中止时
+ * @throws {SyntaxError} 当响应体不是合法 JSON 时
+ */
+export declare function fetchJson<T>(url: string, options?: RequestInit, signal?: AbortSignal, timeout?: number): Promise<T>;
+/**
+ * 发起 HTTP 请求并获取原始文本
+ *
+ * @param url     - 请求 URL
+ * @param options - 可选的 fetch 选项（method、headers、body 等）
+ * @param signal  - 可选的 AbortSignal，用于外部控制中止
+ * @param timeout - 超时毫秒数，默认 15s
+ * @returns 响应文本
+ *
+ * @example
+ * ```typescript
+ * const html = await fetchText('https://example.com');
+ * ```
+ *
+ * @throws {HttpError}  当响应状态码非 2xx 时
+ * @throws {AbortError} 当请求超时或被中止时
+ */
+export declare function fetchText(url: string, options?: RequestInit, signal?: AbortSignal, timeout?: number): Promise<string>;
+/**
+ * 带退避重试机制的异步函数执行器
+ *
+ * 对传入的异步函数进行重试，仅在遇到可重试错误
+ *（网络异常或服务端 5xx 状态码）时触发。
+ * 重试间隔恒定（非指数退避），适用于高频数据轮询场景。
+ *
+ * @param fn      - 要执行的异步函数（通常是 fetch 调用）
+ * @param retries - 最大重试次数，默认 2（共执行 1 + retries = 3 次）
+ * @param delay   - 每次重试前的等待时间（毫秒），默认 1000
+ * @returns 函数执行结果
+ *
+ * @example
+ * ```typescript
+ * const data = await fetchWithRetry(
+ *   () => fetchJson<StockData>('https://api.example.com/stock'),
+ *   3,   // 最多重试 3 次
+ *   500  // 间隔 500ms
+ * );
+ * ```
+ *
+ * @throws 最后一次尝试抛出的原始错误（非可重试错误直接透传）
+ */
+export declare function fetchWithRetry<T>(fn: () => Promise<T>, retries?: number, delay?: number): Promise<T>;
+//# sourceMappingURL=http-client.d.ts.map

package/dist/utils/http-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../../src/utils/http-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,eAAe;IACf,SAAgB,MAAM,EAAE,MAAM,CAAC;IAE/B,gBAAgB;IAChB,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC,YAAY;IACZ,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEjB,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAO7D;AAgED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CASzH;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG3H;AA2BD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,MAAwB,EACjC,KAAK,GAAE,MAA+B,GACrC,OAAO,CAAC,CAAC,CAAC,CAqBZ"}

package/dist/utils/http-client.js

@@ -0,0 +1,211 @@
+/**
+ * HTTP 客户端工具模块
+ *
+ * 基于 Node.js 内置 fetch（Node 22+），提供带超时控制、
+ * 错误处理和重试机制的 HTTP 请求封装。
+ *
+ * @module http-client
+ */
+// ─── 常量 ─────────────────────────────────────────────────────
+/** 默认请求超时时间（毫秒） */
+const DEFAULT_TIMEOUT_MS = 15_000;
+/** 默认最大重试次数 */
+const DEFAULT_RETRIES = 2;
+/** 默认重试间隔（毫秒） */
+const DEFAULT_RETRY_DELAY_MS = 1_000;
+// ─── 错误类型 ─────────────────────────────────────────────────
+/**
+ * HTTP 请求错误
+ *
+ * 当服务端返回非 2xx 状态码时抛出，包含状态码、状态文本和响应体。
+ */
+export class HttpError extends Error {
+    /** HTTP 状态码 */
+    status;
+    /** HTTP 状态文本 */
+    statusText;
+    /** 响应体文本 */
+    body;
+    constructor(status, statusText, body) {
+        super(`HTTP ${status} ${statusText}`);
+        this.name = 'HttpError';
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+    }
+}
+// ─── 底层请求函数 ─────────────────────────────────────────────
+/**
+ * 核心请求函数：发起 HTTP 请求并返回 Response
+ *
+ * 内置超时控制，超时时抛出 AbortError。
+ *
+ * @param url     - 请求 URL
+ * @param options - fetch 选项（method、headers、body 等）
+ * @param signal  - 外部 AbortSignal（可与内部超时同时生效）
+ * @param timeout - 超时毫秒数，默认 DEFAULT_TIMEOUT_MS
+ * @returns Response 对象
+ * @throws {HttpError}  当响应状态码非 2xx 时
+ * @throws {AbortError} 当请求超时或被外部中止时
+ */
+async function request(url, options, signal, timeout) {
+    const effectiveTimeout = timeout ?? DEFAULT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), effectiveTimeout);
+    try {
+        const combinedSignal = signal
+            ? combineAbortSignals(signal, controller.signal)
+            : controller.signal;
+        const fetchOptions = {
+            ...options,
+            signal: combinedSignal,
+        };
+        const response = await fetch(url, fetchOptions);
+        if (!response.ok) {
+            const body = await response.text();
+            throw new HttpError(response.status, response.statusText, body);
+        }
+        return response;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * 合并两个 AbortSignal，任一 signal 中止则合并后的 signal 中止
+ */
+function combineAbortSignals(...signals) {
+    const controller = new AbortController();
+    for (const sig of signals) {
+        if (sig.aborted) {
+            controller.abort(sig.reason);
+            return controller.signal;
+        }
+        sig.addEventListener('abort', () => controller.abort(sig.reason), { once: true });
+    }
+    return controller.signal;
+}
+// ─── 公开函数 ─────────────────────────────────────────────────
+/**
+ * 发起 HTTP 请求并解析响应为 JSON
+ *
+ * @typeParam T    - 期望的 JSON 数据类型
+ * @param url     - 请求 URL
+ * @param options - 可选的 fetch 选项（method、headers、body 等）
+ * @param signal  - 可选的 AbortSignal，用于外部控制中止
+ * @param timeout - 超时毫秒数，默认 15s
+ * @returns 解析后的 JSON 数据
+ *
+ * @example
+ * ```typescript
+ * const data = await fetchJson<{ code: string; price: number }>(
+ *   'https://api.example.com/stock/600519'
+ * );
+ * ```
+ *
+ * @throws {HttpError}  当响应状态码非 2xx 时
+ * @throws {AbortError} 当请求超时或被中止时
+ * @throws {SyntaxError} 当响应体不是合法 JSON 时
+ */
+export async function fetchJson(url, options, signal, timeout) {
+    const response = await request(url, options, signal, timeout);
+    const text = await response.text();
+    if (text.length === 0) {
+        throw new SyntaxError('响应体为空，无法解析为 JSON');
+    }
+    return JSON.parse(text);
+}
+/**
+ * 发起 HTTP 请求并获取原始文本
+ *
+ * @param url     - 请求 URL
+ * @param options - 可选的 fetch 选项（method、headers、body 等）
+ * @param signal  - 可选的 AbortSignal，用于外部控制中止
+ * @param timeout - 超时毫秒数，默认 15s
+ * @returns 响应文本
+ *
+ * @example
+ * ```typescript
+ * const html = await fetchText('https://example.com');
+ * ```
+ *
+ * @throws {HttpError}  当响应状态码非 2xx 时
+ * @throws {AbortError} 当请求超时或被中止时
+ */
+export async function fetchText(url, options, signal, timeout) {
+    const response = await request(url, options, signal, timeout);
+    return response.text();
+}
+/**
+ * 判断一个错误是否应该触发重试
+ *
+ * 重试条件：
+ * - 网络错误（TypeError）
+ * - 服务端错误（HTTP 5xx）
+ *
+ * @param error - 捕获的异常
+ * @returns 是否应重试
+ */
+function isRetryableError(error) {
+    if (error instanceof TypeError) {
+        // TypeError 通常表示网络层面错误（DNS 解析失败、连接重置等）
+        return true;
+    }
+    if (error instanceof HttpError) {
+        // 5xx 服务端错误可以重试
+        return error.status >= 500 && error.status < 600;
+    }
+    // 非 HttpError 或 TypeError 的错误（如 JSON 解析错误）不重试
+    return false;
+}
+/**
+ * 带退避重试机制的异步函数执行器
+ *
+ * 对传入的异步函数进行重试，仅在遇到可重试错误
+ *（网络异常或服务端 5xx 状态码）时触发。
+ * 重试间隔恒定（非指数退避），适用于高频数据轮询场景。
+ *
+ * @param fn      - 要执行的异步函数（通常是 fetch 调用）
+ * @param retries - 最大重试次数，默认 2（共执行 1 + retries = 3 次）
+ * @param delay   - 每次重试前的等待时间（毫秒），默认 1000
+ * @returns 函数执行结果
+ *
+ * @example
+ * ```typescript
+ * const data = await fetchWithRetry(
+ *   () => fetchJson<StockData>('https://api.example.com/stock'),
+ *   3,   // 最多重试 3 次
+ *   500  // 间隔 500ms
+ * );
+ * ```
+ *
+ * @throws 最后一次尝试抛出的原始错误（非可重试错误直接透传）
+ */
+export async function fetchWithRetry(fn, retries = DEFAULT_RETRIES, delay = DEFAULT_RETRY_DELAY_MS) {
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < retries && isRetryableError(error)) {
+                await sleep(delay);
+                continue;
+            }
+            // 非可重试错误或已达最大重试次数，直接抛出
+            throw error;
+        }
+    }
+    // TypeScript 控制流无法推断此处不可达，显式抛出
+    throw lastError;
+}
+/**
+ * 延迟函数
+ *
+ * @param ms - 等待毫秒数
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=http-client.js.map

package/dist/utils/http-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.js","sourceRoot":"","sources":["../../src/utils/http-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+DAA+D;AAE/D,mBAAmB;AACnB,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC,eAAe;AACf,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B,iBAAiB;AACjB,MAAM,sBAAsB,GAAG,KAAK,CAAC;AAErC,6DAA6D;AAE7D;;;;GAIG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,eAAe;IACC,MAAM,CAAS;IAE/B,gBAAgB;IACA,UAAU,CAAS;IAEnC,YAAY;IACI,IAAI,CAAS;IAE7B,YAAY,MAAc,EAAE,UAAkB,EAAE,IAAY;QAC1D,KAAK,CAAC,QAAQ,MAAM,IAAI,UAAU,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,2DAA2D;AAE3D;;;;;;;;;;;;GAYG;AACH,KAAK,UAAU,OAAO,CAAC,GAAW,EAAE,OAAqB,EAAE,MAAoB,EAAE,OAAgB;IAC/F,MAAM,gBAAgB,GAAG,OAAO,IAAI,kBAAkB,CAAC;IACvD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,gBAAgB,CAAC,CAAC;IAEzE,IAAI,CAAC;QACH,MAAM,cAAc,GAAG,MAAM;YAC3B,CAAC,CAAC,mBAAmB,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC;YAChD,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;QAEtB,MAAM,YAAY,GAAgB;YAChC,GAAG,OAAO;YACV,MAAM,EAAE,cAAc;SACvB,CAAC;QAEF,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QAEhD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAClE,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,SAAS,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,mBAAmB,CAAC,GAAG,OAAsB;IACpD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IAEzC,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YAChB,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC7B,OAAO,UAAU,CAAC,MAAM,CAAC;QAC3B,CAAC;QACD,GAAG,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,OAAO,UAAU,CAAC,MAAM,CAAC;AAC3B,CAAC;AAED,6DAA6D;AAE7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,GAAW,EAAE,OAAqB,EAAE,MAAoB,EAAE,OAAgB;IAC3G,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAEnC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,WAAW,CAAC,kBAAkB,CAAC,CAAC;IAC5C,CAAC;IAED,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW,EAAE,OAAqB,EAAE,MAAoB,EAAE,OAAgB;IACxG,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9D,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;AACzB,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,gBAAgB,CAAC,KAAc;IACtC,IAAI,KAAK,YAAY,SAAS,EAAE,CAAC;QAC/B,uCAAuC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,KAAK,YAAY,SAAS,EAAE,CAAC;QAC/B,gBAAgB;QAChB,OAAO,KAAK,CAAC,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC;IACnD,CAAC;IAED,8CAA8C;IAC9C,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAoB,EACpB,UAAkB,eAAe,EACjC,QAAgB,sBAAsB;IAEtC,IAAI,SAAkB,CAAC;IAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,SAAS,GAAG,KAAK,CAAC;YAElB,IAAI,OAAO,GAAG,OAAO,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjD,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;gBACnB,SAAS;YACX,CAAC;YAED,uBAAuB;YACvB,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,+BAA+B;IAC/B,MAAM,SAAS,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}