- .gitignore 增加 *.err(egg-bin 启动失败转储等本地运行产物,不入库) - 新增《订单拆分需求文档》记录订单拆分的业务规则与数据口径 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
6.6 KiB
6.6 KiB
订单拆分模块 需求文档
版本:v1.0 状态:已对齐(菜单定位确认为「独立拆单业务模块」) 作者:产品 / 研发对齐 日期:2026-09-15
1. 背景与目标
「订单拆分」是一个独立的业务模块:将原始订单拆分为子单(拆单)后,按不同状态在系统中流转并完成履约。
拆单后的子单需要经历以下生命周期: 待审核 → 委外中 → 配送 → 历史,其中 异常 为侧路状态,可回流转正。
目标:
- 在一个统一的页面内,按订单当前状态分视图管理,避免在不同菜单间跳转。
- 通过「订单索引表」统一追踪每张拆单子单的当前归属表,保证 id 全局唯一、可溯源。
- 通过批量操作按业务场景驱动状态流转,提升履约效率。
2. 菜单与页面形态
- 菜单归属:挂在「订单管理」下,作为独立子菜单。
- 菜单名:
订单拆分 - 路由:
/order-split - 图标:
Switch - 权限标识:
splitOrder:list - 页面布局:左侧 tab 样式(仿「商品属性」页面),tab 依次为:
待审核/异常/委外中/配送/历史
说明:前 4 个 tab(待审核、异常、委外中、配送)共用一张主业务表;
历史为独立表,仅多一个归档时间字段,其余字段与主表一致。
3. 状态流转(状态机)
审核通过
待审核 ───────────────► 委外中
▲ │
│ 异常批量转回待审核 │ 推送外部失败
│ ▼
└────── 异常 ◄──────── 异常(推送失败产生)
│
│ 直接审核(通过)
└──────────► 委外中
委外中 ── 外部回传 ──► 配送
任意状态(创建时间 > 3 个月)── 自动归档 ──► 历史(记录归档时间 + 转入时间)
3.1 流转规则明细
| 触发动作 | 来源状态 | 目标状态 | 备注 |
|---|---|---|---|
| 审核完成 | 待审核 | 委外中 | 审核通过后才进入委外 |
| 推送外部失败 | 委外中 | 异常 | 推送给外部系统时失败 |
| 外部回传成功 | 委外中 | 配送 | 外部系统回传履约结果 |
| 异常 → 批量转回待审核 | 异常 | 待审核 | 批量操作,可多选 |
| 异常 → 直接审核 | 异常 | 委外中 | 审核通过后直接进入委外 |
| 创建时间超 3 个月 | 任意 | 历史 | 系统定时任务归档,记录转入时间 |
4. 数据模型
4.1 订单索引表(order_index)
统一索引,所有拆单子单的 id 以本表为准;通过 current_table 记录子单当前所在业务表。
| 字段 | 类型 | 说明 |
|---|---|---|
| id | bigint | 主键,全局唯一,子单 id 以此为准 |
| order_no | varchar | 拆单子单单号 |
| parent_order_no | varchar | 原订单号(关联拆单来源) |
| current_table | varchar | 当前所在表(pending/exception/outsourcing/delivery/history) |
| current_status | varchar | 当前状态枚举 |
| created_at | datetime | 创建时间(用于 3 个月归档判断) |
| updated_at | datetime | 更新时间 |
4.2 状态业务表(4 张共用结构)
split_order_pending(待审核)、split_order_exception(异常)、split_order_outsourcing(委外中)、split_order_delivery(配送)字段保持一致:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | bigint | 关联 order_index.id |
| order_no | varchar | 子单单号 |
| parent_order_no | varchar | 原订单号 |
| shop_id | bigint | 店铺 |
| product_info | json/text | 商品明细 |
| receiver | varchar | 收货人 |
| address | varchar | 收货地址 |
| status | varchar | 状态 |
| remark | varchar | 备注/异常原因 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |
4.3 历史表(split_order_history)
结构与上述业务表一致,新增字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| archived_at | datetime | 归档时间(转入历史时写入) |
| transferred_at | datetime | 转入时间(状态流转进入历史的时间) |
| (其余字段同状态业务表) | — | — |
5. 前端页面设计
5.1 左侧 Tab + 表格
- 左侧 tab 切换 5 个状态视图。
- 待审核 / 异常 / 委外中 / 配送 共用同一表格组件,数据源为对应状态表。
- 历史 tab 使用历史表(带归档时间、转入时间列)。
5.2 条件筛选区
- 位置:表格上方。
- 默认:展示一行简单条件(如:单号、状态、时间范围)。
- 展开:可展开为完整条件(店铺、收货人、商品、异常原因等更多字段)。
5.3 批量操作(按场景分布在对应页面/tab)
| 所在 Tab | 批量操作 | 目标 |
|---|---|---|
| 待审核 | 批量审核 | 通过 → 委外中 |
| 委外中 | 推送外部(批量) | 失败 → 异常;成功回传 → 配送 |
| 异常 | 批量转回待审核 | 待审核 |
| 异常 | 批量审核(直接审核) | 委外中 |
| 配送 | 查看 / 回传确认 | — |
| 历史 | 查看(归档只读) | — |
批量操作按场景分布在「不同的页面/tab」,而非集中在一个操作区。
6. 接口规划(建议)
| 接口 | 说明 |
|---|---|
| GET /api/split-order/list?status= | 按状态分页查询(索引表 + 对应业务表 join) |
| POST /api/split-order/audit | 批量审核(待审核→委外中 / 异常→委外中) |
| POST /api/split-order/push | 推送外部(委外中→配送 / 失败→异常) |
| POST /api/split-order/return-to-pending | 异常批量转回待审核 |
| POST /api/split-order/archive | 归档到历史(定时任务调用,写入归档/转入时间) |
| GET /api/split-order/filters | 筛选条件下拉数据源 |
7. 非功能与权限
- 权限:
splitOrder:list控制菜单可见;各批量操作建议有独立权限点。 - 主体隔离:沿用系统现有 principal 隔离机制,拆单数据按主体隔离。
- 归档任务:定时任务扫描
created_at > 3 个月且未归档的子单,迁移至历史表并写归档/转入时间。
8. 待确认项
- 拆单触发时机:是在本模块内拆,还是由「创建发货单/订单」模块拆好后流入?
- 历史归档是软删除(标记)还是物理迁移?当前方案为物理迁移至历史表。
- 异常原因的枚举值清单。
- 各批量操作的具体权限点命名。