outsource/appointment_system

Fork 0

18631081161 7cf63cfad0 1

2025-12-11 22:50:18 +08:00

4.4 KiB

Raw Blame History

首页内容管理指南

本文档说明如何管理小程序首页的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

使用示例

创建Banner

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

创建热门服务

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个热门服务:

国内/外机票 (Domestic/International Tickets / Passagens Domésticas/Internacionais)
全球酒店 (Global Hotels / Hotéis Globais)
机场贵宾室 (VIP Lounge / Sala VIP)
特殊旅客定制 (Custom Service / Serviço Personalizado)

注意事项

图片上传: 图片需要先通过上传接口上传,获得URL后再配置
排序: sort_order数字越小,显示越靠前
启用状态: 只有is_active=true的内容才会在小程序中显示
多语言: 热门服务支持三种语言,小程序会根据用户语言设置自动显示对应语言
图片URL: 可以是相对路径(如/uploads/xxx.jpg)或完整URL

管理后台UI

管理后台的Banner和热门服务管理界面可以在配置页面中添加,或者创建独立的管理页面。

建议在管理后台的侧边栏添加"首页管理"菜单项,包含:

Banner管理
热门服务管理

小程序前端

小程序首页会自动从API加载Banner和热门服务数据:

Banner会显示在页面顶部的轮播图中
热门服务会显示在"热门服务"区域
如果没有配置图片,会显示占位符

故障排查

Banner不显示

检查数据库中是否有is_active=true的Banner记录
检查image_url是否正确
检查图片文件是否存在于uploads目录
检查小程序控制台是否有错误信息

图片加载失败

确认后端服务器正在运行
确认图片URL可以访问
检查CSP安全策略是否允许加载图片
在微信开发者工具中关闭"不校验合法域名"选项

4.4 KiB Raw Blame History