jennisonzhang/LabelChange-server

Fork 0

Files

Im-Jenisson b2a9b7d3c2 上传源代码版本

2026-06-01 16:30:29 +08:00

8.0 KiB

Raw Permalink Blame History

批量解析接口(batch-parse)更新说明

概述

批量解析接口已进行重大升级，新增了时间记录、灵活的参数验证和批量订单模式，使得接口更加灵活和便于性能监控。

版本: v1.1
更新日期: 2026-05-19

主要改进

1. 添加了完整的时间记录

开始和结束时间戳

{
    "status": "success",
    "message": "批量解析完成",
    "data": {
        "totalProcessed": 100,
        "successCount": 95,
        "errorCount": 5,
        "startTimestamp": 1716127200000,
        "endTimestamp": 1716127240000,
        "totalDuration": 40000,
        "processRecords": [...]
    }
}

单个订单处理时间记录

每个订单都有详细的处理记录：

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)

用途: 直接传入一个订单号列表进行解析，无需查询数据库

请求示例:

{
    "Mode": "batch",
    "WaybillNumbers": [
        "SF2026051900001",
        "SF2026051900002",
        "SF2026051900003"
    ]
}

响应示例:

{
    "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

请求参数

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; }
}

响应结构

{
    "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: 解析所有有标签的订单

请求:

curl -X POST http://localhost:5000/api/label/batch-parse \
  -H "Content-Type: application/json" \
  -d '{
    "Mode": "all",
    "Limit": 500
  }'

场景2: 按时间范围解析

请求:

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: 解析指定客户的订单

请求:

curl -X POST http://localhost:5000/api/label/batch-parse \
  -H "Content-Type: application/json" \
  -d '{
    "Mode": "customer",
    "CustomerId": 123,
    "Limit": 500
  }'

场景4: 解析单个订单

请求:

curl -X POST http://localhost:5000/api/label/batch-parse \
  -H "Content-Type: application/json" \
  -d '{
    "Mode": "single",
    "WaybillNumber": "SF2026051900001"
  }'

场景5: 批量解析指定的订单号

请求:

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 可以进行性能分析：

var avgDuration = processRecords.Average(r => r.Duration);
var maxDuration = processRecords.Max(r => r.Duration);
var minDuration = processRecords.Min(r => r.Duration);

错误处理

模式参数不存在

{
    "message": "请提供有效的请求参数"
}

无效的模式

{
    "message": "无效的处理模式，请使用: all, range, customer, single, batch"
}

Range 模式缺少日期

{
    "message": "时间范围模式需要 StartDate 和 EndDate 参数"
}

Customer 模式缺少 CustomerId

{
    "message": "客户模式需要 CustomerId 参数"
}

Single 模式缺少 WaybillNumber

{
    "message": "单条模式需要 WaybillNumber 参数"
}

Batch 模式缺少 WaybillNumbers

{
    "message": "批量模式需要 WaybillNumbers 参数（订单号数组）"
}

更新历史

版本	日期	内容
v1.0	2026-05-xx	初始版本
v1.1	2026-05-19	新增时间记录、灵活参数验证和批量订单模式

8.0 KiB Raw Permalink Blame History Unescape Escape