refactor(report): 优化报告生成服务的安全性和文档处理

- 添加 FilePathSanitizer 工具类，防止路径穿越和非法字符问题
- 在报告目录路径构建中使用安全的文件名处理
- 为 BookmarkEnum 添加排序字段和注释说明
- 改进书签处理排序逻辑，使用 sort 字段而非依赖枚举声明顺序
- 添加批量处理的语义说明文档
- 优化数据处理流程中的哨兵标记机制
- 为 WordReportService 接口添加详细的资源管理契约文档
- 改进 dealDataLine 方法的职责分离和参数命名
- 修复测试结果详情书签键值引用错误

detection/src/main/java/com/njcn/gather/report/pojo/enums/BookmarkEnum.java

@@ -30,6 +30,7 @@ public enum BookmarkEnum {
 
     private String desc;
 
+    /** 书签处理顺序：1=数据项，2=结果信息，3=目录信息；由 dealDataModelScatteredByBookmark 排序时使用 */
     private Integer sort;
 
     BookmarkEnum(String key, String desc, Integer sort) {

detection/src/main/java/com/njcn/gather/report/service/impl/PqReportServiceImpl.java

@@ -76,6 +76,7 @@ import com.njcn.gather.tools.report.service.IWordReportService;
 import com.njcn.gather.tools.report.util.BookmarkUtil;
 import com.njcn.gather.tools.report.util.Docx4jUtil;
 import com.njcn.gather.tools.report.util.DocxMergeUtil;
+import com.njcn.gather.tools.report.util.FilePathSanitizer;
 import com.njcn.gather.tools.report.util.WordDocumentUtil;
 import com.njcn.gather.type.pojo.po.DevType;
 import com.njcn.gather.type.service.IDevTypeService;
@@ -133,6 +134,17 @@ import java.util.stream.Collectors;
 @RequiredArgsConstructor
 public class PqReportServiceImpl extends ServiceImpl<PqReportMapper, PqReport> implements IPqReportService {
 
+    /**
+     * resultMap 内部协议：当 dealDataLine 跑完一轮但未采集到任何有效合格性数据时，
+     * 在 resultMap 中塞入这个 key 作为"已尝试且无数据"的哨兵，避免后续 TEST_RESULT_*
+     * 分支的 fallback 重复调用 dealDataLine 浪费资源；同时 dealTestResultLine 检测到
+     * 此 key 存在时跳过结论表生成。
+     * <p>
+     * 故意使用明显非业务字符串，避免与任何 PqScriptDtls.scriptCode / PowerIndexEnum
+     * 的真实业务取值撞车。
+     */
+    private static final String RESULT_MAP_NO_DATA_FLAG = "__internal_no_data__";
+
     @Value("${report.template:D:\\template}")
     private String templatePath;
 
@@ -583,6 +595,11 @@ public class PqReportServiceImpl extends ServiceImpl<PqReportMapper, PqReport> i
     /**
      * 根据设备类型生成报告
      * 注：该方法目前仅支持楼下出厂检测场景，属于模板占位符替换方式，后期可能会有调整
+     * <p>
+     * 批量语义：采用"任一设备失败则整批中断"——forEach 循环内任一设备抛 BusinessException
+     * 会终止整个循环，已生成的报告文件保留，中断之后的设备不再处理；失败原因通过异常抛给
+     * 调用方，调用方应提示用户修复问题后重新发起批量。此为有意保留的批量原子语义，
+     * 而非待修复缺陷。
      *
      * @param devReportParam 被检设备信息
      */
@@ -783,6 +800,11 @@ public class PqReportServiceImpl extends ServiceImpl<PqReportMapper, PqReport> i
     /**
      * 需要支持批量生成,如果用户选择批量生成,则默认都采用测试数据的第一个合格,如果
      * 比对模式下生成检测报告,实际后期需要根据用户选择的检测数据或者某次波形数据生成报告
+     * <p>
+     * 批量语义：采用"任一设备失败则整批中断"——forEach 循环内任一设备抛 BusinessException
+     * 会终止整个循环，已生成的报告文件保留，中断之后的设备不再处理；失败原因通过异常抛给
+     * 调用方，调用方应提示用户修复问题后重新发起批量。此为有意保留的批量原子语义，
+     * 而非待修复缺陷。
      *
      * @param plan           计划信息
      * @param devReportParam 设备信息
@@ -821,7 +843,7 @@ public class PqReportServiceImpl extends ServiceImpl<PqReportMapper, PqReport> i
                     MainDocumentPart detailDocumentPart = detailModelDocument.getMainDocumentPart();
                     dealDataModelScatteredByBookmarkByPlanContrast(baseDocumentPart, detailDocumentPart, devReportParam, pqDevVO);
                     // 保存新的文档
-                    String dirPath = reportPath.concat(File.separator).concat(plan.getName());
+                    String dirPath = reportPath.concat(File.separator).concat(FilePathSanitizer.toSafeFileName(plan.getName()));
                     // 确保目录存在
                     ensureDirectoryExists(dirPath);
                     // 构建文件名：cityName_gdName_subName_name.docx
@@ -861,6 +883,11 @@ public class PqReportServiceImpl extends ServiceImpl<PqReportMapper, PqReport> i
     /**
      * 根据计划绑定的报告模板生成报告
      * 注：该方法目前属于同用信息占位符替换，数据页为面向对象动态填充拼凑方式
+     * <p>
+     * 批量语义：采用"任一设备失败则整批中断"——forEach 循环内任一设备抛 BusinessException
+     * 会终止整个循环，已生成的报告文件保留，中断之后的设备不再处理；失败原因通过异常抛给
+     * 调用方，调用方应提示用户修复问题后重新发起批量。此为有意保留的批量原子语义，
+     * 而非待修复缺陷。
      *
      * @param plan           计划信息
      * @param devReportParam 设备信息
@@ -899,7 +926,7 @@ public class PqReportServiceImpl extends ServiceImpl<PqReportMapper, PqReport> i
                 dealDataModelScatteredByBookmark(baseDocumentPart, detailDocumentPart, devReportParam, pqDevVO);
 
                 // 保存新的文档
-                String dirPath = reportPath.concat(File.separator).concat(devType.getName());
+                String dirPath = reportPath.concat(File.separator).concat(FilePathSanitizer.toSafeFileName(devType.getName()));
                 // 确保目录存在
                 ensureDirectoryExists(dirPath);
                 baseModelDocument.save(new File(dirPath.concat(File.separator).concat(pqDevVO.getCreateId()).concat(ReportConstant.DOCX)));
@@ -950,9 +977,9 @@ public class PqReportServiceImpl extends ServiceImpl<PqReportMapper, PqReport> i
              * 1、数据项
              * 2、结果信息
              * 3、目录信息
-             * 所以要先先获取的书签进行操作排序
+             * 按 BookmarkEnum.sort 字段排序，避免依赖枚举常量声明顺序
              * */
-            Collections.sort(bookmarkEnums);
+            bookmarkEnums.sort(Comparator.comparingInt(BookmarkEnum::getSort).thenComparingInt(Enum::ordinal));
             List<Object> todoInsertList;
             BookmarkUtil.BookmarkInfo bookmarkInfo;
             Map<Integer/*回路号*/, List<ContrastTestResult>> resultMap = null;
@@ -1230,9 +1257,9 @@ public class PqReportServiceImpl extends ServiceImpl<PqReportMapper, PqReport> i
              * 1、数据项
              * 2、结果信息
              * 3、目录信息
-             * 所以要先先获取的书签进行操作排序
+             * 按 BookmarkEnum.sort 字段排序，避免依赖枚举常量声明顺序
              * */
-            Collections.sort(bookmarkEnums);
+            bookmarkEnums.sort(Comparator.comparingInt(BookmarkEnum::getSort).thenComparingInt(Enum::ordinal));
             // 定义个结果，以便存在结果信息的书签
             Map<String/*指标名称*/, List<Boolean/*以回路的顺序填充结果*/>> resultMap = new HashMap<>();
             List<Object> todoInsertList;
@@ -1281,7 +1308,7 @@ public class PqReportServiceImpl extends ServiceImpl<PqReportMapper, PqReport> i
                         if (CollUtil.isEmpty(resultMap)) {
                             dealDataLine(baseDocumentPart, devReportParam, pqDevVO, resultMap);
                         }
-                        bookmarkInfo = BookmarkUtil.getBookmarkInfo(BookmarkEnum.TEST_RESULT_LINE.getKey(), bookmarks);
+                        bookmarkInfo = BookmarkUtil.getBookmarkInfo(BookmarkEnum.TEST_RESULT_DETAIL.getKey(), bookmarks);
                         todoInsertList = dealTestResultLine(devReportParam, resultMap, DocAnchorEnum.TEST_RESULT_DETAIL);
                         if (Objects.nonNull(bookmarkInfo) && CollectionUtil.isNotEmpty(todoInsertList)) {
                             BookmarkUtil.insertElement(bookmarkInfo, todoInsertList);
@@ -1306,8 +1333,8 @@ public class PqReportServiceImpl extends ServiceImpl<PqReportMapper, PqReport> i
      */
     private List<Object> dealTestResultLine(DevReportParam devReportParam, Map<String, List<Boolean>> resultMap, DocAnchorEnum docAnchorEnum) {
         List<Object> todoInsertList = new ArrayList<>();
-        // 先判断数据有没有，如果没有，则不处理
-        if (CollUtil.isEmpty(resultMap.get(PowerIndexEnum.UNKNOWN.getKey()))) {
+        // 先判断数据有没有，如果没有，则不处理（哨兵协议详见 RESULT_MAP_NO_DATA_FLAG 注释）
+        if (!resultMap.containsKey(RESULT_MAP_NO_DATA_FLAG)) {
             ObjectFactory factory = Context.getWmlObjectFactory();
             // 源文档的内容
             // 创建表格（示例为3列，列数可任意调整）
@@ -1396,13 +1423,27 @@ public class PqReportServiceImpl extends ServiceImpl<PqReportMapper, PqReport> i
 
 
     /**
-     * 处理以回路为维度的数据项，书签占位符的方式
+     * 以回路维度处理数据项，并填充 resultMap（指标合格性结论）。
+     * <p>
+     * 本方法承担双重职责：
+     * <ol>
+     *   <li><b>返回值</b>：根据 modelPart 中的 H5 分组表格模板，灌入实测数据后生成可插入文档的元素列表；</li>
+     *   <li><b>副作用</b>：把每个指标在各回路上的合格性写入 resultMap，供后续 dealTestResultLine 构造结论表使用。</li>
+     * </ol>
+     * 调用约定（务必区分以下两条路径，避免误解形参用途）：
+     * <ul>
+     *   <li><b>常规路径</b>（DATA_LINE 分支）：modelPart 传 detail 文档（数据页模板池），返回值会被插入 DATA_LINE 书签锚点。</li>
+     *   <li><b>fallback 路径</b>（TEST_RESULT_* 分支且 resultMap 为空时）：modelPart 允许传 base 文档（封面页）；此时模板池为空，返回值无业务意义，调用方应丢弃，仅借此触发 resultMap 计算。</li>
+     * </ul>
+     * 因此 modelPart 命名保持中性，不要改回 detailXxx 等带语义偏向的名字。
      *
-     * @param detailModelDocument 数据项模板
-     * @param devReportParam      测试报告参数
-     * @param pqDevVO             被检设备
+     * @param modelPart      文档模板部分；常规传 detail 文档，fallback 仅需算 resultMap 时可传 base 文档
+     * @param devReportParam 测试报告参数
+     * @param pqDevVO        被检设备
+     * @param resultMap      结果性数据集合（被本方法写入；fallback 路径正是借此计算）
+     * @return 待插入文档的元素列表；fallback 路径下应被调用方丢弃
      */
-    private List<Object> dealDataLine(MainDocumentPart detailModelDocument, DevReportParam devReportParam, PqDevVO pqDevVO, Map<String, List<Boolean>> resultMap) {
+    private List<Object> dealDataLine(MainDocumentPart modelPart, DevReportParam devReportParam, PqDevVO pqDevVO, Map<String, List<Boolean>> resultMap) {
         List<Object> todoInsertList = new ArrayList<>();
         // 以回路维度处理数据项
         Integer devChns = pqDevVO.getDevChns();
@@ -1410,8 +1451,8 @@ public class PqReportServiceImpl extends ServiceImpl<PqReportMapper, PqReport> i
         // 读取该计划的检测大项组装数据内容
         List<PqScriptDtlDataVO> pqScriptDtlsList = pqScriptDtlsService.getScriptDtlsDataList(devReportParam.getScriptId());
         Map<String, List<PqScriptDtlDataVO>> scriptMap = pqScriptDtlsList.stream().collect(Collectors.groupingBy(PqScriptDtlDataVO::getScriptCode, LinkedHashMap::new, Collectors.toList()));
-        List<Object> allContent = detailModelDocument.getContent();
-        List<Docx4jUtil.HeadingContent> headingContents = Docx4jUtil.extractHeading5Contents(allContent, detailModelDocument);
+        List<Object> allContent = modelPart.getContent();
+        List<Docx4jUtil.HeadingContent> headingContents = Docx4jUtil.extractHeading5Contents(allContent, modelPart);
         Map<String, List<Docx4jUtil.HeadingContent>> contentMap = headingContents.stream().collect(Collectors.groupingBy(Docx4jUtil.HeadingContent::getHeadingText, Collectors.toList()));
         for (int i = 0; i < devChns; i++) {
             // 回路标题
@@ -1479,9 +1520,11 @@ public class PqReportServiceImpl extends ServiceImpl<PqReportMapper, PqReport> i
                 }
             }
         }
-        // 如果经过一顿处理后，结果性数据集合还是空，塞个特殊数据进去，避免嵌套循环
+        // 经过一轮处理仍未采集到任何合格性数据时，塞入哨兵：
+        // 一是让后续 TEST_RESULT_* 分支的 fallback 看到 resultMap 非空而跳过重复调用本方法，
+        // 二是供 dealTestResultLine 据此跳过结论表生成（哨兵协议详见 RESULT_MAP_NO_DATA_FLAG 注释）。
         if (CollUtil.isEmpty(resultMap)) {
-            resultMap.put(PowerIndexEnum.UNKNOWN.getKey(), Collections.singletonList(false));
+            resultMap.put(RESULT_MAP_NO_DATA_FLAG, Collections.singletonList(false));
         }
         return todoInsertList;
     }
@@ -1906,16 +1949,16 @@ public class PqReportServiceImpl extends ServiceImpl<PqReportMapper, PqReport> i
                         pqDevVO.getGdName() != null ? pqDevVO.getGdName() : "未知供电公司",
                         pqDevVO.getSubName() != null ? pqDevVO.getSubName() : "未知电站",
                         pqDevVO.getName() != null ? pqDevVO.getName() : "未知设备");
-                filePath = reportPath.concat(File.separator).concat(plan.getName()).concat(File.separator).concat(fileName);
+                filePath = reportPath.concat(File.separator).concat(FilePathSanitizer.toSafeFileName(plan.getName())).concat(File.separator).concat(fileName);
                 downloadFileName = fileName;
             } else {
                 // 数字/模拟模式：使用原来的路径结构
-                filePath = reportPath.concat(File.separator).concat(devType.getName()).concat(File.separator).concat(pqDevVO.getCreateId()).concat(ReportConstant.DOCX);
+                filePath = reportPath.concat(File.separator).concat(FilePathSanitizer.toSafeFileName(devType.getName())).concat(File.separator).concat(pqDevVO.getCreateId()).concat(ReportConstant.DOCX);
                 downloadFileName = pqDevVO.getCreateId() + ReportConstant.DOCX;
             }
         } else {
             // 兜底：使用旧的路径结构
-            filePath = reportPath.concat(File.separator).concat(devType.getName()).concat(File.separator).concat(pqDevVO.getCreateId()).concat(ReportConstant.DOCX);
+            filePath = reportPath.concat(File.separator).concat(FilePathSanitizer.toSafeFileName(devType.getName())).concat(File.separator).concat(pqDevVO.getCreateId()).concat(ReportConstant.DOCX);
             downloadFileName = pqDevVO.getCreateId() + ReportConstant.DOCX;
         }