515 lines
13 KiB
Markdown
515 lines
13 KiB
Markdown
# 面单标签PDF缓存系统 API 文档
|
||
|
||
## 概述
|
||
|
||
本文档描述了面单标签PDF缓存系统的API接口。该系统用于存储和管理物流面单的PDF标签字节流，支持批量解析、条码识别和缓存统计功能。
|
||
|
||
---
|
||
|
||
## 基础信息
|
||
|
||
### API基地址
|
||
```
|
||
http://[服务器地址]:[端口]/api/label
|
||
```
|
||
|
||
### 支持的HTTP方法
|
||
- `GET` - 获取数据
|
||
- `POST` - 创建或提交数据
|
||
|
||
### 响应格式
|
||
所有API响应都是JSON格式，包含以下顶层字段：
|
||
- `status` - 状态标识 (`success` 或 `error`)
|
||
- `message` - 状态消息
|
||
- `data` - 响应数据（成功时）或 `errorDetails` - 错误详情（失败时）
|
||
|
||
---
|
||
|
||
## API 接口列表
|
||
|
||
### 1. 批量解析标签数据
|
||
|
||
#### 接口信息
|
||
- **路由**: `/batch-parse`
|
||
- **方法**: `POST`
|
||
- **URL**: `/api/label/batch-parse`
|
||
- **描述**: 批量解析订单标签数据，支持多种模式。可用于补充解析已有的订单标签。
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必需 | 说明 |
|
||
|--------|------|------|------|
|
||
| Mode | string | 是 | 解析模式，必须是以下值之一：`all`、`range`、`customer`、`single` |
|
||
| WaybillNumber | string | 否 | 中性面单单号。在 `single` 模式下必需 |
|
||
| CustomerId | int | 否 | 客户ID。在 `customer` 模式下必需 |
|
||
| StartDate | datetime | 否 | 开始日期。在 `range` 模式下必需，格式：`YYYY-MM-DD` 或 ISO 8601 |
|
||
| EndDate | datetime | 否 | 结束日期。在 `range` 模式下必需，格式：`YYYY-MM-DD` 或 ISO 8601 |
|
||
| Limit | int | 否 | 限制返回的最大数量。默认值：1000 |
|
||
|
||
#### 模式说明
|
||
|
||
| 模式 | 说明 | 必需参数 |
|
||
|------|------|---------|
|
||
| `all` | 处理所有有标签的订单 | 无 |
|
||
| `range` | 按时间范围处理 | StartDate, EndDate |
|
||
| `customer` | 按指定客户处理 | CustomerId |
|
||
| `single` | 处理单条订单 | WaybillNumber |
|
||
|
||
#### 请求示例
|
||
|
||
**模式1: 处理所有有标签的订单**
|
||
```json
|
||
{
|
||
"mode": "all",
|
||
"limit": 500
|
||
}
|
||
```
|
||
|
||
**模式2: 按时间范围处理**
|
||
```json
|
||
{
|
||
"mode": "range",
|
||
"startDate": "2024-01-01",
|
||
"endDate": "2024-01-31",
|
||
"limit": 1000
|
||
}
|
||
```
|
||
|
||
**模式3: 按客户处理**
|
||
```json
|
||
{
|
||
"mode": "customer",
|
||
"customerId": 123,
|
||
"limit": 500
|
||
}
|
||
```
|
||
|
||
**模式4: 处理单条订单**
|
||
```json
|
||
{
|
||
"mode": "single",
|
||
"waybillNumber": "1Z999AA10123456784"
|
||
}
|
||
```
|
||
|
||
#### 成功响应示例
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "批量解析完成",
|
||
"data": {
|
||
"totalProcessed": 100,
|
||
"successCount": 98,
|
||
"errorCount": 2,
|
||
"mode": "all"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 失败响应示例
|
||
|
||
**参数验证失败**
|
||
```json
|
||
{
|
||
"status": "error",
|
||
"message": "请提供有效的请求参数"
|
||
}
|
||
```
|
||
|
||
**模式参数缺失**
|
||
```json
|
||
{
|
||
"status": "error",
|
||
"message": "时间范围模式需要 StartDate 和 EndDate 参数"
|
||
}
|
||
```
|
||
|
||
或
|
||
|
||
```json
|
||
{
|
||
"status": "error",
|
||
"message": "客户模式需要 CustomerId 参数"
|
||
}
|
||
```
|
||
|
||
或
|
||
|
||
```json
|
||
{
|
||
"status": "error",
|
||
"message": "单条模式需要 WaybillNumber 参数"
|
||
}
|
||
```
|
||
|
||
**无效的处理模式**
|
||
```json
|
||
{
|
||
"status": "error",
|
||
"message": "无效的处理模式，请使用: all, range, customer, single"
|
||
}
|
||
```
|
||
|
||
**系统异常**
|
||
```json
|
||
{
|
||
"status": "error",
|
||
"message": "批量解析失败",
|
||
"errorDetails": "[具体错误信息]"
|
||
}
|
||
```
|
||
|
||
#### 响应字段说明
|
||
|
||
**成功响应 (data 字段)**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| totalProcessed | int | 处理的总订单数量 |
|
||
| successCount | int | 成功处理的订单数量 |
|
||
| errorCount | int | 处理失败的订单数量 |
|
||
| mode | string | 使用的解析模式 |
|
||
|
||
#### HTTP状态码
|
||
- `200` - 请求成功处理（即使业务逻辑返回error状态也是200）
|
||
- `400` - 请求参数错误
|
||
|
||
---
|
||
|
||
### 2. 查看缓存统计信息
|
||
|
||
#### 接口信息
|
||
- **路由**: `/cache-statistics`
|
||
- **方法**: `GET`
|
||
- **URL**: `/api/label/cache-statistics`
|
||
- **描述**: 获取PDF标签缓存的统计信息，包括总数、成功数、失败数、性能指标等。
|
||
|
||
#### 请求参数
|
||
无
|
||
|
||
#### 成功响应示例
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "缓存统计信息",
|
||
"data": {
|
||
"totalRecords": 5000,
|
||
"successRecords": 4950,
|
||
"failedRecords": 30,
|
||
"invalidRecords": 15,
|
||
"pendingRecords": 5,
|
||
"withBarcodeRecords": 4890,
|
||
"averageParseDurationMs": 245.5,
|
||
"maxParseDurationMs": 1200,
|
||
"minParseDurationMs": 50
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 失败响应示例
|
||
```json
|
||
{
|
||
"status": "error",
|
||
"message": "获取统计信息失败",
|
||
"errorDetails": "[具体错误信息]"
|
||
}
|
||
```
|
||
|
||
#### 响应字段说明
|
||
|
||
**data 字段**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| totalRecords | int | 缓存表中的总记录数 |
|
||
| successRecords | int | 处理成功的记录数（Status=1） |
|
||
| failedRecords | int | 处理失败的记录数（Status=2） |
|
||
| invalidRecords | int | 无效的记录数（Status=3） |
|
||
| pendingRecords | int | 待处理的记录数（Status=0） |
|
||
| withBarcodeRecords | int | 成功识别条码的记录数 |
|
||
| averageParseDurationMs | double | 平均PDF解析耗时（毫秒） |
|
||
| maxParseDurationMs | int | 最大PDF解析耗时（毫秒） |
|
||
| minParseDurationMs | int | 最小PDF解析耗时（毫秒） |
|
||
|
||
#### 缓存记录状态说明
|
||
|
||
| 状态值 | 说明 |
|
||
|--------|------|
|
||
| 0 | 待处理 - 刚创建或待重试的记录 |
|
||
| 1 | 成功 - PDF已缓存且处理成功 |
|
||
| 2 | 失败 - 处理失败，超过重试次数 |
|
||
| 3 | 无效 - 缓存已失效或过期 |
|
||
|
||
#### HTTP状态码
|
||
- `200` - 请求成功处理
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### BatchParseLabelRequest
|
||
批量解析请求模型
|
||
|
||
```typescript
|
||
{
|
||
mode: string; // 必需：all | range | customer | single
|
||
waybillNumber?: string; // 可选：单条模式下的面单号
|
||
customerId?: number; // 可选：客户ID
|
||
startDate?: string; // 可选：开始日期 (YYYY-MM-DD)
|
||
endDate?: string; // 可选：结束日期 (YYYY-MM-DD)
|
||
limit?: number; // 可选：最大数量，默认1000
|
||
}
|
||
```
|
||
|
||
### CacheStatistics
|
||
缓存统计数据模型
|
||
|
||
```typescript
|
||
{
|
||
totalRecords: number; // 总记录数
|
||
successRecords: number; // 成功记录数
|
||
failedRecords: number; // 失败记录数
|
||
invalidRecords: number; // 无效记录数
|
||
pendingRecords: number; // 待处理记录数
|
||
withBarcodeRecords: number; // 包含条码的记录数
|
||
averageParseDurationMs: number; // 平均解析时间（毫秒）
|
||
maxParseDurationMs: number; // 最大解析时间（毫秒）
|
||
minParseDurationMs: number; // 最小解析时间（毫秒）
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### JavaScript/TypeScript
|
||
|
||
#### 使用Fetch API
|
||
|
||
```javascript
|
||
// 1. 批量解析 - 处理所有有标签的订单
|
||
const batchParseAllOrders = async () => {
|
||
const response = await fetch('http://localhost:8080/api/label/batch-parse', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
},
|
||
body: JSON.stringify({
|
||
mode: 'all',
|
||
limit: 500
|
||
})
|
||
});
|
||
const data = await response.json();
|
||
console.log(data);
|
||
};
|
||
|
||
// 2. 批量解析 - 按时间范围
|
||
const batchParseByDateRange = async () => {
|
||
const response = await fetch('http://localhost:8080/api/label/batch-parse', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
},
|
||
body: JSON.stringify({
|
||
mode: 'range',
|
||
startDate: '2024-01-01',
|
||
endDate: '2024-01-31',
|
||
limit: 1000
|
||
})
|
||
});
|
||
const data = await response.json();
|
||
console.log(data);
|
||
};
|
||
|
||
// 3. 批量解析 - 按客户
|
||
const batchParseByCustomer = async () => {
|
||
const response = await fetch('http://localhost:8080/api/label/batch-parse', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
},
|
||
body: JSON.stringify({
|
||
mode: 'customer',
|
||
customerId: 123,
|
||
limit: 500
|
||
})
|
||
});
|
||
const data = await response.json();
|
||
console.log(data);
|
||
};
|
||
|
||
// 4. 批量解析 - 单条订单
|
||
const batchParseSingle = async () => {
|
||
const response = await fetch('http://localhost:8080/api/label/batch-parse', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
},
|
||
body: JSON.stringify({
|
||
mode: 'single',
|
||
waybillNumber: '1Z999AA10123456784'
|
||
})
|
||
});
|
||
const data = await response.json();
|
||
console.log(data);
|
||
};
|
||
|
||
// 5. 获取缓存统计
|
||
const getCacheStatistics = async () => {
|
||
const response = await fetch('http://localhost:8080/api/label/cache-statistics');
|
||
const data = await response.json();
|
||
console.log(data);
|
||
};
|
||
```
|
||
|
||
#### 使用Axios
|
||
|
||
```javascript
|
||
import axios from 'axios';
|
||
|
||
const baseURL = 'http://localhost:8080/api/label';
|
||
|
||
// 1. 批量解析 - 处理所有有标签的订单
|
||
const batchParseAll = async () => {
|
||
try {
|
||
const response = await axios.post(`${baseURL}/batch-parse`, {
|
||
mode: 'all',
|
||
limit: 500
|
||
});
|
||
console.log(response.data);
|
||
} catch (error) {
|
||
console.error('Error:', error);
|
||
}
|
||
};
|
||
|
||
// 2. 获取缓存统计
|
||
const getStatistics = async () => {
|
||
try {
|
||
const response = await axios.get(`${baseURL}/cache-statistics`);
|
||
console.log(response.data);
|
||
} catch (error) {
|
||
console.error('Error:', error);
|
||
}
|
||
};
|
||
```
|
||
|
||
### Python
|
||
|
||
```python
|
||
import requests
|
||
import json
|
||
from datetime import datetime
|
||
|
||
BASE_URL = "http://localhost:8080/api/label"
|
||
|
||
# 1. 批量解析 - 处理所有有标签的订单
|
||
def batch_parse_all():
|
||
payload = {
|
||
"mode": "all",
|
||
"limit": 500
|
||
}
|
||
response = requests.post(f"{BASE_URL}/batch-parse", json=payload)
|
||
print(json.dumps(response.json(), indent=2))
|
||
|
||
# 2. 批量解析 - 按时间范围
|
||
def batch_parse_by_date_range():
|
||
payload = {
|
||
"mode": "range",
|
||
"startDate": "2024-01-01",
|
||
"endDate": "2024-01-31",
|
||
"limit": 1000
|
||
}
|
||
response = requests.post(f"{BASE_URL}/batch-parse", json=payload)
|
||
print(json.dumps(response.json(), indent=2))
|
||
|
||
# 3. 批量解析 - 按客户
|
||
def batch_parse_by_customer():
|
||
payload = {
|
||
"mode": "customer",
|
||
"customerId": 123,
|
||
"limit": 500
|
||
}
|
||
response = requests.post(f"{BASE_URL}/batch-parse", json=payload)
|
||
print(json.dumps(response.json(), indent=2))
|
||
|
||
# 4. 批量解析 - 单条订单
|
||
def batch_parse_single():
|
||
payload = {
|
||
"mode": "single",
|
||
"waybillNumber": "1Z999AA10123456784"
|
||
}
|
||
response = requests.post(f"{BASE_URL}/batch-parse", json=payload)
|
||
print(json.dumps(response.json(), indent=2))
|
||
|
||
# 5. 获取缓存统计
|
||
def get_cache_statistics():
|
||
response = requests.get(f"{BASE_URL}/cache-statistics")
|
||
print(json.dumps(response.json(), indent=2))
|
||
|
||
# 使用示例
|
||
if __name__ == "__main__":
|
||
# batch_parse_all()
|
||
# batch_parse_by_date_range()
|
||
# batch_parse_by_customer()
|
||
batch_parse_single()
|
||
# get_cache_statistics()
|
||
```
|
||
|
||
---
|
||
|
||
## 错误处理
|
||
|
||
### 常见错误及解决方案
|
||
|
||
| 错误信息 | 原因 | 解决方案 |
|
||
|---------|------|---------|
|
||
| 请提供有效的请求参数 | 请求体为空或Mode字段缺失 | 检查请求JSON格式，确保Mode字段存在 |
|
||
| 时间范围模式需要 StartDate 和 EndDate 参数 | range模式缺少日期参数 | 添加StartDate和EndDate参数 |
|
||
| 客户模式需要 CustomerId 参数 | customer模式缺少客户ID | 添加CustomerId参数 |
|
||
| 单条模式需要 WaybillNumber 参数 | single模式缺少面单号 | 添加WaybillNumber参数 |
|
||
| 无效的处理模式 | Mode值不是允许的四种之一 | 使用 all、range、customer、single 之一 |
|
||
| 批量解析失败 | 服务器内部错误 | 查看errorDetails字段，检查服务器日志 |
|
||
| 获取统计信息失败 | 服务器内部错误 | 查看errorDetails字段，检查服务器日志 |
|
||
|
||
---
|
||
|
||
## 性能建议
|
||
|
||
1. **批量大小**: 建议Limit不要超过5000，避免单次请求处理过多数据
|
||
2. **日期范围**: 时间范围模式时，建议不要跨越太长的时间跨度（如超过90天）
|
||
3. **请求频率**: 避免频繁发送相同的请求，建议间隔至少5秒
|
||
4. **缓存更新**: 定时任务会自动处理待处理订单，无需频繁手动调用
|
||
|
||
---
|
||
|
||
## FAQ
|
||
|
||
**Q: 批量解析后多久能看到结果？**
|
||
A: 批量解析是异步处理的。解析请求返回后，系统会在后台处理。通常需要几秒到几分钟，取决于数据量和系统负载。
|
||
|
||
**Q: 可以同时发送多个批量解析请求吗？**
|
||
A: 可以，但建议不要同时发送超过10个请求，避免系统过载。
|
||
|
||
**Q: 如何判断某个订单是否已被缓存？**
|
||
A: 调用cache-statistics接口，查看successRecords字段。或者查询订单表中对应订单的缓存状态。
|
||
|
||
**Q: 缓存数据会被清理吗？**
|
||
A: 缓存数据会根据业务规则进行清理。无效的缓存会被标记为Status=3，并可能在定期维护时删除。
|
||
|
||
**Q: 如何处理解析失败的订单？**
|
||
A: 系统会自动重试失败的订单（最多3次）。重试都失败后会标记为Status=2。可以通过single模式重新尝试解析单个订单。
|
||
|
||
---
|
||
|
||
## 更新历史
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|------|------|------|
|
||
| 1.0 | 2024-01-01 | 初版发布，包含batch-parse和cache-statistics接口 |
|
||
|
||
---
|
||
|
||
## 联系方式
|
||
|
||
如有任何问题或建议，请联系技术支持团队。
|