Mall 电商系统

主题

前台接口说明 ​

版本：v3.0 ｜ 最后更新：2026-07 ｜ 文档状态：已同步代码

按消费者购物流程，说明前台商城每个功能对应的接口。

路径已与代码逐一核对（mall-portal 全部 16 个 Controller / 89 个端点），下表均为真实端点。

📌 路径说明：下表是后端服务的真实路径（mall-portal，端口 8085）。前端调用时经 Vite 代理转发：/api/* 需写成 /papi/*（代理会 rewrite 回 /api），而 /member/* 直接使用（无需 /papi 前缀）。

一、首页与浏览 ​

这些接口都是公开的，游客也能访问。

获取首页数据 ​

  • 用途：打开首页时加载轮播广告、推荐商品、品牌等
  • 接口：GET /api/home/content
  • 返回：轮播图列表、新品推荐、人气推荐、品牌推荐、专题推荐

首页楼层（分接口） ​

楼层接口
新品推荐GET /api/home/newProductList
人气推荐GET /api/home/recommendProductList
分类导航GET /api/home/productCateList/{parentId}
专题列表GET /api/home/subjectList
专题详情GET /api/home/subject/{id}
专题商品GET /api/home/subject/{id}/products
热门商品GET /api/home/hotProductList

按分类获取商品 ​

  • 用途：点击某个分类后，展示该分类下的商品
  • 接口：GET /api/product/listByCategory
  • 参数：分类 ID、页码、每页数量
  • 返回：商品列表（含图片、名称、价格、销量）

分类树 ​

  • 接口：GET /api/product/categoryTreeList

搜索商品 ​

  • 用途：输入关键词搜索商品
  • 接口：GET /api/product/search
  • 参数：关键词、页码、排序
  • 返回：匹配的商品列表
  • 说明：当前走 MySQL LIKE 检索，非 Elasticsearch

热搜词与搜索联想 ​

功能接口
热搜词GET /api/product/hotKeywords
搜索联想GET /api/product/suggest

获取商品详情 ​

  • 用途：打开商品详情页
  • 接口：GET /api/product/detail/{id}
  • 返回：商品信息、规格属性、SKU 列表、评价统计

相关推荐 ​

  • 接口：GET /api/product/recommend/{id}

品牌专区 ​

功能接口
品牌详情GET /api/brand/detail/{brandId}
品牌商品列表GET /api/brand/productList/{brandId}
推荐品牌GET /api/brand/recommendList

二、会员账号 ​

注册 ​

  • 用途：新用户注册
  • 接口：POST /member/register
  • 参数：用户名、密码、手机号、验证码
  • 说明：注册成功后自动设置昵称=用户名、初始积分=0

登录 ​

  • 用途：会员登录
  • 接口：POST /member/login
  • 参数：用户名（或手机号）+ 密码
  • 返回：Token（身份凭证）、会员信息
  • 说明：支持用户名或手机号登录

获取验证码 ​

  • 接口：GET /member/getAuthCode

刷新 Token ​

  • 接口：GET /member/refreshToken

获取个人信息 ​

  • 用途：查看当前登录会员的信息
  • 接口：GET /member/info
  • 返回：昵称、头像、积分、成长值、会员等级

修改个人信息 ​

  • 用途：修改昵称或头像
  • 接口：POST /member/update
  • 参数：昵称、头像 URL

修改密码 ​

  • 接口：POST /member/updatePassword

积分变动记录 ​

  • 接口：GET /member/integrationHistory

会员等级 ​

  • 接口：GET /member/level/list

品牌关注 ​

功能接口
关注/取消POST /member/attention/add、/delete
关注状态GET /member/attention/detail
关注列表GET /member/attention/list
清空关注POST /member/attention/clear

三、收货地址 ​

全部使用 /member/address 前缀（不是 /api/member/address）

地址列表 ​

  • 用途：查看我的所有收货地址
  • 接口：GET /member/address/list
  • 返回：地址列表（含是否默认标记）

添加地址 ​

  • 用途：新增一个收货地址
  • 接口：POST /member/address/create
  • 参数：收货人、手机号、省市区、详细地址
  • 说明：每个用户最多 10 个地址

修改地址 ​

  • 用途：编辑已有地址
  • 接口：POST /member/address/update/{id}

删除地址 ​

  • 用途：删除一个地址
  • 接口：POST /member/address/delete/{id}
  • 说明：如果删除的是默认地址，系统自动将最近创建的地址设为默认

地址详情 ​

  • 接口：GET /member/address/{id}

四、购物车 ​

获取购物车 ​

  • 用途：查看购物车里的商品
  • 接口：GET /api/cart/list
  • 返回：购物车商品列表（含商品信息、数量、单价、选中状态）

添加到购物车 ​

  • 用途：把商品加入购物车
  • 接口：POST /api/cart/add
  • 参数：商品 ID、SKU ID、数量
  • 说明：必须登录后才能操作

修改数量 ​

  • 用途：调整购物车中某个商品的数量
  • 接口：GET /api/cart/update/quantity

重选规格 ​

  • 接口：POST /api/cart/update/attr

切换选中 ​

  • 用途：勾选/取消勾选某个商品（结算时只结算选中的）
  • 接口：POST /api/cart/check

删除购物车商品 ​

  • 用途：从购物车移除商品
  • 接口：POST /api/cart/delete

清空购物车 ​

  • 接口：POST /api/cart/clear

购物车促销信息 ​

  • 接口：GET /api/cart/list/promotion

五、订单 ​

生成确认单 ​

  • 用途：下单前确认信息（地址、商品、优惠券）
  • 接口：POST /api/order/generateConfirmOrder
  • 返回：选中的购物车商品、收货地址、可用优惠券、金额明细

提交订单 ​

  • 用途：正式下单
  • 接口：POST /api/order/generateOrder
  • 参数：地址 ID、优惠券 ID（可选）
  • 返回：订单号、应付金额

模拟支付 ​

  • 用途：完成支付（当前为模拟，非真实支付）
  • 接口：POST /api/order/paySuccess
  • 参数：订单 ID、支付方式
  • 说明：后端直接置订单状态为已支付并扣减真实库存，无支付网关调用、无签名校验。前台支付页的「微信支付」「支付宝」选项均为占位，点击后走同一逻辑

订单列表 ​

  • 用途：查看我的订单
  • 接口：GET /api/order/list
  • 参数：订单状态（可选：待付款/待发货/待收货/已完成）
  • 返回：订单列表

订单详情 ​

  • 用途：查看某个订单的详细信息
  • 接口：GET /api/order/detail/{orderId}
  • 返回：商品信息、地址、金额、物流信息、操作历史

订单操作记录 ​

  • 接口：GET /api/order/operateHistory/{orderId}

取消订单 ​

  • 用途：取消未支付的订单
  • 接口：POST /api/order/cancelUserOrder

确认收货 ​

  • 用途：确认收到商品
  • 接口：POST /api/order/confirmReceiveOrder

删除订单 ​

  • 接口：POST /api/order/deleteOrder

超时订单取消（内部） ​

  • 接口：POST /api/order/cancelTimeOutOrder
  • 说明：⚠️ 原本由定时任务调用。OrderTimeOutCancelTask 此前因 @Component 被注释而未生效，现已启用（每 10 分钟兜底扫描一次）；主路径为 RabbitMQ 死信延迟队列（见 CancelOrderReceiver），两者并发安全

六、售后 ​

申请退货 ​

  • 用途：对已收到的商品申请退货
  • 接口：POST /api/returnApply/create
  • 参数：订单商品 ID、退货原因、说明、联系电话

退货列表 ​

  • 用途：查看我的退货申请
  • 接口：GET /api/returnApply/list
  • 返回：退货申请列表（含状态：待审核/退货中/已完成/已拒绝）

可选的退货原因 ​

  • 接口：GET /api/returnApply/reasons

七、商品评价 ​

获取评价列表 ​

  • 用途：查看商品的用户评价
  • 接口：GET /api/product/comment/list
  • 参数：商品 ID、类型筛选（全部/有图/好评/中评/差评）
  • 返回：评价列表（含评分、内容、图片、用户信息）
  • 说明：/api/product/** 在白名单内，游客可匿名读取

获取商家回复 ​

  • 用途：查看某条评价的商家回复
  • 接口：GET /api/product/comment/replayList/{commentId}

评价统计 ​

  • 接口：GET /api/product/comment/stats

八、收藏与历史 ​

存储于 MongoDB；前缀为 /member/...（无 /api）

收藏商品 ​

功能接口
收藏POST /member/productCollection/add
取消收藏POST /member/productCollection/delete
收藏列表GET /member/productCollection/list
收藏状态GET /member/productCollection/detail
清空收藏POST /member/productCollection/clear

浏览历史 ​

功能接口
记录浏览POST /member/readHistory/create
历史列表GET /member/readHistory/list
删除记录POST /member/readHistory/delete
清空历史POST /member/readHistory/clear

打开商品详情时自动记录，按日期分组展示。

九、优惠券 ​

前缀为 /member/coupon（不是 /api/member/coupon）

功能接口
领取优惠券POST /member/coupon/add/{couponId}
我的优惠券GET /member/coupon/list
领券中心GET /member/coupon/listCenter
使用记录GET /member/coupon/listHistory
商品可用券GET /member/coupon/listByProduct/{productId}
购物车可用券GET /member/coupon/list/cart/{type}
券适用商品GET /member/coupon/listProduct/{couponId}

十、帮助中心与举报 ​

帮助中心（公开） ​

功能接口
帮助分类GET /api/help/categoryList
帮助列表GET /api/help/list
帮助详情GET /api/help/{id}
热门帮助GET /api/help/popular
帮助搜索GET /api/help/search

举报（需登录） ​

  • 接口：POST /member/report/submit

十一、支付宝（代码已接入，未接线） ​

功能接口
电脑网站支付GET /alipay/pay
手机网站支付GET /alipay/webPay
异步回调POST /alipay/notify
交易查询GET /alipay/query

⚠️ 后端 SDK 代码完整，但 appId / 密钥均为 your appId 占位符，prod 环境也用沙箱网关，前端 0 次调用。详见 docs/prd/17-admin-finance.md 与 AGENTS.md 已知注意事项第 12 条。

Mall 电商系统知识库

Copyright © 2025 Mall Project