jennisonzhang/LabelChange-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
LabelChange-server/.trae/docs/Batch_Parse_API_Guide.md
Im-Jenisson b2a9b7d3c2 上传源代码版本
2026-06-01 16:30:29 +08:00

7.7 KiB
Raw Permalink Blame History

PDF标签批量解析接口指南

版本: v1.0
更新: 2026-05-13
状态: ✅ 已实施并编译通过

📋 接口概述

为了方便您进行已有订单数据的标签解析，我为您新增了两个API接口：

接口 方法 路由 说明
批量解析标签 POST /api/label/label-replace/batch-parse 批量解析订单标签
缓存统计 GET /api/label/label-replace/cache-statistics 查看缓存统计信息

🚀 接口详解

1. 批量解析标签接口

端点: POST /api/label/label-replace/batch-parse

功能: 根据不同条件批量解析订单标签并缓存

请求格式

{
  "mode": "all|range|customer|single",
  "limit": 1000,
  "waybillNumber": "可选：单条模式的中性面单号",
  "customerId": "可选：客户模式的客户ID",
  "startDate": "可选：时间范围模式的开始时间",
  "endDate": "可选：时间范围模式的结束时间"
}

Mode 模式详解

1️⃣ all 模式（全部）

处理所有有标签的订单

请求示例：

curl -X POST http://localhost:8080/api/label/label-replace/batch-parse \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "all",
    "limit": 1000
  }'

响应示例：

{
  "status": "success",
  "message": "批量解析完成",
  "data": {
    "totalProcessed": 250,
    "successCount": 248,
    "errorCount": 2,
    "mode": "all"
  }
}
2️⃣ range 模式（时间范围）

按指定的时间范围处理订单

请求示例：

curl -X POST http://localhost:8080/api/label/label-replace/batch-parse \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "range",
    "startDate": "2026-05-01T00:00:00",
    "endDate": "2026-05-13T23:59:59",
    "limit": 500
  }'

响应示例：

{
  "status": "success",
  "message": "批量解析完成",
  "data": {
    "totalProcessed": 150,
    "successCount": 148,
    "errorCount": 2,
    "mode": "range"
  }
}
3️⃣ customer 模式（按客户）

按指定客户处理订单

请求示例：

curl -X POST http://localhost:8080/api/label/label-replace/batch-parse \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "customer",
    "customerId": "CUST001",
    "limit": 500
  }'

响应示例：

{
  "status": "success",
  "message": "批量解析完成",
  "data": {
    "totalProcessed": 80,
    "successCount": 79,
    "errorCount": 1,
    "mode": "customer"
  }
}
4️⃣ single 模式（单条）

处理单条订单

请求示例：

curl -X POST http://localhost:8080/api/label/label-replace/batch-parse \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "single",
    "waybillNumber": "SFN202605130001"
  }'

响应示例：

{
  "status": "success",
  "message": "批量解析完成",
  "data": {
    "totalProcessed": 1,
    "successCount": 1,
    "errorCount": 0,
    "mode": "single"
  }
}

2. 缓存统计接口

端点: GET /api/label/label-replace/cache-statistics

功能: 查看PDF缓存的统计信息

请求示例

curl -X GET http://localhost:8080/api/label/label-replace/cache-statistics

响应示例

{
  "status": "success",
  "message": "缓存统计信息",
  "data": {
    "totalRecords": 1250,
    "successRecords": 1200,
    "failedRecords": 30,
    "invalidRecords": 10,
    "pendingRecords": 10,
    "withBarcodeRecords": 980,
    "averageParseDurationMs": 425.5,
    "maxParseDurationMs": 2100,
    "minParseDurationMs": 45
  }
}

统计字段说明：

字段 说明
totalRecords 缓存表中的总记录数
successRecords 成功缓存的记录数（Status=1）
failedRecords 缓存失败的记录数（Status=2）
invalidRecords 已失效的记录数（Status=3）
pendingRecords 待处理的记录数（Status=0）
withBarcodeRecords 成功提取条码的记录数
averageParseDurationMs 平均解析耗时（毫秒）
maxParseDurationMs 最长解析耗时（毫秒）
minParseDurationMs 最短解析耗时（毫秒）

💡 使用场景

场景1：初始化现有数据

需求：将所有现有订单的标签解析并缓存

curl -X POST http://localhost:8080/api/label/label-replace/batch-parse \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "all",
    "limit": 5000
  }'

场景2：重新解析指定时间范围的订单

需求：重新解析2026年5月1日至5月13日的所有订单标签

curl -X POST http://localhost:8080/api/label/label-replace/batch-parse \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "range",
    "startDate": "2026-05-01T00:00:00",
    "endDate": "2026-05-13T23:59:59",
    "limit": 2000
  }'

场景3：按客户重新解析

需求：重新解析特定客户的所有订单标签

curl -X POST http://localhost:8080/api/label/label-replace/batch-parse \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "customer",
    "customerId": "CUST001",
    "limit": 1000
  }'

场景4：解析单条订单

需求：重新解析某个特定订单的标签

curl -X POST http://localhost:8080/api/label/label-replace/batch-parse \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "single",
    "waybillNumber": "SFN202605130001"
  }'

🔍 错误处理

错误响应示例

缺少必需参数：

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

无效的mode参数：

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

解析过程中的错误：

{
  "status": "error",
  "message": "批量解析失败",
  "errorDetails": "具体错误信息"
}

📊 执行过程

当您调用批量解析接口时，系统会：

1. 根据mode参数查询匹配的订单
   ↓
2. 对每个订单执行以下步骤：
   ├─ 下载或读取标签（URL或Base64）
   ├─ 验证PDF有效性（页数、文件大小）
   ├─ 使用GhostScript渲染PDF
   ├─ 提取条码信息（异步）
   └─ 缓存结果到数据库
   ↓
3. 返回处理统计结果

⚠️ 注意事项

  1. 批量处理限制

    • 默认limit为1000，建议分批处理避免超时
    • 对于all模式，建议limit不超过5000

  2. 处理时间

    • 根据订单数量和标签复杂度，处理时间会变化
    • 平均每个订单处理时间为400-600ms
    • 建议使用较长的HTTP超时时间（>60秒）

  3. 资源占用

    • 大批量处理会占用服务器资源
    • 建议在业务低谷期执行

  4. 重复处理

    • 重复调用接口会重新处理订单
    • 已有缓存会被覆盖

🛠️ 与PostMan集成

1. 创建环境变量

{{base_url}} = http://localhost:8080

2. 创建请求

全部解析

POST {{base_url}}/api/label/label-replace/batch-parse

Body (JSON):
{
  "mode": "all",
  "limit": 1000
}

查看统计

GET {{base_url}}/api/label/label-replace/cache-statistics

📈 使用建议

首次使用流程

1. 调用统计接口查看当前缓存状态
   GET /cache-statistics
   
2. 根据统计结果决定是否需要全量解析
   
3. 如果需要解析，根据场景选择合适的mode
   POST /batch-parse
   
4. 解析完成后，再次调用统计接口查看效果
   GET /cache-statistics

✅ 验证清单

✅ 接口已实施
✅ 支持4种处理模式
✅ 完整的错误处理
✅ 详细的统计信息
✅ 编译成功（exit code = 0）
✅ 零编译错误

现在您可以随时触发订单标签解析了！ 🎉