10 KiB
10 KiB
组合商品(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
}
}