推荐商品

2026-08-31 22:21:59 +08:00
parent 6c809d893b
commit 9c59f3bc99
191 changed files with 2095 additions and 1 deletions
@@ -0,0 +1,146 @@
+# 小程序接口文档：特价推荐
+
+> 小程序首页「特价推荐」商品区：后台在「客户端配置 → 特价推荐」批量选择商品标记为推荐，
+> 小程序端通过本接口分页获取推荐商品列表。
+>
+> 推荐仅标记商品、不设特价字段：**价格按登录门店的客户等级价展示**（售价 = 成本价 × (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 后台「客户端配置 → 特价推荐」：
+
+| 操作 | 说明 |
+|---|---|
+| 添加商品 | 按商品名称搜索（仅上架商品可选），支持一次多选批量添加；已在推荐中的商品自动跳过 |
+| 批量删除 | 勾选后批量移除推荐（不影响商品档案本身） |
+| 编辑 | 仅可调整排序与状态（正常/停用） |