上传源代码版本

.trae/specs/receipt_query/spec.md

@@ -0,0 +1,71 @@
+# 收货查询接口设计文档
+
+## 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": "参数错误：请提供提单号或大箱号"
+}
+```