2026-04-15 15:25:38 +08:00

100 KiB

Raw Blame History

oms 表结构与接口设计文档

OMS 系统说明

OMS（Order Management System，订单管理系统）作为独立服务运行和admin权限管理服务合并，面向跨境物流/仓储业务场景，提供订单、渠道、操作、客户四大核心模块，支撑从客户注册、充值、下单、定价、支付到货物入库出库的全流程管理。

核心模块

模块	说明
订单	订单全生命周期管理，包括创建、预报、支付、发货、跟踪等
渠道	销售产品与物流渠道的配置、定价及买价/卖价计算
操作	入库、出库、打印等仓储操作
客户	客户注册、认证、账户余额、额度及权限管理

1.2 表结构设计规范

表的字段命名规范

规范	说明	示例
驼峰命名	字段名开头大写+单词驼峰	`ServiceProviderId`
单数名词	表名用单数，表示实体	`customer` 而非 `customers`
业务前缀	表名按业务模块加前缀	`t_order`、`t_customer`

必备字段（所有表）

字段名	字段类型	说明
Id	BIGINT	主键，自增，步长 1
IsDeleted	TINYINT	软删除：0-否，1-是，默认 0
CreateUserId	INT	创建人
CreateTime	DATETIME	创建时间
UpdateUserId	INT	更新人
UpdateTime	DATETIME	更新时间

字段命名规范

规范	说明	示例
布尔字段	用 `IsXxx` 或 `HasXxx`	`IsDeleted`、`IsActive`
外键字段	`关联表名Id` 或 `XxxId`	`CustomerId`、`WarehouseId`
时间字段	`XxxTime` 或 `XxxAt`	`CreateTime`、`PayTime`
禁用保留字	不用 desc、range、match 等	用 `Description` 替代 `Desc`

数据类型规范

类型	说明
主键	BIGINT，单表自增
金额/重量	DECIMAL，禁止 float/double
字符串	varchar 长度 ≤ 5000，超出用 TEXT
枚举	小数据量用 TINYINT，可读性要求高用 VARCHAR
状态标志	TINYINT

二、订单模块

1.1 核心需求说明

我的订单：支持订单全流程管理，包括分页查询、详情查看、支付、预报、拦截/取消拦截、删除、打印、导出；订单状态覆盖草稿→已预报→已收货→待支付→待发货→运输中→派送成功/失败等全生命周期。
我要查价：根据目的国、运输方式、重量尺寸、货物类型等条件查价，返回可选渠道及费用明细。
我要下单：支持下载下单模板、上传 Excel 批量下单、查看任务进度与详情；模板分为标准模板与自定义模板。

1.2 表结构设计

命名约定：表名按业务模块加 t_ 前缀；字段名驼峰命名（开头大写+单词驼峰）。

订单表 `t_order`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
ServiceNo	VARCHAR	64	-	是	运单号
ClientNo	VARCHAR	64	-	否	客户单号
TrackNo	VARCHAR	64	-	否	跟踪号
ProductCode	VARCHAR	128	-	否	产品code
ChannelCode	VARCHAR	128	-	否	渠道code
ConsigneeCountry	VARCHAR	8	-	否	国家二字码
CargoAttribute	VARCHAR	32	-	否	货物属性：general-普货，electronics-3c&带电，sensitive-敏感货
OrderStatus	VARCHAR	32	-	是	订单状态
WarehouseId	BIGINT	-	外键	否	仓库ID
CustomerId	BIGINT	-	外键	否	客户ID
SenderId	BIGINT	-	外键	否	发件人ID → t_order_sender
RecipientId	BIGINT	-	外键	否	收件人ID → t_order_recipient
DeclarationId	BIGINT	-	外键	否	申报信息ID → t_order_declaration
ReceiveTime	DATETIME	-	-	否	收货时间
ShipTime	DATETIME	-	-	否	发货时间
PayTime	DATETIME	-	-	否	支付时间
SignTime	DATETIME	-	-	否	签收时间
IsCod	TINYINT	-	-	否	是否COD：0-否，1-是
CodCurrency	VARCHAR	16	-	否	COD币种
CodSum	DECIMAL	18,4	-	否	COD金额
IsIntercept	TINYINT	-	-	否	是否拦截：0-否，1-是
IsRemote	TINYINT	-	-	否	是否偏远：0-否，1-是
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

OrderStatus 枚举：draft, predeclared, received, pendingPayment, pendingShip, pendingOnline, shipping, deliverySuccess, deliveryFailed, problematic, deleted, claimed

CargoAttribute 枚举：general-普货，electronics-3c&带电，sensitive-敏感货

下单模板表 `t_order_template`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
Name	VARCHAR	64	-	是	模板名称
Type	VARCHAR	16	-	是	standard/custom
TemplateKey	VARCHAR	64	-	否	模板标识
CustomerId	BIGINT	-	外键	否	客户ID(自定义模板)
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

下单任务表 `t_order_task`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
TaskName	VARCHAR	128	-	是	任务名称
Quantity	INT	-	-	否	数量
Status	VARCHAR	16	-	是	处理中/已完成/待处理
TemplateId	BIGINT	-	外键	否	模板ID
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间
CustomerId	BIGINT	-	外键	否	客户ID

订单发件人表 `t_order_sender`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
OrderId	BIGINT	-	外键	是	订单ID
SenderName	VARCHAR	50	-	否	姓名
Company	VARCHAR	255	-	否	公司
Country	INT	-	-	否	国家
Province	VARCHAR	50	-	否	州省
City	VARCHAR	50	-	否	城市
ZipCode	VARCHAR	50	-	否	邮编
StreetAddress1	VARCHAR	500	-	否	地址1
StreetAddress2	VARCHAR	500	-	否	地址2
StreetAddress3	VARCHAR	500	-	否	地址3
HouseNumber	VARCHAR	50	-	否	门牌号
Phone	VARCHAR	50	-	否	手机
TelePhone	VARCHAR	50	-	否	电话
Email	VARCHAR	60	-	否	邮箱
IsDefault	TINYINT	-	-	否	是否默认：0-否，1-是
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

订单收件人表 `t_order_recipient`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
OrderId	BIGINT	-	外键	是	订单ID
RecipientsName	VARCHAR	30	-	否	收件人名称
CompanyName	VARCHAR	60	-	否	收件人公司名称
Country	INT	-	-	否	国家
Phone	VARCHAR	20	-	否	收件人手机
TelePhone	VARCHAR	20	-	否	收件人电话
ZipCode	VARCHAR	15	-	否	收件人邮编
Province	VARCHAR	25	-	否	收件人省/州
City	VARCHAR	25	-	否	收件人城市
StreetNumber	VARCHAR	20	-	否	收件人门牌号
StreetAddress1	VARCHAR	255	-	否	收件人地址1
StreetAddress2	VARCHAR	255	-	否	收件人地址2
StreetAddress3	VARCHAR	255	-	否	收件人地址3
Email	VARCHAR	60	-	否	收件人邮箱
TaxType	INT	-	-	否	税号类型
TaxNo	VARCHAR	35	-	否	税号
CertificateType	INT	-	-	否	证件类型
CertificateNo	VARCHAR	30	-	否	证件号码
Eori	VARCHAR	255	-	否	EORI
Vat	VARCHAR	255	-	否	Vat
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

订单申报信息表 `t_order_declaration`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
OrderId	BIGINT	-	外键	是	订单ID
CnName	VARCHAR	500	-	否	品名--中
EnName	VARCHAR	500	-	否	品名--英
Sku	VARCHAR	255	-	否	SKU
Unit	VARCHAR	5	-	否	单位
UnitPrice	DECIMAL	10,2	-	否	单价
UnitWeight	DECIMAL	11,3	-	否	单重
Quantity	INT	-	-	否	数量
Amount	DECIMAL	11,2	-	否	总金额
Weight	DECIMAL	11,3	-	否	总重量
HsCode	VARCHAR	50	-	否	HsCode
SkuImage	VARCHAR	255	-	否	图片
Category	VARCHAR	20	-	否	类别
Brand	VARCHAR	50	-	否	品牌
BrandType	VARCHAR	50	-	否	品牌类型
IsMagnetic	BIT	-	-	否	是否带磁带电
Distribution	VARCHAR	255	-	否	配货信息
Material	VARCHAR	50	-	否	材质
EnMaterial	VARCHAR	64	-	否	英文材质
Purpose	VARCHAR	50	-	否	用途
Attributes	VARCHAR	50	-	否	属性
OriginCountry	VARCHAR	50	-	否	原产国
SalesLink	VARCHAR	255	-	否	销售链接
Model	VARCHAR	64	-	否	型号
Specifications	VARCHAR	50	-	否	规格
Comment	VARCHAR	500	-	否	备注
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

订单件重尺表 `t_order_weight`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
OrderId	BIGINT	-	外键	是	订单ID
Type	VARCHAR	16	-	是	类型：forecast/receive/ship/downstream
Length	DECIMAL	10,2	-	否	长(cm)
Width	DECIMAL	10,2	-	否	宽(cm)
Height	DECIMAL	10,2	-	否	高(cm)
ActualWeight	DECIMAL	10,3	-	否	实重(kg)
VolumetricWeight	DECIMAL	10,3	-	否	体积重(kg)
ChargeableWeight	DECIMAL	10,3	-	否	计费重(kg)
Cubic	DECIMAL	12,6	-	否	立方(m³)
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

Type 枚举：forecast(预报)、receive(收货)、ship(发货)、downstream(下游)

订单费用表 `t_order_fee`（子表，关联 t_order）

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
OrderId	BIGINT	-	外键	是	订单ID
Type	VARCHAR	16	-	是	类型：receivable(应收)/payable(应付)
CostItem	VARCHAR	64	-	是	费用项
Amount	DECIMAL	18,4	-	是	金额
Currency	VARCHAR	16	-	是	币种：RMB/USD/EUR
DownstreamProvider	VARCHAR	128	-	否	下游服务商
PriceNo	VARCHAR	64	-	否	价格编号
PriceEffectiveTime	DATETIME	-	-	否	价格编号生效时间
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

Type 枚举：receivable(应收)、payable(应付)

1.3 核心接口设计

我的订单

接口名称	请求方式	请求路径	说明
分页查询订单列表	POST	/order/list	支持 status、keyword、createTimeStart/End 筛选
订单详情	GET	/order/detail	根据订单ID获取详情
支付	POST	/order/pay	订单支付
预报	POST	/order/pre-declare	订单预报
拦截	POST	/order/intercept	订单拦截
取消拦截	POST	/order/cancel-intercept	取消订单拦截
删除	POST	/order/delete	删除订单
打印	POST	/order/print	打印订单
导出	POST	/order/export	导出订单

请求 /order/list（POST，分页参数放 Body）

{
  "page": 1, // 页码，从1开始
  "pageSize": 20, // 每页条数
  "status": "all|draft|predeclared|received|...", // 订单状态筛选
  "keyword": "", // 关键词（运单号/客户单号/跟踪号）
  "createTimeStart": "", // 创建时间起
  "createTimeEnd": "" // 创建时间止
}

响应（用于 order/myOrders 列表及订单详情抽屉，字段与 parcel/create 对应，创建时传啥返回啥 + weightList）

{
  "items": [
    {
      "id": 1,
      "clientNo": "CUST...",
      "trackNo": "TRK...",
      "serviceNo": "LP...",
      "productCode": "US_AIR",
      "channelCode": "CH001",
      "cargoAttribute": "general",
      "warehouseId": 1,
      "warehouse": "深圳仓",
      "customerId": 1,
      "isCod": false,
      "codCurrency": "",
      "codSum": "",
      "orderStatus": "待支付",
      "status": "pendingPayment",
      "receiveTime": "",
      "shipTime": "",
      "payTime": "",
      "signTime": "",
      "isIntercept": false,
      "isRemote": false,
      "createTime": "2024-01-01 12:00:00",
      "createBy": "",
      "updateTime": "",
      "updateBy": "",
      "sender": {
        "senderName": "发件人",
        "company": "示例公司",
        "phone": "13800138000",
        "telePhone": "",
        "email": "sender@example.com",
        "countryCode": 0,
        "province": "广东省",
        "city": "深圳市",
        "zipCode": "518000",
        "streetAddress1": "示例地址1",
        "streetAddress2": "",
        "streetAddress3": "",
        "houseNumber": ""
      },
      "receiver": {
        "recipientsName": "收件人1",
        "companyName": "",
        "phone": "13800138000",
        "telePhone": "",
        "email": "",
        "countryCode": 0,
        "province": "California",
        "city": "Los Angeles",
        "streetNumber": "",
        "streetAddress1": "123 Main St",
        "streetAddress2": "",
        "streetAddress3": "",
        "zipCode": "90001",
        "taxType": 0,
        "taxNo": "",
        "certificateType": 0,
        "certificateNo": "",
        "eori": "",
        "vat": ""
      },
      "items": [
        {
          "cnName": "示例商品",
          "enName": "Sample Product",
          "sku": "SKU001",
          "unit": "件",
          "unitPrice": 10,
          "unitWeight": 0.5,
          "quantity": 1,
          "amount": 10,
          "weight": 0.5,
          "hsCode": "1234567890",
          "skuImage": "",
          "category": "普货",
          "brand": "示例品牌",
          "brandType": "自有",
          "isMagnetic": false,
          "distribution": "",
          "material": "塑料",
          "enMaterial": "Plastic",
          "purpose": "日用",
          "attributes": "",
          "originCountry": "中国",
          "salesLink": "",
          "model": "",
          "specifications": "",
          "comment": ""
        }
      ],
      "weightList": [
        {
          "type": "forecast",
          "length": "20",
          "width": "15",
          "height": "10",
          "actualWeight": "2.50",
          "volumetricWeight": "2.00",
          "chargeableWeight": "2.50",
          "cubic": "0.003"
        }
      ]
    }
  ],
  "total": 100
}

请求 /order/detail（GET，Query 参数）

?id=1

响应

{
  "id": 1,
  "clientNo": "CUST...",
  "trackNo": "TRK...",
  "serviceNo": "LP...",
  "productCode": "US_AIR",
  "channelCode": "CH001",
  "cargoAttribute": "general",
  "warehouseId": 1,
  "warehouse": "深圳仓",
  "customerId": 1,
  "sender": {},
  "receiver": {},
  "items": [],
  "weightList": []
}

data 结构与 list 单条 item 一致，含 sender、receiver、items、weightList。

请求 /order/pay（POST）

{
  "id": 1,
  "requestId": ""
}

requestId 幂等，可选。

响应

null

请求 /order/pre-declare（POST）

{
  "id": 1,
  "requestId": ""
}

响应

null

请求 /order/intercept（POST）

{
  "id": 1,
  "requestId": ""
}

响应

null

请求 /order/cancel-intercept（POST）

{
  "id": 1,
  "requestId": ""
}

响应

null

请求 /order/delete（POST）

{
  "id": 1,
  "requestId": ""
}

响应

null

请求 /order/print（POST）

{
  "id": 1,
  "requestId": ""
}

响应

{
  "printUrl": ""
}

请求 /order/export（POST）

{
  "status": "all|draft|...",
  "keyword": "",
  "createTimeStart": "",
  "createTimeEnd": ""
}

响应

{
  "downloadUrl": "",
  "expireAt": ""
}

我要查价

接口名称	请求方式	请求路径	说明
查价	POST	/order/price-check	根据目的国、重量尺寸等查价

请求 /order/price-check（POST）

{
  "destinationCountry": "US", // 目的国二字码
  "shippingMethod": "", // 运输方式
  "cargoWeight": "2", // 货物重量(kg)
  "length": "20", // 长(cm)
  "width": "15", // 宽(cm)
  "height": "10", // 高(cm)
  "cargoType": "普货", // 货物类型
  "destinationProvince": "", // 目的省州
  "postalCode": "" // 邮编
}

响应

{
  "items": [
    {
      "id": 1,
      "shippingMethod": "美国空运专线(普货)",
      "warehouse": "一代深圳仓",
      "deliveryTime": "3-7",
      "volumetricWeight": "2",
      "chargeableWeight": "2",
      "costFormula": "(62*2) +5+7",
      "freight": "62",
      "otherFees": "5",
      "totalCost": "136",
      "maxDeliveryDays": 7,
      "totalCostNum": 136
    }
  ]
}

我要下单

接口名称	请求方式	请求路径	说明
模板列表	GET	/order/template/list	获取下单模板列表
下载模板	GET	/order/template/download	下载 Excel 模板
上传下单	POST	/order/upload	multipart/form-data，file + templateId
任务进度列表	GET	/order/task/list	批量下单任务列表
任务详情	GET	/order/task/detail	任务详情
创建小包	POST	/order/parcel/create	创建小包订单

请求 /order/parcel/create（POST）

字段与 t_order、t_order_sender、t_order_recipient、t_order_declaration、t_order_weight 表对应，采用 camelCase。

{
  "clientNo": "string", // 客户单号 t_order.ClientNo
  "trackNo": "string", // 跟踪号 t_order.TrackNo
  "serviceNo": "string", // 服务商单号/运单号 t_order.ServiceNo
  "productCode": "string", // 产品代码 t_order.ProductCode
  "channelCode": "string", // 渠道代码 t_order.ChannelCode
  "cargoAttribute": "string", // 货物属性 t_order.CargoAttribute：general-普货，electronics-3c&带电，sensitive-敏感货
  "warehouseId": 0, // 仓库ID t_order.WarehouseId
  "customerId": 0, // 客户ID t_order.CustomerId
  "length": 3, // 长(cm) t_order_weight.Length
  "width": 3, // 宽(cm) t_order_weight.Width
  "height": 3, // 高(cm) t_order_weight.Height
  "actualWeight": 3, // 实重(kg) t_order_weight.ActualWeight
  "volumetricWeight": 3, // 体积重(kg) t_order_weight.VolumetricWeight
  "chargeableWeight": 3, // 计费重(kg) t_order_weight.ChargeableWeight
  "cubic": 0, // 立方(m³) t_order_weight.Cubic
  "isCod": false, // 是否COD
  "codCurrency": "string", // COD币种
  "codSum": "string", // COD金额
  "declaredCurrency": "string", // 申报币种
  "declaredSum": "string", // 申报金额
  "quantity": "string", // 包裹数量
  "receiver": { // 收件人 t_order_recipient
    "recipientsName": "string", // 收件人名称
    "companyName": "string", // 收件人公司名称
    "phone": "string", // 收件人手机
    "telePhone": "string", // 收件人电话
    "email": "string", // 收件人邮箱
    "countryCode": 0, // 国家
    "province": "string", // 收件人省/州
    "city": "string", // 收件人城市
    "streetNumber": "string", // 收件人门牌号
    "streetAddress1": "string", // 收件人地址1
    "streetAddress2": "string", // 收件人地址2
    "streetAddress3": "string", // 收件人地址3
    "zipCode": "string", // 收件人邮编
    "taxType": 0, // 税号类型
    "taxNo": "string", // 税号
    "certificateType": 0, // 证件类型
    "certificateNo": "string", // 证件号码
    "eori": "string", // EORI
    "vat": "string" // Vat
  },
  "sender": { // 发件人 t_order_sender
    "senderName": "string", // 发件人姓名
    "company": "string", // 发件人公司
    "phone": "string", // 发件人手机
    "telePhone": "string", // 发件人电话
    "email": "string", // 发件人邮箱
    "countryCode": 0, // 国家
    "province": "string", // 州省
    "city": "string", // 城市
    "zipCode": "string", // 邮编
    "streetAddress1": "string", // 地址1
    "streetAddress2": "string", // 地址2
    "streetAddress3": "string", // 地址3
    "houseNumber": "string" // 门牌号
  },
  "items": [ // 申报明细 t_order_declaration
    {
      "cnName": "string", // 品名-中
      "enName": "string", // 品名-英
      "sku": "string", // SKU
      "unit": "string", // 单位
      "unitPrice": 0, // 单价
      "unitWeight": 0, // 单重
      "quantity": 0, // 数量
      "amount": 0, // 总金额
      "weight": 0, // 总重量
      "imHsCode": "string", // 进口HsCode
      "exHsCode": "string", // 出口HsCode
      "skuImage": "string", // 图片
      "category": "string", // 类别
      "brand": "string", // 品牌
      "brandType": "string", // 品牌类型
      "isMagnetic": false, // 是否带磁带电
      "distribution": "string", // 配货信息
      "material": "string", // 材质
      "enMaterial": "string", // 英文材质
      "purpose": "string", // 用途
      "attributes": "string", // 属性
      "originCountry": "string", // 原产国
      "salesLink": "string", // 销售链接
      "model": "string", // 型号
      "specifications": "string", // 规格
      "comment": "string" // 备注
    }
  ]
}

响应

{
  "clientNo": "",
  "serviceNo": "",
  "trackNo": "",
  "labelUrl": ""
}

幂等时可选传 requestId。

请求 /order/template/list（GET，Query 参数）

?page=1&pageSize=20&type=standard|custom&keyword=

响应

{
  "items": [
    {
      "id": 1,
      "name": "标准模板",
      "type": "standard",
      "templateKey": "standard_v1",
      "customerId": 0,
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ],
  "total": 10
}

请求 /order/template/download（GET，Query 参数）

?templateId=1

响应

直接返回 Excel 文件流，Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

请求 /order/upload（POST，multipart/form-data）

字段	类型	说明
file	File	Excel 文件
templateId	number	模板ID

响应

{
  "taskId": 1
}

请求 /order/task/list（GET，Query 参数）

?page=1&pageSize=20&status=&keyword=

响应

{
  "items": [
    {
      "id": 1,
      "taskName": "批量下单_20240101",
      "quantity": 100,
      "status": "处理中",
      "templateId": 1,
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ],
  "total": 10
}

请求 /order/task/detail（GET，Query 参数）

?taskId=1

响应

{
  "id": 1,
  "taskName": "批量下单_20240101",
  "quantity": 100,
  "successCount": 80,
  "failCount": 20,
  "status": "已完成",
  "templateId": 1,
  "createTime": "2024-01-01 12:00:00",
  "updateTime": "2024-01-01 12:00:00",
  "failList": []
}

三、渠道模块

2.1 核心需求说明

销售产品：管理对外销售的产品（专线/快递/邮政），配置时效、黑名单区、偏远分区、计重规则、计重进位等；支持价格配置。
- 产品配置：产品基础信息（编码、名称、分组、时效、面单、黑名单区、偏远分区、计重规则、计重进位等）。
- 产品卖价：为每个产品配置多条价格项（运费、保险费、燃油附加费等）；每条价格项通过弹窗配置：
  - 基础信息：费用项、费用单位、币种、收费时机、收费条件、计费因素（因素+因素值，如货物类型、分区、重量、仓库、客户等）。
  - 价格表：根据计费因素动态生成价格表，支持分区/货物类型/重量等组合、计算公式（总价/单价/续单价）、计算值、客户组。
- 排货规则：选择排货方案（成本最低/时效最快/综合最优），配置服务商列表（服务商名称、服务渠道、权重、指定客户）。
- 发布记录：价格与规则的发布历史，支持查看版本内容、回滚到指定版本。
服务渠道：管理下游服务渠道（支持渠道组+渠道层级），配置预报单号类型、时效、买价等。
- 渠道配置：渠道基础信息（渠道代码、名称、时效、预报配置、描述、预报前脚本等）。
- 渠道买价：为每个渠道配置多条买价项（运费、保险费、燃油附加费等）；每条买价项通过弹窗配置：
  - 基础信息：费用项、费用单位、币种、收费时机、收费条件、计费因素（因素+因素值）。
  - 价格表：根据计费因素动态生成价格表，支持分区/货物类型/重量等组合、计算公式、计算值、客户组。
- 发布记录：买价与规则的发布历史，支持查看版本内容、回滚到指定版本。
黑名单区/偏远分区/预警分区：共用 KpiArea 表，通过 appKey/areaType 区分；支持分区及明细（国家/省/市/邮编区间）的增删改查。
计重规则/计重进位：配置计费重量规则与进位方式，明细结构与分区类似。
自动触发：配置下单/入库/出库时的自动拦截、警告、问题件等触发规则。
标签设计：保存 vg-print 导出的标签模板 JSON，支持尾程/客户/入库/出库/sku 等类型。

2.2 表结构设计

销售产品表 `t_sales_product`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
ProductCode	VARCHAR	64	-	是	产品编码
ProductName	VARCHAR	128	-	是	产品名称
ProductGroup	VARCHAR	32	-	否	分组(专线/快递/邮政)
MinTimeliness	INT	-	-	否	最小时效(天)
MaxTimeliness	INT	-	-	否	最大时效(天)
CustomerWaybill	VARCHAR	32	-	否	系统面单/客户面单
BlacklistAreaId	BIGINT	-	外键	否	黑名单区ID
RemoteAreaId	BIGINT	-	外键	否	偏远分区ID
WeightRuleId	BIGINT	-	外键	否	计重规则ID
WeightRoundingId	BIGINT	-	外键	否	计重进位ID
ProductDescription	TEXT	-	-	否	产品描述
PreStorageScript	TEXT	-	-	否	入库前脚本
IsActive	TINYINT	-	-	是	是否启用
Scheme	VARCHAR	32	-	是	排货方案：costLowest/timeFastest/overallBest
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

产品卖价表 `t_sales_product_price`（子表，关联 t_sales_product）

产品卖价主表，每个产品可配置多条价格项（运费、保险费、燃油附加费等）。

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
SalesProductId	BIGINT	-	外键	是	销售产品ID
SerialNumber	INT	-	-	是	序号
Status	TINYINT	-	-	是	状态：0-禁用，1-启用
PriceName	VARCHAR	64	-	是	价格名称（如运费、保险费）
CostItem	VARCHAR	64	-	是	费用项
CostUnit	VARCHAR	16	-	是	费用单位：kg/票/件
Currency	VARCHAR	16	-	是	币种：RMB/USD/EUR
ChargingTime	VARCHAR	32	-	否	收费时机：预报/出库/签收
ChargingCondition	VARCHAR	64	-	否	收费条件
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

产品卖价-计费因素表 `t_sales_product_price_factor`（子表，关联 t_sales_product_price）

弹窗「基础信息」中的计费因素配置，支持货物类型、分区、重量、仓库、客户等。

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
PriceId	BIGINT	-	外键	是	产品卖价ID
SerialNumber	INT	-	-	是	序号（决定因素排序）
Factor	VARCHAR	64	-	是	因素：货物类型/分区/重量/仓库/客户
FactorValues	JSON	-	-	否	因素值数组，如 ["普货","敏感货"]
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

产品卖价-价格表明细表 `t_sales_product_price_detail`（子表，关联 t_sales_product_price）

弹窗「价格表」中的价格明细，表头由计费因素动态生成，存储各组合的价格值。

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
PriceId	BIGINT	-	外键	是	产品卖价ID
FactorValuesJson	JSON	-	-	否	非客户因素组合，如 {"分区":"欧洲","货物类型":"普货","重量":"0-0.5"}
CalculationFormula	VARCHAR	32	-	是	计算公式：总价/单价/续单价
CalculatedValue	DECIMAL	18,4	-	否	计算值
CustomerGroupValues	JSON	-	-	否	客户组对应价格，如 {"客户组1":10,"客户组2":12}
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

排货规则-服务商表 `t_sales_product_allocation_provider`（子表，关联 t_sales_product_allocation_rule）

服务商列表：服务商名称、服务渠道、权重、指定客户。

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
SalesProductId	BIGINT	-	外键	是	销售产品ID
SerialNumber	INT	-	-	是	序号
ProviderName	VARCHAR	128	-	是	服务商名称
ServiceChannelId	BIGINT	-	外键	否	服务渠道ID
Weight	INT	-	-	是	权重（评分用）
CustomerIds	JSON	-	-	否	指定客户ID数组，空表示全部
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

Scheme 枚举：costLowest(成本最低)、timeFastest(时效最快)、overallBest(综合最优)

发布记录表 `t_sales_product_publish_record`（子表，关联 t_sales_product）

价格与规则的发布历史，支持查看版本内容、回滚。

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
SalesProductId	BIGINT	-	外键	是	销售产品ID
Version	VARCHAR	32	-	是	版本号，如 20231227112339
OperatorType	VARCHAR	16	-	是	操作类型：price(价格)/rules(规则)
Status	VARCHAR	16	-	是	状态：生效/回滚/无效
PublishUser	VARCHAR	64	-	是	发布人
PublishTime	DATETIME	-	-	是	发布时间
Description	VARCHAR	512	-	否	版本备注
Content	JSON	-	-	否	发布内容（价格或规则配置的JSON快照）
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

服务渠道组表 `t_service_channel_group`（可选，用于渠道分组）

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
Name	VARCHAR	128	-	是	渠道组名称
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

服务渠道表 `t_service_channel`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
GroupId	BIGINT	-	外键	否	渠道组ID（可选）
ChannelCode	VARCHAR	64	-	是	渠道编码
ChannelName	VARCHAR	128	-	是	渠道名称
MinTime	INT	-	-	否	最小时效(天)
MaxTime	INT	-	-	否	最大时效(天)
ForecastType	VARCHAR	32	-	否	预报单号类型(customer/waybill/tracking)
ForecastCode	VARCHAR	128	-	否	预报单号
Description	TEXT	-	-	否	描述
PreScript	TEXT	-	-	否	入库前脚本
IsActive	TINYINT	-	-	是	是否启用
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

渠道买价表 `t_service_channel_price`（子表，关联 t_service_channel）

渠道买价主表，每个渠道可配置多条买价项（运费、保险费、燃油附加费等）。

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
ServiceChannelId	BIGINT	-	外键	是	服务渠道ID
SerialNumber	INT	-	-	是	序号
Status	TINYINT	-	-	是	状态：0-禁用，1-启用
PriceName	VARCHAR	64	-	是	价格名称
CostItem	VARCHAR	64	-	是	费用项
CostUnit	VARCHAR	16	-	是	费用单位：kg/票/件
Currency	VARCHAR	16	-	是	币种：RMB/USD/EUR
ChargingTime	VARCHAR	32	-	否	收费时机：预报/出库/签收
ChargingCondition	VARCHAR	64	-	否	收费条件
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

渠道买价-计费因素表 `t_service_channel_price_factor`（子表，关联 t_service_channel_price）

弹窗「基础信息」中的计费因素配置。

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
PriceId	BIGINT	-	外键	是	渠道买价ID
SerialNumber	INT	-	-	是	序号
Factor	VARCHAR	64	-	是	因素：货物类型/分区/重量/仓库/客户
FactorValues	JSON	-	-	否	因素值数组
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

渠道买价-价格表明细表 `t_service_channel_price_detail`（子表，关联 t_service_channel_price）

弹窗「价格表」中的价格明细。

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
PriceId	BIGINT	-	外键	是	渠道买价ID
FactorValuesJson	JSON	-	-	否	非客户因素组合
CalculationFormula	VARCHAR	32	-	是	计算公式：总价/单价/续单价
CalculatedValue	DECIMAL	18,4	-	否	计算值
CustomerGroupValues	JSON	-	-	否	客户组对应价格
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

服务渠道发布记录表 `t_service_channel_publish_record`（子表，关联 t_service_channel）

买价与规则的发布历史。

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
ServiceChannelId	BIGINT	-	外键	是	服务渠道ID
Version	VARCHAR	32	-	是	版本号
OperatorType	VARCHAR	16	-	是	操作类型：price(价格)/rules(规则)
Status	VARCHAR	16	-	是	状态：生效/回滚/无效
PublishUser	VARCHAR	64	-	是	发布人
PublishTime	DATETIME	-	-	是	发布时间
Description	VARCHAR	512	-	否	版本备注
Content	JSON	-	-	否	发布内容JSON快照
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

分区表（黑名单区/偏远分区/预警分区共用）`t_kpi_area`

与轨迹下预警分区共用，通过 AreaType 区分。

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
AppKey	VARCHAR	64	-	是	应用标识
AreaType	VARCHAR	32	-	是	类型: blacklist/remote/warning
Name	VARCHAR	128	-	是	分区名称
SystemName	VARCHAR	128	-	否	系统名称
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

AreaType 枚举：blacklist(黑名单区)、remote(偏远分区)、warning(预警分区)

分区明细表 `t_kpi_area_info`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
AreaId	BIGINT	-	外键	是	分区ID
CountryCode	VARCHAR	8	-	否	国家二字码
CountryName	VARCHAR	64	-	否	国家名称
Province	VARCHAR	128	-	否	省份
City	VARCHAR	128	-	否	城市
LeftPostcode	VARCHAR	32	-	否	左侧邮编
RightPostcode	VARCHAR	32	-	否	右侧邮编
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

计重规则表 `t_weight_rule`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
AppKey	VARCHAR	64	-	是	应用标识
Name	VARCHAR	128	-	是	规则名称
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

计重规则明细表 `t_weight_rule_info`（子表，关联 t_weight_rule）

计重规则子页面，配置客户组对应的计费规则（条件表达式、计费重取值、材积系数）。

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
RuleId	BIGINT	-	外键	是	计重规则ID
Client	VARCHAR	128	-	是	客户/客户组（如：公共、客户组1、客户组2）
Condition	VARCHAR	256	-	是	条件表达式（如：gw>vw）
BillableWeight	VARCHAR	64	-	是	计费重取值（如：vw、gw）
VolumetricFactor	VARCHAR	32	-	是	材积系数（如：6000）
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

计重进位表 `t_weight_rounding`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
AppKey	VARCHAR	64	-	是	应用标识
Name	VARCHAR	128	-	是	进位名称
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

计重进位明细表 `t_weight_rounding_info`（子表，关联 t_weight_rounding）

计重进位子页面，配置重量区间的进位值（起始值、结束值、公共/客户组进位值）。

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
RoundingId	BIGINT	-	外键	是	计重进位ID
StartValue	DECIMAL	18,4	-	是	起始值(kg)
EndValue	DECIMAL	18,4	-	是	结束值(kg)
Public	VARCHAR	32	-	否	公共进位值
CustomerGroup1	VARCHAR	32	-	否	客户组1进位值
CustomerGroup2	VARCHAR	32	-	否	客户组2进位值
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

自动触发表 `t_auto_trigger`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
Status	TINYINT	-	-	是	是否启用
Operation	VARCHAR	32	-	否	操作: 拦截/警告/问题件
TriggerTiming	VARCHAR	32	-	否	触发时机: 下单/入库/出库
TriggerCondition	TEXT	-	-	否	触发条件
PromptMessage	VARCHAR	512	-	否	提示信息
Notifier	VARCHAR	128	-	否	通知人
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

标签模板表 `t_label_template`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
Name	VARCHAR	128	-	是	模板名称
TemplateJson	JSON	-	-	否	vg-print 模板 JSON
TemplateType	VARCHAR	32	-	否	尾程/客户/入库/出库/sku
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

2.3 核心接口设计

销售产品

接口名称	请求方式	请求路径	说明
产品列表	GET	/channel/sales-product/list	产品列表
产品详情	GET	/channel/sales-product/detail	产品详情
新增产品	POST	/channel/sales-product/create	新增产品
更新产品	POST	/channel/sales-product/update	更新产品
删除产品	POST	/channel/sales-product/delete	删除产品
保存产品配置	POST	/channel/sales-product/config/save	保存产品配置（产品配置 tab）

请求 /channel/sales-product/list（GET，Query 参数）

?page=1&pageSize=20&productGroup=专线&keyword=&isActive=1

响应

{
  "items": [
    {
      "id": 1,
      "productCode": "US-AIR-P",
      "productName": "美国空运专线(普货)",
      "productGroup": "专线",
      "minTimeliness": 3,
      "maxTimeliness": 7,
      "customerWaybill": "系统面单",
      "blacklistAreaId": 1,
      "remoteAreaId": 2,
      "weightRuleId": 1,
      "weightRoundingId": 1,
      "productDescription": "美国空运普货专线",
      "isActive": 1,
      "scheme": "costLowest",
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ],
  "total": 10
}

请求 /channel/sales-product/detail（GET，Query 参数）

?id=1

响应

{
  "id": 1,
  "productCode": "US-AIR-P",
  "productName": "美国空运专线(普货)",
  "productGroup": "专线",
  "minTimeliness": 3,
  "maxTimeliness": 7,
  "customerWaybill": "系统面单",
  "blacklistAreaId": 1,
  "remoteAreaId": 2,
  "weightRuleId": 1,
  "weightRoundingId": 1,
  "productDescription": "美国空运普货专线",
  "preStorageScript": "",
  "isActive": 1,
  "scheme": "costLowest",
  "createTime": "2024-01-01 12:00:00",
  "createBy": "admin",
  "updateTime": "2024-01-01 12:00:00",
  "updateBy": "admin"
}

请求 /channel/sales-product/create（POST）

{
  "productCode": "US-AIR-P",
  "productName": "美国空运专线(普货)",
  "productGroup": "专线",
  "minTimeliness": 3,
  "maxTimeliness": 7,
  "customerWaybill": "系统面单",
  "blacklistAreaId": 1,
  "remoteAreaId": 2,
  "weightRuleId": 1,
  "weightRoundingId": 1,
  "productDescription": "美国空运普货专线",
  "preStorageScript": "",
  "isActive": 1,
  "scheme": "costLowest"
}

请求 /channel/sales-product/update（POST）

{
  "id": 1,
  "productCode": "US-AIR-P",
  "productName": "美国空运专线(普货)",
  "productGroup": "专线",
  "minTimeliness": 3,
  "maxTimeliness": 7,
  "customerWaybill": "系统面单",
  "blacklistAreaId": 1,
  "remoteAreaId": 2,
  "weightRuleId": 1,
  "weightRoundingId": 1,
  "productDescription": "美国空运普货专线",
  "preStorageScript": "",
  "isActive": 1,
  "scheme": "costLowest"
}

请求 /channel/sales-product/delete（POST）

{
  "id": 1
}

请求 /channel/sales-product/config/save（POST）

{
  "id": 1,
  "productCode": "US-AIR-P",
  "productName": "美国空运专线(普货)",
  "productGroup": "专线",
  "minTimeliness": 3,
  "maxTimeliness": 7,
  "customerWaybill": "系统面单",
  "blacklistAreaId": 1,
  "remoteAreaId": 2,
  "weightRuleId": 1,
  "weightRoundingId": 1,
  "productDescription": "美国空运普货专线",
  "preStorageScript": "",
  "isActive": 1,
  "scheme": "costLowest"
}

响应（create/update/delete/config/save）

null

产品卖价（子表接口）

接口名称	请求方式	请求路径	说明
价格项列表	GET	/channel/sales-product/price/list	按产品ID获取价格项列表
新增价格项	POST	/channel/sales-product/price/create	新增价格项（含基础信息+计费因素+价格表）
更新价格项	POST	/channel/sales-product/price/update	更新价格项
删除价格项	POST	/channel/sales-product/price/delete	删除价格项
切换价格项状态	POST	/channel/sales-product/price/toggleStatus	启用/禁用价格项
保存价格配置	POST	/channel/sales-product/price/save	批量保存产品卖价（保存并可选发布）

请求 /channel/sales-product/price/list（GET，Query 参数）

?salesProductId=1

响应

{
  "items": [
    {
      "id": 1,
      "salesProductId": 1,
      "serialNumber": 1,
      "status": 1,
      "priceName": "运费",
      "costItem": "freight",
      "costUnit": "kg",
      "currency": "RMB",
      "chargingTime": "出库",
      "chargingCondition": "",
      "factors": [
        {
          "id": 1,
          "priceId": 1,
          "serialNumber": 1,
          "factor": "货物类型",
          "factorValues": [
            "普货",
            "敏感货"
          ]
        }
      ],
      "details": [
        {
          "id": 1,
          "priceId": 1,
          "factorValuesJson": {
            "分区": "欧洲",
            "货物类型": "普货",
            "重量": "0-0.5"
          },
          "calculationFormula": "单价",
          "calculatedValue": 62,
          "customerGroupValues": {
            "客户组1": 60,
            "客户组2": 65
          }
        }
      ],
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ]
}

请求 /channel/sales-product/price/create（POST）

{
  "salesProductId": 1,
  "serialNumber": 1,
  "status": 1,
  "priceName": "运费",
  "costItem": "freight",
  "costUnit": "kg",
  "currency": "RMB",
  "chargingTime": "出库",
  "chargingCondition": "",
  "factors": [
    {
      "serialNumber": 1,
      "factor": "货物类型",
      "factorValues": ["普货", "敏感货"]
    },
    {
      "serialNumber": 2,
      "factor": "分区",
      "factorValues": ["欧洲", "美国"]
    }
  ],
  "details": [
    {
      "factorValuesJson": {"分区": "欧洲", "货物类型": "普货", "重量": "0-0.5"},
      "calculationFormula": "单价",
      "calculatedValue": 62,
      "customerGroupValues": {"客户组1": 60, "客户组2": 65}
    }
  ]
}

请求 /channel/sales-product/price/update（POST）

{
  "id": 1,
  "salesProductId": 1,
  "serialNumber": 1,
  "status": 1,
  "priceName": "运费",
  "costItem": "freight",
  "costUnit": "kg",
  "currency": "RMB",
  "chargingTime": "出库",
  "chargingCondition": "",
  "factors": [],
  "details": []
}

请求 /channel/sales-product/price/delete（POST）

{
  "id": 1
}

请求 /channel/sales-product/price/toggleStatus（POST）

{
  "id": 1,
  "status": 0
}

请求 /channel/sales-product/price/save（POST）

{
  "salesProductId": 1,
  "publish": false,
  "prices": [
    {
      "id": 1,
      "serialNumber": 1,
      "status": 1,
      "priceName": "运费",
      "costItem": "freight",
      "costUnit": "kg",
      "currency": "RMB",
      "chargingTime": "出库",
      "chargingCondition": "",
      "factors": [],
      "details": []
    }
  ]
}

响应（create/update/delete/toggleStatus/save）

null

排货规则（子表接口）

接口名称	请求方式	请求路径	说明
获取排货规则	GET	/channel/sales-product/allocation/get	按产品ID获取排货方案及服务商列表
保存排货规则	POST	/channel/sales-product/allocation/save	保存排货方案及服务商（保存并可选发布）

请求 /channel/sales-product/allocation/get（GET，Query 参数）

?salesProductId=1

响应

{
  "salesProductId": 1,
  "scheme": "costLowest",
  "providers": [
    {
      "id": 1,
      "salesProductId": 1,
      "serialNumber": 1,
      "providerName": "一代物流",
      "serviceChannelId": 10,
      "serviceChannelName": "DHL美国专线",
      "weight": 100,
      "customerIds": [
        1,
        2
      ],
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ]
}

请求 /channel/sales-product/allocation/save（POST）

{
  "salesProductId": 1,
  "publish": false,
  "scheme": "costLowest",
  "providers": [
    {
      "id": 0,
      "serialNumber": 1,
      "providerName": "一代物流",
      "serviceChannelId": 10,
      "weight": 100,
      "customerIds": [1, 2]
    }
  ]
}

响应

null

发布记录（子表接口）

接口名称	请求方式	请求路径	说明
价格发布记录列表	GET	/channel/sales-product/publish/price/list	按产品ID获取价格发布历史
规则发布记录列表	GET	/channel/sales-product/publish/rules/list	按产品ID获取规则发布历史
发布	POST	/channel/sales-product/publish	发布当前配置（价格或规则）
回滚到版本	POST	/channel/sales-product/publish/rollback	回滚到指定版本

请求 /channel/sales-product/publish/price/list（GET，Query 参数）

?salesProductId=1&page=1&pageSize=20

响应

{
  "items": [
    {
      "id": 1,
      "salesProductId": 1,
      "version": "20231227112339",
      "operatorType": "price",
      "status": "生效",
      "publishUser": "admin",
      "publishTime": "2023-12-27 11:23:39",
      "description": "价格调整",
      "content": {},
      "createTime": "2023-12-27 11:23:39"
    }
  ],
  "total": 5
}

请求 /channel/sales-product/publish/rules/list（GET，Query 参数）

?salesProductId=1&page=1&pageSize=20

响应（结构同 price/list，operatorType 为 rules）

请求 /channel/sales-product/publish（POST）

{
  "salesProductId": 1,
  "operatorType": "price",
  "description": "价格调整"
}

请求 /channel/sales-product/publish/rollback（POST）

{
  "salesProductId": 1,
  "recordId": 1,
  "operatorType": "price"
}

响应（publish/rollback）

null

服务渠道

接口名称	请求方式	请求路径	说明
渠道列表	GET	/channel/service-channel/list	渠道列表（含渠道组层级）
渠道详情	GET	/channel/service-channel/detail	渠道详情
新增渠道	POST	/channel/service-channel/create	新增渠道
更新渠道	POST	/channel/service-channel/update	更新渠道
删除渠道	POST	/channel/service-channel/delete	删除渠道
保存渠道配置	POST	/channel/service-channel/config/save	保存渠道配置（渠道配置 tab）

请求 /channel/service-channel/list（GET，Query 参数）

?page=1&pageSize=20&groupId=&keyword=&isActive=1

响应

{
  "items": [
    {
      "id": 1,
      "groupId": 1,
      "groupName": "DHL渠道组",
      "channelCode": "DHL-US",
      "channelName": "DHL美国专线",
      "minTime": 3,
      "maxTime": 7,
      "forecastType": "waybill",
      "forecastCode": "",
      "description": "DHL美国专线渠道",
      "isActive": 1,
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ],
  "total": 10
}

请求 /channel/service-channel/detail（GET，Query 参数）

?id=1

响应

{
  "id": 1,
  "groupId": 1,
  "groupName": "DHL渠道组",
  "channelCode": "DHL-US",
  "channelName": "DHL美国专线",
  "minTime": 3,
  "maxTime": 7,
  "forecastType": "waybill",
  "forecastCode": "",
  "description": "DHL美国专线渠道",
  "preScript": "",
  "isActive": 1,
  "createTime": "2024-01-01 12:00:00",
  "createBy": "admin",
  "updateTime": "2024-01-01 12:00:00",
  "updateBy": "admin"
}

请求 /channel/service-channel/create（POST）

{
  "groupId": 1,
  "channelCode": "DHL-US",
  "channelName": "DHL美国专线",
  "minTime": 3,
  "maxTime": 7,
  "forecastType": "waybill",
  "forecastCode": "",
  "description": "DHL美国专线渠道",
  "preScript": "",
  "isActive": 1
}

请求 /channel/service-channel/update（POST）

{
  "id": 1,
  "groupId": 1,
  "channelCode": "DHL-US",
  "channelName": "DHL美国专线",
  "minTime": 3,
  "maxTime": 7,
  "forecastType": "waybill",
  "forecastCode": "",
  "description": "DHL美国专线渠道",
  "preScript": "",
  "isActive": 1
}

请求 /channel/service-channel/delete（POST）

{
  "id": 1
}

请求 /channel/service-channel/config/save（POST）

{
  "id": 1,
  "groupId": 1,
  "channelCode": "DHL-US",
  "channelName": "DHL美国专线",
  "minTime": 3,
  "maxTime": 7,
  "forecastType": "waybill",
  "forecastCode": "",
  "description": "DHL美国专线渠道",
  "preScript": "",
  "isActive": 1
}

响应（create/update/delete/config/save）

null

渠道买价（子表接口）

接口名称	请求方式	请求路径	说明
买价项列表	GET	/channel/service-channel/price/list	按渠道ID获取买价项列表
新增买价项	POST	/channel/service-channel/price/create	新增买价项（含基础信息+计费因素+价格表）
更新买价项	POST	/channel/service-channel/price/update	更新买价项
删除买价项	POST	/channel/service-channel/price/delete	删除买价项
切换买价项状态	POST	/channel/service-channel/price/toggleStatus	启用/禁用买价项
保存买价配置	POST	/channel/service-channel/price/save	批量保存渠道买价（保存并可选发布）

请求 /channel/service-channel/price/list（GET，Query 参数）

?serviceChannelId=1

响应

{
  "items": [
    {
      "id": 1,
      "serviceChannelId": 1,
      "serialNumber": 1,
      "status": 1,
      "priceName": "运费",
      "costItem": "freight",
      "costUnit": "kg",
      "currency": "RMB",
      "chargingTime": "出库",
      "chargingCondition": "",
      "factors": [
        {
          "id": 1,
          "priceId": 1,
          "serialNumber": 1,
          "factor": "货物类型",
          "factorValues": [
            "普货",
            "敏感货"
          ]
        }
      ],
      "details": [
        {
          "id": 1,
          "priceId": 1,
          "factorValuesJson": {
            "分区": "欧洲",
            "货物类型": "普货",
            "重量": "0-0.5"
          },
          "calculationFormula": "单价",
          "calculatedValue": 45,
          "customerGroupValues": {}
        }
      ],
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ]
}

请求 /channel/service-channel/price/create（POST）

{
  "serviceChannelId": 1,
  "serialNumber": 1,
  "status": 1,
  "priceName": "运费",
  "costItem": "freight",
  "costUnit": "kg",
  "currency": "RMB",
  "chargingTime": "出库",
  "chargingCondition": "",
  "factors": [
    {
      "serialNumber": 1,
      "factor": "货物类型",
      "factorValues": ["普货", "敏感货"]
    }
  ],
  "details": [
    {
      "factorValuesJson": {"分区": "欧洲", "货物类型": "普货", "重量": "0-0.5"},
      "calculationFormula": "单价",
      "calculatedValue": 45,
      "customerGroupValues": {}
    }
  ]
}

请求 /channel/service-channel/price/update（POST）

{
  "id": 1,
  "serviceChannelId": 1,
  "serialNumber": 1,
  "status": 1,
  "priceName": "运费",
  "costItem": "freight",
  "costUnit": "kg",
  "currency": "RMB",
  "chargingTime": "出库",
  "chargingCondition": "",
  "factors": [],
  "details": []
}

请求 /channel/service-channel/price/delete（POST）

{
  "id": 1
}

请求 /channel/service-channel/price/toggleStatus（POST）

{
  "id": 1,
  "status": 0
}

请求 /channel/service-channel/price/save（POST）

{
  "serviceChannelId": 1,
  "publish": false,
  "prices": [
    {
      "id": 1,
      "serialNumber": 1,
      "status": 1,
      "priceName": "运费",
      "costItem": "freight",
      "costUnit": "kg",
      "currency": "RMB",
      "chargingTime": "出库",
      "chargingCondition": "",
      "factors": [],
      "details": []
    }
  ]
}

响应（create/update/delete/toggleStatus/save）

null

服务渠道发布记录（子表接口）

接口名称	请求方式	请求路径	说明
价格发布记录列表	GET	/channel/service-channel/publish/price/list	按渠道ID获取买价发布历史
规则发布记录列表	GET	/channel/service-channel/publish/rules/list	按渠道ID获取规则发布历史
发布	POST	/channel/service-channel/publish	发布当前配置（买价或规则）
回滚到版本	POST	/channel/service-channel/publish/rollback	回滚到指定版本

请求 /channel/service-channel/publish/price/list（GET，Query 参数）

?serviceChannelId=1&page=1&pageSize=20

响应

{
  "items": [
    {
      "id": 1,
      "serviceChannelId": 1,
      "version": "20231227112339",
      "operatorType": "price",
      "status": "生效",
      "publishUser": "admin",
      "publishTime": "2023-12-27 11:23:39",
      "description": "买价调整",
      "content": {},
      "createTime": "2023-12-27 11:23:39"
    }
  ],
  "total": 5
}

请求 /channel/service-channel/publish/rules/list（GET，Query 参数）

?serviceChannelId=1&page=1&pageSize=20

响应（结构同 price/list，operatorType 为 rules）

请求 /channel/service-channel/publish（POST）

{
  "serviceChannelId": 1,
  "operatorType": "price",
  "description": "买价调整"
}

请求 /channel/service-channel/publish/rollback（POST）

{
  "serviceChannelId": 1,
  "recordId": 1,
  "operatorType": "price"
}

响应（publish/rollback）

null

黑名单区 / 偏远分区 / 预警分区（共用 KpiArea）

共用 Track/ForewarningService/KpiArea/* 接口，通过 appKey 区分类型。建议网关层映射为 /channel/kpi-area/* 以符合 URL 规范。

类型	appKey 建议值
黑名单区	blacklist
偏远分区	remote
预警分区	warning

接口名称	请求方式	请求路径	说明
创建分区	POST	Track/ForewarningService/KpiArea/CreateKpiArea	创建分区
修改分区	POST	Track/ForewarningService/KpiArea/ModifyKpiArea	修改分区
删除分区	POST	Track/ForewarningService/KpiArea/DeleteKpiArea	删除分区
分区列表	POST	Track/ForewarningService/KpiArea/GetKpiAreas	分区列表
新增分区明细	POST	Track/ForewarningService/KpiArea/AddAreaInfo	新增分区明细
修改分区明细	POST	Track/ForewarningService/KpiArea/ModifyKpiAreaInfo	修改分区明细
删除分区明细	POST	Track/ForewarningService/KpiArea/DeleteKpiAreaInfo	删除分区明细
分区明细列表	POST	Track/ForewarningService/KpiArea/GetKpiAreaInfos	分区明细列表

请求 Track/ForewarningService/KpiArea/CreateKpiArea（POST）

{
  "appKey": "blacklist",
  "areaType": "blacklist",
  "name": "黑名单区1",
  "systemName": "系统黑名单"
}

请求 Track/ForewarningService/KpiArea/ModifyKpiArea（POST）

{
  "id": 1,
  "appKey": "blacklist",
  "areaType": "blacklist",
  "name": "黑名单区1",
  "systemName": "系统黑名单"
}

请求 Track/ForewarningService/KpiArea/DeleteKpiArea（POST）

{
  "id": 1
}

请求 Track/ForewarningService/KpiArea/GetKpiAreas（POST）

{
  "appKey": "blacklist",
  "areaType": "blacklist",
  "page": 1,
  "pageSize": 20
}

响应（GetKpiAreas）

{
  "items": [
    {
      "id": 1,
      "appKey": "blacklist",
      "areaType": "blacklist",
      "name": "黑名单区1",
      "systemName": "系统黑名单",
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ],
  "total": 5
}

请求 Track/ForewarningService/KpiArea/AddAreaInfo（POST）

{
  "areaId": 1,
  "countryCode": "US",
  "countryName": "美国",
  "province": "加州",
  "city": "洛杉矶",
  "leftPostcode": "90001",
  "rightPostcode": "90099"
}

请求 Track/ForewarningService/KpiArea/ModifyKpiAreaInfo（POST）

{
  "id": 1,
  "areaId": 1,
  "countryCode": "US",
  "countryName": "美国",
  "province": "加州",
  "city": "洛杉矶",
  "leftPostcode": "90001",
  "rightPostcode": "90099"
}

请求 Track/ForewarningService/KpiArea/DeleteKpiAreaInfo（POST）

{
  "id": 1
}

请求 Track/ForewarningService/KpiArea/GetKpiAreaInfos（POST）

{
  "areaId": 1,
  "page": 1,
  "pageSize": 20
}

响应（GetKpiAreaInfos）

{
  "items": [
    {
      "id": 1,
      "areaId": 1,
      "countryCode": "US",
      "countryName": "美国",
      "province": "加州",
      "city": "洛杉矶",
      "leftPostcode": "90001",
      "rightPostcode": "90099",
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ],
  "total": 10
}

响应（Create/Modify/Delete/Add/Modify/Delete 明细）

null

计重规则 / 计重进位

接口名称	请求方式	请求路径	说明
规则列表	POST	/channel/weight-rule/list	规则列表
创建规则	POST	/channel/weight-rule/create	创建规则
更新规则	POST	/channel/weight-rule/update	更新规则
删除规则	POST	/channel/weight-rule/delete	删除规则
规则明细列表	POST	/channel/weight-rule/info/list	规则明细列表
新增明细	POST	/channel/weight-rule/info/add	新增明细
更新明细	POST	/channel/weight-rule/info/update	更新明细
删除明细	POST	/channel/weight-rule/info/delete	删除明细

计重进位接口同上，路径改为 /channel/weight-rounding/*，请求/响应结构与计重规则一致。

请求 /channel/weight-rounding/list（POST）

{
  "appKey": "itfx",
  "page": 1,
  "pageSize": 20
}

响应

{
  "items": [
    {
      "id": 1,
      "appKey": "itfx",
      "name": "标准进位",
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ],
  "total": 5
}

请求 /channel/weight-rounding/create（POST）

{
  "appKey": "itfx",
  "name": "标准进位"
}

请求 /channel/weight-rounding/update（POST）

{
  "id": 1,
  "appKey": "itfx",
  "name": "标准进位"
}

请求 /channel/weight-rounding/delete（POST）

{
  "id": 1
}

响应（create/update/delete）

null

请求 /channel/weight-rule/list（POST）

{
  "appKey": "itfx",
  "page": 1,
  "pageSize": 20
}

响应

{
  "items": [
    {
      "id": 1,
      "appKey": "itfx",
      "name": "标准计重规则",
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ],
  "total": 5
}

请求 /channel/weight-rule/create（POST）

{
  "appKey": "itfx",
  "name": "标准计重规则"
}

请求 /channel/weight-rule/update（POST）

{
  "id": 1,
  "appKey": "itfx",
  "name": "标准计重规则"
}

请求 /channel/weight-rule/delete（POST）

{
  "id": 1
}

请求 /channel/weight-rule/info/list（POST）

{
  "ruleId": 1,
  "page": 1,
  "pageSize": 20
}

响应

{
  "items": [
    {
      "id": 1,
      "ruleId": 1,
      "client": "公共",
      "condition": "gw>vw",
      "billableWeight": "vw",
      "volumetricFactor": "6000",
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ],
  "total": 3
}

请求 /channel/weight-rule/info/add（POST）

{
  "ruleId": 1,
  "client": "公共",
  "condition": "gw>vw",
  "billableWeight": "vw",
  "volumetricFactor": "6000"
}

请求 /channel/weight-rule/info/update（POST）

{
  "id": 1,
  "ruleId": 1,
  "client": "公共",
  "condition": "gw>vw",
  "billableWeight": "vw",
  "volumetricFactor": "6000"
}

请求 /channel/weight-rule/info/delete（POST）

{
  "id": 1
}

响应（create/update/delete/info/add/update/delete）

null

计重进位（/channel/weight-rounding/*）请求/响应结构与计重规则类似，规则明细改为：

请求 /channel/weight-rounding/info/add（POST）

{
  "roundingId": 1,
  "startValue": 0,
  "endValue": 1,
  "public": "0.5",
  "customerGroup1": "0.5",
  "customerGroup2": "0.25"
}

响应（info/list）

{
  "items": [
    {
      "id": 1,
      "roundingId": 1,
      "startValue": 0,
      "endValue": 1,
      "public": "0.5",
      "customerGroup1": "0.5",
      "customerGroup2": "0.25",
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ],
  "total": 5
}

自动触发

接口名称	请求方式	请求路径	说明
列表	GET	/channel/auto-trigger/list	列表
新增	POST	/channel/auto-trigger/create	新增
更新	POST	/channel/auto-trigger/update	更新
删除	POST	/channel/auto-trigger/delete	删除
切换启用状态	POST	/channel/auto-trigger/toggleStatus	切换启用状态

请求 /channel/auto-trigger/list（GET，Query 参数）

?page=1&pageSize=20&operation=&triggerTiming=

响应

{
  "items": [
    {
      "id": 1,
      "status": 1,
      "operation": "拦截",
      "triggerTiming": "下单",
      "triggerCondition": "weight>30",
      "promptMessage": "重量超过30kg，请确认",
      "notifier": "admin@example.com",
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ],
  "total": 5
}

请求 /channel/auto-trigger/create（POST）

{
  "status": 1,
  "operation": "拦截",
  "triggerTiming": "下单",
  "triggerCondition": "weight>30",
  "promptMessage": "重量超过30kg，请确认",
  "notifier": "admin@example.com"
}

请求 /channel/auto-trigger/update（POST）

{
  "id": 1,
  "status": 1,
  "operation": "拦截",
  "triggerTiming": "下单",
  "triggerCondition": "weight>30",
  "promptMessage": "重量超过30kg，请确认",
  "notifier": "admin@example.com"
}

请求 /channel/auto-trigger/delete（POST）

{
  "id": 1
}

请求 /channel/auto-trigger/toggleStatus（POST）

{
  "id": 1,
  "status": 0
}

响应（create/update/delete/toggleStatus）

null

标签设计

接口名称	请求方式	请求路径	说明
保存标签模板	POST	/channel/label-template/save	保存标签模板

请求 /channel/label-template/save（POST）

{
  "id": 0,
  "name": "尾程标签模板1",
  "templateType": "lastMile",
  "templateJson": {}
}

参数说明：id 模板ID，0为新增；templateType 类型：lastMile(尾程)/customer(客户)/inbound(入库)/outbound(出库)/sku；templateJson vg-print 导出的模板 JSON。

响应

{
  "id": 1,
  "name": "尾程标签模板1",
  "templateType": "lastMile",
  "templateJson": {},
  "createTime": "2024-01-01 12:00:00",
  "updateTime": "2024-01-01 12:00:00"
}

四、操作模块

3.1 核心需求说明

入库扫描：扫描运单号完成入库，记录实重、尺寸、销售产品、目的国、仓库、操作人、操作时间；支持查看最近入库记录。
出库扫描：扫描运单号完成出库，记录仓库、操作人、操作时间；支持查看最近出库记录。
标签打印：按运单号/客户单号/跟踪号/其他单号选择标签模板打印；记录打印结果与操作人。

3.2 表结构设计

入库记录表 `t_inbound_record`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
WaybillNo	VARCHAR	64	-	是	运单号
Weight	DECIMAL	10,2	-	否	实重(kg)
Length	DECIMAL	10,2	-	否	长(cm)
Width	DECIMAL	10,2	-	否	宽(cm)
Height	DECIMAL	10,2	-	否	高(cm)
SalesProductId	BIGINT	-	外键	否	销售产品ID
DestinationCountry	VARCHAR	8	-	否	目的国
WarehouseId	BIGINT	-	外键	否	仓库ID
OperateTime	DATETIME	-	-	是	操作时间
OperatorId	BIGINT	-	外键	否	操作人ID
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

出库记录表 `t_outbound_record`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
WaybillNo	VARCHAR	64	-	是	运单号
WarehouseId	BIGINT	-	外键	否	仓库ID
OperateTime	DATETIME	-	-	是	操作时间
OperatorId	BIGINT	-	外键	否	操作人ID
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

标签打印记录表 `t_label_print_record`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
WaybillNo	VARCHAR	64	-	是	运单号
CustomerOrderNo	VARCHAR	64	-	否	客户单号
TrackingNo	VARCHAR	64	-	否	跟踪号
OtherNumber	VARCHAR	64	-	否	其他单号
LabelTemplateId	BIGINT	-	外键	否	标签模板ID
PrintSuccess	TINYINT	-	-	是	是否打印成功
PrintTime	DATETIME	-	-	是	打印时间
OperatorId	BIGINT	-	外键	否	操作人ID
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

3.3 核心接口设计

入库扫描

接口名称	请求方式	请求路径	说明
入库	POST	/operation/inbound/create	入库
最近入库记录	GET	/operation/inbound/recent-list	最近入库记录

请求 /operation/inbound/create（POST）

{
  "waybillNo": "LP1234567890",
  "weight": 2.5,
  "length": 20,
  "width": 15,
  "height": 10,
  "salesProductId": 1,
  "destinationCountry": "US",
  "warehouseId": 1
}

参数说明：waybillNo 运单号；weight 实重(kg)；length/width/height 长宽高(cm)；salesProductId 销售产品ID；destinationCountry 目的国二字码；warehouseId 仓库ID。操作时间、操作人由服务端从当前会话获取。

响应

{
  "id": 1,
  "waybillNo": "LP1234567890",
  "weight": 2.5,
  "length": 20,
  "width": 15,
  "height": 10,
  "salesProductId": 1,
  "destinationCountry": "US",
  "warehouseId": 1,
  "operateTime": "2024-01-01 12:00:00",
  "operatorId": 1,
  "createTime": "2024-01-01 12:00:00"
}

请求 /operation/inbound/recent-list（GET，Query 参数）

?limit=20&warehouseId=

响应

{
  "items": [
    {
      "id": 1,
      "waybillNo": "LP1234567890",
      "weight": 2.5,
      "length": 20,
      "width": 15,
      "height": 10,
      "salesProductId": 1,
      "salesProductName": "美国空运专线(普货)",
      "destinationCountry": "US",
      "warehouseId": 1,
      "warehouseName": "深圳仓",
      "operateTime": "2024-01-01 12:00:00",
      "operatorId": 1,
      "operatorName": "张三",
      "createTime": "2024-01-01 12:00:00"
    }
  ]
}

出库扫描

接口名称	请求方式	请求路径	说明
出库	POST	/operation/outbound/create	出库
最近出库记录	GET	/operation/outbound/recent-list	最近出库记录

请求 /operation/outbound/create（POST）

{
  "waybillNo": "LP1234567890",
  "warehouseId": 1
}

参数说明：waybillNo 运单号；warehouseId 仓库ID（可选，不传则从订单或默认仓库获取）。操作时间、操作人由服务端从当前会话获取。

响应

{
  "id": 1,
  "waybillNo": "LP1234567890",
  "warehouseId": 1,
  "operateTime": "2024-01-01 12:00:00",
  "operatorId": 1,
  "createTime": "2024-01-01 12:00:00"
}

请求 /operation/outbound/recent-list（GET，Query 参数）

?limit=20&warehouseId=

响应

{
  "items": [
    {
      "id": 1,
      "waybillNo": "LP1234567890",
      "warehouseId": 1,
      "warehouseName": "深圳仓",
      "operateTime": "2024-01-01 12:00:00",
      "operatorId": 1,
      "operatorName": "张三",
      "createTime": "2024-01-01 12:00:00"
    }
  ]
}

标签打印

接口名称	请求方式	请求路径	说明
打印标签	POST	/operation/print-label/print	打印标签
最近打印记录	GET	/operation/print-label/recent-list	最近打印记录
标签模板列表	GET	/operation/print-label/template-list	标签模板列表

请求 /operation/print-label/print（POST）

{
  "number": "LP1234567890",
  "numberType": "waybill",
  "labelTemplateId": 1
}

参数说明：number 运单号/客户单号/跟踪号/其他单号；numberType 单号类型：waybill(运单号)/customerOrder(客户单号)/tracking(跟踪号)/other(其他单号)；labelTemplateId 标签模板ID，可选，不传则按 templateType 取默认模板。也可传 templateType：lastMile(尾程)/customer(客户)/inbound(入库)/outbound(出库)/sku。

响应

{
  "id": 1,
  "waybillNo": "LP1234567890",
  "customerOrderNo": "",
  "trackingNo": "",
  "otherNumber": "",
  "labelTemplateId": 1,
  "labelTemplateName": "尾程标签模板1",
  "printSuccess": 1,
  "printTime": "2024-01-01 12:00:00",
  "operatorId": 1,
  "createTime": "2024-01-01 12:00:00"
}

请求 /operation/print-label/recent-list（GET，Query 参数）

?limit=20&labelTemplateId=

响应

{
  "items": [
    {
      "id": 1,
      "waybillNo": "LP1234567890",
      "customerOrderNo": "CUST001",
      "trackingNo": "TRK001",
      "otherNumber": "",
      "labelTemplateId": 1,
      "labelTemplateName": "尾程标签模板1",
      "printSuccess": 1,
      "printTime": "2024-01-01 12:00:00",
      "operatorId": 1,
      "operatorName": "张三",
      "createTime": "2024-01-01 12:00:00"
    }
  ]
}

请求 /operation/print-label/template-list（GET，Query 参数）

?templateType=lastMile

参数说明：templateType 可选，筛选模板类型：lastMile/customer/inbound/outbound/sku。不传则返回全部可用模板。

响应

{
  "items": [
    {
      "id": 1,
      "name": "尾程标签模板1",
      "templateType": "lastMile",
      "templateJson": {},
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ]
}

五、客户模块

4.1 核心需求说明

客户管理：客户信息的增删改查，支持客户编号、手机、邮箱、余额、额度、状态等管理；支持重置密码；已有 customer API。
子账号：主客户可创建子账号，子账号共享主客户余额与额度，独立登录与权限。

4.2 表结构设计

客户表 `t_customer`

已有 customer API，表结构参考 CustomerDto。

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
CustomerCode	VARCHAR	32	-	是	客户编号，规则：前缀w+年份+序号（如W2501）
WechatAvatar	VARCHAR	255	-	否	微信头像URL
WechatNickname	VARCHAR	64	-	否	微信昵称
Email	VARCHAR	64	-	否	邮箱，唯一，用于登录/找回密码
Phone	VARCHAR	16	-	是	手机号，唯一，用于登录/验证
Balance	DECIMAL	18,2	-	是	账户余额，默认0
TotalQuota	DECIMAL	18,2	-	是	总额度，默认0
UsedQuota	DECIMAL	18,2	-	是	已用额度，默认0
Status	TINYINT	-	-	是	状态：0-禁用，1-正常，2-冻结
Remark	VARCHAR	512	-	否	备注信息
CreateUserId	INT	-	-	是	创建人（系统/管理员账号）
CreateTime	DATETIME	-	-	是	创建时间，默认当前时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间
Salesman	VARCHAR	32	-	否	所属销售员账号
CustomerService	VARCHAR	32	-	否	所属客服账号
CustomerGroup	TINYINT	-	-	否	客户分组：0-普通客户，1-VIP1，2-VIP2，3-VIP3，4-VIP4，5-VIP5
Role	VARCHAR	64	-	否	角色，用于菜单权限
LastLoginIp	VARCHAR	64	-	否	最后在线IP
LastLoginTime	DATETIME	-	-	否	最后在线时间
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
WechatOpenid	VARCHAR	64	-	否	微信OpenID，唯一，关联微信账号
Password	VARCHAR	64	-	是	密码（MD5加密存储）

CustomerGroup 枚举：0-普通客户、1-VIP1、2-VIP2、3-VIP3、4-VIP4、5-VIP5

子账号表 `t_customer_sub_account`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
MainCustomerId	BIGINT	-	外键（t_customer.Id）	是	主客户ID
SubAccountCode	VARCHAR	32	-	是	子账号编号，规则：主客户编号+"_"+序号
SubWechatAvatar	VARCHAR	255	-	否	子账号微信头像
SubWechatNickname	VARCHAR	64	-	否	子账号微信昵称
SubPhone	VARCHAR	16	-	是	子账号手机号，唯一
SubEmail	VARCHAR	64	-	否	子账号邮箱
SubPassword	VARCHAR	64	-	是	子账号密码（MD5加密）
SubStatus	TINYINT	-	-	是	子账号状态：0-禁用，1-正常
CreateUserId	INT	-	-	是	创建人（主客户/管理员）
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是

4.3 核心接口设计

接口名称	请求方式	请求路径	说明
客户列表	GET	/customer/list	客户列表
客户详情	GET	/customer/get	客户详情
创建客户	POST	/customer/create	创建客户
更新客户	POST	/customer/update	更新客户
删除客户	POST	/customer/delete	删除客户
重置密码	POST	/customer/reset-password	重置密码

个人中心可复用 /customer/get，传入当前登录客户 ID。

请求 /customer/list（GET，Query 参数）

?page=1&pageSize=20&keyword=&status=1&customerGroup=&salesman=&customerService=

响应

{
  "items": [
    {
      "id": 1,
      "customerCode": "W2501",
      "wechatAvatar": "",
      "wechatNickname": "",
      "email": "customer@example.com",
      "phone": "13800138000",
      "balance": 1000.0,
      "totalQuota": 5000.0,
      "usedQuota": 500.0,
      "status": 1,
      "remark": "",
      "salesman": "sales1",
      "customerService": "cs1",
      "customerGroup": 1,
      "lastLoginIp": "192.168.1.1",
      "lastLoginTime": "2024-01-01 12:00:00",
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ],
  "total": 50
}

请求 /customer/get（GET，Query 参数）

?id=1

响应

{
  "id": 1,
  "customerCode": "W2501",
  "wechatAvatar": "",
  "wechatNickname": "",
  "email": "customer@example.com",
  "phone": "13800138000",
  "balance": 1000.0,
  "totalQuota": 5000.0,
  "usedQuota": 500.0,
  "status": 1,
  "remark": "",
  "salesman": "sales1",
  "customerService": "cs1",
  "customerGroup": 1,
  "lastLoginIp": "192.168.1.1",
  "lastLoginTime": "2024-01-01 12:00:00",
  "createTime": "2024-01-01 12:00:00",
  "createBy": "admin",
  "updateTime": "2024-01-01 12:00:00",
  "updateBy": "admin"
}

请求 /customer/create（POST）

{
  "phone": "13800138000",
  "email": "customer@example.com",
  "password": "123456",
  "totalQuota": 5000.00,
  "status": 1,
  "remark": "",
  "salesman": "sales1",
  "customerService": "cs1",
  "customerGroup": 1
}

请求 /customer/update（POST）

{
  "id": 1,
  "email": "customer@example.com",
  "totalQuota": 5000.00,
  "status": 1,
  "remark": "",
  "salesman": "sales1",
  "customerService": "cs1",
  "customerGroup": 1
}

请求 /customer/delete（POST）

{
  "id": 1
}

请求 /customer/reset-password（POST）

{
  "id": 1,
  "newPassword": "123456"
}

响应（create/update/delete/reset-password）

null

六、充值管理

5.1 核心需求说明

充值流程：客户提交充值金额 → 选择支付方式（微信/支付宝）→ 上传充值截图 → 提交审核 → 管理员审核（通过/驳回）→ 审核通过后更新客户余额。
充值记录：完整留存充值全流程信息，支持查询、导出；充值状态包含：待审核、审核通过、审核驳回。

5.2 表结构设计

充值记录表 `t_recharge_record`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
CustomerId	BIGINT	-	外键（t_customer.Id）	是	客户ID（主账号/子账号关联主账号ID）
SerialNumber	VARCHAR	64	-	是	流水号，规则：RECHARGE+日期+随机6位数字
RechargeTime	DATETIME	-	-	是	充值提交时间，默认当前时间
PayType	TINYINT	-	-	是	支付方式：1-微信，2-支付宝
RechargeAmount	DECIMAL	18,2	-	是	充值金额，≥0.01
RechargeScreenshot	VARCHAR	255	-	否	充值截图URL（存储文件服务器地址）
RechargeStatus	TINYINT	-	-	是	充值状态：0-待审核，1-审核通过，2-审核驳回
Remark	VARCHAR	512	-	否	备注（客户/审核人填写）
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间
AuditTime	DATETIME	-	-	否	审核时间
AuditBy	VARCHAR	32	-	否	审核人（管理员账号）
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0

5.3 核心接口设计

接口名称	请求方式	请求路径	请求参数	响应参数	接口说明
提交充值申请	POST	/recharge/recharge/submit	customerId, payType, rechargeAmount, screenshotUrl, remark	serialNumber	生成流水号，保存充值记录，状态为待审核
审核充值申请	POST	/recharge/recharge-record/approve 或 reject	id, auditStatus, auditBy, remark	null	审核通过则更新客户余额，更新审核时间、状态、审核人
查询充值记录	GET	/recharge/recharge-record/list	customerId, serialNumber, startTime, endTime, status	list, total	多条件分页查询充值记录
导出充值记录	GET	/recharge/export	customerId, startTime, endTime	文件流	导出充值记录为Excel文件

请求 /recharge/recharge/submit（POST）

{
  "customerId": 1,
  "rechargeAmount": 500,
  "payType": 1,
  "rechargeScreenshot": "https://example.com/upload/screenshot.jpg",
  "remark": "充值500元"
}

参数说明：customerId 客户ID（客户端提交时可不传，取当前登录客户）；rechargeAmount 充值金额，≥0.01；payType 支付方式：1-微信，2-支付宝；rechargeScreenshot 充值截图URL；remark 备注。

响应

{
  "id": 1,
  "serialNumber": "RECHARGE2024010100123456",
  "customerId": 1,
  "rechargeAmount": 500.0,
  "payType": 1,
  "rechargeScreenshot": "https://example.com/upload/screenshot.jpg",
  "rechargeStatus": 0,
  "remark": "充值500元",
  "rechargeTime": "2024-01-01 12:00:00",
  "createTime": "2024-01-01 12:00:00"
}

请求 /recharge/recharge-record/approve（POST）

{
  "id": 1,
  "remark": "审核通过"
}

请求 /recharge/recharge-record/reject（POST）

{
  "id": 1,
  "remark": "截图不清晰，请重新上传"
}

响应（approve/reject）

null

请求 /recharge/recharge-record/list（GET，Query 参数）

?page=1&pageSize=20&customerId=1&serialNumber=&rechargeStatus=0&startTime=2024-01-01&endTime=2024-01-31

响应

{
  "items": [
    {
      "id": 1,
      "customerId": 1,
      "customerCode": "W2501",
      "customerPhone": "13800138000",
      "serialNumber": "RECHARGE2024010100123456",
      "rechargeTime": "2024-01-01 12:00:00",
      "payType": 1,
      "payTypeName": "微信",
      "rechargeAmount": 500.0,
      "rechargeScreenshot": "https://example.com/upload/screenshot.jpg",
      "rechargeStatus": 0,
      "rechargeStatusName": "待审核",
      "remark": "充值500元",
      "auditTime": null,
      "auditBy": null,
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ],
  "total": 20
}

请求 /recharge/export（GET，Query 参数）

?customerId=1&startTime=2024-01-01&endTime=2024-01-31

响应

返回 Excel 文件流，Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

七、系统模块

6.1 核心需求说明

仓库地址：管理仓库收货地址信息，包括主仓/中转仓/退货仓/其他类型；支持收件人、联系电话、收货地址、客服电话、客服微信及二维码等配置。

6.2 表结构设计

仓库地址表 `t_warehouse_address`

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
WarehouseName	VARCHAR	128	-	是	仓库名称
WarehouseType	VARCHAR	32	-	是	main/transit/return/other
Recipient	VARCHAR	64	-	否	收件人
ContactPhone	VARCHAR	32	-	否	联系电话
ShippingAddress	TEXT	-	-	否	收货地址
ServicePhone	VARCHAR	32	-	否	客服电话
ServiceWechat	VARCHAR	64	-	否	客服微信
ServiceWechatFiles	JSON	-	-	否	微信二维码图片
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

6.3 核心接口设计

接口名称	请求方式	请求路径	说明
仓库列表	GET	/system/warehouse/list	仓库列表
仓库详情	GET	/system/warehouse/detail	仓库详情
新增仓库	POST	/system/warehouse/create	新增
更新仓库	POST	/system/warehouse/update	更新
删除仓库	POST	/system/warehouse/delete	删除

请求 /system/warehouse/list（GET，Query 参数）

?page=1&pageSize=20&warehouseType=main&keyword=

响应

{
  "items": [
    {
      "id": 1,
      "warehouseName": "深圳主仓",
      "warehouseType": "main",
      "warehouseTypeName": "主仓",
      "recipient": "张三",
      "contactPhone": "0755-12345678",
      "shippingAddress": "广东省深圳市南山区xxx路xxx号",
      "servicePhone": "400-xxx-xxxx",
      "serviceWechat": "itfx_service",
      "serviceWechatFiles": [
        "https://example.com/qrcode1.jpg"
      ],
      "createTime": "2024-01-01 12:00:00",
      "updateTime": "2024-01-01 12:00:00"
    }
  ],
  "total": 5
}

请求 /system/warehouse/detail（GET，Query 参数）

?id=1

响应

{
  "id": 1,
  "warehouseName": "深圳主仓",
  "warehouseType": "main",
  "recipient": "张三",
  "contactPhone": "0755-12345678",
  "shippingAddress": "广东省深圳市南山区xxx路xxx号",
  "servicePhone": "400-xxx-xxxx",
  "serviceWechat": "itfx_service",
  "serviceWechatFiles": [
    "https://example.com/qrcode1.jpg"
  ],
  "createTime": "2024-01-01 12:00:00",
  "createBy": "admin",
  "updateTime": "2024-01-01 12:00:00",
  "updateBy": "admin"
}

请求 /system/warehouse/create（POST）

{
  "warehouseName": "深圳主仓",
  "warehouseType": "main",
  "recipient": "张三",
  "contactPhone": "0755-12345678",
  "shippingAddress": "广东省深圳市南山区xxx路xxx号",
  "servicePhone": "400-xxx-xxxx",
  "serviceWechat": "itfx_service",
  "serviceWechatFiles": ["https://example.com/qrcode1.jpg"]
}

请求 /system/warehouse/update（POST）

{
  "id": 1,
  "warehouseName": "深圳主仓",
  "warehouseType": "main",
  "recipient": "张三",
  "contactPhone": "0755-12345678",
  "shippingAddress": "广东省深圳市南山区xxx路xxx号",
  "servicePhone": "400-xxx-xxxx",
  "serviceWechat": "itfx_service",
  "serviceWechatFiles": ["https://example.com/qrcode1.jpg"]
}

请求 /system/warehouse/delete（POST）

{
  "id": 1
}

响应（create/update/delete）

null

附录

附录一：接口路径规范（kebab-case 汇总）

模块	路径前缀	示例
订单	/order/	list, detail, pay, pre-declare, cancel-intercept, delete, price-check
渠道-销售产品	/channel/sales-product/	list, detail, create, update, delete, config/save, price/list, allocation/get
渠道-服务渠道	/channel/service-channel/	list, detail, create, update, delete, price/list
渠道-计重	/channel/weight-rule/, weight-rounding/	list, create, update, delete, info/list
渠道-自动触发	/channel/auto-trigger/	list, create, update, delete, toggle-status
渠道-标签	/channel/label-template/save
操作	/operation/	inbound/create, inbound/recent-list, outbound/create, print-label/print
客户	/customer/	list, get, create, update, delete, reset-password
充值	/recharge/	recharge/submit, recharge-record/list, approve, reject
系统	/system/warehouse/	list, detail, create, update, delete

附录二：分区类型说明（黑名单/偏远/预警）

页面	area_type / Key	说明
黑名单区	blacklist	黑名单分区
偏远分区	remote	偏远分区
预警分区	warning	轨迹下预警分区

调用 KpiArea 接口时，传入对应 Key 即可区分不同业务分区，无需新建表或接口。

附录三：状态码与枚举

订单状态

status	中文
draft	草稿
predeclared	已预报
received	已收货
pendingPayment	待支付
pendingShip	待发货
pendingOnline	待上网
shipping	运输中
deliverySuccess	派送成功
deliveryFailed	派送失败
problematic	问题件
deleted	已删除
claimed	已理赔

充值状态

payStatus	中文
0	待审核
1	成功
2	失败

仓库类型

warehouseType	中文
main	主仓
transit	中转仓
return	退货仓
other	其他

客户分组（客户表）

customerGroup	中文
0	普通客户
1	VIP1
2	VIP2
3	VIP3
4	VIP4
5	VIP5

文档版本：v1.0 | 最后更新：2025-03-04

100 KiB Raw Blame History Unescape Escape