ccdi/docs/reports/implementation/2026-05-07-project-overview-pdf-chinese-font-fix.md

项目总览 PDF 中文字体配置化修复实施记录

保存路径确认

• 文档类型：实施记录
• 保存路径：docs/reports/implementation/

问题说明

• 异常信息：com.ruoyi.common.exception.ServiceException: 未找到可用中文字体，无法导出PDF报告
• 触发链路：结果总览导出 PDF 时，CcdiProjectOverviewReportPdfExporter 需要通过 PDFBox 加载中文字体；原实现依赖代码内置候选路径，部署环境字体路径不可控时会导致导出失败。

修改内容

• 修改 ccdi-project/src/main/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectOverviewReportPdfExporter.java
  • 删除 Java 代码内置多路径候选列表。
  • 通过 ccdi.report.pdf-font-path 读取 profile 配置中的单个字体路径。
  • 配置为空时提示 未配置PDF中文字体路径，无法导出PDF报告。
  • 配置文件不存在、格式不支持或字体不可导出时，错误信息包含配置路径。
  • .ttc 字体集合优先选择支持 TrueType 子集化的简体中文字体名，未命中时再使用集合内首个支持子集化的字体。
  • 字体集合源在 document.save() 完成后再关闭，避免 PDFBox 保存阶段继续读取字体时源文件已关闭。
  • 增加 .otf 字体文件加载支持。
• 修改 ruoyi-admin/src/main/resources/application-dev.yml
  • 增加本地 macOS 字体路径：/System/Library/Fonts/STHeiti Medium.ttc。
• 修改 ruoyi-admin/src/main/resources/application-nas.yml
• 修改 ruoyi-admin/src/main/resources/application-uat.yml
• 修改 ruoyi-admin/src/main/resources/application-pro.yml
  • 增加 Linux 字体路径：/usr/share/fonts/truetype/wqy/wqy-microhei.ttc。
  • 未修改 application.yml，不提供全局默认值。
• 修改 docker/backend/Dockerfile
  • 后端镜像安装 fontconfig 与 fonts-wqy-microhei，确保 NAS Docker 部署环境具备可用中文字体。
• 修改 ccdi-project/src/test/java/com/ruoyi/ccdi/project/service/impl/CcdiProjectOverviewReportPdfExporterTest.java
  • 正常导出用例显式传入测试环境字体路径。
  • 新增空配置与不存在路径的异常覆盖。

影响范围

• 影响结果总览 PDF 导出功能。
• 不改变报告数据组装、表格内容、前端下载接口和文件名规则。
• 不在 application.yml 增加默认配置，缺少 profile 配置时导出时报错。
• Docker 镜像构建会新增中文字体包安装步骤。

验证记录

• 已执行：mvn -pl ccdi-project -Dtest=CcdiProjectOverviewReportPdfExporterTest -Dsurefire.failIfNoSpecifiedTests=false test
  • 结果：失败，失败原因是当前工作区已有其他源码编译错误，未进入 PDF 导出测试。
  • 主要错误包括：getDataTable 调用参数不匹配、流水接口字段和方法签名不匹配。
• 已执行：手工编译 PDF 导出器及其依赖 VO 到 ccdi-project/target/classes 后，运行 mvn -pl ccdi-project -Dtest=CcdiProjectOverviewReportPdfExporterTest -Dsurefire.failIfNoSpecifiedTests=false -Dmaven.main.skip=true test
  • 结果：失败，失败原因是 Maven 仍尝试编译 ccdi-project 下全量测试类，而当前 target/classes 缺少其他测试依赖的业务类。
• 已执行：手工编译 CcdiProjectOverviewReportPdfExporterTest 后，通过 JUnit Platform Launcher 指定运行该测试类
  • 结果：通过，Tests found: 3，Tests succeeded: 3，Tests failed: 0。