前言

最近逛 Gitee 开源社区时，发现了一个非常有意思的项目 —— Scenic Digital（智慧文旅数字人体验平台）。

这个项目将"数字人"、“数据大屏”、"MCP 导航"这些热门概念整合到了一起，做出了一个科幻感十足的文旅场景应用。整个项目前后端分离，代码结构清晰，非常适合用来学习全栈开发或作为展厅类项目的起步模板。

今天就来深度拆解一下这个项目。

---

一、项目概览

Scenic Digital 是一个以 Fay 数字人服务和魔珐星云 3D 渲染 SDK 为核心的现代化大屏展示与管理平台。它提供了：

• 沉浸式景区全景概览大屏（桌面端三面板布局）
• 实时客流监控与舒适度联动计算
• 景点本地图片上传管理
• 3D 伴游数字人交互
• MCP 地图导航服务
• 移动端独立体验页面

适用场景非常明确：企业展厅展示、景区游客中心大屏、政府数字化投标演示以及全栈开发学习参考。

---

二、视觉体验：科幻级 UI 是怎么炼成的

打开项目的第一眼，你就会被它的 UI 震撼到。整套界面基于 Tailwind CSS v4 构建深色科幻风格（Cyberpunk/Tech 风格），视觉细节拉满。

2.1 Canvas 粒子动画背景

项目使用原生 Canvas API 实现了全屏粒子动画背景，粒子之间会动态连线形成网络效果。更巧妙的是，粒子颜色会随着四季主题（春/夏/秋/冬）自动切换：

// 根据主题设置粒子颜色
const theme = document.documentElement.getAttribute('data-theme')
if (theme === 'spring_season') {
  this.color = Math.random() > 0.5 ? '#84cc16' : '#22c55e'
} else if (theme === 'summer') {
  this.color = Math.random() > 0.5 ? '#38bdf8' : '#3b82f6'
} else if (theme === 'autumn') {
  this.color = Math.random() > 0.5 ? '#f97316' : '#f59e0b'
} else if (theme === 'winter') {
  this.color = Math.random() > 0.5 ? '#94a3b8' : '#818cf8'
}

移动端也做了针对性优化——粒子数量减少到桌面端的约 1/3，并且关闭了粒子连线以节省性能。

2.2 CSS 几何裁剪与光晕渲染

面板卡片使用了 clip-path: polygon(...) 做几何裁剪，营造出机械装甲般的棱角感。背景层则通过大面积 blur-[150px] 的圆形色块模拟光晕效果，配合网格纹理背景，科幻氛围感十足。

.tech-card {
  background: linear-gradient(135deg, rgba(6, 18, 38, 0.8), rgba(2, 9, 26, 0.9));
  border: 1px solid rgba(59, 130, 246, 0.3);
  clip-path: polygon(0 15px, 15px 0, 100% 0, 100% calc(100% - 15px), calc(100% - 15px) 100%, 0 100%);
}

2.3 面板动画

左右面板的展开/收起使用了 Vue <transition> 配合 cubic-bezier 贝塞尔曲线，实现平滑的滑入滑出效果，视觉上非常流畅。

---

三、架构拆解：全栈工程化实践

3.1 技术栈全景

层级	技术选型
前端	Vue 3 (Composition API) + Pinia + Vite + Tailwind CSS v4 + Axios + Lucide Vue Next
后端	Python Flask (Blueprints 路由 + Service 层) + PyMySQL + Flask-CORS + Werkzeug
MCP 服务	FastMCP (Model Context Protocol) + 高德地图 Web API
数据库	MySQL 8.0+（含完整建表与 Mock 数据 SQL 脚本）
数字人	Fay 核心大脑 + 魔珐星云 XmovAvatar 3D SDK

3.2 前端架构

前端采用标准的 Vue 3 组合式 API + Pinia 状态管理模式，目录结构清晰：

src/
├── api/            # Axios 请求封装（config.js, fay.js, map.js, scenic.js）
├── components/     # 组件层
│   ├── admin/      # 管理后台组件
│   ├── common/     # 通用组件（ConfigPanel, Message, VersionModal）
│   ├── photo/      # AI 照相馆组件
│   └── scenic/     # 大屏三面板（LeftPanel, CenterPanel, RightPanel）
├── pages/          # 页面级组件
│   ├── admin/      # 管理端页面
│   ├── MobileScreen.vue    # 移动端独立页面
│   └── ScenicScreen.vue    # 桌面端大屏页面
├── stores/         # Pinia 状态管理（scenic.js, avatar.js）
├── router/         # Vue Router 路由配置
└── utils/          # 工具类（request.js, message.js, config-store.js）

几个值得注意的设计：

• 双页面架构：ScenicScreen.vue（桌面大屏）和 MobileScreen.vue（移动端）是完全独立的页面，而不是简单响应式适配，移动端有自己的 UI 交互逻辑
• Pinia 全局状态联动：scenic.js 管理景区数据，avatar.js 管理数字人状态，一处数据变更，多面板实时刷新
• Axios 拦截器封装：统一请求/响应处理，环境变量隔离

3.3 后端架构

后端采用 Flask 蓝图（Blueprints）路由分发 + Service 业务逻辑层的标准分层架构：

backend/app/
├── routes/         # 蓝图路由层
│   ├── config_routes.py     # 系统配置 API
│   ├── map_routes.py        # 地图服务 API
│   ├── scenic_info_routes.py # 景区信息 API
│   ├── spot_routes.py       # 景点 CRUD API
│   └── upload_routes.py     # 文件上传 API
├── services/       # 业务逻辑层
│   ├── config_service.py
│   ├── scenic_info_service.py
│   └── spot_service.py
└── utils/          # 工具层（db.py, response.py）

路由层只做参数校验和响应包装，业务逻辑全部下沉到 Service 层，代码职责清晰，方便后续维护和扩展。

---

四、核心功能深度解析

4.1 3D 数字人集成

项目的核心亮点之一是深度集成了魔珐星云（XmovAvatar）Web 3D 渲染 SDK。在 CenterPanel 组件中预留了中央全息展示舱，通过 avatar.js Store 管理 SDK 的生命周期：

• 初始化：avatarStore.initSDK() 启动 3D 渲染引擎
• 销毁：avatarStore.destroySDK() 释放资源
• 语音播报：avatarStore.speak(text, ...) 驱动数字人口型动画

结合 Fay 数字人核心大脑，用户可以通过 WebSocket 实时通信，数字人能够理解语音并以自然语言回复，同时驱动 3D 模型的口型和表情动画。

4.2 MCP 地图导航

这个功能是我觉得最有创意的部分。项目基于 Model Context Protocol（MCP） 协议构建了一个独立的地图导航微服务：

# mcp_server/main.py
# 基于 FastMCP 框架，集成高德地图 Web API
# 支持景区内任意两点之间的步行路线规划

工作流程：

1. 游客向数字人提问：“从这里到千年古刹怎么走？”
2. Fay 大脑解析意图，通过 MCP 协议调用导航工具
3. MCP 服务调用高德地图 API，计算步行路线
4. 返回导航指令和预计时间
5. 数字人语音播报 + 前端弹出地图展示路线

前端 MapModal 组件支持实时展示起终点坐标和路线，配合高德地图 SDK 渲染地图视图。

4.3 实时客流与舒适度联动

后端根据各景点的实时在园人数和最大承载量动态计算拥挤度等级（畅通/适中/拥挤），前端通过 Pinia Store 全局订阅，大屏的左面板（景点列表）、中面板（数字人区域）、右面板（数据面板）实时联动刷新。

这种"数据驱动 UI"的模式非常适合大屏展示场景，数据变化时不需要手动刷新，Pinia 的响应式机制会自动处理。

4.4 AI 穿越照相馆

移动端内置了 AI 照相馆功能（AIPhotoOverlay 组件），采用单屏三态流程设计：拍照 → 选择风格 → 生成 AI 穿越照片。这个功能为景区增加了互动娱乐性，游客可以生成古风、科幻风等主题照片。

4.5 管理后台

内置科幻风格的 AdminOverlay 管理控制台，功能完整：

• 景点列表 CRUD（增删改查）
• 景区基础信息维护
• 本地图片拖拽/点击上传（Flask 后端 UUID 命名 + 静态文件服务）
• 系统配置管理

---

五、移动端：不只是响应式

移动端体验是很多大屏项目的短板，但这个项目做了完全独立的移动端页面（MobileScreen.vue）。

移动端的核心功能包括：

1. 3D 数字人伴游：全屏展示数字人模型，底部控制栏提供麦克风、Fay 服务、定位、数字人开关、照相馆五大功能入口
2. 消息交互：底部输入框可直接向 Fay 发送文字消息，支持 WebSocket 实时接收回复
3. 地图定位导航：一键获取当前位置，数字人对话中自动识别路线意图并弹出地图
4. AI 照相馆：与桌面端共享 AIPhotoOverlay 组件
5. 性能优化：粒子数量减少、关闭粒子连线、背景模糊简化

底部控制栏的按钮设计也很有细节——每个按钮都是圆形图标 + 文字标签的经典移动端交互模式，激活态使用不同颜色区分（绿色=运行中、琥珀色=数字人运行中、青色=可操作）。

---

六、快速上手

6.1 环境准备

• Node.js 16+
• Python 3.8+
• MySQL 8.0+
• Fay 数字人服务（百度网盘下载，提取码 kxca）

6.2 三步启动

第一步：初始化数据库

mysql -u root -p < database/scenic_init.sql

第二步：配置环境变量

# 后端
cd backend && cp .env.example .env
# 修改 .env 中的 DB_PASSWORD

# 前端（根目录）
cp .env.example .env
# 填入魔珐星云 SDK 凭证

# MCP 服务
cd mcp_server && cp .env.example .env
# 填入高德地图 API Key

第三步：一键启动

Windows 用户直接运行：

.\scripts\start.bat

或手动分别启动前后端：

# 后端
cd backend && python -m venv venv && venv\Scripts\activate
pip install -r requirements.txt && python run.py

# 前端（新终端）
npm install && npm run dev

启动后访问 http://localhost:5173 即可看到大屏界面。

6.3 后端打包为 EXE

项目还提供了 PyInstaller 打包脚本，可以将后端打包为独立可执行文件：

scripts\build.bat

打包输出 backend\dist\scenic-backend.exe，无需 Python 环境即可运行，方便部署到展厅设备。

---

七、项目亮点总结

维度	评价
视觉设计	科幻级 UI，Canvas 粒子 + clip-path 裁剪 + 光晕渲染，Tailwind CSS v4 深色主题
功能完整度	大屏展示 + 管理后台 + 移动端 + MCP 导航 + AI 照相馆，功能链路完整
代码质量	前后端分层清晰，Vue 3 组合式 API + Flask Blueprint + Service 层
技术前沿性	集成 MCP 协议、3D 数字人 SDK、WebSocket 实时通信
上手难度	提供一键启动脚本和完整 SQL，环境变量模板齐全
扩展性	模块化设计，四季主题切换，蓝图路由方便新增 API

---

八、写在最后

Scenic Digital 是一个完成度很高的开源项目，不仅代码结构规范，UI 设计也非常用心。无论你是想找一个展厅大屏项目的起步模板，还是想学习 Vue 3 + Flask 全栈开发实践，或者对数字人和 MCP 协议感兴趣，这个项目都值得深入研究。

项目地址：

• Gitee：https://gitee.com/fay-community/scenic-digital

开源协议：MIT License，可自由使用和修改。

如果这个项目对你有帮助，欢迎 Star 支持，也欢迎加入社区交流群一起探讨。

---

本文参与开源项目推荐，项目代码和技术内容均来自开源社区，非商业推广。