# 报告模板 `pattern` 字段改造设计 ## 背景 当前报告模板管理使用 `pq_report` 表，前端页面位于： - `frontend/src/views/system/template` - `frontend/src/views/plan/planList/components/planPopup.vue` 后端代码位于： - `D:\njcn\test\CN_Gather\detection\src\main\java\com\njcn\gather\report` - `D:\njcn\test\CN_Gather\detection\src\main\java\com\njcn\gather\plan` 数据库结构已新增字段： - `pattern char(32) COLLATE utf8mb4_bin NOT NULL COMMENT '模式id'` 当前系统中的设备、计划、脚本、检测源等业务对象都已按模式隔离，但报告模板仍是全局管理： - 模板列表未按模式过滤 - 模板新增/编辑没有模式归属 - 计划弹窗的报告模板下拉取的是全部模板 - 模板文件目录与模式无关 本次改造的目标是让报告模板纳入现有的模式上下文管理，但保持“模式为隐式上下文”，不增加用户额外操作负担。 ## 目标 - 报告模板列表按当前模式过滤 - 报告模板新增/编辑时自动绑定当前模式 `pattern` - 报告模板前端页面不展示模式列，不展示模式下拉 - 计划弹窗中的报告模板选项只返回当前模式模板 - 删除不再使用的 `getPqReportAllName()` 前后端接口和调用 - 模板落盘目录改为 `patternName/name/version/` - 模板重复校验改为 `pattern + name + version` ## 非目标 - 不增加模式列展示 - 不在新增/编辑弹窗中增加模式下拉 - 不在计划绑定模板时校验 `plan.pattern == report.pattern` - 不在生成报告时校验 `plan.pattern == report.pattern` - 不处理旧模板数据补 `pattern`，由数据库手工修复 - 不调整 `ad_plan.reportTemplateId` 的现有绑定模型 ## 业务约束 ### 模式来源 前端不允许用户手工选择模板模式。页面中的模板模式始终取“当前模式”上下文： - 来源：`modeStore.currentMode` - 映射：`dictStore.getDictData('Pattern')` 中与当前模式名称匹配的数据字典项 - 实际提交值：字典项 `id` ### 目录规则 模板文件存储目录由当前的： - `name/version/` 改为： - `patternName/name/version/` 其中： - `patternName` 取模式字典的 `name` - 数据库存储的 `pattern` 仍然是模式字典 `id` - 目录名在落盘前需要做 Windows 路径安全处理 ### 模板唯一性 模板唯一性由当前的全局： - `name + version` 改为： - `pattern + name + version` 因此： - 同一模式下不允许同名同版本模板 - 不同模式下允许同名同版本模板 ## 数据模型调整 ### 后端实体与参数 以下对象补充 `pattern` 字段： - `PqReport` - `ReportParam` - `ReportParam.UpdateParam` - `ReportParam.QueryParam` - `PqReportVO` 用途如下： - `PqReport.pattern`：数据库持久化 - `ReportParam.pattern`：新增/编辑接收当前模式 id - `ReportParam.QueryParam.pattern`：列表查询条件 - `PqReportVO.pattern`：详情回显与后续兼容 ### 数据库存储 - `pq_report.pattern` 保存模式字典 `id` - 不额外保存 `patternName` - `patternName` 仅在文件目录拼接时通过字典服务即时获取 ## 后端接口设计 ### 1. `POST /report/list` 职责： - 分页查询当前模式下的报告模板 请求参数新增： - `pattern` 处理规则： - 必须传 `pattern` - 按 `pattern + name + version + state=1` 过滤 - 不允许在未传 `pattern` 时返回全量模板 返回： - 保持现有分页结构 - `PqReportVO` 中可包含 `pattern` - 前端列表不展示该字段 ### 2. `GET /report/getById` 职责： - 查询模板详情 处理规则： - 保持现有按 `id` 查询 - 返回结果包含 `pattern` 说明： - 本次不额外增加 `id + pattern` 双重校验 - 模板访问范围由列表入口和当前页面模式上下文收口 ### 3. `POST /report/add` 职责： - 新增报告模板 请求参数新增： - `pattern` 处理规则： - `pattern` 必传 - `pattern` 必须是合法模式字典 id - 重复校验使用 `pattern + name + version` - 文件目录按 `patternName/name/version/` 创建 ### 4. `POST /report/update` 职责： - 修改报告模板 请求参数新增： - `pattern` 处理规则： - 前端仍会传当前模式 id - 后端接收该字段 - 不开放通过页面显式修改模式 - 更新名称或版本时，模板目录迁移到新的 `patternName/name/version/` 说明： - 本次不设计跨模式迁移能力 - 模板模式的变更不作为用户可操作能力暴露 ### 5. 新增模板选项接口 新增接口替代旧的全量模板名接口。 建议接口： - `GET /report/listOptions?pattern={patternId}` 职责： - 返回当前模式下可选报告模板列表，供计划弹窗下拉使用 建议返回结构： - `id` - `name` - `version` - `displayName` 其中： - `displayName = name + '_' + version` 说明： - 由后端拼接 `displayName` - 前端不再自行拼接全量名称列表 ### 6. 移除旧接口 以下接口与服务一并移除： - `GET /report/listAllName` - `IPqReportService.listAllName()` - `PqReportServiceImpl.listAllName()` - 前端 `getPqReportAllName()` ## 后端服务设计 ### 列表查询 `PqReportServiceImpl.list()` 增加： - `pattern` 非空校验 - `wrapper.eq("pattern", queryParam.getPattern())` ### 重复校验 `checkRepeat()` 调整为： - `pattern` - `name` - `version` - `state = ENABLE` ### 模板目录构造 新增统一内部方法，例如： - `buildReportTemplateRelativeDir(String patternId, String name, String version)` 职责： - 查询字典得到 `patternName` - 对 `patternName`、`name`、`version` 做路径安全清洗 - 生成相对目录 `patternName/name/version/` 所有路径相关逻辑统一走该方法： - 新增模板 - 更新模板 - 重命名目录 - 删除目录 ### 文件目录迁移 编辑模板时： - 若 `name` 或 `version` 变化，按新目录规则迁移 - 若未变化，则沿用原目录 - 文件替换逻辑仍保持现有语义 ### 模式字典读取 可直接复用现有字典服务： - `IDictDataService` 用途： - 校验 `pattern` 是否存在 - 读取 `pattern.name` ## 前端页面设计 ### 模板管理列表页 页面： - `frontend/src/views/system/template/index.vue` 调整内容： - 查询列表时自动注入当前模式 `patternId` - 列表不新增模式列 - 列表不新增模式搜索项 - 打开新增弹窗时，将当前模式 id 写入表单状态 ### 模板新增/编辑弹窗 页面： - `frontend/src/views/system/template/components/reportPopup.vue` 调整内容： - 本地表单对象增加 `pattern` - 不展示模式下拉 - 新增时自动写入当前模式 id - 编辑时保留接口返回的 `pattern` 值，但不展示、不允许修改 - 提交 `FormData` 时带上 `pattern` 说明： - 模板模式是隐式上下文，不是表单可见字段 ### 计划弹窗中的报告模板下拉 页面： - `frontend/src/views/plan/planList/components/planPopup.vue` 调整内容： - 不再调用 `getPqReportAllName()` - 改为调用新的按模式模板选项接口 - 查询参数传当前模式 `patternId` - 下拉只展示当前模式模板 - 展示文案使用后端返回的 `displayName` 说明： - 本次不调整计划保存的数据结构 - 只调整模板下拉的取值范围和数据来源 ## 前端 API 调整 文件： - `frontend/src/api/device/report/index.ts` - `frontend/src/api/device/interface/report.ts` 调整内容： - `PqReport.ReqReportParams` 增加 `pattern` - `PqReport.ResReport` 增加 `pattern` - `getPqReportList` 调用参数增加 `pattern` - 删除 `getPqReportAllName` - 新增按模式查询模板选项接口 ## 异常处理 ### 后端 - `/report/list` 未传 `pattern` 时，返回参数错误 - `/report/add`、`/report/update` 中 `pattern` 为空时，返回参数错误 - `pattern` 对应字典不存在时，返回参数错误 - 路径安全清洗后若目录段为空，返回参数错误 - 同模式下模板重名重版本时，返回重复模板错误 ### 前端 - 当前模式找不到对应 `patternId` 时，不发起新增、编辑、列表查询 - 提示当前模式配置异常 ## 风险与处理 ### 风险 1：旧目录与新目录并存 由于目录规则由 `name/version/` 改为 `patternName/name/version/`： - 未编辑过的旧模板文件可能仍在旧目录 - 新增或编辑后的模板会进入新目录 处理： - 本次不做历史文件批量迁移 - 以编辑后的新目录规则为准 ### 风险 2：不同模式同名同版本模板的路径冲突 如果不把模式带入目录，会出现覆盖。 处理： - 目录规则强制引入 `patternName` - 唯一性规则改为 `pattern + name + version` ### 风险 3：计划绑定仍是弱约束 本次明确不校验： - `plan.pattern == report.pattern` 因此若历史数据存在错绑： - 系统不会主动阻止 - 但新的模板选择入口只暴露当前模式模板，后续错绑概率会明显下降 ## 测试范围 ### 后端验证 - 新增模板时成功写入 `pattern` - 列表接口只返回当前模式模板 - 同模式下不允许同名同版本 - 不同模式下允许同名同版本 - 模板目录为 `patternName/name/version/` - 更新名称或版本时目录迁移正确 - 新模板选项接口只返回当前模式模板 - 旧 `listAllName` 接口与实现已彻底移除 ### 前端联调 - 模板管理页在不同模式下看到不同模板列表 - 新增模板时界面不展示模式字段，但提交体中带 `pattern` - 编辑模板时界面不展示模式字段 - 计划弹窗中报告模板下拉只显示当前模式模板 - 前端已无 `getPqReportAllName()` 调用残留 ## 实施范围 前端涉及： - `frontend/src/api/device/interface/report.ts` - `frontend/src/api/device/report/index.ts` - `frontend/src/views/system/template/index.vue` - `frontend/src/views/system/template/components/reportPopup.vue` - `frontend/src/views/plan/planList/components/planPopup.vue` 后端涉及： - `com.njcn.gather.report.pojo.po.PqReport` - `com.njcn.gather.report.pojo.param.ReportParam` - `com.njcn.gather.report.pojo.vo.PqReportVO` - `com.njcn.gather.report.controller.ReportController` - `com.njcn.gather.report.service.IPqReportService` - `com.njcn.gather.report.service.impl.PqReportServiceImpl` - `com.njcn.gather.plan` 中报告模板下拉相关查询逻辑 ## 结论 本方案将报告模板纳入已有模式体系，但保持“模式为页面隐式上下文”： - 用户不需要手工选择模式 - 页面不展示模式字段 - 模板列表、模板新增/编辑、计划模板下拉都以当前模式为边界 - 目录结构与重复规则同时引入模式维度，避免数据和文件冲突 本方案不引入计划与模板的强一致校验，属于低侵入、可平滑上线的模式隔离改造。