# 批量解析接口(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 | 新增时间记录、灵活参数验证和批量订单模式 |
