@quantlife/qlchart 0.0.1

package/src/core/DataManager.ts

@@ -0,0 +1,427 @@
+import type { LogicalRange, IChartApi, ISeriesApi, UTCTimestamp } from 'lightweight-charts';
+import type { ChartRequestParams, ChartFetchResult, CandlestickRawData, CandlestickData } from '../types/index.js';
+import { transformCandlestickData } from '../utils/dataTransformer.js';
+
+/** 数据获取回调函数类型 */
+export type FetchFn = (params: ChartRequestParams) => Promise<unknown>;
+
+/** 分片缓存条目 */
+interface CacheSlice {
+  data: CandlestickRawData[];
+  startTime: number;
+  endTime: number;
+  timestamp: number;
+}
+
+/**
+ * 数据管理器（增强版）
+ *
+ * 三大核心能力：
+ * 1. 拖动加载（ScrollLoader）— 监听 visibleLogicalRangeChange，触底自动加载历史
+ * 2. 定时获取（RealtimePoller）— setInterval 拉取最新 K 线
+ * 3. 分片缓存（SliceCache）— 按 pair+product+period 维度缓存已加载的分片
+ *
+ * 同时保持对旧 fetchChartData() 的向后兼容。
+ */
+export class DataManager {
+  private fetchFn: FetchFn;
+
+  // ── 旧缓存系统（保留向后兼容）──
+  private cache = new Map<string, { data: unknown; timestamp: number }>();
+  private cacheTTL = 5 * 60 * 1000;
+
+  // ── Chart 绑定状态 ──
+  private chart: IChartApi | null = null;
+  private series: ISeriesApi<any> | null = null;
+  private pairId = '';
+  private product = '';
+  private period = '';
+
+  // ── 拖动加载 ──
+  private isLoadingHistory = false;
+  private hasMoreHistory = true;
+  private scrollHandler: ((range: LogicalRange | null) => void) | null = null;
+
+  // ── 定时获取 ──
+  private realtimeTimer: ReturnType<typeof setInterval> | null = null;
+
+  // ── 全量数据（方案B：维护内存数组）──
+  private allData: CandlestickData[] = [];
+
+  // ── 分片缓存 ──
+  private slices = new Map<string, CacheSlice[]>();
+
+  constructor(fetchFn: FetchFn) {
+    this.fetchFn = fetchFn;
+  }
+
+  // ════════════════════════════════════════
+  //  Chart 绑定 / 解绑
+  // ════════════════════════════════════════
+
+  /**
+   * 绑定到图表实例，启用拖动加载
+   */
+  attachToChart(
+    chart: IChartApi,
+    series: ISeriesApi<any>,
+    params: { pairId: string; product: string; period: string },
+  ): void {
+    this.chart = chart;
+    this.series = series;
+    this.pairId = params.pairId;
+    this.product = params.product;
+    this.period = params.period;
+
+    // 重置状态
+    this.hasMoreHistory = true;
+    this.isLoadingHistory = false;
+
+    // 初始化全量数据（从当前 series 获取已有数据）
+    this.syncAllDataFromSeries();
+
+    // 注册拖动监听
+    this.scrollHandler = (range: LogicalRange | null) => {
+      if (!range) return;
+      // 当可见范围左边缘接近起点时触发历史加载
+      if (range.from < 10 && this.hasMoreHistory && !this.isLoadingHistory) {
+        this.loadMoreHistory();
+      }
+    };
+    chart.timeScale().subscribeVisibleLogicalRangeChange(this.scrollHandler);
+  }
+
+  /**
+   * 解绑图表，清理所有监听和定时器
+   */
+  detach(): void {
+    if (this.scrollHandler && this.chart) {
+      this.chart.timeScale().unsubscribeVisibleLogicalRangeChange(this.scrollHandler);
+    }
+    this.stopRealtimeFetch();
+    this.chart = null;
+    this.series = null;
+    this.scrollHandler = null;
+    this.allData = [];
+  }
+
+  // ════════════════════════════════════════
+  //  拖动加载（ScrollLoader）
+  // ════════════════════════════════════════
+
+  /**
+   * 加载更早的历史数据
+   */
+  private async loadMoreHistory(): Promise<void> {
+    this.isLoadingHistory = true;
+    try {
+      const earliestTime = this.getEarliestDataTime();
+      const result = await this.fetchFn({
+        pairId: this.pairId,
+        product: this.product,
+        period: this.period,
+        endTime: earliestTime,
+        limit: 500,
+      }) as ChartFetchResult | { data: CandlestickRawData[] } | undefined;
+
+      if (!result) {
+        this.hasMoreHistory = false;
+        return;
+      }
+
+      // 兼容 ChartFetchResult 和旧格式
+      const rawData = (result as ChartFetchResult).data ?? (result as { data?: CandlestickRawData[] }).data ?? [];
+      const hasMore = (result as ChartFetchResult).hasMoreHistory;
+
+      if (rawData.length > 0) {
+        this.prependData(rawData);
+        this.saveSlice(rawData);
+      }
+
+      // 更新 hasMoreHistory（未明确返回 false 则默认 true）
+      this.hasMoreHistory = hasMore !== false && rawData.length > 0;
+    } catch (e) {
+      console.error('[DataManager] loadMoreHistory failed:', e);
+    } finally {
+      this.isLoadingHistory = false;
+    }
+  }
+
+  /**
+   * 在 series 前面追加历史数据（方案B：维护全量数组）
+   */
+  private prependData(newData: CandlestickRawData[]): void {
+    if (!this.series) return;
+    const newTransformed = transformCandlestickData(newData);
+    // 合并到全量数组前面
+    this.allData = [...newTransformed, ...this.allData];
+    // 去重（按 time）
+    const seen = new Set<number>();
+    this.allData = this.allData.filter((d) => {
+      const t = d.time as number;
+      if (seen.has(t)) return false;
+      seen.add(t);
+      return true;
+    });
+    // 全量 setData
+    this.series.setData(this.allData);
+  }
+
+  // ════════════════════════════════════════
+  //  定时获取最新（RealtimePoller）
+  // ════════════════════════════════════════
+
+  /**
+   * 启动定时获取最新数据
+   */
+  startRealtimeFetch(intervalMs: number = 5000): void {
+    if (this.realtimeTimer) clearInterval(this.realtimeTimer);
+    this.realtimeTimer = setInterval(() => this.fetchLatest(), intervalMs);
+  }
+
+  /**
+   * 停止定时获取
+   */
+  stopRealtimeFetch(): void {
+    if (this.realtimeTimer) {
+      clearInterval(this.realtimeTimer);
+      this.realtimeTimer = null;
+    }
+  }
+
+  /**
+   * 获取最新 K 线并增量更新
+   */
+  private async fetchLatest(): Promise<void> {
+    if (!this.series) return;
+    try {
+      const latestTime = this.getLatestDataTime();
+      const now = Date.now();
+      const result = await this.fetchFn({
+        pairId: this.pairId,
+        product: this.product,
+        period: this.period,
+        startTime: latestTime,
+        endTime: now,
+      }) as ChartFetchResult | { data: CandlestickRawData[] } | undefined;
+
+      if (!result) return;
+
+      const rawData = (result as ChartFetchResult).data ?? (result as { data?: CandlestickRawData[] }).data ?? [];
+
+      if (rawData.length > 0) {
+        // 增量更新：逐条 update（最后一条可能是更新而非新增）
+        for (const candle of rawData) {
+          const point = {
+            time: (candle.time / 1000) as UTCTimestamp,
+            open: candle.open,
+            high: candle.high,
+            low: candle.low,
+            close: candle.close,
+          };
+          this.series.update(point);
+
+          // 同步 allData
+          const timeSec = candle.time / 1000;
+          const existingIdx = this.allData.findIndex((d) => (d.time as number) === timeSec);
+          if (existingIdx >= 0) {
+            this.allData[existingIdx] = point;
+          } else {
+            this.allData.push(point);
+            this.allData.sort((a, b) => (a.time as number) - (b.time as number));
+          }
+        }
+      }
+    } catch (e) {
+      console.error('[DataManager] fetchLatest failed:', e);
+    }
+  }
+
+  // ════════════════════════════════════════
+  //  分片缓存（SliceCache）
+  // ════════════════════════════════════════
+
+  private getCacheKey(): string {
+    return `${this.pairId}_${this.product}_${this.period}`;
+  }
+
+  /**
+   * 保存分片到缓存
+   */
+  private saveSlice(data: CandlestickRawData[]): void {
+    if (data.length === 0) return;
+    const key = this.getCacheKey();
+    const times = data.map((d) => d.time);
+    const slice: CacheSlice = {
+      data,
+      startTime: Math.min(...times),
+      endTime: Math.max(...times),
+      timestamp: Date.now(),
+    };
+    const existing = this.slices.get(key) ?? [];
+    existing.push(slice);
+    // 过期清理
+    const validSlices = existing.filter((s) => Date.now() - s.timestamp < this.cacheTTL);
+    this.slices.set(key, validSlices);
+  }
+
+  /**
+   * 查询缓存中是否包含指定时间范围的数据
+   */
+  private getCachedSlices(startTime: number, endTime: number): CandlestickRawData[] {
+    const key = this.getCacheKey();
+    const slices = this.slices.get(key);
+    if (!slices) return [];
+
+    const merged: CandlestickRawData[] = [];
+    const seen = new Set<number>();
+    for (const slice of slices) {
+      // 分片与请求范围有交集
+      if (slice.startTime <= endTime && slice.endTime >= startTime) {
+        for (const d of slice.data) {
+          if (d.time >= startTime && d.time <= endTime && !seen.has(d.time)) {
+            merged.push(d);
+            seen.add(d.time);
+          }
+        }
+      }
+    }
+    return merged.sort((a, b) => a.time - b.time);
+  }
+
+  /**
+   * 检查分片缓存是否覆盖了请求范围
+   */
+  private isRangeCached(startTime: number, endTime: number): boolean {
+    const key = this.getCacheKey();
+    const slices = this.slices.get(key);
+    if (!slices || slices.length === 0) return false;
+
+    // 合并所有有效分片的时间范围
+    let cachedMin = Infinity;
+    let cachedMax = -Infinity;
+    for (const slice of slices) {
+      if (Date.now() - slice.timestamp >= this.cacheTTL) continue;
+      cachedMin = Math.min(cachedMin, slice.startTime);
+      cachedMax = Math.max(cachedMax, slice.endTime);
+    }
+    return cachedMin <= startTime && cachedMax >= endTime;
+  }
+
+  // ════════════════════════════════════════
+  //  辅助方法
+  // ════════════════════════════════════════
+
+  /**
+   * 从当前 allData 获取最早时间戳（毫秒）
+   */
+  private getEarliestDataTime(): number {
+    if (this.allData.length === 0) return Date.now();
+    const earliest = this.allData[0].time as number;
+    return earliest * 1000;
+  }
+
+  /**
+   * 从当前 allData 获取最新时间戳（毫秒）
+   */
+  private getLatestDataTime(): number {
+    if (this.allData.length === 0) return Date.now() - 86400000;
+    const latest = this.allData[this.allData.length - 1].time as number;
+    return latest * 1000;
+  }
+
+  /**
+   * 从 series 同步全量数据到 allData
+   */
+  private syncAllDataFromSeries(): void {
+    if (!this.series) return;
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const data = (this.series as any).data?.() as CandlestickData[] | undefined;
+      if (data && Array.isArray(data)) {
+        this.allData = [...data];
+      }
+    } catch {
+      // LWC API 可能不支持 data() 方法，忽略
+    }
+  }
+
+  /**
+   * 手动设置全量数据（外部调用 setData 后同步）
+   */
+  setAllData(data: CandlestickData[]): void {
+    this.allData = [...data];
+  }
+
+  // ════════════════════════════════════════
+  //  旧 API（向后兼容）
+  // ════════════════════════════════════════
+
+  /**
+   * 获取图表数据（带缓存，向后兼容）
+   */
+  async fetchChartData(params: ChartRequestParams): Promise<unknown> {
+    const cacheKey = this.getLegacyCacheKey(params);
+    const cached = this.getCacheEntry(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    const data = await this.fetchFn(params);
+    this.setCache(cacheKey, data);
+
+    // 同时保存到分片缓存
+    const result = data as ChartFetchResult | { data?: CandlestickRawData[] };
+    const rawData = (result as ChartFetchResult)?.data ?? (result as { data?: CandlestickRawData[] })?.data;
+    if (rawData && Array.isArray(rawData) && rawData.length > 0) {
+      // 临时设置 pair/product/period 以便 getCacheKey 工作
+      const savedPair = this.pairId;
+      const savedProduct = this.product;
+      const savedPeriod = this.period;
+      this.pairId = params.pairId;
+      this.product = params.product;
+      this.period = params.period;
+      this.saveSlice(rawData);
+      this.pairId = savedPair;
+      this.product = savedProduct;
+      this.period = savedPeriod;
+    }
+
+    return data;
+  }
+
+  private getLegacyCacheKey(params: ChartRequestParams): string {
+    return `${params.pairId}_${params.product}_${params.period}_${params.startTime ?? ''}_${params.endTime ?? ''}`;
+  }
+
+  private getCacheEntry(key: string): unknown | null {
+    const entry = this.cache.get(key);
+    if (entry && Date.now() - entry.timestamp < this.cacheTTL) {
+      return entry.data;
+    }
+    if (entry) {
+      this.cache.delete(key);
+    }
+    return null;
+  }
+
+  private setCache(key: string, data: unknown): void {
+    this.cache.set(key, { data, timestamp: Date.now() });
+  }
+
+  /** 手动设置缓存数据 */
+  setCacheData(params: ChartRequestParams, data: unknown): void {
+    this.setCache(this.getLegacyCacheKey(params), data);
+  }
+
+  /** 清除所有缓存（旧缓存 + 分片缓存） */
+  clearCache(): void {
+    this.cache.clear();
+    this.slices.clear();
+  }
+
+  /** 设置缓存TTL（毫秒） */
+  setCacheTTL(ttl: number): void {
+    this.cacheTTL = ttl;
+  }
+}

package/src/core/EventManager.ts

@@ -0,0 +1,63 @@
+/** 图表事件枚举 */
+export enum ChartEvent {
+  ChartCreated = 'chart:created',
+  ChartDisposed = 'chart:disposed',
+  DataLoaded = 'data:loaded',
+  PeriodChanged = 'period:changed',
+  CrosshairMove = 'crosshair:move',
+  SeriesAdded = 'series:added',
+  SeriesRemoved = 'series:removed',
+  ThemeChanged = 'theme:changed',
+  LayoutChanged = 'layout:changed',
+  Error = 'error',
+}
+
+/** 事件处理器类型 */
+export type EventHandler<T = unknown> = (data: T) => void;
+
+/**
+ * 泛型事件总线
+ * 用于图表各模块间的解耦通信
+ */
+export class EventManager {
+  private listeners = new Map<string, Set<EventHandler>>();
+
+  /** 注册事件监听 */
+  on<T = unknown>(event: string, handler: EventHandler<T>): () => void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    const set = this.listeners.get(event)!;
+    set.add(handler as EventHandler);
+
+    // 返回取消监听函数
+    return () => this.off(event, handler);
+  }
+
+  /** 取消事件监听 */
+  off<T = unknown>(event: string, handler: EventHandler<T>): void {
+    const set = this.listeners.get(event);
+    if (set) {
+      set.delete(handler as EventHandler);
+    }
+  }
+
+  /** 触发事件 */
+  emit<T = unknown>(event: string, data?: T): void {
+    const set = this.listeners.get(event);
+    if (set) {
+      set.forEach((handler) => {
+        try {
+          handler(data);
+        } catch (err) {
+          console.error(`[EventManager] Error in handler for "${event}":`, err);
+        }
+      });
+    }
+  }
+
+  /** 清除所有监听 */
+  clear(): void {
+    this.listeners.clear();
+  }
+}

package/src/core/IndicatorDataProcessor.ts

@@ -0,0 +1,104 @@
+import type { UTCTimestamp } from 'lightweight-charts';
+import type { ChartDataResponse, IndicatorMeta } from '../types/indicator.js';
+import { IndicatorType, IndicatorDisplayType } from '../types/indicator.js';
+
+/** 解析后的单条指标线数据 */
+export interface ParsedIndicatorLine {
+  line: IndicatorMeta['lines'][number];
+  data: Array<{ time: UTCTimestamp; value: number }>;
+}
+
+/** 解析后的单条指标 */
+export interface ParsedIndicator {
+  meta: IndicatorMeta;
+  lineData: ParsedIndicatorLine[];
+}
+
+/** IndicatorDataProcessor 解析结果 */
+export interface ParsedChartData {
+  candlestick: Array<{ time: UTCTimestamp; open: number; high: number; low: number; close: number }>;
+  volume: Array<{ time: UTCTimestamp; value: number; color: string }>;
+  overlayIndicators: ParsedIndicator[];
+  paneIndicators: ParsedIndicator[];
+}
+
+/**
+ * IndicatorDataProcessor
+ *
+ * 将后端返回的 ChartDataResponse（二维数组格式）解析为可渲染的指标序列数据。
+ * 前端不需要知道指标算法，只按 dataIndex 取值渲染。
+ */
+export class IndicatorDataProcessor {
+  /**
+   * 解析 ChartDataResponse 为可渲染数据
+   */
+  static parse(response: ChartDataResponse): ParsedChartData {
+    const { timestamps, data, ohlcIndex, indicators } = response;
+
+    // 解析K线数据
+    const candlestick = timestamps.map((time, i) => ({
+      time: (time / 1000) as UTCTimestamp,
+      open: data[i]?.[ohlcIndex.open] ?? 0,
+      high: data[i]?.[ohlcIndex.high] ?? 0,
+      low: data[i]?.[ohlcIndex.low] ?? 0,
+      close: data[i]?.[ohlcIndex.close] ?? 0,
+    }));
+
+    // 解析成交量
+    const volume = timestamps.map((time, i) => ({
+      time: (time / 1000) as UTCTimestamp,
+      value: data[i]?.[ohlcIndex.volume] ?? 0,
+      color: (data[i]?.[ohlcIndex.close] ?? 0) >= (data[i]?.[ohlcIndex.open] ?? 0)
+        ? 'rgba(38, 166, 154, 0.35)'
+        : 'rgba(239, 83, 80, 0.35)',
+    }));
+
+    // 按指标类型分组解析
+    const overlayIndicators: ParsedIndicator[] = [];
+    const paneIndicators: ParsedIndicator[] = [];
+
+    for (const meta of indicators) {
+      const parsed: ParsedIndicator = {
+        meta,
+        lineData: meta.lines.map(line => ({
+          line,
+          data: timestamps
+            .map((time, i) => ({
+              time: (time / 1000) as UTCTimestamp,
+              value: data[i]?.[line.dataIndex] ?? NaN,
+            }))
+            .filter(d => !Number.isNaN(d.value) && d.value != null),
+        })),
+      };
+
+      if (meta.displayType === IndicatorDisplayType.Pane) {
+        paneIndicators.push(parsed);
+      } else {
+        overlayIndicators.push(parsed);
+      }
+    }
+
+    return { candlestick, volume, overlayIndicators, paneIndicators };
+  }
+
+  /**
+   * 判断fetchFn返回的是否为v2格式
+   */
+  static isV2Format(response: unknown): response is ChartDataResponse {
+    return (
+      typeof response === 'object' && response !== null &&
+      'timestamps' in response &&
+      'data' in response &&
+      'ohlcIndex' in response &&
+      'indicators' in response
+    );
+  }
+
+  /**
+   * 兼容旧枚举值映射
+   */
+  static mapDisplayType(displayType: string): IndicatorType {
+    if (displayType === 'pane') return IndicatorType.Pane;
+    return IndicatorType.Overlay;
+  }
+}