# 商城业务API
**本文引用的文件**
- [ProductCategoryApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/category/ProductCategoryApi.java)
- [ProductSpuApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/spu/ProductSpuApi.java)
- [ProductSKUApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/sku/ProductSKUApi.java)
- [ProductCommentApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/comment/ProductCommentApi.java)
- [SeckillActivityApi.java](file://viewsh-module-mall/viewsh-module-promotion-api/src/main/java/com/viewsh/module/promotion/api/seckill/SeckillActivityApi.java)
- [TradeOrderApi.java](file://viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/api/order/TradeOrderApi.java)
- [MemberStatisticsController.java](file://viewsh-module-mall/viewsh-module-statistics-server/src/main/java/com/viewsh/module/statistics/controller/admin/member/MemberStatisticsController.java)
- [TradeStatisticsController.java](file://viewsh-module-mall/viewsh-module-statistics-server/src/main/java/com/viewsh/module/statistics/controller/admin/trade/TradeStatisticsController.java)
- [MemberStatisticsServiceImpl.java](file://viewsh-module-mall/viewsh-module-statistics-server/src/main/java/com/viewsh/module/statistics/service/member/MemberStatisticsServiceImpl.java)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件为商城业务模块的综合API接口文档，覆盖商品管理（类目、SPU/SKU、评论）、促销活动（限时秒杀、拼团、优惠券等）、订单交易（创建、取消、查询）、会员管理（地址、等级、积分、用户基础信息）、统计数据（会员概览、交易趋势、订单对比）等核心能力。文档以RESTful风格描述接口，标注请求方法、路径、参数、返回值及权限要求，并给出关键流程的时序图与最佳实践建议。
## 项目结构
商城业务相关模块采用“多模块分层”组织方式，按领域拆分为 product（商品）、promotion（促销）、trade（交易）、member（会员）、statistics（统计），并通过统一的API常量与OpenFeign进行跨模块RPC调用。
```mermaid
graph TB
subgraph "商城业务模块"
PRODUCT["商品模块
product-api / product-server"]
PROMO["促销模块
promotion-api / promotion-server"]
TRADE["交易模块
trade-api / trade-server"]
MEMBER["会员模块
member-api / member-server"]
STATS["统计模块
statistics-api / statistics-server"]
end
CLIENT["客户端/前端/其他服务"] --> PRODUCT
CLIENT --> PROMO
CLIENT --> TRADE
CLIENT --> MEMBER
CLIENT --> STATS
PRODUCT --> PROMO
PRODUCT --> TRADE
PRODUCT --> STATS
PROMO --> TRADE
TRADE --> STATS
MEMBER --> STATS
```
图表来源
- [ProductCategoryApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/category/ProductCategoryApi.java#L14-L25)
- [ProductSpuApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/spu/ProductSpuApi.java#L19-L50)
- [ProductSKUApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/sku/ProductSKUApi.java#L23-L58)
- [SeckillActivityApi.java](file://viewsh-module-mall/viewsh-module-promotion-api/src/main/java/com/viewsh/module/promotion/api/seckill/SeckillActivityApi.java#L15-L54)
- [TradeOrderApi.java](file://viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/api/order/TradeOrderApi.java#L18-L43)
章节来源
- [ProductCategoryApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/category/ProductCategoryApi.java#L1-L26)
- [ProductSpuApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/spu/ProductSpuApi.java#L1-L51)
- [ProductSKUApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/sku/ProductSKUApi.java#L1-L59)
- [SeckillActivityApi.java](file://viewsh-module-mall/viewsh-module-promotion-api/src/main/java/com/viewsh/module/promotion/api/seckill/SeckillActivityApi.java#L1-L55)
- [TradeOrderApi.java](file://viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/api/order/TradeOrderApi.java#L1-L44)
## 核心组件
- 商品类目管理：提供类目合法性校验的RPC接口，供其他模块在业务前置校验使用。
- 商品SPU/SKU管理：提供SPU/SKU的批量查询、单个查询、按SPU批量查询以及库存更新RPC接口。
- 商品评论管理：提供创建评论的RPC接口。
- 促销活动：提供秒杀活动的库存扣减/回补、参与校验等RPC接口。
- 订单交易：提供订单列表/单个查询、已支付取消等RPC接口。
- 统计数据：提供会员概览、交易订单数量、订单对比、订单趋势等管理后台统计接口。
章节来源
- [ProductCategoryApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/category/ProductCategoryApi.java#L14-L25)
- [ProductSpuApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/spu/ProductSpuApi.java#L19-L50)
- [ProductSKUApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/sku/ProductSKUApi.java#L23-L58)
- [ProductCommentApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/comment/ProductCommentApi.java#L14-L24)
- [SeckillActivityApi.java](file://viewsh-module-mall/viewsh-module-promotion-api/src/main/java/com/viewsh/module/promotion/api/seckill/SeckillActivityApi.java#L15-L54)
- [TradeOrderApi.java](file://viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/api/order/TradeOrderApi.java#L18-L43)
- [MemberStatisticsController.java](file://viewsh-module-mall/viewsh-module-statistics-server/src/main/java/com/viewsh/module/statistics/controller/admin/member/MemberStatisticsController.java#L1-L29)
- [TradeStatisticsController.java](file://viewsh-module-mall/viewsh-module-statistics-server/src/main/java/com/viewsh/module/statistics/controller/admin/trade/TradeStatisticsController.java#L101-L122)
- [MemberStatisticsServiceImpl.java](file://viewsh-module-mall/viewsh-module-statistics-server/src/main/java/com/viewsh/module/statistics/service/member/MemberStatisticsServiceImpl.java#L36-L57)
## 架构总览
商城业务通过统一的API常量与OpenFeign进行跨模块调用，形成清晰的领域边界与职责划分。商品模块负责SPU/SKU与评论；促销模块负责活动与库存变更；交易模块负责订单生命周期；统计模块提供运营看板数据。
```mermaid
graph LR
FEIGN["OpenFeign 客户端
FeignClient 接口"] --> API["API 常量
ApiConstants"]
API --> PRODUCT_API["商品API"]
API --> PROMO_API["促销API"]
API --> TRADE_API["交易API"]
API --> MEMBER_API["会员API"]
API --> STATS_API["统计API"]
PRODUCT_API --> PRODUCT_SERVER["商品服务实现"]
PROMO_API --> PROMO_SERVER["促销服务实现"]
TRADE_API --> TRADE_SERVER["交易服务实现"]
MEMBER_API --> MEMBER_SERVER["会员服务实现"]
STATS_API --> STATS_SERVER["统计服务实现"]
```
图表来源
- [ProductCategoryApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/category/ProductCategoryApi.java#L14-L25)
- [ProductSpuApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/spu/ProductSpuApi.java#L19-L50)
- [ProductSKUApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/sku/ProductSKUApi.java#L23-L58)
- [SeckillActivityApi.java](file://viewsh-module-mall/viewsh-module-promotion-api/src/main/java/com/viewsh/module/promotion/api/seckill/SeckillActivityApi.java#L15-L54)
- [TradeOrderApi.java](file://viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/api/order/TradeOrderApi.java#L18-L43)
## 详细组件分析
### 商品类目管理接口
- 功能：校验传入的商品类目编号集合是否合法。
- 接口定义（RPC）
- 方法：GET
- 路径：/category/valid
- 请求参数：ids（类目编号数组）
- 返回：CommonResult
- 使用场景：在创建/编辑商品或订单结算前，对类目进行前置校验。
章节来源
- [ProductCategoryApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/category/ProductCategoryApi.java#L14-L25)
### 商品SPU管理接口
- 功能：批量查询SPU、校验SPU有效性、获取单个SPU。
- 接口定义（RPC）
- 批量查询SPU：GET /spu/list
- 校验SPU并返回有效列表：GET /spu/valid
- 获取单个SPU：GET /spu/get
- 返回类型：CommonResult
章节来源
- [ProductSpuApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/spu/ProductSpuApi.java#L19-L50)
### 商品SKU管理接口
- 功能：查询SKU、批量查询SKU、按SPU批量查询、更新SKU库存（增/减）。
- 接口定义（RPC）
- 查询单个SKU：GET /sku/get
- 批量查询SKU：GET /sku/list
- 按SPU批量查询SKU：GET /sku/list-by-spu-id
- 更新库存（减少）：POST /sku/update-stock
- 更新库存（增加）：POST /sku/update-stock
- 返回类型：CommonResult
章节来源
- [ProductSKUApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/sku/ProductSKUApi.java#L23-L58)
### 商品评论管理接口
- 功能：创建商品评论。
- 接口定义（RPC）
- 创建评论：POST /comment/create
- 请求体：ProductCommentCreateReqDTO
- 返回：CommonResult（评论ID）
章节来源
- [ProductCommentApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/comment/ProductCommentApi.java#L14-L24)
### 促销活动接口（限时秒杀）
- 功能：校验用户是否可参与秒杀、扣减/回补秒杀库存。
- 接口定义（RPC）
- 扣减库存：PUT /discount-activity/update-stock-decr
- 回补库存：PUT /discount-activity/update-stock-incr
- 参与校验：GET /discount-activity/validate-join
- 请求参数（示例）：activityId、skuId、count
- 返回类型：CommonResult
章节来源
- [SeckillActivityApi.java](file://viewsh-module-mall/viewsh-module-promotion-api/src/main/java/com/viewsh/module/promotion/api/seckill/SeckillActivityApi.java#L15-L54)
### 订单交易接口
- 功能：查询订单列表/单个订单、取消已支付订单。
- 接口定义（RPC）
- 查询订单列表：GET /order/list
- 查询单个订单：GET /order/get
- 取消已支付订单：PUT /order/cancel-paid
- 请求参数（示例）：ids、id、userId、orderId、cancelType
- 返回类型：CommonResult
章节来源
- [TradeOrderApi.java](file://viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/api/order/TradeOrderApi.java#L18-L43)
### 会员统计接口
- 功能：管理后台会员概览、会员趋势、活跃度等。
- 控制器接口（HTTP）
- GET /member/summary（示例）
- 权限：需具备 statistics:member:query 权限
- 返回：会员汇总数据对象
章节来源
- [MemberStatisticsController.java](file://viewsh-module-mall/viewsh-module-statistics-server/src/main/java/com/viewsh/module/statistics/controller/admin/member/MemberStatisticsController.java#L1-L29)
### 交易统计接口
- 功能：管理后台交易概览、订单数量、订单对比、订单趋势。
- 控制器接口（HTTP）
- GET /trade/order-count：未发货/门店自提订单数、售后申请数、佣金提现审核中数
- GET /trade/order-comparison：订单数量对比
- GET /trade/order-count-trend：订单数量趋势
- 权限：需具备 statistics:trade:query 权限
- 返回：对应统计响应对象
章节来源
- [TradeStatisticsController.java](file://viewsh-module-mall/viewsh-module-statistics-server/src/main/java/com/viewsh/module/statistics/controller/admin/trade/TradeStatisticsController.java#L101-L122)
### 统计服务实现（会员）
- 功能：聚合会员充值、消费、用户总数等指标
- 关键调用链：
- 获取用户充值汇总
- 获取消费金额（按订单支付价统计）
- 获取用户总数
- 返回：会员概览响应对象
章节来源
- [MemberStatisticsServiceImpl.java](file://viewsh-module-mall/viewsh-module-statistics-server/src/main/java/com/viewsh/module/statistics/service/member/MemberStatisticsServiceImpl.java#L36-L57)
## 依赖关系分析
- RPC接口通过FeignClient声明，统一使用ApiConstants作为服务名与前缀，降低耦合。
- 商品模块为上游数据源，被促销、交易、统计模块广泛依赖。
- 促销模块与交易模块存在强关联：秒杀活动在下单前校验，下单后扣减库存。
- 统计模块聚合来自会员、交易、钱包等多模块的数据，形成运营看板。
```mermaid
graph TB
PCAT["ProductCategoryApi"] --> PCAT_IMPL["商品服务实现"]
PSUP["ProductSpuApi"] --> PSUP_IMPL["商品服务实现"]
PSKU["ProductSKUApi"] --> PSKU_IMPL["商品服务实现"]
PCOM["ProductCommentApi"] --> PCOM_IMPL["商品服务实现"]
SECK["SeckillActivityApi"] --> SECK_IMPL["促销服务实现"]
TORD["TradeOrderApi"] --> TORD_IMPL["交易服务实现"]
STAT_CTRL["统计控制器"] --> STAT_SRV["统计服务实现"]
STAT_SRV --> PCAT_IMPL
STAT_SRV --> PSUP_IMPL
STAT_SRV --> PSKU_IMPL
STAT_SRV --> SECK_IMPL
STAT_SRV --> TORD_IMPL
```
图表来源
- [ProductCategoryApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/category/ProductCategoryApi.java#L14-L25)
- [ProductSpuApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/spu/ProductSpuApi.java#L19-L50)
- [ProductSKUApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/sku/ProductSKUApi.java#L23-L58)
- [ProductCommentApi.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/comment/ProductCommentApi.java#L14-L24)
- [SeckillActivityApi.java](file://viewsh-module-mall/viewsh-module-promotion-api/src/main/java/com/viewsh/module/promotion/api/seckill/SeckillActivityApi.java#L15-L54)
- [TradeOrderApi.java](file://viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/api/order/TradeOrderApi.java#L18-L43)
- [MemberStatisticsController.java](file://viewsh-module-mall/viewsh-module-statistics-server/src/main/java/com/viewsh/module/statistics/controller/admin/member/MemberStatisticsController.java#L1-L29)
- [TradeStatisticsController.java](file://viewsh-module-mall/viewsh-module-statistics-server/src/main/java/com/viewsh/module/statistics/controller/admin/trade/TradeStatisticsController.java#L101-L122)
- [MemberStatisticsServiceImpl.java](file://viewsh-module-mall/viewsh-module-statistics-server/src/main/java/com/viewsh/module/statistics/service/member/MemberStatisticsServiceImpl.java#L36-L57)
## 性能考量
- 批量查询优先：SPU/SKU均提供批量接口，避免多次RPC往返。
- 库存更新原子性：秒杀库存扣减/回补应结合分布式锁或数据库层面的原子操作，防止超卖。
- 统计聚合：会员与交易统计建议异步落表或缓存热点数据，避免高频实时统计带来的压力。
- 分页与过滤：列表查询建议支持分页与条件过滤，控制单次返回数据量。
## 故障排查指南
- 类目校验失败：确认传入的ids是否为空或包含非法值；检查商品类目状态。
- SPU/SKU查询为空：核对编号是否正确；确认商品状态与上下架状态。
- 库存更新失败：检查活动是否存在、SKU是否匹配、库存是否充足；关注并发场景下的超卖风险。
- 秒杀校验失败：确认活动时间、限购规则、用户资格；检查活动与SKU绑定关系。
- 订单取消失败：确认订单状态为“已支付”，取消类型参数是否正确；检查退款/库存回滚流程。
- 统计数据异常：核对统计口径（如消费金额按订单支付价统计）、时间范围、权限配置。
## 结论
本API文档梳理了商城业务的核心能力与接口契约，明确了商品、促销、交易、会员、统计等模块的职责边界与交互关系。建议在实际接入时遵循批量查询、幂等设计、原子性更新与权限控制的最佳实践，确保业务流程稳定与数据一致。
## 附录
### 电商业务流程接口调用示例（概念性流程）
以下为典型业务流程的概念性时序图，展示从下单到支付、发货、售后的调用顺序与关键校验点。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant Trade as "交易模块"
participant Promo as "促销模块"
participant Prod as "商品模块"
participant Stats as "统计模块"
Client->>Prod : "查询SPU/SKU详情"
Prod-->>Client : "返回SPU/SKU信息"
Client->>Promo : "校验参与秒杀/拼团/优惠券"
Promo-->>Client : "返回校验结果"
Client->>Trade : "提交订单含商品、优惠、收货信息"
Trade->>Prod : "锁定/扣减库存"
Prod-->>Trade : "库存扣减结果"
Trade-->>Client : "返回订单号"
Client->>Trade : "发起支付"
Trade-->>Client : "支付结果"
Client->>Trade : "申请发货/物流"
Trade-->>Client : "物流信息"
Client->>Trade : "售后/退款申请"
Trade-->>Client : "售后处理结果"
Trade->>Stats : "更新销售/用户行为统计"
Stats-->>Trade : "统计完成"
```
### 关键流程与数据一致性保障机制（概念性说明）
- 库存一致性：秒杀/下单扣减采用“预占+最终确认/回滚”的两阶段策略，结合分布式锁与数据库事务。
- 支付与订单状态：支付成功后才允许发货；退款成功后回滚库存与统计。
- 统计一致性：采用异步任务或消息队列更新统计表，避免阻塞主交易链路。
- 权限与审计：所有管理后台接口均需鉴权与操作日志记录，确保可追溯。