@axiom-lattice/gateway 3.0.2 → 3.0.3

package/public/sdk/README.md

@@ -1,695 +0,0 @@
-# Data Query SDK v3.0.0 - 状态机版本
-
-> **面向 AI 助手**: 本文档专为 AI 设计，包含完整的 API 说明和声明式配置规范  
-> **版本**: 3.0.0 | **更新日期**: 2025-01-15
-
----
-
-## 快速开始
-
-### 1. 引入 SDK
-
-```html
-<script src="http://localhost:4001/sdk/data-query-sdk.js"></script>
-<script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>
-<script src="https://cdn.tailwindcss.com"></script>
-```
-
-### 2. 声明式看板配置
-
-```javascript
-const config = {
-  filters: [
-    {
-      id: 'year',
-      label: '年份',
-      dimension: 'date__year',
-      operator: 'EQ',
-      defaultValue: 'ALL',
-      options: [
-        { value: 'ALL', text: '全部' },
-        { value: '2024', text: '2024年' }
-      ],
-      emitsToState: 'selected_year'  // 选择后写入全局状态
-    }
-  ],
-  widgets: [
-    {
-      id: 'yearly-pie',
-      type: 'pie',
-      title: '年度销售占比（点击下钻）',
-      gridClass: 'md:col-span-6',
-      query: {
-        serverKey: 'production',
-        datasourceId: '1',
-        metrics: ['sales'],
-        groupBy: ['date__year']
-      },
-      mapping: {
-        name: 'date__year',
-        value: 'sales'
-      },
-      emit: [{                       // 点击时发射状态
-        event: 'click',
-        extractValueFrom: 'date__year',
-        updateState: 'drill_year'
-      }]
-    },
-    {
-      id: 'monthly-bar',
-      type: 'bar',
-      title: '月度销售趋势',
-      gridClass: 'md:col-span-6',
-      query: {
-        serverKey: 'production',
-        datasourceId: '1',
-        metrics: ['sales'],
-        groupBy: ['date__month']
-      },
-      mapping: {
-        xAxis: 'date__month',
-        yAxis: ['sales']
-      },
-      receiveFilters: [{             // 接收全局状态
-        fromState: 'selected_year',
-        mapToDimension: 'date',        // 映射到原始维度字段
-        operator: 'BETWEEN',           // 日期范围使用 BETWEEN
-        ignoreIfEmpty: true
-      }, {
-        fromState: 'drill_year',
-        mapToDimension: 'date',        // 映射到原始维度字段
-        operator: 'BETWEEN',           // 日期范围使用 BETWEEN
-        ignoreIfEmpty: true
-      }]
-    }
-  ]
-};
-```
-
-### 3. 初始化看板
-
-```javascript
-const sdk = new DataQuerySDK({
-  baseURL: 'http://localhost:4001'
-});
-
-const engine = new DashboardEngine(sdk, config);
-await engine.init();
-```
-
----
-
-## 核心概念
-
-DashboardEngine 基于**发布-订阅**模型：
-
-- **`emit`**: 图表或过滤器被操作时，将值写入全局状态池
-- **`receiveFilters`**: 图表监听全局状态池，自动应用过滤条件
-
-**工作流程：**
-1. 用户操作过滤器或点击图表
-2. 触发 `emit`，将值写入全局状态
-3. 订阅该状态的图表收到通知
-4. 自动刷新，应用新的过滤条件
-
----
-
-## API 参考
-
-### DashboardEngine
-
-#### constructor(sdk, config, stateManager?)
-
-```javascript
-const engine = new DashboardEngine(sdk, config);
-// 或使用自定义状态管理器
-const engine = new DashboardEngine(sdk, config, new StateManager());
-```
-
-**参数：**
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| sdk | DataQuerySDK | ✅ | SDK 实例 |
-| config | Object | ✅ | 看板配置 |
-| stateManager | StateManager | ❌ | 自定义状态管理器 |
-
-#### init()
-
-初始化看板：渲染布局、绑定事件、加载数据。
-
-```javascript
-await engine.init();
-```
-
-#### destroy()
-
-销毁看板，清理资源。
-
-```javascript
-engine.destroy();
-```
-
----
-
-## 配置 Schema
-
-### FilterConfig - 过滤器配置
-
-```typescript
-interface FilterConfig {
-  id: string;                    // 唯一标识
-  label: string;                 // 显示标签
-  dimension: string;             // 维度字段名
-  operator: 'EQ' | 'NE' | 'GT' | 'LT' | 'GTE' | 'LTE' | 'BETWEEN' | 'IN';
-  defaultValue: string;          // 默认值
-  options: Array<{ value: string; text: string }>;
-  emitsToState: string;          // 选择后写入的全局状态键
-}
-```
-
-**示例：**
-
-```javascript
-{
-  id: 'region',
-  label: '区域',
-  dimension: 'region',
-  operator: 'EQ',
-  defaultValue: 'ALL',
-  options: [
-    { value: 'ALL', text: '全部' },
-    { value: 'north', text: '华北' },
-    { value: 'south', text: '华南' }
-  ],
-  emitsToState: 'selected_region'
-}
-```
-
----
-
-### WidgetConfig - 图表配置
-
-```typescript
-interface WidgetConfig {
-  id: string;                    // 唯一标识
-  title: string;                 // 标题
-  type: 'bar' | 'line' | 'pie' | 'scatter' | 'kpi' | 'table';
-  gridClass?: string;            // 布局类名（如 'md:col-span-6'）
-  
-  query: {
-    serverKey: string;           // 指标服务器 key
-    datasourceId: string;        // 数据源 ID
-    metrics: string[];           // 指标数组
-    groupBy?: string[];          // 分组维度
-    filters?: Filter[];          // 静态过滤器
-  };
-  
-  mapping: WidgetMapping;        // 数据映射
-  
-  receiveFilters?: ReceiveFilter[];  // 接收的全局过滤器
-  emit?: EmitConfig[];           // 点击事件发射器
-}
-```
-
----
-
-### WidgetMapping - 数据映射
-
-**柱状图/折线图 (bar/line):**
-
-```javascript
-{
-  mapping: {
-    xAxis: 'date__month',        // X 轴字段
-    yAxis: ['sales', 'profit'],  // Y 轴字段数组
-    valueFormat: 'currency_cny'  // 可选：数值格式化
-  }
-}
-```
-
-**饼图 (pie):**
-
-```javascript
-{
-  mapping: {
-    name: 'region',              // 分类字段
-    value: 'sales',              // 数值字段
-    valueFormat: 'compact_number'
-  }
-}
-```
-
-**KPI 卡片 (kpi):**
-
-```javascript
-{
-  mapping: {
-    value: 'total_sales',        // 数值字段
-    valueFormat: 'currency_cny'
-  }
-}
-```
-
-**表格 (table):**
-
-```javascript
-{
-  type: 'table',
-  title: '销售明细',
-  query: {
-    serverKey: 'production',
-    datasourceId: '1',
-    metrics: ['sales', 'profit'],
-    groupBy: ['product', 'region']
-  },
-  // table 类型不需要 mapping，直接显示所有列
-  tableConfig: {
-    pageSize: 10,                // 每页显示行数（默认 10）
-    align: 'left',               // 对齐方式：left/center/right
-    columnFormats: {             // 列特定的格式化
-      'sales': 'currency_cny',
-      'profit': 'currency_cny'
-    },
-    defaultFormat: 'compact_number'  // 默认格式化
-  },
-  emit: [{                       // 点击行时发射状态
-    event: 'click',
-    extractValueFrom: 'product',
-    updateState: 'selected_product'
-  }]
-}
-```
-
-**支持的 valueFormat:**
-
-| 格式 | 说明 | 示例 |
-|------|------|------|
-| `currency_cny` | 人民币 | ¥100,000 |
-| `currency_usd` | 美元 | $100,000 |
-| `percent` | 百分比 | 85.50% |
-| `compact_number` | 紧凑数字 | 10万 |
-
----
-
-### ReceiveFilter - 接收过滤器
-
-用于接收全局状态并映射为查询条件：
-
-```typescript
-interface ReceiveFilter {
-  fromState: string;             // 监听的全局状态键名
-  mapToDimension: string;        // 映射到当前查询的维度
-  operator: string;              // 操作符
-  ignoreIfEmpty?: boolean;       // 空值时是否忽略
-}
-```
-
-**示例：**
-
-```javascript
-{
-  fromState: 'selected_year',    // 监听全局状态
-  mapToDimension: 'date',        // 映射到原始维度字段（不是粒度表达式）
-  operator: 'BETWEEN',           // 日期范围使用 BETWEEN
-  ignoreIfEmpty: true            // 如果状态为空或 'ALL'，则忽略
-}
-```
-
-**解决字段不一致问题：**
-
-```javascript
-// Widget A - 销售数据
-{
-  receiveFilters: [{
-    fromState: 'selected_region',
-    mapToDimension: 'region',    // 映射到 'region' 字段
-    operator: 'EQ'
-  }]
-}
-
-// Widget B - 库存数据（不同字段名）
-{
-  receiveFilters: [{
-    fromState: 'selected_region',
-    mapToDimension: 'warehouse_location',  // 映射到 'warehouse_location'
-    operator: 'EQ'
-  }]
-}
-```
-
----
-
-### EmitConfig - 发射配置
-
-用于点击图表时发射状态：
-
-```typescript
-interface EmitConfig {
-  event: 'click';                // 事件类型
-  extractValueFrom: string;      // 从点击数据中提取的字段
-  updateState: string;           // 写入的全局状态键名
-}
-```
-
-**示例：**
-
-```javascript
-{
-  emit: [{
-    event: 'click',
-    extractValueFrom: 'date__year',
-    updateState: 'drill_year'
-  }]
-}
-```
-
----
-
-## 完整示例
-
-### 跨粒度联动（年度 → 月度）
-
-```javascript
-const config = {
-  filters: [
-    {
-      id: 'year',
-      label: '年份',
-      dimension: 'date__year',
-      operator: 'EQ',
-      defaultValue: 'ALL',
-      options: [
-        { value: 'ALL', text: '全部年份' },
-        { value: '2023', text: '2023年' },
-        { value: '2024', text: '2024年' }
-      ],
-      emitsToState: 'selected_year'
-    }
-  ],
-  widgets: [
-    {
-      id: 'yearly-pie',
-      type: 'pie',
-      title: '年度销售占比（点击下钻）',
-      gridClass: 'md:col-span-6',
-      query: {
-        serverKey: 'sales',
-        datasourceId: '1',
-        metrics: ['sales'],
-        groupBy: ['date__year']
-      },
-      mapping: {
-        name: 'date__year',
-        value: 'sales',
-        valueFormat: 'currency_cny'
-      },
-      emit: [{
-        event: 'click',
-        extractValueFrom: 'date__year',
-        updateState: 'drill_year'
-      }]
-    },
-    {
-      id: 'monthly-bar',
-      type: 'bar',
-      title: '月度销售趋势',
-      gridClass: 'md:col-span-6',
-      query: {
-        serverKey: 'sales',
-        datasourceId: '1',
-        metrics: ['sales'],
-        groupBy: ['date__month']
-      },
-      mapping: {
-        xAxis: 'date__month',
-        yAxis: ['sales']
-      },
-      receiveFilters: [
-        {
-          fromState: 'selected_year',
-          mapToDimension: 'date',        // 映射到原始维度字段
-          operator: 'BETWEEN',           // 日期范围使用 BETWEEN
-          ignoreIfEmpty: true
-        },
-        {
-          fromState: 'drill_year',
-          mapToDimension: 'date',        // 映射到原始维度字段
-          operator: 'BETWEEN',           // 日期范围使用 BETWEEN
-          ignoreIfEmpty: true
-        }
-      ]
-    }
-  ]
-};
-```
-
-**交互效果：**
-1. 选择全局年份过滤器 → 饼图和柱状图都更新
-2. 点击饼图的某个年份 → 柱状图显示该年份的月度数据
-
----
-
-### 多图表联动
-
-```javascript
-const config = {
-  widgets: [
-    {
-      id: 'region-pie',
-      type: 'pie',
-      title: '区域分布',
-      query: { metrics: ['sales'], groupBy: ['region'] },
-      mapping: { name: 'region', value: 'sales' },
-      emit: [{
-        event: 'click',
-        extractValueFrom: 'region',
-        updateState: 'selected_region'
-      }]
-    },
-    {
-      id: 'product-bar',
-      type: 'bar',
-      title: '产品销售（按区域过滤）',
-      query: { metrics: ['sales'], groupBy: ['product'] },
-      mapping: { xAxis: 'product', yAxis: ['sales'] },
-      receiveFilters: [{
-        fromState: 'selected_region',
-        mapToDimension: 'region',
-        operator: 'EQ',
-        ignoreIfEmpty: true
-      }]
-    },
-    {
-      id: 'trend-line',
-      type: 'line',
-      title: '趋势（按区域过滤）',
-      query: { metrics: ['sales'], groupBy: ['date__month'] },
-      mapping: { xAxis: 'date__month', yAxis: ['sales'] },
-      receiveFilters: [{
-        fromState: 'selected_region',
-        mapToDimension: 'region',
-        operator: 'EQ',
-        ignoreIfEmpty: true
-      }]
-    }
-  ]
-};
-```
-
----
-
-## 配置验证
-
-DashboardEngine 在初始化时会自动验证配置：
-
-```javascript
-try {
-  const engine = new DashboardEngine(sdk, invalidConfig);
-} catch (error) {
-  console.error(error.message);
-  // 输出:
-  // 配置错误:
-  //   - widgets[0] 缺少 title
-  //   - widgets[0].query 缺少 serverKey
-  //   - 闭环校验失败: emit 状态 "drill_year" 没有对应的 receiveFilters 消费
-}
-```
-
-### 手动验证配置
-
-```javascript
-const result = validateDashboardConfig(config);
-
-if (!result.valid) {
-  console.error('配置错误:');
-  result.errors.forEach(error => {
-    console.error('  -', error);
-  });
-} else {
-  console.log('配置有效！');
-}
-```
-
----
-
-## DataQuerySDK
-
-### 构造函数
-
-```javascript
-const sdk = new DataQuerySDK({
-  baseURL: 'http://localhost:4001',  // Gateway 地址（必填）
-  timeout: 30000                      // 超时时间（可选，默认 30 秒）
-});
-```
-
-> **注意：** `tenantId` 不需要手动传递！SDK 会自动从页面注入的 `window.__AI2APP_CONTEXT__` 中读取。
-
-### query(params)
-
-执行数据查询。
-
-```javascript
-const result = await sdk.query({
-  serverKey: 'production_metrics',
-  datasourceId: '1',
-  metrics: ['net_sales_amt'],
-  groupBy: ['DocDate__month'],
-  filters: [{
-    dimension: 'DocDate',
-    operator: 'BETWEEN',
-    values: ['2025-01-01', '2025-12-31']
-  }]
-});
-```
-
-**返回值：**
-
-```javascript
-{
-  success: true,
-  data: {
-    columns: [
-      { name: 'DocDate__month', type: 'date' },
-      { name: 'net_sales_amt', type: 'numeric' }
-    ],
-    rows: [
-      ['2025-01-01', 150000],
-      ['2025-02-01', 180000]
-    ],
-    rowsObject: [
-      { 'DocDate__month': '2025-01-01', 'net_sales_amt': 150000 },
-      { 'DocDate__month': '2025-02-01', 'net_sales_amt': 180000 }
-    ],
-    metadata: {
-      rowCount: 2,
-      executionTimeMs: 150
-    }
-  }
-}
-```
-
----
-
-## 完整 HTML 示例
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <meta charset="UTF-8">
-  <script src="https://cdn.tailwindcss.com"></script>
-  <script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>
-  <script src="http://localhost:4001/sdk/data-query-sdk.js"></script>
-</head>
-<body class="bg-gray-50 p-8">
-  <div id="filters-container" class="mb-4"></div>
-  <div id="dashboard-grid" class="grid grid-cols-12 gap-4"></div>
-  
-  <script>
-    const config = {
-      filters: [
-        {
-          id: 'year',
-          label: '年份',
-          dimension: 'date__year',
-          operator: 'EQ',
-          defaultValue: 'ALL',
-          options: [
-            { value: 'ALL', text: '全部' },
-            { value: '2024', text: '2024年' }
-          ],
-          emitsToState: 'selected_year'
-        }
-      ],
-      widgets: [
-        {
-          id: 'yearly-pie',
-          type: 'pie',
-          title: '年度销售占比',
-          gridClass: 'md:col-span-6',
-          query: {
-            serverKey: 'production',
-            datasourceId: '1',
-            metrics: ['sales'],
-            groupBy: ['date__year']
-          },
-          mapping: { name: 'date__year', value: 'sales' },
-          emit: [{
-            event: 'click',
-            extractValueFrom: 'date__year',
-            updateState: 'drill_year'
-          }]
-        },
-        {
-          id: 'monthly-bar',
-          type: 'bar',
-          title: '月度销售趋势',
-          gridClass: 'md:col-span-6',
-          query: {
-            serverKey: 'production',
-            datasourceId: '1',
-            metrics: ['sales'],
-            groupBy: ['date__month']
-          },
-          mapping: { xAxis: 'date__month', yAxis: ['sales'] },
-          receiveFilters: [{
-            fromState: 'drill_year',
-            mapToDimension: 'date',        // 映射到原始维度字段
-            operator: 'BETWEEN',           // 日期范围使用 BETWEEN
-            ignoreIfEmpty: true
-          }]
-        }
-      ]
-    };
-
-    async function init() {
-      const sdk = new DataQuerySDK({ baseURL: 'http://localhost:4001' });
-      const engine = new DashboardEngine(sdk, config);
-      await engine.init();
-    }
-
-    init().catch(console.error);
-  </script>
-</body>
-</html>
-```
-
----
-
-## 测试
-
-访问测试页面查看完整测试套件：
-
-```
-http://localhost:4001/sdk/test-dashboard.html
-```
-
----
-
-## 版本信息
-
-- **版本**: 3.0.0
-- **更新日期**: 2025-01-15
-- **文件位置**: `http://localhost:4001/sdk/data-query-sdk.js`