LabelChange-server/.trae/docs/Batch_Parse_API_Guide.md

# 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`

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

#### 请求格式

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

#### Mode 模式详解

##### **1️⃣ all 模式（全部）**
处理所有有标签的订单

**请求示例**：
```bash
curl -X POST http://localhost:8080/api/label/label-replace/batch-parse \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "all",
    "limit": 1000
  }'
```

**响应示例**：
```json
{
  "status": "success",
  "message": "批量解析完成",
  "data": {
    "totalProcessed": 250,
    "successCount": 248,
    "errorCount": 2,
    "mode": "all"
  }
}
```

---

##### **2️⃣ range 模式（时间范围）**
按指定的时间范围处理订单

**请求示例**：
```bash
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
  }'
```

**响应示例**：
```json
{
  "status": "success",
  "message": "批量解析完成",
  "data": {
    "totalProcessed": 150,
    "successCount": 148,
    "errorCount": 2,
    "mode": "range"
  }
}
```

---

##### **3️⃣ customer 模式（按客户）**
按指定客户处理订单

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

**响应示例**：
```json
{
  "status": "success",
  "message": "批量解析完成",
  "data": {
    "totalProcessed": 80,
    "successCount": 79,
    "errorCount": 1,
    "mode": "customer"
  }
}
```

---

##### **4️⃣ single 模式（单条）**
处理单条订单

**请求示例**：
```bash
curl -X POST http://localhost:8080/api/label/label-replace/batch-parse \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "single",
    "waybillNumber": "SFN202605130001"
  }'
```

**响应示例**：
```json
{
  "status": "success",
  "message": "批量解析完成",
  "data": {
    "totalProcessed": 1,
    "successCount": 1,
    "errorCount": 0,
    "mode": "single"
  }
}
```

---

### 2. 缓存统计接口

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

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

#### 请求示例

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

#### 响应示例

```json
{
  "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：初始化现有数据

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

```bash
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日的所有订单标签

```bash
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：按客户重新解析

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

```bash
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：解析单条订单

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

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

---

## 🔍 错误处理

### 错误响应示例

**缺少必需参数**：
```json
{
  "message": "时间范围模式需要 StartDate 和 EndDate 参数"
}
```

**无效的mode参数**：
```json
{
  "message": "无效的处理模式，请使用: all, range, customer, single"
}
```

**解析过程中的错误**：
```json
{
  "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）
✅ 零编译错误
```

---

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