# 批量取消订单接口文档

## 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凭证验证，确保操作的安全性

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