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

854 lines
41 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.

# 售后模块 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 图
```mermaid
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`):
```javascript
// 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 |
**典型场景:**
- 仓库验货步骤上传破损商品照片
- 客服接单步骤上传客户提供的聊天截图
- 运方理赔步骤上传快递破损证明
- 退款步骤上传打款凭证截图
**查询示例:**
```sql
-- 查询某售后单所有步骤的附件
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` | 普通 | 按操作人查询其处理的步骤 |
---
## 五、状态流转
```mermaid
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 定义:**
```json
{
"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 定义:**
```json
{
"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`:**
```json
{
"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`:**
```json
{
"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`
```json
{
"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`
```json
{
"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`)
- [ ] 是否需要支持售后单之间的关联(如换货单关联原退货单)