SpiAoi_API.md的接口文档说明

tjx

2025-10-13 1a92948effc5d28692c847e40d820284e6b1701c

SpiAoi_API.md的接口文档说明

 MESApplication/Docs/SpiAoi_API.md

¶Ô±ÈÐÂÎļþ
@@ -0,0 +1,167 @@
# SPI/AOI æŽ¥å£æ–‡æ¡£

## åŸºæœ¬ä¿¡æ¯
- åŸºç¡€è·¯å¾„：`/api/SpiAoi`（示例完整地址：`http://192.168.1.251:10054/api/SpiAoi`）
- è¯·æ±‚与响应格式：`application/json; charset=utf-8`

## ç»Ÿä¸€è¿”回模型（ResponseResult）
- `status`：整数，0=成功，1=失败
- `message`：字符串，结果说明或错误原因
- `data`：对象，业务数据载体
- `TotalCount`：整数，仅分页接口返回，总记录数

## æ•°æ®æ¨¡åž‹ä¸Žçº¦æŸï¼ˆé€å­—段注释）
以下字段说明参考了 SPIAOI.txt ä¸­çš„数据库定义与注释，调用方请严格按约束提供数据。

### Header（主表摘要，上传时必填）
- `testDate`：字符串，必填。测试日期，格式为 `yyyy-MM-dd`，与设备上传日期保持一致。
- `testTime`：字符串，必填。测试时间，格式为 `HH:mm:ss`，与设备上传时间保持一致。
- `testResult`：字符串，必填，长度≤12。测试结果原始字符串，例如 `0:0:1;0`（通过）、`0;0;0:1`（失败）、`Fail`（异常）。不做解析，原样入库。
- `surface`：字符串，必填。检测面，取值 `T` è¡¨ç¤ºé¡¶é¢ï¼ˆTop），`B` è¡¨ç¤ºåº•é¢ï¼ˆBottom）。
- `totalPoints`：整数，可空，≥0。计划检测点数。
- `actualDefects`：整数，可空，≥0。实际不良点数（统计结果）。
- `equipmentModel`：字符串，可空。设备型号（如 SPI/AOI æœºå°åž‹å·ï¼‰ã€‚
- `workOrder`：字符串，可空。生产工单或批次号。
- `productModel`：字符串，可空。机种/产品型号。
- `boardBarcode`：字符串，必填，长度≤128。板件条码，全局唯一；重复将被拒绝。
- `smtGroup`：字符串，可空。SMT ç»„别。
- `lineName`：字符串，可空。线别名称。

返回专用（查询接口会返回以下字段）：
- `id`：数值，数据库主键 ID，由序列生成。
- `createdAt`：字符串，创建时间 
- `updatedAt`：字符串，更新时间 

### Detail（子表缺陷与产线指标，上传时至少 1 æ¡ï¼‰
设备与产线：
- `machineName`：字符串，可空。检测机台名称。
- `lineDisplayName`：字符串，可空。产线显示名称。

缺陷计数（均为整数，必须 â‰¥0）：
- `offsetCount`：偏位数量（器件贴装偏移）。
- `missingCount`：缺件数量（器件缺失）。
- `reverseCount`：反向数量（器件极性/方向反装）。
- `liftedCount`：翘起数量（器件一端或整体翘起）。
- `floatHighCount`：浮高数量（器件高度超差）。
- `tombstoneCount`：立碑数量（片式器件一端竖起）。
- `flipCount`：翻转数量（器件翻面/翻身）。
- `wrongPartCount`：错件数量（型号/规格错误）。
- `leadLiftCount`：翘脚数量（引脚未贴伏）。
- `coldJointCount`：虚焊数量（冷焊/假焊）。
- `noSolderCount`：空焊数量（焊料缺失）。
- `insufficientSolderCount`：少锡数量（焊料不足）。
- `excessSolderCount`：多锡数量（焊料过量）。
- `bridgeCount`：连锡数量（焊锡桥连）。
- `copperExposureCount`：漏铜数量（焊盘/线路铜箔外露）。
- `spikeCount`：拉尖数量（锡料拉尖）。
- `foreignMatterCount`：异物数量（污染/颗粒）。
- `glueOverflowCount`：溢胶数量（胶水外溢）。
- `pinOffsetCount`：引脚偏位数量（引脚未对中）。

产线统计（除比率外为整数，必须 â‰¥0）：
- `inputBoards`：投入板数（进入检测的板数量）。
- `okBoards`：OK æ¿æ•°ï¼ˆæ£€æµ‹ä¸º OK çš„板数量）。
- `passBoards`：通过板数（最终判定通过的板数量）。
- `passRate`：小数，单位百分比。合格率，例如 `98.00` è¡¨ç¤º 98%。
- `defectBoards`：不良板数（最终判定不良的板数量）。
- `defectRate`：小数，单位百分比。不良率。
- `defectPpm`：整数，单位 PPM。不良数（百万分率）。
- `defectPoints`：不良点数（缺陷点合计）。
- `measuredPoints`：实测点数（实际完成检测的点数）。
- `pendingPoints`：待测点数（未完成检测的点数）。

业务校验提示（提示不阻断）：
- `passBoards` ä¸åº”大于 `inputBoards`。
- å»ºè®® `defectBoards = inputBoards - passBoards`，偏差仅提示。
- å½“ `inputBoards > 0` ä¸”提供 `passRate` æ—¶ï¼Œå»ºè®®ä¸Žè®¡ç®—值 `passBoards/inputBoards*100` åå·® â‰¤ 1.0。

系统记录：每次调用会在消息中心记录一条流水（记录目标表名为 `MES_SPI_AOI_HEADER`、接口 URL、方法、请求与处理结果），用于审计追踪。

---

## æŽ¥å£åˆ—表

### 1. ä¸Šä¼  SPI/AOI æ•°æ®
- è·¯å¾„与方法：`POST /api/SpiAoi/Upload`
- ç”¨é€”：新增一笔主表与多笔子表数据；若 `boardBarcode` å·²å­˜åœ¨åˆ™å¤±è´¥
- è¯·æ±‚示例：
```json
{
  "header": {
    "testDate": "2025-10-10",
    "testTime": "14:33:21",
    "testResult": "0;0;0:1",
    "surface": "T",
    "totalPoints": 500,
    "actualDefects": 3,
    "equipmentModel": "SPI-9000",
    "workOrder": "WO20251010-01",
    "productModel": "MODEL-ABC",
    "boardBarcode": "BC123456789",
    "smtGroup": "A1",
    "lineName": "SMT-01"
  },
  "details": [
    {
      "machineName": "AOI-01",
      "lineDisplayName": "SMT-01",
      "offsetCount": 1,
      "missingCount": 0,
      "reverseCount": 0,
      "liftedCount": 0,
      "floatHighCount": 0,
      "tombstoneCount": 0,
      "flipCount": 0,
      "wrongPartCount": 0,
      "leadLiftCount": 0,
      "coldJointCount": 0,
      "noSolderCount": 0,
      "insufficientSolderCount": 1,
      "excessSolderCount": 0,
      "bridgeCount": 1,
      "copperExposureCount": 0,
      "spikeCount": 0,
      "foreignMatterCount": 0,
      "glueOverflowCount": 0,
      "pinOffsetCount": 0,
      "inputBoards": 100,
      "okBoards": 98,
      "passBoards": 98,
      "passRate": 98.00,
      "defectBoards": 2,
      "defectRate": 2.00,
      "defectPpm": 20000,
      "defectPoints": 3,
      "measuredPoints": 500,
      "pendingPoints": 0
    }
  ]
}
```
- æˆåŠŸå“åº”示例：
```json
{
  "status": 0,
  "message": "OK",
  "data": {
    "headerId": 12001,
    "detailCount": 1,
    "message": "SPI/AOI检测数据上传成功"
  },
  "TotalCount": 0
}
```
- å¤±è´¥å“åº”示例（条码重复）：
```json
{
  "status": 1,
  "message": "上传SPI/AOI检测数据失败: æ¡ç  BC123456789 å·²å­˜åœ¨ï¼Œä¸å…è®¸é‡å¤ä¸Šä¼ ",
  "data": "上传SPI/AOI检测数据失败: æ¡ç  BC123456789 å·²å­˜åœ¨ï¼Œä¸å…è®¸é‡å¤ä¸Šä¼ ",
  "TotalCount": 0
}
```
 

## è°ƒç”¨å»ºè®®
- ä¸¥æ ¼æŒ‰å­—段约束组织数据；数值字段使用整数或小数的正确类型
- å‘生错误时读取 `message` ä¾¿äºŽå®šä½é—®é¢˜ï¼›ä¿ç•™è¯·æ±‚与响应作为追踪依据