173 lines
4.9 KiB
Markdown
173 lines
4.9 KiB
Markdown
# 小程序首页接口文档
|
||
|
||
> 适用端：微信小程序（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 封装自动跳登录页。
|