小程序首页配置

2026-08-14 12:41:18 +08:00
parent 889f987f17
commit 8b3cef5af0
21 changed files with 1350 additions and 3 deletions
@@ -0,0 +1,172 @@
+# 小程序首页接口文档
+
+> 适用端：微信小程序（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 封装自动跳登录页。