355 lines
8.0 KiB
Markdown
355 lines
8.0 KiB
Markdown
# 批量解析接口(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
|
||
{
|
||
/// <summary>
|
||
/// 解析模式：all、range、customer、single、batch
|
||
/// </summary>
|
||
public string Mode { get; set; }
|
||
|
||
/// <summary>
|
||
/// 单条或指定模式下的单号（single、customer 模式必填）
|
||
/// </summary>
|
||
public string WaybillNumber { get; set; }
|
||
|
||
/// <summary>
|
||
/// 批量订单单号列表（batch 模式必填）
|
||
/// </summary>
|
||
public List<string> WaybillNumbers { get; set; }
|
||
|
||
/// <summary>
|
||
/// 指定客户ID（customer 模式必填）
|
||
/// </summary>
|
||
public int? CustomerId { get; set; }
|
||
|
||
/// <summary>
|
||
/// 开始日期（range 模式必填）
|
||
/// </summary>
|
||
public DateTime? StartDate { get; set; }
|
||
|
||
/// <summary>
|
||
/// 结束日期（range 模式必填）
|
||
/// </summary>
|
||
public DateTime? EndDate { get; set; }
|
||
|
||
/// <summary>
|
||
/// 限制返回的最大数量（默认1000）
|
||
/// </summary>
|
||
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 | 新增时间记录、灵活参数验证和批量订单模式 |
|