商品 SPU 与 SKU
商品 SPU/SKU 是 Mall 模块的商品中心。SPU 负责承载商品主信息、上下架状态、分类品牌、详情、配送方式等；SKU 负责承载规格组合、价格、库存、条码、图片和分销佣金等可售卖单元。
本页基于当前 ProductSpuController、ProductSkuService、管理端 views/mall/product/spu 和前端 API 类型整理，帮助你理解商品维护、状态流转和二次开发边界。
模块边界
| 层 | 路径 / 接口 |
|---|---|
| 后端模块 | ruoyi-office/yudao-module-mall/yudao-module-product-server |
| 管理端 SPU 控制器 | controller/admin/spu/ProductSpuController.java |
| 用户端 SPU 控制器 | controller/app/spu/AppProductSpuController.java |
| SKU 服务 | service/sku/ProductSkuService |
| 管理端页面 | apps/web-antd/src/views/mall/product/spu |
| 管理端 API | apps/web-antd/src/api/mall/product/spu/index.ts |
| 接口前缀 | /admin-api/product/spu、/app-api/product/spu |
SPU/SKU 关系
单规格商品也会落到 SKU，只是 SKU 规格组合为空或只有一个默认规格。交易订单、购物车、售后等模块最终通常引用 SKU，同时保留 SPU/SKU 的商品快照。
管理端能力
商品列表页按 Tab 展示不同状态的数量：出售中、仓库中、已售罄、警戒库存、回收站。页面调用 getTabsCount 获取数量，调用 getSpuPage 获取分页。
| 功能 | 接口 | 权限 |
|---|---|---|
| 创建商品 | POST /product/spu/create | product:spu:create |
| 更新商品 | PUT /product/spu/update | product:spu:update |
| 更新状态 | PUT /product/spu/update-status | product:spu:update |
| 删除商品 | DELETE /product/spu/delete | product:spu:delete |
| 商品详情 | GET /product/spu/get-detail | product:spu:query |
| 商品分页 | GET /product/spu/page | product:spu:query |
| Tab 数量 | GET /product/spu/get-count | product:spu:query |
| 导出商品 | GET /product/spu/export-excel | product:spu:export |
商品状态
管理端页面中的 Tab 是运营视角，实际状态以 ProductSpuStatusEnum 和后端统计逻辑为准。常见状态包括：
| 运营视角 | 含义 |
|---|---|
| 出售中 | 已上架，可在用户端展示和购买 |
| 仓库中 | 未上架，运营可继续编辑 |
| 已售罄 | 库存不足或无库存，需要补货或下架 |
| 警戒库存 | 低于安全库存，适合运营关注 |
| 回收站 | 已回收，通常不可直接售卖 |
更新状态时，前端会弹出二次确认；回收站和仓库之间也有专门的状态切换入口。
用户端商品详情
用户端 AppProductSpuController 提供商品列表和详情。详情接口会：
- 校验 SPU 存在。
- 校验 SPU 已上架。
- 查询 SKU 列表。
- 增加浏览量。
- 保存用户浏览记录。
- 返回 SPU 与 SKU 组合数据。
因此移动端或商城端展示商品详情时，不应直接调用管理端接口。
二次开发建议
- 新增商品字段时同步修改 SPU DO、SaveReqVO、RespVO、Convert、管理端表单和 API 类型。
- 新增 SKU 字段时重点检查规格表单、SKU 批量生成、价格/库存格式化和订单快照。
- 金额字段继续保持后端以分存储和传输，前端展示再转换。
- 上架前应校验分类、SKU、库存、价格、配送方式和封面图，避免用户端展示异常商品。
- 订单、购物车、售后依赖商品快照，不要让商品修改影响历史订单展示。
排查清单
| 现象 | 优先检查 |
|---|---|
| 商品列表 Tab 数量不准 | getTabsCount、SPU 状态、库存统计规则 |
| 用户端商品详情 404 | SPU 是否存在、是否上架、租户数据是否一致 |
| SKU 规格显示异常 | 商品属性/属性值是否存在，SKU properties 是否完整 |
| 价格显示异常 | 是否重复执行分/元转换 |
| 上架后无法购买 | SKU 库存、配送方式、运费模板、支付/交易配置 |
