@axiom-lattice/gateway 2.1.39 → 2.1.41

package/public/sdk/dashboard-engine-skill.md

@@ -0,0 +1,1122 @@
+# 技能：使用 DashboardEngine 创建数据看板（v3.0 状态机版本）
+
+## 概述
+
+本技能指导如何使用 Data Query SDK v3.0 的 DashboardEngine 创建声明式数据看板，支持状态机联动机制。
+
+**适用场景**：
+- 需要创建可交互的数据看板
+- 图表间需要联动（点击下钻、过滤器联动）
+- 跨数据源字段名不一致的场景
+
+**核心特性**：
+- ✅ 声明式配置（纯 JSON，无 JS 函数）
+- ✅ 状态机架构（emit/receiveFilters）
+- ✅ 字段映射（解决跨数据源不一致）
+- ✅ 配置验证（防止模型幻觉）
+- ✅ 闭环校验（自动检查 emit/receive 配对）
+
+---
+
+## 依赖
+
+```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>
+```
+
+---
+
+## 核心概念
+
+### 状态机架构
+
+DashboardEngine 基于**发布-订阅**模型：
+
+```
+过滤器/图表点击
+    ↓
+  emit（发射状态）
+    ↓
+全局状态池（State Pool）
+    ↓
+  receiveFilters（订阅状态）
+    ↓
+图表自动刷新
+```
+
+**关键字段：**
+- **`emitsToState`**: 过滤器选择后写入全局状态
+- **`emit`**: 图表点击时发射状态
+- **`receiveFilters`**: 图表订阅状态并应用过滤
+
+---
+
+## 步骤 1：数据探查（必须先完成）
+
+**⚠️ 关键原则：没有数据探查，就没有 Dashboard 设计**
+
+在设计任何 Dashboard 之前，必须完成完整的数据探查。你需要了解有哪些指标可用、维度如何分布、过滤条件如何影响数据，才能决定什么作为 KPI、什么用什么图表展示。
+
+**🚫 严禁伪造数据**
+
+- **所有图表和表格的数据必须通过查询获取**，禁止在配置中硬编码或伪造任何数据
+- **筛选器的选项值如果是静态值**（如固定的年份列表、固定的地区选项），可以写入配置
+- **任何动态数据**（指标数值、维度值、统计结果）必须通过 `query` 查询获取
+- **禁止示例数据**：不要在 `mapping`、`tableConfig` 或任何配置字段中放置假数据作为示例
+
+### 1.1 获取可用指标和维度
+
+**第一步：查询数据源的元数据**
+
+使用现有工具查询数据源的指标和维度信息，获取：
+- **指标列表**：有哪些数值字段可用（销售额、订单量、用户数等）
+- **维度列表**：有哪些分组字段可用（时间、地区、产品类别等）
+- **时间粒度**：时间维度支持哪些粒度（日、周、月、季度、年）
+
+**第二步：验证每个指标的实际查询**
+
+对每个候选指标执行实际查询，确认：
+- 指标名称是否正确（大小写敏感）
+- 返回的数据格式是否符合预期
+- 数值范围是否合理
+
+**第三步：验证每个维度的下钻能力**
+
+对想要下钻的维度执行带过滤条件的查询：
+- 测试维度过滤是否生效
+- 确认过滤后的数据量是否适合展示
+- 验证维度值的格式（如日期格式、地区编码）
+
+### 1.2 Query 查询规则
+
+每个 Widget 的 `query` 字段遵循以下结构：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `serverKey` | `string` | ✅ | 指标服务器 key |
+| `datasourceId` | `string` | ✅ | 数据源 ID |
+| `metrics` | `string[]` | ✅ | 要查询的指标名列表，名称来自 meta 中的指标定义（metric name） |
+| `groupBy` | `string[]` | ❌ | 分组维度。可为**维度名**或**带粒度的维度**（如 `{dimension}__day`、`{dimension}__week`、`{dimension}__month`、`{dimension}__quarter`、`{dimension}__year`），具体支持粒度以 meta 中该维度的 `time_granularities` 或等价定义为准 |
+| `filters` | `object[]` | ❌ | 过滤条件数组，见下方 Filter 项结构 |
+| `orderBy` | `object[]` | ❌ | 排序规则数组，见下方 OrderBy 项结构 |
+| `limit` | `integer` | ❌ | 返回行数上限，区间 [1, 20000]，未传时由服务端默认 |
+| `debug` | `boolean` | ❌ | 为 `true` 时，响应 `data.debug` 中可包含执行信息（如生成 SQL、参数等），便于排查 |
+
+**Filter 项结构：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `dimension` | `string` | ✅ | 维度名，须与 meta 中定义的维度一致（如时间维度、分类维度等） |
+| `operator` | `string` | ✅ | 操作符，见下方支持的操作符列表 |
+| `values` | `string[]` | 依操作符 | 用于比较的值；`BETWEEN` 时为 `[起, 止]`，`IN`/`NOT_IN` 时为多值列表；部分操作符可为空 |
+
+**支持的操作符：**
+
+| 操作符 | 说明 | 适用场景 |
+|--------|------|----------|
+| `EQ` | 等于（=） | 精确匹配单个值 |
+| `NEQ` | 不等于（!=） | 排除单个值 |
+| `IN` | 包含在列表中 | 匹配多个值中的任意一个 |
+| `NOT_IN` | 不包含在列表中 | 排除多个值 |
+| `BETWEEN` | 范围（闭区间） | 时间范围、数值范围，values 为 `[min, max]` |
+| `GT` | 大于（>） | 数值比较 |
+| `GTE` | 大于等于（>=） | 数值比较 |
+| `LT` | 小于（<） | 数值比较 |
+| `LTE` | 小于等于（<=） | 数值比较 |
+| `LIKE` | 模糊匹配 | 字符串匹配，支持 `%` 通配符 |
+| `ILIKE` | 模糊匹配（不区分大小写） | 字符串匹配 |
+| `IS_NULL` | 为空 | 检查空值，values 可省略 |
+| `IS_NOT_NULL` | 不为空 | 检查非空值，values 可省略 |
+
+**⚠️ 数据探查时必须使用过滤条件**
+
+在进行数据探查时，**必须**带上过滤条件执行查询，原因如下：
+
+1. **验证指标可用性**：有些指标在全局查询时正常，但加上过滤条件后可能返回空数据或报错
+2. **确认维度有效性**：过滤条件能帮你确认维度值的真实格式（如日期是 `2025-01-01` 还是 `2025/01/01`）
+3. **评估数据量**：带过滤的查询能反映 Dashboard 实际使用时的数据量，避免配置后发现数据过多或过少
+4. **测试下钻路径**：只有通过带过滤的查询，才能验证下钻逻辑是否可行
+
+**数据探查时的过滤条件示例：**
+
+```javascript
+// ✅ 正确：数据探查时带上时间范围过滤
+{
+  dimension: 'date',
+  operator: 'BETWEEN',
+  values: ['2025-01-01', '2025-01-31']
+}
+
+// ✅ 正确：数据探查时带上分类维度过滤
+{
+  dimension: 'region',
+  operator: 'IN',
+  values: ['north', 'south']
+}
+```
+
+**OrderBy 项结构：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `field` | `string` | ✅ | 排序字段，一般为响应中的列名（如指标名或 groupBy 中的维度/粒度表达式） |
+| `direction` | `string` | ✅ | `"ASC"`（升序）或 `"DESC"`（降序） |
+
+**时间粒度表达式：**
+
+**仅用于 `groupBy`**（决定数据如何分组聚合）：
+
+| 表达式 | 说明 |
+|--------|------|
+| `{dimension}__day` | 按天分组 |
+| `{dimension}__week` | 按周分组 |
+| `{dimension}__month` | 按月分组 |
+| `{dimension}__quarter` | 按季度分组 |
+| `{dimension}__year` | 按年分组 |
+
+**⚠️ 重要区别：**
+
+- **`groupBy`**：可以使用粒度表达式（如 `date__month`）
+- **`filters.dimension`**：必须使用**原始维度字段**（如 `date`），不能用粒度表达式
+
+**正确示例：**
+
+```javascript
+// ✅ 正确：groupBy 使用粒度表达式
+query: {
+  metrics: ['sales'],
+  groupBy: ['date__month'],     // 按月分组
+  filters: [{
+    dimension: 'date',          // 使用原始维度字段
+    operator: 'BETWEEN',
+    values: ['2025-01-01', '2025-12-31']
+  }]
+}
+
+// ❌ 错误：filters 中使用粒度表达式
+query: {
+  filters: [{
+    dimension: 'date__year',    // 错误！不能用粒度表达式
+    operator: 'EQ',
+    values: ['2025']
+  }]
+}
+```
+
+> **⚠️ 重要提醒：日期过滤必须使用 `BETWEEN` 操作符**
+> 
+> 查询日期范围时，必须使用 `BETWEEN` 操作符，并提供具体的起始和结束日期。
+> 
+> **❌ 错误示例：**
+> ```javascript
+> // 不要用 EQ 查询年份
+> {
+>   dimension: 'date__year',
+>   operator: 'EQ',
+>   values: ['2025']  // 错误！
+> }
+> ```
+> 
+> **✅ 正确示例：**
+> ```javascript
+> // 使用 BETWEEN 查询具体日期范围
+> {
+>   dimension: 'date',
+>   operator: 'BETWEEN',
+>   values: ['2025-01-01', '2025-12-31']  // 正确！
+> }
+> 
+> // 查询 2025 年 Q1
+> {
+>   dimension: 'date',
+>   operator: 'BETWEEN',
+>   values: ['2025-01-01', '2025-03-31']
+> }
+> 
+> // 查询最近 30 天
+> {
+>   dimension: 'date',
+>   operator: 'BETWEEN',
+>   values: ['2025-01-01', '2025-01-31']
+> }
+> ```
+> 
+> **原因：** 日期在底层存储通常是时间戳或日期类型，使用 `EQ` 匹配年份字符串会导致查询失败。`BETWEEN` 操作符会在 SQL 中生成 `date >= 'start' AND date <= 'end'`，能正确处理日期范围。
+
+### 1.3 基于数据探查结果设计 Dashboard
+
+**在完成数据探查后，回答以下问题：**
+
+| 问题 | 决策依据 | Dashboard 配置 |
+|------|---------|---------------|
+| 哪些指标作为 KPI 展示？ | 核心业务指标、领导关注的关键数据 | 使用 `type: 'kpi'` |
+| 哪些指标用于趋势分析？ | 时间序列数据、需要观察变化的指标 | 使用 `type: 'line'` |
+| 哪些维度用于对比分析？ | 分类数据、需要横向比较的维度 | 使用 `type: 'bar'` 或 `type: 'pie'` |
+| 哪些维度支持下钻？ | 有层级关系的维度（如年→月→日） | 配置 `emit` 和 `receiveFilters` |
+| 需要什么过滤条件？ | 常用的筛选维度（地区、产品类型等） | 配置 `filters` |
+
+**⚠️ 重要：所有设计决策必须基于实际查询结果**
+
+- 不要假设某个指标存在，必须先查询确认
+- 不要假设维度有数据，必须带过滤条件测试
+- 不要假设时间粒度可用，必须查看 meta 中的 `time_granularities`
+
+### 1.4 确定图表类型
+
+根据数据探查结果选择图表类型：
+
+| 数据特征 | 推荐图表类型 | 说明 |
+|---------|------------|------|
+| 时间序列 + 数值 | line, bar | 趋势分析 |
+| 分类 + 数值对比 | bar, pie | 对比分析 |
+| 占比关系 | pie | 构成分析 |
+| 单指标展示 | kpi | 关键指标卡片 |
+| 详细数据 | table | 表格展示（支持分页） |
+
+---
+
+## 步骤 2：设计看板布局
+
+### 2.1 网格系统
+
+使用 Tailwind CSS 的 12 列网格：
+
+```
+col-span-12    - 全宽（趋势图、表格）
+col-span-6     - 半宽（对比图、饼图）
+col-span-4     - 1/3 宽（KPI）
+col-span-3     - 1/4 宽（小卡片）
+```
+
+### 2.2 布局示例
+
+**联动型看板：**
+```
+┌─────────────────────────────────────┐
+│ [年份过滤器] → emitsToState: year    │
+├──────────┬──────────────────────────┤
+│ 年度饼图  │      月度柱状图           │
+│ (emit)   │    (receiveFilters)      │
+│ 点击年份  │  接收 year 状态并过滤     │
+└──────────┴──────────────────────────┘
+```
+
+---
+
+## 步骤 3：配置 Widgets
+
+### 3.1 基础配置模板
+
+```javascript
+{
+  id: 'unique-id',              // 必填：唯一标识
+  title: '图表标题',             // 必填：显示标题
+  type: 'line',                 // 必填：图表类型
+  gridClass: 'col-span-12',     // 可选：网格类
+  containerId: 'chart-id',      // 可选：外部容器 ID（用于自定义 HTML 布局）
+  
+  query: {                      // 必填：查询配置
+    // serverKey 和 datasourceId 可选，默认使用 SDK 配置
+    metrics: ['metric_name'],
+    groupBy: ['dimension']
+  },
+  
+  mapping: {                    // 必填：数据映射
+    xAxis: 'dimension',
+    yAxis: ['metric_name']
+  },
+  
+  // 可选：接收全局过滤器
+  receiveFilters: [{
+    fromState: 'selected_year',
+    mapToDimension: 'date',        // 映射到原始维度字段，不是粒度表达式
+    operator: 'BETWEEN',           // 日期范围使用 BETWEEN
+    ignoreIfEmpty: true
+  }],
+  
+  // 可选：点击发射状态
+  emit: [{
+    event: 'click',
+    extractValueFrom: 'dimension',
+    updateState: 'drill_state'
+  }]
+}
+```
+
+---
+
+### 3.2 图表类型配置示例
+
+#### 折线图（趋势）
+
+```javascript
+{
+  id: 'trend-chart',
+  title: '销售趋势',
+  type: 'line',
+  gridClass: 'col-span-12',
+  query: {
+    serverKey: 'prod',
+    datasourceId: '1',
+    metrics: ['sales_amt'],
+    groupBy: ['date__month']
+  },
+  mapping: {
+    xAxis: 'date__month',
+    yAxis: ['sales_amt']
+  },
+  receiveFilters: [{
+    fromState: 'selected_year',
+    mapToDimension: 'date',        // 映射到原始维度字段
+    operator: 'BETWEEN',           // 日期范围使用 BETWEEN
+    ignoreIfEmpty: true
+  }]
+}
+```
+
+#### 柱状图（对比）
+
+```javascript
+{
+  id: 'bar-chart',
+  title: '门店对比',
+  type: 'bar',
+  gridClass: 'col-span-6',
+  query: {
+    serverKey: 'prod',
+    datasourceId: '1',
+    metrics: ['sales_amt'],
+    groupBy: ['shop']
+  },
+  mapping: {
+    xAxis: 'shop',
+    yAxis: ['sales_amt']
+  }
+}
+```
+
+#### 饼图（占比 + 点击下钻）
+
+```javascript
+{
+  id: 'yearly-pie',
+  title: '年度占比（点击下钻）',
+  type: 'pie',
+  gridClass: 'col-span-6',
+  query: {
+    serverKey: 'prod',
+    datasourceId: '1',
+    metrics: ['sales_amt'],
+    groupBy: ['date__year']
+  },
+  mapping: {
+    name: 'date__year',
+    value: 'sales_amt'
+  },
+  emit: [{
+    event: 'click',
+    extractValueFrom: 'date__year',
+    updateState: 'drill_year'
+  }]
+}
+```
+
+#### KPI 卡片
+
+```javascript
+{
+  id: 'kpi-sales',
+  title: '总销售额',
+  type: 'kpi',
+  gridClass: 'col-span-3',
+  query: {
+    serverKey: 'prod',
+    datasourceId: '1',
+    metrics: ['sales_amt']
+  },
+  mapping: {
+    value: 'sales_amt',
+    valueFormat: 'currency_cny'
+  }
+}
+```
+
+#### 表格（支持分页和点击）
+
+```javascript
+{
+  id: 'detail-table',
+  title: '销售明细',
+  type: 'table',
+  gridClass: 'col-span-12',
+  query: {
+    serverKey: 'prod',
+    datasourceId: '1',
+    metrics: ['sales', 'profit'],
+    groupBy: ['product', 'region']
+  },
+  tableConfig: {
+    pageSize: 10,
+    align: 'left',
+    columnFormats: {
+      'sales': 'currency_cny',
+      'profit': 'currency_cny'
+    }
+  },
+  emit: [{
+    event: 'click',
+    extractValueFrom: 'product',
+    updateState: 'selected_product'
+  }]
+}
+```
+
+---
+
+## 步骤 4：配置 Filters（全局过滤器）
+
+### 4.1 基础过滤器
+
+**分类维度过滤器（如区域、产品类型）：**
+
+```javascript
+{
+  id: 'region',
+  label: '区域',
+  dimension: 'region',           // 使用原始维度字段
+  operator: 'EQ',
+  defaultValue: 'ALL',
+  options: [
+    { value: 'ALL', text: '全部' },
+    { value: 'north', text: '华北' },
+    { value: 'south', text: '华南' }
+  ],
+  emitsToState: 'selected_region'
+}
+```
+
+**日期过滤器：**
+
+日期过滤器比较特殊，选择后需要将年份转换为日期范围：
+
+```javascript
+{
+  id: 'year',
+  label: '年份',
+  dimension: 'date',             // 使用原始维度字段
+  operator: 'BETWEEN',           // 日期范围使用 BETWEEN
+  defaultValue: 'ALL',
+  options: [
+    { value: 'ALL', text: '全部' },
+    { value: '2025-01-01,2025-12-31', text: '2025年' },    // 值是日期范围
+    { value: '2024-01-01,2024-12-31', text: '2024年' },
+    { value: '2023-01-01,2023-12-31', text: '2023年' }
+  ],
+  emitsToState: 'selected_year'   // 选择后写入全局状态（值是日期范围字符串）
+}
+```
+
+**注意：** 日期过滤器的 `options.value` 是逗号分隔的日期范围，这样 `receiveFilters` 可以直接使用：
+
+```javascript
+// 在 receiveFilters 中处理日期范围
+receiveFilters: [{
+  fromState: 'selected_year',
+  mapToDimension: 'date',
+  operator: 'BETWEEN',
+  ignoreIfEmpty: true
+  // 当选择 "2025-01-01,2025-12-31" 时，会自动解析为 BETWEEN 查询
+}]
+```
+
+### 4.2 过滤器工作原理
+
+1. 用户选择过滤器值
+2. 值通过 `emitsToState` 写入全局状态池
+3. 订阅该状态的图表收到通知
+4. 自动刷新并应用过滤条件
+
+---
+
+## 步骤 5：完整联动示例
+
+### 跨粒度联动（年度 → 月度）
+
+```javascript
+const config = {
+  filters: [
+    {
+      id: 'year',
+      label: '年份',
+      dimension: 'date',                      // 使用原始维度字段
+      operator: 'BETWEEN',                    // 日期范围使用 BETWEEN
+      defaultValue: 'ALL',
+      options: [
+        { value: 'ALL', text: '全部年份' },
+        { value: '2024-01-01,2024-12-31', text: '2024年' },  // 日期范围
+        { value: '2023-01-01,2023-12-31', text: '2023年' }
+      ],
+      emitsToState: 'selected_year'           // 写入全局状态（值是日期范围）
+    }
+  ],
+  widgets: [
+    {
+      id: 'yearly-pie',
+      type: 'pie',
+      title: '年度销售占比（点击下钻）',
+      gridClass: 'col-span-6',
+      query: {
+        serverKey: 'sales',
+        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: '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. 点击饼图的某个年份 → 柱状图显示该年份的月度数据
+
+---
+
+## 步骤 6：解决字段不一致
+
+当不同数据源使用不同字段名时，使用 `mapToDimension`：
+
+```javascript
+// 全局过滤器
+filters: [{
+  id: 'region',
+  emitsToState: 'selected_region'    // 全局状态名
+}]
+
+// Widget A - 销售数据（字段名：region）
+widgets: [{
+  receiveFilters: [{
+    fromState: 'selected_region',
+    mapToDimension: 'region',         // 映射到 'region'
+    operator: 'EQ'
+  }]
+}]
+
+// Widget B - 库存数据（字段名：warehouse_location）
+widgets: [{
+  receiveFilters: [{
+    fromState: 'selected_region',
+    mapToDimension: 'warehouse_location',  // 映射到 'warehouse_location'
+    operator: 'EQ'
+  }]
+}]
+```
+
+---
+
+## 步骤 7：生成完整 HTML
+
+### 7.1 HTML 模板
+
+#### 方案 A：零 HTML 自动渲染（推荐）
+
+**最简单的用法 - 只需要一个空 body：**
+
+SDK 会自动创建所有容器并渲染看板，无需编写任何 HTML 结构：
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<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>
+  <script>
+    const config = {
+      title: '数据看板',  // 可选：看板标题
+      filters: [
+        // ... 过滤器配置
+      ],
+      widgets: [
+        // ... 图表配置
+      ]
+    };
+
+    async function init() {
+      const sdk = new DataQuerySDK({
+        baseURL: 'http://localhost:4001',
+        serverKey: 'prod',
+        datasourceId: '1'
+      });
+      
+      const engine = new DashboardEngine(sdk, config);
+      await engine.init();
+    }
+
+    init().catch(console.error);
+  </script>
+</body>
+</html>
+```
+
+**自动创建的 DOM 结构：**
+
+```html
+<body>
+  <div id="dashboard-auto-container" class="max-w-7xl mx-auto px-4 py-8">
+    <h1 class="text-3xl font-bold text-gray-900 mb-8">数据看板</h1>
+    <div id="filters-container" class="mb-4"><!-- 过滤器 --></div>
+    <div id="dashboard-grid" class="grid grid-cols-12 gap-4">
+      <!-- 自动生成的图表卡片 -->
+    </div>
+  </div>
+</body>
+```
+
+#### 方案 B：使用 dashboard-grid 半自动布局
+
+如果你需要自定义看板标题或外层容器，但让 SDK 自动生成图表：
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<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 class="max-w-7xl mx-auto">
+    <h1 class="text-3xl font-bold mb-8">数据看板</h1>
+    
+    <!-- 过滤器容器 -->
+    <div id="filters-container" class="mb-4"></div>
+    
+    <!-- 看板网格 - SDK 会自动在此创建图表 -->
+    <div id="dashboard-grid" class="grid grid-cols-12 gap-4"></div>
+  </div>
+
+  <script>
+    const config = {
+      filters: [
+        // ... 过滤器配置
+      ],
+      widgets: [
+        // ... 图表配置
+      ]
+    };
+
+    async function init() {
+      const sdk = new DataQuerySDK({
+        baseURL: 'http://localhost:4001',
+        serverKey: 'prod',
+        datasourceId: '1'
+      });
+      
+      const engine = new DashboardEngine(sdk, config);
+      await engine.init();
+    }
+
+    init().catch(console.error);
+  </script>
+```
+
+#### 方案 C：使用外部容器自定义布局
+
+如果你需要完全自定义 HTML 结构，可以为每个 widget 指定 `containerId`：
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<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 class="max-w-7xl mx-auto">
+    <h1 class="text-3xl font-bold mb-8">数据看板</h1>
+    
+    <!-- 过滤器容器 -->
+    <div id="filters-container" class="mb-4"></div>
+    
+    <!-- 自定义布局 -->
+    <div class="grid grid-cols-1 lg:grid-cols-2 gap-6">
+      <!-- 出租率趋势图 -->
+      <div class="bg-white p-5 rounded-xl shadow-sm">
+        <h3 class="text-lg font-semibold mb-4">月度出租率趋势</h3>
+        <div id="occupancy-trend-chart" class="h-80"></div>
+      </div>
+      
+      <!-- 门店出租率对比 -->
+      <div class="bg-white p-5 rounded-xl shadow-sm">
+        <h3 class="text-lg font-semibold mb-4">各门店出租率对比</h3>
+        <div id="shop-occupancy-chart" class="h-80"></div>
+      </div>
+    </div>
+  </div>
+
+  <script>
+    const config = {
+      filters: [
+        // ... 过滤器配置
+      ],
+      widgets: [
+        {
+          id: 'occupancy-trend',
+          type: 'line',
+          title: '月度出租率趋势',
+          containerId: 'occupancy-trend-chart',  // 指向外部容器
+          // ... 其他配置
+        },
+        {
+          id: 'shop-occupancy',
+          type: 'bar',
+          title: '各门店出租率对比',
+          containerId: 'shop-occupancy-chart',   // 指向外部容器
+          // ... 其他配置
+        }
+      ]
+    };
+
+    async function init() {
+      const sdk = new DataQuerySDK({
+        baseURL: 'http://localhost:4001',
+        serverKey: 'prod',
+        datasourceId: '1'
+      });
+      
+      const engine = new DashboardEngine(sdk, config);
+      await engine.init();
+    }
+
+    init().catch(console.error);
+  </script>
+```
+
+**三种方案的区别：**
+
+| 特性 | 方案 A (零 HTML) | 方案 B (dashboard-grid) | 方案 C (外部容器) |
+|------|-----------------|------------------------|------------------|
+| HTML 要求 | 只需要空 body | 需要 dashboard-grid 容器 | 完全自定义 HTML |
+| 代码量 | 最少 | 中等 | 最多 |
+| 布局控制 | SDK 完全控制 | SDK 控制网格布局 | 完全自定义 |
+| 适用场景 | 快速原型、标准看板 | 标准看板、需要自定义标题 | 需要精确控制样式 |
+| 灵活性 | 低 | 中 | 高 |
+
+**容器查找优先级：**
+
+SDK 按以下顺序查找容器：
+
+1. **外部容器** (`config.containerId`) - 如果指定且存在
+2. **dashboard-grid** - 如果存在
+3. **自动创建** - 如果以上都不存在，SDK 自动创建完整容器
+
+**注意事项：**
+- 使用方案 C 时，必须确保 `containerId` 指向的 DOM 元素存在
+- 如果同时存在 `dashboard-grid` 和外部容器，优先使用外部容器
+- 自动创建模式下，可以通过 `config.title` 设置看板标题
+</body>
+</html>
+```
+
+---
+
+## 配置验证
+
+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);
+  });
+}
+```
+
+---
+
+## 最佳实践
+
+### 1. 数据真实性原则（强制）
+
+**🚫 严禁伪造数据**
+
+| 类型 | 是否可硬编码 | 说明 |
+|------|------------|------|
+| **筛选器选项** | ✅ 可以 | 静态值如年份列表、地区选项 |
+| **图表数据** | ❌ 禁止 | 必须通过 `query` 查询获取 |
+| **表格数据** | ❌ 禁止 | 必须通过 `query` 查询获取 |
+| **KPI 数值** | ❌ 禁止 | 必须通过 `query` 查询获取 |
+| **维度值** | ❌ 禁止 | 必须通过查询获取，不可假设 |
+
+**✅ 正确示例：**
+```javascript
+// 筛选器使用静态选项（允许）
+{
+  id: 'year',
+  label: '年份',
+  options: [
+    { value: '2024', text: '2024年' },  // ✅ 静态选项可以硬编码
+    { value: '2023', text: '2023年' }
+  ]
+}
+
+// 图表数据通过查询获取（必须）
+{
+  id: 'sales-chart',
+  type: 'line',
+  query: {
+    metrics: ['sales_amt'],  // ✅ 通过查询获取真实数据
+    groupBy: ['date__month']
+  }
+}
+```
+
+**❌ 错误示例：**
+```javascript
+// 禁止在配置中伪造数据
+{
+  id: 'sales-chart',
+  type: 'line',
+  data: [                    // ❌ 错误！禁止硬编码数据
+    { month: '1月', value: 100 },
+    { month: '2月', value: 200 }
+  ]
+}
+```
+
+### 2. 闭环校验原则
+
+确保每个 `emit.updateState` 都有对应的 `receiveFilters.fromState`：
+
+```javascript
+// ✅ 正确：emit 和 receive 配对
+emit: [{ updateState: 'drill_year' }]
+receiveFilters: [{ fromState: 'drill_year' }]
+
+// ❌ 错误：孤儿 emit（会报错）
+emit: [{ updateState: 'orphan_state' }]
+// 没有对应的 receiveFilters
+```
+
+### 3. 使用 ignoreIfEmpty
+
+```javascript
+receiveFilters: [{
+  fromState: 'selected_year',
+  mapToDimension: 'date',        // 映射到原始维度字段
+  operator: 'BETWEEN',           // 日期范围使用 BETWEEN
+  ignoreIfEmpty: true            // 当选择 "全部" 时不应用过滤
+}]
+```
+
+### 4. 响应式布局
+
+```javascript
+gridClass: 'col-span-12 md:col-span-6 lg:col-span-4'
+// 移动端：全宽
+// 平板：半宽
+// 桌面：1/3 宽
+```
+
+### 5. 错误处理
+
+```javascript
+engine.init().catch(err => {
+  console.error('看板初始化失败:', err);
+  document.getElementById('dashboard-grid').innerHTML = `
+    <div class="col-span-12 text-center text-red-500">
+      配置错误: ${err.message}
+    </div>
+  `;
+});
+```
+
+---
+
+## 常见问题
+
+### Q1: 图表不显示
+
+**排查步骤**：
+1. 检查浏览器控制台是否有错误
+2. 确认 ECharts 已加载
+3. 检查配置验证错误
+4. 确认容器元素存在
+
+### Q2: 联动不生效
+
+**排查步骤**：
+1. 检查 `emitsToState` 和 `fromState` 名称是否一致
+2. 确认 `mapToDimension` 字段名正确
+3. 检查是否设置了 `ignoreIfEmpty: true` 但状态为空
+4. 查看闭环校验错误
+
+### Q3: 字段不一致如何处理
+
+**解决方案**：使用 `mapToDimension` 映射：
+
+```javascript
+// 不同数据源使用相同的 fromState，但不同的 mapToDimension
+receiveFilters: [{
+  fromState: 'selected_region',
+  mapToDimension: 'region_code',  // 数据源 A 的字段
+  operator: 'EQ'
+}]
+```
+
+### Q4: 如何调试状态变化
+
+```javascript
+// 监听全局状态变化
+globalState.subscribe('selected_year', (newValue, oldValue) => {
+  console.log('年份变化:', oldValue, '->', newValue);
+});
+```
+
+---
+
+## 步骤 8：最终检查清单
+
+在提交 Dashboard 配置之前，必须完成以下检查：
+
+### 8.1 数据真实性检查
+
+- [ ] **所有图表数据通过查询获取**：确认每个 widget 的 `query` 字段配置正确，没有硬编码 `data` 字段
+- [ ] **所有表格数据通过查询获取**：确认 table 类型的 widget 使用 `query` 而非静态数据
+- [ ] **所有 KPI 数值通过查询获取**：确认 kpi 类型的 widget 使用 `query` 获取真实数据
+- [ ] **筛选器选项合理**：静态选项值符合业务逻辑，动态选项通过查询获取
+
+### 8.2 配置完整性检查
+
+- [ ] **所有 widget 有唯一 id**：没有重复的 widget id
+- [ ] **所有 widget 有 title**：每个图表都有显示标题
+- [ ] **所有 query 配置正确**：
+  - [ ] `serverKey` 和 `datasourceId` 已配置（或在 SDK 初始化时统一配置）
+  - [ ] `metrics` 数组不为空，且指标名来自数据探查结果
+  - [ ] `groupBy` 使用的维度名正确（区分原始字段和粒度表达式）
+- [ ] **所有 mapping 配置正确**：
+  - [ ] `xAxis`、`yAxis`、`name`、`value` 等字段名与 query 返回的列名匹配
+  - [ ] 日期字段使用正确的粒度表达式（如 `date__month`）
+
+### 8.3 联动机制检查
+
+- [ ] **闭环校验通过**：每个 `emit.updateState` 都有对应的 `receiveFilters.fromState`
+- [ ] **状态名称一致**：`emitsToState` 和 `fromState` 使用相同的命名
+- [ ] **字段映射正确**：`mapToDimension` 使用原始维度字段，不是粒度表达式
+- [ ] **日期过滤使用 BETWEEN**：所有日期范围过滤使用 `BETWEEN` 操作符
+
+### 8.4 HTML 文件检查
+
+- [ ] **依赖加载正确**：
+  ```html
+  <!-- 检查以下脚本是否按顺序加载 -->
+  <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>
+  ```
+- [ ] **容器元素存在**：确认 `filters-container` 和 `dashboard-grid` 元素在 HTML 中存在
+- [ ] **SDK 初始化正确**：
+  ```javascript
+  // 检查 baseURL、serverKey、datasourceId 配置
+  const sdk = new DataQuerySDK({
+    baseURL: 'http://localhost:4001',
+    serverKey: 'prod',
+    datasourceId: '1'
+  });
+  ```
+- [ ] **DashboardEngine 初始化**：确认 `engine.init()` 被调用且有错误处理
+
+### 8.5 数据探查验证
+
+- [ ] **所有指标已验证**：每个使用的指标都经过实际查询测试
+- [ ] **所有维度已验证**：每个使用的维度都经过带过滤条件的查询测试
+- [ ] **下钻路径已验证**：点击下钻的交互逻辑经过实际测试
+- [ ] **过滤条件已验证**：每个筛选器的选项值都经过查询确认
+
+### 8.6 常见错误排查
+
+如果检查失败，参考以下常见问题：
+
+| 检查项 | 常见错误 | 解决方案 |
+|--------|---------|---------|
+| 数据真实性 | 硬编码了示例数据 | 删除 `data` 字段，使用 `query` 查询 |
+| 配置完整性 | 缺少 `title` 或 `id` | 为每个 widget 添加必填字段 |
+| 联动机制 | 状态名称不匹配 | 统一 `emitsToState` 和 `fromState` 的命名 |
+| HTML 加载 | 脚本加载顺序错误 | 确保 Tailwind → ECharts → SDK 的顺序 |
+| 数据探查 | 指标名错误 | 重新查询 meta 确认指标名大小写 |
+
+---
+
+## 版本信息
+
+- **版本**: 3.0.0
+- **更新日期**: 2025-01-15
+- **重大变更**: 状态机架构、emit/receiveFilters 联动机制
+- **文件位置**: `http://localhost:4001/sdk/data-query-sdk.js`