# 内部接口文档

## 文档概述
本文档描述了系统内部使用的API接口，用于系统内部模块之间的通信和数据交互。

## 接口列表

| 接口名称 | 请求方法 | 接口URL | 描述 |
|---------|---------|--------|------|
| 根据跟踪单号查询标签替换记录 | GET | /api/label/label-replace/tracking/{trackingNumber} | 根据跟踪单号查询标签替换请求记录 |
| 根据中性面单查询标签替换记录 | GET | /api/label/label-replace/waybill/{waybillNumber} | 根据中性面单单号查询标签替换请求记录 |
| 根据中性面单下载标签文件 | GET | /api/label/label-replace/waybill/{waybillNumber}/download | 根据中性面单单号下载标签文件 |
| 记录标签扫描 | POST | /api/label/label-scan/record | 记录标签扫描信息，包括扫描次数和时间 |
| 根据中性面单查询扫描记录 | GET | /api/label/label-scan/waybill/{waybillNumber} | 根据中性面单单号查询标签扫描记录 |

## 详细接口说明

### 1. 根据跟踪单号查询标签替换记录接口

#### 接口概述
该接口用于根据跟踪单号查询标签替换请求记录，返回符合条件的标签替换请求列表。

#### 请求信息

##### URL
```
GET http://172.232.21.79:5002/api/label/label-replace/tracking/{trackingNumber}
```

##### 请求方法
`GET`

##### 请求头
```
Content-Type: application/json
```

##### 请求参数
| 参数名 | 位置 | 类型 | 必填 | 描述 |
|--------|------|------|------|------|
| trackingNumber | 路径 | string | 是 | 跟踪单号 |

#### 响应信息

##### 成功响应

###### 响应状态码
`200 OK`

###### 响应头
```
Content-Type: application/json
```

###### 响应参数
| 字段名 | 类型 | 描述 |
|--------|------|------|
| status | string | 状态，成功为"ok" |
| timestamp | string | 响应时间戳（UTC） |
| trackingNumber | string | 请求中的跟踪单号 |
| count | integer | 返回的记录数量 |
| data | array | 标签替换请求记录列表 |

###### 成功响应示例
```json
{
  "status": "ok",
  "timestamp": "2026-01-19T10:00:00Z",
  "trackingNumber": "FM1234567890",
  "count": 1,
  "data": [
    {
      "Id": 1,
      "BillOfLadingNumber": "BL12345678",
      "MasterPackageNumber": "MP98765432",
      "ReferenceNumber": "ORD123456",
      "NeutralWaybillNumber": "NW1234567890",
      "FinalMileTrackingNumber": "FM1234567890",
      "Label": "base64_encoded_pdf_content",
      "ReplaceStatus": "Y",
      "CreatedAt": "2026-01-19T08:00:00Z",
      "UpdatedAt": "2026-01-19T08:00:00Z"
    }
  ]
}
```

#### 错误响应

##### 响应状态码
`400 Bad Request` - 参数错误

##### 错误响应示例
```json
{
  "status": "error",
  "message": "Tracking number is required"
}
```

### 2. 根据中性面单查询标签替换记录接口

#### 接口概述
该接口用于根据中性面单单号查询标签替换请求记录，返回符合条件的标签替换请求详情。

#### 请求信息

##### URL
```
GET http://172.232.21.79:5002/api/label/label-replace/waybill/{waybillNumber}
```

##### 请求方法
`GET`

##### 请求头
```
Content-Type: application/json
```

##### 请求参数
| 参数名 | 位置 | 类型 | 必填 | 描述 |
|--------|------|------|------|------|
| waybillNumber | 路径 | string | 是 | 中性面单单号 |

#### 响应信息

##### 成功响应

###### 响应状态码
`200 OK`

###### 响应头
```
Content-Type: application/json
```

###### 响应参数
| 字段名 | 类型 | 描述 |
|--------|------|------|
| status | string | 状态，成功为"ok" |
| timestamp | string | 响应时间戳（UTC） |
| waybillNumber | string | 请求中的中性面单单号 |
| data | object | 标签替换请求记录详情 |

###### 成功响应示例
```json
{
  "status": "ok",
  "timestamp": "2026-01-19T10:00:00Z",
  "waybillNumber": "NW1234567890",
  "data": {
    "Id": 1,
    "BillOfLadingNumber": "BL12345678",
    "MasterPackageNumber": "MP98765432",
    "ReferenceNumber": "ORD123456",
    "NeutralWaybillNumber": "NW1234567890",
    "FinalMileTrackingNumber": "FM1234567890",
    "Label": "base64_encoded_pdf_content",
    "ReplaceStatus": "Y",
    "CreatedAt": "2026-01-19T08:00:00Z",
    "UpdatedAt": "2026-01-19T08:00:00Z"
  }
}
```

#### 错误响应

##### 响应状态码
`400 Bad Request` - 参数错误

##### 错误响应示例
```json
{
  "status": "error",
  "message": "Waybill number is required"
}
```

### 3. 根据中性面单下载标签文件接口

#### 接口概述
该接口用于根据中性面单单号获取标签替换请求的标签文件，并以字节流形式返回。支持base64编码和URL两种标签数据格式。

#### 请求信息

##### URL
```
GET http://172.232.21.79:5002/api/label/label-replace/waybill/{waybillNumber}/download
```

##### 请求方法
`GET`

##### 请求头
```
Content-Type: application/json
```

##### 请求参数
| 参数名 | 位置 | 类型 | 必填 | 描述 |
|--------|------|------|------|------|
| waybillNumber | 路径 | string | 是 | 中性面单单号 |

#### 响应信息

##### 成功响应

###### 响应状态码
`200 OK`

###### 响应头
```
Content-Type: application/pdf
Content-Disposition: attachment; filename="label_NW1234567890.pdf"
```

###### 响应内容
标签文件的字节流数据

#### 错误响应

##### 响应状态码
- `400 Bad Request` - 参数错误或标签数据格式无效
- `404 Not Found` - 找不到对应的标签替换请求
- `500 Internal Server Error` - 服务器内部错误

##### 错误响应示例
```json
{
  "status": "error",
  "message": "Waybill number is required"
}
```

## 接口使用说明

1. **接口访问**：这些接口仅允许系统内部模块访问，不对外暴露
2. **参数验证**：请确保提供有效的参数值，否则将返回错误响应
3. **响应处理**：根据响应状态和数据结构正确处理返回结果
4. **错误处理**：捕获并处理可能的错误，确保系统稳定性
5. **文件下载**：对于下载接口，需正确处理二进制响应流并保存为文件

### 4. 记录标签扫描接口

#### 接口概述
该接口用于记录标签扫描信息，每次调用都会在`label_scan_history`表中创建一条新的历史记录，包含扫描结果、客户ID等详细信息。该接口会自动记录每次扫描的时间、操作人员等信息。

#### 请求信息

##### URL
```
POST http://172.232.21.79:5002/api/label/label-scan/record
```

##### 请求方法
`POST`

##### 请求头
```
Content-Type: application/json
```

##### 请求参数
| 参数名 | 位置 | 类型 | 必填 | 描述 |
|--------|------|------|------|------|
| NeutralWaybillNumber | 请求体 | string | 是 | 中性面单单号 |
| ReferenceNumber | 请求体 | string | 否 | 参考号（一般表示订单号） |
| FinalMileTrackingNumber | 请求体 | string | 否 | 尾程跟踪单号 |
| CustomerId | 请求体 | integer | 否 | 客户ID |
| Result | 请求体 | integer | 否 | 扫描结果：0=ReturnedLabel, 1=NoLabelData, 2=NoOrderData, 3=OrderFrozen, 4=Other |
| CreatedBy | 请求体 | string | 否 | 操作人员，默认为"system" |

##### 请求示例
```json
{
  "NeutralWaybillNumber": "NW1234567890",
  "ReferenceNumber": "ORD123456",
  "FinalMileTrackingNumber": "FM1234567890",
  "CustomerId": 123,
  "Result": 0,
  "CreatedBy": "system"
}
```

#### 响应信息

##### 成功响应

###### 响应状态码
`200 OK`

###### 响应头
```
Content-Type: application/json
```

###### 响应参数
| 字段名 | 类型 | 描述 |
|--------|------|------|
| status | string | 状态，成功为"ok" |
| timestamp | string | 响应时间戳（UTC） |
| scanRecord | object | 标签扫描记录详情 |

###### 成功响应示例
```json
{
  "status": "ok",
  "timestamp": "2026-01-23T10:00:00Z",
  "scanRecord": {
    "Id": 1,
    "CustomerId": 123,
    "ReferenceNumber": "ORD123456",
    "NeutralWaybillNumber": "NW1234567890",
    "FinalMileTrackingNumber": "FM1234567890",
    "Result": 0,
    "Description": "自动记录的标签下载扫描",
    "CreatedBy": "system",
    "CreatedAt": "2026-01-23T10:00:00Z",
    "UpdatedAt": "2026-01-23T10:00:00Z"
  }
}
```

#### 扫描结果类型说明

| 枚举值 | 扫描结果类型 | 描述 |
|--------|------------|------|
| 0 | ReturnedLabel | 成功返回标签 |
| 1 | NoLabelData | 未找到标签数据 |
| 2 | NoOrderData | 未找到订单数据 |
| 3 | OrderFrozen | 订单被冻结，无法下载面单 |
| 4 | Other | 其他异常情况 |

#### 错误响应

##### 响应状态码
`400 Bad Request` - 参数错误

##### 错误响应示例
```json
{
  "status": "error",
  "message": "Neutral waybill number is required"
}
```

### 5. 根据中性面单查询扫描记录接口

#### 接口概述
该接口用于根据中性面单单号查询标签扫描历史记录，返回符合条件的所有扫描记录列表。

#### 请求信息

##### URL
```
GET http://172.232.21.79:5002/api/label/label-scan/waybill/{waybillNumber}
```

##### 请求方法
`GET`

##### 请求头
```
Content-Type: application/json
```

##### 请求参数
| 参数名 | 位置 | 类型 | 必填 | 描述 |
|--------|------|------|------|------|
| waybillNumber | 路径 | string | 是 | 中性面单单号 |

#### 响应信息

##### 成功响应

###### 响应状态码
`200 OK`

###### 响应头
```
Content-Type: application/json
```

###### 响应参数
| 字段名 | 类型 | 描述 |
|--------|------|------|
| status | string | 状态，成功为"ok" |
| timestamp | string | 响应时间戳（UTC） |
| waybillNumber | string | 请求中的中性面单单号 |
| count | integer | 扫描记录总数 |
| data | array | 标签扫描历史记录列表 |

###### 成功响应示例
```json
{
  "status": "ok",
  "timestamp": "2026-01-23T10:00:00Z",
  "waybillNumber": "NW1234567890",
  "count": 2,
  "data": [
    {
      "Id": 1,
      "CustomerId": 123,
      "ReferenceNumber": "ORD123456",
      "NeutralWaybillNumber": "NW1234567890",
      "FinalMileTrackingNumber": "FM1234567890",
      "Result": 0,
      "Description": "自动记录的标签下载扫描",
      "CreatedBy": "system",
      "CreatedAt": "2026-01-23T10:00:00Z",
      "UpdatedAt": "2026-01-23T10:00:00Z"
    },
    {
      "Id": 2,
      "CustomerId": 123,
      "ReferenceNumber": "ORD123456",
      "NeutralWaybillNumber": "NW1234567890",
      "FinalMileTrackingNumber": "FM1234567890",
      "Result": 0,
      "Description": "手动记录的扫描",
      "CreatedBy": "user123",
      "CreatedAt": "2026-01-23T11:30:00Z",
      "UpdatedAt": "2026-01-23T11:30:00Z"
    }
  ]
}
```

#### 扫描结果类型说明

| 枚举值 | 扫描结果类型 | 描述 |
|--------|------------|------|
| 0 | ReturnedLabel | 成功返回标签 |
| 1 | NoLabelData | 未找到标签数据 |
| 2 | NoOrderData | 未找到订单数据 |
| 3 | OrderFrozen | 订单被冻结，无法下载面单 |
| 4 | Other | 其他异常情况 |

#### 错误响应

##### 响应状态码
- `400 Bad Request` - 参数错误
- `404 Not Found` - 找不到对应的扫描记录

##### 错误响应示例
```json
{
  "status": "error",
  "message": "Waybill number is required"
}
```

## 接口使用说明

1. **接口访问**：这些接口仅允许系统内部模块访问，不对外暴露
2. **参数验证**：请确保提供有效的参数值，否则将返回错误响应
3. **响应处理**：根据响应状态和数据结构正确处理返回结果
4. **错误处理**：捕获并处理可能的错误，确保系统稳定性
5. **文件下载**：对于下载接口，需正确处理二进制响应流并保存为文件
6. **扫描记录**：扫描记录接口会自动维护扫描次数和时间信息，无需手动计算

## 文档更新日志

| 日期 | 更新内容 | 更新人 |
|------|----------|--------|
| 2026-01-19 | 1. 初始创建文档<br>2. 添加根据跟踪单号查询标签替换记录接口文档<br>3. 添加根据中性面单查询标签替换记录接口文档<br>4. 添加根据中性面单下载标签文件接口文档<br>5. 添加记录标签扫描接口文档<br>6. 添加根据中性面单查询扫描记录接口文档 | 系统生成 |
| 2026-01-23 | 1. 更新记录标签扫描接口，添加新的请求参数（CustomerId、Result、CreatedBy）<br>2. 更新根据中性面单查询扫描记录接口，返回历史记录列表而非单条记录<br>3. 添加扫描结果类型说明表格<br>4. 更新响应示例，反映新的扫描记录字段<br>5. 调整接口描述，反映从统计扫描次数到历史记录的转变 | 系统生成 |