商品管理控制器文档

接口信息

• 控制器类: MallItemController
• 包路径: com.qisheng.mall.web
• 功能描述: 负责处理商城商品的增删改查操作

类图

接口列表

1. 获取商品列表

• 请求方式: GET
• URL: /{merchantId}/mall_item 或 /{merchantId}/mp_mall_item
• 功能: 分页获取商品列表
• 参数:
  • merchantId: 商户ID (路径参数)
  • mallItemReq: 商品查询请求对象 (查询参数)
• 返回: PageResponse
• 示例:

GET /82/mall_item?categoryId=123&isOnSale=Y&pageNum=1&pageSize=20

2. 添加商品

• 请求方式: POST
• URL: /{merchantId}/mall_item
• 功能: 创建新的商品
• 参数:
  • merchantId: 商户ID (路径参数)
  • mallItemReq: 商品请求对象 (请求体)
• 返回: ObjectResponse<MallItem>
• 示例:

POST /82/mall_item
{
  "name": "测试商品",
  "type": "NORMAL",
  "categoryId": 123,
  "price": 10000,
  "originalPrice": 12000,
  "stock": 100,
  "isOnSale": "Y",
  "images": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"],
  "description": "商品详情描述"
}

3. 更新商品

• 请求方式: PUT 或 PATCH
• URL: /{merchantId}/mall_item/{id}
• 功能: 更新商品信息
• 参数:
  • merchantId: 商户ID (路径参数)
  • id: 商品ID (路径参数)
  • request: 更新数据的JSON对象 (请求体)
• 返回: BaseResponse
• 示例:

PATCH /82/mall_item/123
{
  "name": "更新后的商品名称",
  "price": 9900,
  "stock": 200
}

4. 删除商品

• 请求方式: DELETE
• URL: /{merchantId}/mall_item/{id}
• 功能: 删除商品
• 参数:
  • merchantId: 商户ID (路径参数)
  • id: 商品ID (路径参数)
• 返回: BaseResponse
• 示例:

DELETE /82/mall_item/123

5. 根据ID获取商品

• 请求方式: GET
• URL: /{merchantId}/mall_item/{id} 或 /{merchantId}/mp_mall_item/{id}
• 功能: 获取指定ID的商品详情
• 参数:
  • merchantId: 商户ID (路径参数)
  • id: 商品ID (路径参数)
  • mallItemReq: 商品查询请求对象 (查询参数)
• 返回: ObjectResponse
• 示例:

GET /82/mall_item/123

6. 获取营销商品

• 请求方式: GET
• URL: /{merchantId}/mp_mall_item_marketing
• 功能: 获取营销商品列表
• 参数:
  • merchantId: 商户ID (路径参数)
  • mallItemReq: 商品查询请求对象 (查询参数)
• 返回: ObjectResponse
• 示例:

GET /82/mp_mall_item_marketing?marketingType=GROUP_BUYING

7. 上下架商品

• 请求方式: PUT
• URL: /{merchantId}/sale_mall_item
• 功能: 修改商品上下架状态
• 参数:
  • merchantId: 商户ID (路径参数)
  • mallItemReq: 商品请求对象 (请求体)
• 返回: ObjectResponse
• 示例:

PUT /82/sale_mall_item
{
  "mallItemIds": [123, 456, 789],
  "isOnSale": "Y"
}

8. 批量保存商品

• 请求方式: PUT 或 PATCH
• URL: /{merchantId}/mall_item
• 功能: 批量保存商品信息
• 参数:
  • merchantId: 商户ID (路径参数)
  • batchUpdateMallItemReq: 批量更新商品请求对象 (请求体)
• 返回: BaseResponse
• 示例:

PATCH /82/mall_item
{
  "items": [
    {
      "id": 123,
      "name": "商品1",
      "price": 10000
    },
    {
      "id": 456,
      "name": "商品2",
      "price": 20000
    }
  ]
}

9. 批量添加商品

• 请求方式: POST
• URL: /{merchantId}/batch_add_mall_item
• 功能: 批量添加商品
• 参数:
  • merchantId: 商户ID (路径参数)
  • batchUpdateMallItemReq: 批量添加商品请求对象 (请求体)
• 返回: ObjectResponse
• 示例:

POST /82/batch_add_mall_item
{
  "items": [
    {
      "name": "商品1",
      "type": "NORMAL",
      "categoryId": 123,
      "price": 10000
    },
    {
      "name": "商品2",
      "type": "NORMAL",
      "categoryId": 123,
      "price": 20000
    }
  ]
}

10. 批量更新商品分类

• 请求方式: POST
• URL: /{merchantId}/batch_update_mall_item_category
• 功能: 批量更新商品分类
• 参数:
  • merchantId: 商户ID (路径参数)
  • batchUpdateMallItemCategoryReq: 批量更新商品分类请求对象 (请求体)
• 返回: ObjectResponse
• 示例:

POST /82/batch_update_mall_item_category
{
  "mallItemIds": [123, 456, 789],
  "categoryId": 456
}

11. 获取线下商品列表

• 请求方式: GET
• URL: /{merchantId}/offline_item
• 功能: 获取线下商品列表
• 参数:
  • merchantId: 商户ID (路径参数)
  • offlineItemReq: 线下商品请求对象 (查询参数)
• 返回: PageResponse<List<OffLineItemDTO>>
• 示例:

GET /82/offline_item?pageNum=1&pageSize=20

12. 获取线下商品信息

• 请求方式: POST
• URL: /{merchantId}/offline_item_info
• 功能: 获取线下商品信息
• 参数:
  • merchantId: 商户ID (路径参数)
  • itemListReq: 商品列表请求对象 (请求体)
• 返回: ObjectResponse<List<OffLineItemDTO>>
• 示例:

POST /82/offline_item_info
{
  "itemIds": [123, 456, 789]
}

13. 获取线下商品数量

• 请求方式: GET
• URL: /{merchantId}/offline_item_count
• 功能: 获取线下商品数量
• 参数:
  • merchantId: 商户ID (路径参数)
  • offlineItemReq: 线下商品请求对象 (查询参数)
• 返回: ObjectResponse<List<OffLineItemCountDTO>>
• 示例:

GET /82/offline_item_count

调用流程

1. 获取商品列表流程

2. 添加商品流程

SQL查询

商品统计SQL

-- 根据分类统计商品数量
SELECT CATEGORY_ID, COUNT(id) AS itemCount 
FROM T_MALL_ITEM 
WHERE MERCHANT_ID = #{merchantId} 
  AND status = 'NORMAL' 
  AND CATEGORY_ID IS NOT NULL 
GROUP BY CATEGORY_ID

库存回滚SQL

-- 订单取消时回滚商品库存
UPDATE T_MALL_ITEM a
JOIN (
  SELECT
    MALL_ITEM_ID,
    SUM(IFNULL(MALL_ITEM_NUM, 0)) AS MALL_ITEM_NUM
  FROM ${mallOrderItemTableName}
  WHERE STATUS = 'CREATED'
    AND CREATE_TS <= #{entity.createTs}
    AND MALL_ORDER_ID = #{entity.id}
  GROUP BY MALL_ITEM_ID
) b ON a.id = b.MALL_ITEM_ID
SET a.STOCK = a.STOCK + b.MALL_ITEM_NUM,
    a.sold = a.sold - b.MALL_ITEM_NUM

订单项回滚SQL

-- 根据订单项回滚商品库存
UPDATE T_MALL_ITEM 
SET STOCK = STOCK + #{entity.mallItemNum},
    sold = sold - #{entity.mallItemNum} 
WHERE MERCHANT_ID = #{entity.merchantId} 
  AND id = #{entity.mallItemId}

主要功能说明

商品类型

• NORMAL: 普通商品
• CARD: 会员卡
• SERVICE: 项目
• GOODS: 卖品

营销类型

• NORMAL: 不启用营销
• GROUP_BUYING: 团购
• RUSH: 抢购

商品状态

• NORMAL: 正常
• DELETED: 已删除

指定阶段

• POTENTIAL: 潜客
• ALL: 所有
• MEMBER: 会员

注意事项

1. 数据表说明

• T_MALL_ITEM: 商品表，存储商品的基本信息和规则

2. 权限控制

• 商户ID: 通过商户ID进行权限控制，只能操作自己商户的商品

3. 业务逻辑

• 商品上下架: 通过 isOnSale 字段控制商品是否上架
• 商品库存: 商品库存不能为负数，如果为负数，会返回0
• 商品营销: 通过 marketingType 和 marketingDetail 字段控制商品的营销方式和详情

4. 商品特性

• 积分兑换: 通过 enablePoint、needPoint 等字段控制商品是否支持积分兑换
• 积分抵扣: 通过 enableUsePoint、maxUsePoint 等字段控制商品是否支持积分抵扣
• 会员卡支付: 通过 enableCard 字段控制商品是否支持会员卡支付
• 优惠券抵扣: 通过 enableCoupon、limitedCouponAmount 等字段控制商品是否支持优惠券抵扣
• 赠送商品: 通过 enableBonusItem、bonusItem 等字段控制商品是否赠送其他商品
• 赠送优惠券: 通过 enableBonusCoupon、bonusCoupon 等字段控制商品是否赠送优惠券
• 赠送积分: 通过 enableBonusPoint、bonusPoint 等字段控制商品是否赠送积分

5. 商品核销

• 核销天数: 通过 writeoffDays 字段控制商品可核销天数
• 核销时间: 通过 writeoffStartTime、writeoffEndTime 字段控制商品可核销时间段
• 核销门店: 通过 writeoffShop 字段控制商品可核销门店

6. 商品限制

• 单人购买限制: 通过 limitedSingleUser 字段控制单人可购买数量
• 单人兑换限制: 通过 limitedSingleExchange 字段控制单人可兑换数量
• 最大售卖限制: 通过 limitedSold 字段控制最大可售卖数量