LabelChange-server/批量取消订单接口文档.md

批量取消订单接口文档

1. 数据库索引优化

1.1 优化内容

本次优化为以下表添加了必要的索引：

1.1.1 label_replace_requests表

• idx_label_replace_NeutralWaybillNumber：中性面单单号索引
• idx_label_replace_FinalMileTrackingNumber：尾程跟踪单号索引
• idx_label_replace_CustomerId：客户ID索引
• idx_label_replace_CreatedAt：创建时间索引
• idx_label_replace_CustomerId_CreatedAt：客户ID和创建时间组合索引

1.1.2 label_scan_history表

• idx_label_scan_NeutralWaybillNumber：中性面单单号索引
• idx_label_scan_CustomerId：客户ID索引
• idx_label_scan_CreatedAt：创建时间索引
• idx_label_scan_CustomerId_NeutralWaybillNumber：客户ID和中性面单单号组合索引
• idx_label_scan_ReferenceNumber：参考号索引
• idx_label_scan_FinalMileTrackingNumber：尾程跟踪单号索引

1.2 优化效果

• 查询性能提升：通过添加索引，减少了数据库查询的扫描范围，提高了查询速度
• 批量操作优化：对于批量查询和处理操作，索引能够显著提升性能
• 系统稳定性：减少了数据库负载，提高了系统的整体稳定性

2. 批量取消订单接口

2.1 接口信息

• 接口地址：/api/Label/label-replace/batch-cancel
• 请求方法：POST
• 内容类型：application/json

2.2 请求参数

参数名	类型	必需	描述
CustomerCode	string	是	客户代码
ApiKey	string	是	API密钥
WaybillNumbers	array[string]	是	中性面单单号列表

2.3 请求示例

{
  "CustomerCode": "TEST_CUSTOMER",
  "ApiKey": "your_api_key",
  "WaybillNumbers": [
    "WB202603180001",
    "WB202603180002",
    "WB202603180003"
  ]
}

2.4 响应参数

参数名	类型	描述
status	string	操作状态（ok或error）
timestamp	datetime	操作时间戳
successCount	number	成功取消的订单数量
failedCount	number	失败的订单数量
failedItems	array	失败的订单详情
message	string	操作消息

2.5 响应示例

成功响应

{
  "status": "ok",
  "timestamp": "2026-03-18T11:00:00Z",
  "successCount": 2,
  "failedCount": 1,
  "failedItems": [
    {
      "WaybillNumber": "WB202603180003",
      "Reason": "Order not found"
    }
  ],
  "message": "Batch cancellation completed. Success: 2, Failed: 1"
}

失败响应

{
  "status": "error",
  "message": "Invalid API credentials. Please check your customer_code and api_key."
}

2.6 错误码说明

错误信息	说明
Waybill numbers are required	未提供中性面单单号列表
Invalid API credentials	API凭证无效
Order not found	订单不存在
Label has been returned and cannot be modified	标签已返回，无法修改
Internal error	内部错误

2.7 使用注意事项

1. API凭证验证：调用接口时必须提供有效的CustomerCode和ApiKey
2. 订单状态检查：已返回标签的订单无法取消
3. 批量处理：支持同时取消多个订单，建议每次批量处理的订单数量不超过100个
4. 错误处理：接口会返回每个失败订单的具体原因，便于排查问题
5. 幂等性：重复调用接口不会导致重复取消操作

3. 接口测试

3.1 测试环境

• 测试地址：http://localhost:5003/api/Label/label-replace/batch-cancel
• 测试工具：Postman、curl等

3.2 测试步骤

1. 准备测试数据，确保有可取消的订单
2. 构造请求参数，包含有效的CustomerCode、ApiKey和WaybillNumbers
3. 发送POST请求到接口地址
4. 检查响应结果，验证取消操作是否成功
5. 验证数据库中订单状态是否已更新为"N"（冻结状态）

3.3 测试用例

测试场景	预期结果
正常批量取消	成功取消所有订单，返回successCount等于请求数量
部分订单不存在	成功取消存在的订单，返回failedItems包含不存在的订单
部分订单已返回标签	成功取消未返回标签的订单，返回failedItems包含已返回标签的订单
无效API凭证	返回错误信息，不执行取消操作
空订单列表	返回错误信息，不执行取消操作

4. 性能考虑

4.1 数据库性能

• 通过添加索引，批量取消操作的数据库查询性能得到显著提升
• 对于大批量操作（如1000+订单），建议分批次处理，每批次不超过100个订单

4.2 系统负载

• 批量取消操作会产生一定的系统负载，建议在系统低峰期执行大批量操作
• 接口内部使用了异步处理，不会阻塞其他请求

4.3 超时处理

• 接口默认超时时间为30秒，对于大批量操作可能需要适当增加超时时间
• 建议客户端设置合理的超时时间，避免因网络问题导致操作失败

5. 总结

本次实现了以下功能：

1. 数据库索引优化：为核心表添加了必要的索引，提高了查询性能
2. 批量取消订单接口：实现了支持批量取消订单的API，提高了操作效率
3. 完善的错误处理：提供了详细的错误信息和失败原因
4. 安全性：通过API凭证验证，确保操作的安全性

批量取消订单接口的实现，大大提高了订单管理的效率，特别是在需要批量处理大量订单的场景下。同时，数据库索引的优化也为系统的整体性能提升奠定了基础。