front/docs/物流下单协议.md

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.3 接口设计规范

规范	说明
操作审计必填	任何新增、编辑、删除操作，必须记录操作者与操作时间
新增接口	创建成功后需落库 CreateUserId、CreateTime
编辑接口	更新成功后需落库 UpdateUserId、UpdateTime
删除接口	逻辑删除时需落库 UpdateUserId、UpdateTime，并更新 IsDeleted=1

审计字段中的操作者信息优先从当前登录会话获取，不允许由前端直接信任覆盖。

---

二、订单模块

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

原 t_order_task / t_order_task_fail 已合并至本组表。Excel 导入、批量支付/预报等均统一落库于此。

任务头 t_order_batch_job（摘要）

字段名	说明
Id	主键
Action	操作类型：import-row / pay / print 等
Status	pending / running / completed / failed / cancelled
Total / SuccessCount / FailCount	进度统计
CustomerId	客户ID
PayloadJson	任务扩展（导入含 taskName、templateId）
RequestId	幂等键

任务明细 t_order_batch_job_item（摘要）

字段名	说明
JobId	关联任务头
OrderId	订单ID（导入行前为 0）
ClientNo / ServiceNo	客户单号 / 运单号
Status	pending / running / success / failed / cancelled
PayloadJson	子项入参（导入含 rowNumber、rowDataJson）
FailReason / ResultJson	失败原因 / 结果快照

订单发件人表 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	导出订单

分页查询订单列表（POST /order/list）

1 接口请求示例

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

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

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

{
  "code": 0,
  "msg": "success",
  "data": {
    "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
  }
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

订单详情（GET /order/detail）

1 接口请求示例

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

?id=1

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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。

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

支付（POST /order/pay）

1 接口请求示例

请求 /order/pay（POST）

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

requestId 幂等，可选。

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

预报（POST /order/pre-declare）

1 接口请求示例

请求 /order/pre-declare（POST）

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

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

拦截（POST /order/intercept）

1 接口请求示例

请求 /order/intercept（POST）

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

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

取消拦截（POST /order/cancel-intercept）

1 接口请求示例

请求 /order/cancel-intercept（POST）

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

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

删除（POST /order/delete）

1 接口请求示例

请求 /order/delete（POST）

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

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

打印（POST /order/print）

1 接口请求示例

请求 /order/print（POST）

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "printUrl": ""
  }
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

导出（POST /order/export）

1 接口请求示例

请求 /order/export（POST）

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "downloadUrl": "",
    "expireAt": ""
  }
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

我要查价

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

查价（POST /order/price-check）

1 接口请求示例

请求 /order/price-check（POST）

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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
      }
    ]
  }
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

我要下单

接口名称	请求方式	请求路径	说明
模板列表	GET	/order/template/list	获取下单模板列表
下载模板	GET	/order/template/download	下载 Excel 模板
上传下单	POST	/order/upload	multipart/form-data，创建 import-row 批量任务，返回 jobId
批量任务列表	GET	/order/batch/jobs	批量任务分页列表
批量任务详情	GET	/order/batch/jobs/{id}	任务进度与汇总
批量任务子项	GET	/order/batch/jobs/{id}/items	子项明细（含失败行、客户单号）
重试失败子项	POST	/order/batch/jobs/{id}/retry-failed	重新投递失败子项
取消待处理	POST	/order/batch/jobs/{id}/cancel	取消 pending 子项
创建小包	POST	/order/parcel/create	创建小包订单
批量创建小包	POST	/order/parcel/batch-create	批量创建小包订单

创建小包（POST /order/parcel/create）

1 接口请求示例

请求 /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" // 备注
    }
  ]
}

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "clientNo": "",
    "serviceNo": "",
    "trackNo": "",
    "labelUrl": ""
  }
}

幂等时可选传 requestId。

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

批量创建小包（POST /order/parcel/batch-create）

1 接口请求示例

请求 /order/parcel/batch-create（POST）

批量请求体为数组，数组内每一项与 /order/parcel/create 的单票请求结构完全一致。

[
  {
    "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" // 备注
      }
    ]
  }
]

响应

{
  "code": 0,
  "msg": "success",
}

2 接口业务逻辑

####### 核心流程

• 接收批量订单数据并逐条按单票创建规则执行，下发统一批次任务号并返回逐条处理结果。

####### 校验与异常

• 校验请求数组非空、单次数量上限与单条必填字段；部分失败时返回明细错误信息。

模板列表（GET /order/template/list）

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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
  }
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

下载模板（GET /order/template/download）

1 接口请求示例

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

?templateId=1

响应

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

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

上传下单（POST /order/upload）

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "jobId": 1001,
    "async": true
  }
}

• jobId：批量任务 ID，前端跳转批量任务详情页查看进度。
• async：true 表示 RabbitMQ 异步入队；false 表示 MQ 未启用、已在当前请求内同步处理完毕。

2 接口业务逻辑

####### 核心流程

1. 校验模板与 Excel 有效数据行（最多 2000 行）。
2. 创建 t_order_batch_job（Action=import-row）及逐行 t_order_batch_job_item。
3. MQ 开启：异步入队，逐行调用 CreateParcelCoreAsync；MQ 关闭：同步逐条处理。
4. 返回 { jobId, async }；失败明细见 GET /order/batch/jobs/{id}/items。

####### 校验与异常

• 文件为空、模板不存在、超过 2000 行等返回对应业务错误。

批量任务（GET /order/batch/jobs、/items 等）

1 接口请求示例

任务列表 GET /order/batch/jobs?page=1&pageSize=30&status=&action=&jobId=

任务详情 GET /order/batch/jobs/{id}

子项列表 GET /order/batch/jobs/{id}/items

响应（任务详情摘要）

{
  "code": 0,
  "msg": "success",
  "data": {
    "jobId": 1001,
    "action": "import-row",
    "status": "completed",
    "total": 100,
    "successCount": 95,
    "failCount": 5,
    "templateId": 1,
    "taskName": "批量下单_20260722120000"
  }
}

响应（失败子项摘要）

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "clientNo": "CUST-001",
      "rowNumber": 2,
      "status": "failed",
      "failReason": "客户单号重复"
    }
  ]
}

2 接口业务逻辑

####### 核心流程

• 按 CustomerId 隔离；导入任务子项含 rowNumber、clientNo 便于定位 Excel 行。
• 支持重试失败子项、取消待处理子项。

####### 校验与异常

• 跨客户访问返回「批量任务不存在」。

三、渠道模块

2.1 核心需求说明

• 销售产品：管理对外销售的产品（专线/快递/邮政），配置时效、黑名单区、偏远分区、价格分区、计重规则、计重进位等；支持价格配置。
  • 产品配置：产品基础信息（编码、名称、分组、时效、面单、黑名单区、偏远分区、价格分区、计重规则、计重进位等）。
  • 产品卖价：为每个产品配置多条价格项（运费、保险费、燃油附加费等）；每条价格项通过弹窗配置：
    • 基础信息：费用项、费用单位、币种、收费时机、收费条件、计费因素（因素+因素值，如货物类型、分区、重量、仓库、客户等）。
    • 价格表：根据计费因素动态生成价格表，支持分区/货物类型/重量等组合、计算公式（总价/单价/续单价）、计算值、客户组。
  • 排货规则：选择排货方案（成本最低/时效最快/综合最优），配置服务商列表（服务商名称、服务渠道、权重、指定客户）。
  • 发布记录：价格与规则的发布历史，支持查看版本内容、回滚到指定版本。
• 服务渠道：管理下游服务渠道（支持渠道组+渠道层级），配置预报单号类型、时效、买价等。
  • 渠道配置：渠道基础信息（渠道代码、名称、时效、预报配置、描述、预报前脚本等）。
  • 渠道买价：为每个渠道配置多条买价项（运费、保险费、燃油附加费等）；每条买价项通过弹窗配置：
    • 基础信息：费用项、费用单位、币种、收费时机、收费条件、计费因素（因素+因素值）。
    • 价格表：根据计费因素动态生成价格表，支持分区/货物类型/重量等组合、计算公式、计算值、客户组。
  • 发布记录：买价与规则的发布历史，支持查看版本内容、回滚到指定版本。
• 黑名单区/偏远分区/价格分区：共用 KpiArea 表，仅通过 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
PriceAreaId	BIGINT	-	外键	否	价格分区ID（t_kpi_area，AreaType=price）
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	-	是	渠道组名称
AppId	BIGINT	-	-	否	应用ID（页面新增/编辑服务商时保存）
ApiServiceProviderId	BIGINT	-	-	否	API服务商ID（页面新增/编辑服务商时保存）
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	-	主键	是	自增唯一标识
AreaType	VARCHAR	32	-	是	类型: blacklist/remote/price
Name	VARCHAR	128	-	是	分区名称
SystemName	VARCHAR	128	-	否	系统名称
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

AreaType 枚举：blacklist(黑名单区)、remote(偏远分区)、price(价格分区)

分区明细表 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	-	主键	是	自增唯一标识
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	-	主键	是	自增唯一标识
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	更新产品（包含产品配置 tab 保存）
删除产品	POST	/channel/sales-product/delete	删除产品

产品列表（GET /channel/sales-product/list）

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "productCode": "US-AIR-P",
        "productName": "美国空运专线(普货)",
        "productGroup": "专线",
        "minTimeliness": 3,
        "maxTimeliness": 7,
        "customerWaybill": "系统面单",
        "blacklistAreaId": 1,
        "remoteAreaId": 2,
        "priceAreaId": 3,
        "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
  }
}

2 接口业务逻辑

####### 核心流程

• 接收分页与筛选参数后构建查询条件（productGroup、keyword、isActive）。 ####### 校验与异常
• 按分页参数查询销售产品列表，返回 items 与 total。

产品详情（GET /channel/sales-product/detail）

1 接口请求示例

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

?id=1

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 1,
    "productCode": "US-AIR-P",
    "productName": "美国空运专线(普货)",
    "productGroup": "专线",
    "minTimeliness": 3,
    "maxTimeliness": 7,
    "customerWaybill": "系统面单",
    "blacklistAreaId": 1,
    "remoteAreaId": 2,
    "priceAreaId": 3,
    "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"
  }
}

2 接口业务逻辑

####### 核心流程

• 根据 id 查询产品主数据及扩展配置，组装详情对象返回。 ####### 校验与异常
• 若产品不存在或不可访问，返回业务错误码。

新增产品（POST /channel/sales-product/create）

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 校验产品编码唯一性与必填字段后新增产品记录。 ####### 校验与异常
• 初始化产品配置与默认状态，写入审计字段。

更新产品（POST /channel/sales-product/update）

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 根据 id 校验产品存在性后更新可变字段（包含产品配置 tab 的保存内容）。 ####### 校验与异常
• 记录操作人和更新时间，并触发配置缓存刷新。

删除产品（POST /channel/sales-product/delete）

1 接口请求示例

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

{
  "id": 1
}

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 校验产品是否可删除（无有效关联配置/任务）后执行逻辑删除。 ####### 校验与异常
• 更新删除标识及审计字段，避免物理删除带来的历史数据丢失。

产品卖价（子表接口）

接口名称	请求方式	请求路径	说明
价格项列表	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	批量保存产品卖价（保存并可选发布）

1 接口请求示例

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

?salesProductId=1

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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}
          }
        ],
        "version": "20260425143000",
        "publishTime": "2026-04-25 14:30:00",
        "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）

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 按本节接口定义执行业务处理流程，完成参数解析、数据查询/写入与结果返回。

####### 校验与异常

• 对必填参数、状态流转与数据存在性进行校验；异常场景返回统一错误码与错误信息。

排货规则（子表接口）

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

1 接口请求示例

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

?salesProductId=1

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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]
    }
  ]
}

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 按本节接口定义执行业务处理流程，完成参数解析、数据查询/写入与结果返回。

####### 校验与异常

• 对必填参数、状态流转与数据存在性进行校验；异常场景返回统一错误码与错误信息。

发布记录（子表接口）

接口名称	请求方式	请求路径	说明
价格发布记录列表	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	回滚到指定版本

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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）

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 按本节接口定义执行业务处理流程，完成参数解析、数据查询/写入与结果返回。

####### 校验与异常

• 对必填参数、状态流转与数据存在性进行校验；异常场景返回统一错误码与错误信息。

服务渠道

接口名称	请求方式	请求路径	说明
渠道列表	GET	/channel/service-channel/list	渠道列表（含渠道组层级）
渠道详情	GET	/channel/service-channel/detail	渠道详情
新增渠道	POST	/channel/service-channel/create	新增渠道
更新渠道	POST	/channel/service-channel/update	更新渠道（包含渠道配置 tab 保存）
删除渠道	POST	/channel/service-channel/delete	删除渠道
新增服务商	POST	/channel/service-channel/group/create	新增服务商分组（写入 t_service_channel_group，保存应用ID与API服务商ID）
编辑服务商	POST	/channel/service-channel/group/update	编辑服务商分组（更新名称/应用ID/API服务商ID）
删除服务商	POST	/channel/service-channel/group/delete	删除服务商分组（若分组下存在渠道需禁止删除）

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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/group/create（POST）

{
  "name": "DHL服务商",
  "appId": 1,
  "apiServiceProviderId": 12
}

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

{
  "id": 1,
  "name": "DHL服务商(更新)",
  "appId": 1,
  "apiServiceProviderId": 12
}

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

{
  "id": 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
}

响应（create/update/delete）

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 按本节接口定义执行业务处理流程，完成参数解析、数据查询/写入与结果返回（包含渠道配置 tab 的保存内容）。
• 新增服务商时向 t_service_channel_group 写入服务商名称、应用ID（AppId）与API服务商ID（ApiServiceProviderId）。

####### 校验与异常

• 对必填参数、状态流转与数据存在性进行校验；异常场景返回统一错误码与错误信息。

渠道买价（子表接口）

接口名称	请求方式	请求路径	说明
买价项列表	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	批量保存渠道买价（保存并可选发布）

1 接口请求示例

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

?serviceChannelId=1

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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）

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 按本节接口定义执行业务处理流程，完成参数解析、数据查询/写入与结果返回。

####### 校验与异常

• 对必填参数、状态流转与数据存在性进行校验；异常场景返回统一错误码与错误信息。

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

接口名称	请求方式	请求路径	说明
价格发布记录列表	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	回滚到指定版本

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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）

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 按本节接口定义执行业务处理流程，完成参数解析、数据查询/写入与结果返回。

####### 校验与异常

• 对必填参数、状态流转与数据存在性进行校验；异常场景返回统一错误码与错误信息。

黑名单区 / 偏远分区 / 价格分区（共用 KpiArea）

共用 /channel/kpi-area/* 接口，仅通过请求/响应中的 areaType（对应表字段 AreaType）区分分区类型。

类型	areaType
黑名单区	blacklist
偏远分区	remote
价格分区	price

接口名称	请求方式	请求路径	说明
创建分区	POST	/channel/kpi-area/create	创建分区
修改分区	POST	/channel/kpi-area/update	修改分区
删除分区	POST	/channel/kpi-area/delete	删除分区
分区列表	POST	/channel/kpi-area/list	分区列表
新增分区明细	POST	/channel/kpi-area/info/add	新增分区明细
修改分区明细	POST	/channel/kpi-area/info/update	修改分区明细
删除分区明细	POST	/channel/kpi-area/info/delete	删除分区明细
分区明细列表	POST	/channel/kpi-area/info/list	分区明细列表

1 接口请求示例

请求 /channel/kpi-area/create（POST）

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

请求 /channel/kpi-area/update（POST）

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

请求 /channel/kpi-area/delete（POST）

{
  "id": 1
}

请求 /channel/kpi-area/list（POST）

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

响应（GetKpiAreas）

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

请求 /channel/kpi-area/info/add（POST）

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

请求 /channel/kpi-area/info/update（POST）

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

请求 /channel/kpi-area/info/delete（POST）

{
  "id": 1
}

请求 /channel/kpi-area/info/list（POST）

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

响应（GetKpiAreaInfos）

{
  "code": 0,
  "msg": "success",
  "data": {
    "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 明细）

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 按本节接口定义执行业务处理流程，完成参数解析、数据查询/写入与结果返回。

####### 校验与异常

• 对必填参数、状态流转与数据存在性进行校验；异常场景返回统一错误码与错误信息。

计重规则 / 计重进位

接口名称	请求方式	请求路径	说明
规则列表	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/*，请求/响应结构与计重规则一致。

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "标准进位",
        "createTime": "2024-01-01 12:00:00",
        "updateTime": "2024-01-01 12:00:00"
      }
    ],
    "total": 5
  }
}

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

{
  "name": "标准进位"
}

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

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

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

{
  "id": 1
}

响应（create/update/delete）

{
  "code": 0,
  "msg": "success",
  "data": null
}

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "标准计重规则",
        "createTime": "2024-01-01 12:00:00",
        "updateTime": "2024-01-01 12:00:00"
      }
    ],
    "total": 5
  }
}

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

{
  "name": "标准计重规则"
}

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

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

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

{
  "id": 1
}

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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）

{
  "code": 0,
  "msg": "success",
  "data": 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）

{
  "code": 0,
  "msg": "success",
  "data": {
    "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
  }
}

2 接口业务逻辑

####### 核心流程

• 按本节接口定义执行业务处理流程，完成参数解析、数据查询/写入与结果返回。

####### 校验与异常

• 对必填参数、状态流转与数据存在性进行校验；异常场景返回统一错误码与错误信息。

自动触发

接口名称	请求方式	请求路径	说明
列表	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	切换启用状态

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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）

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 按本节接口定义执行业务处理流程，完成参数解析、数据查询/写入与结果返回。

####### 校验与异常

• 对必填参数、状态流转与数据存在性进行校验；异常场景返回统一错误码与错误信息。

标签设计

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

1 接口请求示例

请求 /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。

响应

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

---

---

2 接口业务逻辑

####### 核心流程

• 按本节接口定义执行业务处理流程，完成参数解析、数据查询/写入与结果返回。

####### 校验与异常

• 对必填参数、状态流转与数据存在性进行校验；异常场景返回统一错误码与错误信息。

四、操作模块

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	最近入库记录

入库（POST /operation/inbound/create）

1 接口请求示例

请求 /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。操作时间、操作人由服务端从当前会话获取。

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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"
  }
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

最近入库记录（GET /operation/inbound/recent-list）

1 接口请求示例

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

?limit=20&warehouseId=

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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"
      }
    ]
  }
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

出库扫描

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

出库（POST /operation/outbound/create）

1 接口请求示例

请求 /operation/outbound/create（POST）

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 1,
    "waybillNo": "LP1234567890",
    "warehouseId": 1,
    "operateTime": "2024-01-01 12:00:00",
    "operatorId": 1,
    "createTime": "2024-01-01 12:00:00"
  }
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

最近出库记录（GET /operation/outbound/recent-list）

1 接口请求示例

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

?limit=20&warehouseId=

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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"
      }
    ]
  }
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

标签打印

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

打印标签（POST /operation/print-label/print）

1 接口请求示例

请求 /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。

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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"
  }
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

最近打印记录（GET /operation/print-label/recent-list）

1 接口请求示例

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

?limit=20&labelTemplateId=

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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"
      }
    ]
  }
}

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

标签模板列表（GET /operation/print-label/template-list）

1 接口请求示例

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

?templateType=lastMile

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

响应

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

---

---

2 接口业务逻辑

####### 核心流程

• 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。

####### 校验与异常

• 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。

五、客户模块

4.1 核心需求说明

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

4.2 表结构设计

客户表 t_customer

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

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
CustomerCode	VARCHAR	32	-	是	客户编号，规则：前缀w+年份+序号（如W2501）
CustomerName	VARCHAR	128	-	是	客户名称
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。

客户列表（GET /customer/list）

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "customerCode": "W2501",
        "wechatAvatar": "",
        "wechatNickname": "",
        "email": "customer@example.com",
        "phone": "13800138000",
        "balance": 1000.00,
        "totalQuota": 5000.00,
        "usedQuota": 500.00,
        "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
  }
}

2 接口业务逻辑

####### 核心流程

• 根据筛选参数分页查询客户列表，返回客户基础信息、状态与余额额度信息。

####### 校验与异常

• 校验分页参数合法性；当筛选条件无匹配数据时返回空列表与 total=0。

客户详情（GET /customer/get）

1 接口请求示例

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

?id=1

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 1,
    "customerCode": "W2501",
    "wechatAvatar": "",
    "wechatNickname": "",
    "email": "customer@example.com",
    "phone": "13800138000",
    "balance": 1000.00,
    "totalQuota": 5000.00,
    "usedQuota": 500.00,
    "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"
  }
}

2 接口业务逻辑

####### 核心流程

• 按客户 ID 查询客户详情，返回完整客户资料与审计字段。

####### 校验与异常

• 校验 id 必填且存在；不存在时返回业务错误码。

创建客户（POST /customer/create）

1 接口请求示例

请求 /customer/create（POST）

{
  "customerCode": "W2501",
  "customerName": "张三客户",
  "wechatAvatar": "https://cdn.example.com/avatar/w2501.png",
  "wechatNickname": "张三",
  "phone": "13800138000",
  "email": "customer@example.com",
  "password": "123456",
  "balance": 1000.00,
  "totalQuota": 5000.00,
  "usedQuota": 500.00,
  "status": 1,
  "role": "customer",
  "remark": "",
  "salesman": "sales1",
  "customerService": "cs1",
  "customerGroup": 1
}

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 新增客户账号并写入客户基础资料（客户编号/名称、微信信息、联系方式）、余额额度、角色与业务归属信息。

####### 校验与异常

• 校验手机号/邮箱唯一性与必填字段，冲突时返回业务错误。

更新客户（POST /customer/update）

1 接口请求示例

请求 /customer/update（POST）

{
  "id": 1,
  "customerCode": "W2501",
  "customerName": "张三客户",
  "wechatAvatar": "https://cdn.example.com/avatar/w2501.png",
  "wechatNickname": "张三",
  "phone": "13800138000",
  "email": "customer@example.com",
  "balance": 1000.00,
  "totalQuota": 5000.00,
  "usedQuota": 500.00,
  "status": 1,
  "role": "customer",
  "remark": "",
  "salesman": "sales1",
  "customerService": "cs1",
  "customerGroup": 1
}

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 根据客户 ID 更新客户资料（编号/名称、微信信息、联系方式）、余额额度、状态、角色与业务归属字段。

####### 校验与异常

• 校验 id 存在与可更新状态；非法状态流转时返回业务错误。

删除客户（POST /customer/delete）

1 接口请求示例

请求 /customer/delete（POST）

{
  "id": 1
}

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 按客户 ID 执行逻辑删除，保留历史审计数据。

####### 校验与异常

• 校验 id 存在且可删除；存在关联数据限制时返回业务错误。

重置密码（POST /customer/reset-password）

1 接口请求示例

请求 /customer/reset-password（POST）

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

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 根据客户 ID 重置登录密码并更新密码变更时间。

####### 校验与异常

• 校验 id 与 newPassword 合法性，不满足密码策略时返回业务错误。

---

---

六、充值管理

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	code, msg, data.serialNumber	生成流水号，保存充值记录，状态为待审核
审核充值申请	POST	/recharge/recharge-record/approve 或 reject	id, auditStatus, auditBy, remark	code, msg	审核通过则更新客户余额，更新审核时间、状态、审核人
查询充值记录	GET	/recharge/recharge-record/list	customerId, serialNumber, startTime, endTime, status	list, total	多条件分页查询充值记录
导出充值记录	GET	/recharge/export	customerId, startTime, endTime	文件流	导出充值记录为Excel文件

提交充值申请（POST /recharge/recharge/submit）

1 接口请求示例

请求 /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 备注。

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 1,
    "serialNumber": "RECHARGE2024010100123456",
    "customerId": 1,
    "rechargeAmount": 500.00,
    "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"
  }
}

2 接口业务逻辑

####### 核心流程

• 创建充值记录并生成流水号，初始状态为待审核。

####### 校验与异常

• 校验金额、支付方式与截图信息合法性，不合法时返回业务错误。

审核充值申请-通过（POST /recharge/recharge-record/approve）

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 审核通过后更新充值状态与审核信息，并增加客户余额。

####### 校验与异常

• 校验记录状态必须为待审核；重复审核或状态冲突时返回业务错误。

审核充值申请-驳回（POST /recharge/recharge-record/reject）

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 审核驳回后更新充值状态与审核备注，不变更客户余额。

####### 校验与异常

• 校验记录状态与审核权限，非法操作时返回业务错误。

查询充值记录（GET /recharge/recharge-record/list）

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "customerId": 1,
        "customerCode": "W2501",
        "customerPhone": "13800138000",
        "serialNumber": "RECHARGE2024010100123456",
        "rechargeTime": "2024-01-01 12:00:00",
        "payType": 1,
        "payTypeName": "微信",
        "rechargeAmount": 500.00,
        "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
  }
}

2 接口业务逻辑

####### 核心流程

• 按客户、流水号、状态和时间区间进行分页查询，返回记录列表与总数。

####### 校验与异常

• 校验时间区间与分页参数合法性，查询异常时返回统一错误码。

导出充值记录（GET /recharge/export）

1 接口请求示例

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

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

响应

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

2 接口业务逻辑

####### 核心流程

• 根据筛选条件导出充值记录为 Excel 文件流。

####### 校验与异常

• 校验导出条件与数据权限，导出失败时返回统一错误信息。

---

---

七、系统模块

6.1 核心需求说明

• 仓库地址：管理仓库收货地址信息，包括主仓/中转仓/退货仓/其他类型；支持收件人、联系电话、收货地址、客服电话、客服微信及二维码等配置。
• 国家管理：维护国家基础资料（中文名称、英文名称、二字代码），供渠道分区、下单地址等模块复用。

6.2 表结构设计

国家表 t_country

字段名	字段类型	长度	主键/外键	非空	说明
Id	BIGINT	-	主键	是	自增唯一标识
ChineseName	VARCHAR	128	-	是	中文名称
EnglishName	VARCHAR	128	-	是	英文名称
CountryCode	VARCHAR	2	-	是	国家二字代码（ISO 3166-1 alpha-2）
IsDeleted	TINYINT	-	-	是	是否删除：0-否，1-是，默认0
CreateUserId	INT	-	-	是	创建人
CreateTime	DATETIME	-	-	是	创建时间
UpdateUserId	INT	-	-	否	更新人
UpdateTime	DATETIME	-	-	否	更新时间

仓库地址表 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/country/list	查询国家列表（返回全部字段）
仓库列表	GET	/system/warehouse/list	仓库列表
仓库详情	GET	/system/warehouse/detail	仓库详情
新增仓库	POST	/system/warehouse/create	新增
更新仓库	POST	/system/warehouse/update	更新
删除仓库	POST	/system/warehouse/delete	删除

国家列表（GET /system/country/list）

1 接口请求示例

请求 /system/country/list（GET）

无请求参数，返回全部国家字段。

响应

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "chineseName": "中国",
      "englishName": "China",
      "countryCode": "CN"
    },
    {
      "id": 2,
      "chineseName": "美国",
      "englishName": "United States",
      "countryCode": "US"
    }
  ]
}

2 接口业务逻辑

####### 核心流程

• 查询 t_country 全量有效数据，按 countryCode 或 englishName 排序返回（不返回创建时间、更新时间）。

####### 校验与异常

• 仅返回未删除记录；无数据时返回空数组。

仓库列表（GET /system/warehouse/list）

1 接口请求示例

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

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

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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
  }
}

2 接口业务逻辑

####### 核心流程

• 按仓库类型与关键词分页查询仓库地址信息列表。

####### 校验与异常

• 校验分页参数与筛选条件合法性，异常时返回统一错误码。

仓库详情（GET /system/warehouse/detail）

1 接口请求示例

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

?id=1

响应

{
  "code": 0,
  "msg": "success",
  "data": {
    "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"
  }
}

2 接口业务逻辑

####### 核心流程

• 根据仓库 ID 查询仓库详情，返回完整地址与客服信息。

####### 校验与异常

• 校验 id 必填且存在，不存在时返回业务错误。

新增仓库（POST /system/warehouse/create）

1 接口请求示例

请求 /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"]
}

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 新增仓库地址配置并写入创建审计信息。

####### 校验与异常

• 校验仓库名称、类型及地址字段完整性，不合法时返回业务错误。

更新仓库（POST /system/warehouse/update）

1 接口请求示例

请求 /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"]
}

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 根据仓库 ID 更新仓库基础信息与联系方式。

####### 校验与异常

• 校验 id 存在与更新字段合法性，更新失败时返回业务错误。

删除仓库（POST /system/warehouse/delete）

1 接口请求示例

请求 /system/warehouse/delete（POST）

{
  "id": 1
}

响应

{
  "code": 0,
  "msg": "success",
  "data": null
}

2 接口业务逻辑

####### 核心流程

• 根据仓库 ID 执行逻辑删除并保留历史记录。

####### 校验与异常

• 校验 id 存在与删除前置条件，冲突时返回业务错误。

---

---

附录

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

模块	路径前缀	示例
订单	/order/	list, detail, pay, pre-declare, cancel-intercept, delete, price-check
渠道-销售产品	/channel/sales-product/	list, detail, create, update, delete, price/list, allocation/get
渠道-服务渠道	/channel/service-channel/	list, detail, create, update, delete, group/create, group/update, group/delete, price/list
渠道-计重	/channel/weight-rule/, weight-rounding/	list, create, update, delete, info/list
渠道-自动触发	/channel/auto-trigger/	list, create, update, delete, toggle-status
渠道-分区（KpiArea）	/channel/kpi-area/	create, update, delete, list, info/add, info/update, info/delete, info/list
渠道-标签	/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/	country/list, warehouse/list, warehouse/detail, warehouse/create, warehouse/update, warehouse/delete

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

页面	areaType	说明
黑名单区	blacklist	黑名单分区
偏远分区	remote	偏远分区
价格分区	price	用于计价/价格表关联的分区

调用 KpiArea 接口时，通过 areaType 区分不同业务分区，无需新建表或接口。

附录三：状态码与枚举

订单状态

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