# 新版前端工作区图表开发文档

## 1. 技术选型

| 项目 | 选择 | 版本 |
|------|------|------|
| 图表引擎 | ECharts | ^6.0.0 |
| Vue 集成 | vue-echarts | ^8.0.1 |
| 渲染模式 | SVG（默认）+ Canvas 可选 |  |
| 状态管理 | Composable (useChartData) |  |

## 2. 组件架构

```
WorkspacePage.vue (chart block section)
  └── ChartRenderer.vue              (ECharts 图表渲染核心组件)
      └── vue-echarts (<v-chart>)    (ECharts Vue 封装)

composables/
  └── useChartData.ts                (图表数据获取 + 状态管理)
```

## 3. 后端 API 对齐

### 3.1 数据来源

| chart_type | API 方法 | 数据格式 |
|------------|----------|----------|
| Count/Sum/Average | `dashboard_chart.get` | `{ labels, datasets }` |
| Group By | `dashboard_chart.get` | `{ labels, datasets }` |
| Report | `query_report.run` | `{ result, columns, chart }` |
| Custom | 自定义 method | 自定义 |

### 3.2 标准数据格式

```typescript
// 后端返回的图表数据
interface ChartData {
  labels: string[]
  datasets: Array<{ name: string; values: number[] }>
}

// Heatmap 数据
interface HeatmapData {
  labels: string[]
  dataPoints: Record<number, number>  // timestamp -> value
}
```

### 3.3 Dashboard Chart 配置 (chart_pg)

```typescript
interface DashboardChartConfig {
  name: string
  chart_name: string
  chart_type: 'Count' | 'Sum' | 'Average' | 'Group By' | 'Report' | 'Custom'
  type: 'Line' | 'Bar' | 'Percentage' | 'Pie' | 'Donut' | 'Heatmap'
  document_type: string
  timeseries: boolean
  time_interval: string
  timespan: string
  filters_json: string
  color: string
  y_axis: Array<{ y_field: string; color: string }>
  number_of_groups: number
  custom_options: string  // JSON
  value_based_on: string
  currency: string
  source: string  // Custom chart source
  report_name: string
  use_report_chart: boolean
  heatmap_year: number
}
```

## 4. ECharts 图表类型映射

| 旧版 type | ECharts option |
|-----------|---------------|
| Line | `type: 'line'` in series |
| Bar | `type: 'bar'` in series |
| Pie | `type: 'pie'` in series |
| Donut | `type: 'pie'` + `radius: ['40%', '70%']` |
| Percentage | 堆叠 bar `stack: 'total'` + 百分比转换 |
| Heatmap | ECharts calendar heatmap |

## 5. 开发流程

### Step 1: useChartData Composable

文件: `frontend/src/composables/useChartData.ts`

功能:
- 通过 `chart_name` 获取 Dashboard Chart 配置（chart_pg）
- 根据 chart_type 确定 API method
- 传递 timespan/time_interval/filters 参数获取图表数据
- 管理 loading/error/data 状态
- 支持 refresh / reset
- 支持用户级 chart_settings 保存

### Step 2: ChartRenderer.vue

文件: `frontend/src/core/features/workspace_builder/blocks/ChartRenderer.vue`

功能:
- 接收 `chartData` (labels + datasets) 和 `chartConfig` (chart_pg)
- 使用 vue-echarts `<v-chart>` 渲染
- 将后端数据格式转换为 ECharts option
- 支持所有 6 种图表类型
- 响应式尺寸自适应
- SVG 渲染（性能最优）

### Step 3: 更新 WorkspacePage.vue 图表区块

将当前 placeholder:
```html
<div class="chart-placeholder">{{ t('Chart') }}: {{ item.chart_name }}</div>
```

替换为完整的图表渲染组件，包括:
- 图表标题头部
- ChartRenderer 渲染区域
- Loading / Empty 状态
- 操作按钮区域

### Step 4: 时间序列控件

- Timespan 选择器: Last Year, Last Quarter, Last Month, Last Week, Select Date Range
- Time Interval 选择器: Yearly, Quarterly, Monthly, Weekly, Daily
- Heatmap Year 选择器
- 日期范围选择器 (n-date-picker)

### Step 5: 图表操作菜单

- Refresh: 重新获取数据
- Edit: 导航到 Dashboard Chart 编辑页
- Reset: 重置用户自定义设置
- List/Report: 导航到关联的列表或报表页

### Step 6: 构建验证

- `npm run build` 通过
- 运行时验证图表渲染

## 6. 数据流

```
1. WorkspacePage.load()
   → getDesktopPage(data)
   → filteredCharts = response.charts.items
   → 每个 chart block 包含 chart_name

2. Chart Block 渲染
   → useChartData(chartName)
   → api.call('jingrow.desk.pagetype.dashboard_chart.dashboard_chart.get', { chart_name, ... })
   → 返回 { labels, datasets }

3. ChartRenderer
   → 将 { labels, datasets } 转换为 ECharts option
   → <v-chart :option="option" autoresize />
```

## 7. 关键实现细节

### 7.1 ECharts Option 转换

```typescript
function buildEChartsOption(data: ChartData, config: DashboardChartConfig): EChartsOption {
  // Line/Bar → xAxis(category) + yAxis(value) + series
  // Pie/Donut → series(pie) with radius
  // Percentage → series(bar) stack + 百分比
  // Heatmap → calendar + visualMap
}
```

### 7.2 颜色处理

旧版颜色来自 `chart_pg.y_axis[].color` 或 `chart_pg.color`，直接映射到 ECharts `color` 配置。

### 7.3 Tooltip 格式化

根据 `fieldtype` / `currency` 使用对应的格式化函数。

### 7.4 Chart Settings 持久化

用户自定义的 timespan/interval/filters 通过 API 保存:
```
jingrow.desk.pagetype.dashboard_settings.dashboard_settings.save_chart_config
```
