WMS_MAIN/database/designs/after-sale-work-order-design.md

441 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 售后工单表设计方案
> **状态**: ✅ 已落库(开发环境)
> **设计日期**: 2026-07-28(v4 定稿:新增 parent_work_order_id 支持主子工单)
> **设计人**: wms-db-agent
> **说明**: 本文档仅输出设计方案,不执行落库。审阅通过后再生成迁移文件。
---
## 一、需求概述
1. **主表**:售后工单单表,支持灵活绑定多种业务单据(运单、订单、入库单、退货单等),通过 `business_type` + `business_sub_type` + `business_id` 三级多态关联
2. **副表**:进度步骤处理表,记录每一步的操作员工、动作、备注(步骤不预设模板,由业务逻辑动态创建)
3. **状态流转**:工单整体状态 + 主表 `current_step` 进度 + 步骤级状态三层次
4. **简单记账**:记录是"进"还是"出"
5. **理赔追踪**:是否需要理赔、理赔金额、理赔结算状态
6. **附件关联**:通过现有 `wms_file_reference` 表关联附件/图片
---
## 二、表结构设计
### 2.1 主表:`wms_after_sale_work_order`(售后工单主表)
| # | 字段名 | 类型 | 必填 | 默认值 | 说明 |
|---|--------|------|------|--------|------|
| 1 | `id` | `BIGINT(20) UNSIGNED` | Y | AUTO | 主键ID |
| 2 | `warehouse_id` | `BIGINT(20) UNSIGNED` | Y | — | 仓库ID |
| 3 | `store_id` | `BIGINT(20) UNSIGNED` | Y | — | 货主ID |
| 4 | `work_order_no` | `VARCHAR(50)` | Y | — | 售后工单号,唯一,格式 `AS` + 时间戳(如 AS202607280001) |
| 5 | `business_type` | `VARCHAR(50)` | Y | — | 关联业务类型,见 §3.1 枚举及 §五 Model 内置定义 |
| 6 | `business_sub_type` | `VARCHAR(50)` | Y | — | 关联业务子类型,如运单下的 `intercept`(拦截)、订单下的 `mis_shipment`(错发),见 §五 |
| 7 | `business_id` | `BIGINT(20) UNSIGNED` | Y | — | 关联业务单据主键ID(多态关联) |
| 8 | `business_no` | `VARCHAR(100)` | N | — | 关联业务单据号(冗余,方便列表展示) |
| 9 | `direction` | `TINYINT UNSIGNED` | Y | 0 | 记账方向:`1`=入库(退货入库/换货入库),`2`=出库(补发/换货出库),`0`=未确定 |
| 10 | `status` | `TINYINT UNSIGNED` | Y | 0 | 工单状态,见 §3.4 状态机 |
| 11 | `priority` | `TINYINT UNSIGNED` | Y | 50 | 优先级:`1`~`100`,数字越大优先级越高,由客服接待或AI自动识别填入 |
| 12 | `title` | `VARCHAR(200)` | Y | — | 工单标题/摘要 |
| 13 | `description` | `TEXT` | N | — | 问题描述 |
| 14 | `creator_id` | `BIGINT(20) UNSIGNED` | Y | — | 创建人ID,关联 `account.id`;`0` 表示 AI 自动接待 |
| 15 | `creator_snapshot` | `TEXT` | N | — | 创建人信息快照(JSON格式);AI创建时记录模型/会话信息 |
| 16 | `assignee_id` | `BIGINT(20) UNSIGNED` | N | — | 当前处理人ID,关联 `account.id` |
| 17 | `parent_work_order_id` | `BIGINT(20) UNSIGNED` | N | — | 父工单ID,自关联 `wms_after_sale_work_order.id`;非空时表示当前工单为子工单 |
| 18 | `current_step` | `TINYINT UNSIGNED` | Y | 1 | **当前进度**(位于主表),值为当前正在处理的 `step_order` 序号 |
| 19 | `claim_needed` | `TINYINT UNSIGNED` | Y | 0 | 是否需要理赔:`0`=不需要,`1`=需要 |
| 20 | `claim_amount` | `DECIMAL(12,2)` | N | 0.00 | 理赔金额(元),精度2位小数 |
| 21 | `claim_status` | `TINYINT UNSIGNED` | Y | 0 | 理赔状态:`0`=未理赔,`1`=已理赔(单笔结清),`2`=月结 |
| 22 | `resolution` | `TEXT` | N | — | 处理结果说明 |
| 23 | `resolved_at` | `DATETIME` | N | — | 解决时间 |
| 24 | `created_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP` | 创建时间 |
| 25 | `updated_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP ON UPDATE` | 更新时间 |
| 26 | `deleted_at` | `DATETIME` | N | — | 软删除时间 |
**索引设计**:
| 索引名 | 字段 | 类型 | 说明 |
|--------|------|------|------|
| `PRIMARY` | `id` | 主键 | — |
| `uk_work_order_no` | `work_order_no` | 唯一 | 工单号唯一 |
| `idx_warehouse_id` | `warehouse_id` | 普通 | 按仓库查询 |
| `idx_store_id` | `store_id` | 普通 | 按货主查询 |
| `idx_business_type_subtype_id` | `business_type, business_sub_type, business_id` | 普通 | 按业务类型+子类型+单据ID反查工单 |
| `idx_status` | `status` | 普通 | 按状态筛选 |
| `idx_assignee_id` | `assignee_id` | 普通 | 按处理人查询 |
| `idx_parent_work_order_id` | `parent_work_order_id` | 普通 | 按父工单查所有子工单 |
| `idx_priority` | `priority` | 普通 | 按优先级排序 |
| `idx_claim_status` | `claim_status` | 普通 | 按理赔状态筛选 |
| `idx_created_at` | `created_at` | 普通 | 按时间排序 |
| `idx_deleted_at` | `deleted_at` | 普通 | 软删除查询 |
---
### 2.2 副表:`wms_after_sale_work_order_step`(售后工单进度步骤表)
| # | 字段名 | 类型 | 必填 | 默认值 | 说明 |
|---|--------|------|------|--------|------|
| 1 | `id` | `BIGINT(20) UNSIGNED` | Y | AUTO | 主键ID |
| 2 | `work_order_id` | `BIGINT(20) UNSIGNED` | Y | — | 工单ID,关联 `wms_after_sale_work_order.id` |
| 3 | `step_order` | `TINYINT UNSIGNED` | Y | 1 | 步骤序号(从1开始递增) |
| 4 | `step_name` | `VARCHAR(100)` | Y | — | 步骤名称 |
| 5 | `step_status` | `TINYINT UNSIGNED` | Y | 0 | 步骤状态:`0`=待开始,`1`=进行中,`2`=已完成,`3`=已跳过 |
| 6 | `operator_id` | `BIGINT(20) UNSIGNED` | N | — | 操作员工ID,关联 `account.id` |
| 7 | `operator_snapshot` | `TEXT` | N | — | 操作人信息快照(JSON格式) |
| 8 | `action` | `VARCHAR(100)` | N | — | 操作动作描述(如"核实问题属实,安排退货入库") |
| 9 | `remark` | `TEXT` | N | — | 处理备注 |
| 10 | `started_at` | `DATETIME` | N | — | 步骤开始时间 |
| 11 | `completed_at` | `DATETIME` | N | — | 步骤完成时间 |
| 12 | `created_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP` | 创建时间 |
| 13 | `updated_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP ON UPDATE` | 更新时间 |
| 14 | `deleted_at` | `DATETIME` | N | — | 软删除时间 |
**索引设计**:
| 索引名 | 字段 | 类型 | 说明 |
|--------|------|------|------|
| `PRIMARY` | `id` | 主键 | — |
| `idx_work_order_id` | `work_order_id` | 普通 | 按工单查所有步骤 |
| `idx_operator_id` | `operator_id` | 普通 | 按操作人反查 |
| `idx_deleted_at` | `deleted_at` | 普通 | 软删除查询 |
| `uk_work_order_step` | `work_order_id, step_order, deleted_at` | 唯一 | 同一工单下步骤序号唯一(含软删除) |
---
## 三、枚举定义
### 3.1 `business_type` 与 `business_sub_type`(业务类型及子类型)
业务类型和子类型由 Model 文件 `app/model/after_sale_work_order.js` 中的 `BUSINESS_TYPES` 常量统一定义。数据库层面使用 `VARCHAR(50)` 存储,方便扩展。
#### 内置业务类型总览
| business_type | 业务名称 | 关联表 | 子类型 (business_sub_type) |
|---------------|---------|--------|---------------------------|
| `waybill` | 运单 | `wms_order_express` | `intercept`(拦截)、`urge`(催件)、`damage`(破损)、`lost`(丢件)、`wrong_info`(信息错误) |
| `order_delivery` | 发货订单 | `wms_order_delivery` | `mis_shipment`(错发)、`missing_item`(少发)、`wrong_sku`(错品)、`quality_issue`(质量问题)、`delivery_delay`(发货延迟) |
| `entry_order` | 入库单 | `wms_entry_order` | `shortage`(少货)、`damage`(破损)、`wrong_sku`(错品)、`quality_issue`(质量问题) |
| `order_stockout` | 出库单/退货出库单 | `wms_order_stockout` | `return_issue`(退货异常)、`wrong_outbound`(错发)、`shortage`(少发) |
| `receiving` | 收货单 | `wms_receiving` | `shortage`(少货)、`damage`(破损)、`quality_issue`(质量问题) |
| `other` | 其他 | — | `general`(通用) |
> **扩展方式**:在 Model 的 `BUSINESS_TYPES` 常量中增删条目即可,无需 ALTER TABLE。外部代码通过 `require` Model 文件读取。
### 3.2 `priority`(优先级)
```
1 ~ 100 的整数,数字越大优先级越高。
由客服接待手动填入,或由 AI 根据问题描述自动识别并填入。
默认值 50(中等优先级)。
```
### 3.3 `direction`(记账方向)
```
0 — 未确定
1 — 入库(IN):退货入库 / 换货入库 / 赔付补货入库
2 — 出库(OUT):补发出库 / 换货出库 / 退款退货出库
```
> 与 `stock_transaction.transaction_type`(`INBOUND`/`OUTBOUND`)语义对齐。
### 3.4 `status`(工单状态)
```
0 — 待处理 (工单刚创建,尚未分配)
1 — 处理中 (已分配处理人,正在推进)
2 — 已完成 (问题已解决,全部步骤完成)
3 — 已关闭 (问题关闭,不再跟进)
9 — 已取消 (工单作废)
```
### 3.5 `claim_status`(理赔状态)
```
0 — 未理赔 (不需要理赔,或尚未发起理赔)
1 — 已理赔 (单笔已结清,理赔款项已到账)
2 — 月结 (纳入月度结算,按月统一对账打款)
```
### 3.6 `step_status`(步骤状态)
```
0 — 待开始 (步骤尚未激活)
1 — 进行中 (当前正在处理的步骤)
2 — 已完成 (步骤已处理完毕)
3 — 已跳过 (该步骤被跳过,不适用)
```
### 3.7 `creator_id` 特殊值
```
0 — AI 自动接待(非员工账号创建)
> 0 — 对应 account.id,人工客服/员工创建
```
> 当 `creator_id = 0` 时,`creator_snapshot` 可记录 AI 模型标识及会话 ID 等元信息。
---
## 四、状态流转设计
### 4.1 工单级别状态机
```
┌──────────────────────────────────┐
│ │
┌───┴──────┐ ┌───┴──────┐
创建工单 ───→ │ 待处理(0) │ ──── 分配处理人 ───→ │ 处理中(1) │
└───┬──────┘ └───┬──────┘
│ │
│ 取消 │ 全部步骤完成
↓ ↓
┌───┴──────┐ ┌───┴──────┐
│ 已取消(9) │ │ 已完成(2) │
└──────────┘ └───┬──────┘
│
│ 关闭
↓
┌───┴──────┐
│ 已关闭(3) │
└──────────┘
```
**流转规则**:
| 当前状态 | 允许流转到 | 触发条件 |
|----------|-----------|----------|
| `0-待处理` | `1-处理中` | 分配处理人 |
| `0-待处理` | `9-已取消` | 主动取消 |
| `1-处理中` | `2-已完成` | 所有步骤均标记为已完成 |
| `1-处理中` | `9-已取消` | 主动取消 |
| `2-已完成` | `3-已关闭` | 确认关闭 |
| `3-已关闭` | — | 终态,不可流转 |
### 4.2 步骤级别状态机
```
┌──────────────────────────────────┐
│ │
┌───┴──────┐ ┌───┴──────┐
步骤创建 ───→ │ 待开始(0) │ ──── 开始处理 ───→ │ 进行中(1) │
└───┬──────┘ └───┬──────┘
│ │
│ 跳过 │ 完成
↓ ↓
┌───┴──────┐ ┌───┴──────┐
│ 已跳过(3) │ │ 已完成(2) │
└──────────┘ └──────────┘
```
**约束**:
- 同一工单下,同一时刻最多只有 1 个步骤处于 `进行中(1)`
- 步骤按 `step_order` 顺序流转,但允许跳过中间步骤
- 工单进度由主表 `current_step` 字段追踪,指向当前正在处理的 `step_order`
- 所有步骤标记为 `已完成(2)` 或 `已跳过(3)` 后,`current_step` 置为最终步骤号,工单状态可流转至 `已完成(2)`
---
## 五、Model 内置业务类型定义
> **步骤不预设模板**:`wms_after_sale_work_order_step` 表的步骤由业务逻辑在运行时动态创建,不在数据库或 Model 中硬编码步骤模板。
### 5.1 `BUSINESS_TYPES` 常量(定义在 `app/model/after_sale_work_order.js`)
```javascript
/**
* 售后工单业务类型定义
* 外部可通过 require('./app/model/after_sale_work_order').BUSINESS_TYPES 访问
* 增删业务类型或子类型只需修改此常量,无需 ALTER TABLE
*/
const BUSINESS_TYPES = {
waybill: {
label: '运单',
table: 'wms_order_express', // 关联的数据库表名
subtypes: {
intercept: '拦截',
urge: '催件',
damage: '破损',
lost: '丢件',
wrong_info: '信息错误',
},
},
order_delivery: {
label: '发货订单',
table: 'wms_order_delivery',
subtypes: {
mis_shipment: '错发',
missing_item: '少发',
wrong_sku: '错品',
quality_issue: '质量问题',
delivery_delay: '发货延迟',
},
},
entry_order: {
label: '入库单',
table: 'wms_entry_order',
subtypes: {
shortage: '少货',
damage: '破损',
wrong_sku: '错品',
quality_issue: '质量问题',
},
},
order_stockout: {
label: '出库单/退货出库单',
table: 'wms_order_stockout',
subtypes: {
return_issue: '退货异常',
wrong_outbound: '错发',
shortage: '少发',
},
},
receiving: {
label: '收货单',
table: 'wms_receiving',
subtypes: {
shortage: '少货',
damage: '破损',
quality_issue: '质量问题',
},
},
other: {
label: '其他',
table: null,
subtypes: {
general: '通用',
},
},
};
// 辅助函数:根据 business_type 获取关联表名
function getBusinessTable(businessType) {
return BUSINESS_TYPES[businessType]?.table || null;
}
// 辅助函数:校验 business_type + business_sub_type 组合是否合法
function isValidSubType(businessType, businessSubType) {
const def = BUSINESS_TYPES[businessType];
return def && Object.prototype.hasOwnProperty.call(def.subtypes, businessSubType);
}
module.exports = { BUSINESS_TYPES, getBusinessTable, isValidSubType };
```
### 5.2 使用示例
```javascript
// 外部读取
const { BUSINESS_TYPES, getBusinessTable, isValidSubType } = require('./app/model/after_sale_work_order');
// 获取所有业务类型列表
Object.keys(BUSINESS_TYPES); // ['waybill', 'order_delivery', 'entry_order', ...]
// 获取运单下的子类型
BUSINESS_TYPES.waybill.subtypes; // { intercept: '拦截', urge: '催件', ... }
// 获取关联表
const table = getBusinessTable('waybill'); // 'wms_order_express'
// 校验合法性
isValidSubType('waybill', 'intercept'); // true
isValidSubType('waybill', 'mis_shipment'); // false
```
---
## 六、与现有系统的关联
### 6.1 与业务单据的多态关联(三级定位)
```
wms_after_sale_work_order
.business_type = 'waybill'
.business_sub_type = 'intercept' ← 子类型(Model 常量定义)
.business_id = 12345 ← wms_order_express.id
.business_no = 'YD202607280001' ← 冗余单号
实际关联链路:
business_type → BUSINESS_TYPES[type].table → 确定关联表
business_id → 关联表主键
business_sub_type → 细分工单类别(如拦截/催件/破损)
示例:
├── 'waybill' / 'intercept' → wms_order_express.id
├── 'waybill' / 'urge' → wms_order_express.id
├── 'waybill' / 'damage' → wms_order_express.id
├── 'order_delivery' / 'mis_shipment' → wms_order_delivery.id
├── 'order_delivery' / 'missing_item' → wms_order_delivery.id
├── 'entry_order' / 'shortage' → wms_entry_order.id
├── 'order_stockout' / 'return_issue' → wms_order_stockout.id
├── 'receiving' / 'damage' → wms_receiving.id
└── 'other' / 'general' → 自定义
```
### 6.2 与库存交易的对账
```
售后工单.direction = 1 (入库)
→ stock_transaction.transaction_type = 'INBOUND'
→ stock_transaction.order_type = 'AFTER_SALE' (需同步在 stock_transaction 中新增此类型)
售后工单.direction = 2 (出库)
→ stock_transaction.transaction_type = 'OUTBOUND'
→ stock_transaction.order_type = 'AFTER_SALE'
```
### 6.4 与附件的关联
售后工单不新增附件字段,复用现有 `wms_file_reference` 表做多态附件关联:
```
wms_file_reference
.reference_type = 'after_sale_work_order' ← 固定标识
.reference_id = 工单 id ← wms_after_sale_work_order.id
.file_id = 文件 id ← wms_file.id
示例:一张工单可关联多张图片/多个附件(如破损照片、快递面单照片等)。
```
> `file_reference` 表已支持多态关联(`reference_type` + `reference_id`),无需新建表或字段。
### 6.5 与员工的关联
```
wms_after_sale_work_order.creator_id → account.id(创建人)
wms_after_sale_work_order.assignee_id → account.id(当前处理人)
wms_after_sale_work_order_step.operator_id → account.id(步骤操作人)
```
---
## 七、待确认事项(审阅清单)
请审阅时重点关注以下设计决策:
- [x] **1. `business_type` 枚举值**:`order_delivery` / `entry_order` / `order_stockout` / `waybill` / `receiving` / `other` — ✅ 已确认,暂不增加 `return_order` 独立类型(退货场景通过 `order_stockout` 覆盖)
- [x] **2. `direction` 记账方向**:`1`=入库 / `2`=出库 / `0`=未确定 — ✅ 已确认,细粒度区分由关联的实际出入库单承载
- [x] **3. 工单状态值**:`0-待处理/1-处理中/2-已完成/3-已关闭/9-已取消` — ✅ 已确认,当前中间态足够,无需增加"驳回/退回"
- [x] **4. 预设步骤模板**:不再预设步骤模板,步骤由业务逻辑动态创建 ✅
- [x] **5. `business_id` 多态关联**:采用 `business_type` + `business_sub_type` + `business_id` 三级多态关联,子类型由 Model 常量定义 ✅
- [x] **6. 理赔信息**:已新增 `claim_needed` / `claim_amount` / `claim_status` 三个字段 ✅
- [x] **7. 进度追踪**:进度由主表 `current_step` 字段承载(不再仅依赖副表步骤状态) ✅
- [x] **8. 优先级**:改为 `TINYINT UNSIGNED` 取值范围 `1-100`,由客服或 AI 自动识别填入,默认值 `50` ✅
- [x] **9. AI 创建支持**:`creator_id = 0` 表示 AI 自动接待,`creator_snapshot` 记录模型/会话信息 ✅
- [x] **10. 附件/图片**:复用现有 `wms_file_reference` 表做多态关联,不新增字段 ✅
- [x] **11. 预计完成时间**:暂不增加,后续通过 `created_at` + `priority` 做超时告警替代;SLA 配置表留待后续迭代 ✅
- [x] **12. 关联工单**:已确认新增 `parent_work_order_id` 字段,支持主子工单拆分 ✅
- [x] **13. 表名**:`wms_after_sale_work_order` 和 `wms_after_sale_work_order_step` — ✅ 已确认
- [x] **14. 权限**:API 接口设计阶段再补录 `wms_permission` 记录,不阻塞表落库 ✅
---
## 八、后续落库计划(审阅通过后执行)
1. 创建迁移文件 `database/migrations/20260728XXXXXX-create-wms-after-sale-work-order.js`
2. 创建迁移文件 `database/migrations/20260728XXXXXX-create-wms-after-sale-work-order-step.js`
3. 创建 Model 文件 `app/model/after_sale_work_order.js`
4. 创建 Model 文件 `app/model/after_sale_work_order_step.js`
5. 在 `methods/system.json` 中新增接口路由
6. 如需,在 `stock_transaction.order_type` 中新增 `AFTER_SALE` 枚举值(独立迁移)
7. 如需,新增 `wms_permission` 权限记录