# 小程序首页接口文档

> 适用端：微信小程序（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）
- **请求参数**：无

### 响应示例

```json
{
  "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`（新增）：

```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')
}
```

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

```tsx
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 封装自动跳登录页。