Inbound20260114/入库秤设备端接口文档.md

# 入库秤设备端接口文档

**Base URL**：`http://192.168.10.101:24801/nutrition/neglect/inbound`
**鉴权**：无需 Sa-Token（Nacos 白名单 `/nutrition/neglect/**`）

| Header 字段 | 说明 | 示例值 |
|---|---|---|
| `authorization` | 固定鉴权值 | `57ee87183f2a4fa59683ec9ef41c8f5d` |
**Content-Type**：`application/json`

---

## 通用响应结构

```json
{
  "code": 200,
  "msg": "success",
  "data": { ... }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| code | int | 200 成功，其他为业务错误码 |
| msg | string | 提示信息 |
| data | any | 响应数据，无数据时为 `null` |

---

## 接口列表

### 1. 按溯源码查食材

**GET** `/nutrition/neglect/inbound/ingredient-by-trace`

按溯源码反查命中的食材列表，返回食材 id、名称、净菜类型，用于毛菜/净菜入库时联动选择食材。

**Query 参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| traceCode | string | ✅ | 溯源码 |

**响应示例**

```json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "traceCode": "TC20240501001",
      "materId": 1001,
      "materName": "西红柿",
      "vegTypes": "切丁,切片"
    }
  ]
}
```

**响应字段说明**

| 字段 | 类型 | 说明 |
|------|------|------|
| traceCode | string | 溯源码 |
| materId | long | 食材 id（关联 nut_mater_base.id） |
| materName | string | 食材名称 |
| vegTypes | string | 净菜类型，逗号分隔，如 `切丁,切片` |

---

### 2. 仓库区域下拉列表

**GET** `/nutrition/neglect/inbound/zone-options`

获取仓库区域选项，用于入库时选择存放区域。

**Query 参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| warehouseId | long | ❌ | 仓库 id，不传则返回所有区域 |
| keyword | string | ❌ | 关键字模糊搜索（区域编号/名称） |

**响应示例**

```json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": 101,
      "zoneNo": "WH-A-01",
      "zoneName": "A仓-蔬菜区-01",
      "warehouseId": 10
    }
  ]
}
```

**响应字段说明**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | long | 区域主键 id |
| zoneNo | string | 区域编号，如 `WH-A-01` |
| zoneName | string | 区域名称，如 `A仓-蔬菜区-01` |
| warehouseId | long | 关联仓库 id |

---

### 3. 供应商下拉列表

**GET** `/nutrition/neglect/inbound/supplier-options`

获取供应商选项，内部与外部供应商合并返回。

**Query 参数**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| type | int | ❌ | 供应商类型：`1`-内部，`2`-外部，不传则返回全部 |
| keyword | string | ❌ | 关键字模糊搜索（供应商名称） |

**响应示例**

```json
{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": 201,
      "name": "绿源农场",
      "type": 1
    },
    {
      "id": 202,
      "name": "鲜达食品有限公司",
      "type": 2
    }
  ]
}
```

**响应字段说明**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | long | 供应商 id |
| name | string | 供应商名称 |
| type | int | `1`-内部供应商，`2`-外部供应商 |

---

### 4. 毛菜入库提交

**POST** `/nutrition/neglect/inbound/raw-inbound`

入库秤设备提交毛菜入库记录，`opType` 由后端固定为 `1`（设备自动），无需传入。

**Request Body**

```json
{
  "traceCode": "TC20240501001",
  "supplierType": 1,
  "materialName": "西红柿",
  "supplierId": 201,
  "spec": "25kg/件",
  "quantity": 2,
  "weight": 49.8,
  "zoneId": 101,
  "operator": "张三",
  "storageArea": "A仓-蔬菜区-01",
  "reportNo": "RPT-2024-001",
  "cameraCode": "CAM-001",
  "videoUrl": "http://example.com/video/001.mp4",
  "remark": ""
}
```

**字段说明**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| traceCode | string | ✅ | 溯源码 |
| supplierType | short | ✅ | 供应商类型：`1`-内部，`2`-外部 |
| materialName | string | ✅ | 食材名称 |
| supplierId | long | ✅ | 供应商 id |
| spec | string | ✅ | 入库规格，如 `25kg/件`、`散装(kg)` |
| quantity | int | ✅ | 入库数量 |
| weight | decimal | ✅ | 入库重量（kg） |
| zoneId | long | ✅ | 存放区域 id |
| operator | string | ✅ | 操作人姓名 |
| storageArea | string | ❌ | 存放区域名称（冗余字段，可与 zoneId 对应名称一致） |
| reportNo | string | ❌ | 卫生检测报告编号 |
| cameraCode | string | ❌ | 摄像头编号 |
| videoUrl | string | ❌ | 监控视频地址 |
| remark | string | ❌ | 备注 |

**响应示例**

```json
{
  "code": 200,
  "msg": "保存成功",
  "data": null
}
```

---

### 5. 净菜入库提交

**POST** `/nutrition/neglect/inbound/clean-inbound`

入库秤设备提交净菜入库记录，`opType` 由后端固定为 `1`（设备自动），无需传入。

**Request Body**

```json
{
  "traceCode": "TC20240501002",
  "ingredientName": "西红柿",
  "cleanType": "切丁",
  "spec": "袋装/500g",
  "quantity": 10,
  "weight": 5.0,
  "inboundTime": "2024-05-01T08:30:00",
  "zoneId": 102,
  "operator": "李四",
  "expiryDate": "2024-05-03T00:00:00",
  "storageTemp": 4.5,
  "cameraCode": "CAM-002",
  "videoUrl": "http://example.com/video/002.mp4",
  "remark": ""
}
```

**字段说明**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| traceCode | string | ✅ | 溯源码 |
| ingredientName | string | ✅ | 食材名称 |
| cleanType | string | ✅ | 净菜类型，如 `切丁`、`切片`（参考接口1返回的 `vegTypes`） |
| spec | string | ✅ | 入库规格，如 `袋装/500g`、`盒装/300g` |
| quantity | int | ✅ | 入库数量（包/盒/份） |
| weight | decimal | ✅ | 入库重量（kg） |
| inboundTime | datetime | ✅ | 入库时间，格式：`yyyy-MM-dd'T'HH:mm:ss` |
| zoneId | long | ✅ | 仓库区域 id |
| operator | string | ❌ | 操作人姓名 |
| expiryDate | datetime | ❌ | 保质期至，格式同 `inboundTime` |
| storageTemp | decimal | ❌ | 存放温度（℃） |
| cameraCode | string | ❌ | 摄像头编号 |
| videoUrl | string | ❌ | 监控视频地址 |
| remark | string | ❌ | 备注 |

**响应示例**

```json
{
  "code": 200,
  "msg": "保存成功",
  "data": null
}
```

---

## 典型业务流程

```
设备扫溯源码
    ↓
GET /ingredient-by-trace?traceCode=xxx   → 获取食材列表
    ↓
GET /zone-options                         → 获取区域列表
GET /supplier-options                     → 获取供应商列表（毛菜需要）
    ↓
用户确认信息 / 秤自动称重
    ↓
POST /raw-inbound  （毛菜）
 或
POST /clean-inbound（净菜）
```