snack-mall/docs/API_CATALOG.md

后端真实接口清单

本文档为前后端对接的唯一事实来源,由后端 Controller 扫描生成。 整理日期:2026-06-05

关键约定(摘自 server-snack/src/main/java/com/snack/server/config/SaTokenConfig.java):

• 用户端白名单:/api/user/login;需登录:/api/user/**、/api/cart/**、/api/orders/**、/api/seckill/buy、/api/coupons/*/receive、/api/user/coupons
• 管理端白名单:/api/admin/login、/api/admin/captcha;其余 /api/admin/** 均需登录
• 响应统一封装 Result<T>:{code, message, data}。前端 axios 拦截器在 code===200 时直接返回 data(已解包)

---

一、用户端接口(/api/...)

1. 用户鉴权

方法	路径	入参	出参	鉴权
POST	/api/user/login	{username, password}	{token, userId, nickname}	白名单
POST	/api/user/register	TODO 业务模块未实现注册(由 UserAuthController 暂代)	—	待确认

现状:用户端没有 profile 公开接口,登录后只能用 token 调其他接口。注册入口需另作设计。

2. 商品(用户端)

方法	路径	入参	出参	鉴权
GET	/api/product/{id}	路径:id	ProductDetailVO(含 skuList)	公开
GET	/api/product/list	query:categoryIds(逗号分隔)、orderBy(sales_desc/price_asc/price_desc/create_desc)、limit	List<ProductListVO>	公开
GET	/api/product/hot	query:limit	List<ProductListVO>	公开
GET	/api/product/new	query:limit	List<ProductListVO>	公开

注意:用户端没有 keyword 搜索接口,需确认是否走 categoryIds 或单独 /api/search — 当前不存在。

3. 分类(用户端)

方法	路径	入参	出参	鉴权
GET	/api/category/tree	—	List<CategoryTreeVO>(树形)	公开

4. 轮播图(用户端)

方法	路径	入参	出参	鉴权
GET	/api/banner	—	List<BannerVO>	公开

5. 公告(用户端)

方法	路径	入参	出参	鉴权
GET	/api/notice/list	—	List<NoticeVO>	公开
GET	/api/notice/{id}	路径:id	NoticeVO(自动 +1 viewCount)	公开

6. 购物车(用户端)

方法	路径	入参	出参	鉴权
GET	/api/cart	—	CartVO{items, totalCount, selectedCount, totalAmount, selectedAmount, allSelected}	登录
POST	/api/cart	CartAddReq{productId, skuId, quantity}	void	登录
PUT	/api/cart/quantity	CartUpdateReq{skuId, quantity}	void	登录
PUT	/api/cart/{skuId}/selected	query:selected(0/1)	void	登录
PUT	/api/cart/all-selected	query:selected(0/1)	void	登录
DELETE	/api/cart/{skuId}	路径:skuId	void	登录
DELETE	/api/cart	body:List<Long>(skuIds 批量)	void	登录
DELETE	/api/cart/all	—	void	登录
GET	/api/cart/count	—	Integer(商品总件数)	登录

CartItemVO 关键字段:id/productId/productName/productImage/skuId/skuName/skuImage/price/quantity/subtotal/stock/selected/productStatus

7. 收货地址(用户端)

方法	路径	入参	出参	鉴权
GET	/api/address	—	List<AddressVO>	登录
GET	/api/address/default	—	AddressVO	登录
GET	/api/address/{id}	路径:id	AddressVO	登录
POST	/api/address	AddressSaveReq	Long(新 ID)	登录
PUT	/api/address	AddressSaveReq(带 id)	void	登录
DELETE	/api/address/{id}	路径:id	void	登录
PUT	/api/address/{id}/default	路径:id	void	登录

AddressSaveReq 字段:receiver、phone(^1[3-9]\d{9}$)、province、city、district、detail、tag、isDefault(0/1) AddressVO 额外返回 fullAddress(省市区+详细 拼接)

8. 订单(用户端)— 路径是 /api/orders(复数,非 order)

方法	路径	入参	出参	鉴权
POST	/api/orders	OrderSubmitReq{items[{skuId, quantity}], addressId, couponId?, remark?}	{orderNo}	登录
GET	/api/orders/{id}	路径:id	OrderDetailVO	登录
GET	/api/orders	query:current/size/status?/keyword?	Page<OrderDetailVO>	登录
POST	/api/orders/{id}/pay	路径:id	void	登录
POST	/api/orders/{id}/cancel	路径:id	void	登录
POST	/api/orders/{id}/receive	路径:id	void	登录
POST	/api/orders/{id}/refund	路径:id + query:reason?	void	登录

OrderDetailVO 关键字段:id/orderNo/totalAmount/freightAmount/discountAmount/couponAmount/payAmount/status+statusText+statusTagType(Element Plus tag 类型)/receiverName/receiverPhone/receiverAddress/trackingCompany/trackingNo/payTime/deliverTime/receiveTime/payChannel+payChannelText/items+totalQuantity

9. 优惠券(用户端)— 路径是 /api/coupons(复数)

方法	路径	入参	出参	鉴权
GET	/api/coupons	—	List<CouponVO>(可领取列表,含已领取标记)	公开
POST	/api/coupons/{id}/receive	路径:id	Long(领取记录 ID)	登录
GET	/api/user/coupons	query:status?(0未使用/1已使用/2过期/3作废)	List<UserCouponVO>	登录

10. 收藏(用户端)

方法	路径	入参	出参	鉴权
GET	/api/favorite	query:current/size	Page<FavoriteVO>	登录
POST	/api/favorite/{productId}	路径:productId	void	登录
DELETE	/api/favorite/{favoriteId}	路径:favoriteId	void	登录
DELETE	/api/favorite/product/{productId}	路径:productId	void	登录
GET	/api/favorite/check	query:productId	Boolean	登录
GET	/api/favorite/count	—	Long	登录

11. 抢购(用户端)

方法	路径	入参	出参	鉴权
GET	/api/seckill/activities	—	List<SeckillActivityVO>(进行中/即将开始)	公开
GET	/api/seckill/activities/{id}	路径:id	SeckillActivityVO(含 products)	公开
POST	/api/seckill/buy	SeckillBuyReq{activityId, skuId, quantity}	{orderNo}(排队号/订单号)	登录
GET	/api/seckill/result/{orderNo}	路径:orderNo	SeckillResultVO{orderNo, status(0排队/1成功/2失败), statusText, message?, mainOrderId?}	登录

SeckillActivityVO 关键字段:id/name/cover/startTime/endTime/status(0未开始/1进行中/2已结束)+statusText/countdownSeconds/description/products SeckillProductVO 关键字段:id/activityId/productId/productName/productImage/skuId/skuName/originPrice/seckillPrice/discount/seckillStock/remainStock/soldPercent/perLimit

12. 客服聊天(用户端)

方法	路径	入参	出参	鉴权
POST	/api/chat/session	—	ChatSessionDetailVO(创建/恢复)	登录
GET	/api/chat/sessions	—	List<ChatSessionVO>(我的会话)	登录
GET	/api/chat/session/{id}	路径:id	ChatSessionDetailVO	登录
GET	/api/chat/session/{id}/messages	query:afterSeq?、limit(默认50)	List<ChatMessageVO>	登录
POST	/api/chat/session/{id}/message	ChatSendMessageReq	ChatMessageVO	登录
PUT	/api/chat/session/{id}/ack	ChatAckReq	void	登录
PUT	/api/chat/session/{id}/close	路径:id	void	登录
GET	/api/chat/admin/online	—	Boolean	登录
POST	/api/chat/heartbeat	—	void	登录

13. 文件上传(用户端 + 管理端通用)

方法	路径	入参	出参	鉴权
POST	/api/file/upload	multipart:file + query:bizType(avatar/product/banner/notice/chat/common,默认 common)	FileUploadVO{id, name, url, path, size, contentType, bizType, createTime}	登录
DELETE	/api/file/{id}	路径:id	void	登录

---

二、管理端接口(/api/admin/...)

1. 管理员鉴权

方法	路径	入参	出参	鉴权
POST	/api/admin/login	AdminLoginReq	LoginVO	白名单
GET	/api/admin/captcha	—	CaptchaVO(推测)	白名单
POST	/api/admin/logout	—	void	登录
GET	/api/admin/info	—	AdminVO(当前登录管理员)	登录
PUT	/api/admin/password	ChangePasswordReq	void	登录
GET	/api/admin/page	query:AdminPageReq	Page<AdminVO>	登录
GET	/api/admin/{id}	路径:id	AdminVO	登录
POST	/api/admin	AdminSaveReq	Long	登录 + super_admin
PUT	/api/admin	AdminSaveReq	void	登录 + super_admin
DELETE	/api/admin/{id}	路径:id	void	登录 + super_admin
PUT	/api/admin/{id}/password/reset	路径:id + query:newPassword	void	登录 + super_admin
PUT	/api/admin/{id}/status/{status}	路径:id/status	void	登录 + super_admin
POST	/api/admin/avatar/upload	multipart:file	FileUploadVO	登录

2. 用户管理

方法	路径	出参	鉴权
GET	/api/admin/user/page	Page<UserVO>	登录
GET	/api/admin/user/{id}	UserVO	登录
POST	/api/admin/user	Long	登录
PUT	/api/admin/user	void	登录
DELETE	/api/admin/user/{id}	void	登录
PUT	/api/admin/user/{id}/password/reset	void	登录
PUT	/api/admin/user/{id}/status/{status}	void	登录
GET	/api/admin/user/{id}/orders	Page<OrderDetailVO>	登录

3. 商品分类

方法	路径	出参	鉴权
GET	/api/admin/category/tree	List<CategoryTreeVO>	登录
GET	/api/admin/category/children	List<Category>	登录
GET	/api/admin/category/options	List<CategoryOptionVO>	登录
GET	/api/admin/category/{id}	Category	登录
POST	/api/admin/category	Long	登录
PUT	/api/admin/category	void	登录
DELETE	/api/admin/category/{id}	void	登录
PUT	/api/admin/category/{id}/status/{status}	void	登录
PUT	/api/admin/category/{id}/sort/{sort}	void	登录
POST	/api/admin/category/{id}/icon	FileUploadVO	登录

4. 商品管理

方法	路径	出参	鉴权
GET	/api/admin/product/page	Page<ProductListVO>	登录
GET	/api/admin/product/{id}	ProductDetailVO	登录
POST	/api/admin/product	Long	登录
PUT	/api/admin/product	void	登录
DELETE	/api/admin/product/{id}	void	登录
PUT	/api/admin/product/{id}/status/{status}	void	登录
PUT	/api/admin/product/{id}/hot/{isHot}	void	登录
PUT	/api/admin/product/{id}/new/{isNew}	void	登录
PUT	/api/admin/product/stock/adjust	void(StockAdjustReq)	登录

5. 轮播图管理

方法	路径	出参	鉴权
GET	/api/admin/banner/page	Page<BannerVO>	登录
GET	/api/admin/banner/{id}	BannerVO	登录
POST	/api/admin/banner	Long	登录
PUT	/api/admin/banner	void	登录
DELETE	/api/admin/banner/{id}	void	登录
PUT	/api/admin/banner/{id}/status/{status}	void	登录
PUT	/api/admin/banner/{id}/sort/{sort}	void	登录

6. 公告管理

方法	路径	出参	鉴权
GET	/api/admin/notice/page	Page<NoticeVO>	登录
GET	/api/admin/notice/{id}	NoticeVO	登录
POST	/api/admin/notice	Long	登录
PUT	/api/admin/notice	void	登录
DELETE	/api/admin/notice/{id}	void	登录
PUT	/api/admin/notice/{id}/status/{status}	void	登录
PUT	/api/admin/notice/{id}/top/{isTop}	void	登录

7. 订单管理

方法	路径	出参	鉴权
GET	/api/admin/order/page	Page<OrderDetailVO>	登录
GET	/api/admin/order/{id}	OrderDetailVO	登录
POST	/api/admin/order/{id}/deliver	void(company, trackingNo)	登录
POST	/api/admin/order/{id}/cancel	void(reason)	登录

8. 抢购管理

方法	路径	出参	鉴权
GET	/api/admin/seckill/page	Page<SeckillActivity>	登录
POST	/api/admin/seckill	Long	登录 + super_admin
PUT	/api/admin/seckill	void	登录 + super_admin
DELETE	/api/admin/seckill/{id}	void	登录 + super_admin
PUT	/api/admin/seckill/{id}/end	void	登录 + super_admin
POST	/api/admin/seckill/{id}/warmup	void	登录 + super_admin
POST	/api/admin/seckill/product	Long	登录 + super_admin
DELETE	/api/admin/seckill/product/{id}	void	登录 + super_admin

9. 优惠券管理

方法	路径	出参	鉴权
GET	/api/admin/coupon/page	Page<CouponVO>	登录
GET	/api/admin/coupon/{id}	CouponVO	登录
POST	/api/admin/coupon	Long	登录
PUT	/api/admin/coupon	void	登录
DELETE	/api/admin/coupon/{id}	void	登录
PUT	/api/admin/coupon/{id}/status/{status}	void	登录
PUT	/api/admin/coupon/{id}/status	void(兼容旧前端)	登录
GET	/api/admin/coupon/record/page	Page<UserCouponVO>	登录
GET	/api/admin/coupon/{id}/records	Page<UserCouponVO>	登录

10. 客服聊天(管理端)

方法	路径	出参	鉴权
GET	/api/admin/chat/session/page	Page<ChatSessionVO>	登录
GET	/api/admin/chat/session/{id}	ChatSessionDetailVO	登录
POST	/api/admin/chat/session/{id}/accept	ChatSessionVO	登录
POST	/api/admin/chat/session/{id}/transfer	ChatSessionVO(toAdminId)	登录
PUT	/api/admin/chat/session/{id}/status/{status}	void	登录
PUT	/api/admin/chat/session/{id}/close	void	登录
GET	/api/admin/chat/session/{id}/messages	List<ChatMessageVO>	登录
POST	/api/admin/chat/session/{id}/message	ChatMessageVO	登录
PUT	/api/admin/chat/session/{id}/ack	void	登录
GET	/api/admin/chat/quick-reply/list	List<QuickReplyVO>	登录
GET	/api/admin/chat/quick-reply/{id}	QuickReplyVO	登录
POST	/api/admin/chat/quick-reply	Long	登录
PUT	/api/admin/chat/quick-reply	void	登录
DELETE	/api/admin/chat/quick-reply/{id}	void	登录
POST	/api/admin/chat/heartbeat	void	登录
GET	/api/admin/chat/admin/online/count	Long	登录

11. 支付回调(沙箱)

方法	路径	入参	出参	鉴权
POST	/api/payment/alipay/notify	orderId/payChannel?/payTradeNo?	String	公开
POST	/api/payment/alipay/refund/notify	orderId/refundTradeNo?	String	公开

---

三、与前端 api 现状的差异(摘录)

web-snack src/api/index.ts 当前(已淘汰/需改):

当前路径	实际后端	备注
/user/login(已脱 /api)	POST /api/user/login	缺少 /api 前缀,且 request 工具应该统一加前缀
/user/profile	不存在	改为从 LoginResp 中保存 userId/nickname 到 store,登录后通过其他接口取信息
/banner/list	GET /api/banner	路径不同
/category/list	GET /api/category/tree	返回结构是树形,不是平铺
/product/list?categoryId&keyword&isHot&isNew	GET /api/product/list?categoryIds&orderBy&limit	不支持 keyword/isHot/isNew 参数;categoryId 改 categoryIds;无搜索接口
/product/detail/{id}	GET /api/product/{id}	路径差 /api 前缀
/cart/list	GET /api/cart	列表嵌套在 CartVO.items,结构不一样
/cart/add	POST /api/cart	路径不同
/cart/update(body 含 id+quantity+selected)	PUT /api/cart/quantity(只改数量)+ PUT /api/cart/{skuId}/selected	拆成两个接口
/cart/delete/{id}	DELETE /api/cart/{skuId}(用 skuId 不是 cart item id)	标识符不同
/address/list、/address/default	GET /api/address、GET /api/address/default	✓ 路径一致(只差前缀)
/order/list	GET /api/orders	路径是 orders(复数)
/order/create	POST /api/orders	路径不同;返回结构是 {orderNo} 不是完整 Order
/order/detail/{id}	GET /api/orders/{id}	路径是 orders
/coupon/list	GET /api/coupons	路径是 coupons(复数)
/notice/list	GET /api/notice/list	✓
/seckill/list	GET /api/seckill/activities	路径不同

admin-snack 现状(基本 OK,主要差异点)

模块	现状(可能)	后端实际	备注
auth	auth/login、auth/captcha	/api/admin/login、/api/admin/captcha	应确认是否存在 auth/ 子目录,或直接 /admin
chat	见 admin	见 admin	✓
coupon	coupon/list	/api/admin/coupon/page	用 page 而非 list
order	order/list	/api/admin/order/page	同上
seckill	seckill/list	/api/admin/seckill/page	同上
product	product/list	/api/admin/product/page	同上
notice	notice/list	/api/admin/notice/page	同上
file	/file/upload	POST /api/file/upload(multipart,bizType)	✓ 路径一致
user	user/list	/api/admin/user/page	同上

---

四、关键 VO 字段速查(给前端写 TS 类型用)

ProductListVO

id, name, categoryId, categoryName, brand, mainImage,
minPrice, maxPrice, totalStock, sales, status, isHot, isNew, createTime

ProductDetailVO

id, name, categoryId, categoryName, brand, mainImage, subImages[],
detail, originPrice, minPrice, sales, viewCount, status, isHot, isNew,
skuList: ProductSkuVO[], createTime

ProductSkuVO

id, productId, skuName, image, price, stock, sales, weight, sort

CartVO

items: CartItemVO[], totalCount, selectedCount,
totalAmount, selectedAmount, allSelected

CartItemVO

id, productId, productName, productImage, skuId, skuName, skuImage,
price, quantity, subtotal, stock, selected, productStatus

OrderDetailVO

id, orderNo, userId, username, totalAmount, freightAmount, discountAmount,
couponAmount, payAmount, status, statusText, statusTagType,
receiverName, receiverPhone, receiverAddress, remark,
trackingCompany, trackingNo,
payTime, deliverTime, receiveTime, cancelTime, createTime,
payChannel, payChannelText, payTradeNo, refundTradeNo, refundTime, refundReason,
items: OrderItemVO[], totalQuantity

SeckillActivityVO

id, name, cover, startTime, endTime, status(0未开始/1进行中/2已结束), statusText,
countdownSeconds, description, products: SeckillProductVO[]

SeckillProductVO

id, activityId, productId, productName, productImage, skuId, skuName,
originPrice, seckillPrice, discount, seckillStock, remainStock, soldPercent, perLimit

AddressVO

id, receiver, phone, province, city, district, detail, tag, isDefault, fullAddress, createTime

BannerVO

id, title, image, linkType(0无/1商品/2分类/3外链), linkValue, sort,
status(0下线/1上线), startTime, endTime, createTime, updateTime

NoticeVO

id, title, content(HTML), type(0普通/1重要/2活动), isTop, status,
startTime, endTime, viewCount, publisherId, createTime, updateTime

CategoryTreeVO

id, name, parentId, level(1/2/3), sort, icon, status, children: CategoryTreeVO[], createTime

CouponVO

id, name, type(0满减/1折扣/2无门槛), typeText, amount, minAmount, maxDiscount,
total(发放总量,-1不限量), remain, received, perLimit,
status(0未上线/1已上线/2已结束), statusText,
startTime, endTime, validDays, description, createTime, updateTime

UserCouponVO

id, userId, username, nickname, couponId, couponName, couponType,
status(0未使用/1已使用/2过期/3作废), statusText, orderId,
receiveTime, useTime, expireTime

FileUploadVO

id, name, url(直接用), path, size, contentType, bizType, createTime

ChatSessionVO

id, sessionNo, userId, username, nickname, avatar,
adminId, adminName, status(0待处理/1处理中/2已解决/3关闭), statusText,
unreadCount(视角相关), lastMessage, lastTime, createTime

ChatSessionDetailVO

session: ChatSessionVO, userSeq, adminSeq, closeTime

ChatMessageVO

id, sessionId, seq(会话内递增), senderId, senderType(0用户/1客服/2系统),
type(text/image/file/product/system), content, extra(JSON), isRecalled, createTime

FavoriteVO

id, productId, productName, productMainImage, minPrice, productStatus, createTime