187 lines
13 KiB
Markdown
187 lines
13 KiB
Markdown
# 订单工作台 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 | 货主主键 |
|
||
| 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 文档代理
|