148 lines
4.4 KiB
Markdown
148 lines
4.4 KiB
Markdown
# 首页内容管理指南
|
|
|
|
本文档说明如何管理小程序首页的Banner和热门服务。
|
|
|
|
## 功能概述
|
|
|
|
系统支持动态配置首页的以下内容:
|
|
- **Banner轮播图**: 首页顶部的轮播广告图
|
|
- **热门服务**: 首页展示的服务快捷入口
|
|
|
|
## 数据库表结构
|
|
|
|
### banners表
|
|
| 字段 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| id | INT | 主键 |
|
|
| image_url | VARCHAR(500) | Banner图片URL |
|
|
| link_url | VARCHAR(500) | 点击跳转链接(可选) |
|
|
| sort_order | INT | 排序顺序(数字越小越靠前) |
|
|
| is_active | BOOLEAN | 是否启用 |
|
|
|
|
### hot_services表
|
|
| 字段 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| id | INT | 主键 |
|
|
| name_zh | VARCHAR(100) | 服务名称(中文) |
|
|
| name_en | VARCHAR(100) | 服务名称(英文) |
|
|
| name_pt | VARCHAR(100) | 服务名称(葡萄牙语) |
|
|
| image_url | VARCHAR(500) | 服务图片URL(可选) |
|
|
| link_url | VARCHAR(500) | 点击跳转链接(可选) |
|
|
| sort_order | INT | 排序顺序(数字越小越靠前) |
|
|
| is_active | BOOLEAN | 是否启用 |
|
|
|
|
## API接口
|
|
|
|
### 公共接口(小程序使用)
|
|
|
|
#### 获取Banner列表
|
|
```
|
|
GET /api/v1/home/banners
|
|
```
|
|
返回所有启用的Banner,按sort_order排序。
|
|
|
|
#### 获取热门服务列表
|
|
```
|
|
GET /api/v1/home/hot-services
|
|
```
|
|
返回所有启用的热门服务,按sort_order排序。
|
|
支持多语言,通过`Accept-Language`请求头指定语言(zh/en/pt)。
|
|
|
|
### 管理后台接口(需要管理员权限)
|
|
|
|
#### Banner管理
|
|
```
|
|
GET /api/v1/admin/home/banners # 获取所有Banner
|
|
POST /api/v1/admin/home/banners # 创建Banner
|
|
PUT /api/v1/admin/home/banners/:id # 更新Banner
|
|
DELETE /api/v1/admin/home/banners/:id # 删除Banner
|
|
```
|
|
|
|
#### 热门服务管理
|
|
```
|
|
GET /api/v1/admin/home/hot-services # 获取所有热门服务
|
|
POST /api/v1/admin/home/hot-services # 创建热门服务
|
|
PUT /api/v1/admin/home/hot-services/:id # 更新热门服务
|
|
DELETE /api/v1/admin/home/hot-services/:id # 删除热门服务
|
|
```
|
|
|
|
## 使用示例
|
|
|
|
### 创建Banner
|
|
```bash
|
|
curl -X POST http://localhost:3000/api/v1/admin/home/banners \
|
|
-H "Authorization: Bearer YOUR_TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"image_url": "/uploads/banner1.jpg",
|
|
"link_url": "/pages/promotion/detail",
|
|
"sort_order": 1,
|
|
"is_active": true
|
|
}'
|
|
```
|
|
|
|
### 创建热门服务
|
|
```bash
|
|
curl -X POST http://localhost:3000/api/v1/admin/home/hot-services \
|
|
-H "Authorization: Bearer YOUR_TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"name_zh": "国内/外机票",
|
|
"name_en": "Domestic/International Tickets",
|
|
"name_pt": "Passagens Domésticas/Internacionais",
|
|
"image_url": "/uploads/service-flight.jpg",
|
|
"sort_order": 1,
|
|
"is_active": true
|
|
}'
|
|
```
|
|
|
|
## 默认数据
|
|
|
|
系统已预置4个热门服务:
|
|
1. 国内/外机票 (Domestic/International Tickets / Passagens Domésticas/Internacionais)
|
|
2. 全球酒店 (Global Hotels / Hotéis Globais)
|
|
3. 机场贵宾室 (VIP Lounge / Sala VIP)
|
|
4. 特殊旅客定制 (Custom Service / Serviço Personalizado)
|
|
|
|
## 注意事项
|
|
|
|
1. **图片上传**: 图片需要先通过上传接口上传,获得URL后再配置
|
|
2. **排序**: sort_order数字越小,显示越靠前
|
|
3. **启用状态**: 只有is_active=true的内容才会在小程序中显示
|
|
4. **多语言**: 热门服务支持三种语言,小程序会根据用户语言设置自动显示对应语言
|
|
5. **图片URL**: 可以是相对路径(如/uploads/xxx.jpg)或完整URL
|
|
|
|
## 管理后台UI
|
|
|
|
管理后台的Banner和热门服务管理界面可以在配置页面中添加,或者创建独立的管理页面。
|
|
|
|
建议在管理后台的侧边栏添加"首页管理"菜单项,包含:
|
|
- Banner管理
|
|
- 热门服务管理
|
|
|
|
## 小程序前端
|
|
|
|
小程序首页会自动从API加载Banner和热门服务数据:
|
|
- Banner会显示在页面顶部的轮播图中
|
|
- 热门服务会显示在"热门服务"区域
|
|
- 如果没有配置图片,会显示占位符
|
|
|
|
## 故障排查
|
|
|
|
### Banner不显示
|
|
1. 检查数据库中是否有is_active=true的Banner记录
|
|
2. 检查image_url是否正确
|
|
3. 检查图片文件是否存在于uploads目录
|
|
4. 检查小程序控制台是否有错误信息
|
|
|
|
### 热门服务不显示
|
|
1. 检查数据库中是否有is_active=true的记录
|
|
2. 检查API返回的数据格式是否正确
|
|
3. 检查小程序的语言设置
|
|
|
|
### 图片加载失败
|
|
1. 确认后端服务器正在运行
|
|
2. 确认图片URL可以访问
|
|
3. 检查CSP安全策略是否允许加载图片
|
|
4. 在微信开发者工具中关闭"不校验合法域名"选项
|