plugin.store-projects.frontend.designer.get-goods 接口文档

多门店核销组件商品列表接口，支持距离排序、销量排序、分类筛选及分类列表返回

接口地址

POST plugin.store-projects.frontend.designer.get-goods

请求参数

参数名 类型 必填 说明
distance_order string 否 功能1：距离排序方向。传 asc 由近到远，desc 由远到近；不传则不按距离排序
sales_order string 否 功能4：销量排序方向。传 asc 升序（少→多），desc 降序（多→少）；不传则不按销量排序
return_category int 否 功能2：是否返回一级分类列表。传 1 开启；不传则不返回
category_id int 否 功能2附加：按一级分类 ID 筛选商品；不传则返回所有商品
page int 否 页码，默认 1

响应示例

{
  "status": 1,
  "msg": "成功",
  "data": {
    "current_page": 1,
    "data": [
      {
        "goodid": 100,
        "name": "商品名称",
        "img": "https://xxx.com/image.jpg",
        "priceold": "99.00",
        "pricenow": "59.00",
        "sales": 520,
        "distance": 850,
        "distance_unit": "m",
        "stock_status": 0,
        "point": 10,
        "vip_price": "49.00",
        "goods_content_show": {}
      }
    ],
    "total": 20,
    "per_page": 8,
    "last_page": 3,
    "categories": [
      {
        "id": 5,
        "name": "餐饮美食",
        "thumb": "https://xxx.com/cat.png"
      },
      {
        "id": 8,
        "name": "休闲娱乐",
        "thumb": "https://xxx.com/cat2.png"
      }
    ]
  }
}

新增功能说明

功能1：距离排序（distance_order）

根据商品可核销的最近门店距离在 SQL 层排序。

  • distance_order=asc：由近到远排序
  • distance_order=desc：由远到近排序
  • 不传：不排序，保持装修组件原始顺序
  • 使用 Haversine 公式在 SQL 中计算每个商品到其可核销门店的最近距离
  • 优先取 yz_store 表中该商品绑定门店的距离；若未绑定或无门店则取 yz_hotel 表
  • 排序在 SQL 层完成（ORDER BY goods_distance），支持分页正确排序
  • 返回的 distance 字段：小于 1000 米时为米（m），超过 1000 米自动转为千米（km）

功能2：返回一级分类列表（return_category）

返回当前所有可核销商品所属的所有一级分类（去重）。

  • 查询 yz_goods_category 表获取商品-分类关系
  • 通过 category_ids 字段取出一级分类 ID，过滤 level=1, enabled=1
  • 返回格式：[{id, name, thumb}, ...]
  • ⚠️ 分类列表基于所有商品，不因 category_id 筛选而丢失

功能2附加：分类筛选（category_id）

按一级分类 ID 筛选商品，与 return_category 配合使用。

  • 传入一级分类 id，只返回该分类下的商品
  • category_id 筛选不影响 categories 返回，分类列表始终包含所有商品的分类
  • 若筛选后无商品，返回空 data 数组，但 categories 仍然完整

功能4：销量排序（sales_order）

按商品总销量（virtual_sales + real_sales）在 SQL 层排序。

  • sales_order=asc：升序（销量少的在前）
  • sales_order=desc：降序（销量多的在前）
  • 不传：不排序，保持原有顺序
  • 排序在 SQL 层完成（ORDER BY (virtual_sales + real_sales)），支持分页正确排序

排序优先级

当同时传 distance_order 和 sales_order 时，距离优先：

  1. 先按距离排序
  2. 距离相同的情况下，按销量排序

注意事项

  • lng 和 lat 为必填参数，用于计算门店距离
  • 需安装并启用 decorate（装修）插件
  • 距离和销量排序均在 SQL 层完成，分页结果正确