21 KiB
21 KiB
售后工单表设计方案
状态: ✅ 已落库(开发环境)
设计日期: 2026-07-28(v4 定稿:新增 parent_work_order_id 支持主子工单)
设计人: wms-db-agent
说明: 本文档仅输出设计方案,不执行落库。审阅通过后再生成迁移文件。
一、需求概述
- 主表:售后工单单表,支持灵活绑定多种业务单据(运单、订单、入库单、退货单等),通过
business_type+business_sub_type+business_id三级多态关联 - 副表:进度步骤处理表,记录每一步的操作员工、动作、备注(步骤不预设模板,由业务逻辑动态创建)
- 状态流转:工单整体状态 + 主表
current_step进度 + 步骤级状态三层次 - 简单记账:记录是"进"还是"出"
- 理赔追踪:是否需要理赔、理赔金额、理赔结算状态
- 附件关联:通过现有
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。外部代码通过requireModel 文件读取。
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)
/**
* 售后工单业务类型定义
* 外部可通过 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 使用示例
// 外部读取
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(步骤操作人)
七、待确认事项(审阅清单)
请审阅时重点关注以下设计决策:
- 1.
business_type枚举值:order_delivery/entry_order/order_stockout/waybill/receiving/other— ✅ 已确认,暂不增加return_order独立类型(退货场景通过order_stockout覆盖) - 2.
direction记账方向:1=入库 /2=出库 /0=未确定 — ✅ 已确认,细粒度区分由关联的实际出入库单承载 - 3. 工单状态值:
0-待处理/1-处理中/2-已完成/3-已关闭/9-已取消— ✅ 已确认,当前中间态足够,无需增加"驳回/退回" - 4. 预设步骤模板:不再预设步骤模板,步骤由业务逻辑动态创建 ✅
- 5.
business_id多态关联:采用business_type+business_sub_type+business_id三级多态关联,子类型由 Model 常量定义 ✅ - 6. 理赔信息:已新增
claim_needed/claim_amount/claim_status三个字段 ✅ - 7. 进度追踪:进度由主表
current_step字段承载(不再仅依赖副表步骤状态) ✅ - 8. 优先级:改为
TINYINT UNSIGNED取值范围1-100,由客服或 AI 自动识别填入,默认值50✅ - 9. AI 创建支持:
creator_id = 0表示 AI 自动接待,creator_snapshot记录模型/会话信息 ✅ - 10. 附件/图片:复用现有
wms_file_reference表做多态关联,不新增字段 ✅ - 11. 预计完成时间:暂不增加,后续通过
created_at+priority做超时告警替代;SLA 配置表留待后续迭代 ✅ - 12. 关联工单:已确认新增
parent_work_order_id字段,支持主子工单拆分 ✅ - 13. 表名:
wms_after_sale_work_order和wms_after_sale_work_order_step— ✅ 已确认 - 14. 权限:API 接口设计阶段再补录
wms_permission记录,不阻塞表落库 ✅
八、后续落库计划(审阅通过后执行)
- 创建迁移文件
database/migrations/20260728XXXXXX-create-wms-after-sale-work-order.js - 创建迁移文件
database/migrations/20260728XXXXXX-create-wms-after-sale-work-order-step.js - 创建 Model 文件
app/model/after_sale_work_order.js - 创建 Model 文件
app/model/after_sale_work_order_step.js - 在
methods/system.json中新增接口路由 - 如需,在
stock_transaction.order_type中新增AFTER_SALE枚举值(独立迁移) - 如需,新增
wms_permission权限记录