# 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` 便于定位问题；保留请求与响应作为追踪依据