@axiom-lattice/gateway 2.1.39 → 2.1.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/gateway",
-  "version": "2.1.39",
+  "version": "2.1.41",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -21,6 +21,7 @@
     "@fastify/multipart": "^9.4.0",
     "@fastify/reply-from": "^12.5.0",
     "@fastify/sensible": "^6.0.3",
+    "@fastify/static": "^9.0.0",
     "@fastify/swagger": "^9.5.1",
     "@fastify/swagger-ui": "^5.2.3",
     "@fastify/websocket": "^11.0.1",
@@ -36,14 +37,14 @@
     "pino-roll": "^3.1.0",
     "redis": "^5.0.1",
     "uuid": "^9.0.1",
-    "@axiom-lattice/core": "2.1.33",
+    "@axiom-lattice/core": "2.1.35",
     "@axiom-lattice/protocols": "2.1.20",
     "@axiom-lattice/queue-redis": "1.0.19"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",
     "@types/lodash": "^4.17.16",
-    "@types/node": "^20.17.23",
+    "@types/node": "^20.19.13",
     "@types/uuid": "^9.0.8",
     "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^7.2.0",

package/public/sdk/README.md

@@ -0,0 +1,695 @@
+# 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`