WMS_MAIN/database/designs/after-sale-v2-design.md
liufumingren b436b6dd9e feat: 拦截链路全流程完善 — 新增interceptScan + 运单表同步 + 工单通知
新增:
- 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: 变更记录
2026-08-12 20:47:19 +08:00

41 KiB
Raw Blame History

售后模块 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 正式移除。旧版存在以下核心问题:

  1. 多态关联难以维护:使用 business_type + business_sub_type + business_id 三元组关联业务单据,导致:
    • 查询需要动态拼接 JOIN 条件,性能差
    • 无法利用数据库外键约束保证数据完整性
    • 业务类型枚举膨胀,新增业务类型需改动多处代码
  2. 不支持多单据共存:一个售后单只能关联一种业务单据,实际场景中退货退款往往同时涉及运单、发货订单、收货单等多张单据
  3. 覆盖场景不足:旧版仅覆盖工单流转,未涵盖理赔、投诉等售后场景
  4. 缺少明细层级:无法记录售后单中的商品明细(退什么货、换什么货、赔多少钱)

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):

  1. 客户端调用 afterSale.export 提交导出任务,服务端生成 task_id,在 Redis 中初始化任务状态为 submitted
  2. 通过 setImmediate 启动异步执行,立即返回 task_id 给客户端
  3. 后台任务分页查询售后数据,使用 ExcelJS 流式写入 Excel 文件
  4. Excel 生成完成后上传至 COS,获取下载链接
  5. 更新 Redis 中任务状态为 success,并写入 download_url
  6. 若任一步骤失败,更新任务状态为 failed,并写入错误信息
  7. 客户端轮询 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": "处理失败" }
    ]
}

处理流程:

  1. 校验工单 id 存在,且当前用户 role_group 与工单 role_group 匹配(否则 403)
  2. 从登录上下文(JWT token)提取操作人 operator_id 和 operator_snapshot
  3. 写入 wms_after_sale_detail:
    • step_status = 主表当前 status(由 safeStatus 决定,不填或填错默认 processing)
    • action = 服务端固定 "处理工单"
    • remark = 入参 remark
    • operator_id / operator_snapshot = 当前用户
    • started_at = now, completed_at = now
  4. 若传入了 attachment_ids,遍历写入 wms_file_reference:
    • business_type = 'after_sale_detail'
    • business_id = 刚写入的 detail.id
    • file_id = attachment_id
  5. 更新 wms_after_sale.status:始终写入 safeStatus(默认 processing,白名单校验,不含 pending)
  6. 若当前 role_group ≠ 'customer_service' 且 status ≠ 'completed',自动将 role_group 回设为 'customer_service'(仓库/财务处理完本环节后自动退回客服组继续跟进)
  7. 若 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": "登记失败" }
    ]
}

处理流程:

  1. 校验工单 id 存在
  2. 从登录上下文提取操作人信息
  3. 更新 wms_after_sale 中传入的非空理赔字段(claim_needed/amount/status、carrier_claim_needed/amount/status)
  4. 写入 wms_after_sale_detail(step_status=主表当前 status,action/remark/operator)
  5. 若有 attachment_ids,绑定到本次步骤

使用场景:

  • 单赔:只传仓库理赔字段组,运方字段不传
  • 单赔:只传运方理赔字段组,仓库字段不传
  • 双赔:同时传两套字段(仓库+运输途中均破损)

十一、待评审事项

  • 售后单号 after_sale_no 生成规则:格式已确定为 AS + YYYYMMDD + 6位序号(如 AS20260809000001),待确认序号从 1 起始还是从指定起始值起
  • 仓库理赔(claim_status)和运方理赔(carrier_claim_status)是否需要更细粒度的流转(如:待审核 → 审核通过 → 已打款 → 月结)
  • 进度步骤表是否需要记录商品明细信息(如退货 SKU/数量),或通过 remark JSON 扩展存储
  • 单据关联字段是否需要扩展到更多类型(如质检单 quality_check_id)
  • 是否需要支持售后单之间的关联(如换货单关联原退货单)