xin-procurement-weapp/mini-home-api.md

小程序首页接口文档

适用端：微信小程序（h5 仓库，Taro） 后台配置入口：PC 后台「客户端配置」菜单（首页轮播图 / 宫格导航 / 促销推荐卡片） 更新日期：2026-08-14

通用约定

项	说明
根地址	BASE_URL（见 src/utils/request.ts，如 http://localhost:8000/index.php）
认证	请求头 Authorization: Bearer {token}，token 来自登录接口，本地存储 key auth_token
响应包络	{ success: boolean, data: T, msg?: string, showType?: number }
失败处理	success=false 时 msg 为中文错误信息；HTTP 401 表示登录过期，需重新登录

GET /mini/home

首页配置聚合接口：一次返回轮播图、宫格导航、促销推荐卡片三组数据，均为**启用状态（status=1）**且按 sort 升序（越小越靠前）。

• 权限：需登录（Bearer token）
• 请求参数：无

响应示例

{
  "success": true,
  "msg": "ok",
  "data": {
    "banners": [
      {
        "id": 1,
        "title": "新鲜直采",
        "image_id": 123,
        "link": "/pages/goods/detail?id=1",
        "sort": 0,
        "image_url": "http://localhost:8000/storage/uploads/2026/08/14/xxx.jpg"
      }
    ],
    "navs": [
      {
        "id": 1,
        "name": "蔬菜专区",
        "image_id": 124,
        "link": "/pages/category/index?id=1",
        "sort": 0,
        "image_url": "http://localhost:8000/storage/uploads/2026/08/14/yyy.png"
      }
    ],
    "promos": [
      {
        "id": 1,
        "title": "限时特惠",
        "sub_title": "全场 8 折起",
        "image_id": 125,
        "link": "/pages/promo/detail?id=1",
        "sort": 0,
        "image_url": "http://localhost:8000/storage/uploads/2026/08/14/zzz.jpg"
      }
    ]
  }
}

字段说明

banners（轮播图）

字段	类型	说明
id	number	轮播图 ID
title	string	标题（后台维护，可用于无障碍/占位）
image_id	number	图片文件 ID（sys_file），一般无需使用
image_url	string | null	轮播图片完整 URL，直接用于 <Image src>；未传图时为 null
link	string	小程序页面跳转路径，空字符串表示点击不跳转
sort	number	排序值（已按此升序返回，前端无需再排）

navs（宫格导航）

字段	类型	说明
id	number	导航 ID
name	string	导航名称（宫格文字）
image_url	string | null	导航图标完整 URL
link	string	小程序页面跳转路径，空字符串不跳转
sort	number	排序值

promos（促销推荐卡片）

字段	类型	说明
id	number	卡片 ID
title	string	卡片标题
sub_title	string	副标题/促销文案，可能为空字符串
image_url	string | null	卡片图片完整 URL
link	string	小程序页面跳转路径，空字符串不跳转
sort	number	排序值

前端接入示例

src/services/home.ts（新增）：

import { get } from '@/utils/request'

/** 首页轮播图项 */
export interface HomeBanner {
  id: number
  title: string
  image_id: number
  image_url: string | null
  link: string
  sort: number
}

/** 首页宫格导航项 */
export interface HomeNav {
  id: number
  name: string
  image_id: number
  image_url: string | null
  link: string
  sort: number
}

/** 首页促销推荐卡片 */
export interface HomePromo {
  id: number
  title: string
  sub_title: string
  image_id: number
  image_url: string | null
  link: string
  sort: number
}

/** 首页配置聚合数据 */
export interface HomeConfig {
  banners: HomeBanner[]
  navs: HomeNav[]
  promos: HomePromo[]
}

/** 首页配置（轮播图 + 宫格导航 + 促销卡片）：GET /mini/home */
export function getHomeConfigApi() {
  return get<HomeConfig>('/mini/home')
}

页面中使用（跳转需兼容空链接）：

const [config, setConfig] = useState<HomeConfig>({ banners: [], navs: [], promos: [] })

useEffect(() => {
  getHomeConfigApi().then(res => setConfig(res.data))
}, [])

/** 统一跳转：link 为空不跳转 */
function handleLink(link: string) {
  if (!link) return
  Taro.navigateTo({ url: link })
}

注意事项

1. 三组数据均可能为空数组（后台未配置或全部停用），页面需做空态处理。
2. image_url 可能为 null（后台未上传图片），渲染前判空。
3. link 为小程序内部页面路径（以 / 开头），用 Taro.navigateTo 跳转；若目标为 tabBar 页面需改用 Taro.switchTab（建议后台配置时避免填 tabBar 路径）。
4. 数据实时生效：后台修改后，小程序下次进入首页请求即为最新内容，无缓存。
5. 接口需登录后调用；未登录（401）会由 request 封装自动跳登录页。