智能质检报告 — 出件接口 前端联调方案

后端模块：yudao-module-qcreport　接口前缀：/admin-api/qc-report/instance
本轮范围：**HTML 出件 + PDF 出件**。PDF 由后端调 Chromium 打印，接口只返回归档结果与签名地址；
报告实例表**不存文件地址**，PDF 统一挂在附件库（system_storage_attachment）里。

涉及页面

菜单已入库：「报告实例」挂在「质量管理」（parent_id=5500）下，component 填 mes/qc/report/instance/index，前端动态路由解析到同名 .vue。

业务流程与数据带入

1. 设计器 → 预览：设计器把当前画布保存成版本后，用「当前画布对应的模板 + 版本」加一份示例数据调用 preview，
   拿到 HTML 直接展示。**预览不消耗报告编号**，可以反复调用；**预览接受草稿版本**（见「业务规则」）。
2. 业务系统 → 出件：调用方（本轮是手工构造，后续是 MES 质检单）准备「报告上下文」→ 调 generate
   → 后端渲染、落库、冻结数据快照 → 返回实例编号与报告编号。
3. 列表 → 详情：列表拿到 id → 调 get 取 renderHtml 展示；需要看「当时用的什么数据」再调 snapshot。
4. 详情 → 重新生成：调 regenerate 用**冻结的快照**重渲，覆盖产物 HTML。数据与编号都不变。
   已归档的 PDF 会被一并作废（见「业务规则」）。
5. 详情 → 导出 PDF：点「导出 PDF」调 pdf 接口 → 后端打印并归档 → 接口返回本次的下载地址（临时签名）。
   页面要长期显示「这份报告有 PDF」请调**附件列表接口**（见「PDF 归档怎么查」），不要缓存接口返回的签名地址。

带入关系要点

• templateId 是主线，从模板列表带入设计器、再带入出件。
• version 可以不传：不传时后端取**模板当前的版本**（currentVersion）；一定要用某个特定版本才需要显式传。
  设计器预览建议始终显式传版本——见「业务规则」里对 currentVersion 的说明。
• reportNo 可以不传：不传时由后端按 QR + 日期 + 4 位流水 自动生成。
• businessId / businessType 只做留痕与查询过滤，后端不校验、不解析它指向的单据。

API

✅ 前端实例页落地时，qc-report:instance:* 的菜单与按钮权限**已同步补入 system_menu**
（菜单「报告实例」+ 查询/出件/导出PDF/删除四条按钮 + qc-report:template:ai-import 一条）。
未插这些行之前，非超管角色调这些接口会 403；超管由代码直返全部菜单，联调从不受影响。

出件 / 预览请求参数（preview 与 generate 同一套）

context 结构（与设计器里的数据契约同构）

请求示例

{
  "templateId": 5,
  "version": "v1.0",
  "businessId": "OQC20260918001",
  "businessType": "mes_qc_oqc",
  "context": {
    "report": { "reportName": "出货检验报告", "productName": "法兰", "inspector": "张三" },
    "inspectionItems": [
      { "index": 1, "itemName": "外观", "standardValue": "无划痕", "actualValue": "合格" },
      { "index": 2, "itemName": "长度", "standardValue": "10±0.5", "actualValue": 10.2, "upperLimit": 10.5, "lowerLimit": 9.5 }
    ]
  }
}

响应字段

preview 响应

generate 响应

regenerate 响应

pdf 响应

pdf 是**显式触发**的：用户点「导出 PDF」才生成。它不会随 generate / regenerate 自动跑，
因为每导一次都要拉起 Chromium 打印（秒级），出件接口不该背这个开销。

get 响应：id、reportNo、templateId、templateVersion、businessId、businessType、renderHtml、status、creator、createTime、updateTime。
注意不含 dataSnapshot（体积大且列表/详情用不到），要它请调 snapshot。

snapshot 响应：{ "report": {...}, "inspectionItems": [...] }，即出件当时冻结的那份数据（含算好的 PASS/FAIL 与合格率）。

page 请求参数（其余为通用分页参数 pageNo / pageSize）

PDF 归档怎么查（不新增专用查询接口）

报告实例表里**没有也不会有** pdfUrl / pdfPath 这类字段。PDF 统一通过 system 模块的附件库里查，
走的是全项目通用的附件接口（ERP / CRM 页面同款姿势）：

响应是一个数组，每项含 url / previewURL / downloadURL / name / id（附件编号）等。
正常情况数组里最多一条（再次导出会替换掉旧的，不会越导越多）。

前端展示「PDF」按钮的逻辑建议：

1. 进详情页时调一次附件列表接口，有数据 → 显示「下载 PDF」；没有 → 显示「导出 PDF」。
2. 点「导出 PDF」调 pdf 接口，成功后用返回的 downloadURL 直接下载（或重新查一次附件列表刷新状态）。
3. 不要把 downloadURL 存进前端状态长期使用：它是带签名的临时地址，过期后会 401/403。

字段展示规则

业务规则说明

注意事项

• 列表/详情不要展示 dataSnapshot 字段：get 与 page 都不返回它，这是有意的（体积大）。
• get 对已删除的实例返回 data:null，不是报错。所有按 id 取详情的入口都要判空。
• HTML 渲染要注意样式隔离：产物是完整 HTML 文档（自带 @page 与样式），
  直接塞进页面会污染全局样式，建议用 iframe 承载。
• 预览响应里的 reportNo 可能为空，这是正常的（预览不生成编号），不要拿它当出件结果。
• inspectionItems 不能传空数组：没有检验项的「报告」没有意义，后端会直接报错。
• businessId 不会是数字类型：虽然表里是 varchar，但调用方给的可能是工单号、批次号一类的字符串，前端别按 Long 处理。
• errors 可能很长，尤其模板刚做好时。建议折叠展示 + 显示条数。
• 权限：接口权限码是 qc-report:instance:query / :create / :delete / :export。
  已入库到 system_menu（见「API」节下的说明）。create 是**预置**的：本轮页面没有出件入口，
  它是给后续 MesQcReportApi 轮准备的，不是遗漏。
• 「AI 导入」按钮用独立权限码 qc-report:template:ai-import：能改模板不等于能用大模型识别文件
  （每次调用都产生费用），两者必须分开授权，不能合并到模板的编辑权限里。
• 预览必须 sandbox=""（空属性，不是省略该属性）：空值 = 完全禁用脚本、表单与同源，只让 CSS 生效。
  产物 HTML 是渲染结果，不需要也不应该让它执行任何东西。
• 重复导出不堆文件已实测：同一实例连点 3 次，库中始终只有 1 条有效附件
  （前两条附件行与 blob 行均为 deleted=1），磁盘目录里也只留当前这一份 PDF。
• 导出的 PDF 中文依赖服务器的字体：开发机（Windows）自带微软雅黑没问题；
  生产 Linux 服务器若没装 CJK 字体会打成方框。这属于部署前置，前端不需要处理，但**验收时要在目标环境上看一眼中文**。
• pdf 接口的返回地址是签名的临时地址，带过期时间与使用次数限制，
  不要把它写进数据库、也不要放进列表接口缓存，需要时重新查附件列表或重新导出。
• 附件列表里的 name 是 PDF 文件名（QR20260918-0001.pdf），下载时用它命名即可。

错误码