LabelChange-server/.trae/specs/receipt_query/spec.md

收货查询接口设计文档

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. 示例响应

成功响应

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

失败响应

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