@quantlife/qlchart 0.0.1

package/src/components/QLChartPanel.tsx

@@ -0,0 +1,560 @@
+import { useEffect, useState, useCallback, useRef, forwardRef, useImperativeHandle } from 'react';
+import { useChart } from '../hooks/useChart.js';
+import { useTheme } from '../hooks/useTheme.js';
+import { useChartStore, selectPanelPeriod } from '../store/useChartStore.js';
+import { useIndicatorStore } from '../store/useIndicatorStore.js';
+import { useQLChartConfig } from './QLChartProvider.js';
+import { transformCandlestickData, transformVolumeData, transformVolumeCandlestickData } from '../utils/dataTransformer.js';
+import { generateFutureWhitespace } from '../utils/timeScaleUtils.js';
+import { transformToHeikinAshi } from '../utils/heikinAshi.js';
+import { transformToLineBreak } from '../utils/lineBreak.js';
+import { SeriesType } from '../types/index.js';
+import type { CandlestickRawData } from '../types/index.js';
+import { QLToolbar } from './toolbar/QLToolbar.js';
+import { IndicatorRenderer } from '../plugins/indicators/IndicatorRenderer.js';
+import { IndicatorTag } from './indicator/IndicatorTag.js';
+import { MockIndicatorService } from '../mock/MockIndicatorService.js';
+import { DrawingPropertyPanel } from './drawing/DrawingPropertyPanel.js';
+import { ChartContextMenu } from './context-menu/ChartContextMenu.js';
+import { ChartFunctionMenu } from './ChartFunctionMenu.js';
+import { useDrawingModule } from '../hooks/useDrawingModule.js';
+import { DrawingModule } from './drawing/DrawingModule.js';
+import type { IChartApi, ISeriesApi, SeriesType as LWCSeriesType } from 'lightweight-charts';
+import { useDrawingStore } from '../store/useDrawingStore.js';
+import { RealtimeDataFeed, type RealtimeCandle } from '../core/RealtimeDataFeed.js';
+import { DataManager } from '../core/DataManager.js';
+
+import '../styles/chart.css';
+import '../styles/toolbar.css';
+import '../styles/drawing.css';
+import '../styles/context-menu.css';
+import '../styles/indicator-modal.css';
+import '../styles/themes/dark.css';
+import '../styles/themes/light.css';
+import '../styles/responsive.css';
+import '../styles/pane-chart.css';
+import '../styles/components.css';
+
+export interface QLChartPanelProps {
+  pairId: string;
+  product: string;
+  period?: string;
+  seriesType?: SeriesType;
+  showToolbar?: boolean;
+  panelId?: string;
+  panelIndex?: number;
+  onChartCreated?: (chart: IChartApi | null, index: number) => void;
+  /** chart 和 series 就绪回调 */
+  onChartReady?: (chart: IChartApi | null, mainSeries: ISeriesApi<LWCSeriesType> | null) => void;
+  /** 是否为单面板模式（控制绘图UI渲染位置） */
+  isSinglePanel?: boolean;
+}
+
+/** ★ Req1：QLChartPanel 暴露的命令式API */
+export interface QLChartPanelRef {
+  /** 推送实时K线数据（增量更新） */
+  pushRealtimeData: (data: RealtimeCandle) => void;
+  /** 批量推送实时数据 */
+  pushRealtimeBatch: (datas: RealtimeCandle[]) => void;
+  /** 重载数据 */
+  reload: () => void;
+  /** 获取chart实例 */
+  getChart: () => IChartApi | null;
+  /** 获取主序列 */
+  getMainSeries: () => ISeriesApi<LWCSeriesType> | null;
+  /** 清除缓存 */
+  clearCache: () => void;
+}
+
+
+
+export const QLChartPanel = forwardRef<QLChartPanelRef, QLChartPanelProps>(
+  function QLChartPanel({
+    pairId,
+    product,
+    period = '1h',
+    seriesType,
+    showToolbar = true,
+    panelId,
+    panelIndex,
+    onChartCreated,
+    onChartReady,
+    isSinglePanel = true,
+  }, ref) {
+  const { containerRef, chartManager, seriesManager } = useChart();
+  const { config: themeConfig, theme, setTheme } = useTheme();
+  const config = useQLChartConfig();
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // ★ Req1：DataManager 和 RealtimeDataFeed refs
+  const dataManagerRef = useRef<DataManager | null>(null);
+  const realtimeFeedRef = useRef<RealtimeDataFeed | null>(null);
+  // ★ Req1：保存 volumeSeriesId 以便 RealtimeDataFeed 获取引用
+  const volumeSeriesIdRef = useRef<string | null>(null);
+
+  // ★ Req1：初始化 DataManager
+  useEffect(() => {
+    if (config.cacheEnabled !== false && config.fetchFn) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const dm = new DataManager(config.fetchFn as any);
+      if (config.cacheTTL) dm.setCacheTTL(config.cacheTTL);
+      dataManagerRef.current = dm;
+    }
+    return () => { dataManagerRef.current = null; };
+  }, [config.cacheEnabled, config.cacheTTL, config.fetchFn]);
+
+  // ★ Req1：暴露命令式API
+  useImperativeHandle(ref, () => ({
+    pushRealtimeData: (data: RealtimeCandle) => {
+      realtimeFeedRef.current?.push(data);
+    },
+    pushRealtimeBatch: (datas: RealtimeCandle[]) => {
+      realtimeFeedRef.current?.pushBatch(datas);
+    },
+    reload: () => loadData(),
+    getChart: () => chartManager?.getChart() ?? null,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getMainSeries: () => seriesManager?.getFirstMainSeries() as any ?? null,
+    clearCache: () => dataManagerRef.current?.clearCache(),
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }), [chartManager, seriesManager]);
+
+  // 同步 defaultTheme 到 zustand store
+  useEffect(() => {
+    if (config.defaultTheme && config.defaultTheme !== theme) {
+      setTheme(config.defaultTheme);
+    }
+  }, [config.defaultTheme, theme, setTheme]);
+
+  const activePeriod = useChartStore((s) => s.activePeriod);
+  const panelPeriod = useChartStore(selectPanelPeriod(panelId));
+  const setPanelPeriod = useChartStore((s) => s.setPanelPeriod);
+  const activeSeriesType = useChartStore((s) => s.activeSeriesType);
+
+  // period prop 同步到 store（仅 period prop 变化时触发）
+  useEffect(() => {
+    if (period && period !== activePeriod) {
+      // 多面板模式：写入面板级状态
+      if (panelId) {
+        setPanelPeriod(panelId, period);
+      } else {
+        useChartStore.getState().setPeriod(period);
+      }
+    }
+  }, [period]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // period prop 初始化到面板级状态（仅首次）
+  useEffect(() => {
+    if (panelId && period) {
+      const current = useChartStore.getState().panelPeriods[panelId];
+      if (!current) {
+        setPanelPeriod(panelId, period);
+      }
+    }
+  }, [panelId]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // currentPeriod 统一从面板级状态取值
+  const currentPeriod = panelPeriod || period || '1h';
+  const currentSeriesType = seriesType ?? activeSeriesType;
+
+  // Theme: set data-theme attribute on container
+  useEffect(() => {
+    const container = containerRef.current?.closest('.qlchart-container');
+    if (container) {
+      container.setAttribute('data-theme', theme);
+    }
+  }, [theme]);
+
+  // Theme update: apply chart options without reloading data
+  useEffect(() => {
+    if (!chartManager) return;
+    chartManager.updateOptions(themeConfig.chart);
+  }, [chartManager, themeConfig]);
+
+  // Track whether data has been loaded (series exist)
+  const [dataLoaded, setDataLoaded] = useState(false);
+
+  // ★ F1: loadData generation 序列号 — 丢弃过期异步结果，消除竞态
+  const loadGenerationRef = useRef(0);
+
+  // Indicator integration
+  const rendererRef = useRef<IndicatorRenderer | null>(null);
+  const activeIndicators = useIndicatorStore((s) => s.activeIndicators);
+  const setIndicatorData = useIndicatorStore((s) => s.setIndicatorData);
+  const prevIndicatorIdsRef = useRef<string>('');
+
+  // ★ 绘图模块 Hook
+  const {
+    drawingAdapterRef,
+    recentTools,
+    handleDrawingStyleChange,
+    handleDeleteDrawing,
+    handleContextMenuToolSelect,
+  } = useDrawingModule({
+    chartManager,
+    seriesManager,
+    containerRef,
+    pairId,
+    product,
+    period: currentPeriod,
+    panelId,
+    panelIndex,
+    onChartCreated,
+    dataLoaded,
+    indicatorRendererRef: rendererRef,  // ★ V4 需求1: 传 ref 桥接副图绘图
+  });
+
+  const selectedDrawingId = useDrawingStore((s) => s.selectedDrawingId);
+
+  const loadData = useCallback(async () => {
+    if (!chartManager || !seriesManager || !config.fetchFn) return;
+
+    const chart = chartManager.getChart();
+    if (!chart) return;
+
+    // ★ F1: 递增 generation，使前一次 loadData 的 continuation 作废
+    const myGeneration = ++loadGenerationRef.current;
+
+    setLoading(true);
+    setError(null);
+    setDataLoaded(false);
+
+    try {
+      // 清除旧序列
+      seriesManager.clearAll();
+
+      // 初始化 IndicatorRenderer
+      const renderer = new IndicatorRenderer();
+      renderer.setChart(chart);
+      renderer.setSeriesManager(seriesManager);
+      rendererRef.current = renderer;
+
+      // ★ Req1：通过 DataManager 获取数据（自动缓存），如果没有则回退到直接调用 fetchFn
+      const fetcher = dataManagerRef.current;
+      const result = (fetcher
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ? await fetcher.fetchChartData({ pairId, product, period: currentPeriod } as any)
+        : await config.fetchFn({ pairId, product, period: currentPeriod })) as { data?: CandlestickRawData[] };
+
+      // ★ F1: 检查 generation — 如果不是最新调用，丢弃过期结果
+      if (myGeneration !== loadGenerationRef.current) {
+        console.log('[QLChartPanel] loadData generation expired, discarding result', { myGeneration, current: loadGenerationRef.current });
+        return;
+      }
+
+      if (!result?.data || !Array.isArray(result.data)) {
+        throw new Error('Invalid data format');
+      }
+
+      const candlestickData = transformCandlestickData(result.data);
+      const volumeData = transformVolumeData(result.data);
+
+      // 添加主序列
+      const mainSeries = seriesManager.addMainSeries(currentSeriesType, {
+        upColor: themeConfig.upColor,
+        downColor: themeConfig.downColor,
+        borderDownColor: themeConfig.downColor,
+        borderUpColor: themeConfig.upColor,
+        wickDownColor: themeConfig.downColor,
+        wickUpColor: themeConfig.upColor,
+      });
+
+      if (mainSeries && candlestickData.length > 0) {
+        // ★ F2/F7: K线类型数据预处理 + whitespace注入
+        let displayData: any[] = [...candlestickData];
+
+        switch (currentSeriesType) {
+          case SeriesType.HeikinAshi:
+            displayData = transformToHeikinAshi(displayData);
+            break;
+          case SeriesType.LineBreak:
+            displayData = transformToLineBreak(displayData, 3);
+            break;
+          case SeriesType.VolumeCandlestick:
+            displayData = transformVolumeCandlestickData(result.data);
+            break;
+          // 其他类型直接使用原始 candlestickData
+        }
+
+        // 注入未来 whitespace 时间点
+        const lastTime = displayData[displayData.length - 1].time as number;
+        const futureWhitespace = generateFutureWhitespace(lastTime, currentPeriod, 100);
+        const combinedData: any[] = [...displayData, ...futureWhitespace];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (mainSeries as any).setData(combinedData);
+      }
+
+      // 添加成交量序列
+      const volumeSeries = seriesManager.addOverlaySeries(
+        SeriesType.Histogram,
+        {
+          color: 'rgba(38, 166, 154, 0.35)',
+          priceFormat: { type: 'volume' },
+        },
+        'volume',
+      );
+      // ★ Req1：保存 volumeSeriesId
+      volumeSeriesIdRef.current = volumeSeries as unknown as string | null;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const volumeSeriesApi = volumeSeries as any;
+
+      if (volumeSeries && volumeData.length > 0) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        volumeSeriesApi.setData(volumeData);
+        chart.priceScale('volume').applyOptions({
+          scaleMargins: { top: 0.8, bottom: 0 },
+          borderVisible: false,
+          textColor: 'rgba(209, 212, 220, 0.3)',
+        });
+      }
+
+      // ★ F3: 替换 fitContent — 避免whitespace拉宽初始视图，精确控制可见范围
+      const totalDataBars = candlestickData.length;
+      const visibleBars = 80;
+      const futurePreviewBars = 15;
+      chart.timeScale().setVisibleLogicalRange({
+        from: Math.max(0, totalDataBars - visibleBars),
+        to: totalDataBars + futurePreviewBars,
+      });
+
+      // Pass candle data to DrawingAdapter for magnet snap
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      drawingAdapterRef.current?.setCandleData(candlestickData as any);
+
+      // 数据重载后，更新DrawingAdapter的series引用（防御性修复：clearAll后series引用过期）
+      if (drawingAdapterRef.current && mainSeries) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        drawingAdapterRef.current.updateSeries(mainSeries as any);
+      }
+
+      // ★ F1: 再次检查 generation — 防止 addMainSeries 后被另一个 loadData 超越
+      if (myGeneration !== loadGenerationRef.current) {
+        console.log('[QLChartPanel] loadData generation expired after addMainSeries, discarding', { myGeneration, current: loadGenerationRef.current });
+        return;
+      }
+
+      setDataLoaded(true);
+
+      // ★ Req1：数据加载完成后初始化 RealtimeDataFeed
+      if (mainSeries) {
+        const feed = new RealtimeDataFeed();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        feed.attach(mainSeries as any, volumeSeriesApi ?? null);
+        realtimeFeedRef.current = feed;
+      }
+
+      // ★ 任务3-2.1：DataManager 绑定到 chart — 启用拖动加载 + 定时获取
+      const dm = dataManagerRef.current;
+      const chartApi = chartManager.getChart();
+      if (dm && chartApi && mainSeries) {
+        // 同步全量数据到 DataManager
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        dm.setAllData(candlestickData as any);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        dm.attachToChart(chartApi, mainSeries as any, {
+          pairId,
+          product,
+          period: currentPeriod,
+        });
+        // 启动定时获取（默认5秒）
+        dm.startRealtimeFetch(5000);
+      }
+
+      // chart 和 series 就绪回调
+      if (onChartReady) {
+        onChartReady(chart, mainSeries as ISeriesApi<LWCSeriesType> || null);
+      }
+    } catch (err) {
+      // ★ F1: 过期调用的错误也不处理
+      if (myGeneration !== loadGenerationRef.current) return;
+
+      const msg = err instanceof Error ? err.message : 'Failed to load chart data';
+      setError(msg);
+      console.error('[QLChartPanel]', err);
+    } finally {
+      // ★ F1: 只有最新 generation 才更新 loading 状态
+      if (myGeneration === loadGenerationRef.current) {
+        setLoading(false);
+      }
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [chartManager, seriesManager, config.fetchFn, pairId, product, currentPeriod, currentSeriesType]);
+
+  // 数据加载
+  useEffect(() => {
+    loadData();
+  }, [loadData]);
+
+  // ★ 任务3-2.1：DataManager detach 清理（period 变化或组件卸载时）
+  useEffect(() => {
+    return () => {
+      dataManagerRef.current?.detach();
+    };
+  }, [currentPeriod]);
+
+  // ★ Req1：注册外部实时数据回调
+  useEffect(() => {
+    if (!dataLoaded || !config.realtimeSubscribe) return;
+
+    const result = config.realtimeSubscribe({
+      pairId,
+      product,
+      period: currentPeriod,
+      onUpdate: (data) => realtimeFeedRef.current?.push(data),
+    });
+
+    // 返回 unsubscribe
+    if (typeof result === 'function') {
+      return result;
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [dataLoaded, pairId, product, currentPeriod, config.realtimeSubscribe]);
+
+  // 指标渲染 - 监听 activeIndicators 变化
+  // 重构：副图指标使用LWC v5原生pane系统，不再使用PaneChartPanel
+  useEffect(() => {
+    const renderer = rendererRef.current;
+    if (!renderer) return;
+
+    // ★ V4 需求4：复合 signature diff（id:visible:params），任何变化都触发重渲染
+    const currentSignature = activeIndicators
+      .map((i) => `${i.id}:${i.visible ? '1' : '0'}:${JSON.stringify(i.params)}`)
+      .sort()
+      .join(',');
+    if (currentSignature === prevIndicatorIdsRef.current) return;
+    prevIndicatorIdsRef.current = currentSignature;
+
+    // 清除旧的指标渲染
+    renderer.clearAll();
+
+    // ★ V6 需求1: clearAll 后清除 DrawingAdapter 的 pane series 映射
+    // clearAll 删除了所有副图 pane，旧 series 已失效
+    if (drawingAdapterRef.current) {
+      drawingAdapterRef.current.clearPaneSeriesMap();
+      // 重置到主图 pane
+      drawingAdapterRef.current.resetToMainPane();
+    }
+
+    // 重新渲染所有活跃指标
+    for (const indicator of activeIndicators) {
+      if (!indicator.visible) continue;
+
+      // 使用 MockIndicatorService 生成 mock 数据（过渡期，后端就绪后替换）
+      const mockData = MockIndicatorService.generate({ name: indicator.name, count: 100 });
+      setIndicatorData(indicator.name, {
+        name: indicator.name,
+        params: indicator.params,
+        data: mockData,
+      });
+
+      try {
+        const seriesIds = renderer.renderIndicator(indicator, mockData);
+        indicator.seriesIds = seriesIds;
+
+        // ★ V5 需求1: 注册副图 pane series 到 DrawingAdapter
+        const paneIndex = renderer.getPaneIndexByIndicatorId(indicator.id);
+        if (paneIndex > 0) {
+          const paneSeries = renderer.getPaneSeries(paneIndex);
+          if (paneSeries && drawingAdapterRef.current) {
+            drawingAdapterRef.current.registerPaneSeries(paneIndex, paneSeries);
+          }
+        }
+      } catch (err) {
+        console.error(`[QLChartPanel] Failed to render indicator ${indicator.name}:`, err);
+      }
+    }
+  }, [activeIndicators, setIndicatorData]);
+
+  // Bug②修复：panel mousedown事件在capture阶段可靠切换activePanelId
+  // 使用 panelId ?? 'panel_0' 确保单面板模式也正确设置 activePanelId
+  const effectivePanelId = panelId ?? 'panel_0';
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const handleMouseDown = () => {
+      const state = useChartStore.getState();
+      if (state.activePanelId !== effectivePanelId) {
+        state.setActivePanel(effectivePanelId);
+      }
+    };
+
+    // capture阶段确保优先触发
+    container.addEventListener('mousedown', handleMouseDown, true);
+    return () => {
+      container.removeEventListener('mousedown', handleMouseDown, true);
+    };
+  }, [containerRef, effectivePanelId]);
+
+  const handlePanelClick = useCallback(() => {
+    useChartStore.getState().setActivePanel(effectivePanelId);
+  }, [effectivePanelId]);
+
+  const activePanelId = useChartStore((s) => s.activePanelId);
+  const isActive = activePanelId === effectivePanelId;
+
+  // 切换活跃面板时清除绘图选中状态（避免跨面板属性编辑混乱）
+  useEffect(() => {
+    if (!isActive && useDrawingStore.getState().selectedDrawingId) {
+      useDrawingStore.getState().selectDrawing(null);
+    }
+  }, [isActive]);
+
+  return (
+    <div className={`qlchart-container ${isActive ? 'active-panel' : ''}`} data-panel-id={panelId} onClick={handlePanelClick}>
+      {showToolbar && (
+        <QLToolbar
+          period={currentPeriod}
+          seriesType={currentSeriesType}
+          theme={theme}
+          chartManager={chartManager}
+        />
+      )}
+      {/* 指标标签栏 */}
+      {activeIndicators.length > 0 && (
+        <div className="qlchart-indicator-tags">
+          {activeIndicators.map((ind) => (
+            <IndicatorTag key={ind.id} config={ind} />
+          ))}
+        </div>
+      )}
+      <div className="qlchart-chart-area" style={{
+        display: 'flex',
+        flexDirection: 'column',
+        flex: 1,
+      }}>
+        <div className="qlchart-panel" style={{ flex: 1, position: 'relative' }}>
+          {/* eslint-disable-next-line @typescript-eslint/no-explicit-any */}
+          <div ref={containerRef as any} className="qlchart-chart-wrapper" />
+
+          {/* 功能菜单 */}
+          <ChartFunctionMenu chart={chartManager?.getChart() ?? null} />
+
+          {/* 绘图工具栏：仅单面板时在此渲染 */}
+          {isSinglePanel && <DrawingModule />}
+
+          {/* 绘图属性栏：单面板 或 多面板的活跃面板时渲染 */}
+          {(isSinglePanel || isActive) && (
+            <DrawingPropertyPanel
+              onStyleChange={handleDrawingStyleChange}
+              onDelete={(id) => drawingAdapterRef.current?.removeDrawing(id)}
+            />
+          )}
+          <ChartContextMenu
+            containerRef={containerRef}
+            recentTools={recentTools}
+            onToolSelect={handleContextMenuToolSelect}
+            onDeleteDrawing={handleDeleteDrawing}
+            hasSelectedDrawing={!!selectedDrawingId}
+          />
+          {loading && <div className="qlchart-loading">加载中...</div>}
+          {error && <div className="qlchart-error">{error}</div>}
+        </div>
+        {/* 副图指标通过LWC v5原生pane系统在主chart内渲染，不再需要独立Panel */}
+      </div>
+    </div>
+  );
+  }
+);

package/src/components/QLChartProvider.tsx

@@ -0,0 +1,90 @@
+import { createContext, useContext, useEffect, useRef, type ReactNode } from 'react';
+import type { ThemePreset, SeriesType, IndicatorListResponse, IndicatorSearchQuery, IndicatorTemplate } from '../types/index.js';
+import { migrateLegacyDrawings } from '../plugins/drawing/migration.js';
+
+/** ★ Req1：实时K线数据格式（秒级时间戳，与LWC一致） */
+export interface RealtimeCandle {
+  time: number;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume?: number;
+}
+
+/** ★ Req1：实时数据订阅函数 */
+export interface RealtimeSubscribeFn {
+  (params: {
+    pairId: string;
+    product: string;
+    period: string;
+    onUpdate: (data: RealtimeCandle) => void;
+  }): (() => void) | void;
+}
+
+/** QLChart 配置 */
+export interface QLChartConfig {
+  /** API基础URL */
+  apiBaseUrl?: string;
+  /** 默认主题 */
+  defaultTheme?: ThemePreset;
+  /** 默认周期 */
+  defaultPeriod?: string;
+  /** 默认序列类型 */
+  defaultSeriesType?: SeriesType;
+  /** 数据获取函数 */
+  fetchFn?: (params: Record<string, unknown>) => Promise<unknown>;
+  /** ★ Req1：是否启用数据缓存（默认true） */
+  cacheEnabled?: boolean;
+  /** ★ Req1：缓存TTL（毫秒，默认300000 = 5分钟） */
+  cacheTTL?: number;
+  /** ★ Req1：实时数据订阅（WebSocket场景） */
+  realtimeSubscribe?: RealtimeSubscribeFn;
+  // ★ 任务3-2.2：指标总览API（注入式）
+  /** 指标列表查询函数（注入式，未注入时 fallback 到 BUILTIN_INDICATORS） */
+  indicatorListFn?: () => Promise<IndicatorListResponse>;
+  /** 指标搜索函数（注入式，用于指标面板搜索） */
+  indicatorSearchFn?: (query: IndicatorSearchQuery) => Promise<IndicatorTemplate[]>;
+}
+
+const QLChartContext = createContext<QLChartConfig>({});
+
+/** 配置Provider
+ *
+ * 支持两种使用方式：
+ * 1. 散装属性（推荐）：`<QLChartProvider fetchFn={fn} cacheEnabled />`
+ * 2. config对象（向后兼容）：`<QLChartProvider config={{ fetchFn: fn }} />`
+ */
+export function QLChartProvider({
+  config,
+  children,
+  ...restProps
+}: {
+  config?: QLChartConfig;
+  children: ReactNode;
+} & Partial<QLChartConfig>) {
+  const migratedRef = useRef(false);
+
+  // 一次性迁移旧版LocalStorage绘图数据
+  useEffect(() => {
+    if (migratedRef.current) return;
+    migratedRef.current = true;
+    migrateLegacyDrawings();
+  }, []);
+
+  // 合并 config prop 和散装属性，散装属性优先
+  const mergedConfig: QLChartConfig = { ...(config ?? {}), ...restProps };
+
+  return (
+    <QLChartContext.Provider value={mergedConfig}>
+      {children}
+    </QLChartContext.Provider>
+  );
+}
+
+/** 获取配置 */
+export function useQLChartConfig(): QLChartConfig {
+  return useContext(QLChartContext);
+}
+
+export { QLChartContext };