jennisonzhang/LabelChange-server

Fork 0

Files

Im-Jenisson b2a9b7d3c2 上传源代码版本

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

13 KiB

Raw Permalink Blame History

面单标签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: 处理所有有标签的订单

{
  "mode": "all",
  "limit": 500
}

模式2: 按时间范围处理

{
  "mode": "range",
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "limit": 1000
}

模式3: 按客户处理

{
  "mode": "customer",
  "customerId": 123,
  "limit": 500
}

模式4: 处理单条订单

{
  "mode": "single",
  "waybillNumber": "1Z999AA10123456784"
}

成功响应示例

{
  "status": "success",
  "message": "批量解析完成",
  "data": {
    "totalProcessed": 100,
    "successCount": 98,
    "errorCount": 2,
    "mode": "all"
  }
}

失败响应示例

参数验证失败

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

模式参数缺失

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

或

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

或

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

无效的处理模式

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

系统异常

{
  "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标签缓存的统计信息，包括总数、成功数、失败数、性能指标等。

请求参数

无

成功响应示例

{
  "status": "success",
  "message": "缓存统计信息",
  "data": {
    "totalRecords": 5000,
    "successRecords": 4950,
    "failedRecords": 30,
    "invalidRecords": 15,
    "pendingRecords": 5,
    "withBarcodeRecords": 4890,
    "averageParseDurationMs": 245.5,
    "maxParseDurationMs": 1200,
    "minParseDurationMs": 50
  }
}

失败响应示例

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

批量解析请求模型

{
  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

缓存统计数据模型

{
  totalRecords: number;              // 总记录数
  successRecords: number;            // 成功记录数
  failedRecords: number;             // 失败记录数
  invalidRecords: number;            // 无效记录数
  pendingRecords: number;            // 待处理记录数
  withBarcodeRecords: number;        // 包含条码的记录数
  averageParseDurationMs: number;    // 平均解析时间（毫秒）
  maxParseDurationMs: number;        // 最大解析时间（毫秒）
  minParseDurationMs: number;        // 最小解析时间（毫秒）
}

使用示例

JavaScript/TypeScript

使用Fetch API

// 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

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

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字段，检查服务器日志

性能建议

批量大小: 建议Limit不要超过5000，避免单次请求处理过多数据
日期范围: 时间范围模式时，建议不要跨越太长的时间跨度（如超过90天）
请求频率: 避免频繁发送相同的请求，建议间隔至少5秒
缓存更新: 定时任务会自动处理待处理订单，无需频繁手动调用

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接口

联系方式

如有任何问题或建议，请联系技术支持团队。

13 KiB Raw Permalink Blame History Unescape Escape

面单标签PDF缓存系统 API 文档

概述

基础信息

API基地址

支持的HTTP方法

响应格式

API 接口列表

1. 批量解析标签数据

接口信息

请求参数

模式说明

请求示例

成功响应示例

失败响应示例

响应字段说明

HTTP状态码

2. 查看缓存统计信息

接口信息

请求参数

成功响应示例

失败响应示例

响应字段说明

缓存记录状态说明

HTTP状态码

数据模型

BatchParseLabelRequest

CacheStatistics

使用示例

JavaScript/TypeScript

使用Fetch API

使用Axios

Python

错误处理

常见错误及解决方案

性能建议

FAQ

更新历史

联系方式

13 KiB

Raw Permalink Blame History