logan

Appearance

平台轮播开发文档 ​

平台轮播由管理员按用户端、商户端分别配置，两端图片和公告链接互不影响。配置分别保存在 system_config.platform_banners_user 和 system_config.platform_banners_merchant，无需新增数据表。

1. 获取平台轮播图 ​

接口地址：POST /home/index/platformBanners

认证：不需要

请求参数：

参数名类型必填说明
sceneString是轮播场景：user=用户端，merchant=商户端

用户端请求示例：

json
{
  "scene": "user"
}

商户端请求示例：

json
{
  "scene": "merchant"
}

商户端调用位置：mini_app_merchant/src/api/config/platformBanner.ts

用户端调用位置：mini_app_client/src/api/common/platformBanner.ts

成功响应示例：

json
{
  "code": 1,
  "msg": "获取成功",
  "data": [
    {
      "image": "https://example.com/upload/image/20260803/banner-1.jpg",
      "link": "https://example.com/activity",
      "sort": 10
    },
    {
      "image": "https://example.com/upload/image/20260803/banner-2.jpg",
      "link": "",
      "sort": 20
    }
  ]
}

响应字段：

字段名类型说明
imageString图片完整访问地址
linkString点击后的跳转链接；空字符串表示不可跳转
sortInteger排序值，数值越小越靠前

业务规则：

  • 最多返回 5 张图片。
  • 只返回已配置图片的项目。
  • 返回前按照 sort 升序排列；排序相同时保持原配置顺序。
  • 未配置轮播图时返回空数组 []，前端不显示轮播区域。
  • link 支持站内 / 开头路径、http://、https:// 和 tg:// 链接。
  • 用户端只请求 scene=user，商户端只请求 scene=merchant，两端配置互不混用。
  • 为兼容拆分前的数据，如果某一端从未单独保存过配置，会临时回退读取旧的 system_config.platform_banners；该端首次保存后即停止回退。

2. 获取管理端轮播配置 ​

接口地址：POST /adminapi/config/platformBanner/getConfig

认证：需要管理员 Token 和对应接口权限

请求参数：

参数名类型必填说明
sceneString是user 或 merchant

响应说明：响应结构与公开读取接口一致。管理端响应中的 image 保留配置原值，可能是上传接口返回的相对路径，便于继续编辑和保存。

3. 保存管理端轮播配置 ​

接口地址：POST /adminapi/config/platformBanner/saveConfig

认证：需要管理员 Token 和对应接口权限

请求参数：

参数名类型必填说明
bannersArray是轮播配置数组，最多 5 项；清空轮播时传空数组
sceneString是保存目标：user=用户端，merchant=商户端
banners[].imageString是图片地址或上传接口返回的图片路径
banners[].linkString否点击跳转链接，默认空字符串
banners[].sortInteger否排序值，范围 0～9999，默认使用当前顺序

请求示例：

json
{
  "scene": "user",
  "banners": [
    {
      "image": "/upload/image/20260803/banner-1.jpg",
      "link": "https://example.com/activity",
      "sort": 10
    },
    {
      "image": "/upload/image/20260803/banner-2.jpg",
      "link": "",
      "sort": 20
    }
  ]
}

成功响应示例：

json
{
  "code": 1,
  "msg": "保存成功",
  "data": [
    {
      "image": "/upload/image/20260803/banner-1.jpg",
      "link": "https://example.com/activity",
      "sort": 10
    },
    {
      "image": "/upload/image/20260803/banner-2.jpg",
      "link": "",
      "sort": 20
    }
  ]
}

常见错误：

json
{
  "code": 0,
  "msg": "轮播场景必须为 user 或 merchant"
}
json
{
  "code": 0,
  "msg": "轮播图最多配置5张"
}
json
{
  "code": 0,
  "msg": "第1张轮播图不能为空"
}
json
{
  "code": 0,
  "msg": "第1张轮播图的跳转链接格式不正确"
}

4. 缓存策略 ​

  • 两端使用独立应用缓存：用户端为 platform_banners_user_v1，商户端为 platform_banners_merchant_v1。
  • 缓存有效期为 3600 秒（1 小时）。
  • 管理员保存某一端配置成功后，只删除该端缓存，不影响另一端。
  • 缓存删除后，下一次商户端或用户端请求会从 system_config 读取最新配置、生成图片完整地址并重新缓存。
  • 前端请求中的时间戳参数不会绕过或重复生成服务端缓存。

5. 管理后台入口 ​

进入“配置中心 → 网站配置 → 轮播配置”，先选择“用户端轮播”或“商户端轮播”，再上传图片、填写可选跳转链接和设置排序。每个端最多配置 5 张。

管理员上传图片使用现有接口：POST /adminapi/upload/upload，表单字段为 file，并携带 type=image。