商品与店铺 API
商品与店铺 API
本文归纳商品、店铺、上架、库存、评价、收藏和浏览历史相关接口。
使用场景
商品与店铺接口贯穿平台供给、商户经营和消费者导购：
| 场景 | 主要接口 | 说明 |
|---|---|---|
| 平台商品基础资料 | 类目、品牌、属性、属性值 | 建立商品录入和筛选基础 |
| 商品资料维护 | SPU、SKU、价格策略 | 管理商品详情、规格、价格和库存关联 |
| 店铺商品售卖 | 商户店铺、店铺上架、上架审核 | 将 SKU 挂到店铺并控制是否可售 |
| 消费者导购 | SPU、SKU、店铺、价格、评价 | 首页、分类、列表、详情、店铺页依赖这些接口 |
| 商品治理 | 评价管理、黑名单、禁用词 | 平台治理评价内容和商户回复 |
| 用户行为 | 店铺收藏、浏览历史 | 支撑个人中心收藏和足迹 |
商品上架调用顺序
- 维护类目、品牌、属性和属性值。
- 创建 SPU，维护标题、主图、详情和类目关系。
- 创建 SKU，维护规格、图片、基础价格和库存相关字段。
- 创建或选择商户店铺。
- 调用店铺上架接口，将 SKU 绑定到店铺和售卖价格策略。
- 提交上架审核。
- 平台审核通过后，消费者侧商品列表和详情可展示该商品。
后端商品逻辑
商品域以 SPU、SKU、店铺上架和库存为核心。消费者最终购买的是店铺中的 SKU，而不是后台孤立的 SKU 资料。
| 对象 | 后端职责 |
|---|---|
| 类目、品牌、属性 | 建立商品录入、筛选和规格基础 |
| SPU | 商品主体，承载标题、主图、详情、类目和店铺归属 |
| SKU | 具体规格，承载规格 JSON、主图、重量、体积和库存关联 |
| 店铺上架 | 决定 SKU 在某个店铺是否可售，以及货架价和运费方式 |
| 商户库存 | 校验商品可售数量，订单创建前必须检查库存 |
| 当前价格 | 聚合货架价、价格策略、活动价、运费和营销快照 |
当前价格计算顺序：
- 校验 SKU 和 SPU 是否存在且对当前访问者可见。
- 查询店铺货架，确认 SKU 已上架且只有一个有效货架记录。
- 校验货架价格和币种。
- 优先匹配平台或商户活动价。
- 未命中活动价时，回退到会员价、阶梯价或促销价等价格策略。
- 计算国内和国际运费。
- 返回
ProductCurrentPrice，作为购物车和订单试算的金额来源。
SKU 创建和修改时，重量 weight 和体积 volume 必须存在且大于 0，否则物流计费、仓储和报关链路无法稳定计算。
关键字段
| 字段 | 说明 |
|---|---|
spuId |
商品主体 ID，用于聚合同一商品的多个 SKU |
skuId |
具体售卖规格 ID，购物车和订单最终以 SKU 为购买对象 |
shopId |
店铺 ID，决定商品归属商户和店铺展示 |
shelfId |
店铺上架记录 ID，决定 SKU 在店铺内是否可售 |
strategyId |
价格策略 ID，用于会员价、阶梯价或促销价 |
inventoryId |
商户库存 ID，连接商户库存和 SKU |
reviewId |
商品评价 ID，平台和商户回复都围绕该对象处理 |
搜索和展示口径
搜索接口现在会返回 SKU、店铺和 SPU 简要信息。前端展示商品卡片时建议使用以下口径：
| 展示项 | 推荐来源 |
|---|---|
| 商品标题 | SKU 名称或 SPU 名称，按页面场景统一 |
| 商品主图 | SKU 主图优先，缺失时回退 SPU 主图 |
| 店铺信息 | 搜索结果中的 shop 或店铺详情接口 |
| 价格 | SKU 当前价格接口或订单试算结果，不直接使用录入价 |
| 是否可售 | 店铺上架状态、库存状态和后端返回状态 |
商品详情页进入下单前，需要重新拉取 SKU 当前价格，避免列表页缓存价格过期。
| 端别 | 接口名称 | 方法 | 路径 | 权限标识 | 主要用途 | 主要调用端 | 后端 Controller |
|---|---|---|---|---|---|---|---|
| shared | 商品类目 | GET /list、GET /page、GET /{categoryId}、POST、PUT、DELETE |
/api/v1/product/category |
*:product:category:* |
类目维护和查询 | admin、client |
ProductCategoryController |
| shared | 商品品牌 | GET /list、GET /page、GET /{brandId}、POST、PUT、DELETE |
/api/v1/product/brand |
*:product:brand:* |
品牌维护和查询 | admin、client |
ProductBrandController |
| shared | 商品属性 | GET /list、GET /page、GET /{attributeId}、POST、PUT、DELETE |
/api/v1/product/attribute |
*:product:attribute:* |
商品属性维护 | admin |
ProductAttributeController |
| shared | 商品属性值 | GET /list、GET /page、GET /{valueId}、POST、PUT、DELETE |
/api/v1/product/attribute/value |
*:product:attribute:value:* |
属性值维护 | admin |
ProductAttributeValueController |
| shared | 商品 SPU | GET /list、GET /page、GET /{spuId}、POST、PUT、DELETE |
/api/v1/product/spu |
*:product:spu:* |
SPU 维护和详情 | admin、client |
ProductSpuController |
| shared | 商品 SKU | GET /page、GET /shop-admin/page、GET /{skuId}、GET /{id}/{quantity}/current/price、POST、PUT、DELETE |
/api/v1/product/sku |
*:product:sku:* |
SKU 维护、店铺 SKU 查询和当前价计算 | admin、client |
ProductSkuController |
| shared | 价格策略 | GET /list、GET /page、GET /{strategyId}、POST、PUT、DELETE |
/api/v1/product/price/strategy |
*:product:price:strategy:* |
商品价格策略 | admin、client |
ProductPriceStrategyController |
| shared | 商户店铺 | GET /list、GET /page、GET /{shopId}、POST、PUT、DELETE、PUT /{shopId}/commission-policy |
/api/v1/merchant/shop |
*:merchant:shop:* |
店铺资料和佣金策略绑定 | admin、client、ops |
MerchantShopController |
| shared | 商户店铺上架 | GET /list、GET /page、GET /{shelfId}、POST、PUT、DELETE |
/api/v1/merchant/shop/shelf |
*:merchant:shop:shelf:* |
店铺商品上架 | admin、client |
MerchantShopShelfController |
| shared | 店铺上架审核 | GET /list、GET /page、GET /{auditId}、PUT /{auditId}/allow、PUT /{auditId}/disallow |
/api/v1/merchant/shop/shelf/audit |
*:merchant:shop:shelf:audit:* |
上架审核通过或驳回 | admin |
MerchantShopShelfAuditController |
| shared | 商户库存 | GET /page、GET /{inventoryId}、POST、PUT /{inventoryId}/inbound/stock、PUT /{inventoryId}/inbound/revision、PUT /{inventoryId}/outbound/revision、PUT /{inventoryId}/disable、DELETE |
/api/v1/merchant/inventory |
*:merchant:inventory:* |
商户库存维护和调整 | admin、ops |
MerchantInventoryController |
| shared | 商户库存日志 | GET /page、GET /{logId} |
/api/v1/merchant/inventory/log |
*:merchant:inventory:log:* |
库存流水查询 | admin、ops |
MerchantInventoryLogController |
| admin | 商品评价管理 | GET /page、GET /{reviewId}、PUT /{reviewId}/approve、PUT /{reviewId}/reject、PUT /{reviewId}/offline、PUT /{reviewId}/reply/approve、PUT /{reviewId}/reply/reject、PUT /{reviewId}/reply/offline、POST /rescan |
/api/v1/product/review |
admin:product:review:* |
平台评价审核、下架和重扫 | admin |
ProductReviewController |
| client | 商品评价查询 | GET /page、GET /summary |
/api/v1/product/spu/{spuId}/review |
client:product:review:* |
商品评价展示和 SPU 评价汇总 | client |
ProductReviewController |
| client | 个人商品评价 | GET /page、GET /{reviewId}、POST、PUT /{reviewId} |
/api/v1/personal/product/review |
client:personal:product:review:* |
消费者评价创建、修改和查询 | client |
PersonalProductReviewController |
| client | 商户商品评价 | GET /page、GET /{reviewId}、PUT /{reviewId}/reply |
/api/v1/merchant/product/review |
client:merchant:product:review:* |
商户评价查看和回复 | ops |
MerchantProductReviewController |
| admin | 评价黑名单 | GET /page、GET /{id}、POST、PUT、DELETE |
/api/v1/product/review/blacklist |
admin:product:review:blacklist:* |
评价黑名单治理 | admin |
ProductReviewBlacklistController |
| admin | 评价禁用词 | GET /page、GET /{id}、POST、PUT、DELETE |
/api/v1/product/review/forbidden-word |
admin:product:review:forbidden-word:* |
评价敏感词治理 | admin |
ProductReviewForbiddenWordController |
| client | 店铺收藏 | POST /{shopId}/favorite、DELETE /{shopId}/favorite、GET /{shopId}/favorite/status、GET /favorite/page |
/api/v1/personal/merchant/shop |
client:personal:merchant:shop:favorite:* |
收藏店铺、取消收藏和查询收藏 | client |
PersonalMerchantShopFavoriteController |
| client | 商品浏览历史 | POST /{skuId}/browse-history、GET /browse-history/page、DELETE /{skuId}/browse-history、DELETE /browse-history/clear |
/api/v1/personal/product/sku |
client:personal:product:sku:browse-history:* |
浏览历史记录和清理 | client |
PersonalProductSkuBrowseHistoryController |
前端封装
admin/src/api/productApi.ts、accountApi.ts。client/api/index.js的banner、productCategory、search、spu、sku、shop、productReview分组。ops当前不承担消费者商品浏览，但会间接使用商户发货和库存相关接口。
维护注意事项
- 消费者侧价格展示应以店铺上架和当前价格计算结果为准，不直接使用后台原始录入价。
- SKU 删除或禁用前需要确认购物车、未完成订单和店铺上架记录是否仍引用。
- 上架审核状态变化应触发商户消息或待办，避免商户不知道审核结果。
- 评价回复属于商户经营能力，平台审核属于治理能力，两者权限需要分开。
- 当前个人评价接口只支持发布、修改、分页和详情查询；删除或撤回需要走后续治理设计，前端不要展示删除入口。
- 浏览历史和收藏是个人行为数据，分页接口应只返回当前登录用户范围内的数据。
- 店铺收藏新增使用
POST，取消收藏使用DELETE，收藏状态不要用PUT做切换，避免重复点击造成语义不清。 - 店铺上架、库存和当前价格是下单前置条件，前端页面展示可买不代表创建订单一定成功。
- 活动价接入后，商品当前价格可能因活动状态、时间、范围和预算变化而变化。
联调验收
| 场景 | 验收口径 |
|---|---|
| SKU 维护 | 规格、主图、重量、体积、HS Code 等字段保存后详情一致 |
| 店铺上架 | 上架后消费者能看到商品，驳回或下架后消费者不可购买 |
| 当前价格 | 命中活动价、价格策略和原价时金额都可解释 |
| 库存校验 | 库存不足时购物车试算或下单返回明确业务错误 |
| 搜索展示 | 搜索结果包含 SKU、SPU 和店铺信息，匿名搜索可访问 |
| 评价治理 | 消费者评价、商户回复、平台审核和下架动作状态一致 |