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

388 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 组合商品(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
}
}
```