@fui-org/fui-cli 0.2.0 → 0.4.0

package/skills/fui-skill/references/components-echart.md

@@ -0,0 +1,391 @@
+# f-echart — Biểu đồ ECharts V5 (Core)
+
+> File này sở hữu: **`f-echart` core: import, kiến trúc, props, config, theme, DataView, lỗi thường gặp**. Template từng loại chart xem [echart-templates.md](echart-templates.md).
+
+Dùng `f-echart` cho mọi loại biểu đồ: bar, line, pie, scatter, gauge, radar, heatmap, sankey, tree, map, graph...
+
+> ⚠️ `:option` / `:config` của `f-echart` là nơi luật **"`:attr` chỉ nhận expression thuần"** hay bị vi phạm nhất — logic dựng option nhiều bước phải nằm trong hàm `script.js` gọi qua `EXE`, không nhét IIFE / `var` / `return` vào JSON (vi phạm ⇒ trang trắng, 0 JS error, 0 Vue warn). Luật đầy đủ: [advanced-techniques.md](advanced-techniques.md) §1.
+
+File này là **core**: import, kiến trúc, props, config, theme, DataView, events, lỗi thường gặp. **Template từng loại chart + các pattern module.json** đã tách sang [echart-templates.md](echart-templates.md) — load thêm khi đã biết cần vẽ loại chart nào.
+
+---
+
+## Import — Bắt buộc, đúng thứ tự
+
+`f-echart` yêu cầu 2 file JS nền tảng. Không có → component không tồn tại, trang trắng.
+
+```
+1. /include/chart/echarts.min.js   ← ECharts core (phải đứng TRƯỚC)
+2. /include/chart/fechart.js       ← FUI wrapper (phải đứng SAU)
+```
+
+Quy trình `file_import_list` → `file_import_new` → `file_import_delete`: xem
+[component-quickref.md](component-quickref.md). **Điểm đặc thù của f-echart** — sort number quyết
+định thứ tự load, và `fechart.js` phụ thuộc biến `echarts` global nên **PHẢI có sort lớn hơn**
+`echarts.min.js` (ví dụ `echarts.min.js` = 100, `fechart.js` = 110).
+
+---
+
+## Kiến trúc — Direct Mode
+
+`f-echart` **xây dựng hoàn toàn trên Apache ECharts V5** (echarts.apache.org). `fechart.js` chỉ là lớp bọc mỏng: nạp theme, vài shortcut trong `config`, DataView, events. **Mọi thứ trong `option` chính là ECharts option** — khi cần cấu hình chart, **dùng thẳng kiến thức Apache ECharts** (option, series, axis, visualMap, dataZoom...); chỉ `config` là shortcut riêng của FUI.
+
+`f-echart` là **Direct Mode only**. Bạn viết ECharts `option` trực tiếp — không có Auto mode, không có `config.type`.
+
+| Prop | Vai trò |
+|---|---|
+| `option` | **Primary** — full ECharts option, truyền thẳng vào `echarts.setOption()`. Dùng kiến thức Apache ECharts |
+| `config` | Meta/shortcut riêng FUI: height, theme, title, toolbox... Là defaults, bị `option` merge đè |
+
+**Thứ tự merge:** `config` xây base → `option` merge đè lên bằng `_.merge` (lodash).
+- Plain objects → **deep-merge**
+- Primitives → **replace**
+- Arrays → **merge theo chỉ số**, KHÔNG phải replace ⚠️
+
+Bẫy của merge-theo-chỉ-số: `config` chỉ sinh ra hai mảng là `color` (từ `config.color`) và `dataZoom` (từ `config.zoom`). Nếu cả `config.color` lẫn `option.color` cùng có, mảng ngắn hơn **không xoá được đuôi của mảng dài hơn**:
+
+```js
+config.color = ['#111','#222','#333','#444'];  option.color = ['#aaa','#bbb'];
+// → ['#aaa','#bbb','#333','#444']   ← 2 màu cũ còn sót lại
+```
+
+⇒ Chọn **một chỗ duy nhất** để khai palette (khuyến nghị `config.color`), đừng khai cả hai. Với `series`/`xAxis`/`yAxis`/`grid` thì `config` không bao giờ sinh ra nên không có va chạm — cứ khai thoải mái trong `option`.
+
+Sau khi merge, chart luôn được vẽ bằng `setOption(opt, true)` (**notMerge**) — mỗi lần render là thay toàn bộ option, không sót cấu hình của lần trước.
+
+---
+
+## Quy ước hiển thị MẶC ĐỊNH (làm đúng ngay từ đầu, không chờ user nhắc)
+
+Đúc kết từ các yêu cầu chỉnh sửa lặp lại nhiều lần của user thật. Áp dụng mặc định cho mọi chart mới/refactor — chỉ bỏ qua khi user yêu cầu rõ kiểu khác:
+
+1. **Luôn hiển thị giá trị trên chart** — bar: `label: { show: true, position: 'top' }` (horizontal bar → `position: 'right'`); line: `label: { show: true, position: 'top' }`.
+2. **Grid padding**: mặc định chart có hệ trục dùng `left: 0`, `right: 0`, `top: 50`, `bottom: 50`; `top`/`bottom` tự tăng nếu title/legend cần thêm chỗ. Chỉ khai cạnh mà user yêu cầu đổi; thêm `containLabel: true` khi nhãn trục có nguy cơ bị cắt. Xem "Grid padding và boundaryGap".
+3. **Số hiển thị đầy đủ** có phân cách nghìn (`1,500,000`) — không rút gọn `1.5M`/`1.2k` trừ khi user yêu cầu (mặc định `formatFull` của tooltip đã đúng — đừng override).
+4. **Pie**: không để labelLine ("râu") dài rối; label ngắn gọn (tên + % nếu cần) hoặc dồn thông tin về legend + tooltip.
+5. **Không tự dựng nút "Xem dữ liệu"** — dùng `config.dataView: true` có sẵn của f-echart.
+
+---
+
+## Props
+
+| Prop | Type | Default | Mô tả |
+|---|---|---|---|
+| `config` | Object | `{}` | Shortcut settings |
+| `option` | Object | `{}` | Full ECharts option — primary |
+
+> Component chỉ có 2 props: `config` và `option`. **Không có `data` prop.**
+
+---
+
+## config keys
+
+| Key | Type | Default | Mô tả |
+|---|---|---|---|
+| `height` | number\|string | `400` | Số = `px`; string = `'50vh'`... |
+| `theme` | string | `'fui'` | **Chỉ nhận** `'fui'`\|`'shine'`\|`'v5'`. Tên khác (kể cả theme tự `echarts.registerTheme`) và `null` đều **âm thầm rơi về `'fui'`** — đổi màu thì dùng `config.color` |
+| `backgroundColor` | string | `'transparent'` | Override background |
+| `title` | string | | → `option.title.text` |
+| `subtitle` | string | | → `option.title.subtext` |
+| `titleAlign` | string | `'center'` | `'left'`/`'center'`/`'right'` (bí danh cũ: `titleLeft`) |
+| `titleSize` | number | `16` | Cỡ chữ title (px) |
+| `titleColor` | string | | Màu chữ title — bỏ trống thì theo theme |
+| `titleWeight` | string\|number | `'bold'` | `'normal'`/`'bold'`/`500`... |
+| `titleFont` | string | | font-family cho cả title lẫn subtitle |
+| `titleStyle` | Object | | ECharts textStyle đầy đủ — **thắng mọi key `title*` ở trên** |
+| `subtitleSize` / `subtitleColor` / `subtitleStyle` | | `12` | Tương tự, cho subtitle |
+| `color` | string[] | | Override color palette |
+| `animation` | boolean | | `false` = tắt animation |
+| `animationDuration` | number | | ms |
+| `animationEasing` | string | | ECharts easing name |
+| `legend` | true\|false\|Object | | `false` = ẩn; `true`/Object = bật, merge với `{ type:'scroll', left:'center' }` — **không đặt top/bottom**, vị trí dọc do layout engine tính |
+| `legendPosition` | string | `'bottom'` | Cạnh legend neo vào: `'top'`/`'bottom'`. **Chỉ có tác dụng khi legend được bật qua `config.legend`/`config.legendConfig`** — xem "Khoảng trống & bố cục dọc" |
+| `legendRows` | number | `1` | Số hàng legend cần chừa chỗ — đặt >1 khi nhiều mục xuống dòng. Có tác dụng với mọi cách khai legend |
+| `legendConfig` | Object | | Extra legend props (merge sau `legend`) |
+| `tooltip` | Object | | Merge vào default `{ confine: true }`. **Không có `trigger` mặc định** → ECharts dùng `'item'`; chart nhiều series theo trục phải tự khai `tooltip: { trigger: 'axis' }` trong `option` |
+| `tooltipFormat` | string | `'auto'` | `'number'`/`'percent'`/`'currency'`/`'short'`/`'auto'`. `'auto'` = số đầy đủ có phân cách nghìn (`1,500,000`); `'short'` = co gọn (`1.5M`) — chỉ dùng khi user yêu cầu rõ |
+| `decimals` | number | | Số chữ số thập phân cho `tooltipFormat` `'number'`/`'percent'`/`'currency'` |
+| `symbol` | string | `'₫'` | Ký hiệu tiền tệ cho `tooltipFormat: 'currency'` |
+| `tooltipFormatter` | Function | | Custom tooltip fn — **thắng `tooltipFormat`** |
+| `toolbox` | boolean | `false` | Hiện toolbox (saveAsImage + restore) |
+| `toolboxConfig` | Object | | Override/extend toolbox features |
+| `dataView` | boolean | `false` | Hiện nút bảng (Vue overlay) — tự trích xuất data từ `option` |
+| `zoom` | boolean | | dataZoom inside + slider |
+| `zoomConfig` | Array | | Override dataZoom config |
+| `refreshInterval` | number | | ms — auto-refresh |
+
+**Tooltip mặc định đã đẹp sẵn — KHÔNG cần cấu hình gì thêm:** title (tên category) canh giữa, mỗi dòng series gồm chấm màu + label canh trái, giá trị canh phải, số hiển thị đầy đủ có phân cách nghìn (`2,535` chứ không phải `2.5K`). Chỉ đụng vào `tooltipFormat`/`tooltipFormatter` khi user yêu cầu format khác (`percent`, `currency`, co gọn `short`...).
+
+---
+
+## Grid padding và `boundaryGap` — chọn đúng cấu hình
+
+Hai khái niệm này giải quyết hai loại khoảng trống khác nhau:
+
+| User muốn thay đổi | Cấu hình đúng | Vị trí khai |
+|---|---|---|
+| Khoảng cách từ vùng vẽ tới mép canvas | `grid.top` / `grid.bottom` / `grid.left` / `grid.right` | `option.grid` |
+| Khoảng hở từ điểm/cột đầu và cuối tới hai đầu trục | `boundaryGap` | ngay trong `xAxis` hoặc `yAxis` tương ứng |
+
+`f-echart` không có prop `padding`, và `boundaryGap` không thay thế cho `grid`. Số trong `grid` là px; chuỗi như `'10%'` dùng phần trăm. Mặc định wrapper cho chart Cartesian là:
+
+```js
+grid: { top: 50, bottom: 50, left: 0, right: 0 }
+```
+
+`top`/`bottom` là mức tối thiểu: layout engine có thể tăng để tránh title/legend. Mỗi cạnh user khai trong `option.grid` sẽ thắng mặc định và không còn được engine tự tính. Vì vậy, nếu user chỉ yêu cầu đổi padding ngang, chỉ khai hai cạnh ngang:
+
+```js
+grid: { left: 12, right: 24, containLabel: true }
+```
+
+Nếu user yêu cầu con số chính xác cho cả bốn cạnh, khai đủ bốn cạnh; cần kiểm tra title/legend không đè vùng vẽ:
+
+```js
+grid: { top: 40, bottom: 60, left: 12, right: 24, containLabel: true }
+```
+
+`containLabel: true` giúp giữ nhãn trục trong vùng `grid`; dùng khi nhãn dài hoặc sát mép. `grid` chỉ điều khiển chart Cartesian có `xAxis`/`yAxis`. Pie, funnel, treemap, sankey và graph bỏ qua `grid`; chỉnh khoảng trống của chúng bằng `series.top` / `bottom` / `left` / `right` (hoặc `center` / `radius` theo loại chart).
+
+`fechart.js` không đặt `boundaryGap`, nên giữ mặc định ECharts:
+
+- Trục `category`: `boundaryGap: true`.
+- Trục `value`, `time`, `log`: `boundaryGap: [0, 0]`.
+
+Khi user muốn line chart chạm hai đầu trục category, đặt `boundaryGap: false` trên chính trục category:
+
+```js
+xAxis: { type: 'category', boundaryGap: false, data: labels }
+```
+
+Bar chart thường giữ `boundaryGap: true` để cột đầu/cuối không bị ép sát mép. Với horizontal bar, trục category là `yAxis`, nên đặt ở `yAxis.boundaryGap`. Với trục `value`/`time`, có thể chừa biên theo hai phía:
+
+```js
+xAxis: { type: 'time', boundaryGap: ['5%', '5%'] }
+```
+
+Khi user nói "bỏ khoảng trắng hai đầu đường dữ liệu", ưu tiên kiểm tra `boundaryGap`; khi user nói "giảm padding quanh biểu đồ/canvas", chỉnh `grid`.
+
+---
+
+## Khoảng trống & bố cục dọc (layout box model)
+
+ECharts đặt title / legend / vùng vẽ bằng toạ độ tuyệt đối — nó **không** biết "khối này nằm dưới khối kia". `f-echart` bù lại bằng một layout engine chạy sau khi merge `config` + `option`: đi từ mép trên xuống và từ mép dưới lên, mỗi khối hiện diện lấy **đúng chiều cao của mình + một khoảng hở**, phần chưa ai lấy là vùng vẽ.
+
+| Hằng số | px | Dùng cho |
+|---|---|---|
+| padding | 8 | khoảng hở với mép canvas |
+| gap | 12 | khoảng hở tối thiểu giữa hai khối bất kỳ |
+| grid trái / phải | 0 / 0 | mặc định vùng vẽ Cartesian; module có thể override từng cạnh |
+| grid trên / dưới | 50 / 50 | mức tối thiểu khi module không khai; title/legend có thể làm tăng |
+| chiều cao title | `round(fontSize × 1.4)` | mặc định `16px` → 22 |
+| chiều cao subtitle | `4 + round(fontSize × 1.4)` | mặc định `12px` → 4+17 |
+| một hàng legend | 24 | nhân với `legendRows` |
+| chừa nhãn trục hoành | 26 | cộng thêm vào `grid.bottom` |
+| chừa nhãn trục tung | 10 | cộng thêm vào `grid.top` |
+
+Vùng vẽ nhận phần còn lại qua **hai cơ chế khác nhau**:
+- chart **có hệ trục** (`xAxis`/`yAxis`) → `grid.top` / `grid.bottom`
+- **pie / funnel / treemap / sankey / graph** → `series.top` / `series.bottom`, vì các loại này **bỏ qua `grid` hoàn toàn**. Ngoại lệ: series khai `center` bằng px thì engine không đụng vào (đổi box sẽ dịch hình đi).
+
+Số thực tế (đo trên chính `fechart.js`), chart có trục, title mặc định:
+
+| Cấu hình | `title.top` | `legend` | `grid.top` | `grid.bottom` |
+|---|---|---|---|---|
+| không title, không legend | — | — | 50 | 50 |
+| chỉ title | 8 | — | 52 | 50 |
+| title + `config.legend: true` | 8 | `bottom: 8` | 52 | 70 |
+| title + `legendPosition:'top'` | 8 | `top: 42` | 88 | 50 |
+| như trên + `legendRows: 2` | 8 | `top: 42` | 112 | 50 |
+| title `titleSize: 24` + subtitle | 8 | — | 85 | 50 |
+
+### Legend neo cạnh nào — luật quyết định
+
+Đọc theo thứ tự, dừng ở điều kiện đầu tiên đúng:
+
+1. `legend.top` có giá trị → neo **trên**; `legend.bottom` có giá trị → neo **dưới** (giá trị module khai được giữ nguyên).
+2. Legend bật qua `config.legend` / `config.legendConfig` → `config.legendPosition`, mặc định **`'bottom'`**.
+3. Legend chỉ khai trong `option.legend` (không qua `config`) → neo **trên**. ⚠️ Trong ca này `config.legendPosition` **không có tác dụng** — muốn legend xuống đáy thì hoặc đặt `option.legend.bottom: 0`, hoặc bật legend qua `config.legend: true`.
+
+**Hệ quả khi viết module:** đừng tự chỉnh `grid.top`/`grid.bottom`/`legend.top` để "né" title — thêm title, đổi `titleSize`, hay chuyển `legendPosition` thì khoảng trống tự cộng lại. Giá trị **do module tự khai luôn được tôn trọng** (khai `grid.top: 5` thì engine không đụng vào, và khối sau vẫn cộng dồn từ giá trị đó), nên chỉ khai khi thật sự cần một bố cục riêng. Legend nhiều mục xuống dòng thì báo `legendRows` thay vì tự đẩy `grid.top`.
+
+Hai giới hạn đã biết: (a) engine chỉ tính được `top`/`bottom` dạng **số px** — khai `'10%'`/`'middle'` thì nó chỉ giữ một mức tối thiểu, phần còn lại tự canh; (b) `option.grid` dạng **mảng** (multi-grid) thì engine bỏ qua hoàn toàn, module tự lo bố cục.
+
+---
+
+## DataView
+
+`config.dataView: true` → hiện icon bảng (góc trên phải chart). Click → overlay bảng dữ liệu phủ lên chart.
+
+**DataView tự trích xuất từ `option` — không cần truyền data riêng:**
+- Ưu tiên `option.dataset.source` (object-array hoặc array-of-arrays)
+- Fallback: `option.series[].data` + `xAxis.data` / `yAxis.data`
+- Không có data phù hợp → nút bảng ẩn tự động
+
+```json
+{
+  "el": "f-echart", "w": "12",
+  "attr": {
+    ":config": "{ title: 'Doanh thu', dataView: true, height: 350 }",
+    ":option": "vueData.chartOpt"
+  }
+}
+```
+
+> DataView là **Vue overlay tùy chỉnh** — **không phải** ECharts toolbox DataView. `config.toolbox: true` chỉ thêm saveAsImage + restore.
+
+Bỏ `dataView` khi option không có series array rõ ràng (gauge giá trị đơn, sankey node/link, tree hierarchical...).
+
+---
+
+## Series auto-enhancement
+
+`f-echart` tự động áp style theo loại series — điều khiển bởi **enhancement policy** của theme:
+
+| Policy | Áp cho | Hành vi |
+|---|---|---|
+| `lighten` | `bar`, `pie`, `funnel` | Fill màu nhạt 50% + viền màu gốc |
+| `separator` | `treemap`, `sunburst` | Viền trắng mờ giữa các ô/lớp |
+| `outline` | `scatter`, `effectScatter` | Viền trắng quanh điểm |
+
+**`lighten` detail:**
+- `bar` — per-series: một màu nhạt + viền cho toàn bộ cột
+- `pie` / `funnel` — per-item: mỗi lát/phần tử lấy màu riêng từ palette rồi làm nhạt
+
+**Override:**
+- Tắt lighten cho bar: đặt `itemStyle.color` tường minh trong `option.series[]`
+- Tắt lighten cho pie item: đặt `itemStyle.color` vào từng phần tử `data[]`
+- Tắt separator/outline: đặt `itemStyle.borderWidth: 0` trong `option.series[]`
+
+---
+
+## Theme
+
+3 theme nhúng sẵn trong `fechart.js` — không cần file ngoài:
+
+| Theme | Màu | Đặc điểm |
+|---|---|---|
+| `'fui'` | 56 màu | **Mặc định** — palette rộng, nhiều series |
+| `'shine'` | 8 màu | Classic axis style, màu đậm nét |
+| `'v5'` | 9 màu | ECharts V5 default style |
+
+```json
+":config": "{ theme: 'shine' }"
+":config": "{ theme: 'v5' }"
+```
+
+> ⚠️ **Chỉ ba tên trên là hợp lệ.** Mọi tên khác — kể cả theme tự đăng ký bằng `echarts.registerTheme('myTheme', …)` — và cả `theme: null` đều **âm thầm rơi về `'fui'`**, không lỗi, không cảnh báo. Đừng dùng `config.theme` cho theme custom.
+
+**Đổi bảng màu thì dùng `config.color`** — đây là đường được hỗ trợ, và cũng là bảng màu mà series auto-enhancement đọc để tính màu fill/viền:
+
+```json
+":config": "{ color: ['#e63946', '#457b9d', '#2a9d8f'] }"
+```
+
+---
+
+## Events
+
+| Event | Payload | Mô tả |
+|---|---|---|
+| `chart-click` | params | Click data point |
+| `drilldown` | params | Alias của `chart-click` |
+| `legend-change` | params | Chọn/bỏ legend item |
+| `rendered` | — | Sau mỗi lần `setOption` |
+| `finished` | — | Sau khi animation xong |
+
+```json
+{ "v-on:drilldown": "CALL(vueData.loadDetail, { row: $event })" }
+```
+
+---
+
+## Exposed methods (`$refs`)
+
+```js
+this.$refs.myChart.getInstance()           // ECharts instance gốc
+this.$refs.myChart.refresh()               // Force re-render (gọi lại setOption)
+this.$refs.myChart.exportImage('chart.png')
+this.$refs.myChart.resizeChart()           // Hiếm khi cần — xem ghi chú dưới
+```
+
+> **Không cần gọi `resizeChart()` thủ công trong hầu hết trường hợp**: component đã tự nghe `window.resize` **và** `ResizeObserver` trên chính thẻ chứa chart, nên chart co giãn đúng cả khi container đổi kích thước mà viewport không đổi (Vuetify grid settle sau mount, mở tab/dialog, thu gọn sidebar).
+
+```js
+// Native ECharts API
+const chart = vueData.$refs.myChart.getInstance();
+chart.dispatchAction({ type: 'highlight', seriesIndex: 0, dataIndex: 2 });
+chart.on('mouseover', p => { vueData.hoverLabel = p.name; });
+```
+
+---
+
+## FEchartFormatter (global, dùng trong script.js)
+
+Đúng 6 hàm, không có gì khác:
+
+```js
+FEchartFormatter.build('currency', { symbol: '₫', decimals: 0 })(1500000) // → '₫1,500,000'
+FEchartFormatter.formatShort(1500000)   // → '1.5M' (co gọn — chỉ dùng khi cần tiết kiệm chỗ, vd axis label)
+FEchartFormatter.formatNumber(1500000)  // → '1,500,000'  (decimals thứ 2, mặc định 0)
+FEchartFormatter.formatFull(2535.678)   // → '2,535.68' (đầy đủ, tối đa 2 số thập phân — mặc định của tooltip)
+// Tạo tooltip formatter từ config.tooltipFormat ('auto'/không khai → formatFull, số đầy đủ)
+FEchartFormatter.buildTooltip({ tooltipFormat: 'currency', symbol: '₫' })
+FEchartFormatter.buildDefault()         // formatter tooltip mặc định (formatFull)
+```
+
+Hai điểm dễ sai:
+- **Không có** `formatPercent` / `formatCurrency` rời — muốn hai kiểu đó thì đi qua `build('percent', { decimals })` / `build('currency', { symbol, decimals })`.
+- Truy cập bằng **tên trần** `FEchartFormatter`, **không phải** `window.FEchartFormatter` (khai bằng `const` ở cấp script nên không gắn lên `window`; `window.FEchartFormatter` là `undefined`).
+
+---
+
+## Sort dữ liệu
+
+Không có `config.sort`. Sort trong `script.js` trước khi gán:
+
+```js
+vueData.rows = (d.data || []).slice().sort((a, b) => b.doanhThu - a.doanhThu);
+// String sort
+vueData.rows = (d.data || []).slice().sort((a, b) => a.name.localeCompare(b.name));
+```
+
+> **Không dùng ECharts `dataset.transform sort`** với object-array — không ổn định với ECharts V5.
+
+---
+
+## Pattern trong module.json (controls)
+
+```json
+{
+  "el": "f-echart",
+  "w": "12",
+  "attr": {
+    ":config": "{ title: 'Tiêu đề', height: 350, dataView: true }",
+    ":option": "vueData.chartOpt"
+  }
+}
+```
+
+`vueData.chartOpt` được build trong `script.js` (callback sau khi fetch data). `dataView: true` tự trích xuất dữ liệu từ `option` để hiển thị bảng.
+
+> **Template từng loại chart (bar/line/pie/gauge/radar/heatmap/sankey/tree/graph...) + 5 pattern module.json (inline, vueData ref, dynamic height, conditional option, no-dataview):** xem [echart-templates.md](echart-templates.md).
+
+---
+
+## Lỗi thường gặp
+
+| Lỗi | Nguyên nhân | Giải pháp |
+|---|---|---|
+| Trang trắng / component không tồn tại | Thiếu `fechart.js` trong import | `file_import_list` → thêm nếu thiếu |
+| `echarts is not defined` | `fechart.js` sort nhỏ hơn `echarts.min.js` | Đảo sort: `echarts.min.js` phải có số nhỏ hơn |
+| Chart trống dù data có | Data nằm ngoài `option` (ví dụ cố truyền qua prop `data` không tồn tại) | Data chart phải trong `option.series` — không có prop `data` |
+| Nút DataView không hiện | `option` không có series array hoặc axis data | DataView chỉ hiện khi tự trích được data từ `option` |
+| Bar fill nhạt | Auto lighten enhancement (50%) | Set `itemStyle.color` tường minh trong `option.series[]` |
+| Chart không update khi filter thay đổi | `config`/`option` đều có **deep watch** nên sửa lồng sâu vẫn vẽ lại — không update nghĩa là biến **chưa khai trong `data[]`** (Vue không theo dõi được) | Khai key trong `data[]` module.json rồi mới gán; cùng lắm gọi `$refs.myChart.refresh()` |
+| `config.type` không có tác dụng | f-echart không có config.type | Đặt `type` trong `option.series[].type` |
+| Theme custom không ăn | `config.theme` chỉ nhận `'fui'`/`'shine'`/`'v5'`, tên khác **âm thầm** về `'fui'` | Đổi màu bằng `config.color` |
+| Palette lạ, có màu không khai ở đâu | Khai màu ở **cả** `config.color` lẫn `option.color` → merge theo chỉ số, đuôi mảng dài hơn còn sót | Chỉ khai palette ở một chỗ |
+| Legend nằm trên đầu dù đặt `legendPosition: 'bottom'` | Legend khai trong `option` (không qua `config.legend`) thì neo **trên**, `legendPosition` vô hiệu | `option.legend.bottom: 0`, hoặc bật legend bằng `config.legend: true` |
+| Tooltip chỉ hiện 1 series khi rê chuột | Không có `trigger` mặc định → ECharts dùng `'item'` | Khai `tooltip: { trigger: 'axis' }` trong `option` |
+| Legend nhiều hàng đè lên chart | Engine mặc định chừa chỗ cho **1 hàng** legend | `config.legendRows: 2` (hoặc hơn) |