OpsMind 图表模块重构

wwxdsg2026-02-152026-03-25

一、背景与问题发现

1.1 项目背景

OpsMind 是一个智能运营助手，支持 25 种交互式图表的自动生成。在 LLM 图表映射增强功能开发完成后，我们发现了一个架构层面的问题：

问题现象：generate_charts() 方法代码量达到 ~800 行，且持续增长。

1.2 问题发现过程

在一次代码审查中，我注意到以下代码模式反复出现：

# 每种图表都有类似的判断逻辑
if "histogram" in chart_types:
    m = column_mappings.get("histogram", {})
    hist_col = _get_col(m, "values", numeric_cols, 0)
    color_col = _get_col(m, "color_col", [], 0)
    
    if hist_col:
        if color_col:
            # 按分组列绘制
            ...
        else:
            # 不分组绘制
            ...

if "scatter" in chart_types:
    m = column_mappings.get("scatter", {})
    x_col = _get_col(m, "x_axis", numeric_cols, 0)
    y_col = _get_col(m, "y_axis", numeric_cols, 1)
    color_col = _get_col(m, "color", [], 0)
    
    if x_col and y_col:
        if color_col:
            # 带颜色分组绘制
            ...
        else:
            # 普通绘制
            ...

问题识别：同样的”判断-回退-绘制”模式在 25 种图表中重复出现。

二、问题分析与诊断

2.1 根因分析

使用 5 Why 分析法 追根溯源：

问题：generate_charts() 代码冗长、职责混乱

Why 1: 为什么代码冗长？
→ 每种图表都有判断逻辑、回退逻辑、绘制逻辑

Why 2: 为什么每种图表都要重复这些逻辑？
→ 因为绘制方法需要处理"配置不完整"的情况

Why 3: 为什么配置会不完整？
→ LLM 生成的配置可能缺失字段或使用无效列名

Why 4: 为什么不在配置阶段就解决这些问题？
→ 配置生成和绘制耦合在一起，没有明确分离

Why 5: 为什么没有分离？
→ 初期设计时没有预见到配置验证的复杂性

根因：配置生成职责和绘制职责没有分离。

2.2 职责混乱诊断

┌─────────────────────────────────────────────────────────────────────────┐
│                     原始 generate_charts() 职责分析                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐      │
│   │   配置解析      │   │   默认值回退    │   │   图表绘制      │      │
│   │                 │   │                 │   │                 │      │
│   │ • 提取映射字段  │   │ • 列名不存在时  │   │ • matplotlib    │      │
│   │ • 类型转换      │   │ • 字段缺失时    │   │ • plotly        │      │
│   │ • 空值处理      │   │ • 使用第一列    │   │ • 样式配置      │      │
│   └─────────────────┘   └─────────────────┘   └─────────────────┘      │
│                                                                          │
│   问题：三种职责混在一个方法中，导致代码膨胀、难以维护                    │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

2.3 量化分析

指标	重构前	理想值
代码行数	~800 行	~400 行
圈复杂度	高（多层嵌套）	低（扁平结构）
单一职责违反	是	否
可测试性	困难	容易
可扩展性	差（每次修改多处）	好（只改配置）

三、方案设计与评估

3.1 方案构思

基于根因分析，提出 配置驱动架构：

┌─────────────────────────────────────────────────────────────────────────┐
│                          配置驱动架构                                    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   配置生成阶段                          绘制阶段                          │
│   ┌─────────────────────┐              ┌─────────────────────┐          │
│   │ _generate_chart_    │              │ generate_charts()   │          │
│   │ config()            │  ─────────►  │                     │          │
│   │                     │   完整配置   │ • 检查 status       │          │
│   │ • LLM 推断列映射    │              │ • 直接使用配置      │          │
│   │ • Schema 验证       │              │ • 纯绘制逻辑        │          │
│   │ • 默认值补充        │              │ • 不做任何判断      │          │
│   │ • 输出完整配置      │              │                     │          │
│   └─────────────────────┘              └─────────────────────┘          │
│                                                                          │
│   职责：配置完整性保证                   职责：按配置绘制                │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

3.2 方案对比

方案	优点	缺点	评分
方案A：维持现状	无需改动	技术债务持续累积	⭐
方案B：抽取工具函数	减少重复代码	职责仍然混乱	⭐⭐
方案C：配置驱动	职责清晰、易维护	需要重构	⭐⭐⭐⭐⭐

3.3 详细设计

3.3.1 渲染规范定义

CHART_RENDER_SPEC = {
    "histogram": {
        "cond": "≥1 数值列",
        "required": {"col": "str : 分布分析的数值列名"},
        "optional": {"color_col": "str|null : 分组显示的分类列名"},
    },
    "bullet": {
        "cond": "≥2 数值列 + ≥1 分类列",
        "required": {
            "category_col": "str : 指标/类别列名",
            "actual_col":   "str : 实际值列名",
            "target_col":   "str : 目标值列名",
        },
        "optional": {},
    },
    # ... 25种图表的完整规范
}

设计要点：

required：必填字段，缺失则 status: skip
optional：可选字段，缺失不影响绘制
cond：绘图条件说明，供 LLM 参考

3.3.2 配置生成流程

┌─────────────────────────────────────────────────────────────────────────┐
│                      _generate_chart_config() 流程                       │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   输入：query + 数据详情 + 图表类型 + domain/logic                        │
│                              │                                           │
│                              ▼                                           │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │ Step 1: 构建数据上下文                                           │   │
│   │   • 数值列统计（min/max/mean/std）                               │   │
│   │   • 分类列唯一值                                                 │   │
│   │   • 日期时间列                                                   │   │
│   └─────────────────────────────────────────────────────────────────┘   │
│                              │                                           │
│                              ▼                                           │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │ Step 2: 构建字段规范文本（从 CHART_RENDER_SPEC 生成）            │   │
│   │   • 必填字段说明                                                 │   │
│   │   • 可选字段说明                                                 │   │
│   │   • 绘图条件                                                     │   │
│   └─────────────────────────────────────────────────────────────────┘   │
│                              │                                           │
│                              ▼                                           │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │ Step 3: LLM 调用                                                  │   │
│   │   • temperature=0.05（高稳定性）                                 │   │
│   │   • 输出格式：{chart_type: {status, ...字段}}                    │   │
│   └─────────────────────────────────────────────────────────────────┘   │
│                              │                                           │
│                              ▼                                           │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │ Step 4: Schema 验证                                               │   │
│   │   • 必填字段存在性检查                                           │   │
│   │   • 列名有效性检查                                               │   │
│   │   • 决定 status: ok / skip                                       │   │
│   └─────────────────────────────────────────────────────────────────┘   │
│                              │                                           │
│                              ▼                                           │
│   输出：{chart_type: {status: "ok/skip", ...字段}}                       │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

四、风险评估与应对

4.1 风险识别

风险类型	风险描述	可能性	影响	风险等级
兼容性风险	现有调用方可能依赖旧行为	中	高	🔴 高
性能风险	LLM 调用可能增加延迟	低	中	🟡 中
正确性风险	Schema 验证可能遗漏边界情况	中	高	🔴 高
回滚风险	重构后难以回滚	低	高	🟡 中

4.2 应对策略

4.2.1 兼容性风险应对

# 保留原有接口签名
def generate_charts(self, df, chart_types=None, binned_columns=None, 
                    column_mappings=None) -> List[str]:
    """
    保持向后兼容：
    - column_mappings=None 时使用原有默认逻辑
    - column_mappings 有值时使用配置驱动
    """
    if column_mappings is None:
        column_mappings = {}
    
    # 新增：检查 status 字段
    def _skip(ct: str, m: dict) -> bool:
        if m.get("status") != "ok":
            logger.info(f"跳过 {ct}: {m.get('reason')}")
            return True
        return False
    
    # 绘制逻辑...

4.2.2 正确性风险应对

# 多层验证机制
NON_COL_FIELDS = {"agg_func", "method", "left_label", "right_label"}

for field in req_fields:
    val = raw_m.get(field)
    
    # 验证1：字段存在性
    if val is None or val == "":
        errors.append(f"缺少必填字段 '{field}'")
    
    # 验证2：列名有效性（排除非列名字段）
    elif isinstance(val, str) and field not in NON_COL_FIELDS:
        if val not in all_cols:
            errors.append(f"'{field}'='{val}' 不是有效列名")
    
    # 验证3：数组非空
    elif isinstance(val, list):
        if not val:
            errors.append(f"'{field}' 数组为空")

4.2.3 回滚风险应对

保留原有 _get_col() 等辅助函数（注释状态）
配置文件保存完整信息，便于调试
增加详细日志记录

五、执行方案与实施

5.1 实施步骤

Step 1: 定义渲染规范
        └── 在 interactive_charts.py 中添加 CHART_RENDER_SPEC

Step 2: 增强配置生成
        └── 重构 _generate_chart_config()，增加 Schema 验证

Step 3: 简化绘制方法
        └── 移除判断逻辑，只保留纯绘制代码

Step 4: 增加状态检查
        └── 添加 _skip() 辅助函数

Step 5: 测试验证
        └── 单元测试 + 集成测试

5.2 关键代码变更

5.2.1 新增渲染规范

# interactive_charts.py
CHART_RENDER_SPEC: Dict[str, Any] = {
    "histogram": {
        "cond": "≥1 数值列",
        "required": {"col": "str : 分布分析的数值列名"},
        "optional": {"color_col": "str|null : 分组显示的分类列名"},
    },
    "scatter": {
        "cond": "≥2 不同数值列",
        "required": {
            "x_col": "str : X轴数值列名",
            "y_col": "str : Y轴数值列名（须与x_col不同）",
        },
        "optional": {
            "color_col": "str|null : 颜色分组列名",
            "size_col":  "str|null : 大小映射数值列名",
        },
    },
    # ... 25种图表
}

5.2.2 配置生成重构

# pandas_ai_service.py
def _generate_chart_config(self, query, df, chart_types, ...) -> Dict:
    """生成完整的图表配置，包含 Schema 验证"""
    
    # 1. 引用渲染规范
    CHART_RENDER_SPEC = InteractiveChartGenerator.CHART_RENDER_SPEC
    
    # 2. 构建数据上下文
    data_context = self._build_data_context(df)
    
    # 3. 构建字段规范文本
    schema_text = self._build_schema_text(chart_types, CHART_RENDER_SPEC)
    
    # 4. LLM 调用
    raw_output = self._call_llm(prompt)
    
    # 5. Schema 验证
    validated = self._validate_schema(raw_output, CHART_RENDER_SPEC, df)
    
    return {"column_mappings": validated, "config_file": config_file}

5.2.3 绘制方法简化

# 重构前
if "histogram" in chart_types:
    m = column_mappings.get("histogram", {})
    hist_col = _get_col(m, "values", numeric_cols, 0)
    color_col = _get_col(m, "color_col", [], 0)
    if hist_col:
        if color_col:
            # ... 分组绘制
        else:
            # ... 普通绘制

# 重构后
if "histogram" in chart_types:
    m = column_mappings.get("histogram", {})
    if not _skip("histogram", m):
        col = m["col"]                    # 直接使用
        color_col = m.get("color_col")    # 直接使用
        # ... 绘制（无需判断）

5.3 实施成果

指标	重构前	重构后	改善
代码行数	~800 行	~400 行	-50%
圈复杂度	高	低	显著降低
职责分离	混乱	清晰	✅
可测试性	困难	容易	✅
可扩展性	差	好	✅

六、后期测试与验证

6.1 测试策略

┌─────────────────────────────────────────────────────────────────────────┐
│                           测试金字塔                                    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│                        ┌─────────────────┐                              │
│                        │   端到端测试    │                              │
│                        │   用户场景验证  │                              │
│                        └─────────────────┘                              │
│                    ┌─────────────────────────┐                          │
│                    │      集成测试           │                          │
│                    │  配置生成 → 图表绘制    │                          │
│                    └─────────────────────────┘                          │
│              ┌───────────────────────────────────┐                      │
│              │           单元测试                │                      │
│              │  Schema验证 / 列名验证 / 配置解析 │                      │
│              └───────────────────────────────────┘                      │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

6.2 单元测试

6.2.1 Schema 验证测试

def test_schema_validation_required_field_missing():
    """测试必填字段缺失时返回 skip"""
    spec = CHART_RENDER_SPEC["histogram"]
    raw_m = {}  # 缺少 col 字段
    
    result = validate_schema("histogram", raw_m, spec, df)
    
    assert result["status"] == "skip"
    assert "缺少必填字段" in result["reason"]


def test_schema_validation_invalid_column():
    """测试无效列名时返回 skip"""
    spec = CHART_RENDER_SPEC["histogram"]
    raw_m = {"col": "non_existent_column"}
    
    result = validate_schema("histogram", raw_m, spec, df)
    
    assert result["status"] == "skip"
    assert "不是有效列名" in result["reason"]


def test_schema_validation_ok():
    """测试有效配置时返回 ok"""
    spec = CHART_RENDER_SPEC["histogram"]
    raw_m = {"col": "age", "color_col": "gender"}
    
    result = validate_schema("histogram", raw_m, spec, df)
    
    assert result["status"] == "ok"
    assert result["col"] == "age"
    assert result["color_col"] == "gender"

6.2.2 配置生成测试

def test_generate_chart_config_integration():
    """测试配置生成集成"""
    engine = DataAnalysisEngine()
    df = pd.DataFrame({
        "age": [25, 30, 35, 40],
        "salary": [5000, 8000, 12000, 15000],
        "department": ["A", "B", "A", "B"]
    })
    
    result = engine._generate_chart_config(
        query="分析年龄分布",
        df=df,
        chart_types=["histogram", "bar"],
        domain="HR",
        logic="DISTRIBUTION"
    )
    
    mappings = result["column_mappings"]
    
    # 验证 histogram 配置
    assert "histogram" in mappings
    assert mappings["histogram"]["status"] == "ok"
    assert mappings["histogram"]["col"] in ["age", "salary"]

6.3 集成测试

def test_end_to_end_chart_generation():
    """端到端测试：从查询到图表生成"""
    engine = DataAnalysisEngine()
    
    # 1. 加载数据
    df = engine.load_data("test_data.xlsx")
    
    # 2. 判断图表类型
    chart_result = engine._determine_chart_types(
        query="分析各部门薪资分布",
        df=df,
        domain="HR",
        logic="DISTRIBUTION"
    )
    chart_types = chart_result["chart_types"]
    
    # 3. 生成配置
    config = engine._generate_chart_config(
        query="分析各部门薪资分布",
        df=df,
        chart_types=chart_types,
        domain="HR",
        logic="DISTRIBUTION"
    )
    
    # 4. 生成图表
    chart_files = engine.generate_charts(
        df=df,
        chart_types=chart_types,
        column_mappings=config["column_mappings"]
    )
    
    # 验证
    assert len(chart_files) > 0
    for f in chart_files:
        assert os.path.exists(f)

6.4 测试结果

测试类型	测试用例数	通过率
单元测试	25	100%
集成测试	10	100%
端到端测试	5	100%

七、方法论总结

7.1 重构方法论框架

┌─────────────────────────────────────────────────────────────────────────┐
│                        重构方法论框架                                    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                │
│   │  问题发现   │ ─► │  问题分析   │ ─► │  方案设计   │                │
│   │             │    │             │    │             │                │
│   │ • 代码审查  │    │ • 根因分析  │    │ • 方案对比  │                │
│   │ • 指标监控  │    │ • 职责诊断  │    │ • 详细设计  │                │
│   │ • 团队反馈  │    │ • 量化分析  │    │ • 架构设计  │                │
│   └─────────────┘    └─────────────┘    └─────────────┘                │
│          │                  │                  │                        │
│          └──────────────────┴──────────────────┘                        │
│                              │                                           │
│                              ▼                                           │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                │
│   │  风险评估   │ ─► │  方案执行   │ ─► │  后期测试   │                │
│   │             │    │             │    │             │                │
│   │ • 风险识别  │    │ • 分步实施  │    │ • 单元测试  │                │
│   │ • 风险分级  │    │ • 代码变更  │    │ • 集成测试  │                │
│   │ • 应对策略  │    │ • 增量发布  │    │ • 回归测试  │                │
│   └─────────────┘    └─────────────┘    └─────────────┘                │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

7.2 关键原则

原则	说明	本次应用
单一职责	一个方法只做一件事	配置生成与绘制分离
配置驱动	用配置替代硬编码	CHART_RENDER_SPEC
渐进式重构	小步快跑，逐步优化	分5步实施
测试先行	重构前设计测试用例	25个单元测试
向后兼容	保持接口稳定	保留原有签名

7.3 经验教训

成功经验

根因分析很重要：使用 5 Why 找到真正的问题根源
量化分析有说服力：用数据证明问题的严重性
风险评估不可少：提前识别风险，准备应对方案
测试是安全网：完善的测试让重构更有信心

改进空间

更早引入测试：应该在重构前就编写测试用例
更细粒度发布：可以分阶段发布，降低风险
文档同步更新：重构后及时更新技术文档

7.4 可复用模板

# 重构检查清单

## 问题发现
- [ ] 代码审查发现问题
- [ ] 指标监控异常
- [ ] 团队反馈收集

## 问题分析
- [ ] 5 Why 根因分析
- [ ] 职责边界诊断
- [ ] 量化指标评估

## 方案设计
- [ ] 多方案对比
- [ ] 详细设计文档
- [ ] 架构图绘制

## 风险评估
- [ ] 风险识别清单
- [ ] 风险等级评估
- [ ] 应对策略制定

## 方案执行
- [ ] 分步实施计划
- [ ] 代码变更记录
- [ ] 增量发布验证

## 后期测试
- [ ] 单元测试覆盖
- [ ] 集成测试验证
- [ ] 回归测试通过