21 KiB

Raw Permalink Blame History

后端真实接口清单

本文档为前后端对接的唯一事实来源,由后端 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

21 KiB Raw Permalink Blame History

后端真实接口清单

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

1. 用户鉴权

2. 商品(用户端)

3. 分类(用户端)

4. 轮播图(用户端)

5. 公告(用户端)

6. 购物车(用户端)

7. 收货地址(用户端)

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

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

10. 收藏(用户端)

11. 抢购(用户端)

12. 客服聊天(用户端)

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

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

1. 管理员鉴权

2. 用户管理

3. 商品分类

4. 商品管理

5. 轮播图管理

6. 公告管理

7. 订单管理

8. 抢购管理

9. 优惠券管理

10. 客服聊天(管理端)

11. 支付回调(沙箱)

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

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

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

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

ProductListVO

ProductDetailVO

ProductSkuVO

CartVO

CartItemVO

OrderDetailVO

SeckillActivityVO

SeckillProductVO

AddressVO

BannerVO

NoticeVO

CategoryTreeVO

CouponVO

UserCouponVO

FileUploadVO

ChatSessionVO

ChatSessionDetailVO

ChatMessageVO

FavoriteVO

21 KiB

Raw Permalink Blame History

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

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

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

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

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