chore: 忽略本地运行日志并补充订单拆分需求文档

- .gitignore 增加 *.err(egg-bin 启动失败转储等本地运行产物,不入库)
- 新增《订单拆分需求文档》记录订单拆分的业务规则与数据口径

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-10-30 23:06:35 +08:00
parent 907df04070
commit 42a40d0325
2 changed files with 173 additions and 0 deletions

2
.gitignore vendored
View File

@ -36,6 +36,8 @@ out/
# logs
*.log
# egg-bin / 启动失败转储(本地运行产物,不入库)
*.err
# 本地开发运行输出(dev-server / 启动错误转储,不入库)
.dev.err

171
订单拆分需求文档.md Normal file
View File

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