# SPI 接口文档

## 基本信息
- 基础路径：`/api/SpiAoi`（示例完整地址：`http://192.168.1.251:10054/api/SpiAoi`）
- 请求与响应格式：`application/json; charset=utf-8`

## 统一返回模型（ResponseResult）
- `status`：整数，`0` 表示成功，`1` 表示失败
- `message`：字符串，返回说明或错误信息
- `data`：对象，业务数据载体
- `TotalCount`：整数，仅分页接口使用，表示总记录数

 
### Spi数据说明
- 设备 / 产线：`machineName`、`lineDisplayName`
- 缺陷统计（int）：`offsetCount`、`missingCount`、`reverseCount`、`liftedCount`、`floatHighCount`、`tombstoneCount`、`flipCount`、`wrongPartCount`、`leadLiftCount`、`coldJointCount`、`noSolderCount`、`insufficientSolderCount`、`excessSolderCount`、`bridgeCount`、`copperExposureCount`、`spikeCount`、`foreignMatterCount`、`glueOverflowCount`、`pinOffsetCount`
- 生产统计：`inputBoards`、`okBoards`、`passBoards`、`defectBoards`、`defectPoints`、`measuredPoints`、`pendingPoints`
- 比例字段（decimal?）：`passRate`、`defectRate`
- 其它：`defectPpm` *(int?)*、`headerId` *(decimal?)*
 
日志记录：每次调用会写入消息中心（`MES_SPI_AOI_HEADER` / `MES_SPI_AOI_DETAIL`），保存请求体、结果等信息备用。

---

## 接口列表

以下两个接口覆盖单笔与批量入库场景，均使用 POST。
 
### 1. UploadSpiDetails — 上传 SPI明细（单笔）
- 路径：`POST /api/SpiAoi/UploadSpiDetails`
- 描述：插入一条明细记录，需指定 `headerId`（或由数据库触发器自动维护）。
- 请求示例
  ```json
  {
    "headerId": 12001,
    "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": {
      "detailCount": 1,
      "message": "SPI detail upload succeeded"
    },
    "TotalCount": 0
  }
  ```

### 2. UploadSpiDetailsBatch — 批量上传 SPI明细
- 路径：`POST /api/SpiAoi/UploadSpiDetailsBatch`
- 描述：批量写入多条明细，使用同一数据库事务保证原子性。
- 请求示例
  ```json
  [
    {
      "headerId": 12001,
      "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": {
      "detailCount": 5,
      "message": "SPI detail batch upload succeeded"
    },
    "TotalCount": 0
  }
  ```

## 调用建议
- 严格按照字段类型与长度构造数据；数值类字段建议使用整型或保留合适小数位。
- 出现错误时先查看 `message`，再结合消息中心记录和服务端日志定位问题。
- 建议在批量调用前自行去重条码或关键字段，减少回滚概率。