QI MingxuanXP.ReportEngine — PDF 报告生成引擎
概述
XP.ReportEngine 是 XplorePlane 平面 CT 检测系统的 PDF 报告生成模块。负责将检测分析结果（距离测量、BGA 气泡率、空隙测量、通孔填锡率）转换为结构化的 PDF 检测报告。
模块采用管线式架构（Pipeline），将报告生成过程分解为五个独立阶段： 模板加载 → 数据适配 → 数据绑定 → 排版计算 → PDF 渲染
对外提供 IReportService 门面接口，外部模块只需构建 ReportRequest 即可一行调用完成报告生成。
技术栈
| 依赖 | 版本 | 用途 |
|---|---|---|
| .NET 8.0 | net8.0-windows7.0 | 运行时 |
| iText7 | 8.0.5 | PDF 文档生成核心库 |
| itext7.bouncy-castle-adapter | 8.0.5 | iText7 加密支持 |
| Newtonsoft.Json | 13.0.3 | JSON 模板反序列化 |
| Prism.Wpf | 9.0.537 | 模块化框架与 DI |
| Telerik UI for WPF | 2024.1.408 | UI 控件（演示窗口） |
| XP.Common | — | 日志、本地化、通用窗体、PDF 阅读器 |
项目结构
XP.ReportEngine/
├── Configs/ # 配置加载
│ ├── ConfigLoader.cs
│ └── ReportConfig.cs
├── Interfaces/ # 核心接口定义
│ ├── IReportService.cs ★ 门面接口（外部调用入口）
│ ├── IReportGenerator.cs
│ ├── IReportGeneratorFactory.cs
│ ├── ITemplateEngine.cs
│ ├── IDataBinder.cs
│ ├── ILayoutEngine.cs
│ ├── IPdfRenderer.cs
│ └── IReportDataAdapter.cs
├── Models/ # 数据模型
│ ├── ReportRequest.cs ★ 报告生成请求
│ ├── ReportServiceResult.cs ★ 报告服务结果
│ ├── ReportContext.cs
│ ├── ReportMetadata.cs
│ ├── ImageData.cs
│ ├── ReportTemplate.cs
│ ├── TemplateElement.cs
│ ├── LayoutPage.cs
│ ├── ReportResult.cs
│ ├── ReportGenerationOptions.cs
│ ├── ProcessorOutput.cs
│ └── TemplateValidationResult.cs
├── Services/ # 服务实现
│ ├── ReportService.cs ★ 门面服务实现
│ ├── PdfReportGenerator.cs # 管线协调器
│ ├── ReportGeneratorFactory.cs # 工厂
│ ├── JsonTemplateEngine.cs # JSON 模板加载与验证
│ ├── ExpressionDataBinder.cs # ${} 表达式数据绑定
│ ├── PageLayoutEngine.cs # 分页与排版
│ ├── ITextPdfRenderer.cs # iText7 PDF 渲染
│ ├── ProcessorDataAdapter.cs # 处理器数据适配
│ └── ReportIdGenerator.cs # 报告编号生成（RPT-yyyyMMdd-NNN）
├── Templates/ # JSON 报告模板
│ └── StandardReportTemplate.json
├── Resources/ # 多语言资源文件
│ ├── Resources.resx
│ ├── Resources.zh-CN.resx
│ ├── Resources.zh-TW.resx
│ └── Resources.en-US.resx
├── ViewModels/ # 演示窗口 ViewModel
│ └── ReportDemoViewModel.cs
├── Views/ # 演示窗口 View
│ ├── ReportDemoWindow.xaml
│ └── ReportDemoWindow.xaml.cs
├── Documents/ # 项目文档
│ ├── README.md ← 本文件
│ ├── Guidance.md # 使用指南
│ ├── App.config.example # 配置示例
│ ├── FontFilesGuidance.md # 字体方案说明
│ ├── XP.ReportEngineDesign.md # 架构设计文档
│ └── XP.ReportEngineModelDefine.md # 模型定义文档
├── ReportEngineModule.cs # Prism 模块入口
└── XP.ReportEngine.csproj
核心接口
| 接口 | 实现类 | 职责 |
|---|---|---|
IReportService |
ReportService |
门面接口，外部模块调用入口 |
IReportGenerator |
PdfReportGenerator |
协调管线各阶段，生成 PDF |
IReportGeneratorFactory |
ReportGeneratorFactory |
根据格式创建对应生成器 |
ITemplateEngine |
JsonTemplateEngine |
JSON 模板加载、反序列化、验证 |
IDataBinder |
ExpressionDataBinder |
${} 表达式解析与数据绑定 |
ILayoutEngine |
PageLayoutEngine |
分页、元素定位、表格跨页 |
IPdfRenderer |
ITextPdfRenderer |
使用 iText7 渲染 PDF |
IReportDataAdapter |
ProcessorDataAdapter |
ProcessorOutput → ReportContext 转换 |
架构分层
┌─────────────────────────────────────────────────────┐
│ 外部调用方（XP.App、其他模块） │
│ 注入 IReportService，传入 ReportRequest │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ ReportService（门面层） │
│ 生成报告ID → 解析输出路径 → 数据适配 → 注入配置数据 │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ PdfReportGenerator（管线协调层） │
│ 模板加载 → 数据绑定 → 排版计算 → PDF 渲染 → 保存 │
└─────────────────────────────────────────────────────┘
快速开始
详细使用指南请参阅 Documents/Guidance.md。
最简调用（通过 IReportService）
public class MyService
{
private readonly IReportService _reportService;
public MyService(IReportService reportService)
{
_reportService = reportService;
}
public async Task GenerateReport(List<ProcessorOutput> outputs)
{
var request = new ReportRequest
{
ProcessorOutputs = outputs,
Metadata = new ReportMetadata
{
SampleName = "PCB-001",
OperatorName = "张三",
InspectionDate = DateTime.Now
}
};
var result = await _reportService.GenerateAsync(request);
if (result.IsSuccess)
{
// result.OutputFilePath — 生成的 PDF 路径
// result.ReportId — 报告编号
}
}
}
预热机制
模块在 Prism 初始化时自动在后台执行一次预热（WarmUpAsync），触发 iText7 初始化、字体加载、JIT 编译等一次性开销，避免用户首次生成报告时卡顿。
预热与正式生成通过 SemaphoreSlim 互斥锁串行执行，不会出现并发冲突。
数据绑定表达式
模板中支持以下绑定语法：
| 语法 | 说明 | 示例 |
|---|---|---|
${propertyName} |
简单属性绑定 | ${sampleName} |
${object.property} |
嵌套属性路径 | ${metadata.reportId} |
${list[index]} |
列表索引访问 | ${bgaBalls[0].voidRate} |
${functionName(param)} |
格式化函数 | ${formatDate(inspectionDate)} |
${loc:ResourceKey} |
本地化键解析 | ${loc:Report_Title} |
多语言支持
支持三种语言：简体中文（zh-CN）、繁体中文（zh-TW）、英文（en-US）。
通过 ILocalizationService 自动解析 ${loc:Key} 表达式为当前语言文本。模块在初始化时注册资源源到 Fallback Chain。
模板页面类型
标准模板 StandardReportTemplate.json 包含以下页面类型：
| 页面类型 | 说明 |
|---|---|
homepage |
报告首页（公司信息 + 元数据 + 汇总表格） |
summary |
检测结果汇总页 |
metricData |
距离测量数据页 |
bgaInspection |
BGA 焊球检测页（含数据表格） |
voidInspection |
空隙检测页（含数据表格） |
viaFillInspection |
通孔填锡检测页 |
错误处理
模块采用结果对象模式（Result Pattern）：
ReportServiceResult.Success(path, reportId)— 成功ReportServiceResult.Failure(message, ex)— 失败
非致命性问题（缺失属性、图像缺失）会记录警告日志并继续执行，不会中断报告生成。
构建
cd XplorePlane
dotnet build XP.ReportEngine/XP.ReportEngine.csproj
相关文档
Documents/Guidance.md— 详细使用指南（IReportService 调用方式）Documents/TemplateDevelopment.md— 模板开发指南（新增/自定义模板）Documents/App.config.example— 配置文件示例Documents/FontFilesGuidance.md— 字体方案说明Documents/XP.ReportEngineDesign.md— 架构设计文档Documents/XP.ReportEngineModelDefine.md— 模型定义文档