# 售后模块 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`) - [ ] 是否需要支持售后单之间的关联(如换货单关联原退货单)