Files

2026-06-01 16:30:29 +08:00

3.5 KiB

Raw Permalink Blame History

批量查询换单状态接口规格说明

1. 需求概述

新增一个可以查询有没有换单成功以及换单成功时间的接口。支持输入多个中性面单或者是尾程单号。头部中要加入customerCode和apiKey的校验。然后要通过customerCode在labelreplacerequests中找到对应的订单并且换单是否成功要通过有没有成功返回标签的扫描记录来判断，这里做连表查询。

2. 接口设计

2.1 接口路径

GET /api/Label/label-replace/status

2.2 请求参数

2.2.1 头部参数

参数名	类型	必选	描述
customerCode	string	是	客户代码
apiKey	string	是	API密钥

2.2.2 查询参数

参数名	类型	必选	描述
waybills	string	否	中性面单单号，多个单号用逗号分隔
trackings	string	否	尾程跟踪单号，多个单号用逗号分隔

2.3 响应结构

{
  "status": "ok",
  "timestamp": "2026-03-10T10:00:00Z",
  "count": 2,
  "data": [
    {
      "waybillNumber": "WB1234567890",
      "trackingNumber": "TN9876543210",
      "replaced": true,
      "replacedAt": "2026-03-10T09:30:00Z"
    },
    {
      "waybillNumber": "WB0987654321",
      "trackingNumber": "TN1234567890",
      "replaced": false,
      "replacedAt": null
    }
  ]
}

2.4 错误响应

{
  "status": "error",
  "message": "错误信息",
  "errorDetails": "详细错误信息"
}

3. 业务逻辑

头部校验：验证customerCode和apiKey是否有效
参数验证：确保至少提供了waybills或trackings参数
数据查询：
- 根据customerCode找到对应的客户ID
- 根据提供的单号查询label_replace_requests表
- 联合查询label_scan_history表，判断是否有成功的扫描记录（Result=0）
结果处理：
- 对于每个单号，判断是否换单成功
- 记录换单成功的时间（最新的成功扫描记录时间）
- 构建响应数据

4. 技术实现

4.1 控制器实现

在LabelController中添加新的方法，处理批量查询请求。

4.2 服务层实现

在ILabelReplaceService接口中添加新的方法，实现批量查询逻辑。

4.3 数据访问层实现

在ILabelReplaceRepository接口中添加新的方法，实现连表查询逻辑。

5. 验证规则

头部校验：
- customerCode和apiKey不能为空
- 验证apiKey是否与customerCode匹配且有效
参数验证：
- 至少提供waybills或trackings参数
- 单号格式验证
数据验证：
- 确保查询的订单属于指定的客户
- 确保扫描记录与订单关联

6. 性能考虑

支持批量查询，减少API调用次数
使用索引优化查询性能
合理处理大数据量的情况

7. 安全考虑

严格的API密钥验证
防止SQL注入攻击
限制查询结果数量

8. 测试用例

8.1 成功场景

批量查询多个中性面单号
批量查询多个尾程跟踪单号
混合查询中性面单和尾程跟踪单号

8.2 失败场景

缺少头部参数
API密钥无效
提供的单号不存在
提供的单号不属于指定客户

9. 实现步骤

在ILabelReplaceService中添加新方法
在LabelReplaceService中实现该方法
在ILabelReplaceRepository中添加新方法
在LabelReplaceRepository中实现该方法
在LabelController中添加新的API端点
实现头部校验逻辑
编写测试用例
部署和验证

3.5 KiB Raw Permalink Blame History Unescape Escape