admin/services
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ed9b555c1c53fc6b92d709c83eb6aa50d6f5c22d
services/5.md
T
董海洋 974b72e5e2 login apii
2026-06-04 10:33:58 +08:00

293 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](controllers/homeCategories.js) 查询了 `c.image`，但 `categories` 表中没有 `image` 字段
- 涉及代码: `getHomeCategories` 和 `getAllCategoriesForConfig` 两个函数
- 修复方案: 在 `categories` 表中添加 `image` 字段，或从查询中移除 `c.image`
Reference in New Issue View Git Blame Copy Permalink