# 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`