# 首页内容管理指南

本文档说明如何管理小程序首页的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. 在微信开发者工具中关闭"不校验合法域名"选项