本文介绍一种基于 `groupby().cumcount()` 辅助 `merge` 的技巧，实现两个 dataframe 按“class”分组后逐行对齐拼接，生成适合 streamlit 等前端直接渲染的结构化报告表。

在构建分析型报表（尤其是面向非技术用户或需嵌入 Streamlit/Dash 等交互式界面时），数据的可读性与对齐逻辑往往比纯计算更重要。当需要将两个来源不同但语义相关的 DataFrame（如“历史订单” vs “新订单”、“基准指标” vs “实验指标”）按某一分类维度（如 class）进行“行对行”对齐展示时，标准的 pd.concat(axis=1) 会简单横向堆叠，而 pd.merge() 默认按键完全匹配，均无法满足“每类内按出现顺序逐行配对、缺失则补 NaN”的需求。

核心思路是：为每个 DataFrame 中同一 class 下的记录打上组内序号（0, 1, 2...），再以此序号 + class 作为复合键进行外连接（how='outer'）。这样就能确保：

• 同一 class 下第 1 条记录只与另一表中该 class 的第 1 条记录对齐；
• 若某类在某一表中条目更少，则对应位置自动填充 NaN；
• 所有 class 值均被保留（外连接保障）。

以下是完整实现代码：

import pandas as pd

# 构造示例数据
data1 = {'class': ['A', 'A', 'B', 'X'],
         'item': ['_1', '_2', '_3', '_4'],
         'value': [10, 11, 12, 13]}
data2 = {'class': ['A', 'B', 'B', 'C'],
         'item': ['_5', '_6', '_7', '_8'],
         'value': [20, 21, 22, 23]}
df1 = pd.DataFrame(data1)
df2 = pd.DataFrame(data2)

# 关键步骤：添加组内序号列并执行外连接
out = (df1
       .merge(df2,
              how='outer',
              left_on=['class', df1.groupby('class').cumcount()],
              right_on=['class', df2.groupby('class').cumcount()],
              suffixes=('_1', '_2'))
       .sort_values('class')  # 按 class 排序提升可读性
       .drop(columns=['key_0', 'key_1'], errors='ignore')  # 清理 merge 生成的临时键列（旧版 pandas 可能为 key_0/key_1）
       .reset_index(drop=True))

print(out)

输出结果如下，完全符合目标格式：

  class item_1  value_1 item_2  value_2
0     A     _1     10.0     _5     20.0
1     A     _2     11.0    NaN      NaN
2     B     _3     12.0     _6     21.0
3     B    NaN      NaN     _7     22.0
4     C    NaN      NaN     _8     23.0
5     X     _4     13.0    NaN      NaN

✅ 注意事项与最佳实践：

• cumcount() 返回从 0 开始的整数，天然适合作为序号键；若需从 1 开始，可用 cumcount() + 1，但两表必须保持一致。
• merge 中 left_on/right_on 接收列表，允许同时指定多个列（含动态生成的序号列），这是本方案的关键灵活性所在。
• suffixes=('_1', '_2') 明确区分来源列，避免列名冲突；建议命名体现业务含义（如 '_baseline', '_current'）。
• drop(columns=[...]) 应显式指定待删列名，并添加 errors='ignore' 防止因 pandas 版本差异导致报错（新版可能不生成 key_0/key_1）。
• 若原始数据中 class 列含空值（NaN），groupby('class') 会将其单独归为一组，需提前用 fillna() 处理以保证逻辑正确。

该方法无需循环或自定义函数，完全向量化，兼具简洁性、可读性与工程鲁棒性，是构建高质量分析报表的实用范式。