4. 报表导出需求分析：常见报表类型、动态列与静态列、数据聚合与格式化

在构建报表导出模块之前，必须对业务侧的报表需求进行系统性分析。本章聚焦于三个核心维度：报表的物理格式、列结构的可变性以及数据的聚合与呈现规则。这些分析结果将直接决定模板引擎的选型策略和 gRPC 接口的契约设计。

4.1 常见报表类型：PDF / Excel / CSV

不同的输出格式对应不同的渲染引擎和模板策略。下表从技术特征、适用场景和模板引擎适配难度三个角度进行对比：

4.2 动态列与静态列

报表的列结构是模板设计中最复杂的变量。根据业务需求，列可以分为两类：

• 静态列（Static Columns）：列名、顺序、数据类型在模板设计时已固定。例如：订单号、客户名称、创建时间。
• 动态列（Dynamic Columns）：列名、数量、数据来源由用户或业务规则在运行时决定。例如：自定义字段、多语言表头、按日期动态展开的统计列。

动态列的实现通常需要模板引擎支持循环结构和条件判断。以下是一个典型的动态列数据结构定义：

// gRPC proto 定义示例
message DynamicColumn {
  string header = 1;          // 列标题（可能多语言）
  string field_key = 2;       // 数据字段键
  ColumnDataType data_type = 3; // 数据类型（STRING / NUMBER / DATE）
  bool visible = 4;           // 是否可见
  int32 order = 5;            // 显示顺序
}

message ReportData {
  repeated DynamicColumn columns = 1;  // 动态列定义
  repeated Row rows = 2;               // 数据行
}

4.3 数据聚合与格式化

报表数据很少是原始数据库记录的直出。在导出前，通常需要经过聚合计算和格式化处理两个阶段。

4.3.1 聚合计算

常见的聚合操作包括：

• 分组汇总：按部门、时间、产品等维度进行 SUM / COUNT / AVG。
• 累计与占比：计算累计值、百分比、同比环比。
• 排名与分档：TOP N、分位数、等级划分。

聚合逻辑建议在服务端完成，模板引擎只负责渲染最终结果。这样可以保持模板的纯净性，避免在模板中嵌入复杂计算逻辑。

4.3.2 格式化规则

格式化决定了数据在报表中的最终呈现方式。常见的格式化类型包括：

4.4 需求分析对接口契约的影响

上述需求分析结果将直接映射到 gRPC 接口的 proto 定义中。以下是关键影响点：

• 报表格式：在请求消息中增加 ReportFormat format = 1; 枚举字段。
• 动态列：在响应消息中增加 repeated DynamicColumn columns = 2; 元数据字段。
• 聚合与格式化：在请求消息中增加 AggregationConfig aggregation = 3; 和 FormatConfig formatting = 4; 可选配置。