# 小程序接口文档：特价推荐

> 小程序首页「特价推荐」商品区：后台在「客户端配置 → 特价推荐」批量选择商品标记为推荐，
> 小程序端通过本接口分页获取推荐商品列表。
>
> 推荐仅标记商品、不设特价字段：**价格按登录门店的客户等级价展示**（售价 = 成本价 × (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 后台「客户端配置 → 特价推荐」：

| 操作 | 说明 |
|---|---|
| 添加商品 | 按商品名称搜索（仅上架商品可选），支持一次多选批量添加；已在推荐中的商品自动跳过 |
| 批量删除 | 勾选后批量移除推荐（不影响商品档案本身） |
| 编辑 | 仅可调整排序与状态（正常/停用） |