WMS_MAIN/docs/combo-goods-api.md
liufumingren 77435aeb79 1
2026-06-23 18:48:33 +08:00

10 KiB
Raw Blame History

组合商品(comboGoods)模块 API 文档

模块概述

组合商品(comboGoods)模块提供组合商品的 CRUD 和搜索功能。组合商品是将多个系统商品(来自 wms_stock_warehouse)捆绑在一起的商品概念,用于订单快速选择。

代码文件:

  • 业务逻辑层:app/service/systems/comboGoods.js
  • 接口包装层:app/service/systemMethods/comboGoods.js

数据表:

  • wms_combo_goods:组合商品主表
  • wms_combo_goods_item:组合商品明细表

数据库表结构

主表:wms_combo_goods

字段 类型 说明
id number 主键ID
combo_code string 组合商品编码(唯一)
combo_name string 组合商品名称
combo_sku_id number 组合商品SKU ID
custom_code string|null 自定义编码,按货主唯一(排除已删除记录)
status number 状态:1=启用 0=停用
warehouse_id number|null 仓库ID
remark string 备注
creator_id number 创建人ID
editor_id number 最后编辑人ID
created_at datetime 创建时间
updated_at datetime 更新时间

明细表:wms_combo_goods_item

字段 类型 说明
id number 主键ID
combo_id number 关联的组合商品ID
item_goods_sku_id number 子商品 stock_id(对应 wms_stock_warehouse.id)
item_quantity number 子商品数量
sort_order number 排序号

约束规则

商品有效性校验

创建/编辑组合商品时,所有子商品必须在 wms_stock_warehouse 表中满足以下条件:

  • is_valid = 'Y'(有效状态)
  • deleted_at IS NULL(未删除)

任一子商品不满足条件,操作将被拒绝并返回具体的不合法 stock_id 列表。

货主一致性校验

所有子商品必须属于同一个货主(store_id 一致)。跨货主组合将返回错误:「所有子商品必须属于同一个货主,不允许跨货主组合」。

自定义编码(custom_code)校验

custom_code 为可选字段(VARCHAR(64)),仅做按货主唯一性校验(排除 status=0 的已删除记录)。

  • create:如果传入非空的 custom_code,会校验同货主非删除记录中唯一。
  • update:如果传入非空的 custom_code,会校验同货主非删除记录中唯一(排除自身 id)。
  • 唯一索引:uk_store_custom_code(warehouse_id, custom_code)。

简记格式说明

列表查询和搜索结果中会返回两种简记字段,供前端直接展示:

simpleNotation(字符串简记)

格式:stock_id|数量,stock_id2|数量

示例:1001|3,1002|5 表示 stock_id=1001 的商品 3 件 + stock_id=1002 的商品 5 件。

nameNotation(商品名称简记)

格式:【数量】商品名称+【数量】商品名称

示例:【3】苹果+【5】香蕉 表示苹果 3 件 + 香蕉 5 件。

商品名称从 wms_stock_warehouse.item_name 获取;若 stock_id 无有效商品信息,则显示为 SKU#stock_id。


接口列表

1. comboGoods.list — 组合商品列表查询(分页)

  • 鉴权:不需要(isNeedAuth=false)
  • 登录:需要

请求参数

字段 类型 必填 说明
pagination object 否 分页参数
pagination.page number 否 页码,默认 1
pagination.pageSize number 否 每页大小,默认 20,最大 200
where object 否 筛选条件
where.combo_code string 否 组合商品编码,精确匹配
where.combo_name string 否 组合商品名称,模糊匹配
where.status number 否 状态筛选:1=启用 0=停用
where.warehouse_id number 否 仓库ID筛选

请求示例

{
  "method": "comboGoods.list",
  "data": {
    "pagination": {
      "page": 1,
      "pageSize": 20
    },
    "where": {
      "combo_name": "春节礼包",
      "status": 1
    }
  }
}

响应格式

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "list": [
      {
        "id": 1,
        "combo_code": "COMBO-001",
        "combo_name": "春节礼包A",
        "combo_sku_id": 0,
        "custom_code": null,
        "status": 1,
        "warehouse_id": 1001,
        "remark": "",
        "creator_id": 10,
        "editor_id": 10,
        "created_at": "2026-06-01T10:00:00.000Z",
        "updated_at": "2026-06-01T10:00:00.000Z",
        "items": [
          {
            "id": 1,
            "combo_id": 1,
            "item_goods_sku_id": 1001,
            "item_quantity": 3,
            "sort_order": 0
          },
          {
            "id": 2,
            "combo_id": 1,
            "item_goods_sku_id": 1002,
            "item_quantity": 5,
            "sort_order": 1
          }
        ],
        "simpleNotation": "1001|3,1002|5",
        "nameNotation": "【3】苹果+【5】香蕉"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}

2. comboGoods.create — 创建组合商品

  • 鉴权:需要(isNeedAuth=true)
  • 登录:需要

请求参数

字段 类型 必填 说明
combo_code string 是 组合商品编码,全局唯一
combo_name string 是 组合商品名称
warehouse_id number 否 仓库ID
remark string 否 备注
custom_code string 否 自定义编码,传入时校验按货主唯一(排除已删除记录)
items array 是 子商品明细数组
items[].item_goods_sku_id number 是 子商品 stock_id
items[].item_quantity number 是 子商品数量(正整数)
items[].sort_order number 否 排序号,默认按数组索引

请求示例

{
  "method": "comboGoods.create",
  "data": {
    "combo_code": "COMBO-001",
    "combo_name": "春节礼包A",
    "warehouse_id": 1001,
    "remark": "2026春节促销礼包",
    "items": [
      { "item_goods_sku_id": 1001, "item_quantity": 3 },
      { "item_goods_sku_id": 1002, "item_quantity": 5 }
    ]
  }
}

响应格式

{
  "code": 200,
  "message": "创建成功",
  "data": {
    "id": 1,
    "combo_code": "COMBO-001",
    "combo_name": "春节礼包A",
    "custom_code": null
  }
}

常见错误

错误信息 说明
组合商品编码不能为空 combo_code 未传或为空
组合商品名称不能为空 combo_name 未传或为空
子商品列表不能为空 items 未传或为空数组
组合商品编码 "XXX" 已存在 combo_code 重复
自定义编码 "XXX" 已被货主其他组合商品使用 custom_code 在同一货主下重复(排除已删除)
以下子商品不存在或已停用:1001, 1002 子商品在 wms_stock_warehouse 中不存在或已停用
所有子商品必须属于同一个货主,不允许跨货主组合 明细中商品的 store_id 不一致

3. comboGoods.update — 编辑组合商品

  • 鉴权:需要(isNeedAuth=true)
  • 登录:需要

请求参数

字段 类型 必填 说明
id number 是 组合商品ID
combo_name string 否 组合商品名称
warehouse_id number 否 仓库ID
remark string 否 备注
custom_code string 否 自定义编码,传入非空值时校验按货主唯一(排除已删除记录和自身 id)
status number 否 状态:1=启用 0=停用
items array 否 子商品明细数组。传入非空数组时先删旧明细再插入新明细;不传保持原明细不变
items[].item_goods_sku_id number 是 子商品 stock_id
items[].item_quantity number 是 子商品数量(正整数)
items[].sort_order number 否 排序号

注意:部分更新语义——不传的字段保持原值不变。items 为可选,不传或传空数组则保持原明细不变。

请求示例

{
  "method": "comboGoods.update",
  "data": {
    "id": 1,
    "combo_name": "春节礼包A(升级版)",
    "remark": "更新备注",
    "items": [
      { "item_goods_sku_id": 1001, "item_quantity": 5 },
      { "item_goods_sku_id": 1003, "item_quantity": 2 }
    ]
  }
}

响应格式

{
  "code": 200,
  "message": "编辑成功",
  "data": {
    "id": 1
  }
}

4. comboGoods.delete — 删除组合商品

  • 鉴权:需要(isNeedAuth=true)
  • 登录:需要

请求参数

字段 类型 必填 说明
id number 是 组合商品ID

注意:删除操作为软删除,仅将 status 置为 0(停用),不会物理删除记录。

请求示例

{
  "method": "comboGoods.delete",
  "data": {
    "id": 1
  }
}

响应格式

{
  "code": 200,
  "message": "删除成功",
  "data": {
    "id": 1
  }
}

5. comboGoods.search — 关键字搜索组合商品

  • 鉴权:不需要(isNeedAuth=false)
  • 登录:需要

请求参数

字段 类型 必填 说明
keyword string 是 搜索关键字,模糊匹配 custom_code、combo_code 和 combo_name,custom_code 匹配项优先排在前面
limit number 否 最大返回条数,默认 20,最大 100

注意:仅返回启用状态(status=1)的记录。该接口用于手工建单时前端选择组合商品。

请求示例

{
  "method": "comboGoods.search",
  "data": {
    "keyword": "礼包",
    "limit": 30
  }
}

响应格式

{
  "code": 200,
  "message": "搜索成功",
  "data": {
    "list": [
      {
        "id": 1,
        "combo_code": "COMBO-001",
        "combo_name": "春节礼包A",
        "custom_code": null,
        "status": 1,
        "warehouse_id": 1001,
        "items": [
          { "id": 1, "combo_id": 1, "item_goods_sku_id": 1001, "item_quantity": 3, "sort_order": 0 }
        ],
        "simpleNotation": "1001|3,1002|5",
        "nameNotation": "【3】苹果+【5】香蕉"
      }
    ],
    "total": 1
  }
}