scaffold-product 商品管理模块
模块概述
scaffold-product 是 Scaffold v2 的商品管理模块，提供完整的电商商品体系。涵盖 SPU/SKU 商品模型、分类/品牌/规格基础数据、购物车、秒杀活动和拼团活动。分为管理端（Admin）和移动端（Mobile）两套 API，管理端负责商品全生命周期管理，移动端面向 C 端用户浏览和购买。
功能列表
- 商品管理（SPU/SKU）：商品创建、审核、上下架，支持多规格 SKU
- 分类管理：树形商品分类，支持多级分类结构
- 品牌管理：品牌 CRUD，启用/禁用控制
- 规格模板：规格模板 CRUD，商品创建时选择规格模板
- 购物车：移动端购物车，支持增删改查、全选、批量操作
- 秒杀活动：秒杀活动创建/取消，Redis 原子扣减库存，移动端秒杀下单
- 拼团活动：拼团活动管理，开团/参团，成团判定
- 商品审核：BPM 审核集成，支持提交审核/撤回/审核回调
- 商品缓存：Redis 缓存商品详情和秒杀库存，提高查询性能
状态字段规范：
status 字段（品牌、SPU、SKU、规格模板、分类）遵循布尔语义：1 = 启用，0 = 禁用
核心组件
分层架构
| 层 |
类 |
职责 |
| Controller |
ProductSpuController, ProductCategoryController, ProductBrandController, ProductSpecTemplateController, ProductFlashSaleController, ProductGroupBuyController, MobileProductController, MobileCartController, MobileFlashSaleController, MobileGroupBuyController |
REST 接口 |
| Service |
ProductSpuService, ProductCategoryService, ProductBrandService, ProductSpecTemplateService, ProductSkuService, ProductCartService, ProductFlashSaleService, ProductGroupBuyService |
业务逻辑 |
| Repository |
对应每种实体的 Repository |
数据访问 |
| Mapper |
对应每种实体的 Mapper |
ORM 映射 |
数据实体
| 实体 |
说明 |
| ProductSpu |
商品 SPU（标准产品单元） |
| ProductSpuDetail |
商品详情（富文本描述等） |
| ProductSku |
商品 SKU（库存量单元），关联 SPU 和规格值 |
| ProductCategory |
商品分类，树形结构 |
| ProductBrand |
商品品牌 |
| ProductSpecTemplate |
规格模板 |
| ProductCart |
购物车 |
| ProductFlashSale |
秒杀活动 |
| ProductFlashSaleRecord |
秒杀记录 |
| ProductGroupBuy |
拼团活动 |
| ProductGroup |
团（一次拼团的实例） |
| ProductGroupMember |
团成员 |
缓存设计
依赖 scaffold-redis 模块（可选），当 Redis 可用时自动启用缓存。
| 缓存 Key |
TTL |
说明 |
| product:detail:{id} |
30 分钟 |
商品详情缓存 |
| flash:detail:{id} |
5 分钟 |
秒杀活动详情缓存 |
| flash:stock:{id} |
无过期 |
秒杀库存，使用 Redis DECR 原子扣减 |
BPM 审核
商品提交审核后通过 BpmIntegrationService（定义在 scaffold-common）发起 BPM 流程。审核完成后回调 ProductAuditCallback.auditCallback 接口更新商品状态。当 BPM 模块未启用时，自动降级为直接通过。
配置参数
配置前缀：scaffold.product
| 参数 |
类型 |
默认值 |
说明 |
| enabled |
boolean |
true |
模块开关 |
API 接口列表
管理端 API
ProductSpuController -- 商品 SPU 管理 (/v1/product/spu)
| 方法 |
路径 |
说明 |
| POST |
/page |
分页查询商品 SPU |
| GET |
/detail/{id} |
查询商品详情（含 SKU 列表） |
| POST |
/create |
创建商品 SPU |
| POST |
/update |
更新商品 SPU |
| POST |
/submitAudit/{id} |
提交审核 |
| POST |
/withdrawAudit/{id} |
撤回审核 |
| POST |
/putOnShelf/{id} |
上架商品 |
| POST |
/takeOffShelf/{id} |
下架商品 |
| POST |
/delete/{id} |
删除商品 |
| POST |
/batchPutOnShelf |
批量上架 |
| POST |
/batchTakeOffShelf |
批量下架 |
| GET |
/skuList/{spuId} |
根据 SPU ID 获取 SKU 列表（活动选择器用） |
| POST |
/auditCallback |
BPM 审核回调 |
ProductCategoryController -- 商品分类管理 (/v1/product/category)
| 方法 |
路径 |
说明 |
| POST |
/create |
创建商品分类 |
| POST |
/update |
更新商品分类 |
| POST |
/delete/{id} |
删除商品分类 |
| GET |
/get/{id} |
查询分类详情 |
| GET |
/list |
查询分类列表 |
| GET |
/tree |
查询分类树 |
ProductBrandController -- 商品品牌管理 (/v1/product/brand)
| 方法 |
路径 |
说明 |
| POST |
/page |
分页查询品牌 |
| GET |
/get/{id} |
品牌详情 |
| POST |
/create |
创建品牌 |
| POST |
/update |
更新品牌 |
| POST |
/delete/{id} |
删除品牌 |
| GET |
/list |
查询全部启用品牌（下拉列表） |
ProductSpecTemplateController -- 规格模板管理 (/v1/product/spec-template)
| 方法 |
路径 |
说明 |
| POST |
/page |
分页查询规格模板 |
| POST |
/create |
创建规格模板 |
| POST |
/update |
更新规格模板 |
| POST |
/delete/{id} |
删除规格模板 |
| GET |
/get/{id} |
规格模板详情 |
| GET |
/list |
查询所有启用的规格模板 |
ProductFlashSaleController -- 秒杀活动管理 (/v1/product/flash-sale)
| 方法 |
路径 |
说明 |
| POST |
/page |
分页查询秒杀活动 |
| GET |
/get/{id} |
秒杀活动详情 |
| POST |
/create |
创建秒杀活动 |
| POST |
/update |
更新秒杀活动 |
| POST |
/cancel/{id} |
取消秒杀活动 |
| POST |
/delete/{id} |
删除秒杀活动 |
ProductGroupBuyController -- 拼团活动管理 (/v1/product/group-buy)
| 方法 |
路径 |
说明 |
| POST |
/page |
分页查询拼团活动 |
| GET |
/get/{id} |
拼团活动详情 |
| POST |
/create |
创建拼团活动 |
| POST |
/update?id= |
更新拼团活动 |
| POST |
/cancel/{id} |
取消拼团活动 |
| POST |
/delete/{id} |
删除拼团活动 |
| GET |
/groups/{id} |
查询活动下的团列表 |
移动端 API
MobileProductController -- 移动端商品 (/v1/mobile/product)
| 方法 |
路径 |
说明 |
| GET |
/list |
商品列表 |
| GET |
/detail/{id} |
商品详情 |
MobileCartController -- 移动端购物车 (/v1/mobile/cart)
| 方法 |
路径 |
说明 |
| GET |
/list |
我的购物车 |
| POST |
/add |
加入购物车 |
| POST |
/updateQuantity |
修改数量 |
| POST |
/remove |
移除购物车项（批量） |
| POST |
/clear |
清空购物车 |
| POST |
/toggleSelect?id=&selected= |
切换选中状态 |
| POST |
/selectAll?selected= |
全选/取消全选 |
MobileFlashSaleController -- 移动端秒杀 (/v1/mobile/flash-sale)
| 方法 |
路径 |
说明 |
| GET |
/list |
秒杀活动列表（进行中） |
| GET |
/detail/{id} |
秒杀活动详情 |
| POST |
/seckill |
秒杀下单 |
MobileGroupBuyController -- 移动端拼团 (/v1/mobile/group-buy)
| 方法 |
路径 |
说明 |
| GET |
/list |
拼团活动列表 |
| GET |
/detail/{id} |
拼团活动详情 |
| GET |
/group/{groupId} |
拼团详情（含成员） |
| POST |
/startGroup |
开团 |
| POST |
/joinGroup |
参团 |
使用示例
1. 创建商品
POST /v1/product/spu/create
{
"name": "商品名称",
"categoryId": 100,
"brandId": 200,
"summary": "商品简介",
"skus": [
{
"specValues": "颜色:红色;尺码:XL",
"price": 9900,
"stock": 100
}
]
}
2. 商品审核与上下架
创建后状态为"草稿"，提交审核 -> 审核通过 -> 上架。
POST /v1/product/spu/submitAudit/{id} -- 提交审核
POST /v1/product/spu/putOnShelf/{id} -- 上架
POST /v1/product/spu/takeOffShelf/{id} -- 下架
3. 创建秒杀活动
POST /v1/product/flash-sale/create
{
"spuId": 100,
"skuId": 200,
"price": 5900,
"stock": 50,
"startTime": "2026-04-27 10:00:00",
"endTime": "2026-04-27 12:00:00",
"perLimit": 1
}
4. 移动端秒杀下单
POST /v1/mobile/flash-sale/seckill
{
"flashSaleId": 300,
"skuId": 200,
"quantity": 1
}
注意事项
- Redis 依赖：秒杀功能依赖 scaffold-redis 模块，如果 Redis 未启用，秒杀库存扣减退化为数据库操作
- 秒杀库存：秒杀使用 Redis DECR 原子扣减，保证高并发下不超卖；缓存 TTL 为 5 分钟
- BPM 审核：商品审核通过
BpmIntegrationService 与 BPM 模块交互，BPM 模块未启用时自动降级
- ID 精度：前端展示 ID 时必须使用 String 类型，雪花 ID 超过 JS 安全整数范围
- 金额单位：价格字段统一使用分为单位（Long 类型）
- 规格模板：商品创建时通过规格模板生成 SKU，规格值为键值对格式（如
颜色:红色;尺码:XL）
- 状态枚举：
- 品牌、SPU、SKU、规格模板、分类的
status 字段遵循布尔语义：1 = 启用，0 = 禁用
ProductAuditStatus、FlashSaleStatus、GroupStatus、GroupBuyStatus、FlashSaleRecordStatus、GroupMemberStatus 等为多态状态机，不遵循布尔语义规范