WMS_MAIN/docs/order-workbench-list-api.md

188 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 订单工作台 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 表示未分配 |
| 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 文档代理