WMS_MAIN/database/designs/after-sale-api-design.md

24 KiB
Raw Blame History

售后工单 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 记录关键状态变更?