147 lines
4.3 KiB
Markdown
147 lines
4.3 KiB
Markdown
# 小程序接口文档：特价推荐
|
||
|
||
> 小程序首页「特价推荐」商品区：后台在「客户端配置 → 特价推荐」批量选择商品标记为推荐，
|
||
> 小程序端通过本接口分页获取推荐商品列表。
|
||
>
|
||
> 推荐仅标记商品、不设特价字段：**价格按登录门店的客户等级价展示**（售价 = 成本价 × (100 + 等级上浮比例) / 100），
|
||
> 与 `/mini/product/list` 价格口径一致。
|
||
|
||
## 通用约定
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 鉴权 | 免登录；携带门店 token（`Authorization: Bearer <token>`，登录见 `/mini/auth/login`）时返回等级价与购物车数量 |
|
||
| 响应格式 | `{ "success": true|false, "data": {...}, "msg": "..." }` |
|
||
| 金额单位 | 元，字符串两位小数（如 `26.00`） |
|
||
|
||
---
|
||
|
||
## 1. 特价推荐商品列表
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 请求方式 | `GET` |
|
||
| 路径 | `/mini/special/list` |
|
||
| 鉴权 | 无（可带门店 token） |
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---|---|
|
||
| `page` | int | 否 | 页码，默认 1 |
|
||
| `pageSize` | int | 否 | 每页条数，默认 10 |
|
||
|
||
### 行为说明
|
||
|
||
- 仅返回「状态正常」且商品「已上架」的推荐，按推荐排序 `sort` 升序（越小越靠前）；
|
||
- 行结构与 `/mini/product/list` 完全一致：商品基础字段 + `price` + `cart_id` / `cart_quantity`；
|
||
- 未登录 / 门店未设客户等级时 `price = null`，前端应引导登录后查看价格；
|
||
- `cost_price`（成本价）属于商业敏感字段，任何情况下都不会输出；
|
||
- `data.cart` 为购物车悬浮球汇总，未登录返回零值结构。
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"msg": "ok",
|
||
"data": {
|
||
"current_page": 1,
|
||
"per_page": 10,
|
||
"total": 2,
|
||
"data": [
|
||
{
|
||
"id": 15,
|
||
"category_id": 2,
|
||
"name": "西红柿",
|
||
"spec": "约5斤/份",
|
||
"unit": "斤",
|
||
"price_unit": "元/斤",
|
||
"market": "新发地",
|
||
"image_ids": "321,322",
|
||
"images_arr": [
|
||
{ "id": 321, "preview_url": "https://example.com/storage/xxx.jpg" }
|
||
],
|
||
"status": 1,
|
||
"sort": 0,
|
||
"price": "3.50",
|
||
"cart_id": 88,
|
||
"cart_quantity": "2.00"
|
||
},
|
||
{
|
||
"id": 23,
|
||
"category_id": 3,
|
||
"name": "麒麟西瓜",
|
||
"spec": "约8斤/个",
|
||
"unit": "个",
|
||
"price_unit": "元/个",
|
||
"market": "岳各庄",
|
||
"image_ids": "340",
|
||
"images_arr": [
|
||
{ "id": 340, "preview_url": "https://example.com/storage/yyy.jpg" }
|
||
],
|
||
"status": 1,
|
||
"sort": 1,
|
||
"price": "26.00",
|
||
"cart_id": 0,
|
||
"cart_quantity": "0.00"
|
||
}
|
||
],
|
||
"cart": {
|
||
"count": 2,
|
||
"quantity": "2.00",
|
||
"amount": "7.00"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `id` | 商品 ID，点击跳转商品详情 `/mini/product/{id}` |
|
||
| `price` | 当前登录门店的等级售价；未登录 / 未设等级为 `null` |
|
||
| `cart_id` | 该商品在当前门店购物车中的行 ID（0 = 不在购物车），列表直接加减购物车用 |
|
||
| `cart_quantity` | 购物车中该商品数量（不在购物车为 `"0.00"`） |
|
||
| `cart` | 购物车悬浮球汇总：`count` 行数 / `quantity` 总数量 / `amount` 总金额（元） |
|
||
|
||
### 小程序端调用示例
|
||
|
||
```js
|
||
// 首页特价推荐区（带上拉加载更多）
|
||
Page({
|
||
data: { specials: [], page: 1, hasMore: true },
|
||
|
||
async loadSpecials() {
|
||
const res = await request.get('/mini/special/list', {
|
||
page: this.data.page,
|
||
pageSize: 10,
|
||
});
|
||
const { data: rows, total } = res.data;
|
||
this.setData({
|
||
specials: this.data.page === 1 ? rows : [...this.data.specials, ...rows],
|
||
hasMore: this.data.specials.length + rows.length < total,
|
||
});
|
||
},
|
||
|
||
onReachBottom() {
|
||
if (!this.data.hasMore) return;
|
||
this.setData({ page: this.data.page + 1 });
|
||
this.loadSpecials();
|
||
},
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 后台配置入口
|
||
|
||
PC 后台「客户端配置 → 特价推荐」：
|
||
|
||
| 操作 | 说明 |
|
||
|---|---|
|
||
| 添加商品 | 按商品名称搜索（仅上架商品可选），支持一次多选批量添加；已在推荐中的商品自动跳过 |
|
||
| 批量删除 | 勾选后批量移除推荐（不影响商品档案本身） |
|
||
| 编辑 | 仅可调整排序与状态（正常/停用） |
|