# Admin Chart Business Blocks Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Extend the existing page designer and business-block generator so admin pages can use metric, line, bar, and pie chart blocks backed by a validated single-table aggregation DSL.

**Architecture:** Keep `front_project_page_design.layout_json`, `BusinessBlockRegistryService`, and `BusinessBlockGenerationService` as the persistence, validation, and generation spine. Add protocol-v2 fields and chart dataset DTOs, filter definitions by page scope, render chart-specific controls in EasyCode, then generate fixed Vue 2/ECharts components and fixed MyBatis aggregation endpoints. Existing frontend blocks remain protocol-v1 compatible through normalization.

**Tech Stack:** Vue 3 + Element Plus + ECharts 5.4 in `easycode-web`, Java 8 + Spring Boot + Fastjson2 + MyBatis + Velocity in the generator, generated Vue 2 + Element UI + ECharts 5.4, Node built-in tests, JUnit 4, Mockito.

---

## Scope

This plan implements:

- Protocol-v2 definition fields: `kind`, `surfaces`, `placements`, `chartType`, `datasetSchema`, and `defaultSpan`.
- Legacy definition normalization without changing old JSON files.
- Scope-filtered business-block API with project ownership validation.
- Four admin-only blocks: metric, line, bar, and pie.
- Single-table aggregation configuration with dimensions, metrics, filters, date range, sorting, and limit.
- Three block widths: 12, 6, and 4 columns.
- Design-time ECharts preview using deterministic sample data.
- Save-time and generation-time chart DSL validation.
- Generated Vue/API/Controller/Service/Mapper files and shared chart runtime.
- Block-level loading, empty, error, and retry states.

This plan does not implement joins, custom SQL, formulas, user-editable runtime filters, free-form grid positioning, block-level RBAC, department data scope, or chart drill-down.

## File Structure

### Protocol and validation

- Modify `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/BusinessBlockDefinition.java`
  - Add protocol-v2 metadata while retaining `placement`.
- Modify `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/BusinessBlockInstance.java`
  - Add `span`, `dataset`, and `display`.
- Create `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartDatasetConfig.java`
- Create `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartDimensionConfig.java`
- Create `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartMetricConfig.java`
- Create `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartFilterConfig.java`
- Create `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartDateRangeConfig.java`
- Create `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartSortConfig.java`
- Create `ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/ChartDatasetValidator.java`
  - Own all chart DSL and field-type validation.
- Modify `ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/BusinessBlockRegistryService.java`
  - Normalize old definitions, filter by surface, and delegate chart validation.

### API and designer

- Modify `ruoyi-admin/src/main/java/com/ruoyi/web/controller/front/FrontProjectController.java`
  - Accept `scope`, verify project ownership, return filtered definitions.
- Modify `ruoyi-admin/src/test/java/com/ruoyi/web/controller/front/FrontProjectControllerRunPreviewTest.java`
- Modify `easycode-web/src/api/project.js`
  - Pass scope to `listBusinessBlocks`.
- Modify `easycode-web/src/views/PageDesignerView.vue`
  - Load and pass filtered blocks for both scopes.
- Modify `easycode-web/src/views/pageDesignerView.test.mjs`
- Modify `easycode-web/package.json` and `easycode-web/package-lock.json`
  - Add ECharts 5.4.
- Create `easycode-web/src/components/business-blocks/chartBlock.js`
  - Pure layout, defaulting, option-building, and local validation helpers.
- Create `easycode-web/src/components/business-blocks/ChartBlockConfigForm.vue`
- Create `easycode-web/src/components/business-blocks/ChartFilterEditor.vue`
- Create `easycode-web/src/components/business-blocks/ChartBlockPreview.vue`
- Modify `easycode-web/src/components/business-blocks/BusinessBlockDesigner.vue`
- Modify `easycode-web/src/components/business-blocks/BlockCanvas.vue`
- Modify `easycode-web/src/components/business-blocks/blockLayout.js`
- Modify `easycode-web/src/components/FrontendPageDesigner.vue`
- Modify `easycode-web/src/components/businessBlockDesigner.test.mjs`
- Modify `easycode-web/src/components/frontendPageDesigner.test.mjs`

### Built-in definitions and generation

- Create:
  - `ruoyi-generator/src/main/resources/business-blocks/admin_metric_chart/block.json`
  - `ruoyi-generator/src/main/resources/business-blocks/admin_line_chart/block.json`
  - `ruoyi-generator/src/main/resources/business-blocks/admin_bar_chart/block.json`
  - `ruoyi-generator/src/main/resources/business-blocks/admin_pie_chart/block.json`
- Create `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartQueryParameter.java`
- Create `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartQueryRenderModel.java`
- Create `ruoyi-generator/src/main/java/com/ruoyi/generator/util/ChartBlockRenderSupport.java`
  - Convert validated metadata into static SQL fragments and bound parameter definitions.
- Modify `ruoyi-generator/src/main/java/com/ruoyi/generator/service/BusinessBlockGenerationService.java`
  - Resolve shared templates, add chart context, emit one shared runtime file, and expose span.
- Modify `ruoyi-generator/src/main/resources/business-blocks/page/business-block-page.vue.vm`
- Modify `ruoyi-generator/src/main/resources/qing/index.vue.vm`
- Modify `ruoyi-generator/src/main/resources/qing/vue-package.json.vm`
- Create shared templates:
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/frontend/AdminChartBlock.vue.vm`
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/frontend/chartApi.js.vm`
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/frontend/chartRuntime.js.vm`
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/backend/AdminChartController.java.vm`
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/backend/AdminChartService.java.vm`
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/backend/AdminChartServiceImpl.java.vm`
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/backend/AdminChartMapper.java.vm`
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/backend/AdminChartMapper.xml.vm`
- Modify tests:
  - `ruoyi-generator/src/test/java/com/ruoyi/generator/service/front/BusinessBlockRegistryServiceTest.java`
  - `ruoyi-generator/src/test/java/com/ruoyi/generator/service/BusinessBlockGenerationServiceTest.java`
  - `ruoyi-generator/src/test/java/com/ruoyi/generator/service/GenProjectServiceImplTest.java`
  - `ruoyi-generator/src/test/java/com/ruoyi/generator/util/QingTemplateSupportTest.java`
  - `ruoyi-generator/src/test/java/com/ruoyi/generator/util/ChartBlockRenderSupportTest.java`

## Task 1: Add protocol-v2 definition metadata and legacy normalization

**Files:**

- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/BusinessBlockDefinition.java`
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/BusinessBlockRegistryService.java`
- Test: `ruoyi-generator/src/test/java/com/ruoyi/generator/service/front/BusinessBlockRegistryServiceTest.java`

- [ ] **Step 1: Write failing normalization and surface-filter tests**

Add these tests:

```java
@Test
public void legacyDefinitionsDefaultToFrontendBusinessBlocks()
{
    BusinessBlockDefinition definition = service.findDefinition("cart");

    assertEquals("business", definition.getKind());
    assertEquals(Collections.singletonList("frontend"), definition.getSurfaces());
    assertEquals(Collections.singletonList("page"), definition.getPlacements());
}

@Test
public void listDefinitionsFiltersBySurface()
{
    for (BusinessBlockDefinition definition : service.listDefinitions("frontend"))
    {
        assertTrue(definition.getSurfaces().contains("frontend"));
    }
    for (BusinessBlockDefinition definition : service.listDefinitions("admin"))
    {
        assertTrue(definition.getSurfaces().contains("admin"));
    }
}
```

- [ ] **Step 2: Run the focused test and verify failure**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=BusinessBlockRegistryServiceTest test
```

Expected: compilation fails because the protocol-v2 getters and `listDefinitions(String)` do not exist.

- [ ] **Step 3: Add protocol-v2 fields**

Add to `BusinessBlockDefinition`:

```java
private String kind;
private List<String> surfaces;
private List<String> placements;
private String chartType;
private String datasetSchema;
private Integer defaultSpan;

public String getKind() { return kind; }
public void setKind(String kind) { this.kind = kind; }
public List<String> getSurfaces() { return surfaces; }
public void setSurfaces(List<String> surfaces) { this.surfaces = surfaces; }
public List<String> getPlacements() { return placements; }
public void setPlacements(List<String> placements) { this.placements = placements; }
public String getChartType() { return chartType; }
public void setChartType(String chartType) { this.chartType = chartType; }
public String getDatasetSchema() { return datasetSchema; }
public void setDatasetSchema(String datasetSchema) { this.datasetSchema = datasetSchema; }
public Integer getDefaultSpan() { return defaultSpan; }
public void setDefaultSpan(Integer defaultSpan) { this.defaultSpan = defaultSpan; }
```

- [ ] **Step 4: Normalize every loaded definition**

In `BusinessBlockRegistryService`, call `normalizeDefinition` before caching:

```java
private BusinessBlockDefinition normalizeDefinition(BusinessBlockDefinition definition)
{
    if (definition == null)
    {
        return null;
    }
    if (StringUtils.isEmpty(definition.getKind()))
    {
        definition.setKind("business");
    }
    if (definition.getSurfaces() == null || definition.getSurfaces().isEmpty())
    {
        definition.setSurfaces(Collections.singletonList("frontend"));
    }
    if (definition.getPlacements() == null || definition.getPlacements().isEmpty())
    {
        String placement = StringUtils.defaultIfEmpty(definition.getPlacement(), PLACEMENT_PAGE);
        definition.setPlacements(Collections.singletonList(placement));
    }
    if (definition.getDefaultSpan() == null)
    {
        definition.setDefaultSpan(Integer.valueOf(12));
    }
    return definition;
}

public List<BusinessBlockDefinition> listDefinitions(String surface)
{
    String normalized = "admin".equals(surface) ? "admin" : "frontend";
    List<BusinessBlockDefinition> result = new ArrayList<BusinessBlockDefinition>();
    for (BusinessBlockDefinition definition : listDefinitions())
    {
        if (definition.getSurfaces().contains(normalized))
        {
            result.add(definition);
        }
    }
    return Collections.unmodifiableList(result);
}
```

Also change `isEmbeddedDefinition` to inspect normalized `placements`:

```java
public boolean supportsPlacement(BusinessBlockDefinition definition, String placement)
{
    return definition != null
            && definition.getPlacements() != null
            && definition.getPlacements().contains(placement);
}
```

- [ ] **Step 5: Run the test and verify pass**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=BusinessBlockRegistryServiceTest test
```

Expected: PASS, with existing cart/notice/carousel tests unchanged.

- [ ] **Step 6: Commit**

```powershell
git add ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/BusinessBlockDefinition.java ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/BusinessBlockRegistryService.java ruoyi-generator/src/test/java/com/ruoyi/generator/service/front/BusinessBlockRegistryServiceTest.java
git commit -m "Extend business block definition protocol"
```

## Task 2: Filter business-block definitions by page scope

**Files:**

- Modify: `ruoyi-admin/src/main/java/com/ruoyi/web/controller/front/FrontProjectController.java`
- Modify: `ruoyi-admin/src/test/java/com/ruoyi/web/controller/front/FrontProjectControllerRunPreviewTest.java`
- Modify: `easycode-web/src/api/project.js`
- Modify: `easycode-web/src/views/PageDesignerView.vue`
- Modify: `easycode-web/src/views/pageDesignerView.test.mjs`

- [ ] **Step 1: Write failing controller and frontend source tests**

Replace the controller test with:

```java
@Mock
private FrontProjectServiceImpl frontProjectService;

@Test
public void businessBlocksChecksOwnershipAndFiltersScope()
{
    BusinessBlockDefinition definition = new BusinessBlockDefinition();
    definition.setCode("admin_line_chart");
    when(businessBlockRegistryService.listDefinitions("admin"))
            .thenReturn(Collections.singletonList(definition));

    AjaxResult result = controller.businessBlocks(20L, "admin");

    assertEquals(Collections.singletonList(definition), result.get(AjaxResult.DATA_TAG));
    verify(frontProjectService).getProject(7L, 20L);
    verify(businessBlockRegistryService).listDefinitions("admin");
}
```

Inject `frontProjectService` in `setUp`.

Change the Node assertions to:

```js
assert.equal(source.includes('listBusinessBlocks(projectId.value, scope.value)'), true)
assert.equal(source.includes(':block-definitions="businessBlockDefinitions"'), true)
assert.equal(source.includes("scope === 'frontend' ? businessBlockDefinitions : []"), false)
assert.equal(apiSource.includes('params: { scope }'), true)
```

- [ ] **Step 2: Run tests and verify failure**

Run:

```powershell
mvn -pl ruoyi-admin -am -Dtest=FrontProjectControllerRunPreviewTest test
cd easycode-web
node --test src/views/pageDesignerView.test.mjs
```

Expected: controller signature and frontend scope calls do not match.

- [ ] **Step 3: Implement the scoped API**

Controller:

```java
@GetMapping("/{projectId}/business-blocks")
public AjaxResult businessBlocks(@PathVariable Long projectId,
        @RequestParam(defaultValue = "frontend") String scope)
{
    Long userId = SecurityUtils.getUserId();
    frontProjectService.getProject(userId, projectId);
    return AjaxResult.success(businessBlockRegistryService.listDefinitions(scope));
}
```

Frontend API:

```js
export function listBusinessBlocks(projectId, scope = 'frontend') {
  return request({
    url: `/front/project/${projectId}/business-blocks`,
    method: 'get',
    params: { scope }
  })
}
```

Page load:

```js
listBusinessBlocks(projectId.value, scope.value)
```

Pass the result directly:

```vue
:block-definitions="businessBlockDefinitions"
```

- [ ] **Step 4: Run tests and verify pass**

Run:

```powershell
mvn -pl ruoyi-admin -am -Dtest=FrontProjectControllerRunPreviewTest test
cd easycode-web
node --test src/views/pageDesignerView.test.mjs
```

Expected: PASS.

- [ ] **Step 5: Commit**

```powershell
git add ruoyi-admin/src/main/java/com/ruoyi/web/controller/front/FrontProjectController.java ruoyi-admin/src/test/java/com/ruoyi/web/controller/front/FrontProjectControllerRunPreviewTest.java easycode-web/src/api/project.js easycode-web/src/views/PageDesignerView.vue easycode-web/src/views/pageDesignerView.test.mjs
git commit -m "Filter business blocks by page scope"
```

## Task 3: Add the chart dataset model on backend and frontend

**Files:**

- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartDatasetConfig.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartDimensionConfig.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartMetricConfig.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartFilterConfig.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartDateRangeConfig.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartSortConfig.java`
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/BusinessBlockInstance.java`
- Create: `easycode-web/src/components/business-blocks/chartBlock.js`
- Modify: `easycode-web/src/components/business-blocks/blockLayout.js`
- Modify: `easycode-web/src/components/businessBlockDesigner.test.mjs`

- [ ] **Step 1: Write failing Java parsing test**

Add:

```java
@Test
public void parseLayoutReadsChartDatasetAndSpan()
{
    PageBusinessBlockLayout layout = service.parseLayout(
            "{\"canvas\":\"business-blocks-v1\",\"blocks\":[{"
            + "\"id\":\"line_001\",\"blockCode\":\"admin_line_chart\",\"span\":6,"
            + "\"dataset\":{\"schema\":\"single-table-aggregate-v1\",\"table\":\"shop_order\","
            + "\"dimension\":{\"field\":\"create_time\",\"timeUnit\":\"day\"},"
            + "\"metrics\":[{\"field\":\"amount\",\"aggregate\":\"sum\",\"alias\":\"salesAmount\"}]},"
            + "\"display\":{\"showLegend\":true}}]}");

    BusinessBlockInstance instance = layout.getBlocks().get(0);
    assertEquals(Integer.valueOf(6), instance.getSpan());
    assertEquals("shop_order", instance.getDataset().getTable());
    assertEquals("amount", instance.getDataset().getMetrics().get(0).getField());
    assertEquals(Boolean.TRUE, instance.getDisplay().get("showLegend"));
}
```

- [ ] **Step 2: Write failing JavaScript helper tests**

Import `buildDefaultChartInstance`, `updateChartDataset`, `updateChartDisplay`, and `validateChartInstance`, then add:

```js
const lineDefinition = {
  code: 'admin_line_chart',
  name: 'Line chart',
  kind: 'chart',
  chartType: 'line',
  datasetSchema: 'single-table-aggregate-v1',
  defaultSpan: 12
}

test('chart helper builds a deterministic line chart instance', () => {
  const block = buildDefaultChartInstance(lineDefinition, 'line_001')
  assert.equal(block.span, 12)
  assert.equal(block.dataset.schema, 'single-table-aggregate-v1')
  assert.deepEqual(block.dataset.metrics, [{ field: '', aggregate: 'sum', alias: 'metric1', label: '指标 1' }])
  assert.equal(block.display.showLegend, true)
})

test('chart helper reports a missing dimension for line charts', () => {
  const block = buildDefaultChartInstance(lineDefinition, 'line_001')
  const errors = validateChartInstance(lineDefinition, block, [])
  assert.equal(errors.some((item) => item.key === 'dimension.field'), true)
})
```

- [ ] **Step 3: Run tests and verify failure**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=BusinessBlockRegistryServiceTest test
cd easycode-web
node --test src/components/businessBlockDesigner.test.mjs
```

Expected: missing DTOs and chart helper exports.

- [ ] **Step 4: Add Java DTOs**

Use ordinary Java 8 beans. `ChartDatasetConfig` has:

```java
private String schema;
private String table;
private ChartDimensionConfig dimension;
private List<ChartMetricConfig> metrics;
private List<ChartFilterConfig> filters;
private ChartDateRangeConfig dateRange;
private ChartSortConfig sort;
private Integer limit;
```

The nested contracts are:

```java
// ChartDimensionConfig
private String field;
private String timeUnit;

// ChartMetricConfig
private String field;
private String aggregate;
private String alias;
private String label;

// ChartFilterConfig
private String field;
private String operator;
private Object value;

// ChartDateRangeConfig
private String field;
private String preset;
private String start;
private String end;

// ChartSortConfig
private String by;
private String order;
```

Add to `BusinessBlockInstance`:

```java
private Integer span;
private ChartDatasetConfig dataset;
private Map<String, Object> display;
```

- [ ] **Step 5: Implement frontend pure helpers**

Create `chartBlock.js` with these exports:

```js
export const allowedChartSpans = [12, 6, 4]

export function isChartDefinition(definition) {
  return definition?.kind === 'chart'
}

export function buildDefaultChartInstance(definition, id) {
  const chartType = definition?.chartType || 'line'
  return {
    id,
    blockCode: definition.code,
    name: definition.name || definition.code,
    span: allowedChartSpans.includes(definition.defaultSpan) ? definition.defaultSpan : 12,
    config: {},
    dataset: {
      schema: definition.datasetSchema || 'single-table-aggregate-v1',
      table: '',
      dimension: chartType === 'metric' ? null : { field: '', timeUnit: '' },
      metrics: [{ field: '', aggregate: chartType === 'metric' ? 'count' : 'sum', alias: 'metric1', label: '指标 1' }],
      filters: [],
      dateRange: null,
      sort: chartType === 'metric' ? null : { by: 'dimension', order: 'asc' },
      limit: chartType === 'pie' ? 10 : chartType === 'bar' ? 20 : chartType === 'metric' ? 1 : 100
    },
    display: {
      showTitle: true,
      showLegend: chartType !== 'metric',
      emptyText: '暂无数据',
      smooth: chartType === 'line',
      donut: chartType === 'pie',
      horizontal: false,
      stacked: false
    }
  }
}

export function updateChartDataset(block, dataset) {
  return { ...block, dataset: structuredClone(dataset || {}) }
}

export function updateChartDisplay(block, display) {
  return { ...block, display: structuredClone(display || {}) }
}

export function validateChartInstance(definition, block, tables) {
  const errors = []
  const dataset = block?.dataset || {}
  const table = tables.find((item) => item.tableName === dataset.table)
  if (!table) errors.push({ key: 'table', message: '请选择数据表' })
  if (definition?.chartType !== 'metric' && !dataset.dimension?.field) {
    errors.push({ key: 'dimension.field', message: '请选择维度字段' })
  }
  if (!Array.isArray(dataset.metrics) || !dataset.metrics.length || dataset.metrics.some((item) => !item.field)) {
    errors.push({ key: 'metrics', message: '请配置指标字段' })
  }
  return errors
}
```

Change `addBlockInstance` so chart definitions call `buildDefaultChartInstance`; legacy definitions retain `{ config: {} }`.

- [ ] **Step 6: Run tests and verify pass**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=BusinessBlockRegistryServiceTest test
cd easycode-web
node --test src/components/businessBlockDesigner.test.mjs
```

Expected: PASS.

- [ ] **Step 7: Commit**

```powershell
git add ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block easycode-web/src/components/business-blocks/chartBlock.js easycode-web/src/components/business-blocks/blockLayout.js easycode-web/src/components/businessBlockDesigner.test.mjs
git commit -m "Add chart business block data model"
```

## Task 4: Validate the single-table aggregation DSL

**Files:**

- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/ChartDatasetValidator.java`
- Create: `ruoyi-generator/src/test/java/com/ruoyi/generator/service/front/ChartDatasetValidatorTest.java`

- [ ] **Step 1: Write failing validator tests**

Create chart test tables with typed columns:

```java
private GenTableColumn typedColumn(String columnName, String javaField, String javaType, String columnType)
{
    GenTableColumn column = column(columnName, javaField);
    column.setJavaType(javaType);
    column.setColumnType(columnType);
    return column;
}
```

Add tests for:

```java
@Test
public void chartValidationRejectsSumOnTextField()
{
    BusinessBlockInstance instance = validLineChartInstance();
    instance.getDataset().getMetrics().get(0).setField("status");

    ServiceException exception = expectServiceException(() ->
            validator.validate(lineChartDefinition(), instance, chartTables()));

    assertTrue(exception.getMessage().contains("SUM"));
    assertTrue(exception.getMessage().contains("status"));
}

@Test
public void chartValidationAcceptsSingleTableTimeSeries()
{
    validator.validate(lineChartDefinition(), validLineChartInstance(), chartTables());
}
```

Use this explicit definition helper so the validator test does not depend on classpath resources:

```java
private BusinessBlockDefinition lineChartDefinition()
{
    BusinessBlockDefinition definition = new BusinessBlockDefinition();
    definition.setCode("admin_line_chart");
    definition.setName("折线图");
    definition.setKind("chart");
    definition.setChartType("line");
    definition.setDatasetSchema("single-table-aggregate-v1");
    definition.setSurfaces(Collections.singletonList("admin"));
    definition.setPlacements(Arrays.asList("embedded", "page"));
    definition.setDefaultSpan(Integer.valueOf(12));
    return definition;
}
```

Also test invalid span, more than three metrics, more than ten filters, invalid `timeUnit`, invalid operator, duplicate aliases, and limit over 500.

- [ ] **Step 2: Run tests and verify failure**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=ChartDatasetValidatorTest test
```

Expected: `ChartDatasetValidator` does not exist.

- [ ] **Step 3: Implement `ChartDatasetValidator`**

Expose:

```java
public void validate(BusinessBlockDefinition definition, BusinessBlockInstance instance,
        List<GenTable> tables)
```

Use these fixed sets:

```java
private static final Set<String> AGGREGATES =
        new HashSet<String>(Arrays.asList("count", "sum", "avg"));
private static final Set<String> TIME_UNITS =
        new HashSet<String>(Arrays.asList("day", "week", "month"));
private static final Set<String> OPERATORS =
        new HashSet<String>(Arrays.asList(
                "eq", "ne", "gt", "gte", "lt", "lte", "between", "in", "is_null", "is_not_null"));
private static final Set<Integer> SPANS =
        new HashSet<Integer>(Arrays.asList(Integer.valueOf(12), Integer.valueOf(6), Integer.valueOf(4)));
```

Numeric fields are recognized by Java type:

```java
private boolean isNumeric(GenTableColumn column)
{
    return StringUtils.equalsAnyIgnoreCase(column.getJavaType(),
            "Integer", "Long", "Double", "Float", "Short", "BigDecimal");
}
```

Date fields are recognized by Java or SQL type:

```java
private boolean isTemporal(GenTableColumn column)
{
    String columnType = StringUtils.defaultString(column.getColumnType()).toLowerCase();
    return StringUtils.equalsAnyIgnoreCase(column.getJavaType(),
            "Date", "LocalDate", "LocalDateTime")
            || columnType.contains("date")
            || columnType.contains("time")
            || columnType.contains("timestamp")
            || columnType.contains("year");
}
```

Validation order:

1. Dataset schema equals `single-table-aggregate-v1`.
2. Table exists.
3. Span is 12, 6, or 4.
4. Metric chart has no required dimension; other charts require one.
5. Metric count is 1 for metric/pie and 1–3 for line/bar.
6. `sum` and `avg` require numeric fields.
7. Time unit requires a temporal dimension.
8. Alias matches `[A-Za-z][A-Za-z0-9_]{0,39}` and is unique.
9. Filters use known fields/operators and max at 10.
10. Limit is 1–500.

- [ ] **Step 4: Run tests and verify pass**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=ChartDatasetValidatorTest test
```

Expected: PASS.

- [ ] **Step 5: Commit**

```powershell
git add ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/ChartDatasetValidator.java ruoyi-generator/src/test/java/com/ruoyi/generator/service/front/ChartDatasetValidatorTest.java
git commit -m "Validate chart business block datasets"
```

## Task 5: Register the four built-in admin chart blocks

**Files:**

- Create:
  - `ruoyi-generator/src/main/resources/business-blocks/admin_metric_chart/block.json`
  - `ruoyi-generator/src/main/resources/business-blocks/admin_line_chart/block.json`
  - `ruoyi-generator/src/main/resources/business-blocks/admin_bar_chart/block.json`
  - `ruoyi-generator/src/main/resources/business-blocks/admin_pie_chart/block.json`
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/BusinessBlockRegistryService.java`
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/FrontendPageDesignService.java`
- Modify: `ruoyi-generator/src/test/java/com/ruoyi/generator/service/front/BusinessBlockRegistryServiceTest.java`
- Modify: `ruoyi-generator/src/test/java/com/ruoyi/generator/service/front/FrontendPageDesignServiceTest.java`

- [ ] **Step 1: Write failing registry tests**

```java
@Test
public void adminSurfaceIncludesFourChartBlocks()
{
    List<BusinessBlockDefinition> definitions = service.listDefinitions("admin");
    assertTrue(hasCode(definitions, "admin_metric_chart"));
    assertTrue(hasCode(definitions, "admin_line_chart"));
    assertTrue(hasCode(definitions, "admin_bar_chart"));
    assertTrue(hasCode(definitions, "admin_pie_chart"));
    assertEquals(4, countKind(definitions, "chart"));
}

@Test
public void frontendSurfaceExcludesAdminCharts()
{
    assertEquals(0, countKind(service.listDefinitions("frontend"), "chart"));
}

@Test
public void chartValidationRejectsAdminChartOnFrontendPage()
{
    ServiceException exception = expectServiceException(() ->
            service.validateInstanceConfig(service.findDefinition("admin_line_chart"),
                    validLineChartInstance(), chartTables(), "frontend"));

    assertTrue(exception.getMessage().contains("后台"));
}
```

Add these test helpers:

```java
private boolean hasCode(List<BusinessBlockDefinition> definitions, String code)
{
    for (BusinessBlockDefinition definition : definitions)
    {
        if (code.equals(definition.getCode())) return true;
    }
    return false;
}

private int countKind(List<BusinessBlockDefinition> definitions, String kind)
{
    int count = 0;
    for (BusinessBlockDefinition definition : definitions)
    {
        if (kind.equals(definition.getKind())) count++;
    }
    return count;
}
```

- [ ] **Step 2: Run and verify failure**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=BusinessBlockRegistryServiceTest test
```

Expected: definitions are absent.

- [ ] **Step 3: Add four definition files**

Use this exact shared template set in each file:

```json
[
  {
    "key": "frontendComponent",
    "template": "/business-blocks/chart/templates/frontend/AdminChartBlock.vue.vm",
    "outputPath": "src/views/pages/${pageCode}/blocks/${instanceCode}/${InstanceClassName}.vue"
  },
  {
    "key": "frontendApi",
    "template": "/business-blocks/chart/templates/frontend/chartApi.js.vm",
    "outputPath": "src/api/business-blocks/${instanceCode}.js"
  },
  {
    "key": "controller",
    "template": "/business-blocks/chart/templates/backend/AdminChartController.java.vm",
    "outputPath": "src/main/java/${packagePath}/controller/block/${InstanceClassName}Controller.java"
  },
  {
    "key": "service",
    "template": "/business-blocks/chart/templates/backend/AdminChartService.java.vm",
    "outputPath": "src/main/java/${packagePath}/service/block/I${InstanceClassName}Service.java"
  },
  {
    "key": "serviceImpl",
    "template": "/business-blocks/chart/templates/backend/AdminChartServiceImpl.java.vm",
    "outputPath": "src/main/java/${packagePath}/service/block/impl/${InstanceClassName}ServiceImpl.java"
  },
  {
    "key": "mapper",
    "template": "/business-blocks/chart/templates/backend/AdminChartMapper.java.vm",
    "outputPath": "src/main/java/${packagePath}/mapper/block/${InstanceClassName}Mapper.java"
  },
  {
    "key": "mapperXml",
    "template": "/business-blocks/chart/templates/backend/AdminChartMapper.xml.vm",
    "outputPath": "src/main/resources/mapper/block/${InstanceClassName}Mapper.xml"
  }
]
```

Each definition declares:

```json
{
  "kind": "chart",
  "surfaces": ["admin"],
  "placements": ["embedded", "page"],
  "datasetSchema": "single-table-aggregate-v1",
  "version": 2,
  "defaultSpan": 12
}
```

Set `chartType` to `metric`, `line`, `bar`, and `pie`. Use category `数据图表`.

- [ ] **Step 4: Integrate chart validation into page save**

Inject `ChartDatasetValidator` into `BusinessBlockRegistryService`. Preserve the repository's plain-constructor unit-test style with:

```java
@Autowired
private ChartDatasetValidator chartDatasetValidator;

private ChartDatasetValidator chartValidator()
{
    if (chartDatasetValidator == null)
    {
        chartDatasetValidator = new ChartDatasetValidator();
    }
    return chartDatasetValidator;
}
```

Add:

```java
public void validateInstanceConfig(BusinessBlockDefinition definition, BusinessBlockInstance instance,
        List<GenTable> tables, String surface)
{
    String normalizedSurface = "admin".equals(surface) ? "admin" : "frontend";
    if (!definition.getSurfaces().contains(normalizedSurface))
    {
        throw new ServiceException("业务块“" + definition.getName() + "”不能用于"
                + ("admin".equals(normalizedSurface) ? "后台" : "前台") + "页面");
    }
    if ("chart".equals(definition.getKind()))
    {
        chartValidator().validate(definition, instance, tables);
        return;
    }
    validateInstanceConfig(definition, instance, tables);
}
```

Update `validateLayout` and `validateEmbeddedBlocks` to accept `surface`, then update `FrontendPageDesignService.normalizeLayout` to pass its existing normalized scope.

Add save tests proving a valid admin chart layout succeeds and the same layout with `scope=frontend` fails.

- [ ] **Step 5: Run and verify pass**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=BusinessBlockRegistryServiceTest,FrontendPageDesignServiceTest test
```

Expected: PASS.

- [ ] **Step 6: Commit**

```powershell
git add ruoyi-generator/src/main/resources/business-blocks/admin_metric_chart/block.json ruoyi-generator/src/main/resources/business-blocks/admin_line_chart/block.json ruoyi-generator/src/main/resources/business-blocks/admin_bar_chart/block.json ruoyi-generator/src/main/resources/business-blocks/admin_pie_chart/block.json ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/BusinessBlockRegistryService.java ruoyi-generator/src/main/java/com/ruoyi/generator/service/front/FrontendPageDesignService.java ruoyi-generator/src/test/java/com/ruoyi/generator/service/front/BusinessBlockRegistryServiceTest.java ruoyi-generator/src/test/java/com/ruoyi/generator/service/front/FrontendPageDesignServiceTest.java
git commit -m "Register admin chart business blocks"
```

## Task 6: Build the chart configuration form

**Files:**

- Create: `easycode-web/src/components/business-blocks/ChartBlockConfigForm.vue`
- Create: `easycode-web/src/components/business-blocks/ChartFilterEditor.vue`
- Modify: `easycode-web/src/components/business-blocks/BusinessBlockDesigner.vue`
- Modify: `easycode-web/src/components/businessBlockDesigner.test.mjs`

- [ ] **Step 1: Write failing source tests**

```js
test('chart blocks use a dedicated dataset and display editor', () => {
  const source = readSource('business-blocks/BusinessBlockDesigner.vue')
  const form = readSource('business-blocks/ChartBlockConfigForm.vue')
  const filters = readSource('business-blocks/ChartFilterEditor.vue')

  assert.equal(source.includes("import ChartBlockConfigForm from './ChartBlockConfigForm.vue'"), true)
  assert.equal(source.includes('selectedDefinition?.kind === \'chart\''), true)
  assert.equal(form.includes('update:dataset'), true)
  assert.equal(form.includes('update:display'), true)
  assert.equal(form.includes('<ChartFilterEditor'), true)
  assert.equal(filters.includes('eq'), true)
  assert.equal(filters.includes('between'), true)
  assert.equal(filters.includes('is_not_null'), true)
})
```

- [ ] **Step 2: Run and verify failure**

Run:

```powershell
cd easycode-web
node --test src/components/businessBlockDesigner.test.mjs
```

Expected: chart components do not exist.

- [ ] **Step 3: Implement `ChartFilterEditor.vue`**

Props and events:

```js
const props = defineProps({
  modelValue: { type: Array, default: () => [] },
  columns: { type: Array, default: () => [] }
})
const emit = defineEmits(['update:modelValue'])
```

Operators:

```js
const operators = [
  { value: 'eq', label: '等于' },
  { value: 'ne', label: '不等于' },
  { value: 'gt', label: '大于' },
  { value: 'gte', label: '大于等于' },
  { value: 'lt', label: '小于' },
  { value: 'lte', label: '小于等于' },
  { value: 'between', label: '区间' },
  { value: 'in', label: '包含任一' },
  { value: 'is_null', label: '为空' },
  { value: 'is_not_null', label: '不为空' }
]
```

Emit immutable arrays on add, remove, and edit. Cap additions at ten.

- [ ] **Step 4: Implement `ChartBlockConfigForm.vue`**

Required props:

```js
const props = defineProps({
  definition: { type: Object, required: true },
  dataset: { type: Object, default: () => ({}) },
  display: { type: Object, default: () => ({}) },
  span: { type: Number, default: 12 },
  tables: { type: Array, default: () => [] },
  errors: { type: Array, default: () => [] }
})
const emit = defineEmits(['update:dataset', 'update:display', 'update:span'])
```

Tabs:

- Data: table, dimension, time unit, metrics, filters, date range, sort, limit.
- Display: title visibility, legend, empty text, plus chart-specific toggles.
- Permission: read-only text `继承所在后台页面；一期不支持块级覆盖`.

Field options come only from the selected table. Aggregate options are:

```js
function aggregateOptions(column) {
  const numeric = ['Integer', 'Long', 'Double', 'Float', 'Short', 'BigDecimal']
    .includes(column?.javaType)
  return numeric
    ? [{ value: 'count', label: '计数' }, { value: 'sum', label: '求和' }, { value: 'avg', label: '平均值' }]
    : [{ value: 'count', label: '计数' }]
}
```

- [ ] **Step 5: Route chart updates through `BusinessBlockDesigner`**

Render:

```vue
<ChartBlockConfigForm
  v-if="showConfig && selectedDefinition?.kind === 'chart'"
  :definition="selectedDefinition"
  :dataset="selectedBlock?.dataset || {}"
  :display="selectedBlock?.display || {}"
  :span="selectedBlock?.span || 12"
  :tables="tables"
  :errors="selectedChartErrors"
  @update:dataset="updateSelectedDataset"
  @update:display="updateSelectedDisplay"
  @update:span="updateSelectedSpan"
/>
<BlockConfigForm
  v-else-if="showConfig"
  :definition="selectedDefinition"
  :model-value="selectedBlock?.config || {}"
  :tables="tables"
  @update:model-value="updateSelectedConfig"
/>
```

Use immutable block updates and emit formatted JSON after every change.

Add:

```js
const selectedChartErrors = computed(() => (
  selectedDefinition.value?.kind === 'chart'
    ? validateChartInstance(selectedDefinition.value, selectedBlock.value, props.tables)
    : []
))

function replaceSelectedBlock(patch) {
  if (!selectedBlock.value) return
  layout.value = {
    ...layout.value,
    blocks: layout.value.blocks.map((block) => (
      block.id === selectedBlock.value.id ? { ...block, ...patch } : block
    ))
  }
  emitLayout()
}

function updateSelectedDataset(dataset) {
  replaceSelectedBlock({ dataset })
}

function updateSelectedDisplay(display) {
  replaceSelectedBlock({ display })
}

function updateSelectedSpan(span) {
  replaceSelectedBlock({ span })
}
```

- [ ] **Step 6: Run tests and verify pass**

Run:

```powershell
cd easycode-web
node --test src/components/businessBlockDesigner.test.mjs
```

Expected: PASS.

- [ ] **Step 7: Commit**

```powershell
git add easycode-web/src/components/business-blocks/ChartBlockConfigForm.vue easycode-web/src/components/business-blocks/ChartFilterEditor.vue easycode-web/src/components/business-blocks/BusinessBlockDesigner.vue easycode-web/src/components/businessBlockDesigner.test.mjs
git commit -m "Add admin chart block configuration UI"
```

## Task 7: Add ECharts design-time preview and three-width canvas

**Files:**

- Modify: `easycode-web/package.json`
- Modify: `easycode-web/package-lock.json`
- Create: `easycode-web/src/components/business-blocks/ChartBlockPreview.vue`
- Modify: `easycode-web/src/components/business-blocks/chartBlock.js`
- Modify: `easycode-web/src/components/business-blocks/BlockCanvas.vue`
- Modify: `easycode-web/src/components/FrontendPageDesigner.vue`
- Modify: `easycode-web/src/components/businessBlockDesigner.test.mjs`
- Modify: `easycode-web/src/components/frontendPageDesigner.test.mjs`

- [ ] **Step 1: Write failing tests**

Add assertions:

```js
test('chart canvas renders previews in a twelve-column grid', () => {
  const canvas = readSource('business-blocks/BlockCanvas.vue')
  const preview = readSource('business-blocks/ChartBlockPreview.vue')

  assert.equal(canvas.includes('grid-template-columns: repeat(12, minmax(0, 1fr))'), true)
  assert.equal(canvas.includes(':style="{ gridColumn: `span ${block.span || 12}` }"'), true)
  assert.equal(canvas.includes('<ChartBlockPreview'), true)
  assert.equal(preview.includes("import * as echarts from 'echarts'"), true)
  assert.equal(preview.includes('chart.resize()'), true)
  assert.equal(preview.includes('chart.dispose()'), true)
})

test('embedded admin blocks retain chart span and use grid wrappers', () => {
  const source = readSource('components/FrontendPageDesigner.vue')
  assert.equal(source.includes("import ChartBlockPreview from '@/components/business-blocks/ChartBlockPreview.vue'"), true)
  assert.equal(source.includes('<ChartBlockPreview'), true)
  assert.equal(source.includes('embedded-block-grid'), true)
  assert.equal(source.includes('block.span || 12'), true)
})
```

- [ ] **Step 2: Run tests and verify failure**

Run:

```powershell
cd easycode-web
node --test src/components/businessBlockDesigner.test.mjs src/components/frontendPageDesigner.test.mjs
```

Expected: missing preview and grid behavior.

- [ ] **Step 3: Install ECharts in the designer**

Run:

```powershell
cd easycode-web
npm install echarts@5.4.0
```

Expected: `package.json` and `package-lock.json` contain `echarts`.

- [ ] **Step 4: Add deterministic preview option builders**

Add to `chartBlock.js`:

```js
export function sampleChartData(definition) {
  if (definition?.chartType === 'metric') {
    return { dimensions: [], series: [], summary: { value: 86420, count: 328 } }
  }
  return {
    dimensions: [
      { key: 'A', label: 'A' },
      { key: 'B', label: 'B' },
      { key: 'C', label: 'C' },
      { key: 'D', label: 'D' }
    ],
    series: [{ key: 'metric1', name: '指标 1', values: [32, 51, 46, 78] }],
    summary: { value: 207, count: 4 }
  }
}

export function buildChartOption(definition, block, data = sampleChartData(definition)) {
  const labels = data.dimensions.map((item) => item.label)
  const series = data.series.map((item) => ({ name: item.name, data: item.values }))
  if (definition?.chartType === 'pie') {
    return {
      tooltip: { trigger: 'item' },
      legend: { show: block?.display?.showLegend !== false },
      series: [{
        type: 'pie',
        radius: block?.display?.donut ? ['45%', '70%'] : '70%',
        data: labels.map((name, index) => ({ name, value: series[0]?.data[index] || 0 }))
      }]
    }
  }
  return {
    tooltip: { trigger: 'axis' },
    legend: { show: block?.display?.showLegend !== false },
    xAxis: { type: 'category', data: labels },
    yAxis: { type: 'value' },
    series: series.map((item) => ({
      ...item,
      type: definition?.chartType === 'bar' ? 'bar' : 'line',
      smooth: definition?.chartType === 'line' && block?.display?.smooth
    }))
  }
}
```

- [ ] **Step 5: Implement `ChartBlockPreview.vue`**

Behavior:

- Metric type renders a number card without creating ECharts.
- Other types create an ECharts instance in `onMounted`.
- Watch option inputs deeply and call `setOption(option, true)`.
- Add and remove `window.resize`.
- Dispose on unmount.
- Catch option errors and render a block-level retry button.

- [ ] **Step 6: Convert canvases to 12-column grids**

Change the chart-capable block wrapper from a `<button>` to an `<article role="button" tabindex="0">` so the preview retry button is not nested inside another button. Preserve click and keyboard selection and keep the remove action as a separate button.

Import and render `ChartBlockPreview` in both `BlockCanvas.vue` and the embedded-block sections of `FrontendPageDesigner.vue`. Legacy business blocks continue to render their existing compact name/code cards.

Wrap every block in a grid item using:

```vue
:style="{ gridColumn: `span ${block.span || 12}` }"
```

Use:

```scss
.block-canvas,
.embedded-block-grid {
  display: grid;
  grid-template-columns: repeat(12, minmax(0, 1fr));
  gap: 12px;
}
```

At widths below 900px, force every item to `grid-column: 1 / -1`.

- [ ] **Step 7: Run tests and build**

Run:

```powershell
cd easycode-web
node --test src/components/businessBlockDesigner.test.mjs src/components/frontendPageDesigner.test.mjs
npm run build
```

Expected: tests PASS and Vite build succeeds.

- [ ] **Step 8: Commit**

```powershell
git add easycode-web/package.json easycode-web/package-lock.json easycode-web/src/components/business-blocks/ChartBlockPreview.vue easycode-web/src/components/business-blocks/chartBlock.js easycode-web/src/components/business-blocks/BlockCanvas.vue easycode-web/src/components/FrontendPageDesigner.vue easycode-web/src/components/businessBlockDesigner.test.mjs easycode-web/src/components/frontendPageDesigner.test.mjs
git commit -m "Preview admin chart blocks in the designer"
```

## Task 8: Build a safe static chart query render model

**Files:**

- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartQueryParameter.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartQueryRenderModel.java`
- Create: `ruoyi-generator/src/main/java/com/ruoyi/generator/util/ChartBlockRenderSupport.java`
- Create: `ruoyi-generator/src/test/java/com/ruoyi/generator/util/ChartBlockRenderSupportTest.java`

- [ ] **Step 1: Write failing SQL render tests**

```java
@Test
public void rendersBoundSingleTableAggregation()
{
    ChartQueryRenderModel model = support.build(orderTable(), lineDefinition(), lineInstance());

    assertEquals("shop_order", model.getTableName());
    assertEquals("DATE_FORMAT(t.create_time, '%Y-%m-%d')", model.getDimensionSql());
    assertTrue(model.getMetricSelectSql().contains("SUM(t.amount) AS salesAmount"));
    assertTrue(model.getWhereSql().contains("t.status = #{filter0}"));
    assertEquals("PAID", model.getParameters().get(0).getValue());
    assertEquals("dimensionKey ASC", model.getOrderBySql());
    assertEquals(Integer.valueOf(100), model.getLimit());
}

@Test
public void neverCopiesFilterValuesIntoSql()
{
    BusinessBlockInstance instance = lineInstance();
    instance.getDataset().getFilters().get(0).setValue("PAID' OR 1=1 --");

    ChartQueryRenderModel model = support.build(orderTable(), lineDefinition(), instance);

    assertTrue(model.getWhereSql().contains("#{filter0}"));
    assertTrue(!model.getWhereSql().contains("OR 1=1"));
}
```

Also test day/week/month formats, count/sum/avg, between, in, null operators, metric no-group query, and pie/bar limits.

- [ ] **Step 2: Run and verify failure**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=ChartBlockRenderSupportTest test
```

Expected: classes do not exist.

- [ ] **Step 3: Add render DTOs**

`ChartQueryParameter`:

```java
private String name;
private Object value;
```

`ChartQueryRenderModel`:

```java
private String tableName;
private String dimensionSql;
private String metricSelectSql;
private String whereSql;
private String groupBySql;
private String orderBySql;
private Integer limit;
private List<ChartQueryParameter> parameters;
private List<ChartMetricConfig> metrics;
private ChartDateRangeConfig dateRange;
private boolean metricOnly;
```

- [ ] **Step 4: Implement `ChartBlockRenderSupport`**

The public entry point is:

```java
public ChartQueryRenderModel build(GenTable table, BusinessBlockDefinition definition,
        BusinessBlockInstance instance)
```

Only use column names resolved from `GenTable.columns`. Never copy the configured field string directly after lookup.

Time SQL:

```java
private String dimensionSql(String column, String timeUnit)
{
    if ("day".equals(timeUnit)) return "DATE_FORMAT(t." + column + ", '%Y-%m-%d')";
    if ("week".equals(timeUnit)) return "DATE_FORMAT(t." + column + ", '%x-W%v')";
    if ("month".equals(timeUnit)) return "DATE_FORMAT(t." + column + ", '%Y-%m')";
    return "t." + column;
}
```

Metrics:

```java
private String metricSql(String column, String aggregate, String alias)
{
    if ("count".equals(aggregate))
    {
        return StringUtils.isEmpty(column) ? "COUNT(*) AS " + alias : "COUNT(t." + column + ") AS " + alias;
    }
    if ("avg".equals(aggregate)) return "AVG(t." + column + ") AS " + alias;
    return "SUM(t." + column + ") AS " + alias;
}
```

Filters create `#{filterN}` parameters. `between` creates two parameters and `in` creates one parameter per value. Null operators create none. Date ranges add `t.<column> >= #{dateStart}` and `t.<column> < #{dateEnd}` to `whereSql`, while the original `ChartDateRangeConfig` is stored in `ChartQueryRenderModel.dateRange` for the generated service to resolve.

- [ ] **Step 5: Run tests and verify pass**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=ChartBlockRenderSupportTest test
```

Expected: PASS.

- [ ] **Step 6: Commit**

```powershell
git add ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartQueryParameter.java ruoyi-generator/src/main/java/com/ruoyi/generator/domain/front/dto/block/ChartQueryRenderModel.java ruoyi-generator/src/main/java/com/ruoyi/generator/util/ChartBlockRenderSupport.java ruoyi-generator/src/test/java/com/ruoyi/generator/util/ChartBlockRenderSupportTest.java
git commit -m "Build safe chart aggregation query models"
```

## Task 9: Extend business-block generation for shared chart templates

**Files:**

- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/service/BusinessBlockGenerationService.java`
- Modify: `ruoyi-generator/src/main/java/com/ruoyi/generator/domain/GeneratedBusinessBlockFile.java`
- Modify: `ruoyi-generator/src/test/java/com/ruoyi/generator/service/BusinessBlockGenerationServiceTest.java`

- [ ] **Step 1: Write failing generation context tests**

```java
@Test
public void chartBlockUsesSharedTemplatesAndAdminApiPath()
{
    List<GeneratedBusinessBlockFile> files = service.listFiles(chartProject(), "admin_frontend");
    GeneratedBusinessBlockFile component = find(files, "admin_line_chart_001", "frontendComponent");

    assertEquals("business-blocks/chart/templates/frontend/AdminChartBlock.vue.vm",
            component.getTemplateResource());
    assertEquals(Integer.valueOf(6), component.getInstance().getSpan());

    String content = service.renderFile(chartProject(), component);
    assertTrue(content.contains("/admin/business-blocks/admin_line_chart_001/data"));
    assertTrue(content.contains("chartType: \"line\""));
}

@Test
public void chartProjectEmitsOneSharedRuntime()
{
    List<GeneratedBusinessBlockFile> files = service.listFiles(chartProject(), "admin_frontend");
    assertEquals(1, countOutput(files, "src/utils/chartRuntime.js"));
}

@Test
public void adminChartGeneratesFrontendAndBackendFiles()
{
    assertTrue(hasBlockFile(service.listFiles(chartProject(), "admin_frontend"),
            "admin_line_chart_001", "frontendComponent"));
    assertTrue(hasBlockFile(service.listFiles(chartProject(), "backend"),
            "admin_line_chart_001", "mapperXml"));
}
```

- [ ] **Step 2: Run and verify failure**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=BusinessBlockGenerationServiceTest test
```

Expected: absolute shared template paths and runtime support are absent.

- [ ] **Step 3: Resolve absolute classpath template paths**

Add:

```java
private String templateResource(String blockCode, String template)
{
    String normalized = normalizePath(template);
    if (normalized.startsWith("/"))
    {
        return normalized.substring(1);
    }
    return "business-blocks/" + blockCode + "/" + normalized;
}
```

Use it from `blockFile`.

- [ ] **Step 4: Add chart generation context**

Inject `ChartBlockRenderSupport` and add the same lazy fallback pattern used by the existing `businessBlockService()`/`registry()` helpers:

```java
@Autowired
private ChartBlockRenderSupport chartBlockRenderSupport;

private ChartBlockRenderSupport chartRenderSupport()
{
    if (chartBlockRenderSupport == null)
    {
        chartBlockRenderSupport = new ChartBlockRenderSupport();
    }
    return chartBlockRenderSupport;
}
```

For chart blocks:

```java
ChartQueryRenderModel chartQuery = chartRenderSupport().build(
        requireTable(project, instance.getDataset().getTable()), file.getDefinition(), instance);
context.put("chartQuery", chartQuery);
context.put("chartType", file.getDefinition().getChartType());
context.put("chartDataset", instance.getDataset());
context.put("chartDisplay", instance.getDisplay());
context.put("apiBasePath", "/admin/business-blocks/" + file.getInstanceCode());
```

Non-chart blocks keep `/business-blocks/{instanceCode}`.

- [ ] **Step 5: Route admin frontend and backend templates correctly**

Replace the current scope gate with:

```java
if ("frontend".equals(templateType) && adminScope)
{
    continue;
}
if ("admin_frontend".equals(templateType) && !adminScope)
{
    continue;
}
```

When selecting template files, treat both frontend targets as Vue/API files:

```java
private boolean templateMatches(String requestedType, BusinessBlockTemplateFile templateFile)
{
    String fileType = templateType(templateFile);
    if ("admin_frontend".equals(requestedType))
    {
        return "frontend".equals(fileType);
    }
    return requestedType.equals(fileType);
}
```

Backend files are therefore generated for both frontend and admin page scopes, while Vue/API files remain scope-specific.

- [ ] **Step 6: Emit one shared runtime file**

When `listFiles(project, "admin_frontend")` encounters the first chart block, prepend:

```text
category: business-block:admin_frontend:shared:chartRuntime
outputPath: src/utils/chartRuntime.js
templateResource: business-blocks/chart/templates/frontend/chartRuntime.js.vm
```

Use a `Set<String>` keyed by output path so multiple chart blocks cannot duplicate it.

- [ ] **Step 7: Expose span to generated page view models**

Add:

```java
block.put("span", instance.getSpan() == null ? Integer.valueOf(12) : instance.getSpan());
```

- [ ] **Step 8: Run tests and verify pass**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=BusinessBlockGenerationServiceTest test
```

Expected: PASS.

- [ ] **Step 9: Commit**

```powershell
git add ruoyi-generator/src/main/java/com/ruoyi/generator/service/BusinessBlockGenerationService.java ruoyi-generator/src/main/java/com/ruoyi/generator/domain/GeneratedBusinessBlockFile.java ruoyi-generator/src/test/java/com/ruoyi/generator/service/BusinessBlockGenerationServiceTest.java
git commit -m "Prepare chart business block generation"
```

## Task 10: Generate chart backend endpoints

**Files:**

- Create:
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/backend/AdminChartController.java.vm`
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/backend/AdminChartService.java.vm`
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/backend/AdminChartServiceImpl.java.vm`
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/backend/AdminChartMapper.java.vm`
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/backend/AdminChartMapper.xml.vm`
- Modify: `ruoyi-generator/src/test/java/com/ruoyi/generator/service/BusinessBlockGenerationServiceTest.java`

- [ ] **Step 1: Write failing generated-backend assertions**

```java
@Test
public void generatedChartBackendUsesBoundParametersAndUnifiedResponse()
{
    Map<String, String> rendered = renderChartFiles(chartProject());

    assertTrue(rendered.get("mapperXml").contains("t.status = #{filter0}"));
    assertTrue(!rendered.get("mapperXml").contains("PAID"));
    assertTrue(rendered.get("mapperXml").contains("limit 100"));
    assertTrue(rendered.get("serviceImpl").contains("dimensions"));
    assertTrue(rendered.get("serviceImpl").contains("series"));
    assertTrue(rendered.get("serviceImpl").contains("summary"));
    assertTrue(rendered.get("controller").contains("@RequestMapping(\"/admin/business-blocks/admin_line_chart_001\")"));
}
```

- [ ] **Step 2: Run and verify failure**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=BusinessBlockGenerationServiceTest test
```

Expected: shared backend templates do not exist.

- [ ] **Step 3: Add mapper contract**

Generated mapper:

```java
List<Map<String, Object>> selectData(Map<String, Object> params);
```

Generated XML shape:

```xml
<select id="selectData" parameterType="java.util.Map" resultType="java.util.LinkedHashMap">
    select
#if(!$chartQuery.metricOnly)
        ${chartQuery.dimensionSql} as dimensionKey,
#end
        ${chartQuery.metricSelectSql}
    from ${chartQuery.tableName} t
#if($chartQuery.whereSql)
    where ${chartQuery.whereSql}
#end
#if($chartQuery.groupBySql)
    group by ${chartQuery.groupBySql}
#end
#if($chartQuery.orderBySql)
    order by ${chartQuery.orderBySql}
#end
    limit ${chartQuery.limit}
</select>
```

All `${...}` values above are generated from validated metadata by `ChartBlockRenderSupport`; runtime values remain `#{...}`.

- [ ] **Step 4: Add service response assembly**

The generated service:

1. Creates a `LinkedHashMap<String,Object>` of bound filter parameters.
2. Calculates date preset start/end with `LocalDate` and `LocalDateTime`.
3. Calls `mapper.selectData(params)`.
4. Returns:

```java
{
    "dimensions": List<Map<String, Object>>,
    "series": List<Map<String, Object>>,
    "summary": Map<String, Object>
}
```

For metric-only charts, read the first row into `summary.value` and set `summary.count`. For grouped charts, preserve row order, create one dimension entry per row, and append each metric alias value to its series.

Generate this private date helper in the service implementation:

```java
private void putDateRange(Map<String, Object> params)
{
#if($chartQuery.dateRange)
    LocalDate today = LocalDate.now();
#if($chartQuery.dateRange.preset == "today")
    params.put("dateStart", today.atStartOfDay());
    params.put("dateEnd", today.plusDays(1).atStartOfDay());
#elseif($chartQuery.dateRange.preset == "last_7_days")
    params.put("dateStart", today.minusDays(6).atStartOfDay());
    params.put("dateEnd", today.plusDays(1).atStartOfDay());
#elseif($chartQuery.dateRange.preset == "last_30_days")
    params.put("dateStart", today.minusDays(29).atStartOfDay());
    params.put("dateEnd", today.plusDays(1).atStartOfDay());
#elseif($chartQuery.dateRange.preset == "this_month")
    params.put("dateStart", today.withDayOfMonth(1).atStartOfDay());
    params.put("dateEnd", today.withDayOfMonth(1).plusMonths(1).atStartOfDay());
#elseif($chartQuery.dateRange.preset == "this_year")
    params.put("dateStart", today.withDayOfYear(1).atStartOfDay());
    params.put("dateEnd", today.withDayOfYear(1).plusYears(1).atStartOfDay());
#else
    params.put("dateStart", LocalDate.parse("${chartQuery.dateRange.start}").atStartOfDay());
    params.put("dateEnd", LocalDate.parse("${chartQuery.dateRange.end}").plusDays(1).atStartOfDay());
#end
#end
}
```

- [ ] **Step 5: Add controller**

```java
@RestController
@RequestMapping("${apiBasePath}")
public class ${InstanceClassName}Controller
{
    @Autowired
    private I${InstanceClassName}Service ${instanceClassName}Service;

    @GetMapping("/data")
    public Result<Map<String, Object>> data()
    {
        return Result.success(${instanceClassName}Service.loadData());
    }
}
```

The `/admin/business-blocks/**` path is not in Qing's public interceptor exclusions, so it remains login-protected.

- [ ] **Step 6: Run tests and verify pass**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=BusinessBlockGenerationServiceTest test
```

Expected: PASS.

- [ ] **Step 7: Commit**

```powershell
git add ruoyi-generator/src/main/resources/business-blocks/chart/templates/backend ruoyi-generator/src/test/java/com/ruoyi/generator/service/BusinessBlockGenerationServiceTest.java
git commit -m "Generate admin chart aggregation endpoints"
```

## Task 11: Generate Vue 2/ECharts chart components and grid pages

**Files:**

- Create:
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/frontend/AdminChartBlock.vue.vm`
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/frontend/chartApi.js.vm`
  - `ruoyi-generator/src/main/resources/business-blocks/chart/templates/frontend/chartRuntime.js.vm`
- Modify: `ruoyi-generator/src/main/resources/business-blocks/page/business-block-page.vue.vm`
- Modify: `ruoyi-generator/src/main/resources/qing/index.vue.vm`
- Modify: `ruoyi-generator/src/main/resources/qing/vue-package.json.vm`
- Modify: `ruoyi-generator/src/test/java/com/ruoyi/generator/util/QingTemplateSupportTest.java`
- Modify: `ruoyi-generator/src/test/java/com/ruoyi/generator/service/BusinessBlockGenerationServiceTest.java`

- [ ] **Step 1: Write failing frontend-generation tests**

```java
@Test
public void qingPackageIncludesEcharts()
{
    String content = render("qing/vue-package.json.vm", projectContext());
    assertTrue(content.contains("\"echarts\": \"5.4.0\""));
}

@Test
public void generatedChartComponentHasBlockLevelStatesAndCleanup()
{
    String component = renderChartFile("frontendComponent");
    assertTrue(component.contains("el-skeleton"));
    assertTrue(component.contains("el-empty"));
    assertTrue(component.contains("retry"));
    assertTrue(component.contains("disposeChart"));
    assertTrue(component.contains("window.removeEventListener"));
}

@Test
public void businessBlockPageUsesTwelveColumnSpanClasses()
{
    String page = renderChartPage();
    assertTrue(page.contains("business-block-page__item--span-6"));
    assertTrue(page.contains("grid-template-columns: repeat(12, minmax(0, 1fr))"));
}
```

- [ ] **Step 2: Run and verify failure**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=BusinessBlockGenerationServiceTest,QingTemplateSupportTest test
```

Expected: ECharts and chart templates are absent.

- [ ] **Step 3: Add generated chart runtime**

`chartRuntime.js.vm` exports:

```js
import * as echarts from "echarts"

export function createChart(element) {
  return echarts.init(element)
}

export function buildChartOption(chartType, display, payload) {
  const safeDisplay = display || {}
  const dimensions = (payload && payload.dimensions) || []
  const sourceSeries = (payload && payload.series) || []
  const labels = dimensions.map(item => item.label)

  if (chartType === "pie") {
    const values = sourceSeries.length ? sourceSeries[0].values : []
    return {
      tooltip: { trigger: "item" },
      legend: { show: safeDisplay.showLegend !== false },
      series: [{
        type: "pie",
        radius: safeDisplay.donut ? ["45%", "70%"] : "70%",
        label: { show: safeDisplay.showLabel !== false },
        data: labels.map((name, index) => ({
          name,
          value: values[index] == null ? 0 : values[index]
        }))
      }]
    }
  }

  const horizontal = chartType === "bar" && safeDisplay.horizontal
  const series = sourceSeries.map(item => ({
    name: item.name,
    type: chartType === "bar" ? "bar" : "line",
    smooth: chartType === "line" && Boolean(safeDisplay.smooth),
    stack: chartType === "bar" && safeDisplay.stacked ? "total" : undefined,
    areaStyle: chartType === "line" && safeDisplay.area ? {} : undefined,
    data: item.values || []
  }))

  return {
    tooltip: { trigger: "axis" },
    legend: { show: safeDisplay.showLegend !== false },
    xAxis: horizontal
      ? { type: "value" }
      : { type: "category", data: labels },
    yAxis: horizontal
      ? { type: "category", data: labels }
      : { type: "value" },
    series
  }
}

export function hasChartData(payload) {
  return Boolean(payload && (
    (payload.summary && payload.summary.value !== null && payload.summary.value !== undefined)
    || (payload.dimensions && payload.dimensions.length)
  ))
}
```

The option builder contains only the four supported chart types and supported display flags.

- [ ] **Step 4: Add API and component templates**

API:

```js
import request from "@/api/request"

export function load${InstanceClassName}Data() {
  return request({
    url: "${apiBasePath}/data",
    method: "get"
  })
}
```

Component behavior:

- `created()` calls `loadData`.
- Metric charts render `summary.value`.
- Other charts initialize after `$nextTick`.
- `loading`, `errorMessage`, and `hasData` are block-local.
- Retry calls `loadData`.
- `beforeDestroy()` removes resize and disposes.

- [ ] **Step 5: Add grid wrappers to generated pages**

Page block:

```velocity
    <div class="business-block-page__item business-block-page__item--span-${block.span}">
      <${block.componentName} />
    </div>
```

CSS:

```css
.business-block-page,
.embedded-business-blocks {
  display: grid;
  grid-template-columns: repeat(12, minmax(0, 1fr));
  gap: 16px;
}

.business-block-page__item--span-12,
.embedded-business-block__item--span-12 { grid-column: span 12; }
.business-block-page__item--span-6,
.embedded-business-block__item--span-6 { grid-column: span 6; }
.business-block-page__item--span-4,
.embedded-business-block__item--span-4 { grid-column: span 4; }
```

At `max-width: 900px`, all wrappers span 12.

- [ ] **Step 6: Add ECharts to generated package**

Add:

```json
"echarts": "5.4.0"
```

to `qing/vue-package.json.vm`.

- [ ] **Step 7: Run tests and verify pass**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=BusinessBlockGenerationServiceTest,QingTemplateSupportTest test
```

Expected: PASS.

- [ ] **Step 8: Commit**

```powershell
git add ruoyi-generator/src/main/resources/business-blocks/chart/templates/frontend ruoyi-generator/src/main/resources/business-blocks/page/business-block-page.vue.vm ruoyi-generator/src/main/resources/qing/index.vue.vm ruoyi-generator/src/main/resources/qing/vue-package.json.vm ruoyi-generator/src/test/java/com/ruoyi/generator/util/QingTemplateSupportTest.java ruoyi-generator/src/test/java/com/ruoyi/generator/service/BusinessBlockGenerationServiceTest.java
git commit -m "Generate admin ECharts business blocks"
```

## Task 12: Merge chart files into preview/download and verify compatibility

**Files:**

- Modify: `ruoyi-generator/src/test/java/com/ruoyi/generator/service/GenProjectServiceImplTest.java`
- Modify: `ruoyi-generator/src/test/java/com/ruoyi/generator/service/BusinessBlockGenerationServiceTest.java`

- [ ] **Step 1: Add end-to-end structure tests**

```java
@Test
public void adminChartFilesAppearInPreviewAndDownloadStructure()
{
    GenProject project = chartProject();
    List<GenStructureNode> frontend = service.getProjectStructure(project, "admin_frontend");
    List<GenStructureNode> backend = service.getProjectStructure(project, "backend");

    assertTrue(hasPath(frontend, "src/utils/chartRuntime.js"));
    assertTrue(hasPath(frontend, "src/views/pages/admin_home/blocks/admin_line_chart_001/AdminLineChart001Block.vue"));
    assertTrue(hasPath(backend, "src/main/resources/mapper/block/AdminLineChart001BlockMapper.xml"));
}

@Test
public void legacyFrontendBlockGenerationIsUnchanged()
{
    List<GeneratedBusinessBlockFile> files = generationService.listFiles(frontendCartProject(), "frontend");
    assertTrue(hasOutput(files, "src/api/business-blocks/cart_001.js"));
    assertTrue(!hasOutput(files, "src/utils/chartRuntime.js"));
}
```

- [ ] **Step 2: Run focused integration tests**

Run:

```powershell
mvn -pl ruoyi-generator -Dtest=GenProjectServiceImplTest,BusinessBlockGenerationServiceTest test
```

Expected: PASS. `GenProjectServiceImpl.addGeneratedFileNode` already builds nodes from arbitrary output paths, so `src/utils/chartRuntime.js` must require no chart-specific production branch.

- [ ] **Step 3: Run all frontend tests**

Run:

```powershell
cd easycode-web
node --test
npm run build
```

Expected: all Node tests PASS and Vite build succeeds.

- [ ] **Step 4: Run all focused backend tests**

Run:

```powershell
mvn -pl ruoyi-generator,ruoyi-admin -am -Dtest=BusinessBlockRegistryServiceTest,ChartBlockRenderSupportTest,FrontendPageDesignServiceTest,BusinessBlockGenerationServiceTest,GenProjectServiceImplTest,QingTemplateSupportTest,FrontProjectControllerRunPreviewTest test
```

Expected: all selected tests PASS.

- [ ] **Step 5: Run module test suites**

Run:

```powershell
mvn -pl ruoyi-generator,ruoyi-admin -am test
```

Expected: BUILD SUCCESS.

- [ ] **Step 6: Manual run-preview smoke test**

Use a project containing:

```text
shop_order.id            bigint
shop_order.amount        decimal
shop_order.status        varchar
shop_order.create_time   datetime
```

In the page designer:

1. Switch to 后台.
2. Open or create a 业务块页面.
3. Add one of each chart type.
4. Configure line chart: `create_time/day`, `amount/sum`, `status=PAID`.
5. Configure bar chart by `status/count`.
6. Configure pie chart by `status/count`.
7. Configure metric card as `amount/sum`.
8. Set widths to 12, 6, 6, and 4.
9. Save, generate, and run preview.
10. Verify login is required for `/admin/business-blocks/**`.
11. Verify each block independently shows loading, data or empty state, and retry on forced API failure.
12. Verify a frontend page still lists only existing frontend business blocks.

- [ ] **Step 7: Keep verification tied to the owning task**

If a verification command fails, return to the task that owns the failing file, make the smallest repair there, rerun that task's focused test, and use that task's explicit `git add` file list and commit message. Do not create a catch-all verification commit.

## Rollout Order

1. Tasks 1–2 establish compatible protocol and scoped discovery.
2. Tasks 3–7 make chart blocks configurable and visible in EasyCode.
3. Tasks 8–11 generate safe aggregation endpoints and ECharts components.
4. Task 12 verifies preview/download integration and legacy compatibility.

## Self-Review

- Spec coverage: protocol compatibility, admin-only scope, four chart types, single-table DSL, three widths, design preview, validation, generation, authentication boundary, error isolation, and compatibility each map to explicit tasks.
- Placeholder scan: the plan contains no unresolved markers or deferred implementation steps.
- Type consistency: `BusinessBlockInstance.dataset` uses `ChartDatasetConfig`; definitions use `surfaces` and `placements`; chart generation uses `ChartQueryRenderModel`; frontend helpers use the same `dataset`, `display`, and `span` property names.
- Security consistency: generated chart APIs use `/admin/business-blocks/**`, while existing public frontend blocks remain under `/business-blocks/**`.
