From 42a40d0325ae54cf3b0ca0a17dacb1bb394315bf Mon Sep 17 00:00:00 2001 From: liufumingren Date: Fri, 30 Oct 2026 23:06:35 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E5=BF=BD=E7=95=A5=E6=9C=AC=E5=9C=B0?= =?UTF-8?q?=E8=BF=90=E8=A1=8C=E6=97=A5=E5=BF=97=E5=B9=B6=E8=A1=A5=E5=85=85?= =?UTF-8?q?=E8=AE=A2=E5=8D=95=E6=8B=86=E5=88=86=E9=9C=80=E6=B1=82=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - .gitignore 增加 *.err(egg-bin 启动失败转储等本地运行产物,不入库) - 新增《订单拆分需求文档》记录订单拆分的业务规则与数据口径 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .gitignore | 2 + 订单拆分需求文档.md | 171 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 173 insertions(+) create mode 100644 订单拆分需求文档.md diff --git a/.gitignore b/.gitignore index 640b61a..7821948 100644 --- a/.gitignore +++ b/.gitignore @@ -36,6 +36,8 @@ out/ # logs *.log +# egg-bin / 启动失败转储(本地运行产物,不入库) +*.err # 本地开发运行输出(dev-server / 启动错误转储,不入库) .dev.err diff --git a/订单拆分需求文档.md b/订单拆分需求文档.md new file mode 100644 index 0000000..3b7ccc1 --- /dev/null +++ b/订单拆分需求文档.md @@ -0,0 +1,171 @@ +# 订单拆分模块 需求文档 + +> 版本: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. 待确认项 + +- [ ] 拆单触发时机:是在本模块内拆,还是由「创建发货单/订单」模块拆好后流入? +- [ ] 历史归档是软删除(标记)还是物理迁移?当前方案为物理迁移至历史表。 +- [ ] 异常原因的枚举值清单。 +- [ ] 各批量操作的具体权限点命名。 +``` \ No newline at end of file