services/5.md

Services 接口文档

基础地址: https://donghy.top (生产) / http://localhost:3006 (开发) 鉴权方式: Authorization: Bearer <token> 或 ?token=<token>

权限说明

权限级别	值	说明
公开	-	无需登录
requireAuth	0+	任何已登录用户
requireStaffAuth	1+	店员或管理员
requireAdminAuth	2	仅管理员

---

1. 用户模块 /api/users

方法	路径	权限	说明
POST	/api/users/login	公开	账号密码登录
POST	/api/users/wechat-login	公开	微信小程序登录
POST	/api/users/register	公开	用户注册
POST	/api/users/change-password	公开	修改密码
POST	/api/users/send-reset-code	公开	发送重置验证码
POST	/api/users/verify-reset-code	公开	验证重置验证码
POST	/api/users/reset-password-with-code	公开	通过验证码重置密码
POST	/api/users/refresh-token	公开	刷新 Token
GET	/api/users/info	公开	获取用户信息
POST	/api/users/logout	登录用户	退出登录
POST	/api/users/register/by-staff	店员+	店员注册用户
POST	/api/users/points/add	店员+	增加用户积分
POST	/api/users/register/staff	管理员	注册店员账号
POST	/api/users/reset-password	管理员	重置用户密码
GET	/api/users	管理员	获取用户列表
PUT	/api/users/:id	管理员	更新用户信息
DELETE	/api/users/:id	管理员	删除用户
GET	/api/users/points/logs	通用	获取积分日志

2. 商品模块 /api/goods

方法	路径	权限	说明
GET	/api/goods	公开	获取商品列表
GET	/api/goods/:id	公开	获取商品详情
POST	/api/goods	店员+	创建商品
POST	/api/goods/batch-update	店员+	批量更新商品
PUT	/api/goods/:id	店员+	更新商品
DELETE	/api/goods/:id	店员+	删除商品

3. 订单模块 /api/orders

方法	路径	权限	说明
GET	/api/orders	-	获取订单列表
GET	/api/orders/:id	-	获取订单详情
POST	/api/orders	-	创建订单
PUT	/api/orders/:id	-	更新订单
PUT	/api/orders/:id/status	-	更新订单状态

4. 购物车模块 /api/cart

方法	路径	权限	说明
GET	/api/cart	登录用户	获取购物车
POST	/api/cart/add	登录用户	添加到购物车
PUT	/api/cart/update	登录用户	更新购物车项
POST	/api/cart/remove	登录用户	移除购物车项
DELETE	/api/cart/clear	登录用户	清空购物车
POST	/api/cart/sync	登录用户	同步购物车

5. 分类模块 /api/categories

方法	路径	权限	说明
GET	/api/categories	公开	获取分类列表
GET	/api/categories/:id	公开	获取分类详情
POST	/api/categories	管理员	创建分类
PUT	/api/categories/:id	管理员	更新分类
DELETE	/api/categories/:id	管理员	删除分类

6. 地址模块 /api/addresses

方法	路径	权限	说明
GET	/api/addresses	登录用户	获取地址列表
GET	/api/addresses/:id	登录用户	获取地址详情
POST	/api/addresses	登录用户	创建地址
PUT	/api/addresses/:id	登录用户	更新地址
DELETE	/api/addresses/:id	登录用户	删除地址
PUT	/api/addresses/:id/default	登录用户	设为默认地址

7. 库存模块 /api/stock

方法	路径	权限	说明
GET	/api/stock	店员+	获取库存列表
GET	/api/stock/logs	店员+	获取库存变动日志
GET	/api/stock/:id	公开	按商品ID查库存
POST	/api/stock/:id/adjust	店员+	调整库存

8. 支付模块 /api/payment

方法	路径	权限	说明
POST	/api/payment/create	登录用户	创建支付
GET	/api/payment/query/:orderId	登录用户	查询支付结果
POST	/api/payment/notify	公开	微信支付回调
POST	/api/payment/refund	管理员	申请退款

9. 退款模块 /api/refunds

方法	路径	权限	说明
GET	/api/refunds	店员+	获取退款列表
GET	/api/refunds/user/list	登录用户	获取用户退款列表
GET	/api/refunds/:id	登录用户	获取退款详情
POST	/api/refunds	登录用户	创建退款申请
PUT	/api/refunds/:id/process	店员+	处理退款

10. 供应商模块 /api/suppliers

方法	路径	权限	说明
GET	/api/suppliers	店员+	获取供应商列表
GET	/api/suppliers/:id	店员+	获取供应商详情
POST	/api/suppliers	店员+	创建供应商
PUT	/api/suppliers/:id	店员+	更新供应商
DELETE	/api/suppliers/:id	管理员	删除供应商

11. 进货模块 /api/purchases

方法	路径	权限	说明
GET	/api/purchases	店员+	获取进货列表
GET	/api/purchases/:id	店员+	获取进货详情
POST	/api/purchases	店员+	创建进货单
POST	/api/purchases/:id/inbound	店员+	进货入库

12. 积分商品模块 /api/points-goods

方法	路径	权限	说明
GET	/api/points-goods	公开	获取积分商品列表
GET	/api/points-goods/:id	公开	获取积分商品详情
POST	/api/points-goods	管理员	创建积分商品
PUT	/api/points-goods/:id	管理员	更新积分商品
DELETE	/api/points-goods/:id	管理员	删除积分商品
POST	/api/points-goods/exchange	登录用户	积分兑换

13. 积分日志模块 /api/points/logs

方法	路径	权限	说明
GET	/api/points/logs/:userId	-	获取用户积分日志

14. 统计模块 /api/stats

方法	路径	权限	说明
GET	/api/stats/today	店员+	今日统计
GET	/api/stats/metrics	管理员	系统指标（连接池/查询/内存）

15. 报表模块 /api/reports

方法	路径	权限	说明
GET	/api/reports/sales-trend	店员+	销售趋势
GET	/api/reports/hot-products	店员+	热销商品
GET	/api/reports/profit	店员+	利润分析
GET	/api/reports/inventory-turnover	店员+	库存周转率

16. 导出模块 /api/export

方法	路径	权限	说明
GET	/api/export/goods	店员+	导出商品
GET	/api/export/orders	店员+	导出订单
GET	/api/export/stock	店员+	导出库存
GET	/api/export/purchases	店员+	导出进货

17. 识别模块 /api/recognize

方法	路径	权限	说明
POST	/api/recognize/barcode	店员+	条码识别
POST	/api/recognize/image	店员+	图片识别

18. AI 模块 /api/ai

方法	路径	权限	说明
POST	/api/ai/generate-product	店员+	AI 生成商品信息
POST	/api/ai/recognize-product	店员+	AI 识别商品（图片）

19. 订阅消息模块 /api/subscribe

方法	路径	权限	说明
POST	/api/subscribe/bind-openid	登录用户	绑定微信 OpenID
POST	/api/subscribe/orders/notify	店员+	订单订阅通知

20. 商品规格模块 /api/goods-specs

方法	路径	权限	说明
GET	/api/goods-specs	公开	获取规格列表
POST	/api/goods-specs	店员+	创建规格
PUT	/api/goods-specs/:id	店员+	更新规格
DELETE	/api/goods-specs/:id	店员+	删除规格
POST	/api/goods-specs/batch	店员+	批量保存规格

21. 首页分类模块 /api/home

方法	路径	权限	说明
GET	/api/home/categories	公开	获取首页分类
PUT	/api/home/categories	管理员	更新首页分类
GET	/api/home/categories/config	管理员	获取分类配置

22. 报价单模块 /api/price-list

方法	路径	权限	说明
GET	/api/price-list/:orderId	登录用户	获取报价单

23. 上传模块 /api/upload

方法	路径	权限	说明
POST	/api/upload	店员+	上传图片（支持 goods/points/avatar/category 目录）

---

接口统计

• 总计 23 个模块，70+ 个接口
• 公开接口: 登录、注册、商品浏览、分类浏览、积分商品浏览等
• 登录用户接口: 购物车、地址、订单、退款、积分兑换等
• 店员接口: 商品管理、库存管理、进货、报表、导出等
• 管理员接口: 用户管理、分类管理、供应商删除、系统指标等

---

接口测试结果（线上 https://donghy.top）

测试时间: 2026-06-04

公开接口测试

接口	方法	状态码	结果
/api/goods	GET	200	正常
/api/categories	GET	200	正常
/api/points-goods	GET	200	正常
/api/goods-specs	GET	200	正常
/api/home/categories	GET	500	异常: Unknown column 'c.image' in 'field list'
/api/users/info	GET	200	正常
/api/users/login	POST	200	正常
/api/users/register	POST	200	正常
/api/payment/notify	POST	200	正常
/api/points/logs/1	GET	200	正常

鉴权接口测试（无 Token，预期返回 401）

接口	方法	状态码	结果
/api/cart	GET	401	正常（未登录拒绝）
/api/addresses	GET	401	正常
/api/stock	GET	401	正常
/api/stats/today	GET	401	正常
/api/suppliers	GET	401	正常
/api/purchases	GET	401	正常
/api/refunds	GET	401	正常
/api/reports/sales-trend	GET	401	正常
/api/stats/metrics	GET	401	正常
/api/ai/generate-product	POST	401	正常
/api/recognize/barcode	POST	401	正常
/api/upload	POST	401	正常
/api/export/goods	GET	401	正常
/api/orders	GET	401	正常
/api/price-list/1	GET	401	正常
/api/subscribe/bind-openid	POST	401	正常

发现的问题

GET /api/home/categories 返回 500 错误

• 错误信息: Unknown column 'c.image' in 'field list'
• 原因: controllers/homeCategories.js 查询了 c.image，但 categories 表中没有 image 字段
• 涉及代码: getHomeCategories 和 getAllCategoriesForConfig 两个函数
• 修复方案: 在 categories 表中添加 image 字段，或从查询中移除 c.image