# ECharts 自包含HTML报告生成规范

## 用途

生成宝锐月度/季度经营报告——自包含HTML单文件，暗色主题，ECharts CDN图表。

## 铁律：ECharts formatter 只能用 function() 不能用箭头函数

**症状**：图表数据显示"NaN万"、格式化失效。

**根因**：ECharts 的 `formatter`、`label.formatter` 等回调中，箭头函数 `=>` 的 `this` 指向与普通 `function()` 不同。ECharts 依赖 `this` 传递数据上下文（如 `this.dataIndex`），箭头函数无法获取。

```javascript
// ❌ 错误：箭头函数 → NaN
formatter: (v) => (v / 10000).toFixed(1) + '万'
label: { formatter: (v) => (v.data / 10000).toFixed(1) + '万' }

// ✅ 正确：function() 声明
formatter: function(v) { return (v / 10000).toFixed(1) + '万'; }
label: { formatter: function(v) { return (v.data / 10000).toFixed(1) + '万'; } }
```

## 铁律二：严禁硬编码目标值（2026-08-03）

**症状**：达成率严重错误。如赵云浩1350万目标被硬编码为350万，达成率24.3%错显为93.7%。

**根因**：手动复制数据到HTML `<script>` 时，不同人目标差异极大（1350万 vs 30万），极易复制错误。

**正确做法**：
1. 用Python脚本从 `kpi_dashboard.json` 读取目标和H1值
2. 从ERP Excel读取当月实际
3. 由Python生成完整JS数据数组，printf写入HTML
4. 或在HTML开篇注明"以下数据由Python脚本自动生成，请勿手动修改"

## 安全数格式守卫

所有金额/百分比格式化前必须做 `Number(v)||0` 守卫，防止 undefined/null 产生 NaN：

```javascript
function fw(v) { return '¥' + (Number(v)/10000 || 0).toFixed(1) + '万'; }
function fp(v) { return (Number(v) || 0).toFixed(0) + '%'; }
```

## 中文字段切勿做对象键

```javascript
// ❌ 致命：中文键在某些环境下取不到值 → undefined → NaN
var deptMap = {'陈溪子':'销售拓展部', '赵云浩':'大客户部', ...};
var dept = deptMap[p.n];  // 可能返回 undefined

// ✅ 正确：数据自带字段
var D = [{n:'陈溪子', dp:'销售拓展部', ...}];
var dept = p.dp;  // 直接取
```

## 数据结构：内嵌静态数据，不用 fetch

月报HTML数据直接硬编码在 `<script>` 中，不用 fetch JSON——确保离线可打开、飞书内可渲染。

```javascript
var D = [
  {n:'陈溪子', dp:'销售拓展部', erp:620894, h1:2334024, tg:6700000},
  // ... 由Python脚本自动生成，请勿手动修改
];
```

## CSS：暗色主题规范

```css
:root {
  --bg: #0f1923;
  --card: #1a2736;
  --pri: #2980b9;
  --accent: #e67e22;
  --green: #27ae60;
  --red: #e74c3c;
  --text: #e8edf2;
  --muted: #8899aa;
  --border: #2a3a4a;
}
```

## 图表类型速查

| 用途 | ECharts类型 | 说明 |
|------|------------|------|
| 部门对比 | 分组柱状图 `bar` | ERP vs KPI两个系列 |
| 个人排名 | 横向柱状图 `bar` + yAxis逆序 | `inverse:true` |
| 客户TOP | 横向柱状图 | 名称截断>16字符 |
| 集中度 | 柱状图+折线图双轴 | 帕累托图 |
| 产品结构 | 环形饼图 | `radius:['40%','70%']` |
| 活动对比 | 分组柱状图 | 6月/7月双系列 |

## 报告六大板块

1. **KPI达成概览** — 4卡片 + 部门/个人图表
2. **个人排名表** — 含ERP/KPI偏差列、全年累计、年达成率、vs时间进度
3. **TOP客户** — 客户柱状图 + 帕累托图 + 明细表
4. **产品结构** — 产品大类饼图 + 订单类型饼图
5. **销售活动** — 飞书MCP 6-7月活动量对比
6. **洞察与待办** — 表格形式关键发现

## 输出路径

`~/Desktop/Hermes输出-工作类/月报/2026年X月月报.html`

## 已知Pitfalls

1. **中文字段名做对象键**：避免 `{'陈溪子':'销售拓展部'}` 这种映射对象，直接用数据自带 `dp` 字段
2. **ECharts CDN加载失败**：飞书WebView可能拦截CDN，确保 `echarts.min.js` 可从 `cdn.jsdelivr.net` 加载
3. **数据量控制**：个人表21人全显，客户表TOP15，活动TOP10
4. **硬编码目标**：不同人目标差异极大（1350万 vs 30万），手工复制极易出错，必须用脚本生成
5. **H1数据源优先ERP**：kpi_dashboard.json的H1值可能来自目标文件而非ERP，优先用ERP Excel汇算