# 批量解析接口(batch-parse)更新说明
## 概述
批量解析接口已进行重大升级，新增了时间记录、灵活的参数验证和批量订单模式，使得接口更加灵活和便于性能监控。
**版本**: v1.1
**更新日期**: 2026-05-19
---
## 主要改进
### 1. 添加了完整的时间记录
#### 开始和结束时间戳
```json
{
"status": "success",
"message": "批量解析完成",
"data": {
"totalProcessed": 100,
"successCount": 95,
"errorCount": 5,
"startTimestamp": 1716127200000,
"endTimestamp": 1716127240000,
"totalDuration": 40000,
"processRecords": [...]
}
}
```
#### 单个订单处理时间记录
每个订单都有详细的处理记录：
```csharp
public class BatchProcessItemRecord
{
public string WaybillNumber { get; set; } // 订单单号
public string Status { get; set; } // 处理状态: success/error
public int Duration { get; set; } // 处理耗时（毫秒）
public long Timestamp { get; set; } // 处理时间戳（毫秒）
public string ErrorMessage { get; set; } // 错误信息（如果失败）
}
```
### 2. WaybillNumber 字段调整为条件必填
| 模式 | WaybillNumber | WaybillNumbers | 说明 |
|------|--------------|----------------|------|
| `all` | 非必填 | 非必填 | 处理所有有标签的订单 |
| `range` | 非必填 | 非必填 | 需要 StartDate 和 EndDate |
| `customer` | 非必填 | 非必填 | 需要 CustomerId |
| `single` | **必填** | 非必填 | 处理单个订单 |
| `batch` | 非必填 | **必填** | 处理批量订单 |
### 3. 新增批量订单模式 (batch)
**用途**: 直接传入一个订单号列表进行解析，无需查询数据库
**请求示例**:
```json
{
"Mode": "batch",
"WaybillNumbers": [
"SF2026051900001",
"SF2026051900002",
"SF2026051900003"
]
}
```
**响应示例**:
```json
{
"status": "success",
"message": "批量解析完成",
"data": {
"totalProcessed": 3,
"successCount": 3,
"errorCount": 0,
"mode": "batch",
"startTimestamp": 1716127200000,
"endTimestamp": 1716127210000,
"totalDuration": 10000,
"processRecords": [
{
"waybillNumber": "SF2026051900001",
"status": "success",
"duration": 3200,
"timestamp": 1716127200000,
"errorMessage": null
},
{
"waybillNumber": "SF2026051900002",
"status": "success",
"duration": 3400,
"timestamp": 1716127203200,
"errorMessage": null
},
{
"waybillNumber": "SF2026051900003",
"status": "success",
"duration": 3400,
"timestamp": 1716127206600,
"errorMessage": null
}
]
}
}
```
---
## API 接口说明
### 端点
```
POST /api/label/batch-parse
Content-Type: application/json
```
### 请求参数
```csharp
public class BatchParseLabelRequest
{
///
/// 解析模式：all、range、customer、single、batch
///
public string Mode { get; set; }
///
/// 单条或指定模式下的单号（single、customer 模式必填）
///
public string WaybillNumber { get; set; }
///
/// 批量订单单号列表（batch 模式必填）
///
public List WaybillNumbers { get; set; }
///
/// 指定客户ID（customer 模式必填）
///
public int? CustomerId { get; set; }
///
/// 开始日期（range 模式必填）
///
public DateTime? StartDate { get; set; }
///
/// 结束日期（range 模式必填）
///
public DateTime? EndDate { get; set; }
///
/// 限制返回的最大数量（默认1000）
///
public int? Limit { get; set; }
}
```
### 响应结构
```csharp
{
"status": "success" | "error",
"message": "批量解析完成" | "批量解析失败",
"errorDetails": "错误详情（仅error时有）",
"data": {
"totalProcessed": 100,
"successCount": 95,
"errorCount": 5,
"mode": "all|range|customer|single|batch",
"startTimestamp": 1716127200000,
"endTimestamp": 1716127240000,
"totalDuration": 40000,
"processRecords": [
{
"waybillNumber": "SF20260519...",
"status": "success|error",
"duration": 3200,
"timestamp": 1716127200000,
"errorMessage": "...(仅error时有)"
}
]
}
}
```
---
## 使用场景
### 场景1: 解析所有有标签的订单
**请求**:
```bash
curl -X POST http://localhost:5000/api/label/batch-parse \
-H "Content-Type: application/json" \
-d '{
"Mode": "all",
"Limit": 500
}'
```
### 场景2: 按时间范围解析
**请求**:
```bash
curl -X POST http://localhost:5000/api/label/batch-parse \
-H "Content-Type: application/json" \
-d '{
"Mode": "range",
"StartDate": "2026-05-10T00:00:00Z",
"EndDate": "2026-05-19T23:59:59Z",
"Limit": 1000
}'
```
### 场景3: 解析指定客户的订单
**请求**:
```bash
curl -X POST http://localhost:5000/api/label/batch-parse \
-H "Content-Type: application/json" \
-d '{
"Mode": "customer",
"CustomerId": 123,
"Limit": 500
}'
```
### 场景4: 解析单个订单
**请求**:
```bash
curl -X POST http://localhost:5000/api/label/batch-parse \
-H "Content-Type: application/json" \
-d '{
"Mode": "single",
"WaybillNumber": "SF2026051900001"
}'
```
### 场景5: 批量解析指定的订单号
**请求**:
```bash
curl -X POST http://localhost:5000/api/label/batch-parse \
-H "Content-Type: application/json" \
-d '{
"Mode": "batch",
"WaybillNumbers": [
"SF2026051900001",
"SF2026051900002",
"SF2026051900003"
]
}'
```
---
## 时间戳说明
### UnixTimeMilliseconds 格式
所有时间戳都采用 **Unix 时间（毫秒级）** 格式：
- `1716127200000` 表示 2026-05-19 08:00:00 UTC
- 可以通过 `new DateTimeOffset(DateTime.FromUnixTimeMilliseconds(timestamp))` 转换
### 性能分析
通过 `totalDuration` 和 `processRecords[].duration` 可以进行性能分析：
```csharp
var avgDuration = processRecords.Average(r => r.Duration);
var maxDuration = processRecords.Max(r => r.Duration);
var minDuration = processRecords.Min(r => r.Duration);
```
---
## 错误处理
### 模式参数不存在
```json
{
"message": "请提供有效的请求参数"
}
```
### 无效的模式
```json
{
"message": "无效的处理模式，请使用: all, range, customer, single, batch"
}
```
### Range 模式缺少日期
```json
{
"message": "时间范围模式需要 StartDate 和 EndDate 参数"
}
```
### Customer 模式缺少 CustomerId
```json
{
"message": "客户模式需要 CustomerId 参数"
}
```
### Single 模式缺少 WaybillNumber
```json
{
"message": "单条模式需要 WaybillNumber 参数"
}
```
### Batch 模式缺少 WaybillNumbers
```json
{
"message": "批量模式需要 WaybillNumbers 参数（订单号数组）"
}
```
---
## 相关源代码
- [LabelController.cs](file:///d:/EPproject/LabelReplaceServer/src/CONTROLLER/Controllers/LabelController.cs#L2617-L2850) - batch-parse 接口实现
- [LabelParseRequests.cs](file:///d:/EPproject/LabelReplaceServer/src/MDL/Models/LabelParseRequests.cs) - 请求/响应模型定义
- [LabelPdfCacheService.cs](file:///d:/EPproject/LabelReplaceServer/src/BLL/Services/LabelPdfCacheService.cs) - 业务逻辑处理
---
## 更新历史
| 版本 | 日期 | 内容 |
|------|------|------|
| v1.0 | 2026-05-xx | 初始版本 |
| v1.1 | 2026-05-19 | 新增时间记录、灵活参数验证和批量订单模式 |