13 KiB
订单工作台 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 | 收件人移动电话 | 手机号 |
| 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 | 货主主键 |
| 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 表示未分配 |
| 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 文档代理