# charts 模式实现说明（现行版）

> 旧版实现在 `docs/旧的关于charts模式的实现.md`。

## 现状概览
- 后端强制 `generate_plots=False`，所有步骤只产出数据，`analysis.<lang>.charts` 收口。
- `images` 为空对象，保留兼容；`steps[].chart` 绑定对应图表 key。
- 清洗函数 `to_echarts_safe` 递归处理 NaN/Inf/Timestamp/numpy/Decimal，确保 JSON-safe。

## 关键结构
- 响应：`analysis.<lang>.charts`（顶层未暴露 charts）。
- 时间序列、季节分解、VAR 等使用 dataset；相关性使用扁平 heatmap；PCA/聚类/因子用 records。
- ACF/PACF：每个列含 `acf`/`pacf` 两个序列（与旧文档拆成两条 series 不同）。
- 正态性：每列包含 histogram 分箱（后端 `np.histogram`），加 Shapiro/JB 结果。
- 频谱：当前为摘要版（spectrogram 只给均值+shape，periodogram 仅前 20 点）。

## 文件与代码映射
- 清洗与汇总：`app/services/analysis_system.py`（`to_echarts_safe`、`_build_chart_payload`、`run_analysis`）。
- 时序数据：`app/services/analysis/modules/time_series.py`（数据-only，频谱摘要版）。
- 正态性分箱：`app/services/analysis/modules/basic.py`。
- 路由返回：`app/api/routes/analysis.py`、`app/api/routes/analysis_v2.py`（`charts` 位于 `analysis.<lang>`）。

## 与旧版差异
- 不再生成图片；顶层不提供 `charts` 字段。
- ACF/PACF 结构改变；频谱从全量矩阵切换为摘要版。
- 正态性直方图格式为字典字段而非二维数组。

## 后续可选改进
1) 路由层增加顶层 `charts` 别名，便于前端无感迁移。
2) ACF/PACF 输出可改为拆分 series（与旧版示例一致）。
3) 频谱提供 `full/summary` 开关，允许返回完整矩阵或摘要。
4) 为大数据集增加抽样/截断策略，防止超大 payload。