388 lines
10 KiB
Markdown
388 lines
10 KiB
Markdown
# 组合商品(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
|
||
}
|
||
}
|
||
```
|