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

21 KiB
Raw Blame History

售后工单表设计方案

状态: ✅ 已落库(开发环境)
设计日期: 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)

/**
 * 售后工单业务类型定义
 * 外部可通过 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 记录,不阻塞表落库 ✅

八、后续落库计划(审阅通过后执行)

  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 权限记录