# 气密检测接口对接文档

> 接口：`MesProductRecordController.qmcheck` / `MesProductRecordController.qmresult`  
> MES 服务地址：`http://192.168.16.99:8980`  
> 版本依据：mescloud 源码（2026-06）

---

## 1. 基本信息

| 项目 | 说明 |
|------|------|
| 服务 IP | `192.168.16.99` |
| 端口 | `8980` |
| 上下文路径 | `/js` |
| 管理路径 | `/a` |
| 完整 Base URL | `http://192.168.16.99:8980/js/a/mes/mesProductRecord` |
| 请求方式 | `POST` |
| Content-Type | `application/x-www-form-urlencoded`（推荐） |
| 字符编码 | UTF-8 |
| 认证 | 无需登录（Shiro 已配置 `anon`） |

### 1.1 对接时序

```
1. 测试前  → 调用 qmcheck（进站校验，确认能否测试）
2. 测试后  → 调用 qmresult（上传气密过程数据 + 更新工位总结果）
```

---

## 2. 接口一：qmcheck（气密进站校验）

### 2.1 接口地址

```
POST http://192.168.16.99:8980/js/a/mes/mesProductRecord/qmcheck
```

### 2.2 功能说明

- 校验工件是否允许在当前气密工位进行测试

### 2.3 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|:----:|------|
| `__ajax` | String | 建议 | 固定传 `json`，JeeSite 约定，服务端返回 JSON 格式 |
| `sn` | String | **是** | 工件码/产品序列号，MES 中唯一标识该工件 |
| `oprno` | String | **是** | 工位号，如 `OP330`、`OP450`；支持子工位如 `OP450A`，服务端会自动格式化 |
| `lineSn` | String | **是** | 产线编号，如 `XT` |
| `workNum` | String | 否 | 工号/操作员账号，参与 MES 质量校验（开班点检等） |
| `craft` | String | 否 | 工艺号；本接口读取但未参与业务逻辑，可不传 |
| `cxm` | String | 否 | 气密程序名/程序号，仅写入 API 日志，不参与校验 |
| `by` | String | 否 | 保压时间（秒），仅写入 API 日志 |
| `cq` | String | 否 | 充气时间（秒），仅写入 API 日志 |
| `cs` | String | 否 | 测试时间（秒），仅写入 API 日志 |

### 2.4 请求示例

#### 表单 Body（推荐）

```
__ajax=json&sn=501901660045119990G4JB100071&oprno=OP450&lineSn=XT&workNum=system
```

#### 带注释的完整参数示例

```
__ajax=json          # JeeSite 返回 JSON，建议固定带上
&sn=501901660045119990G4JB100071   # 工件码（必填）
&oprno=OP450         # 工位号（必填）
&lineSn=XT           # 产线编号（必填）
```

#### 原始 HTTP 报文

```http
POST /js/a/mes/mesProductRecord/qmcheck HTTP/1.1
Host: 192.168.16.99:8980
Content-Type: application/x-www-form-urlencoded

__ajax=json&sn=501901660045119990G4JB100071&oprno=OP450&lineSn=XT
```

#### cURL

```bash
curl -X POST "http://192.168.16.99:8980/js/a/mes/mesProductRecord/qmcheck" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "__ajax=json" \
  -d "sn=501901660045119990G4JB100071" \
  -d "oprno=OP450" \
  -d "lineSn=XT"
```

### 2.5 响应格式

返回 JSON 对象 `CommonResp`：

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | String | `"true"` 允许继续 / `"false"` 不允许 |
| `message` | String | 中文提示信息 |
| `data` | String | 质量校验状态码（2 位字母） |

### 2.6 响应示例

**允许测试：**

```json
{
  "result": "true",
  "message": "工件可以加工",
  "data": "UD"
}
```

**不允许测试（前置工位未完成）：**

```json
{
  "result": "false",
  "message": "该工件OP180未加工",
  "data": "QD"
}
```

**两次气密间隔不足 15 分钟（需配置 `mes.qm.ng.time=1` 开启）：**

```json
{
  "result": "false",
  "message": "两次气密必须间隔15分钟",
  "data": "UD"
}
```

**参数缺失：**

```json
{
  "result": "false",
  "message": "参数错误1",
  "data": null
}
```

### 2.7 data 状态码说明

> **对接规则：仅当 `result="true"` 且 `data="UD"` 时，设备方可开始气密测试。**

| data | 含义 | message 示例 |
|------|------|----------------|
| `UD` | 可以加工/测试 | 工件可以加工 |
| `OK` | 本工位已加工且 OK | 该工件本工位已加工，结果：OK |
| `NG` | 本工位已加工且 NG | 该工件本工位已加工，结果：NG |
| `NE` | 工件未录入系统 | 该工件未录入系统 |
| `NN` | 跳过该工位 | 该工件跳过该工位 |
| `QD` | 前置工位未加工 | 该工件OPxxx未加工 |
| `QN` | 前置工位 NG | 该工件OPxxx加工NG |
| `NF` | 已合格下线 | 该工件已合格下线 |
| `NR` | 返修中 | 该工件离线返修中 |
| `NB` | 已报废 | 该工件已报废 |
| `ND` | NG 待处理 | 该工件NG待处理 |
| `DJ` | 未开班点检 | 未进行开班点检 |
| `BM` | 未绑定物料 | 未绑定物料 |
| `PL` | 配件寿命不足 | 配件寿命不足 |
| `PZ` | 未拍照 | 请先上传照片 |

---

## 3. 接口二：qmresult（气密结果上传）

### 3.1 接口地址

```
POST http://192.168.16.99:8980/js/a/mes/mesProductRecord/qmresult
```

### 3.2 功能说明

一次请求完成两件事：

1. **保存气密过程数据** → 写入 `mes_product_qm` 表  
2. **更新 MES 工位总结果** → 调用 `updateQualityCommon`，更新 `craft=100000` 对应记录

### 3.3 请求参数

#### 3.3.1 基础参数

| 参数名 | 类型 | 必填 | 说明                                     |
|--------|------|:----:|----------------------------------------|
| `__ajax` | String | 建议 | 固定传 `json`                             |
| `sn` | String | **是** | 工件码/产品序列号                              |
| `oprno` | String | **是** | 工位号，例如 `OP330`、`OP450`                 |
| `lineSn` | String | **是** | 产线编号，固定传`XT`                           |
| `result` | String | **是** | 测试结果，固定大写：`OK`（合格）或 `NG`（不合格）          |
| `craft` | String | **建议** | 工艺号，更新工位总结果时使用；**固定传 `100000`**（工位总结果） |
| `workNum` | String | 建议 | 工号/操作员账号，写入气密记录及工位结果                   |

#### 3.3.2 气密过程参数

| 参数名 | 类型 | 必填 | Base64 | 说明 |
|--------|------|:----:|:------:|------|
| `cxm` | String | 否 | 否 | 气密程序号/程序名 |
| `deviceType` | String | 否 | 否 | 设备类型/设备编号 |
| `remark` | String | 否 | 否 | 备注信息 |
| `testPressure` | String | 否 | **是** | 测试压力值，传 Base64 编码后的字符串 |
| `testPressureUnit` | String | 否 | 否 | 测试压力单位，如 `Pa`、`kPa` |
| `leakVal` | String | 否 | **是** | 泄漏值，传 Base64 编码后的字符串 |
| `leakValUnit` | String | 否 | 否 | 泄漏值单位，如 `Pa` |
| `testTime` | String | 否 | **是** | 测试完成时间，Base64 编码；解码后格式 `yyyy-MM-dd HH:mm:ss` |
| `title` | String | 否 | **是** | 测试标题，Base64 编码 |

#### 3.3.3 Base64 编码对照表

| 原始值                   | Base64 编码值 |
|-----------------------|---------------|
| `200`                 | `MjAw` |
| `5`                   | `NQ==` |
| `2026-06-09 12:12:00` | `MjAyNC0wNS0xNiAxMjoxMjowMA==` |

> 编码步骤：原始字符串 → UTF-8 → Base64 编码 → URL 编码（作为表单参数提交）

### 3.4 请求示例

#### 表单 Body（OK 件，完整参数）

```
__ajax=json&sn=501901660045119990G4JB100071&oprno=OP450&lineSn=XT&workNum=system&craft=100000&result=OK&cxm=PROGRAM_01&testPressure=MjAw&testPressureUnit=Pa&leakVal=NQ==&leakValUnit=Pa&testTime=MjAyNC0wNS0xNiAxMjoxMjowMA==&deviceType=QM001&remark=
```

#### 带注释的完整参数示例

```
__ajax=json          # JeeSite 返回 JSON（建议）
&sn=501901660045119990G4JB100071   # 工件码（必填）
&oprno=OP450         # 工位号（必填）
&lineSn=XT           # 产线编号（必填）
&craft=100000        # 工艺号，工位总结果固定传 100000（强烈建议）
&result=OK           # 测试结果 OK/NG（必填，大写）
&workNum=system      # 操作员工号（建议）
&cxm=PROGRAM_01      # 气密程序号（可选）
&deviceType=QM001    # 设备类型/编号（可选）
&testPressure=MjAw   # 测试压 200，Base64 编码（可选）
&testPressureUnit=Pa # 测试压单位（可选）
&leakVal=NQ==        # 泄漏值 5，Base64 编码（可选）
&leakValUnit=Pa      # 泄漏值单位（可选）
&testTime=MjAyNC0wNS0xNiAxMjoxMjowMA==  # 测试时间，Base64 编码（可选）
&remark=             # 备注（可选）
```

#### NG 件最小请求（仅必填项）

```
__ajax=json&sn=501901660045119990G4JB100071&oprno=OP450&lineSn=XT&craft=100000&result=NG&workNum=system
```

#### 原始 HTTP 报文

```http
POST /js/a/mes/mesProductRecord/qmresult HTTP/1.1
Host: 192.168.16.99:8980
Content-Type: application/x-www-form-urlencoded

__ajax=json&sn=501901660045119990G4JB100071&oprno=OP450&lineSn=XT&workNum=system&craft=100000&result=OK&cxm=PROGRAM_01&testPressure=MjAw&testPressureUnit=Pa&leakVal=NQ==&leakValUnit=Pa&testTime=MjAyNC0wNS0xNiAxMjoxMjowMA==&deviceType=QM001
```

#### cURL

```bash
curl -X POST "http://192.168.16.99:8980/js/a/mes/mesProductRecord/qmresult" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "__ajax=json" \
  --data-urlencode "sn=501901660045119990G4JB100071" \
  --data-urlencode "oprno=OP450" \
  --data-urlencode "lineSn=XT" \
  --data-urlencode "workNum=system" \
  --data-urlencode "craft=100000" \
  --data-urlencode "result=OK" \
  --data-urlencode "cxm=PROGRAM_01" \
  --data-urlencode "testPressure=MjAw" \
  --data-urlencode "testPressureUnit=Pa" \
  --data-urlencode "leakVal=NQ==" \
  --data-urlencode "leakValUnit=Pa" \
  --data-urlencode "testTime=MjAyNC0wNS0xNiAxMjoxMjowMA==" \
  --data-urlencode "deviceType=QM001"
```



### 3.5 响应格式

返回 JeeSite 标准 JSON 字符串：

| 字段 | 类型 | 说明 |
|------|------|------|
| `result` | String | `"true"` 成功 / `"false"` 失败 |
| `message` | String | 中文提示信息 |

### 3.6 响应示例

**成功：**

```json
{
  "result": "true",
  "message": "操作成功！"
}
```

**参数错误：**

```json
{
  "result": "false",
  "message": "参数错误1！"
}
```

**工位未配置：**

```json
{
  "result": "false",
  "message": "子工位未配置！"
}
```

**工位结果更新失败（防呆拦截）：**

```json
{
  "result": "false",
  "message": "该工件本工位已加工，结果：OK"
}
```

---

## 4. 两个接口对比

| 对比项 | qmcheck | qmresult |
|--------|---------|----------|
| 用途 | 测试前进站校验 | 测试后上传结果 |
| 是否写气密明细表 | 否 | 是（`mes_product_qm`） |
| 是否更新工位总结果 | 否 | 是（`craft=100000`） |
| 响应结构 | `result` + `message` + `data` | `result` + `message` |
| 必填参数 | sn, oprno, lineSn | sn, oprno, lineSn, result |
| 操作员字段 | `workNum` | `workNum` |
| 特殊校验 | 15 分钟间隔（可配置） | 样件判定、防呆、多次气密 |

---

## 5. 与 pccheck / pcresult 字段差异

| 接口 | 操作员字段 | craft 默认值 | 说明 |
|------|-----------|-------------|------|
| pccheck / pcresult | `ucode` | pcresult 服务端默认 `100000` | 通用工位校验/结果 |
| qmcheck / qmresult | `workNum` | qmresult **需客户端传** `craft=100000` | 气密专用接口 |

---

## 6. 对接注意事项

1. **先 check 后 result**：测试前必须 qmcheck 通过，再调用 qmresult，否则工位结果可能更新失败。  
2. **craft 固定传 `100000`**：与 MES 工位总结果工艺号一致，不传可能导致工位结果无法正确更新。  
3. **result 大小写**：固定大写 `OK` / `NG`。  
4. **Base64 字段**：`testPressure`、`leakVal`、`testTime`、`title` 需 Base64 编码后再 URL 编码提交。  
5. **testTime 格式**：解码后必须为 `yyyy-MM-dd HH:mm:ss`，解析失败则入库为 null。  
6. **15 分钟间隔**：由配置项 `mes.qm.ng.time=1` 控制，未开启时不校验。  
7. **URL 编码**：工件码含 `-`、空格等特殊字符时必须 URL 编码。  
8. **失败重试**：qmresult 失败时根据 `message` 判断原因，不建议盲目重试（可能重复写入气密明细）。

---

## 7. 联调检查清单

- [ ] qmcheck：正常工件返回 `result=true, data=UD`
- [ ] qmcheck：已加工工件返回 `result=false` 及对应 message
- [ ] qmcheck：15 分钟内重复测试被拦截（如已开启配置）
- [ ] qmresult：OK 件上传成功，MES 可查气密明细 + 工位总结果 OK
- [ ] qmresult：NG 件上传成功，工位总结果 NG
- [ ] qmresult：缺少 sn/oprno/lineSn/result 返回参数错误
- [ ] Base64 字段解码后数值、时间正确
- [ ] 无登录/token 可正常访问

---

## 8. 参考源码

| 内容 | 路径 |
|------|------|
| 接口实现 | `src/main/java/com/jeesite/modules/mes/web/MesProductRecordController.java` |
| 请求 DTO | `src/main/java/com/jeesite/modules/mes/req/MesProductQmReq.java` |
| 响应对象 | `src/main/java/com/jeesite/modules/mes/resp/CommonResp.java` |
| 错误码文案 | `src/main/java/com/jeesite/modules/mes/utils/ErrorMsg.java` |
| 匿名访问配置 | `src/main/resources/config/application.yml` |
| 本地测试示例 | `api.http`（约 318~349 行） |