# 关于 charts 模式的实现

## 目标与范围
- 按 `docs/charts-data-mode-plan.md` 将后端改为返回结构化图表数据（ECharts 友好），不再生成/返回图片。
- 保持算法与分析流程不变，仅调整封装与响应结构；旧前端通过空的 `images` 字段保持兼容。

## 核心实现
- **统一清洗函数**：在 `app/services/analysis_system.py` 增加 `to_echarts_safe`，递归处理 NaN/Inf/pd.NA、numpy 标量/数组、Timestamp/datetime、Decimal，带循环引用保护，输出 JSON-safe 结构。
- **分析流程改造**：
  - 在 `run_analysis` 内强制 `generate_plots=False`，改用 `charts` 收集每步结果，`steps[].chart` 指向对应 key。
  - 为每个步骤新增 `chart_key`，映射到 `charts`：
    - `stats`（统计概览 dataset 表格）、`ts`（时间序列 dataset）、`acf_pacf`（acf/pacf 序列）、`stationarity`、`normality`（表格）、`seasonal`、`spectral`、`heatmap`（相关矩阵 flatten）、`pca_scree`、`pca_scatter`、`feature_importance`、`cluster`、`factor`（records）、`cointegration`（表格 meta）、`var_forecast`（forecast dataset，含 step 列）。
  - `_build_chart_payload` 依据 chart_key 组装 ECharts 友好的 dataset/records/flatten 结构，并通过 `to_echarts_safe` 清洗。
  - 移除 fallback 图片生成，仅保留文字 fallback 分析。
- **数据层改动**：
  - 正态性检验在 `app/services/analysis/modules/basic.py` 内增加直方图分箱：`np.histogram` 返回 `[range_start, range_end, count]` 列表，便于前端直接渲染。

## 路由响应调整
- v1 `POST /api/analyze` 与 v2 `POST /api/v2/analyze`：
  - `analysis.<lang>.charts` 返回各图表数据；`steps` 保留顺序与摘要，并携带 `chart` 引用。
  - `images` 始终为空对象，仅为兼容旧前端；删除旧的图片复制/保存逻辑，并剔除 `image_path` 泄露。

## 兼容性与注意事项
- 核心算法、预处理、API 分析调用保持原样；仅输出封装变化。
- 如果前端仍使用旧版，需要改为读取 `analysis.<lang>.charts` 与 `steps[].chart`。旧字段（images）为空不会报错。
- 大型数据仍需关注内存占用；如需进一步压缩，可在 `_build_chart_payload` 中添加截断/抽样。

## 相关文件
- 实现细节：`app/services/analysis_system.py`
- 直方图分箱：`app/services/analysis/modules/basic.py`
- 路由返回：`app/api/routes/analysis.py`、`app/api/routes/analysis_v2.py`
- 设计说明：`docs/charts-data-mode-plan.md`

## 2026-01-29 补充
- ACF/PACF 输出改为按 `lag/value` 的 records，便于前端直接做 bar/line 映射。
- 频谱输出：
  - `spectrogram` 增加降采样并返回 `values: [i,j,val]`，附 `f`、`t` 列表。
  - `periodogram` 返回 dataset 形式 `["f","psd"]`（截断前 200 点）。
- `docs/api-endpoints-status.md` 已更新状态，标记 charts 模式落地，`images` 为空仅兼容。 

## 2026-01-29 后续调整
- 应需求取消频谱降采样：`spectrogram` 现返回全量 `f/t` 与全部 `values[i,j,val]`，`periodogram` 返回全量频点 dataset（可能显著增大 payload；如需再控体积，可重新引入上限或抽样）。

## 2026-01-29 再次更新
- time_series 模块回归“只返数据不生成图片”：时间序列、ACF/PACF、季节分解、频谱均不再绘图，直接返回 charts 所需数据；频谱依旧不降采样，返回全量值。