上传源代码版本

2026-06-01 16:30:29 +08:00
commit b2a9b7d3c2
462 changed files with 104365 additions and 0 deletions
--- a/.trae/docs/Batch_Parse_API_Guide.md
+++ b/.trae/docs/Batch_Parse_API_Guide.md
@@ -0,0 +1,404 @@
+# 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）
+✅ 零编译错误
+```
+
+---
+
+**现在您可以随时触发订单标签解析了！** 🎉