oms/订单拆分需求文档.md
liufumingren 42a40d0325 chore: 忽略本地运行日志并补充订单拆分需求文档
- .gitignore 增加 *.err(egg-bin 启动失败转储等本地运行产物,不入库)
- 新增《订单拆分需求文档》记录订单拆分的业务规则与数据口径

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-10-30 23:06:35 +08:00

6.6 KiB
Raw Permalink Blame History

订单拆分模块 需求文档

版本: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. 待确认项

  • 拆单触发时机:是在本模块内拆,还是由「创建发货单/订单」模块拆好后流入?
  • 历史归档是软删除(标记)还是物理迁移?当前方案为物理迁移至历史表。
  • 异常原因的枚举值清单。
  • 各批量操作的具体权限点命名。