上传源代码版本

2026-06-01 16:30:29 +08:00
commit b2a9b7d3c2
462 changed files with 104365 additions and 0 deletions
--- a/批量取消订单接口文档.md
+++ b/批量取消订单接口文档.md
@@ -0,0 +1,169 @@
+# 批量取消订单接口文档
+
+## 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 请求示例
+
+```json
+{
+  "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 响应示例
+
+#### 成功响应
+
+```json
+{
+  "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"
+}
+```
+
+#### 失败响应
+
+```json
+{
+  "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凭证验证，确保操作的安全性
+
+批量取消订单接口的实现，大大提高了订单管理的效率，特别是在需要批量处理大量订单的场景下。同时，数据库索引的优化也为系统的整体性能提升奠定了基础。