新增: - order.recheckOrder.interceptScan: 拦截扫描接口,入参运单号,查express标记退回,处理工单,更新订单拦截状态 - afterSale.createInterceptWorkOrdersAndNotify: 共享方法,幂等创建工单+通知快递群 修复: - confirmIntercept: 补运单is_back同步(仅限is_intercept=Y),补工单创建+通知 - batchIntercept: 补运单is_intercept同步,补工单创建+通知 - batchUnintercept: 补运单is_intercept/is_back清除 - Qimen/OpenAPI cancel: 补运单is_intercept同步,补工单创建+通知 - interceptScan: 删除死查询,加空指针兜底 文档: - methods/system.json: interceptScan + confirmIntercept 完整API文档 - methods/changes/system.json: 变更记录
41 KiB
售后模块 V2 设计方案
状态: 📋 v1 初稿,待评审
设计日期: 2026-08-09
设计人: wms-doc-agent
模块: 售后管理(After-Sale)
表: 2 张 —wms_after_sale(售后主表)、wms_after_sale_detail(售后进度步骤表)
说明: 本文档为全新设计,替代已移除的旧版wms_after_sale_work_order+wms_after_sale_work_order_step体系。
一、设计背景
1.1 旧版问题
旧版售后工单(after_sale_work_order + after_sale_work_order_step)已于 2026-08-09 通过迁移 20260809120000-drop-wms-after-sale-work-order.js 正式移除。旧版存在以下核心问题:
- 多态关联难以维护:使用
business_type+business_sub_type+business_id三元组关联业务单据,导致:- 查询需要动态拼接 JOIN 条件,性能差
- 无法利用数据库外键约束保证数据完整性
- 业务类型枚举膨胀,新增业务类型需改动多处代码
- 不支持多单据共存:一个售后单只能关联一种业务单据,实际场景中退货退款往往同时涉及运单、发货订单、收货单等多张单据
- 覆盖场景不足:旧版仅覆盖工单流转,未涵盖理赔、投诉等售后场景
- 缺少明细层级:无法记录售后单中的商品明细(退什么货、换什么货、赔多少钱)
1.2 V2 设计目标
| 目标 | 说明 |
|---|---|
| 废弃多态关联 | 每种业务单据使用独立字段,类型安全、查询高效 |
| 支持多单据共存 | 一个售后单可同时关联运单、发货订单、入库单、出库单、收货单等 |
| 覆盖全场景 | 按单据维度分类(订单/收货单/入库单/出库单),售后动作(退货/换货/理赔/投诉等)通过进度步骤体现 |
| 进度追溯 | wms_after_sale_detail 记录售后处理进度步骤,支持按步骤序号追踪操作人、操作动作、处理时间 |
| 可追溯 | 完整记录创建人、处理人、最终处理结果、完结时间 |
1.3 与旧版核心差异
| 维度 | 旧版(已移除) | V2(本设计) |
|---|---|---|
| 主表 | wms_after_sale_work_order |
wms_after_sale |
| 子表 | wms_after_sale_work_order_step(工单步骤流转) |
wms_after_sale_detail(售后进度步骤) |
| 单据关联 | 多态三元组 business_type + business_sub_type + business_id |
每种单据独立字段组,可多个同时有值 |
| 多单据共存 | ❌ 不支持 | ✅ 支持 |
| 理赔 | ❌ 不支持 | ✅ 内建仓库理赔(claim_needed / claim_amount / claim_status)和运方理赔(carrier_claim_needed / carrier_claim_amount / carrier_claim_status) |
| 进度步骤 | ❌ after_sale_work_order_step |
✅ wms_after_sale_detail 记录步骤序号/操作人/操作动作/耗时 |
| 商品明细 | ❌ 无 | ❌ 不再独立建表,商品明细可存入 remark 或扩展 JSON 字段 |
二、ER 图
erDiagram
wms_after_sale ||--o{ wms_after_sale_detail : "1:N"
wms_after_sale {
BIGINT id PK "主键"
BIGINT warehouse_id "仓库ID"
BIGINT store_id "货主ID"
VARCHAR after_sale_no UK "售后单号,唯一"
VARCHAR type "售后类型"
VARCHAR sub_type "售后子类型"
VARCHAR status "状态"
INT priority "优先级"
VARCHAR title "标题"
TEXT description "描述"
BIGINT creator_id "创建人"
BIGINT inbox_message_id "关联消息ID"
VARCHAR role_group "角色组"
TEXT resolution "最终处理结果"
DATETIME resolved_at "完结时间"
TINYINT claim_needed "仓库理赔标记"
DECIMAL claim_amount "仓库理赔金额(元)"
VARCHAR claim_status "仓库理赔状态"
TINYINT carrier_claim_needed "运方理赔标记"
DECIMAL carrier_claim_amount "运方理赔金额(元)"
VARCHAR carrier_claim_status "运方理赔状态"
BIGINT waybill_id "运单ID"
VARCHAR waybill_no "运单号"
BIGINT order_delivery_id "发货订单ID"
VARCHAR order_delivery_no "发货订单号"
BIGINT entry_order_id "入库单ID"
VARCHAR entry_order_no "入库单号"
BIGINT order_stockout_id "出库单ID"
VARCHAR order_stockout_no "出库单号"
BIGINT receiving_id "收货单ID"
VARCHAR receiving_no "收货单号"
DATETIME created_at "创建时间"
DATETIME updated_at "更新时间"
DATETIME deleted_at "软删除"
}
wms_after_sale_detail {
BIGINT id PK "主键"
BIGINT after_sale_id FK "关联售后主表"
VARCHAR step_status "步骤记录时主表状态"
BIGINT operator_id "操作人ID"
TEXT operator_snapshot "操作人信息快照"
VARCHAR action "操作动作"
TEXT remark "处理备注"
DATETIME started_at "步骤开始时间"
DATETIME completed_at "步骤完成时间"
DATETIME created_at "创建时间"
DATETIME updated_at "更新时间"
DATETIME deleted_at "软删除"
}
关联关系说明
wms_after_sale
├─ warehouse_id → stores.id(仓库,逻辑关联)
├─ store_id → stores.id(货主,逻辑关联)
├─ creator_id → accounts.id(创建人,逻辑关联)
├─ inbox_message_id → wms_inbox_message.id(站内信消息,逻辑关联)
├─ waybill_id → wms_order_express.id(运单,逻辑关联)
├─ order_delivery_id → wms_order_delivery.id(发货订单,逻辑关联)
├─ entry_order_id → wms_entry_order.id(入库单,逻辑关联)
├─ order_stockout_id → wms_order_stockout.id(出库单,逻辑关联)
└─ receiving_id → wms_receiving.id(收货单,逻辑关联)
wms_after_sale_detail
└─ after_sale_id → wms_after_sale.id(级联删除)
注意:所有关联均为逻辑关联(不做物理外键),遵循项目现有惯例。
三、数据库表
3.1 表 A:售后主表 wms_after_sale
3.1.1 基础字段
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
id |
BIGINT UNSIGNED |
✅ | AUTO | 主键 |
warehouse_id |
BIGINT UNSIGNED |
✅ | — | 仓库ID |
store_id |
BIGINT UNSIGNED |
— | NULL | 货主ID |
3.1.2 售后信息
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
after_sale_no |
VARCHAR(50) |
✅ | — | 售后单号,唯一索引。生成规则:前缀 AS + 日期 YYYYMMDD + 6 位序号(当天同仓库自增),如 AS20260809000001。参考波次号 wave_no 生成逻辑。 |
type |
VARCHAR(20) |
✅ | — | 售后类型,枚举见 §3.1.6 |
sub_type |
VARCHAR(50) |
✅ | — | 售后子类型,枚举见 §3.1.6,与 type 组成二级分类 |
status |
VARCHAR(20) |
✅ | pending |
售后状态,枚举及流转见 §五 |
priority |
INT(11) |
✅ | 0 | 优先级,数值越大越优先(0=普通,10=紧急) |
title |
VARCHAR(200) |
✅ | — | 售后标题(简要描述) |
description |
TEXT |
— | NULL | 售后详细描述 |
3.1.3 人员信息
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
creator_id |
BIGINT UNSIGNED |
✅ | — | 创建人账户ID(关联 accounts 表) |
role_group |
VARCHAR(50) |
— | NULL | 当前处理角色组,用于角色维度查询待处理工单和转单。枚举见 §3.1.6。NULL 表示未分配。 |
inbox_message_id |
BIGINT UNSIGNED |
— | NULL | 关联 wms_inbox_message.id(站内信消息主键)。为空表示无关联信息,非空表示该售后单由对应站内信消息创建或关联。 |
3.1.4 处理结果
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
resolution |
TEXT |
— | NULL | 最终处理结果说明 |
resolved_at |
DATETIME |
— | NULL | 完结时间(状态变为 completed 时写入) |
3.1.5 仓库理赔 & 运方理赔
仓库理赔:
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
claim_needed |
TINYINT(1) |
✅ | 0 | 仓库理赔标记:0=不需要,1=需要 |
claim_amount |
DECIMAL(12,2) |
— | NULL | 仓库理赔金额,单位:人民币(元),claim_needed=1 时可填写 |
claim_status |
VARCHAR(20) |
— | NULL | 仓库理赔状态,枚举见 §3.1.6,仅 claim_needed=1 时有意义 |
运方理赔:
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
carrier_claim_needed |
TINYINT(1) |
✅ | 0 | 运方理赔标记:0=不需要,1=需要 |
carrier_claim_amount |
DECIMAL(12,2) |
— | NULL | 运方理赔金额,单位:人民币(元),carrier_claim_needed=1 时可填写 |
carrier_claim_status |
VARCHAR(20) |
— | NULL | 运方理赔状态,枚举见 §3.1.6,仅 carrier_claim_needed=1 时有意义 |
3.1.6 类型与状态枚举
售后类型 type + 售后子类型 sub_type:
售后类型表示售后单主要关联的业务单据类型,售后子类型表示具体售后原因分类,两者组成二级分类。具体的售后动作(退货/换货/理赔/投诉等)通过进度步骤和最终处理结果体现。
| type | 说明 | sub_type |
|---|---|---|
order |
订单 | damage 破损, missing_item 少发, mis_shipment 错发, wrong_sku 错品, quality_issue 质量问题, delivery_delay 发货延迟, logistics_issue 物流异常, rejected 客户拒收, intercept 拦截, verify_delivery 核实签收, urge 催件, extra_item 多发, change_address 改地址, change_carrier 换快递, weight_issue 重量异常, freight_issue 运费争议, other 其他 |
receiving |
收货单 | shortage 少货, damage 破损, wrong_sku 错品, quality_issue 质量问题, other 其他 |
entry |
入库单 | shortage 少货, damage 破损, wrong_sku 错品, quality_issue 质量问题, other 其他 |
stockout |
出库单 | return_issue 退货异常, wrong_outbound 错发, shortage 少发, other 其他 |
Model 层常量定义(app/model/after_sale.js):
// app/model/after_sale.js 中的常量定义
const AFTER_SALE_TYPES = [
{
name: '订单',
type: 'order',
subType: [
{ name: '破损', value: 'damage' },
{ name: '少发', value: 'missing_item' },
{ name: '错发', value: 'mis_shipment' },
{ name: '错品', value: 'wrong_sku' },
{ name: '质量问题', value: 'quality_issue' },
{ name: '发货延迟', value: 'delivery_delay' },
{ name: '物流异常', value: 'logistics_issue' },
{ name: '客户拒收', value: 'rejected' },
{ name: '拦截', value: 'intercept' },
{ name: '核实签收', value: 'verify_delivery' },
{ name: '催件', value: 'urge' },
{ name: '多发', value: 'extra_item' },
{ name: '改地址', value: 'change_address' },
{ name: '换快递', value: 'change_carrier' },
{ name: '重量异常', value: 'weight_issue' },
{ name: '运费争议', value: 'freight_issue' },
{ name: '其他', value: 'other' },
],
},
{
name: '收货单',
type: 'receiving',
subType: [
{ name: '少货', value: 'shortage' },
{ name: '破损', value: 'damage' },
{ name: '错品', value: 'wrong_sku' },
{ name: '质量问题', value: 'quality_issue' },
{ name: '其他', value: 'other' },
],
},
{
name: '入库单',
type: 'entry',
subType: [
{ name: '少货', value: 'shortage' },
{ name: '破损', value: 'damage' },
{ name: '错品', value: 'wrong_sku' },
{ name: '质量问题', value: 'quality_issue' },
{ name: '其他', value: 'other' },
],
},
{
name: '出库单',
type: 'stockout',
subType: [
{ name: '退货异常', value: 'return_issue' },
{ name: '错发', value: 'wrong_outbound' },
{ name: '少发', value: 'shortage' },
{ name: '其他', value: 'other' },
],
},
];
角色组 role_group:
| 值 | 说明 |
|---|---|
customer_service |
客服组 |
warehouse |
仓库组 |
finance |
财务组 |
设计理由:运方(快递公司)是外部角色,不登录 WMS 系统,不纳入内部角色组。
售后状态 status:
| 值 | 说明 |
|---|---|
pending |
待处理 |
processing |
处理中 |
pending_feedback |
等待外部反馈(内部处理完成,等待外部反馈后再决定是否继续处理) |
completed |
已完成 |
closed |
已关闭 |
cancelled |
已取消 |
理赔状态(仓库理赔 & 运方理赔通用枚举):
| 值 | 说明 |
|---|---|
pending |
待理赔 |
reviewing |
审核中 |
approved |
已通过 |
paid |
已打款 |
monthly |
月结 |
rejected |
已拒绝 |
3.1.7 单据关联字段(核心设计)
设计要点:每种业务单据使用独立字段组(ID + 单号冗余),替代旧版多态关联。多个字段组可同时有值,实现"一个售后单关联多种单据"。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
waybill_id |
BIGINT UNSIGNED |
— | NULL | 运单ID(关联 wms_order_express.id) |
waybill_no |
VARCHAR(50) |
— | NULL | 运单号(冗余字段,方便查询展示) |
order_delivery_id |
BIGINT UNSIGNED |
— | NULL | 发货订单ID(关联 wms_order_delivery.id) |
order_delivery_no |
VARCHAR(50) |
— | NULL | 发货订单号(冗余字段) |
entry_order_id |
BIGINT UNSIGNED |
— | NULL | 入库单ID(关联 wms_entry_order.id) |
entry_order_no |
VARCHAR(50) |
— | NULL | 入库单号(冗余字段) |
order_stockout_id |
BIGINT UNSIGNED |
— | NULL | 出库单/退货出库单ID(关联 wms_order_stockout.id) |
order_stockout_no |
VARCHAR(50) |
— | NULL | 出库单号(冗余字段) |
receiving_id |
BIGINT UNSIGNED |
— | NULL | 收货单ID(关联 wms_receiving.id) |
receiving_no |
VARCHAR(50) |
— | NULL | 收货单号(冗余字段) |
冗余字段说明:
_no后缀字段为冗余存储,目的是在售后列表查询时避免 JOIN 各业务表。写入时从对应业务表同步取数,后续若业务表单号变更需同步更新(建议通过业务 hook 或定时任务保证最终一致)。
3.1.8 时间戳
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
created_at |
DATETIME |
✅ | CURRENT_TIMESTAMP |
创建时间 |
updated_at |
DATETIME |
✅ | CURRENT_TIMESTAMP ON UPDATE |
更新时间 |
deleted_at |
DATETIME |
— | NULL | 软删除时间 |
3.2 表 B:售后进度步骤表 wms_after_sale_detail
用于记录售后单的处理进度步骤(谁在什么时间做了什么操作)。步骤按 created_at 自然时间排序,通过 action 描述步骤内容,可记录步骤开始/完成时间、操作人及操作快照。
3.2.1 字段定义
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
id |
BIGINT UNSIGNED |
✅ | AUTO | 主键 |
after_sale_id |
BIGINT UNSIGNED |
✅ | — | 关联售后主表ID(wms_after_sale.id) |
step_status |
VARCHAR(20) |
✅ | processing |
步骤记录时售后主表的状态,与 wms_after_sale.status 完全一致: pending / processing / completed / closed / cancelled。每次写入步骤时取主表当前 status 快照 |
operator_id |
BIGINT UNSIGNED |
— | NULL | 操作人账户ID(关联 accounts 表);可为空,外部系统回调/自动触发的步骤无人操作 |
operator_snapshot |
TEXT |
— | NULL | 操作人信息快照(JSON),如 {"name":"张三","role":"客服"},防止账户删除后历史丢失 |
action |
VARCHAR(100) |
— | NULL | 操作动作描述,如"确认收货"、"审核驳回"、"发起退款" |
remark |
TEXT |
— | NULL | 处理备注 |
started_at |
DATETIME |
— | NULL | 步骤开始时间 |
completed_at |
DATETIME |
— | NULL | 步骤完成时间 |
created_at |
DATETIME |
✅ | CURRENT_TIMESTAMP |
创建时间 |
updated_at |
DATETIME |
✅ | CURRENT_TIMESTAMP ON UPDATE |
更新时间 |
deleted_at |
DATETIME |
— | NULL | 软删除时间 |
3.2.2 步骤状态 step_status 说明
step_status 与 wms_after_sale.status 完全一致(类型、枚举均相同),每次写入步骤时记录步骤发生时主表的当前状态快照。枚举值:
| 值 | 说明 |
|---|---|
pending |
待处理 |
processing |
处理中 |
completed |
已完成 |
closed |
已关闭 |
cancelled |
已取消 |
设计考量:
step_status记录的是"该步骤发生时,售后主表处于什么状态",而非步骤本身的"进行中/已完成"标记。这使得每条步骤都能直接追溯到该步骤执行时的工单状态上下文,无需 JOIN 主表查阅历史状态。步骤按created_at自然时间排序。
3.2.3 附件关联
售后进度步骤可通过 wms_file_reference 表挂载附件(如破损照片、签收凭证、理赔单据等)。
绑定方式:
| wms_file_reference 字段 | 值 | 说明 |
|---|---|---|
business_type |
after_sale_detail |
售后进度步骤 |
business_id |
{wms_after_sale_detail.id} |
步骤主键ID |
典型场景:
- 仓库验货步骤上传破损商品照片
- 客服接单步骤上传客户提供的聊天截图
- 运方理赔步骤上传快递破损证明
- 退款步骤上传打款凭证截图
查询示例:
-- 查询某售后单所有步骤的附件
SELECT f.*, fr.business_id AS step_id
FROM wms_file_reference fr
JOIN wms_file f ON f.id = fr.file_id
WHERE fr.business_type = 'after_sale_detail'
AND fr.business_id IN (
SELECT id FROM wms_after_sale_detail WHERE after_sale_id = ?
);
四、索引设计
4.1 wms_after_sale 索引
| 索引名 | 字段 | 类型 | 说明 |
|---|---|---|---|
PRIMARY |
id |
主键 | — |
uk_after_sale_no |
after_sale_no |
唯一 | 售后单号唯一约束 |
idx_warehouse_status |
warehouse_id, status, deleted_at |
普通 | 按仓库+状态查询售后列表(最高频) |
idx_warehouse_type |
warehouse_id, type, deleted_at |
普通 | 按仓库+类型筛选 |
idx_type_subtype |
warehouse_id, type, sub_type, deleted_at |
普通 | 按仓库+类型+子类型筛选 |
idx_store_id |
store_id, deleted_at |
普通 | 按货主查询 |
idx_creator_id |
creator_id, deleted_at |
普通 | 按创建人查询 |
idx_role_group |
role_group, status, deleted_at |
普通 | 按角色组+状态查询待处理工单(角色维度) |
idx_created_at |
warehouse_id, created_at |
普通 | 按仓库+时间排序分页 |
idx_waybill_id |
waybill_id |
普通 | 按运单反查售后单 |
idx_order_delivery_id |
order_delivery_id |
普通 | 按发货订单反查售后单 |
idx_entry_order_id |
entry_order_id |
普通 | 按入库单反查售后单 |
idx_order_stockout_id |
order_stockout_id |
普通 | 按出库单反查售后单 |
idx_receiving_id |
receiving_id |
普通 | 按收货单反查售后单 |
idx_carrier_claim_status |
carrier_claim_status |
普通 | 按运方理赔状态筛选 |
idx_inbox_message_id |
inbox_message_id |
普通 | 按站内信消息反查售后单 |
4.2 wms_after_sale_detail 索引
| 索引名 | 字段 | 类型 | 说明 |
|---|---|---|---|
PRIMARY |
id |
主键 | — |
idx_after_sale_id |
after_sale_id |
普通 | 按售后单查询进度步骤(最高频) |
idx_operator_id |
operator_id |
普通 | 按操作人查询其处理的步骤 |
五、状态流转
stateDiagram-v2
[*] --> pending: 创建售后单
pending --> processing: 指派处理人 / 开始处理
pending --> cancelled: 取消
processing --> pending_feedback: 内部处理完毕,等待外部反馈
processing --> completed: 处理完成
processing --> closed: 强制关闭
pending_feedback --> processing: 收到外部反馈,继续处理
pending_feedback --> completed: 外部反馈确认完成
completed --> [*]
closed --> [*]
cancelled --> [*]
| 流转 | 触发条件 | 说明 |
|---|---|---|
pending → processing |
指派处理人 or 手动开始处理 | 通过 wms_after_sale_detail 记录的处理步骤追踪 |
pending → cancelled |
创建人取消 | 仅待处理状态可取消 |
processing → pending_feedback |
内部处理完毕,等待外部反馈 | 如已将拦截信息发给运方,等待运方反馈拦截结果 |
processing → completed |
处理完毕 | 写入 resolution + resolved_at |
processing → closed |
管理员强制关闭 | 如重复单、无效单等 |
pending_feedback → processing |
收到外部反馈,继续处理 | 如运方反馈已拦截/未拦截,回到内部通知客户 |
pending_feedback → completed |
外部反馈确认完成 | 如平台退款回调确认到账 |
理赔状态流转(仓库理赔 & 运方理赔通用):pending → reviewing → approved → paid,任意阶段可 → rejected,或走 monthly(月结)通道。
wms_after_sale_detail即操作日志:每条进度步骤记录操作人、操作动作、处理备注、开始/完成时间,已完整覆盖状态变更追踪需求,无需额外日志表。
六、典型使用场景
场景1:订单售后(退货退款,关联运单 + 收货单)
售后单 type=order, sub_type=damage, role_group=customer_service
├─ inbox_message_id: 12345(关联站内信消息,客户发送"破损"指令触发)
├─ waybill_id / waybill_no: 客户寄回的快递单号
├─ receiving_id / receiving_no: 仓库收货单
└─ 进度步骤:
├─ step_status=processing, operator_id=1001, action=客服接单-受理退货申请
├─ step_status=processing, operator_id=2001, action=仓库收货-确认收货入库
└─ step_status=processing, action=退款打款
转单说明:当客服接单后发现需要仓库核实实物时,可将
role_group从customer_service更新为warehouse,仓库组即可在自己的待办列表中看到该工单。
场景2:订单售后(换货,关联运单 + 发货订单)
售后单 type=order, sub_type=quality_issue
├─ waybill_id / waybill_no: 客户寄回的快递单号
├─ order_delivery_id / order_delivery_no: 仓库补发的发货订单
└─ 进度步骤:
├─ step_status=processing, action=客服接单-确认换货申请
├─ step_status=processing, action=退回入库-客户退回商品已入库
└─ step_status=processing, action=补发换货-仓库补发新商品
场景3:订单售后(仓库理赔)
售后单 type=order, sub_type=damage
├─ claim_needed=1, claim_amount=50.00, claim_status=pending
└─ 进度步骤:
├─ step_status=processing, action=客服接单-受理仓库理赔
├─ step_status=processing, action=核实定损, remark=仓库出库破损, 核定赔偿50元
└─ step_status=processing, action=审批打款
场景3b:订单售后(运方理赔)
售后单 type=order, sub_type=logistics_issue
├─ carrier_claim_needed=1, carrier_claim_amount=200.00, carrier_claim_status=pending
├─ waybill_id / waybill_no: 涉损运单
└─ 进度步骤:
├─ step_status=processing, action=客服接单-受理运方理赔
├─ step_status=processing, action=核实定损, remark=运输途中破损, 核定赔偿200元
└─ step_status=processing, action=快递审批
说明:仓库理赔与运方理赔可同时存在(如货物在仓库出库&运输途中均发生破损),分别使用
claim_*和carrier_claim_*字段组记录。
场景4:订单售后(多单据共存:退货退款 + 运单 + 收货单 + 出库单)
售后单 type=order, sub_type=damage, role_group=warehouse
├─ waybill_id / waybill_no: 客户退货快递
├─ receiving_id / receiving_no: 仓库收货单
├─ order_stockout_id / order_stockout_no: 退货出库单
└─ 进度步骤:
├─ step_status=processing, action=客服接单-批量退货受理
├─ step_status=processing, operator_id=3001, action=验货签收, remark=SKU001×3, SKU002×1 均完好(可挂附件:破损照片 × 2)
├─ step_status=processing, action=退货入库
└─ step_status=processing, action=退款打款
说明:此场景中
role_group=warehouse表示当前由仓库组负责验货入库环节;验货完成后如需财务退款,转单时将role_group更新为finance。
七、迁移计划
7.1 迁移文件
database/migrations/YYYYMMDDHHMMSS-create-wms-after-sale.js
database/migrations/YYYYMMDDHHMMSS-create-wms-after-sale-detail.js
7.2 Model 文件
app/model/after_sale.js → wms_after_sale
app/model/after_sale_detail.js → wms_after_sale_detail
7.3 后续扩展(不纳入本期)
| 扩展项 | 说明 |
|---|---|
| 批量创建 | 按运单号/订单号批量生成售后单 |
| 自动创建规则 | 如收到退货快递自动创建售后单 |
| 售后统计看板 | 按仓库/类型/状态统计售后量、理赔金额等 |
八、版本记录
| 版本 | 日期 | 变更内容 | 作者 |
|---|---|---|---|
| v1 | 2026-08-09 | 初稿,待评审 | wms-doc-agent |
九、权限设计
售后模块的角色组通过 wms_permission 表中 type='block' 的权限条目来承载,与主表 role_group 字段一一对应。
9.1 Block 权限(角色组区分)
ID 516-523 为售后模块固定 ID。
| ID | meta_title | type | 对应 role_group |
|---|---|---|---|
| 516 | 售后-客服组 | block |
customer_service |
| 517 | 售后-仓库组 | block |
warehouse |
| 518 | 售后-财务组 | block |
finance |
生产组主管(role_code=03)和拣货组组长(role_code=021)使用仓库组 block(517),共享仓库组视角。
9.2 页面权限
| ID | path | meta_title | type | parent_id |
|---|---|---|---|---|
| 519 | afterSale |
售后管理 | web_pages |
null |
| 520 | afterSale.list |
售后列表 | web_pages |
519 |
| 521 | afterSale.detail |
售后明细 | web_pages |
519 |
9.3 API 权限
| ID | path | meta_title | type |
|---|---|---|---|
| 522 | afterSale.workList |
API:售后工作列表查询 | api |
| 523 | afterSale.auditList |
API:售后审计列表查询 | api |
| 508 | afterSale.detail |
API:售后明细查询 | api |
| 509 | afterSale.create |
API:创建售后单 | api |
| 510 | afterSale.update |
API:更新售后单 | api |
| 511 | afterSale.transfer |
API:售后转单 | api |
| 512 | afterSale.handleWorkOrder |
API:处理工单 | api |
| 513 | afterSale.registerClaim |
API:登记理赔 | api |
| 514 | afterSale.export |
API:售后导出 | api |
| 515 | afterSale.exportTaskProgress |
API:导出进度查询 | api |
9.4 角色权限绑定
| 角色 | 角色组 block | 页面 | API |
|---|---|---|---|
| 客服 | 516 | 519, 520, 521 | 522, 523, 508, 509, 510, 511, 512, 513, 514, 515 |
| 仓库 | 517 | 519, 520, 521 | 522, 508, 510, 512 |
| 生产组-主管 | 517 | 519, 520, 521 | 522, 508, 510, 512 |
| 拣货组-组长 | 517 | 519, 520, 521 | 522, 508, 510, 512 |
| 财务 | 518 | 519, 520, 521 | 522, 508 |
| 经理 | — | 519, 520, 521 | 522, 523, 508, 509, 510, 511, 512, 513, 514, 515 |
- 客服:全部权限(创建、更新、转单、查理赔)
- 仓库:只读查询 + 更新处理结果
- 生产组-主管 / 拣货组-组长:共享仓库组视角(同仓库组权限),处理退货验货入库等实物操作。普通生产组员工不授权任何售后权限。
- 财务:只读查询(理赔审核通过财务系统操作,不走 WMS)
- 经理:全部售后权限
生产组其他角色(普通员工、复核、其他普工)不授权任何售后权限。 财务组角色:role_code=
finance,role_name=财务组,自动创建并授权。
十、Methods API 设计
10.1 概述
售后模块 API method 统一以 afterSale. 为前缀,使用 /system 网关接入。工作列表与审计列表分离,导出采用异步任务模式。
10.2 列表一:工作列表 afterSale.workList
定位:仓库内员工看到自己角色组需要处理的工单。
可见性规则:
- 创建时
role_group默认为customer_service,仅客服组可见 - 转单后(如
customer_service→warehouse),原角色组不再可见,目标角色组可见 - 用户通过角色绑定的 block 权限(516/517/518)确定可见哪些 role_group
- 核心逻辑:
WHERE role_group IN (用户拥有的售后block对应的role_group)且status != 'completed' AND status != 'cancelled'
method 定义:
{
"method": "afterSale.workList",
"description": "售后工作列表。仅返回当前用户角色组负责的待处理工单。创建时默认进入客服组,转单后原组不可见、目标组可见。",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [
{ "name": "pagination", "type": "object", "required": false, "source": "body", "description": "分页参数 page/pageSize" },
{ "name": "where", "type": "object", "required": false, "source": "body", "description": "筛选条件:支持 type/sub_type/status/priority/after_sale_no/waybill_no 等字段筛选,以及 quickWhere 快捷搜索" },
{ "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数 sortField/sortOrder,默认按 priority DESC, created_at DESC" }
],
"response": [
{ "name": "list", "type": "array", "required": true, "description": "售后工单列表" },
{ "name": "pagination", "type": "object", "required": true, "description": "分页信息" }
]
}
10.3 列表二:审计列表 afterSale.auditList
定位:所有售后单全局视图,不限角色组,用于审计和管理。
可见性规则:
- 所有
status的工单均可见(包括 completed/cancelled) - 不限
role_group - 与工作列表共享 where/sort/pagination 参数格式
method 定义:
{
"method": "afterSale.auditList",
"description": "售后审计列表。全局售后单视图,不限角色组、不限状态,用于审计和统计分析。入参与 afterSale.workList 一致。",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [
{ "name": "pagination", "type": "object", "required": false, "source": "body" },
{ "name": "where", "type": "object", "required": false, "source": "body", "description": "同 workList,额外支持 claim_status/carrier_claim_status 筛选" },
{ "name": "sort", "type": "object", "required": false, "source": "body" }
],
"response": [
{ "name": "list", "type": "array", "required": true },
{ "name": "pagination", "type": "object", "required": true }
]
}
10.4 导出接口 afterSale.export + afterSale.exportTaskProgress
参考项目现有导出模式(order.export / order.exportTaskProgress)。
afterSale.export:
{
"method": "afterSale.export",
"description": "提交售后审计列表导出任务(异步)。入参 where/sort 与 afterSale.auditList 完全一致。提交后立即返回 task_id,后台异步执行 Excel 生成并上传 COS。通过 afterSale.exportTaskProgress 查询进度和下载链接。",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [
{ "name": "where", "type": "object", "required": false, "source": "body", "description": "查询条件,与 afterSale.auditList 的 where 语义一致" },
{ "name": "sort", "type": "object", "required": false, "source": "body", "description": "排序参数,与 afterSale.auditList 的 sort 语义一致" }
],
"response": [
{ "name": "task_id", "type": "string", "required": true, "description": "导出任务ID" },
{ "name": "status", "type": "string", "required": true, "description": "submitted/running/success/failed" },
{ "name": "progress", "type": "number", "required": true, "description": "0-100" },
{ "name": "message", "type": "string", "required": true }
]
}
afterSale.exportTaskProgress:
{
"method": "afterSale.exportTaskProgress",
"description": "查询售后导出任务进度和下载链接。",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [
{ "name": "task_id", "type": "string", "required": true, "source": "body", "description": "导出任务ID" }
],
"response": [
{ "name": "task_id", "type": "string", "required": true },
{ "name": "status", "type": "string", "required": true },
{ "name": "progress", "type": "number", "required": true },
{ "name": "download_url", "type": "string", "required": false, "description": "status=success 时返回 Excel 下载链接" },
{ "name": "error", "type": "string", "required": false, "description": "status=failed 时返回错误信息" }
]
}
10.5 其他 methods
| method | 说明 | 权限 |
|---|---|---|
afterSale.create |
创建售后单 | 客服 |
afterSale.detail |
售后明细(主表+步骤列表) | 全部 |
afterSale.update |
更新售后单 | 客服/仓库 |
afterSale.transfer |
转单(更新 role_group) | 客服 |
afterSale.handleWorkOrder |
处理工单(写步骤+绑附件) | 当前 role_group 匹配的用户 |
afterSale.registerClaim |
登记售后理赔信息(仓库理赔+运方理赔) | 客服 |
10.6 导出流程说明
导出流程参考项目现有异步导出模式(order.export):
- 客户端调用
afterSale.export提交导出任务,服务端生成task_id,在 Redis 中初始化任务状态为submitted - 通过
setImmediate启动异步执行,立即返回task_id给客户端 - 后台任务分页查询售后数据,使用 ExcelJS 流式写入 Excel 文件
- Excel 生成完成后上传至 COS,获取下载链接
- 更新 Redis 中任务状态为
success,并写入download_url - 若任一步骤失败,更新任务状态为
failed,并写入错误信息 - 客户端轮询
afterSale.exportTaskProgress获取进度和下载链接
Redis 缓存规范:
- Key 格式:
after_sale_export_task_{task_id} - TTL:30 分钟(任务完成后自动过期)
10.7 处理工单 afterSale.handleWorkOrder
{
"method": "afterSale.handleWorkOrder",
"description": "处理售后工单。员工在工作列表中对工单进行操作,写入进度步骤并绑定附件。操作人信息从登录上下文自动获取。步骤 action 由服务端固定为\"处理工单\",前端无需传入。status 不填或填错默认 processing。非客服组处理完成后自动转回客服组继续跟进。",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [
{ "name": "id", "type": "integer", "required": true, "source": "body", "description": "售后工单主表ID(wms_after_sale.id)" },
{ "name": "status", "type": "string", "required": false, "source": "body", "description": "更新售后单状态: processing | completed | closed | cancelled。不填或填错默认 processing。注意:pending 不适用于处理操作" },
{ "name": "remark", "type": "string", "required": false, "source": "body", "description": "处理备注" },
{ "name": "attachment_ids", "type": "array", "required": false, "source": "body", "description": "附件 file_id 数组,如 [123, 456]。处理时自动绑定到本次步骤。" }
],
"response": [
{ "name": "detail_id", "type": "integer", "required": true, "description": "本次写入的 wms_after_sale_detail.id" },
{ "name": "after_sale_id", "type": "integer", "required": true }
],
"errors": [
{ "code": 400, "message": "工单不存在或参数缺失" },
{ "code": 500, "message": "处理失败" }
]
}
处理流程:
- 校验工单
id存在,且当前用户role_group与工单role_group匹配(否则 403) - 从登录上下文(JWT token)提取操作人
operator_id和operator_snapshot - 写入
wms_after_sale_detail:step_status= 主表当前 status(由 safeStatus 决定,不填或填错默认 processing)action= 服务端固定"处理工单"remark= 入参remarkoperator_id/operator_snapshot= 当前用户started_at = now,completed_at = now
- 若传入了
attachment_ids,遍历写入wms_file_reference:business_type = 'after_sale_detail'business_id= 刚写入的detail.idfile_id = attachment_id
- 更新
wms_after_sale.status:始终写入 safeStatus(默认 processing,白名单校验,不含 pending) - 若当前
role_group≠'customer_service'且 status ≠'completed',自动将role_group回设为'customer_service'(仓库/财务处理完本环节后自动退回客服组继续跟进) - 若 status =
'completed',同时写入resolution和resolved_at
10.8 理赔登记 afterSale.registerClaim
{
"method": "afterSale.registerClaim",
"description": "登记售后理赔信息。一次性填入仓库理赔和运方理赔的全部字段,同时写入进度步骤。两套理赔字段可同时填写(双赔场景)。",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [
{ "name": "id", "type": "integer", "required": true, "source": "body", "description": "售后工单主表ID" },
{ "name": "claim_needed", "type": "integer", "required": false, "source": "body", "description": "仓库理赔标记:0/1" },
{ "name": "claim_amount", "type": "number", "required": false, "source": "body", "description": "仓库理赔金额(元)" },
{ "name": "claim_status", "type": "string", "required": false, "source": "body", "description": "仓库理赔状态:pending/reviewing/approved/paid/monthly/rejected" },
{ "name": "carrier_claim_needed", "type": "integer", "required": false, "source": "body", "description": "运方理赔标记:0/1" },
{ "name": "carrier_claim_amount", "type": "number", "required": false, "source": "body", "description": "运方理赔金额(元)" },
{ "name": "carrier_claim_status", "type": "string", "required": false, "source": "body", "description": "运方理赔状态:pending/reviewing/approved/paid/monthly/rejected" },
{ "name": "action", "type": "string", "required": true, "source": "body", "description": "操作动作描述,如"登记仓库理赔"、"登记运方理赔"" },
{ "name": "remark", "type": "string", "required": false, "source": "body", "description": "处理备注,如"快递破损核定赔200元"" },
{ "name": "attachment_ids", "type": "array", "required": false, "source": "body", "description": "附件 file_id 数组(破损照片、理赔单据等)" }
],
"response": [
{ "name": "detail_id", "type": "integer", "required": true, "description": "本次写入的步骤ID" },
{ "name": "after_sale_id", "type": "integer", "required": true }
],
"errors": [
{ "code": 400, "message": "工单不存在或参数缺失" },
{ "code": 500, "message": "登记失败" }
]
}
处理流程:
- 校验工单
id存在 - 从登录上下文提取操作人信息
- 更新
wms_after_sale中传入的非空理赔字段(claim_needed/amount/status、carrier_claim_needed/amount/status) - 写入
wms_after_sale_detail(step_status=主表当前 status,action/remark/operator) - 若有
attachment_ids,绑定到本次步骤
使用场景:
- 单赔:只传仓库理赔字段组,运方字段不传
- 单赔:只传运方理赔字段组,仓库字段不传
- 双赔:同时传两套字段(仓库+运输途中均破损)
十一、待评审事项
- 售后单号
after_sale_no生成规则:格式已确定为AS + YYYYMMDD + 6位序号(如AS20260809000001),待确认序号从 1 起始还是从指定起始值起 - 仓库理赔(
claim_status)和运方理赔(carrier_claim_status)是否需要更细粒度的流转(如:待审核 → 审核通过 → 已打款 → 月结) - 进度步骤表是否需要记录商品明细信息(如退货 SKU/数量),或通过
remarkJSON 扩展存储 - 单据关联字段是否需要扩展到更多类型(如质检单
quality_check_id) - 是否需要支持售后单之间的关联(如换货单关联原退货单)