xin-procurement/docs/api/mini-special.md

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

小程序首页「特价推荐」商品区：后台在「客户端配置 → 特价推荐」批量选择商品标记为推荐， 小程序端通过本接口分页获取推荐商品列表。

推荐仅标记商品、不设特价字段：价格按登录门店的客户等级价展示（售价 = 成本价 × (100 + 等级上浮比例) / 100）， 与 /mini/product/list 价格口径一致。

通用约定

项	值
鉴权	免登录；携带门店 token（Authorization: Bearer <token>，登录见 /mini/auth/login）时返回等级价与购物车数量
响应格式	`{ "success": true
金额单位	元，字符串两位小数（如 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 为购物车悬浮球汇总，未登录返回零值结构。

响应示例

{
  "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 总金额（元）

小程序端调用示例

// 首页特价推荐区（带上拉加载更多）
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 后台「客户端配置 → 特价推荐」：

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