html/docs
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化

Browse Source
This commit is contained in:
ouyangxq
2026-10-09 17:36:27 +08:00
parent d89e8ec16c
commit b472dadd61
3 changed files with 83 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
统一订单主状态与操作契约.md
+21 -1
View File
@@ -85,11 +85,31 @@
### 客户订单列表的分页与待办读取
- 客户订单首页使用 `GET /api/merchant/v1/orders/workbench`，客户范围只取认证上下文，权限为 `merchant:order:list`。接口一次返回当前页、筛选后总数、全部/待费用确认/待上传报关资料/草稿四项数量及该客户完整渠道名称选项；不能先取前 200 条再在浏览器分页或统计。
- 客户订单首页使用 `GET /api/merchant/v1/orders/workbench`，客户范围只取认证上下文，权限为 `merchant:order:list`。接口一次返回当前页、筛选后总数、全部/待费用确认/装柜完成/已报关/已清关/已排车/派送中/派送完成/待上传报关资料/草稿十项数量及该客户完整渠道名称选项；不能先取前 200 条再在浏览器分页或统计。
- Order 在数据库内应用入仓码或 SKU、收货仓、渠道、目的仓类型、快递单号、创建时间、当前状态及待办筛选。草稿排在前面，同组按创建时间和订单 ID 倒序稳定分页；默认每页 10 条，上限 200 条。`DRAFT/CANCELLED` 是订单交易状态在客户读模型中的直接展示，不新增履约推进节点；默认列表排除已取消单。
- Firstleg 通过受内部服务令牌保护的 `/internal/firstleg/v1/inbounds/unified-orders/workbench-filters` 提供当前客户匹配的履约和待办订单范围。费用待确认只取最新费用版本的未确认 `SENT`；报关待上传取最新已完成装柜计划、有效货柜及尚未上传齐当前客户退税入仓码资料的范围，不受同柜其他客户未上传影响。查询不创建报关记录、不更改船或柜、不跨 Schema 读表。
- 翻页、换每页数量和筛选均重新请求服务端；快速切换时旧响应不得覆盖新页。筛选数量随当前条件计算，资料或费用确认后重新读取。分页响应不完整或依赖服务失败时明确报错，不能回退旧查询或显示成功的空列表。
### 客户头程订单履约分类
- 分类不是新增订单主状态。当前分类优先级为装柜完成、已报关、已清关、已排车、派送中、派送完成，采用已确认的最高当前进度；费用确认、报关资料上传是并行待办，可以与履约分类重叠。分类数量随当前查询条件计算，不从当前页推算。
- Firstleg仅按客户实际装载片段读取有效货柜：装柜计划和实际拣货完成才算装柜；报关聚合`COMPLETED`才算已报关；目的港标准节点`PICKUP_READY`存在实际时间才算已清关。上传、回执确认、正式申报、预计时间和较晚船节点不能补造缺失清关事实。
- Lastleg通过`POST /internal/lastleg/v1/customer-order-progress`只读返回认证客户来源订单的尾程进度。Order使用内部服务令牌调用，公网Gateway不公开该接口，不跨Schema联查。该查询依赖Lastleg可用，失败明确报错，不返回假的零数量。
- 已排车取正式排车单`PENDING_DEPARTURE/PICKING/READY_TO_DEPART`的有效货物；预排草稿、取消排车不计。未收货托盘按计划分配来源，实收托盘按实际库存与本次拣货还原所有来源，混托不能用代表订单号归属整托。
- 派送中必须有`DEPARTED + departAt`、关联出库`OUTBOUNDED`及对应目的地派送单`WAIT_DELIVERY/DELIVERING`；生成派送单不表示开始派送。取消、拒收、待退回及退回分支不伪装为正常派送中，原运输事实留在详情。
- 分批履约返回`partial`，列表显示“部分装柜完成/部分已报关/部分已清关/部分已排车/部分派送中”。根订单合并自身及全部有效子单进度，子单继续独立展示；未同步尾程片段不能算整单完成。派送完成只认Order既有可信完成门禁，不凭某张派送单签收推定根订单完成。
- 工作台响应`progress`与当前页订单一一对应，未到装柜阶段返回`none`并显示“—”；列表及导出保留当前订单状态并单独展示履约进度。历史节点仍由详情中的真实运输片段承载。
本次列表交互以用户提供的分类栏截图为依据：横向可滚动分类、计费待办角标、履约分类括号数量和右侧工具栏。截图未覆盖的“派送完成、上传资料、草稿”沿当前入口追加，履约进度列用于区分主状态与客户进度。详情、编辑、计费确认、资料弹框的承载方式沿现有实现，本次不改变。
列表交互核对范围：
| 页面/操作 | 原型依据与承载 | 实现口径 |
|---|---|---|
| 头程订单列表分类 | 用户提供分类栏截图：列表内横向滚动，计费角标、履约括号数量 | 按截图次序展示七个入口，随后保留完成、资料和草稿；筛选重新请求服务端 |
| 列表状态展示 | 截图保留当前订单状态列；已确认方案补充履约进度 | 主状态不改义，新增可选履约进度列，部分事实明确标注“部分” |
| 订单信息导出 | 原列表工具栏按钮与CSV下载承载 | 同步导出主状态及履约进度，不新增弹框 |
### 履约主链
```text