@axiom-lattice/gateway 2.1.39 → 2.1.41

package/public/sdk/data-query-sdk.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Data Query SDK TypeScript 类型定义
+ * 
+ * 用于在 TypeScript 项目中提供类型支持
+ */
+
+export interface SDKConfig {
+  /** Gateway 基础 URL，如 'http://localhost:4001' */
+  baseURL: string;
+  /** 租户 ID，可选 */
+  tenantId?: string;
+  /** 额外的请求头，可选 */
+  headers?: Record<string, string>;
+  /** 请求超时时间（毫秒），默认 30 秒 */
+  timeout?: number;
+}
+
+export interface Filter {
+  /** 维度/字段名 */
+  dimension: string;
+  /** 操作符，如 'BETWEEN', 'EQ', 'GT', 'LT', 'IN' */
+  operator: string;
+  /** 过滤值数组 */
+  values: (string | number | boolean)[];
+}
+
+export interface QueryParams {
+  /** 指标服务器 key */
+  serverKey: string;
+  /** 数据源 ID */
+  datasourceId: string;
+  /** 语义查询：指标名称数组 */
+  metrics?: string[];
+  /** 语义查询：分组维度数组 */
+  groupBy?: string[];
+  /** 语义查询：过滤器数组 */
+  filters?: Filter[];
+  /** SQL 查询：SQL 语句 */
+  customSql?: string;
+  /** SQL 查询：SQL 参数 */
+  params?: Record<string, string | number | boolean>;
+  /** 最大返回行数，默认 1000 */
+  limit?: number;
+  /** 返回格式：'echarts' 或 'raw'，默认 'echarts' */
+  format?: 'echarts' | 'raw';
+}
+
+export interface SemanticQueryParams extends Omit<QueryParams, 'customSql' | 'params'> {
+  /** 指标名称数组（必填） */
+  metrics: string[];
+}
+
+export interface SQLQueryParams extends Omit<QueryParams, 'metrics' | 'groupBy' | 'filters'> {
+  /** SQL 语句（必填） */
+  sql: string;
+  /** SQL 参数 */
+  params?: Record<string, string | number | boolean>;
+}
+
+export interface SeriesConfig {
+  /** 系列名称 */
+  name: string;
+  /** 图表类型：'line', 'bar', 'pie' */
+  type: 'line' | 'bar' | 'pie';
+  /** 编码配置 */
+  encode?: {
+    x?: string;
+    y?: string;
+  };
+}
+
+export interface QueryResultData {
+  /** 维度数组 */
+  dimensions: string[];
+  /** 数据源数组（ECharts dataset.source 格式） */
+  source: Record<string, any>[];
+  /** 系列配置 */
+  series: SeriesConfig[];
+  /** 分页信息 */
+  pagination?: {
+    total: number;
+    limit: number;
+    offset: number;
+  };
+  /** 元数据 */
+  metadata: {
+    queryTimeMs: number;
+    rowCount: number;
+  };
+}
+
+export interface QueryResult {
+  /** 是否成功 */
+  success: boolean;
+  /** 消息 */
+  message: string;
+  /** 数据 */
+  data: QueryResultData;
+}
+
+export interface EChartsOption {
+  title?: { text: string };
+  tooltip?: { trigger: string };
+  legend?: { data: string[] };
+  dataset?: {
+    dimensions: string[];
+    source: Record<string, any>[];
+  };
+  xAxis?: { type: string };
+  yAxis?: { type: string };
+  series: any[];
+}
+
+export interface EChartsOptionConfig {
+  /** 图表标题 */
+  title?: string;
+  /** 图表类型：'line', 'bar', 'pie'，默认 'line' */
+  type?: 'line' | 'bar' | 'pie';
+}
+
+/**
+ * Data Query SDK 类
+ */
+export declare class DataQuerySDK {
+  /**
+   * 创建 SDK 实例
+   * @param config - 配置对象
+   */
+  constructor(config: SDKConfig);
+
+  /**
+   * 执行数据查询
+   * @param params - 查询参数
+   * @returns 查询结果
+   */
+  query(params: QueryParams): Promise<QueryResult>;
+
+  /**
+   * 语义查询快捷方法
+   * @param params - 语义查询参数
+   * @returns 查询结果
+   */
+  semanticQuery(params: SemanticQueryParams): Promise<QueryResult>;
+
+  /**
+   * SQL 查询快捷方法
+   * @param params - SQL 查询参数
+   * @returns 查询结果
+   */
+  sqlQuery(params: SQLQueryParams): Promise<QueryResult>;
+
+  /**
+   * 获取 ECharts 配置
+   * @param result - query 方法返回的结果
+   * @param options - 图表配置选项
+   * @returns ECharts 配置对象
+   */
+  toEChartsOption(result: QueryResult, options?: EChartsOptionConfig): EChartsOption;
+}
+
+// DashboardEngine Types
+
+export interface SeriesMapping {
+  y: string;
+  type: 'bar' | 'line';
+  name: string;
+  yAxisIndex?: number;
+  area?: boolean;
+}
+
+export interface WidgetMapping {
+  x?: string;
+  xName?: string;
+  yAxisNames?: string[];
+  series?: SeriesMapping[];
+  y?: string;
+  yName?: string;
+  name?: string;
+  value?: string;
+  size?: string;
+  color?: string;
+  dimensions?: string[];
+  nameField?: string;
+  max?: number;
+}
+
+export interface WidgetQuery {
+  metrics: string[];
+  groupBy?: string[];
+  serverKey: string;
+  datasourceId: string;
+  filters?: Filter[];
+}
+
+export interface WidgetConfig {
+  id: string;
+  title: string;
+  type: 'bar' | 'line' | 'pie' | 'kpi' | 'scatter' | 'radar' | 'funnel' | 'gauge' | 'heatmap' | 'treemap' | 'custom';
+  gridClass?: string;
+  query: WidgetQuery;
+  mapping: WidgetMapping;
+  optionOverride?: Record<string, any>;
+  getOption?: (rows: any[], config: WidgetConfig) => Record<string, any>;
+}
+
+export interface FilterOption {
+  value: string;
+  text: string;
+}
+
+export interface FilterConfig {
+  id: string;
+  label: string;
+  dimension: string;
+  operator: string;
+  defaultValue: string;
+  options: FilterOption[];
+}
+
+export interface DashboardConfig {
+  widgets: WidgetConfig[];
+  filters: FilterConfig[];
+}
+
+export interface ChartTypeHandler {
+  validate: (config: WidgetConfig) => boolean;
+  generateOption: (rows: any[], mapping: WidgetMapping, baseOption: Record<string, any>) => Record<string, any>;
+}
+
+/**
+ * DashboardEngine - 声明式看板渲染引擎
+ */
+export declare class DashboardEngine {
+  constructor(sdk: DataQuerySDK, config: DashboardConfig);
+
+  /** 初始化看板 */
+  init(): Promise<void>;
+
+  /** 刷新所有图表 */
+  refreshAll(): Promise<void>;
+
+  /** 刷新单个图表 */
+  refreshWidget(config: WidgetConfig): Promise<void>;
+
+  /** 销毁看板，清理资源 */
+  destroy(): void;
+
+  /** 注册自定义图表类型 */
+  static registerChartType(type: string, handler: ChartTypeHandler): void;
+}
+
+export default DataQuerySDK;