在构建 “XXXX处理系统” 的过程中，需要开发一个统计分析模块。该模块需要读取 Pandas 处理后的 CSV 数据，并生成一个包含交互式图表的 HTML 报告（基于 Plotly）。在将后端逻辑接入 PySide6 GUI 界面时，我们遇到了一系列典型的 Python 数据处理与界面集成问题。

1. Matplotlib 后端冲突与类重复定义

1. 现象
   点击“生成报告”时，程序崩溃并弹窗提示 KeyError: ‘font-family’。

2. 原因分析
   这是一个复合型问题：

代码冗余：src 目录下存在两个文件（section_analysis.py 和 statistics.py），它们内部都定义了名为 StatisticsAnalyzer 的类。主程序 main_window.py 错误地引用了旧版（功能不全）的类。

后端冲突：旧版代码中引入了 matplotlib.pyplot。在 PySide6（Qt）的 GUI 线程中，如果未正确配置 Matplotlib 的后端（Backend），直接 import 或调用绘图函数往往会导致配置字典键值丢失（如 font-family）或线程崩溃。

3. 解决方案
   清理冗余：删除 section_analysis.py 中重复且过时的 StatisticsAnalyzer 类，只保留在 statistics.py 中的完整版。

移除冲突库：由于新版报告完全采用 Plotly 生成，彻底删除了 statistics.py 中无用的 import matplotlib.pyplot as plt 引用。

2. Plotly 不接受惰性迭代器 (Range)

1. 现象
   报错提示：Invalid value of type ‘builtins.range’ received for the ‘x’ property。

2. 原因分析
   我们试图绘制累计差异图，X轴使用了 range(len(data))。在 Python 3 中，range() 返回的是一个 迭代器（Iterator） 对象，而不是实体列表。Plotly 的绘图引擎在接收数据时，需要显式的列表（List）或数组（Array），无法直接消费惰性求值的 range 对象。

3. 解决方案
   显式转换类型，用 list() 包裹 range 对象：

// python
# 修改前
x = range(len(sorted_data))
# 修改后
x = list(range(len(sorted_data)))

3. JSON 序列化之“键”的类型错误

1. 现象
   报错提示：keys must be str, int, float, bool or None, not numpy.int64。

2. 原因分析
   在使用 Pandas 读取 CSV 时，整数列（如断面索引 section_index）被自动存储为 numpy.int64 类型。当我们遍历这些数据并将断面索引作为字典的 Key（例如 data[section_idx] = …）时，json.dumps 尝试将字典转为 JSON。标准 JSON 规范要求 Key 必须是字符串（标准库会自动将 Python int 转为字符串 Key），但它不认识 NumPy 的 int64 类型，因此拒绝转换。

3. 解决方案
   在构建字典时，强制将 NumPy 整数转换为 Python 原生整数：

// python
# 修改前
section_chart_data[section] = section_data  # section 是 numpy.int64
# 修改后
section_chart_data[int(section)] = section_data # 强转为 python int

4. JSON 序列化之“值”的类型错误

1. 现象
   解决了 Key 的问题后，紧接着报错：Object of type int64 is not JSON serializable。

2. 原因分析
   这次的问题出在字典的 Value 中。我们的数据字典包含了从 Pandas DataFrame 中提取的里程、坐标等数值，这些数值保留了 NumPy 的数据类型（如 numpy.int64, numpy.float64）。Python 原生的 json 库同样无法序列化这些 NumPy 数据类型。

3. 解决方案
   使用 Plotly 提供的专用编码器 PlotlyJSONEncoder，它专门用于处理 NumPy 和 Pandas 的数据类型转换。

// python
import json
import plotly.utils  # 引入工具库
# 修改前
json_str = json.dumps(data, ensure_ascii=False)

# 修改后
json_str = json.dumps(data, cls=plotly.utils.PlotlyJSONEncoder, ensure_ascii=False)

5. Python 字符串格式化的误区

1. 现象
   报错提示：KeyError: ‘plotly_json’。

2. 原因分析
   在 HTML 模板字符串中保留了一段 JavaScript 注释代码，其中包含 {plotly_json} 占位符：

// python
html_template = 
"""
    <script>
        // var data = {plotly_json};  <-- 这是一个 JS 注释
    </script>
"""

虽然在 JavaScript 看来这是注释，但在 Python 的 .format() 方法眼中，这只是一个等待被替换的文本占位符。由于我们在 .format() 调用中注释掉了对应的参数赋值，Python 找不到填充数据，随即报错。

3. 解决方案
   代码即文本。在处理模板字符串时，必须物理删除那些不需要替换的占位符，即使它们位于目标语言（JS/HTML）的注释中。

// python
# 修改后：直接删除无用的注释行
html_template = """
    <script>
        var mainChartData = __PLOTLY_JSON__; // 使用更安全的替换策略
    </script>
"""

总结

GUI 开发：PySide/PyQt 线程中慎用 Matplotlib，除非确信后端配置正确。推荐使用 WebEngineView + Plotly/Echarts 的方案，交互性更好且不易崩溃。

数据类型：Pandas/NumPy 与 Python 原生类型（List/Dict/JSON）交互时，务必注意类型转换。凡是涉及 JSON 序列化 NumPy 数据，优先考虑 PlotlyJSONEncoder 或自定义 Encoder。

模板引擎：使用 .format() 处理复杂代码模板（含 {}）极其容易出错。对于长文本替换，建议使用更明确的替换标记（如 _ _ DATA _ _）配合 .replace() 方法，或者使用专业的模板引擎（如 Jinja2）。