@axiom-lattice/gateway 2.1.39 → 2.1.41

package/public/sdk/dashboard-single-file-spec.md

@@ -0,0 +1,357 @@
+# Single-File Dashboard Specification (Data Query SDK v3.0 + ECharts 5.x)
+
+**Role:** Senior Data Visualization Expert & Frontend Architect (SDK Deep Integration)
+
+**Objective:** Generate a complete, interactive, runnable single-file Dashboard based on Data Query SDK v3.0 and ECharts 5.x, with modern SaaS visual quality.
+
+---
+
+## 1. SDK Technical Specification (Must Strictly Follow)
+
+### 1.1 Resource Inclusion (Required)
+
+In the generated HTML file, the SDK script **must** be included first among script tags:
+
+```html
+<script src="http://localhost:4001/sdk/data-query-sdk.js"></script>
+```
+
+### 1.2 Class Definition and Initialization
+
+```javascript
+const sdk = new DataQuerySDK({
+  baseURL: 'http://localhost:4001',
+  serverKey: 'prod',
+  datasourceId: '1'
+});
+```
+
+### 1.3 Method Signature: `sdk.query(params)`
+
+**Input `params` structure:**
+
+| Field     | Type     | Required | Description |
+|----------|----------|----------|-------------|
+| `metrics` | `string[]` | ✅ | e.g. `['sales_amt', 'order_cnt']` |
+| `groupBy` | `string[]` | ❌ | Dimension names or granularity expressions: `date__day`, `region` |
+| `filters` | `Array<{dimension: string, operator: string, values: any[]}>` | ❌ | Filter conditions |
+| `orderBy` | `Array<{field: string, direction: 'ASC'\|'DESC'}>` | ❌ | Sort rules |
+| `limit`   | `number`  | ❌ | 1–20000 |
+
+**Core rules:**
+
+- **Do not** use granularity expressions in `filters` (e.g. `date__month`); use **raw dimension names** only (e.g. `date`).
+- For date filtering, use `operator: 'BETWEEN'` and `values: ['YYYY-MM-DD', 'YYYY-MM-DD']`.
+
+### 1.4 Response Structure
+
+SDK returns a Promise resolving to:
+
+```json
+{
+  "code": 200,
+  "data": {
+    "columns": [
+      { "name": "date__month", "type": "date" },
+      { "name": "sales_amt", "type": "numeric" }
+    ],
+    "rows": [
+      ["2025-01-01", 150000],
+      ["2025-02-01", 180000]
+    ]
+  }
+}
+```
+
+---
+
+## 2. Data Adaptation and ECharts Configuration Patterns
+
+### 2.1 Universal Adapter Function
+
+Generated code **must** include this function to convert SDK data into ECharts `dataset.source` format:
+
+```javascript
+function adaptToECharts(sdkResponse) {
+  const header = sdkResponse.data.columns.map(c => c.name);
+  return [header, ...sdkResponse.data.rows];
+}
+```
+
+### 2.2 Pattern A: KPI Sparkline (Mini Trend)
+
+Use for **Tier 1**. Hide axes to emphasize trend.
+
+```javascript
+const sparklineOption = {
+  dataset: { source: adaptToECharts(sdkData) },
+  xAxis: { type: 'category', show: false },
+  yAxis: { type: 'value', show: false },
+  series: [{ type: 'line', smooth: true, areaStyle: { opacity: 0.1 }, symbol: 'none' }]
+};
+```
+
+### 2.3 Pattern B: Multi-Series Stacked Area Chart
+
+Use for **Tier 2**. Show dimension breakdown (e.g. region) over time.
+
+```javascript
+const trendOption = {
+  dataset: { source: adaptToECharts(sdkData) },
+  tooltip: { trigger: 'axis' },
+  legend: {},
+  xAxis: { type: 'category' },
+  yAxis: { type: 'value' },
+  series: [{ type: 'line', stack: 'Total', areaStyle: {}, smooth: true }]
+};
+```
+
+### 2.4 Pattern C: Dimension Ranking Bar Chart
+
+Use for **Tier 3**. Top N by dimension.
+
+```javascript
+const barOption = {
+  dataset: { source: adaptToECharts(sdkData) },
+  xAxis: { type: 'value' },
+  yAxis: { type: 'category' },
+  series: [{ type: 'bar', encode: { x: 'sales_amt', y: 'shop_name' } }]
+};
+```
+
+---
+
+## 3. Dashboard Architecture (Tiered Layout)
+
+### Tier 1: Hero Metrics (Top)
+
+- **Components:** Large KPI cards + mini ECharts sparklines.
+- **Logic:** Query last 30 days totals, with or without daily `groupBy`.
+
+### Tier 2: Driver Trends (Middle)
+
+- **Components:** ECharts stacked area or grouped bar charts.
+- **Logic:** Dimension trends; handle multi-series (e.g. Region over time).
+
+### Tier 3: Diagnostic Details (Bottom)
+
+- **Components:** Data table with heat gradient or heatmap.
+- **Logic:** Use `limit: 100` and `orderBy` for root-cause analysis.
+
+---
+
+## 4. Interaction and Linkage
+
+### 4.1 Global Filters
+
+Implement a UI with:
+
+- Date range picker.
+- Dimension selector(s) (e.g. region, category).
+
+### 4.2 Chart Click Linkage
+
+Listen to ECharts `click` and sync with global filter:
+
+```javascript
+chart.on('click', (params) => {
+  const selectedDim = params.name;
+  // Update global filter state, then call refreshAllCharts()
+});
+```
+
+---
+
+## 5. Output Format and Code Rules
+
+- **Single file:** One complete `.html` file including CSS and all JS.
+- **Resources:** Include the SDK script URL specified above.
+- **Robustness:** Implement simple exponential-backoff retry for SDK calls.
+- **Visual:** Clean business style, rounded corners, ample whitespace.
+
+---
+
+## 6. Visual Enhancement Specification (Modern SaaS Quality)
+
+Generated dashboards **must** apply the following to achieve a modern, professional SaaS look. Do not remove or simplify the above SDK/data/tier/interaction requirements; add these on top.
+
+### 6.1 Icon Library: Lucide Icons
+
+- **Include:** Lucide Icons via CDN (e.g. `https://unpkg.com/lucide@latest` or `lucide-static` script).
+- **Usage:** Use `data-lucide` attribute on elements; call `lucide.createIcons()` after DOM updates.
+- **Where:** KPI cards (e.g. `data-lucide="trending-up"`, `data-lucide="dollar-sign"`, `data-lucide="bar-chart-2"`), filter bar (e.g. `data-lucide="calendar"`, `data-lucide="filter"`), and section headers where appropriate.
+- **Effect:** Clear visual cues and consistent “app” feel.
+
+### 6.2 Typography: Google Fonts (Inter or Equivalent)
+
+- **Include:** One primary font from Google Fonts (e.g. Inter) in `<head>`:
+  ```html
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+  ```
+- **Apply:** Set `font-family: 'Inter', sans-serif` (or chosen font) on `body` or a root container.
+- **Effect:** Improved readability and professional typography vs. system defaults.
+
+### 6.3 UI Style: Shadcn-Inspired (Tailwind)
+
+- **Refined radius:** Use consistent rounded corners (e.g. `rounded-lg` / `rounded-xl` for cards, `rounded-md` for inputs and buttons).
+- **Shadows:** Subtle elevation: e.g. `shadow-sm` for inputs, `shadow` or `shadow-md` for cards; avoid heavy flat blocks.
+- **Borders:** Light borders where needed (e.g. `border border-gray-200/80` or `border-border` if using CSS variables); optional subtle ring on focus for inputs/buttons.
+- **Color:** Neutral background (e.g. `bg-slate-50` or `bg-gray-50`), white or near-white cards; accent for primary actions (e.g. blue or brand color); success/warning/danger for KPI deltas and status.
+- **Effect:** Cohesive, polished component look similar to Shadcn UI.
+
+### 6.4 Glass-Card / Layered Cards
+
+- **Concept:** Optional “glass” effect for key cards: semi-transparent background with backdrop blur (e.g. `bg-white/80 dark:bg-white/90 backdrop-blur-sm`) and a subtle border (e.g. `border border-white/20` or `border-gray-200/60`).
+- **Where:** Tier 1 KPI cards and/or the filter bar; keep tables and dense charts on solid backgrounds for readability.
+- **Effect:** Light, modern layering and depth without clutter.
+
+### 6.5 Loading States
+
+- **During data fetch:** Show loading state for each tier (or per widget) instead of blank space.
+  - **Options:** Skeleton placeholders (e.g. animated `bg-gray-200` / `animate-pulse` for numbers and chart areas), or a small spinner with “Loading…” text.
+- **Placement:** Same layout as final content (e.g. skeleton height similar to sparkline, table rows, or chart container).
+- **Clear transition:** When data arrives, replace loading UI with real content; avoid flash of wrong layout.
+- **Effect:** Clear feedback and perceived performance.
+
+### 6.6 Responsive Layout (Tailwind)
+
+- **Breakpoints:** Use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`) for grid and flex:
+  - Tier 1: e.g. 1 column on mobile, 2–4 columns on larger screens.
+  - Tier 2: Full width or 2-column grid on large screens.
+  - Tier 3: Horizontal scroll for wide tables when needed (`overflow-x-auto`).
+- **Touch:** Ensure buttons and filters are comfortably tappable; charts should resize on `window.resize` (ECharts `resize()`).
+- **Effect:** Usable and refined on all screen sizes.
+
+### 6.7 Summary Checklist
+
+| Item            | Requirement |
+|-----------------|------------|
+| Lucide Icons    | Included; `data-lucide` + `lucide.createIcons()` on KPI/filters/headers |
+| Google Font     | Inter or equivalent; applied to body |
+| Shadcn-style    | Rounded corners, subtle shadows, light borders, neutral + accent palette |
+| Glass-card      | Optional glass effect on hero/filter cards |
+| Loading states  | Skeleton or spinner per section while loading |
+| Responsive      | Tailwind breakpoints; ECharts resize on resize |
+
+---
+
+## 7. Complete Code Example (Reference Paradigm)
+
+The following is a minimal reference that satisfies **Sections 1–5** and aligns with **Section 6**. Expand with full Tier 2/3 and all visual enhancements as specified above.
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>业务监控看板</title>
+  <!-- Google Font -->
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <!-- Tailwind -->
+  <script src="https://cdn.tailwindcss.com"></script>
+  <script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>
+  <!-- Lucide Icons -->
+  <script src="https://unpkg.com/lucide@latest"></script>
+  <!-- Required: SDK -->
+  <script src="http://localhost:4001/sdk/data-query-sdk.js"></script>
+  <style>
+    body { font-family: 'Inter', sans-serif; background-color: #f8fafc; }
+    .card { background: white; border-radius: 12px; padding: 20px; box-shadow: 0 1px 3px rgb(0 0 0 / 0.08); border: 1px solid rgb(0 0 0 / 0.06); }
+    .glass-card { background: rgba(255,255,255,0.85); backdrop-filter: blur(8px); border-radius: 12px; border: 1px solid rgba(0,0,0,0.06); }
+    .skeleton { background: linear-gradient(90deg, #f1f5f9 25%, #e2e8f0 50%, #f1f5f9 75%); background-size: 200% 100%; animation: skeleton 1.5s ease-in-out infinite; }
+    @keyframes skeleton { 0% { background-position: 200% 0; } 100% { background-position: -200% 0; } }
+  </style>
+</head>
+<body class="p-6">
+  <!-- Global filters -->
+  <div class="flex flex-wrap gap-4 mb-6 p-4 rounded-xl shadow-sm glass-card">
+    <div>
+      <label class="block text-xs text-gray-500 mb-1"><i data-lucide="calendar" class="inline w-3.5 h-3.5"></i> 日期范围</label>
+      <input type="date" id="start" class="border border-gray-200 rounded-lg px-3 py-2 text-sm" value="2025-01-01">
+      <input type="date" id="end" class="border border-gray-200 rounded-lg px-3 py-2 text-sm ml-1" value="2025-01-31">
+    </div>
+    <button onclick="refresh()" class="bg-blue-600 text-white px-6 py-2 rounded-lg self-end hover:bg-blue-700 transition flex items-center gap-2">
+      <i data-lucide="refresh-cw" class="w-4 h-4"></i> 查询数据
+    </button>
+  </div>
+
+  <div class="grid grid-cols-1 md:grid-cols-3 gap-6 mb-6">
+    <!-- Tier 1: KPI + Sparkline -->
+    <div class="card">
+      <h3 class="text-gray-500 text-sm flex items-center gap-1"><i data-lucide="trending-up" class="w-4 h-4"></i> 核心营收 (GMV)</h3>
+      <div id="kpi-value-1" class="text-3xl font-bold my-2 text-slate-800">¥0</div>
+      <div id="sparkline-1" style="height: 60px;"></div>
+    </div>
+    <!-- More KPI cards... -->
+  </div>
+
+  <!-- Tier 2: Trend -->
+  <div class="card mb-6">
+    <h3 class="font-bold mb-4 flex items-center gap-2"><i data-lucide="bar-chart-2" class="w-5 h-5"></i> 月度地区销售趋势</h3>
+    <div id="trend-chart" style="height: 400px;"></div>
+  </div>
+
+  <!-- Tier 3: Table -->
+  <div class="card">
+    <h3 class="font-bold mb-4 flex items-center gap-2"><i data-lucide="table" class="w-5 h-5"></i> 店铺表现明细 (Top 50)</h3>
+    <div class="overflow-x-auto">
+      <table id="detail-table" class="w-full text-left">
+        <thead>
+          <tr class="border-b text-gray-400 text-sm"><th class="pb-2">店铺名称</th><th class="pb-2">销售额</th><th class="pb-2">订单数</th></tr>
+        </thead>
+        <tbody class="text-slate-700"></tbody>
+      </table>
+    </div>
+  </div>
+
+  <script>
+    const sdk = new DataQuerySDK({ baseURL: 'http://localhost:4001', serverKey: 'prod', datasourceId: '1' });
+    const adaptToECharts = (res) => [res.data.columns.map(c => c.name), ...res.data.rows];
+
+    async function refresh() {
+      lucide.createIcons();
+      const start = document.getElementById('start').value;
+      const end = document.getElementById('end').value;
+      const timeFilter = { dimension: 'date', operator: 'BETWEEN', values: [start, end] };
+      try {
+        const kpiRes = await sdk.query({ metrics: ['sales_amt'], groupBy: ['date__day'], filters: [timeFilter] });
+        renderKPI(kpiRes);
+        const trendRes = await sdk.query({ metrics: ['sales_amt'], groupBy: ['date__month', 'region'], filters: [timeFilter] });
+        renderTrend(trendRes);
+        const tableRes = await sdk.query({ metrics: ['sales_amt', 'order_cnt'], groupBy: ['shop_name'], filters: [timeFilter], orderBy: [{ field: 'sales_amt', direction: 'DESC' }], limit: 50 });
+        renderTable(tableRes);
+      } catch (err) { console.error("数据请求失败", err); }
+    }
+
+    function renderTrend(res) {
+      const chart = echarts.init(document.getElementById('trend-chart'));
+      chart.setOption({
+        dataset: { source: adaptToECharts(res) },
+        tooltip: { trigger: 'axis' },
+        xAxis: { type: 'category' },
+        yAxis: { type: 'value' },
+        series: [{ type: 'line', stack: 'Total', areaStyle: {}, smooth: true }]
+      });
+    }
+
+    function renderTable(res) {
+      const tbody = document.querySelector('#detail-table tbody');
+      tbody.innerHTML = res.data.rows.map(row =>
+        `<tr class="border-b"><td class="py-3">${row[0]}</td><td>¥${row[1]}</td><td>${row[2]}</td></tr>`
+      ).join('');
+    }
+
+    window.onload = () => { lucide.createIcons(); refresh(); };
+  </script>
+</body>
+</html>
+```
+
+---
+
+**Summary:** Follow Sections 1–5 for SDK, data, layout, and interaction. Apply Section 6 for Lucide, Inter, Shadcn-style, glass-card, loading states, and responsive behavior. Use Section 7 as a minimal reference; full implementations should include retry logic, chart click linkage, and all three tiers with the enhanced visuals above.

package/public/sdk/data-query-sdk-skill.md

@@ -0,0 +1,307 @@
+---
+name: data-query-sdk
+description: Use when using Data Query SDK v3.0 to query metrics data, build filters, or construct data queries for dashboards and reports
+---
+
+# Data Query SDK v3.0
+
+## Overview
+
+Data Query SDK 用于从指标服务器查询数据，支持多维度分组、过滤、排序等操作。
+
+**核心功能：**
+- 指标查询（metrics）
+- 维度分组（groupBy）
+- 过滤条件（filters）
+- 排序规则（orderBy）
+
+---
+
+## 初始化
+
+```javascript
+const sdk = new DataQuerySDK({
+  baseURL: 'http://localhost:4001',
+  serverKey: 'prod',        // 指标服务器 key
+  datasourceId: '1'         // 数据源 ID
+});
+```
+
+---
+
+## Query 结构
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `serverKey` | `string` | ✅ | 指标服务器 key |
+| `datasourceId` | `string` | ✅ | 数据源 ID |
+| `metrics` | `string[]` | ✅ | 指标名列表，来自 meta 中的 metric name |
+| `groupBy` | `string[]` | ❌ | 分组维度，可为维度名或粒度表达式 |
+| `filters` | `object[]` | ❌ | 过滤条件数组 |
+| `orderBy` | `object[]` | ❌ | 排序规则数组 |
+| `limit` | `integer` | ❌ | 返回行数上限 [1, 20000] |
+| `debug` | `boolean` | ❌ | 为 true 时返回 debug 信息 |
+
+---
+
+## 时间粒度表达式
+
+**仅用于 `groupBy`**：
+
+| 表达式 | 说明 |
+|--------|------|
+| `{dimension}__day` | 按天分组 |
+| `{dimension}__week` | 按周分组 |
+| `{dimension}__month` | 按月分组 |
+| `{dimension}__quarter` | 按季度分组 |
+| `{dimension}__year` | 按年分组 |
+
+**⚠️ 重要区别：**
+- `groupBy`：可以使用粒度表达式（如 `date__month`）
+- `filters.dimension`：必须使用**原始维度字段**（如 `date`）
+
+---
+
+## 过滤条件
+
+### Filter 结构
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `dimension` | `string` | ✅ | 维度名，须与 meta 中定义一致 |
+| `operator` | `string` | ✅ | 操作符，见下方列表 |
+| `values` | `string[]` | 依操作符 | 用于比较的值 |
+
+### 支持的操作符
+
+| 操作符 | 说明 | 适用场景 |
+|--------|------|----------|
+| `EQ` | 等于（=） | 精确匹配单个值 |
+| `NEQ` | 不等于（!=） | 排除单个值 |
+| `IN` | 包含在列表中 | 匹配多个值中的任意一个 |
+| `NOT_IN` | 不包含在列表中 | 排除多个值 |
+| `BETWEEN` | 范围（闭区间） | 时间范围、数值范围，values 为 `[min, max]` |
+| `GT` | 大于（>） | 数值比较 |
+| `GTE` | 大于等于（>=） | 数值比较 |
+| `LT` | 小于（<） | 数值比较 |
+| `LTE` | 小于等于（<=） | 数值比较 |
+| `LIKE` | 模糊匹配 | 字符串匹配，支持 `%` 通配符 |
+| `ILIKE` | 模糊匹配（不区分大小写） | 字符串匹配 |
+| `IS_NULL` | 为空 | 检查空值，values 可省略 |
+| `IS_NOT_NULL` | 不为空 | 检查非空值，values 可省略 |
+
+---
+
+## 排序规则
+
+### OrderBy 结构
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `field` | `string` | ✅ | 排序字段，一般为响应中的列名 |
+| `direction` | `string` | ✅ | `"ASC"` 或 `"DESC"` |
+
+---
+
+## 返回数据格式
+
+### 响应体结构（通用）
+
+**外壳**：
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": { ... }
+}
+```
+
+### `data` 结构（指标查询结果）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `semanticModel` | `string` | 命中的语义模型名称，与 meta 中一致 |
+| `columns` | `array` | 列元信息，每项 `{ "name": "<列名>", "type": "<数据类型>" }`。列顺序与 `rows` 中每行元素一一对应 |
+| `rows` | `array` | 行数组，每行为**与 columns 同序**的值数组（非对象） |
+| `rowsObject` | `array` | 行数组（对象格式），每行是一个对象，键为列名，值为对应数据 |
+| `debug` | `object` \| `null` | 仅当请求中 `debug: true` 时存在，可含 `sql`、`params` 等执行信息 |
+
+**说明**：`columns[].name` 可能为维度粒度表达式（如 `date__month`）或指标名；具体列名与 meta 中维度和指标定义一致。
+
+### 完整示例
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "semanticModel": "sales_model",
+    "columns": [
+      { "name": "date__month", "type": "date" },
+      { "name": "sales_amt", "type": "numeric" }
+    ],
+    "rows": [
+      ["2025-01-01", 150000],
+      ["2025-02-01", 180000]
+    ],
+    "rowsObject": [
+      { "date__month": "2025-01-01", "sales_amt": 150000 },
+      { "date__month": "2025-02-01", "sales_amt": 180000 }
+    ],
+    "debug": null
+  }
+}
+```
+
+### 访问数据
+
+```javascript
+const result = await sdk.query({
+  metrics: ['sales_amt'],
+  groupBy: ['date__month']
+});
+
+// 访问返回数据（数组格式）
+console.log(result.data.columns);  // [{ name: 'date__month', type: 'date' }, ...]
+console.log(result.data.rows);     // [['2025-01-01', 150000], ...]
+console.log(result.data.rows[0][1]);  // 150000 (第一行的 sales_amt)
+
+// 访问返回数据（对象格式）
+console.log(result.data.rowsObject);  // [{ date__month: '2025-01-01', sales_amt: 150000 }, ...]
+console.log(result.data.rowsObject[0].sales_amt);  // 150000
+```
+
+---
+
+## 查询示例
+
+### 基础查询
+
+```javascript
+const result = await sdk.query({
+  metrics: ['sales_amt'],
+  groupBy: ['date__month']
+});
+
+// 访问返回数据（数组格式）
+console.log(result.data.rows);     // [['2025-01-01', 150000], ...]
+
+// 访问返回数据（对象格式）
+console.log(result.data.rowsObject);  // [{ date__month: '2025-01-01', sales_amt: 150000 }, ...]
+console.log(result.data.rows[0][1]);  // 150000 (第一行的 sales_amt)
+```
+
+### 带过滤条件
+
+```javascript
+const result = await sdk.query({
+  metrics: ['sales_amt'],
+  groupBy: ['date__month'],
+  filters: [{
+    dimension: 'date',
+    operator: 'BETWEEN',
+    values: ['2025-01-01', '2025-12-31']
+  }]
+});
+```
+
+### 多维度分组
+
+```javascript
+const result = await sdk.query({
+  metrics: ['sales_amt', 'order_cnt'],
+  groupBy: ['region', 'date__month'],
+  filters: [{
+    dimension: 'region',
+    operator: 'IN',
+    values: ['north', 'south']
+  }]
+});
+```
+
+### 带排序和限制
+
+```javascript
+const result = await sdk.query({
+  metrics: ['sales_amt'],
+  groupBy: ['shop'],
+  orderBy: [{
+    field: 'sales_amt',
+    direction: 'DESC'
+  }],
+  limit: 10
+});
+```
+
+---
+
+## 最佳实践
+
+### 日期过滤必须使用 BETWEEN
+
+```javascript
+// ❌ 错误：不要用 EQ 查询年份
+{
+  dimension: 'date__year',
+  operator: 'EQ',
+  values: ['2025']
+}
+
+// ✅ 正确：使用 BETWEEN 查询具体日期范围
+{
+  dimension: 'date',
+  operator: 'BETWEEN',
+  values: ['2025-01-01', '2025-12-31']
+}
+```
+
+### 字段映射一致性
+
+```javascript
+// ✅ 正确：filters 使用原始维度字段
+query: {
+  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']
+  }]
+}
+```
+
+### 数据探查原则
+
+1. **先查 meta**：了解可用的指标和维度
+2. **验证指标**：对每个候选指标执行实际查询
+3. **带过滤测试**：数据探查时必须带上过滤条件
+4. **确认数据格式**：验证维度值的真实格式
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 解决方案 |
+|------|------|----------|
+| 指标不存在 | 指标名拼写错误或大小写不匹配 | 检查 meta 中的指标定义 |
+| 维度不存在 | 维度名错误或该维度不支持 | 查看 meta 中的维度列表 |
+| 日期过滤无效 | 使用了 EQ 而不是 BETWEEN | 日期范围必须使用 BETWEEN |
+| 粒度表达式错误 | 在 filters 中使用了粒度表达式 | filters 必须使用原始维度字段 |
+| 返回空数据 | 过滤条件过于严格或无匹配数据 | 放宽过滤条件或检查数据范围 |
+
+---
+
+## 版本信息
+
+- **版本**: 3.0.0
+- **更新日期**: 2025-01-15
+- **SDK 文件**: `http://localhost:4001/sdk/data-query-sdk.js`