质检单 → 质检报告 出件 前端联调方案

后端模块：yudao-module-qcreport　接口前缀：/admin-api/qc-report/instance
上游数据源：yudao-module-mes（MesQcReportApi，本模块不直接读 MES 表）
本轮范围：**由 MES 质检单（IQC/IPQC/OQC/RQC）直接出报告**。前端只需选「哪张单据 + 用哪张模板」，
数据全部由后端从 MES 取，**前端不再自己拼 context**。

涉及页面

与 qc_report_instance_frontend_integration.md 的分工：那份讲的是「调用方自己准备数据」的通用出件；
本份讲的是「数据从 MES 取」的专用入口。两者最终都落到同一个实例表、同一个列表页。

业务流程与数据带入

1. 质检单 → 出报告：用户在质检单**列表行操作**里点「出报告」→ 前端弹窗列出可选模板
   （**只列出 reportType 与该单据类型一致的模板**）→ 调 generate-from-qc。
2. 后端六道校验（按业务优先级，只报第一处，不一次抛多条）：
   类型合法 → 单据存在 → 已完成检验 → 已填判定 → 模板类型匹配 → 有可用检验项。
3. 后端取数并出件：MesQcReportApi 装配质检单四层结构（单头 / 判定依据 / 样品 / 实测值）
   → 归一成报告上下文 → 走**既有的** generate 流程（版本发布校验、编号生成、快照冻结、判定引擎全部照旧）。
4. 结果回到前端：弹窗内就地展示结果（reportNo / itemCount / undecidableCount / warnings / errors），
   底部「查看报告列表」跳转报告实例列表页并带上筛选条件。
5. 反查：报告实例列表页用 businessType=mes_qc_iqc + businessId=1 即可查出该单据出过的所有报告。

带入关系要点

• qcType + qcId 是主线，从质检单列表行带入。qcType 用字典 mes_qc_type 的**数值**（1/2/3/4）。
• templateId 由用户在弹窗里选。**前端必须先按 reportType 过滤模板列表**，否则用户会选到后端必然拒绝的组合。
• version 不传时后端取模板的 currentVersion（要求已发布）。设计器刚存了草稿想立刻出件才需要显式传。
• reportNo 不传由后端自动生成（QR + 日期 + 4 位流水）。
• 列表 → 报告实例的反查筛选是路由 query 带入：跳转时带 businessType（表名，如 mes_qc_oqc）
  与 businessId（质检单主键的字符串形式）两个参数，报告实例列表页在挂载时把它们预填进搜索表单，
  用户落地即看到刚出的报告，不需要自己再筛一遍。

UI 入口（已落地）

弹窗标题不带类型中文名（仍保持这个做法）：mes_qc_rqc 这一路曾有措辞分歧——
后端枚举、表注释、菜单权限子项都写作「退货检验」，只有菜单父项与 mes_qc_type 字典写作「退料检验」。
现已统一为**「退货检验」**（理由：RQC 的对象同时覆盖生产退料、销售退货、售后退货，
「退货检验」是能覆盖三者的说法；且它本就是多数派）。标题仍不带类型名，少一处需要跟着变的文案。

API

qc-report:instance:generate 是**独立权限码**，与 :create、:query 都不通用。

GET /qc-report/template/selectable 请求参数：

响应： Template[]（**数组，不是分页结构**），字段与模板分页接口一致。

为什么单开这个接口，而不是在前端过滤模板分页结果：
两条过滤条件都落在**版本表**上，分页接口返回的 currentVersion 只是模板表上的一个字符串，看不到版本状态与画布内容。

1. 版本未发布：停用一个版本**不会**清空模板的 currentVersion，于是会出现「currentVersion 有值、但那个版本已停用」的模板；这种模板选中后出件必然失败（1_070_101_003）。
2. 画布没有可渲染内容：GrapesJS 把「打开过设计器但一个组件都没放」的项目存成 {"assets":[],"styles":[]}——它非空，所以旧判据会放它过去，渲染时又取不到根组件、body 渲染成空串，**不报错**，用户最终拿到一张白纸 PDF。

两条都是「看起来能选、选了必出问题」，判断它们要读版本行，放在后端做才是单点；
前端拿着分页结果自己推导会得到「看起来对但会漏」的结论。

已补入 system_menu：id=1075416，名称「报告实例质检单出件」，类型 3（按钮），
挂在「报告实例」（parent_id=1075410）下，sort=5。非超管角色需授予该菜单后才可见按钮 / 可调用接口
（超管由代码直返全部菜单，不受影响）。

请求参数

请求示例

{
  "qcType": 1,
  "qcId": 1,
  "templateId": 1,
  "version": "v1.1"
}

响应字段

响应示例

{
  "code": 0,
  "data": {
    "id": 38,
    "reportNo": "QR20260919-0001",
    "templateVersion": "v1.1",
    "itemCount": 14,
    "undecidableCount": 5,
    "warnings": [
      "以下 2 个分组项在本单的检验明细里没有自己的行（多半是检验模板只选了子项），报告里为它们各补了一行来显示组名与公式：「水分、酸含量」",
      "以下 1 个指标是指标库里的分组项，但本单没有属于它们的子项，报告里按独立检验项列出、组名不合并：「色度」"
    ],
    "errors": []
  }
}

报告上下文新增字段（设计器可绑定）

出件时后端写进报告的每个检验项上，新增了下面 4 个字段。它们不在这条接口的响应里，而是体现在**报告上下文**中，
供模板在设计器里绑定（「分组检验项表」组件已内置这些绑定，一般不需要手工配）：

没有分组的报告不会带 group：整个报告一个分组都没有时，item.group 这个键不出现，模板里也就不会多出一层空格子。
一旦报告里有分组，则**每一项都会带 group**（独立项给空串与 1）—— 字段缺席会让合并属性被跳过，反而把该隐藏的格子露出来。

两个字段必须成对使用：item.group.span 与 item.group.hidden 只作用在「检验项目」这一列上。
不要把它们绑到别的列（如「检测要求」）：组内子项各自的检测要求要逐行显示，并进组头格会把它们翻掉。

字段展示规则

业务规则说明

注意事项

• engine/context.ts 的 qcResult / qcResultText 已补齐（类型接口 + emptyReport() 空串默认值），
  设计器的绑定面板里现在可以选到这两个字段，画布上也能绑。若要用它们，模板需自行绑到某个文本组件上。
• 模板列表要按 reportType 过滤：模板的 report_type 存的是字典数值字符串（"1"/"2"/"3"/"4"），
  与 qcType 直接相等比较即可，不要拿 "IQC" 这类英文名去比。
• qcType 传数值不传字符串名：后端按 1~4 识别，传 "IQC" 会得到 1_070_105_000。
• 不要缓存 warnings：它只在本次响应里出现，**不落库**。事后回看历史报告时看不到当时有哪些提示。
  需要留痕请在出件成功时自己记一份。
• warnings 与 errors 分工：warnings 是「数据取舍的软提示」（跳过、截断、缺值），
  errors 是「模板绑定了但没数据的字段」这类渲染期缺口。**两者都要展示**，不要只显示其中一个。
• itemCount 不等于质检单的行数：指标被删会被跳过、一个指标多条实测值会展开成多条、
  组头在本单没有行时后端会补一行，所以这个数**只能用来展示**，不要拿它去和质检单行数做断言。
• 部分字段刻意不带过去：MES 侧检验项上的「检验方法」（checkMethod）与「检验工具」（tool）
  在报告上下文里**没有承载位**，本轮未传递。若报告要展示这两列，需要先扩 InspectionItem 契约
  （那是改动前端可见的数据契约，需单独确认后再做）。
• 质检单上没有「部门」：报告的 department 字段恒为空，不要拿别的字段硬凑。
• 批次号取哪个字段按类型不同：来料检验取供应商批号，出货/退货取批次号，过程检验两者都没有（只有工单号）。这是后端按业务语义定的，前端不用管。
• 报告实例落库时 businessType 是表名（mes_qc_iqc / mes_qc_ipqc / mes_qc_oqc / mes_qc_rqc），
  与前端路由/字典里的英文枚举同名但与字典数值不同，反查时**直接用这四个字符串**。
• 失败时不要重试出件：五道校验失败都是「数据或选择不对」，重试同样会失败。按报文提示去改数据或换模板。
• 失败报文由请求拦截器自动弹出，业务代码不要再弹一次：code != 0 时拦截器已把后端 message
  显示成 toast，调用处只写 catch {} 即可，重复提示会让用户看到两条一样的报错。
• 权限：本接口权限码 qc-report:instance:generate，已补入 system_menu（id=1075416）。

错误码

本接口新增（1_070_105_xxx）

复用既有错误码（本接口不另造副本）

与原始方案文档的偏离（已落地口径）：方案文档 §7 里列的 105_004（模板不存在）与 105_007（模板无已发布版本）
未实现，改为复用上面的既有码。理由：那几条文案本来就是精确的，再造一遍只会多两条会漂移的副本。