# 组合商品(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筛选 | #### 请求示例 ```json { "method": "comboGoods.list", "data": { "pagination": { "page": 1, "pageSize": 20 }, "where": { "combo_name": "春节礼包", "status": 1 } } } ``` #### 响应格式 ```json { "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 | 否 | 排序号,默认按数组索引 | #### 请求示例 ```json { "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 } ] } } ``` #### 响应格式 ```json { "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 为可选,不传或传空数组则保持原明细不变。 #### 请求示例 ```json { "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 } ] } } ``` #### 响应格式 ```json { "code": 200, "message": "编辑成功", "data": { "id": 1 } } ``` --- ### 4. comboGoods.delete — 删除组合商品 - **鉴权**:需要(isNeedAuth=true) - **登录**:需要 #### 请求参数 | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | id | number | 是 | 组合商品ID | > **注意**:删除操作为软删除,仅将 `status` 置为 0(停用),不会物理删除记录。 #### 请求示例 ```json { "method": "comboGoods.delete", "data": { "id": 1 } } ``` #### 响应格式 ```json { "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)的记录。该接口用于手工建单时前端选择组合商品。 #### 请求示例 ```json { "method": "comboGoods.search", "data": { "keyword": "礼包", "limit": 30 } } ``` #### 响应格式 ```json { "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 } } ```