编辑 | blame | 历史 | 原始文档

MES 出货检验单（OQC）新增/编辑字段放开必填 - 前端联调方案

状态：后端与前端均已按本文实施。改动点：
MesQcOqcSaveReqVO（去校验）、MesQcOqcRespVO（Swagger 标记）、MesQcOqcMapper（客户为空时的可见性）、
src/views/mes/qc/oqc/data.ts（去 rules）。前端只改了 form schema 的 rules，未动列表/详情展示。
后端需**重启**后生效。

变更摘要

OQC 新增/编辑表单中，以下 4 个字段由必填改为非必填：

字段	后端属性	调整前	调整后
客户	`clientId`	必填 `@NotNull`	非必填
发货数量（本次出货数量）	`outQuantity`	必填 `@NotNull`	非必填（填值仍需 ≥ 0）
检测数量（本次检测数量）	`checkQuantity`	必填 `@NotNull`	非必填（填值仍需 ≥ 0）
出货日期	`outDate`	必填 `@NotNull`	非必填

其余字段保持不变，仍为必填：检验单编号、检验单名称、产品物料、合格品数量、不合格品数量、检测日期、检测人员。

相关历史文档：docs/mes_oqc_check_result_frontend.md 曾计划放开「发货数量 / 出货日期」两项，但本仓库前端
（src/views/mes/qc/oqc/data.ts）目前仍是 rules: 'required'，即该两项也未实际放开。本次一并处理。

涉及页面

MES 出货检验单（OQC）列表页 - 新增/编辑弹窗
MES 出货检验单（OQC）列表页 - 列表列、查询条件
MES 出货检验单（OQC）详情页
待检任务页（views/mes/qc/pendinginspect）-「出货检验」按钮跳转的创建弹窗（预填模式）

API

方法	路径	说明
POST	/mes/qc/oqc/create	新增出货检验单
PUT	/mes/qc/oqc/update	修改出货检验单
GET	/mes/qc/oqc/get	查询出货检验单详情
GET	/mes/qc/oqc/page	分页查询出货检验单
GET	/mes/qc/oqc/export-excel	导出出货检验单

请求参数变更（create / update 共用 MesQcOqcSaveReqVO）：

参数	类型	必填	说明
clientId	Long	否	客户 ID，可空、可省略
outQuantity	BigDecimal	否	本次出货数量，可空；填值需 ≥ 0
checkQuantity	BigDecimal	否	本次检测数量，可空；填值需 ≥ 0
outDate	LocalDateTime	否	出货日期，可空

响应字段变更（MesQcOqcRespVO）： 无新增字段，仅 clientId / outQuantity 的 Swagger requiredMode 由 REQUIRED 改为可空。
clientNickname、unitName 等关联字段在对应 ID 为空时不再返回（保持 null），前端需容忍空值。

请求示例（最小可提交体）：

{
  "code": "OQC20260922001",
  "name": "物料A出货检验",
  "itemId": 20,
  "qualifiedQuantity": 10,
  "unqualifiedQuantity": 0,
  "inspectDate": "2026-09-22 10:00:00",
  "inspectorUserId": 1
}

响应： { "code": 0, "data": 123 }（data 为新建单据 ID）

字段展示规则

字段	展示位置	说明
客户	表单、列表、详情、查询条件	非必填；数据库值可为空，前端空值展示 `-`
发货数量	表单、列表、详情	非必填；空值展示 `-`，不可展示为 `0`
检测数量	表单、列表、详情	非必填；空值展示 `-`，不可展示为 `0`
出货日期	表单、列表、详情	非必填；空值展示 `-`

业务规则说明

场景	规则
提交校验	上述 4 个字段为空或省略，后端不再报「XX不能为空」
数量下限	仍保留：填了值就必须 ≥ 0，否则报「XX不能小于 0」
数量一致性（既有规则不变）	检测数量、合格品数量、不合格品数量三者都填了时，必须满足「检测数量 = 合格品数量 + 不合格品数量」，否则报「检测数量必须等于合格品数量与不合格品数量之和」；检测数量为空时不做该校验
完成检验单	与本次变更无关，仍要求：检测结果必填 + 至少一条检测结果记录
缺陷率计算	检测数量为空时，致命/严重/轻微缺陷率按 0 处理（后端已处理）
导出 Excel	空的客户/数量/日期列导出为空白单元格
AI 报告 / 质检报告	客户为空时报告不输出「客户名称」；出货数量为空时不输出该项，不报错

注意事项

前端必填校验已放开：src/views/mes/qc/oqc/data.ts 中 useFormSchema 里这 4 个字段的 rules 已移除
（clientId 原 'selectRequired'；outQuantity / checkQuantity / outDate 原 'required'）。
其余字段 rules 未动。
列表/详情空值展示：本次未改列表/详情模板，空值按 VXE 默认渲染为**空白**（不是 -），
注意不要为了好看改成 ?? 0，会把「未填」显示成 0，与业务含义不符。
发货数量与检测数量联动逻辑：现有表单有「新建态下，填发货数量自动带出检测数量，反之亦然」的 onChange 逻辑，
判断依赖 values.checkQuantity === null。本次未改该逻辑，行为保持原样（仅用户主动输入时触发，清空后不会被自动填回）。
若后续发现 antd InputNumber 回填 undefined 导致联动失效或互相覆盖，再按需调整。
待检任务预填：pendinginspect 页通过 prefill 带入 clientId / outQuantity，form.vue 里会用
data.prefill.checkQuantity ?? data.prefill.outQuantity 补齐检测数量。放开必填后这个「补齐」仍可保留（业务上合理），
但要确认用户清空后不会被再次自动填回。
客户为空时列表可见性（已处理）：
OQC 列表查询带客户权限过滤——MesQcOqcServiceImpl.getOqcPage 取 customerApi.getPermittedCustomerIds()，
非空时拼 client_id IN (...)。放开客户必填后，客户为空的单据原本会连**建单人自己**都看不到（受限用户），
已在 MesQcOqcMapper.selectPage(reqVO, permittedClientIds) 中改为：

有权限客户列表：client_id IS NULL OR client_id IN (...)
没有任何有权限客户（列表为空）：只查 client_id IS NULL

即「无客户的单据不属于任何客户，不受客户权限遮挡，对所有人生效」。超管等 getPermittedCustomerIds() 返回 null
的用户本来就不做过滤，不受影响。

历史数据：现有 OQC 单据的这 4 个字段都有值，无需数据迁移。