24 KiB
24 KiB
售后工单 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 — 获取业务类型枚举
{
"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 — 工单列表
{
"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 — 工单详情
{
"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 — 创建工单
{
"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 — 更新工单基本信息
{
"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 — 删除工单
{
"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 — 分配处理人
{
"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 — 完成工单
{
"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 — 关闭工单
{
"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 — 取消工单
{
"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 — 开始步骤
{
"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 — 完成步骤
{
"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 — 跳过步骤
{
"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 数组末尾追加:
{
"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记录关键状态变更?