# 收货查询接口设计文档

## 1. 接口概述

本接口用于查询收货信息，通过输入提单号或大箱号，返回对应的包裹数、已有标签率和到货时间。

## 2. 接口参数

### 2.1 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| billOfLadingNumber | string | 否 | 提单号 |
| masterPackageNumber | string | 否 | 大箱号 |
| callback | string | 否 | JSONP回调函数名 |

**注意**：billOfLadingNumber和masterPackageNumber至少需要提供一个。

### 2.2 响应参数

| 参数名 | 类型 | 描述 |
|-------|------|------|
| code | int | 响应码，0表示成功，9999表示失败 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| data.packageCount | int | 包裹数 |
| data.labelRate | double | 已有标签率，范围0-1 |
| data.arrivalTime | string | 到货时间，格式：yyyy-MM-dd HH:mm:ss |

## 3. 业务逻辑

1. 根据输入的提单号或大箱号，查询label_replace_requests表，获取符合条件的记录
2. 计算包裹数：符合条件的记录总数
3. 计算已有标签率：Label字段有值的记录数除以总记录数
4. 查询arrival_handover_forms表，获取到货时间
5. 组装响应数据并返回

## 4. 接口路径

GET /api/arrival-handover/receipt-query

## 5. 示例请求

```
GET /api/arrival-handover/receipt-query?billOfLadingNumber=BL123456
```

## 6. 示例响应

### 成功响应

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "packageCount": 10,
    "labelRate": 0.8,
    "arrivalTime": "2026-03-25 10:30:00"
  }
}
```

### 失败响应

```json
{
  "code": 9999,
  "message": "参数错误：请提供提单号或大箱号"
}
```