测试报文生成接口文档

接口概述

该接口用于生成符合TCP位置上报协议规范的十六进制测试报文，支持自定义终端编号、设备类型、定位数据等参数，生成的报文可用于调试终端设备上报逻辑或服务端解析逻辑，确保报文格式符合协议要求。

接口信息

• 接口地址：wuhan.gishub.com.cn:4100/position-server/test/packet/generate
• 请求方法：POST
• 请求格式：JSON（包含报文生成所需参数）
• 响应格式：JSON（包含生成的十六进制报文及相关信息）
• 接口标签：测试报文生成接口
• 功能说明：根据输入参数生成符合协议规范的位置上报报文，自动处理BCD编码、字节序转换、转义及帧头帧尾拼接。

请求参数说明（TestPacketParam）

一级参数	二级参数	类型	是否必传	描述	默认值示例
terminalId	-	String	否	终端编号（数字字符串，最长19位，不足自动补位）	"123456789"
deviceType	-	String	否	设备类型编码（数字字符串，固定19位，不足自动补位）	"888888"
appMd5	-	String	否	appID与秘钥的MD5编码（最长32位，超长截断，不足补0）	"001##password1234567890abcdef"
locationData	year	int	否	年份（完整年份，如2024）	2024
	month	int	否	月份（1-12）	10
	day	int	否	日期（1-31）	05
	hour	int	否	小时（0-23）	15
	minute	int	否	分钟（0-59）	30
	second	int	否	秒（0-59）	45
	coordinateType	int	否	坐标类型：1=BD（北斗），2=GPS，3=NETWORK（网络定位）	2（GPS）
	latLonFlag	int	否	经纬度方向标志： - D0（bit0）：1=北纬，0=南纬 - D1（bit1）：1=东经，0=西经	0x03（北纬+东经）
	longitude	long	否	经度值（×10^7，如116.3972°→1163972000）	1163972000
	latitude	long	否	纬度值（×10^7，如39.9075°→399075000）	399075000
	speed	int	否	速度（km/h，0-65535）	60
	direction	int	否	方向角（度，0-360）	90
	altitude	int	否	高度（米，-32768-32767）	50

响应参数说明

成功响应（success: true）

字段名	类型	描述	示例值
success	Boolean	报文生成是否成功	true
hexPacket	String	生成的十六进制报文（不含空格）	FF0000006502A1A1A1...FF
packetLength	int	报文总长度（字节，包含帧头和帧尾）	101
description	String	生成结果描述	生成符合协议规范的测试报文

失败响应（success: false）

字段名	类型	描述	示例值
success	Boolean	报文生成是否成功	false
message	String	生成失败的原因描述	月份必须在1-12范围内

报文生成逻辑说明

1. 参数处理：
   • 终端编号和设备类型转换为19字节非压缩BCD编码，右对齐，不足位前补0xA。
   • appMD5取前32位，不足32字节补0。
   • 定位数据按协议格式转换为22字节（含日期、时间、坐标等信息）。
2. 包长计算：总长度 = 主体内容长度 + 帧头（1字节） + 帧尾（1字节），并以4字节小端序存储。
3. 转义处理：对主体内容中的0xFF转义为0xFE00，0xFE转义为0xFE01。
4. 帧结构拼接：最终报文 = 帧头（0xFF） + 转义后主体 + 帧尾（0xFF）。

调用示例

请求示例（JSON）

{
  "terminalId": "987654321",
  "deviceType": "123456",
  "appMd5": "abcdef0123456789abcdef0123456789",
  "locationData": {
    "year": 2024,
    "month": 12,
    "day": 31,
    "hour": 23,
    "minute": 59,
    "second": 59,
    "coordinateType": 3,
    "longitude": 1164000000,
    "latitude": 399100000,
    "speed": 80,
    "direction": 180,
    "altitude": 100
  }
}

响应示例

{
  "success": true,
  "hexPacket": "FF0000006702A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1A1987654321A1A1A1A1A1A1A1A1A1A1A123456ABCDEF0123456789ABCDEF0123456789180C1F173B3B0303000000460000007C5000B40064FF",
  "packetLength": 103,
  "description": "生成符合协议规范的测试报文"
}

注意事项

1. 终端编号和设备类型仅支持数字字符，非数字字符会被过滤。
2. 定位数据中的经纬度、速度等多字节字段会自动转换为小端序存储，无需手动处理。
3. 生成的hexPacket为纯大写十六进制字符串，可直接用于终端上报测试或服务端解析测试。
4. 若参数超出有效范围（如月份=13），接口会返回失败并提示具体错误原因。
5. 默认参数已符合协议规范，若无需自定义，可直接发送空JSON请求使用默认值生成报文。