chore: 移除售后工单模块 (after_sale_work_order)

- 删除 model: after_sale_work_order.js, after_sale_work_order_step.js

- 删除旧迁移: 20260728120000, 20260728130000

- 删除设计文档: after-sale-work-order-design.md, after-sale-api-design.md

- 新增 DROP TABLE 迁移: 20260809120000

- 开发/生产环境均已执行 DROP 迁移,两表已删除
This commit is contained in:
liufumingren 2026-08-09 16:21:04 +08:00
parent 3e7c9a7a10
commit 0c2b062658
6 changed files with 104 additions and 1628 deletions

View File

@ -1,267 +0,0 @@
'use strict';
module.exports = app => {
const { STRING, BIGINT, INTEGER, TINYINT, TEXT, DATE, DECIMAL } = app.Sequelize;
/**
* 售后工单业务类型定义
* 外部可通过 require('./app/model/after_sale_work_order').BUSINESS_TYPES 访问
* 增删业务类型或子类型只需修改此常量,无需 ALTER TABLE
*/
const BUSINESS_TYPES = {
waybill: {
label: '运单',
table: 'wms_order_express',
subtypes: {
intercept: '拦截',
urge: '催件',
damage: '破损',
lost: '丢件',
wrong_info: '信息错误',
},
},
order_delivery: {
label: '发货订单',
table: 'wms_order_delivery',
subtypes: {
mis_shipment: '错发',
missing_item: '少发',
wrong_sku: '错品',
quality_issue: '质量问题',
delivery_delay: '发货延迟',
},
},
entry_order: {
label: '入库单',
table: 'wms_entry_order',
subtypes: {
shortage: '少货',
damage: '破损',
wrong_sku: '错品',
quality_issue: '质量问题',
},
},
order_stockout: {
label: '出库单/退货出库单',
table: 'wms_order_stockout',
subtypes: {
return_issue: '退货异常',
wrong_outbound: '错发',
shortage: '少发',
},
},
receiving: {
label: '收货单',
table: 'wms_receiving',
subtypes: {
shortage: '少货',
damage: '破损',
quality_issue: '质量问题',
},
},
other: {
label: '其他',
table: null,
subtypes: {
general: '通用',
},
},
};
/**
* 根据 business_type 获取关联表名
* @param {string} businessType 业务类型
* @return {string|null} 关联表名
*/
function getBusinessTable(businessType) {
return BUSINESS_TYPES[businessType]?.table || null;
}
/**
* 校验 business_type + business_sub_type 组合是否合法
* @param {string} businessType 业务类型
* @param {string} businessSubType 业务子类型
* @return {boolean} 是否合法
*/
function isValidSubType(businessType, businessSubType) {
const def = BUSINESS_TYPES[businessType];
return def && Object.prototype.hasOwnProperty.call(def.subtypes, businessSubType);
}
const AfterSaleWorkOrder = app.model.define('after_sale_work_order', {
id: {
type: BIGINT(20).UNSIGNED,
primaryKey: true,
autoIncrement: true,
comment: '主键ID',
},
warehouse_id: {
type: BIGINT(20).UNSIGNED,
allowNull: false,
comment: '仓库ID',
},
store_id: {
type: BIGINT(20).UNSIGNED,
allowNull: false,
comment: '货主ID',
},
work_order_no: {
type: STRING(50),
allowNull: false,
comment: '售后工单号,唯一',
},
business_type: {
type: STRING(50),
allowNull: false,
comment: '关联业务类型',
},
business_sub_type: {
type: STRING(50),
allowNull: false,
comment: '关联业务子类型',
},
business_id: {
type: BIGINT(20).UNSIGNED,
allowNull: false,
comment: '关联业务单据主键ID(多态关联)',
},
business_no: {
type: STRING(100),
allowNull: true,
comment: '关联业务单据号(冗余)',
},
direction: {
type: TINYINT.UNSIGNED,
allowNull: false,
defaultValue: 0,
comment: '记账方向:0=未确定 1=入库 2=出库',
},
status: {
type: TINYINT.UNSIGNED,
allowNull: false,
defaultValue: 0,
comment: '工单状态:0=待处理 1=处理中 2=已完成 3=已关闭 9=已取消',
},
priority: {
type: TINYINT.UNSIGNED,
allowNull: false,
defaultValue: 50,
comment: '优先级:1~100,数字越大优先级越高',
},
title: {
type: STRING(200),
allowNull: false,
comment: '工单标题/摘要',
},
description: {
type: TEXT,
allowNull: true,
comment: '问题描述',
},
creator_id: {
type: BIGINT(20).UNSIGNED,
allowNull: false,
comment: '创建人ID,关联 account.id;0 表示 AI 自动接待',
},
creator_snapshot: {
type: TEXT,
allowNull: true,
comment: '创建人信息快照(JSON格式);AI创建时记录模型/会话信息',
},
assignee_id: {
type: BIGINT(20).UNSIGNED,
allowNull: true,
comment: '当前处理人ID,关联 account.id',
},
parent_work_order_id: {
type: BIGINT(20).UNSIGNED,
allowNull: true,
comment: '父工单ID,自关联本表;非空时表示子工单',
},
current_step: {
type: TINYINT.UNSIGNED,
allowNull: false,
defaultValue: 1,
comment: '当前进度,值为当前正在处理的 step_order 序号',
},
claim_needed: {
type: TINYINT.UNSIGNED,
allowNull: false,
defaultValue: 0,
comment: '是否需要理赔:0=不需要 1=需要',
},
claim_amount: {
type: DECIMAL(12, 2),
allowNull: true,
defaultValue: 0.00,
comment: '理赔金额(元)',
},
claim_status: {
type: TINYINT.UNSIGNED,
allowNull: false,
defaultValue: 0,
comment: '理赔状态:0=未理赔 1=已理赔(单笔结清) 2=月结',
},
resolution: {
type: TEXT,
allowNull: true,
comment: '处理结果说明',
},
resolved_at: {
type: DATE,
allowNull: true,
comment: '解决时间',
},
created_at: {
type: DATE,
allowNull: false,
comment: '创建时间',
},
updated_at: {
type: DATE,
allowNull: false,
comment: '更新时间',
},
deleted_at: {
type: DATE,
allowNull: true,
comment: '软删除时间',
},
}, {
tableName: 'wms_after_sale_work_order',
timestamps: true,
createdAt: 'created_at',
updatedAt: 'updated_at',
paranoid: true,
deletedAt: 'deleted_at',
comment: '售后工单主表',
});
AfterSaleWorkOrder.associate = () => {
// 自关联:父工单 → 子工单
AfterSaleWorkOrder.hasMany(app.model.AfterSaleWorkOrder, {
foreignKey: 'parent_work_order_id',
sourceKey: 'id',
as: 'children',
});
AfterSaleWorkOrder.belongsTo(app.model.AfterSaleWorkOrder, {
foreignKey: 'parent_work_order_id',
targetKey: 'id',
as: 'parent',
});
// 关联进度步骤表
AfterSaleWorkOrder.hasMany(app.model.AfterSaleWorkOrderStep, {
foreignKey: 'work_order_id',
sourceKey: 'id',
as: 'steps',
});
};
// 挂载业务类型常量及辅助函数到 Model
AfterSaleWorkOrder.BUSINESS_TYPES = BUSINESS_TYPES;
AfterSaleWorkOrder.getBusinessTable = getBusinessTable;
AfterSaleWorkOrder.isValidSubType = isValidSubType;
return AfterSaleWorkOrder;
};

View File

@ -1,99 +0,0 @@
'use strict';
module.exports = app => {
const { STRING, BIGINT, TINYINT, TEXT, DATE } = app.Sequelize;
const AfterSaleWorkOrderStep = app.model.define('after_sale_work_order_step', {
id: {
type: BIGINT(20).UNSIGNED,
primaryKey: true,
autoIncrement: true,
comment: '主键ID',
},
work_order_id: {
type: BIGINT(20).UNSIGNED,
allowNull: false,
comment: '工单ID,关联 wms_after_sale_work_order.id',
},
step_order: {
type: TINYINT.UNSIGNED,
allowNull: false,
defaultValue: 1,
comment: '步骤序号(从1开始递增)',
},
step_name: {
type: STRING(100),
allowNull: false,
comment: '步骤名称',
},
step_status: {
type: TINYINT.UNSIGNED,
allowNull: false,
defaultValue: 0,
comment: '步骤状态:0=待开始 1=进行中 2=已完成 3=已跳过',
},
operator_id: {
type: BIGINT(20).UNSIGNED,
allowNull: true,
comment: '操作员工ID,关联 account.id',
},
operator_snapshot: {
type: TEXT,
allowNull: true,
comment: '操作人信息快照(JSON格式)',
},
action: {
type: STRING(100),
allowNull: true,
comment: '操作动作描述',
},
remark: {
type: TEXT,
allowNull: true,
comment: '处理备注',
},
started_at: {
type: DATE,
allowNull: true,
comment: '步骤开始时间',
},
completed_at: {
type: DATE,
allowNull: true,
comment: '步骤完成时间',
},
created_at: {
type: DATE,
allowNull: false,
comment: '创建时间',
},
updated_at: {
type: DATE,
allowNull: false,
comment: '更新时间',
},
deleted_at: {
type: DATE,
allowNull: true,
comment: '软删除时间',
},
}, {
tableName: 'wms_after_sale_work_order_step',
timestamps: true,
createdAt: 'created_at',
updatedAt: 'updated_at',
paranoid: true,
deletedAt: 'deleted_at',
comment: '售后工单进度步骤表',
});
AfterSaleWorkOrderStep.associate = () => {
AfterSaleWorkOrderStep.belongsTo(app.model.AfterSaleWorkOrder, {
foreignKey: 'work_order_id',
targetKey: 'id',
as: 'workOrder',
});
};
return AfterSaleWorkOrderStep;
};

View File

@ -1,644 +0,0 @@
# 售后工单 API 接口设计方案
> **状态**: ⏳ 等待人工审阅
> **设计日期**: 2026-07-29
> **设计人**: wms-db-agent
> **说明**: 本文档仅输出 API 接口设计方案,不直接修改程序代码。审阅通过后再执行实现。
---
## 一、模块概览
| 项目 | 说明 |
|------|------|
| 模块名 | `afterSale` |
| 接口路径 | `POST /system`,body 中 `method` 字段为 `afterSale.{方法名}` |
| 请求方式 | 全部 `POST`,参数放在 `body` 内 |
| 鉴权 | 除 `businessTypes` 外均需登录;写操作需鉴权 |
### 文件规划
```
app/service/systemMethods/afterSale.js ← 入口层(鉴权、参数校验、委托)
app/service/systems/afterSale.js ← 业务层(数据库操作、状态机)
methods/system.json ← API 文档(追加 afterSale group)
```
### 调用链路
```
POST /system { method: "afterSale.list", ... }
→ app/router.js
→ app/service/system.js
→ app/service/systemMethods/afterSale.js ← 鉴权 + 参数校验
→ app/service/systems/afterSale.js ← 业务逻辑 + DB操作
→ app/model/after_sale_work_order.js ← Sequelize Model
→ app/model/after_sale_work_order_step.js
```
---
## 二、接口清单(共 13 个)
| # | method | 描述 | 需登录 | 需鉴权 |
|---|--------|------|--------|--------|
| 1 | `afterSale.businessTypes` | 获取内置业务类型及子类型枚举 | ✗ | ✗ |
| 2 | `afterSale.list` | 工单列表(分页+筛选) | ✓ | ✗ |
| 3 | `afterSale.detail` | 工单详情(含步骤列表) | ✓ | ✗ |
| 4 | `afterSale.create` | 创建工单 | ✓ | ✓ |
| 5 | `afterSale.update` | 更新工单基本信息 | ✓ | ✓ |
| 6 | `afterSale.delete` | 删除工单(软删除) | ✓ | ✓ |
| 7 | `afterSale.assign` | 分配处理人 | ✓ | ✓ |
| 8 | `afterSale.complete` | 完成工单 | ✓ | ✓ |
| 9 | `afterSale.close` | 关闭工单 | ✓ | ✓ |
| 10 | `afterSale.cancel` | 取消工单 | ✓ | ✓ |
| 11 | `afterSale.stepStart` | 开始某个步骤 | ✓ | ✓ |
| 12 | `afterSale.stepComplete` | 完成某个步骤 | ✓ | ✓ |
| 13 | `afterSale.stepSkip` | 跳过某个步骤 | ✓ | ✓ |
---
## 三、接口详细设计
### 3.1 `afterSale.businessTypes` — 获取业务类型枚举
```json
{
"method": "afterSale.businessTypes",
"description": "获取售后工单内置业务类型及子类型枚举,供前端下拉选择使用。数据来源:app/model/after_sale_work_order.js 中的 BUSINESS_TYPES 常量。",
"isNeedAuth": false,
"isNeedLogin": false,
"params": [],
"response": [
{
"name": "data",
"type": "object",
"description": "业务类型枚举,key 为 business_type,value 含 label、table、subtypes",
"example": {
"waybill": {
"label": "运单",
"table": "wms_order_express",
"subtypes": {
"intercept": "拦截",
"urge": "催件",
"damage": "破损",
"lost": "丢件",
"wrong_info": "信息错误"
}
},
"order_delivery": {
"label": "发货订单",
"table": "wms_order_delivery",
"subtypes": {
"mis_shipment": "错发",
"missing_item": "少发",
"wrong_sku": "错品",
"quality_issue": "质量问题",
"delivery_delay": "发货延迟"
}
}
}
}
]
}
```
---
### 3.2 `afterSale.list` — 工单列表
```json
{
"method": "afterSale.list",
"description": "查询售后工单列表,支持分页与多条件筛选。仓库隔离(自动注入 warehouse_id)。",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页参数 { page, pageSize },默认 page=1 pageSize=20"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "筛选条件,所有字段均为可选",
"children": [
{ "name": "workOrderNo", "type": "string", "description": "工单号(模糊搜索)" },
{ "name": "businessType", "type": "string", "description": "业务类型(等值),如 waybill" },
{ "name": "businessSubType","type": "string", "description": "业务子类型(等值),如 intercept" },
{ "name": "businessNo", "type": "string", "description": "关联业务单据号(模糊)" },
{ "name": "status", "type": "number", "description": "工单状态(等值):0/1/2/3/9" },
{ "name": "priorityMin", "type": "number", "description": "优先级下限(>=)" },
{ "name": "priorityMax", "type": "number", "description": "优先级上限(<=)" },
{ "name": "claimStatus", "type": "number", "description": "理赔状态(等值):0/1/2" },
{ "name": "assigneeId", "type": "number", "description": "处理人ID(等值)" },
{ "name": "creatorId", "type": "number", "description": "创建人ID(等值)" },
{ "name": "keyword", "type": "string", "description": "关键词:匹配工单号/标题/业务单据号" },
{ "name": "createdAtStart", "type": "string", "description": "创建时间起始(YYYY-MM-DD)" },
{ "name": "createdAtEnd", "type": "string", "description": "创建时间截止(YYYY-MM-DD)" }
]
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序 { field: 'priority'|'created_at'|'status', order: 'asc'|'desc' },默认 priority desc"
}
],
"response": [
{
"name": "list",
"type": "array",
"description": "工单列表(不含 description/resolution 长文本,减少传输量)",
"children": [
{ "name": "id", "type": "number", "description": "工单ID" },
{ "name": "work_order_no", "type": "string", "description": "工单号" },
{ "name": "warehouse_id", "type": "number", "description": "仓库ID" },
{ "name": "store_id", "type": "number", "description": "货主ID" },
{ "name": "business_type", "type": "string", "description": "业务类型" },
{ "name": "business_sub_type","type": "string", "description": "业务子类型" },
{ "name": "business_id", "type": "number", "description": "关联单据ID" },
{ "name": "business_no", "type": "string", "description": "关联单据号" },
{ "name": "direction", "type": "number", "description": "记账方向:0/1/2" },
{ "name": "status", "type": "number", "description": "工单状态:0/1/2/3/9" },
{ "name": "priority", "type": "number", "description": "优先级:1-100" },
{ "name": "title", "type": "string", "description": "工单标题" },
{ "name": "creator_id", "type": "number", "description": "创建人ID" },
{ "name": "creator_name", "type": "string", "description": "创建人姓名(JOIN account)" },
{ "name": "assignee_id", "type": "number", "description": "当前处理人ID" },
{ "name": "assignee_name", "type": "string", "description": "当前处理人姓名(JOIN account)" },
{ "name": "parent_work_order_id","type":"number","description": "父工单ID" },
{ "name": "current_step", "type": "number", "description": "当前进度步骤序号" },
{ "name": "claim_needed", "type": "number", "description": "是否理赔" },
{ "name": "claim_amount", "type": "number", "description": "理赔金额" },
{ "name": "claim_status", "type": "number", "description": "理赔状态" },
{ "name": "resolved_at", "type": "string", "description": "解决时间" },
{ "name": "created_at", "type": "string", "description": "创建时间" },
{ "name": "updated_at", "type": "string", "description": "更新时间" }
]
},
{ "name": "pagination", "type": "object", "description": "分页信息 { page, pageSize, total, totalPages }" }
]
}
```
---
### 3.3 `afterSale.detail` — 工单详情
```json
{
"method": "afterSale.detail",
"description": "查询单个工单详情,含完整字段 + 步骤列表。仓库隔离。",
"isNeedAuth": false,
"isNeedLogin": true,
"params": [
{
"name": "id",
"type": "number",
"required": true,
"source": "body",
"description": "工单ID(必填)"
}
],
"response": [
{
"name": "data",
"type": "object",
"description": "工单完整信息",
"children": [
{ "name": "id", "type": "number", "description": "工单ID" },
{ "name": "...", "type": "", "description": "同 list 接口所有字段" },
{ "name": "description", "type": "string", "description": "问题描述(详情接口返回)" },
{ "name": "resolution", "type": "string", "description": "处理结果说明(详情接口返回)" },
{ "name": "creator_snapshot", "type": "string", "description": "创建人信息快照" },
{ "name": "steps", "type": "array", "description": "步骤列表",
"children": [
{ "name": "id", "type": "number", "description": "步骤ID" },
{ "name": "step_order", "type": "number", "description": "步骤序号" },
{ "name": "step_name", "type": "string", "description": "步骤名称" },
{ "name": "step_status", "type": "number", "description": "步骤状态:0/1/2/3" },
{ "name": "operator_id", "type": "number", "description": "操作人ID" },
{ "name": "operator_name", "type": "string", "description": "操作人姓名" },
{ "name": "operator_snapshot","type": "string", "description": "操作人快照" },
{ "name": "action", "type": "string", "description": "操作动作" },
{ "name": "remark", "type": "string", "description": "处理备注" },
{ "name": "started_at", "type": "string", "description": "开始时间" },
{ "name": "completed_at", "type": "string", "description": "完成时间" },
{ "name": "created_at", "type": "string", "description": "创建时间" }
]
},
{ "name": "children", "type": "array", "description": "子工单列表(如有)" },
{ "name": "parent", "type": "object", "description": "父工单简要信息(如有)" }
]
}
],
"errors": [
{ "code": "400", "description": "工单ID不能为空" },
{ "code": "404", "description": "工单不存在或无权访问" }
]
}
```
---
### 3.4 `afterSale.create` — 创建工单
```json
{
"method": "afterSale.create",
"description": "创建售后工单。自动生成工单号(AS+时间戳),自动设置 creator_id 和 warehouse_id。创建成功后返回工单详情。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{
"name": "business_type",
"type": "string",
"required": true,
"source": "body",
"description": "业务类型(必填),如 waybill、order_delivery"
},
{
"name": "business_sub_type",
"type": "string",
"required": true,
"source": "body",
"description": "业务子类型(必填),如 intercept、mis_shipment。需与 business_type 匹配(由 BUSINESS_TYPES 校验)"
},
{
"name": "business_id",
"type": "number",
"required": true,
"source": "body",
"description": "关联业务单据主键ID(必填)"
},
{
"name": "business_no",
"type": "string",
"required": false,
"source": "body",
"description": "关联业务单据号(可选,建议传入方便列表展示)"
},
{
"name": "direction",
"type": "number",
"required": false,
"source": "body",
"description": "记账方向:1=入库 2=出库,默认 0(未确定)"
},
{
"name": "priority",
"type": "number",
"required": false,
"source": "body",
"description": "优先级:1~100,默认 50。AI 创建时自动填入"
},
{
"name": "title",
"type": "string",
"required": true,
"source": "body",
"description": "工单标题(必填)"
},
{
"name": "description",
"type": "string",
"required": false,
"source": "body",
"description": "问题描述"
},
{
"name": "claim_needed",
"type": "number",
"required": false,
"source": "body",
"description": "是否需要理赔:0=否 1=是,默认 0"
},
{
"name": "claim_amount",
"type": "number",
"required": false,
"source": "body",
"description": "理赔金额,默认 0.00"
},
{
"name": "parent_work_order_id",
"type": "number",
"required": false,
"source": "body",
"description": "父工单ID(子工单场景),不传则为根工单"
}
],
"response": [
{
"name": "data",
"type": "object",
"description": "创建成功的工单详情(同 detail 接口返回结构)"
}
],
"errors": [
{ "code": "400", "description": "工单标题不能为空" },
{ "code": "400", "description": "业务类型或子类型不合法" },
{ "code": "400", "description": "父工单不存在" }
]
}
```
---
### 3.5 `afterSale.update` — 更新工单基本信息
```json
{
"method": "afterSale.update",
"description": "更新工单基本信息(标题、描述、优先级、记账方向、理赔信息)。不可修改 business_type/business_sub_type/business_id。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" },
{ "name": "title", "type": "string", "required": false, "source": "body", "description": "工单标题" },
{ "name": "description", "type": "string", "required": false, "source": "body", "description": "问题描述" },
{ "name": "priority", "type": "number", "required": false, "source": "body", "description": "优先级" },
{ "name": "direction", "type": "number", "required": false, "source": "body", "description": "记账方向" },
{ "name": "claim_needed", "type": "number", "required": false, "source": "body", "description": "是否需要理赔" },
{ "name": "claim_amount", "type": "number", "required": false, "source": "body", "description": "理赔金额" },
{ "name": "claim_status", "type": "number", "required": false, "source": "body", "description": "理赔状态" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的工单详情" }
],
"errors": [
{ "code": "400", "description": "工单ID不能为空" },
{ "code": "404", "description": "工单不存在或无权操作" }
]
}
```
---
### 3.6 `afterSale.delete` — 删除工单
```json
{
"method": "afterSale.delete",
"description": "软删除工单及其所有步骤。仅待处理(0)和已取消(9)状态的工单可删除。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" }
],
"response": [],
"errors": [
{ "code": "400", "description": "工单ID不能为空" },
{ "code": "400", "description": "处理中的工单不可删除" },
{ "code": "404", "description": "工单不存在或无权操作" }
]
}
```
---
### 3.7 `afterSale.assign` — 分配处理人
```json
{
"method": "afterSale.assign",
"description": "将工单分配给指定处理人。仅待处理(0)状态的工单可分配。分配后自动流转至处理中(1)。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" },
{ "name": "assignee_id", "type": "number", "required": true, "source": "body", "description": "处理人ID(必填)" },
{ "name": "remark", "type": "string", "required": false, "source": "body", "description": "分配备注" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的工单详情" }
],
"errors": [
{ "code": "400", "description": "工单ID不能为空" },
{ "code": "400", "description": "处理人ID不能为空" },
{ "code": "400", "description": "当前状态不可分配(非待处理状态)" }
]
}
```
---
### 3.8 `afterSale.complete` — 完成工单
```json
{
"method": "afterSale.complete",
"description": "完成工单。仅处理中(1)状态且所有步骤已完成/跳过的工单可完成。完成后自动设置 resolved_at。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" },
{ "name": "resolution", "type": "string", "required": false, "source": "body", "description": "处理结果说明" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的工单详情" }
],
"errors": [
{ "code": "400", "description": "工单ID不能为空" },
{ "code": "400", "description": "当前状态不可完成(非处理中状态)" },
{ "code": "400", "description": "仍有步骤未完成,请先完成所有步骤" }
]
}
```
---
### 3.9 `afterSale.close` — 关闭工单
```json
{
"method": "afterSale.close",
"description": "关闭工单。仅已完成(2)状态的工单可关闭。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" },
{ "name": "remark", "type": "string", "required": false, "source": "body", "description": "关闭备注" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的工单详情" }
],
"errors": [
{ "code": "400", "description": "工单ID不能为空" },
{ "code": "400", "description": "当前状态不可关闭(非已完成状态)" }
]
}
```
---
### 3.10 `afterSale.cancel` — 取消工单
```json
{
"method": "afterSale.cancel",
"description": "取消工单。仅待处理(0)和处理中(1)状态的工单可取消。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "id", "type": "number", "required": true, "source": "body", "description": "工单ID(必填)" },
{ "name": "remark", "type": "string", "required": false, "source": "body", "description": "取消原因" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的工单详情" }
],
"errors": [
{ "code": "400", "description": "工单ID不能为空" },
{ "code": "400", "description": "当前状态不可取消" }
]
}
```
---
### 3.11 `afterSale.stepStart` — 开始步骤
```json
{
"method": "afterSale.stepStart",
"description": "开始处理某个步骤。将步骤状态设为进行中(1),同时更新主表 current_step。同一时刻只允许一个步骤处于进行中。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "step_id", "type": "number", "required": true, "source": "body", "description": "步骤ID(必填,wms_after_sale_work_order_step.id)" },
{ "name": "remark", "type": "string", "required": false, "source": "body", "description": "备注" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的步骤信息" }
],
"errors": [
{ "code": "400", "description": "步骤ID不能为空" },
{ "code": "400", "description": "已有其他步骤正在进行中" },
{ "code": "400", "description": "步骤当前状态不可开始" }
]
}
```
---
### 3.12 `afterSale.stepComplete` — 完成步骤
```json
{
"method": "afterSale.stepComplete",
"description": "完成某个步骤。将步骤状态设为已完成(2),记录操作人和完成时间。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "step_id", "type": "number", "required": true, "source": "body", "description": "步骤ID(必填)" },
{ "name": "action", "type": "string", "required": false, "source": "body", "description": "操作动作描述" },
{ "name": "remark", "type": "string", "required": false, "source": "body", "description": "处理备注" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的步骤信息" }
],
"errors": [
{ "code": "400", "description": "步骤ID不能为空" },
{ "code": "400", "description": "步骤当前状态不可完成(非进行中状态)" }
]
}
```
---
### 3.13 `afterSale.stepSkip` — 跳过步骤
```json
{
"method": "afterSale.stepSkip",
"description": "跳过某个步骤。将步骤状态设为已跳过(3)。仓库隔离。",
"isNeedAuth": true,
"isNeedLogin": true,
"params": [
{ "name": "step_id", "type": "number", "required": true, "source": "body", "description": "步骤ID(必填)" },
{ "name": "remark", "type": "string", "required": false, "source": "body", "description": "跳过原因" }
],
"response": [
{ "name": "data", "type": "object", "description": "更新后的步骤信息" }
],
"errors": [
{ "code": "400", "description": "步骤ID不能为空" },
{ "code": "400", "description": "步骤当前状态不可跳过" }
]
}
```
---
## 四、状态机约束(服务端校验规则)
| 操作 | 允许的当前状态 | 目标状态 |
|------|-------------|---------|
| `create` | — | `status=0`, `current_step=1` |
| `assign` | `status=0` | `status=1` |
| `delete` | `status=0` 或 `status=9` | 软删除 |
| `complete` | `status=1` + 所有步骤已完成/跳过 | `status=2`, `resolved_at=NOW()` |
| `close` | `status=2` | `status=3` |
| `cancel` | `status=0` 或 `status=1` | `status=9` |
| `stepStart` | `step_status=0` + 无其他进行中步骤 | `step_status=1`, `current_step=该step_order` |
| `stepComplete` | `step_status=1` | `step_status=2` |
| `stepSkip` | `step_status=0` | `step_status=3` |
---
## 五、methods/system.json 追加格式
在 `methods.system.json` 的 `methods.groups` 数组末尾追加:
```json
{
"groupName": "售后工单模块",
"module": "afterSale",
"list": [
{ "method": "afterSale.businessTypes", ... },
{ "method": "afterSale.list", ... },
{ "method": "afterSale.detail", ... },
{ "method": "afterSale.create", ... },
{ "method": "afterSale.update", ... },
{ "method": "afterSale.delete", ... },
{ "method": "afterSale.assign", ... },
{ "method": "afterSale.complete", ... },
{ "method": "afterSale.close", ... },
{ "method": "afterSale.cancel", ... },
{ "method": "afterSale.stepStart", ... },
{ "method": "afterSale.stepComplete", ... },
{ "method": "afterSale.stepSkip", ... }
]
}
```
(完整 JSON 定义见第三节各接口)
---
## 六、后续实现计划(审阅通过后执行)
| 步骤 | 文件 | 说明 |
|------|------|------|
| 1 | `app/service/systems/afterSale.js` | 业务层:数据库操作、状态机、工单号生成 |
| 2 | `app/service/systemMethods/afterSale.js` | 入口层:鉴权配置、参数校验、委托调用 |
| 3 | `methods/system.json` | 追加 `afterSale` group 的 13 个 method 文档 |
| 4 | `methods/changes/afterSale-20260729.json` | 接口变更记录 |
---
## 七、待确认事项
- [ ] **1. 模块名**:`afterSale` 是否合适?备选 `asWorkOrder`、`afterSaleWorkOrder`
- [ ] **2. 步骤操作是否需要独立接口**:`stepStart/stepComplete/stepSkip` 三个独立接口 vs 合并为一个 `stepUpdate`(传 status 参数)
- [ ] **3. `businessTypes` 接口免登录**:是否允许未登录用户获取业务类型枚举?
- [ ] **4. 步骤创建时机**:步骤是创建工单时自动初始化一组,还是由前端手动逐条添加?
- [ ] **5. 是否需要批量操作**:批量分配、批量关闭?
- [ ] **6. 是否需要操作日志**:是否复用 `operation_log` 记录关键状态变更?

View File

@ -1,440 +0,0 @@
# 售后工单表设计方案
> **状态**: ✅ 已落库(开发环境)
> **设计日期**: 2026-07-28(v4 定稿:新增 parent_work_order_id 支持主子工单)
> **设计人**: wms-db-agent
> **说明**: 本文档仅输出设计方案,不执行落库。审阅通过后再生成迁移文件。
---
## 一、需求概述
1. **主表**:售后工单单表,支持灵活绑定多种业务单据(运单、订单、入库单、退货单等),通过 `business_type` + `business_sub_type` + `business_id` 三级多态关联
2. **副表**:进度步骤处理表,记录每一步的操作员工、动作、备注(步骤不预设模板,由业务逻辑动态创建)
3. **状态流转**:工单整体状态 + 主表 `current_step` 进度 + 步骤级状态三层次
4. **简单记账**:记录是"进"还是"出"
5. **理赔追踪**:是否需要理赔、理赔金额、理赔结算状态
6. **附件关联**:通过现有 `wms_file_reference` 表关联附件/图片
---
## 二、表结构设计
### 2.1 主表:`wms_after_sale_work_order`(售后工单主表)
| # | 字段名 | 类型 | 必填 | 默认值 | 说明 |
|---|--------|------|------|--------|------|
| 1 | `id` | `BIGINT(20) UNSIGNED` | Y | AUTO | 主键ID |
| 2 | `warehouse_id` | `BIGINT(20) UNSIGNED` | Y | — | 仓库ID |
| 3 | `store_id` | `BIGINT(20) UNSIGNED` | Y | — | 货主ID |
| 4 | `work_order_no` | `VARCHAR(50)` | Y | — | 售后工单号,唯一,格式 `AS` + 时间戳(如 AS202607280001) |
| 5 | `business_type` | `VARCHAR(50)` | Y | — | 关联业务类型,见 §3.1 枚举及 §五 Model 内置定义 |
| 6 | `business_sub_type` | `VARCHAR(50)` | Y | — | 关联业务子类型,如运单下的 `intercept`(拦截)、订单下的 `mis_shipment`(错发),见 §五 |
| 7 | `business_id` | `BIGINT(20) UNSIGNED` | Y | — | 关联业务单据主键ID(多态关联) |
| 8 | `business_no` | `VARCHAR(100)` | N | — | 关联业务单据号(冗余,方便列表展示) |
| 9 | `direction` | `TINYINT UNSIGNED` | Y | 0 | 记账方向:`1`=入库(退货入库/换货入库),`2`=出库(补发/换货出库),`0`=未确定 |
| 10 | `status` | `TINYINT UNSIGNED` | Y | 0 | 工单状态,见 §3.4 状态机 |
| 11 | `priority` | `TINYINT UNSIGNED` | Y | 50 | 优先级:`1`~`100`,数字越大优先级越高,由客服接待或AI自动识别填入 |
| 12 | `title` | `VARCHAR(200)` | Y | — | 工单标题/摘要 |
| 13 | `description` | `TEXT` | N | — | 问题描述 |
| 14 | `creator_id` | `BIGINT(20) UNSIGNED` | Y | — | 创建人ID,关联 `account.id`;`0` 表示 AI 自动接待 |
| 15 | `creator_snapshot` | `TEXT` | N | — | 创建人信息快照(JSON格式);AI创建时记录模型/会话信息 |
| 16 | `assignee_id` | `BIGINT(20) UNSIGNED` | N | — | 当前处理人ID,关联 `account.id` |
| 17 | `parent_work_order_id` | `BIGINT(20) UNSIGNED` | N | — | 父工单ID,自关联 `wms_after_sale_work_order.id`;非空时表示当前工单为子工单 |
| 18 | `current_step` | `TINYINT UNSIGNED` | Y | 1 | **当前进度**(位于主表),值为当前正在处理的 `step_order` 序号 |
| 19 | `claim_needed` | `TINYINT UNSIGNED` | Y | 0 | 是否需要理赔:`0`=不需要,`1`=需要 |
| 20 | `claim_amount` | `DECIMAL(12,2)` | N | 0.00 | 理赔金额(元),精度2位小数 |
| 21 | `claim_status` | `TINYINT UNSIGNED` | Y | 0 | 理赔状态:`0`=未理赔,`1`=已理赔(单笔结清),`2`=月结 |
| 22 | `resolution` | `TEXT` | N | — | 处理结果说明 |
| 23 | `resolved_at` | `DATETIME` | N | — | 解决时间 |
| 24 | `created_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP` | 创建时间 |
| 25 | `updated_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP ON UPDATE` | 更新时间 |
| 26 | `deleted_at` | `DATETIME` | N | — | 软删除时间 |
**索引设计**:
| 索引名 | 字段 | 类型 | 说明 |
|--------|------|------|------|
| `PRIMARY` | `id` | 主键 | — |
| `uk_work_order_no` | `work_order_no` | 唯一 | 工单号唯一 |
| `idx_warehouse_id` | `warehouse_id` | 普通 | 按仓库查询 |
| `idx_store_id` | `store_id` | 普通 | 按货主查询 |
| `idx_business_type_subtype_id` | `business_type, business_sub_type, business_id` | 普通 | 按业务类型+子类型+单据ID反查工单 |
| `idx_status` | `status` | 普通 | 按状态筛选 |
| `idx_assignee_id` | `assignee_id` | 普通 | 按处理人查询 |
| `idx_parent_work_order_id` | `parent_work_order_id` | 普通 | 按父工单查所有子工单 |
| `idx_priority` | `priority` | 普通 | 按优先级排序 |
| `idx_claim_status` | `claim_status` | 普通 | 按理赔状态筛选 |
| `idx_created_at` | `created_at` | 普通 | 按时间排序 |
| `idx_deleted_at` | `deleted_at` | 普通 | 软删除查询 |
---
### 2.2 副表:`wms_after_sale_work_order_step`(售后工单进度步骤表)
| # | 字段名 | 类型 | 必填 | 默认值 | 说明 |
|---|--------|------|------|--------|------|
| 1 | `id` | `BIGINT(20) UNSIGNED` | Y | AUTO | 主键ID |
| 2 | `work_order_id` | `BIGINT(20) UNSIGNED` | Y | — | 工单ID,关联 `wms_after_sale_work_order.id` |
| 3 | `step_order` | `TINYINT UNSIGNED` | Y | 1 | 步骤序号(从1开始递增) |
| 4 | `step_name` | `VARCHAR(100)` | Y | — | 步骤名称 |
| 5 | `step_status` | `TINYINT UNSIGNED` | Y | 0 | 步骤状态:`0`=待开始,`1`=进行中,`2`=已完成,`3`=已跳过 |
| 6 | `operator_id` | `BIGINT(20) UNSIGNED` | N | — | 操作员工ID,关联 `account.id` |
| 7 | `operator_snapshot` | `TEXT` | N | — | 操作人信息快照(JSON格式) |
| 8 | `action` | `VARCHAR(100)` | N | — | 操作动作描述(如"核实问题属实,安排退货入库") |
| 9 | `remark` | `TEXT` | N | — | 处理备注 |
| 10 | `started_at` | `DATETIME` | N | — | 步骤开始时间 |
| 11 | `completed_at` | `DATETIME` | N | — | 步骤完成时间 |
| 12 | `created_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP` | 创建时间 |
| 13 | `updated_at` | `DATETIME` | Y | `CURRENT_TIMESTAMP ON UPDATE` | 更新时间 |
| 14 | `deleted_at` | `DATETIME` | N | — | 软删除时间 |
**索引设计**:
| 索引名 | 字段 | 类型 | 说明 |
|--------|------|------|------|
| `PRIMARY` | `id` | 主键 | — |
| `idx_work_order_id` | `work_order_id` | 普通 | 按工单查所有步骤 |
| `idx_operator_id` | `operator_id` | 普通 | 按操作人反查 |
| `idx_deleted_at` | `deleted_at` | 普通 | 软删除查询 |
| `uk_work_order_step` | `work_order_id, step_order, deleted_at` | 唯一 | 同一工单下步骤序号唯一(含软删除) |
---
## 三、枚举定义
### 3.1 `business_type` 与 `business_sub_type`(业务类型及子类型)
业务类型和子类型由 Model 文件 `app/model/after_sale_work_order.js` 中的 `BUSINESS_TYPES` 常量统一定义。数据库层面使用 `VARCHAR(50)` 存储,方便扩展。
#### 内置业务类型总览
| business_type | 业务名称 | 关联表 | 子类型 (business_sub_type) |
|---------------|---------|--------|---------------------------|
| `waybill` | 运单 | `wms_order_express` | `intercept`(拦截)、`urge`(催件)、`damage`(破损)、`lost`(丢件)、`wrong_info`(信息错误) |
| `order_delivery` | 发货订单 | `wms_order_delivery` | `mis_shipment`(错发)、`missing_item`(少发)、`wrong_sku`(错品)、`quality_issue`(质量问题)、`delivery_delay`(发货延迟) |
| `entry_order` | 入库单 | `wms_entry_order` | `shortage`(少货)、`damage`(破损)、`wrong_sku`(错品)、`quality_issue`(质量问题) |
| `order_stockout` | 出库单/退货出库单 | `wms_order_stockout` | `return_issue`(退货异常)、`wrong_outbound`(错发)、`shortage`(少发) |
| `receiving` | 收货单 | `wms_receiving` | `shortage`(少货)、`damage`(破损)、`quality_issue`(质量问题) |
| `other` | 其他 | — | `general`(通用) |
> **扩展方式**:在 Model 的 `BUSINESS_TYPES` 常量中增删条目即可,无需 ALTER TABLE。外部代码通过 `require` Model 文件读取。
### 3.2 `priority`(优先级)
```
1 ~ 100 的整数,数字越大优先级越高。
由客服接待手动填入,或由 AI 根据问题描述自动识别并填入。
默认值 50(中等优先级)。
```
### 3.3 `direction`(记账方向)
```
0 — 未确定
1 — 入库(IN):退货入库 / 换货入库 / 赔付补货入库
2 — 出库(OUT):补发出库 / 换货出库 / 退款退货出库
```
> 与 `stock_transaction.transaction_type`(`INBOUND`/`OUTBOUND`)语义对齐。
### 3.4 `status`(工单状态)
```
0 — 待处理 (工单刚创建,尚未分配)
1 — 处理中 (已分配处理人,正在推进)
2 — 已完成 (问题已解决,全部步骤完成)
3 — 已关闭 (问题关闭,不再跟进)
9 — 已取消 (工单作废)
```
### 3.5 `claim_status`(理赔状态)
```
0 — 未理赔 (不需要理赔,或尚未发起理赔)
1 — 已理赔 (单笔已结清,理赔款项已到账)
2 — 月结 (纳入月度结算,按月统一对账打款)
```
### 3.6 `step_status`(步骤状态)
```
0 — 待开始 (步骤尚未激活)
1 — 进行中 (当前正在处理的步骤)
2 — 已完成 (步骤已处理完毕)
3 — 已跳过 (该步骤被跳过,不适用)
```
### 3.7 `creator_id` 特殊值
```
0 — AI 自动接待(非员工账号创建)
> 0 — 对应 account.id,人工客服/员工创建
```
> 当 `creator_id = 0` 时,`creator_snapshot` 可记录 AI 模型标识及会话 ID 等元信息。
---
## 四、状态流转设计
### 4.1 工单级别状态机
```
┌──────────────────────────────────┐
│ │
┌───┴──────┐ ┌───┴──────┐
创建工单 ───→ │ 待处理(0) │ ──── 分配处理人 ───→ │ 处理中(1) │
└───┬──────┘ └───┬──────┘
│ │
│ 取消 │ 全部步骤完成
↓ ↓
┌───┴──────┐ ┌───┴──────┐
│ 已取消(9) │ │ 已完成(2) │
└──────────┘ └───┬──────┘
│
│ 关闭
↓
┌───┴──────┐
│ 已关闭(3) │
└──────────┘
```
**流转规则**:
| 当前状态 | 允许流转到 | 触发条件 |
|----------|-----------|----------|
| `0-待处理` | `1-处理中` | 分配处理人 |
| `0-待处理` | `9-已取消` | 主动取消 |
| `1-处理中` | `2-已完成` | 所有步骤均标记为已完成 |
| `1-处理中` | `9-已取消` | 主动取消 |
| `2-已完成` | `3-已关闭` | 确认关闭 |
| `3-已关闭` | — | 终态,不可流转 |
### 4.2 步骤级别状态机
```
┌──────────────────────────────────┐
│ │
┌───┴──────┐ ┌───┴──────┐
步骤创建 ───→ │ 待开始(0) │ ──── 开始处理 ───→ │ 进行中(1) │
└───┬──────┘ └───┬──────┘
│ │
│ 跳过 │ 完成
↓ ↓
┌───┴──────┐ ┌───┴──────┐
│ 已跳过(3) │ │ 已完成(2) │
└──────────┘ └──────────┘
```
**约束**:
- 同一工单下,同一时刻最多只有 1 个步骤处于 `进行中(1)`
- 步骤按 `step_order` 顺序流转,但允许跳过中间步骤
- 工单进度由主表 `current_step` 字段追踪,指向当前正在处理的 `step_order`
- 所有步骤标记为 `已完成(2)` 或 `已跳过(3)` 后,`current_step` 置为最终步骤号,工单状态可流转至 `已完成(2)`
---
## 五、Model 内置业务类型定义
> **步骤不预设模板**:`wms_after_sale_work_order_step` 表的步骤由业务逻辑在运行时动态创建,不在数据库或 Model 中硬编码步骤模板。
### 5.1 `BUSINESS_TYPES` 常量(定义在 `app/model/after_sale_work_order.js`)
```javascript
/**
* 售后工单业务类型定义
* 外部可通过 require('./app/model/after_sale_work_order').BUSINESS_TYPES 访问
* 增删业务类型或子类型只需修改此常量,无需 ALTER TABLE
*/
const BUSINESS_TYPES = {
waybill: {
label: '运单',
table: 'wms_order_express', // 关联的数据库表名
subtypes: {
intercept: '拦截',
urge: '催件',
damage: '破损',
lost: '丢件',
wrong_info: '信息错误',
},
},
order_delivery: {
label: '发货订单',
table: 'wms_order_delivery',
subtypes: {
mis_shipment: '错发',
missing_item: '少发',
wrong_sku: '错品',
quality_issue: '质量问题',
delivery_delay: '发货延迟',
},
},
entry_order: {
label: '入库单',
table: 'wms_entry_order',
subtypes: {
shortage: '少货',
damage: '破损',
wrong_sku: '错品',
quality_issue: '质量问题',
},
},
order_stockout: {
label: '出库单/退货出库单',
table: 'wms_order_stockout',
subtypes: {
return_issue: '退货异常',
wrong_outbound: '错发',
shortage: '少发',
},
},
receiving: {
label: '收货单',
table: 'wms_receiving',
subtypes: {
shortage: '少货',
damage: '破损',
quality_issue: '质量问题',
},
},
other: {
label: '其他',
table: null,
subtypes: {
general: '通用',
},
},
};
// 辅助函数:根据 business_type 获取关联表名
function getBusinessTable(businessType) {
return BUSINESS_TYPES[businessType]?.table || null;
}
// 辅助函数:校验 business_type + business_sub_type 组合是否合法
function isValidSubType(businessType, businessSubType) {
const def = BUSINESS_TYPES[businessType];
return def && Object.prototype.hasOwnProperty.call(def.subtypes, businessSubType);
}
module.exports = { BUSINESS_TYPES, getBusinessTable, isValidSubType };
```
### 5.2 使用示例
```javascript
// 外部读取
const { BUSINESS_TYPES, getBusinessTable, isValidSubType } = require('./app/model/after_sale_work_order');
// 获取所有业务类型列表
Object.keys(BUSINESS_TYPES); // ['waybill', 'order_delivery', 'entry_order', ...]
// 获取运单下的子类型
BUSINESS_TYPES.waybill.subtypes; // { intercept: '拦截', urge: '催件', ... }
// 获取关联表
const table = getBusinessTable('waybill'); // 'wms_order_express'
// 校验合法性
isValidSubType('waybill', 'intercept'); // true
isValidSubType('waybill', 'mis_shipment'); // false
```
---
## 六、与现有系统的关联
### 6.1 与业务单据的多态关联(三级定位)
```
wms_after_sale_work_order
.business_type = 'waybill'
.business_sub_type = 'intercept' ← 子类型(Model 常量定义)
.business_id = 12345 ← wms_order_express.id
.business_no = 'YD202607280001' ← 冗余单号
实际关联链路:
business_type → BUSINESS_TYPES[type].table → 确定关联表
business_id → 关联表主键
business_sub_type → 细分工单类别(如拦截/催件/破损)
示例:
├── 'waybill' / 'intercept' → wms_order_express.id
├── 'waybill' / 'urge' → wms_order_express.id
├── 'waybill' / 'damage' → wms_order_express.id
├── 'order_delivery' / 'mis_shipment' → wms_order_delivery.id
├── 'order_delivery' / 'missing_item' → wms_order_delivery.id
├── 'entry_order' / 'shortage' → wms_entry_order.id
├── 'order_stockout' / 'return_issue' → wms_order_stockout.id
├── 'receiving' / 'damage' → wms_receiving.id
└── 'other' / 'general' → 自定义
```
### 6.2 与库存交易的对账
```
售后工单.direction = 1 (入库)
→ stock_transaction.transaction_type = 'INBOUND'
→ stock_transaction.order_type = 'AFTER_SALE' (需同步在 stock_transaction 中新增此类型)
售后工单.direction = 2 (出库)
→ stock_transaction.transaction_type = 'OUTBOUND'
→ stock_transaction.order_type = 'AFTER_SALE'
```
### 6.4 与附件的关联
售后工单不新增附件字段,复用现有 `wms_file_reference` 表做多态附件关联:
```
wms_file_reference
.reference_type = 'after_sale_work_order' ← 固定标识
.reference_id = 工单 id ← wms_after_sale_work_order.id
.file_id = 文件 id ← wms_file.id
示例:一张工单可关联多张图片/多个附件(如破损照片、快递面单照片等)。
```
> `file_reference` 表已支持多态关联(`reference_type` + `reference_id`),无需新建表或字段。
### 6.5 与员工的关联
```
wms_after_sale_work_order.creator_id → account.id(创建人)
wms_after_sale_work_order.assignee_id → account.id(当前处理人)
wms_after_sale_work_order_step.operator_id → account.id(步骤操作人)
```
---
## 七、待确认事项(审阅清单)
请审阅时重点关注以下设计决策:
- [x] **1. `business_type` 枚举值**:`order_delivery` / `entry_order` / `order_stockout` / `waybill` / `receiving` / `other` — ✅ 已确认,暂不增加 `return_order` 独立类型(退货场景通过 `order_stockout` 覆盖)
- [x] **2. `direction` 记账方向**:`1`=入库 / `2`=出库 / `0`=未确定 — ✅ 已确认,细粒度区分由关联的实际出入库单承载
- [x] **3. 工单状态值**:`0-待处理/1-处理中/2-已完成/3-已关闭/9-已取消` — ✅ 已确认,当前中间态足够,无需增加"驳回/退回"
- [x] **4. 预设步骤模板**:不再预设步骤模板,步骤由业务逻辑动态创建 ✅
- [x] **5. `business_id` 多态关联**:采用 `business_type` + `business_sub_type` + `business_id` 三级多态关联,子类型由 Model 常量定义 ✅
- [x] **6. 理赔信息**:已新增 `claim_needed` / `claim_amount` / `claim_status` 三个字段 ✅
- [x] **7. 进度追踪**:进度由主表 `current_step` 字段承载(不再仅依赖副表步骤状态) ✅
- [x] **8. 优先级**:改为 `TINYINT UNSIGNED` 取值范围 `1-100`,由客服或 AI 自动识别填入,默认值 `50` ✅
- [x] **9. AI 创建支持**:`creator_id = 0` 表示 AI 自动接待,`creator_snapshot` 记录模型/会话信息 ✅
- [x] **10. 附件/图片**:复用现有 `wms_file_reference` 表做多态关联,不新增字段 ✅
- [x] **11. 预计完成时间**:暂不增加,后续通过 `created_at` + `priority` 做超时告警替代;SLA 配置表留待后续迭代 ✅
- [x] **12. 关联工单**:已确认新增 `parent_work_order_id` 字段,支持主子工单拆分 ✅
- [x] **13. 表名**:`wms_after_sale_work_order` 和 `wms_after_sale_work_order_step` — ✅ 已确认
- [x] **14. 权限**:API 接口设计阶段再补录 `wms_permission` 记录,不阻塞表落库 ✅
---
## 八、后续落库计划(审阅通过后执行)
1. 创建迁移文件 `database/migrations/20260728XXXXXX-create-wms-after-sale-work-order.js`
2. 创建迁移文件 `database/migrations/20260728XXXXXX-create-wms-after-sale-work-order-step.js`
3. 创建 Model 文件 `app/model/after_sale_work_order.js`
4. 创建 Model 文件 `app/model/after_sale_work_order_step.js`
5. 在 `methods/system.json` 中新增接口路由
6. 如需,在 `stock_transaction.order_type` 中新增 `AFTER_SALE` 枚举值(独立迁移)
7. 如需,新增 `wms_permission` 权限记录

View File

@ -1,115 +0,0 @@
'use strict';
const TABLE_NAME = 'wms_after_sale_work_order_step';
module.exports = {
up: async (queryInterface, Sequelize) => {
const tables = await queryInterface.showAllTables();
const exists = tables.some(t => (typeof t === 'string' ? t : t.tableName) === TABLE_NAME);
if (exists) return;
await queryInterface.createTable(TABLE_NAME, {
id: {
type: Sequelize.BIGINT(20).UNSIGNED,
primaryKey: true,
autoIncrement: true,
allowNull: false,
comment: '主键ID',
},
work_order_id: {
type: Sequelize.BIGINT(20).UNSIGNED,
allowNull: false,
comment: '工单ID,关联 wms_after_sale_work_order.id',
},
step_order: {
type: Sequelize.TINYINT.UNSIGNED,
allowNull: false,
defaultValue: 1,
comment: '步骤序号(从1开始递增)',
},
step_name: {
type: Sequelize.STRING(100),
allowNull: false,
comment: '步骤名称',
},
step_status: {
type: Sequelize.TINYINT.UNSIGNED,
allowNull: false,
defaultValue: 0,
comment: '步骤状态:0=待开始 1=进行中 2=已完成 3=已跳过',
},
operator_id: {
type: Sequelize.BIGINT(20).UNSIGNED,
allowNull: true,
comment: '操作员工ID,关联 account.id',
},
operator_snapshot: {
type: Sequelize.TEXT,
allowNull: true,
comment: '操作人信息快照(JSON格式)',
},
action: {
type: Sequelize.STRING(100),
allowNull: true,
comment: '操作动作描述',
},
remark: {
type: Sequelize.TEXT,
allowNull: true,
comment: '处理备注',
},
started_at: {
type: Sequelize.DATE,
allowNull: true,
comment: '步骤开始时间',
},
completed_at: {
type: Sequelize.DATE,
allowNull: true,
comment: '步骤完成时间',
},
created_at: {
type: Sequelize.DATE,
allowNull: false,
defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'),
comment: '创建时间',
},
updated_at: {
type: Sequelize.DATE,
allowNull: false,
defaultValue: Sequelize.literal('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'),
comment: '更新时间',
},
deleted_at: {
type: Sequelize.DATE,
allowNull: true,
comment: '软删除时间',
},
});
// 按工单查所有步骤
await queryInterface.addIndex(TABLE_NAME, [ 'work_order_id' ], {
name: 'idx_work_order_id',
});
// 按操作人反查
await queryInterface.addIndex(TABLE_NAME, [ 'operator_id' ], {
name: 'idx_operator_id',
});
// 软删除查询优化
await queryInterface.addIndex(TABLE_NAME, [ 'deleted_at' ], {
name: 'idx_deleted_at',
});
// 同一工单下步骤序号唯一(含软删除)
await queryInterface.addIndex(TABLE_NAME, [ 'work_order_id', 'step_order', 'deleted_at' ], {
unique: true,
name: 'uk_work_order_step',
});
},
down: async queryInterface => {
await queryInterface.dropTable(TABLE_NAME);
},
};

View File

@ -1,14 +1,18 @@
'use strict';
'use strict';
const TABLE_NAME = 'wms_after_sale_work_order';
const TABLE_MAIN = 'wms_after_sale_work_order';
const TABLE_STEP = 'wms_after_sale_work_order_step';
module.exports = {
up: async (queryInterface, Sequelize) => {
const tables = await queryInterface.showAllTables();
const exists = tables.some(t => (typeof t === 'string' ? t : t.tableName) === TABLE_NAME);
if (exists) return;
// 先删子表(步骤表),再删主表(工单表)
await queryInterface.dropTable(TABLE_STEP);
await queryInterface.dropTable(TABLE_MAIN);
},
await queryInterface.createTable(TABLE_NAME, {
down: async (queryInterface, Sequelize) => {
// ========== 1. 重建主表:wms_after_sale_work_order ==========
await queryInterface.createTable(TABLE_MAIN, {
id: {
type: Sequelize.BIGINT(20).UNSIGNED,
primaryKey: true,
@ -152,64 +156,101 @@ module.exports = {
},
});
// 工单号唯一
await queryInterface.addIndex(TABLE_NAME, [ 'work_order_no' ], {
unique: true,
name: 'uk_work_order_no',
await queryInterface.addIndex(TABLE_MAIN, ['work_order_no'], { unique: true, name: 'uk_work_order_no' });
await queryInterface.addIndex(TABLE_MAIN, ['warehouse_id'], { name: 'idx_warehouse_id' });
await queryInterface.addIndex(TABLE_MAIN, ['store_id'], { name: 'idx_store_id' });
await queryInterface.addIndex(TABLE_MAIN, ['business_type', 'business_sub_type', 'business_id'], { name: 'idx_business_type_subtype_id' });
await queryInterface.addIndex(TABLE_MAIN, ['status'], { name: 'idx_status' });
await queryInterface.addIndex(TABLE_MAIN, ['assignee_id'], { name: 'idx_assignee_id' });
await queryInterface.addIndex(TABLE_MAIN, ['parent_work_order_id'], { name: 'idx_parent_work_order_id' });
await queryInterface.addIndex(TABLE_MAIN, ['priority'], { name: 'idx_priority' });
await queryInterface.addIndex(TABLE_MAIN, ['claim_status'], { name: 'idx_claim_status' });
await queryInterface.addIndex(TABLE_MAIN, ['created_at'], { name: 'idx_created_at' });
await queryInterface.addIndex(TABLE_MAIN, ['deleted_at'], { name: 'idx_deleted_at' });
// ========== 2. 重建子表:wms_after_sale_work_order_step ==========
await queryInterface.createTable(TABLE_STEP, {
id: {
type: Sequelize.BIGINT(20).UNSIGNED,
primaryKey: true,
autoIncrement: true,
allowNull: false,
comment: '主键ID',
},
work_order_id: {
type: Sequelize.BIGINT(20).UNSIGNED,
allowNull: false,
comment: '工单ID,关联 wms_after_sale_work_order.id',
},
step_order: {
type: Sequelize.TINYINT.UNSIGNED,
allowNull: false,
defaultValue: 1,
comment: '步骤序号(从1开始递增)',
},
step_name: {
type: Sequelize.STRING(100),
allowNull: false,
comment: '步骤名称',
},
step_status: {
type: Sequelize.TINYINT.UNSIGNED,
allowNull: false,
defaultValue: 0,
comment: '步骤状态:0=待开始 1=进行中 2=已完成 3=已跳过',
},
operator_id: {
type: Sequelize.BIGINT(20).UNSIGNED,
allowNull: true,
comment: '操作员工ID,关联 account.id',
},
operator_snapshot: {
type: Sequelize.TEXT,
allowNull: true,
comment: '操作人信息快照(JSON格式)',
},
action: {
type: Sequelize.STRING(100),
allowNull: true,
comment: '操作动作描述',
},
remark: {
type: Sequelize.TEXT,
allowNull: true,
comment: '处理备注',
},
started_at: {
type: Sequelize.DATE,
allowNull: true,
comment: '步骤开始时间',
},
completed_at: {
type: Sequelize.DATE,
allowNull: true,
comment: '步骤完成时间',
},
created_at: {
type: Sequelize.DATE,
allowNull: false,
defaultValue: Sequelize.literal('CURRENT_TIMESTAMP'),
comment: '创建时间',
},
updated_at: {
type: Sequelize.DATE,
allowNull: false,
defaultValue: Sequelize.literal('CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP'),
comment: '更新时间',
},
deleted_at: {
type: Sequelize.DATE,
allowNull: true,
comment: '软删除时间',
},
});
// 仓库隔离查询
await queryInterface.addIndex(TABLE_NAME, [ 'warehouse_id' ], {
name: 'idx_warehouse_id',
});
// 货主隔离查询
await queryInterface.addIndex(TABLE_NAME, [ 'store_id' ], {
name: 'idx_store_id',
});
// 按业务类型+子类型+单据ID反查工单
await queryInterface.addIndex(TABLE_NAME, [ 'business_type', 'business_sub_type', 'business_id' ], {
name: 'idx_business_type_subtype_id',
});
// 按状态筛选
await queryInterface.addIndex(TABLE_NAME, [ 'status' ], {
name: 'idx_status',
});
// 按处理人查询
await queryInterface.addIndex(TABLE_NAME, [ 'assignee_id' ], {
name: 'idx_assignee_id',
});
// 按父工单查子工单
await queryInterface.addIndex(TABLE_NAME, [ 'parent_work_order_id' ], {
name: 'idx_parent_work_order_id',
});
// 按优先级排序
await queryInterface.addIndex(TABLE_NAME, [ 'priority' ], {
name: 'idx_priority',
});
// 按理赔状态筛选
await queryInterface.addIndex(TABLE_NAME, [ 'claim_status' ], {
name: 'idx_claim_status',
});
// 按时间排序
await queryInterface.addIndex(TABLE_NAME, [ 'created_at' ], {
name: 'idx_created_at',
});
// 软删除查询优化
await queryInterface.addIndex(TABLE_NAME, [ 'deleted_at' ], {
name: 'idx_deleted_at',
});
},
down: async queryInterface => {
await queryInterface.dropTable(TABLE_NAME);
await queryInterface.addIndex(TABLE_STEP, ['work_order_id'], { name: 'idx_work_order_id' });
await queryInterface.addIndex(TABLE_STEP, ['operator_id'], { name: 'idx_operator_id' });
await queryInterface.addIndex(TABLE_STEP, ['deleted_at'], { name: 'idx_deleted_at' });
await queryInterface.addIndex(TABLE_STEP, ['work_order_id', 'step_order', 'deleted_at'], { unique: true, name: 'uk_work_order_step' });
},
};