WMS_MAIN/docs/order-workbench-list-api.md
liufumingren 5ef99e3bed 1
2026-07-01 14:00:59 +08:00

13 KiB
Raw Blame History

订单工作台 List 接口说明

本文档说明订单工作台(Order Workbench)中可用的 list 接口、参数约定、返回结构与行为要点。

变更记录

  • 本次已在 methods/system.json 中补充以下 method 定义,并在 methods/changes/system.json 中追加变更记录(参见变更文件),用于对外说明新增的 list 接口与分页/where 支持。

新增/确认的接口(method 名称,主入口)

  • order.list —— 订单工作台总列表入口(汇总所有分组)
  • order.reviewOrder.list —— 待审核订单工作台(step=0)
  • order.pendingOrder.list —— 待处理订单工作台(step in [1,2])
  • order.expectionOrder.list —— 待处理异常订单工作台(step=3)
  • order.entrustOrder.list —— 委托外仓订单工作台(outsourced 模型)
  • order.deliveryOrder.list —— 配送订单工作台(dispatch 模型,dispatch_lane=m4)
  • order.deliveryExpectionOrder.list —— 配送异常订单工作台(dispatch 模型,dispatch_lane=m5)
  • order.archiveOrder.list —— 归档订单工作台(history 模型)

兼容说明:代码中存在若干旧兼容入口(例如 getreviewOrderlist、getdeliveryOrderlist、getpendingOrderlist、getexpectionOrderlist、getentrustOrderlist、getarchiveOrderlist 等),这些为兼容旧调用保留的旧名入口,不作为首选主入口;建议新调用使用上文列出的主入口。

工作台语义(简要)

  • order.list:总列表入口,返回跨分组的订单集合,适用于需要不分组的通用搜索/分页场景。
  • reviewOrder:待审核(审核步骤为未审核)工作台,用于审核操作筛选与展示(默认 step=0)。审核提交接口仅接收 ids,批量审核,严格同仓校验,不做兼容。
  • pendingOrder:待处理工作台,通常包含需要人工或系统继续处理的订单(默认 step in [1,2])。
  • expectionOrder:异常工单集合(默认 step=3),用于定位异常状态订单。
  • entrustOrder:委托外仓相关订单,使用 outsourced 模型。
  • deliveryOrder / deliveryExpectionOrder:配送相关工作台,使用 dispatch 模型,分别以 dispatch_lane=m4 / m5 筛选。
  • archiveOrder:归档历史订单,使用 history 模型。

实现要点(参考实现位于 app/service/systemMethods/order/*):

  • 模块实现会根据模块名选择不同物理模型(current / dispatch / outsourced / history),由 OrderBaseService#getOrderModel 决定。
  • 每个模块还定义了 defaultWhere(例如 reviewOrder 的 step=0 等),请求的 where 会与模块默认条件合并后一起用于构造最终查询。

参数说明(公共约定)

  • pagination: object
    • pagination.page: number(可选),页码,从 1 开始,默认 1。
    • pagination.pageSize: number(可选),每页条数,默认 20。注意:服务端对 pageSize 做上限截断,最大不可超过 200(见下)。
  • where: object(可选)
    • 统一的筛选条件对象;支持两种写法:
      • 标准化结构:{ field: { operator: 'eq'|'in'|'like'|..., value: ..., type?: 'string'|'number' } }
      • 简写:{ field: value }(会被自动转换为 { operator: 'eq', value } 或在传数组时转换为 in)
    • 服务端会先对 where 做 normalize(兼容简写与 values 字段),再走 parseWhereConditions 生成底层查询条件,最后与模块的 defaultWhere 合并(后者优先级低于请求入参)。
    • 常见可用字段:id、delivery_order_code、order_status、dispatch_lane、quickWhere 等(具体过滤字段以实现解析器支持为准)。
  • sort: object(可选)
    • 支持 sortField / sortOrder 或 field / order;实现层会映射到允许的字段集合(如 id、step、status、delivery_time、updated_at 等),默认按 updated_at DESC, id DESC。

分页/大小限制

  • 默认 pageSize=20。
  • 最大 pageSize: 200(服务端在 normalizePagination 中对 pageSize 做截断,防止单次请求返回过大数据)。调用方仍应合理控制 pageSize,避免前端一次性请求过多数据。

返回结构(公共约定)

  • list: array — 当前页的记录数组(每项为订单对象的序列化行,字段视具体模型与序列化而定)。
  • pagination: object
    • pagination.page: number — 当前页
    • pagination.pageSize: number — 每页条数(实际返回值为服务端截断后的值)
    • pagination.total: number — 符合条件的总记录数
    • pagination.totalPages: number
    • pagination.hasPrevious / hasNext: boolean

订单列表 raw 字段字典(通用)

  • 说明:以下字段为所有订单列表的 raw 基础字段;order.deliveryOrder.list 和 order.deliveryExpectionOrder.list 额外包含 dispatch_lane;服务层还会补充 express_numbers 与 waybill_codes 两个派生字段,二者内容一致,都是该订单绑定的多个快递号。
字段 类型 中文语义 枚举/说明
id number 订单主键 ID 订单记录主键
delivery_order_code string 发货单号 订单单号
pre_delivery_order_code string 预发货单号 预发货阶段单号
pre_delivery_order_id string 预发货单ID 预发货记录关联 ID
order_type string 订单类型 业务类型标识
warehouse_code string 仓库编码 仓库基础编码
order_flag string 订单标记 订单标签/标记信息
source_platform_code string 来源平台编码 原始平台编码
source_platform_name string 来源平台名称 原始平台名称
sys_platform_code string 系统平台编码 系统内平台编码
sys_platform_name string 系统平台名称 系统内平台名称
create_at string 创建时间 ISO 时间字符串
delete_at string 删除时间 ISO 时间字符串,通常为空
updated_at string 更新时间 ISO 时间字符串
place_order_time string 店铺创建订单时间 平台下单时间
pay_time string 支付时间 支付完成时间
pay_no string 支付单号 支付流水号
service_code string 集包服务编码 集包/服务编码
operator_name string ERP审核人 审核人姓名
operate_time string ERP审核时间 审核时间
delivery_time string 发货时间 发货完成时间
shop_nick string 店铺名称 店铺昵称
seller_nick string 卖家名称 卖家昵称
buyer_nick string 买家名称 买家昵称
total_amount number 订单总金额 金额字段,保留两位小数
item_amount number 商品总金额 金额字段,保留两位小数
discount_amount number 订单折扣金额 金额字段,保留两位小数
freight number 快递费用 金额字段,保留两位小数
ar_amount number 应收金额 金额字段,保留两位小数
got_amount number 已收金额 金额字段,保留两位小数
service_fee number COD服务费 金额字段,保留两位小数
logistics_code string 物流公司编码 物流公司编码
logistics_name string 物流公司名称 物流公司名称
sys_logistics_code string 系统物流公司编码 系统内物流编码
sys_logistics_name string 系统物流公司名称 系统内物流名称
express_code string 面单号前置 面单号前缀
logistics_area_code string 快递区域编码 大头笔/区域编码
delivery_type string 发货服务类型 发货方式
is_urgency enum 是否紧急 Y=是,N=否
invoice_flag enum 是否需要发票 Y=需要,N=不需要
status enum 订单状态 pedding=待处理,created=已创建,cancel=已取消,error=异常
name string 收件人姓名 收件人
zip_code string 收件人邮编 邮编
tel string 收件人电话 电话号码
mobile string 收件人移动电话 手机号
email string 收件人邮箱 邮箱
country_code string 国家编码 国家/地区编码
province string 省份 收件地址省
city string 城市 收件地址市
area string 区 收件地址区
town string 镇 收件地址镇
detail_address string 详细地址 街道/门牌详情
id_type string 证件类型 证件类型
id_number number 证件号码 证件号
oaid string OAID 设备/终端标识
sync_status enum 同步状态 padding=待同步,fin=完成,error=失败
store_id number 货主ID 货主主键
store_remark string 货主备注 来自 wms_store_warehouse.store_remask,服务层按 store_id+warehouse_id 聚合填充
warehouse_id number 仓库ID 仓库主键
from_key number 来源键 来源系统键值
items string 商品JSON字符串 原始商品明细 JSON
items_count number 商品种类数 SKU 种类数
items_total number 商品总数 商品件数总和
items_weight number 总重量(kg) 总重量
items_hash string MD5哈希值(32位) 商品明细哈希
items_crc number CRC32校验码 商品明细校验码
wave_id number 波次ID 0 表示未分配
wave_no string 波次号 空字符串表示未分配
post_status enum 分配快递号状态机 padding=处理中,fin=完成,timeout=超时,error=失败,none=未开始
storage_status enum 分配储位状态机 padding=处理中,fin=完成,error=失败,none=未开始
pick_status enum 拣货状态机 padding=处理中,fin=完成,error=失败,none=未开始
pack_status enum 打包状态机 none=未开始,padding=处理中,fin=完成,error=失败
inspection_status enum 检验状态机 none=未开始,padding=处理中,running=进行中,fin=完成,error=失败
step number 订单步骤 0=未审核,1=已审核,2=处理中,3=驳回/异常,4=配送中,5=已完成,9=已关闭
print_status enum 打印状态机 none=未开始,padding=处理中,fin=完成,error=失败
claim_status enum 领取状态机 none=未开始,padding=处理中,fin=完成,error=失败
outbound_status enum 出库状态机 none=未开始,padding=处理中,fin=完成,timeout=超时,error=失败
lock_status enum 锁定状态机 none=未锁定,warehouse=仓库锁定,store=货主锁定
intercept_status enum 拦截状态机 none=未拦截,requesting=请求中,requested=已请求,intercepting=拦截中,intercepted_in_transit=运输中拦截成功,intercepted_at_warehouse=仓库拦截成功,returning=退回中,returned=已退回,delivered_by_mistake=误签收,timeout=超时,cancelled=已取消,failed=失败,exception=异常
dispatch_lane string 配送通道/分区 仅配送相关列表可能出现,常用于区分 m4 / m5 等通道
express_numbers array[string] 快递号列表 服务层聚合字段,内容来自 wms_order_express.waybill_code
waybill_codes array[string] 运单号列表 与 express_numbers 内容一致,为兼容前端使用保留

补充说明

  • express_numbers 和 waybill_codes 都来自订单绑定的多条快递记录,适合前端直接渲染“多个快递号”。
  • sys_platform_name、sys_logistics_name 已由服务层归一化输出,前端无需再回表查询。
  • dispatch_lane 仅在 order.deliveryOrder.list / order.deliveryExpectionOrder.list 这两个配送类列表中出现;其余列表通常不返回该字段。

其他注意事项

  • where 的解析与支持的特殊字段由 parseWhereConditions 决定;若需要支持新的复杂筛选(如跨表/聚合条件),请先在解析器和后端模型中确认可支持的 specialFieldMap 与解析策略。
  • 推荐使用标准化 where 结构({ operator, value })以避免歧义;历史简写会被自动规范化,但可读性较差。
  • 兼容入口(get*)保留以兼容历史客户端,但文档与新开发均建议使用上述主入口方法名;兼容入口可能在不同 module 下存在重复实现(index + 子模块),以兼容不同调用路径。

方法清单(已在 methods/system.json 中登记)

  • order.list
  • order.reviewOrder.list
  • order.pendingOrder.list
  • order.expectionOrder.list
  • order.entrustOrder.list
  • order.deliveryOrder.list
  • order.deliveryExpectionOrder.list
  • order.archiveOrder.list

是否需要补充其它文档同步?

  • 建议同步更新:
    • 若有门户/前端 API 文档站(自动生成或展示 methods/system.json 的地方),应部署或刷新以展现新增条目。
    • 若存在 SDK 或对接说明(如 qimen 或第三方对接文档),如使用到工作台 list 场景也建议补充示例请求与常用 where 范例。

示例请求(简要)

请求体示例: { "pagination": { "page": 1, "pageSize": 50 }, "where": { "delivery_order_code": { "operator": "like", "value": "ABC" }, "create_time_start": { "value": "2026-04-01" } }, "sort": { "sortField": "updated_at", "sortOrder": "DESC" } }

响应示例(简要): { "list": [ /* 订单对象数组 */ ], "pagination": { "page":1, "pageSize":50, "total":1234, "totalPages":25, "hasPrevious":false, "hasNext":true } }

-- 文档维护者:WMS 文档代理