XplorePlane/XP.ReportEngine/Documents/MultiFormatOutputGuide.md

XP.ReportEngine 多格式输出指南 | Multi-Format Output Guide

1. 概述

XP.ReportEngine 已扩展支持四种报告输出格式：

格式	枚举值	扩展名	适用场景
PDF	ReportOutputFormat.Pdf	.pdf	正式归档报告（默认格式，行为不变）
TXT	ReportOutputFormat.Txt	.txt	人工阅读，快速查看检测结论
CSV	ReportOutputFormat.Csv	.csv	数据二次处理（Excel 打开、数据分析工具）
Excel	ReportOutputFormat.Excel	.xlsx	结构化富格式，分组工作表 + 嵌入图像

新增格式复用现有 IReportService 门面接口和 ReportRequest 模型，外部调用方无需更改接口依赖。

2. 快速开始

2.1 生成单一格式（TXT/CSV/Excel）

var request = new ReportRequest
{
    ProcessorOutputs = outputs,
    Metadata = metadata,
    // 指定输出格式为 CSV
    Formats = new List<ReportOutputFormat> { ReportOutputFormat.Csv }
};

var result = await _reportService.GenerateAsync(request);
// result.OutputFilePath → "xxx.csv"

2.2 生成多种格式（一次请求）

var request = new ReportRequest
{
    ProcessorOutputs = outputs,
    Metadata = metadata,
    // 同时生成 PDF + CSV + Excel（最多 4 种不重复）
    Formats = new List<ReportOutputFormat>
    {
        ReportOutputFormat.Pdf,
        ReportOutputFormat.Csv,
        ReportOutputFormat.Excel
    }
};

var result = await _reportService.GenerateAsync(request);

if (result.IsSuccess)
{
    // 兼容字段（首个成功路径）
    Console.WriteLine(result.OutputFilePath);

    // 各格式输出路径列表
    foreach (var output in result.OutputFilePaths)
    {
        Console.WriteLine($"{output.Format}: {output.FilePath}");
    }
}

2.3 默认行为（不指定 Formats）

var request = new ReportRequest
{
    ProcessorOutputs = outputs,
    Metadata = metadata
    // Formats 为 null 或空 → 默认生成 PDF，与之前行为完全兼容
};

3. 各格式输出特性

3.1 TXT 纯文本

• 面向人工阅读：元数据节 + 检测结果分组（处理器类型 / 分类结论 / 键值对 / 等宽列对齐表格）
• 图像处理策略：排除图像二进制；FilePath 来源 → 记录路径引用文本；Bytes/BitmapSource → 本地化占位标识（如 [图像：二进制数据已省略]）
• 字符编码：默认 UTF-8 with BOM（便于 Excel 打开中文 CSV 不乱码），可通过配置切换
• 空结果：仅输出元数据 + 空结果提示

3.2 CSV 逗号分隔值

• 面向数据分析：并集表头（ProcessorType + Classification + Data 键 + TableRows 列名 + ImageRef）
• RFC 4180 兼容：含逗号/双引号/换行的字段自动双引号包裹与转义
• 多分组合并策略：所有分组的 Data 键与 TableRows 列名取有序并集作为表头；每个分组至少一行；含 TableRows 时每行表格数据各为一条记录
• 图像处理策略：同 TXT（排除二进制，以 ImageRef 列承载路径引用或占位标识）
• 字符编码：同 TXT（默认 UTF-8 with BOM）
• 空结果：仅输出表头行

3.3 Excel 富格式工作簿

Excel 输出支持两种模式：

模式一：默认结构化生成（未配置模板时）

• 元数据工作表：报告编号 / 检测日期 / 样品名称 / 操作员 / 描述（缺失字段 → N/A）
• 分组工作表：每个 ResultGroup 一个独立工作表，名称自动规整（截断 31 字符、替换非法字符、去重）
• 键值对输出：Data 字典每对占一行（键列 + 值列）
• 表格输出：TableRows 表头 + 数据行，列数与表头一致
• 图像嵌入：全局图像（Logo 等）嵌入元数据工作表；解码失败以占位文本替代、不中断
• 空结果：仅元数据工作表 + 空结果提示

模式二：基于模板填充（配置了 DefaultExcelTemplatePath）

• 模板加载：加载 .xlsx 模板副本，不修改源文件
• 占位符语法：{{占位符名}} 文本标记
  • {{Meta.ReportId}}、{{Meta.SampleName}} 等 → 元数据标量值
  • {{Data.键名}} → 首个含该键的分组 Data 值
  • {{Table.列名}} → 表格行插入展开（同行多个 Table.* 构成表头定义）
  • {{Image.键名}} → 图像嵌入到锚点单元格
• 表格行插入：在占位符所在行下方插入 N-1 行，下方原有内容整体下移不覆盖
• 残留清理：无对应数据的占位符记号自动清空，不在输出中残留 {{...}}
• 样式保留：模板原有样式、格式、未被占位符覆盖的内容保持不变
• 模板无效处理：路径配置非空但文件不存在/不可读/非合法 .xlsx → 中止、不写文件、不回退结构化生成、返回失败

4. 配置项

在 App.config 的 <appSettings> 中新增以下配置项：

<!-- TXT/CSV 文本编码 | Text encoding for TXT/CSV -->
<!-- 取值: Utf8Bom（默认）/ Utf8 / GB2312 / GBK -->
<add key="Report:TextEncoding" value="Utf8Bom" />

<!-- 默认 Excel 模板文件路径（可选）| Default Excel template file path (optional) -->
<!-- 配置且指向有效 .xlsx 时走基于模板生成；为空或未配置时走默认结构化生成 -->
<add key="Report:DefaultExcelTemplatePath" value="" />

编码选项说明：

配置值	含义	BOM	适用场景
Utf8Bom	UTF-8 with BOM（默认）	EF BB BF	Excel 打开中文 CSV 不乱码
Utf8	UTF-8 without BOM	无	程序化读取、Linux 环境
GB2312	GB2312 编码	无	旧版系统兼容
GBK	GBK 编码	无	旧版系统兼容

注意：编码配置仅对 TXT 与 CSV 生效。Excel 的 .xlsx 为二进制 OOXML 格式，内部统一 UTF-8 处理，不受此配置影响。

5. 文件命名规则

新格式沿用现有 ReportConfig.FileNamePattern 占位符解析机制，仅扩展名按格式变化：

格式	生成文件名示例
PDF	20250512_PCB-A01_SN001_RPT-20250512-001.pdf
TXT	20250512_PCB-A01_SN001_RPT-20250512-001.txt
CSV	20250512_PCB-A01_SN001_RPT-20250512-001.csv
Excel	20250512_PCB-A01_SN001_RPT-20250512-001.xlsx

重复文件名处理：

• AutoIncrementOnDuplicate = true：自动追加序号 (1)、(2) ... 最多 (9999)
• AutoIncrementOnDuplicate = false：文件已存在时返回错误，不覆盖

显式路径优先：

• 单格式 + 显式 OutputFilePath → 直接使用该路径
• 多格式 + 显式 OutputFilePath → 以该路径为基准按各格式扩展名派生

6. 多格式编排规则

规则	说明
格式数量	1～4 种不重复
默认格式	Formats 为空时默认 PDF
数据适配	仅执行一次（不随格式重复）
失败策略	任一格式失败立即返回 Failure，已生成文件保留不回滚
结果聚合	ReportServiceResult.OutputFilePaths 含各格式路径列表

7. 错误处理

格式校验错误

情形	结果
格式数量超过 4	Failure（不生成任何文件）
包含重复格式	Failure（不生成任何文件）
包含未定义枚举值	Failure（不生成任何文件）

生成错误

情形	结果
ReportContext 或 Metadata 为 null	Failure（不写文件，Error 日志）
I/O 写入失败	Failure（不残留不完整文件，Error 日志）
Excel 模板路径无效	Failure（不回退、不写文件、Error 日志）

非致命情形（不中断生成）

情形	行为
图像解码失败	跳过该图像，以占位文本替代
元数据字段缺失	以 N/A 占位
编码配置无效	回退 UTF-8 with BOM，Warn 日志
多语言资源键缺失	用资源键名作占位文本

8. 多语言支持

TXT 和 Excel 报告中的固定标签（字段标题、节标题、工作表名等）通过 ILocalizationService 按当前语言获取，支持 zh-CN / zh-TW / en-US。

单次生成语言一致：生成开始时一次性确定语言，整个生成过程中使用同一语言标签，不支持生成中热切换。

9. ReportServiceResult 扩展字段

字段	类型	说明
OutputFilePaths	List<FormatOutput>	各格式输出路径列表（仅含成功生成的格式）

FormatOutput

字段	类型	说明
Format	ReportOutputFormat	输出格式
FilePath	string	该格式的输出文件路径

OutputFilePath（向后兼容字段）= 首个成功格式的路径。

10. Excel 模板开发指南

10.1 占位符命名约定

前缀	分类	示例	填充行为
Meta.	标量（元数据）	{{Meta.ReportId}}、{{Meta.SampleName}}	替换为元数据字段值
Data.	标量（数据键值）	{{Data.VoidRate}}、{{Data.Distance}}	替换为首个匹配分组的 Data 值
Table.	表格	{{Table.BallId}}、{{Table.VoidRate}}	行插入展开
Image.	图像	{{Image.companyLogo}}、{{Image.softwareLogo}}	嵌入图像到锚点单元格
无前缀	标量（Properties）	{{batchNumber}}	查 ReportContext.Properties

10.2 表格行插入规则

1. 在模板中设计表头行，每个单元格内放置 {{Table.列名}}
2. 生成时将所有分组的 TableRows 按顺序拼接为一张表
3. 若数据行 N > 1，在占位符行下方插入 N-1 行，原有内容整体下移
4. 每行按占位符列位置填入对应字段值，缺失列留空

10.3 模板设计建议

• 将固定样式（表头、Logo、公司信息）设计在模板中，仅用占位符标记动态内容
• 表格占位符行下方留有足够空间（行插入会自动下移内容，但底部预留更美观）
• Logo 等图像占位符所在单元格可适当合并或调整行高/列宽以控制图像显示尺寸
• 模板文件建议存放在应用配置目录（如 Templates/），路径通过 Report:DefaultExcelTemplatePath 配置

11. 架构概览

┌─────────────────────────────────────────────────────┐
│  外部调用方                                           │
│  ReportRequest { Formats = [Pdf, Csv, Excel] }      │
└──────────────────────┬──────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────┐
│  ReportService（门面层）                              │
│  格式校验 → 数据适配(一次) → 多格式编排循环            │
└──────────────────────┬──────────────────────────────┘
                       │ foreach format
┌──────────────────────▼──────────────────────────────┐
│  ReportGeneratorFactory                              │
│  Pdf → PdfReportGenerator (管线)                     │
│  Txt → TxtReportGenerator (纯文本)                   │
│  Csv → CsvReportGenerator (RFC 4180)                │
│  Excel → ExcelReportGenerator (ClosedXML)           │
└─────────────────────────────────────────────────────┘

12. 依赖说明

新增依赖	版本	用途
ClosedXML	0.104.x	Excel (.xlsx) 工作簿读写与图像嵌入
System.Text.Encoding.CodePages	—	.NET 8 中启用 GB2312/GBK 代码页编码

13. 相关文件

文件	说明
Services/TxtReportGenerator.cs	TXT 生成器实现
Services/CsvReportGenerator.cs	CSV 生成器实现
Services/ExcelReportGenerator.cs	Excel 生成器实现
Services/TextReportGeneratorBase.cs	TXT/CSV 共享基类
Services/ExcelSheetNameSanitizer.cs	工作表名规整帮助类
Services/ReportFormatExtensions.cs	格式→扩展名映射
Services/PlaceholderRef.cs	模板占位符索引数据结构
Services/EncodingResolver.cs	编码解析逻辑