新增: - 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: 变更记录
854 lines
41 KiB
Markdown
854 lines
41 KiB
Markdown
# 售后模块 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`)
|
||
- [ ] 是否需要支持售后单之间的关联(如换货单关联原退货单)
|