OPC-Hub/park-desktop
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): 对齐 park-desktop README 至 2026-10 实现现状（后端并入 server-core /park）

Browse Source
This commit is contained in:
Pine
2026-10-21 17:57:46 +08:00
parent a2fbad8169
commit 244ffe8f31
1 changed files with 68 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+68 -154
View File
@@ -1,194 +1,108 @@
# 大屏媒体轮播系统 (DPM)
# 园区大屏（park-desktop / DPM）
**Digital Playback Media** — 基于 Tauri + React 的全屏媒体轮播控制系统，专为昆明市大学生创业园展播大屏设计。
> 核对：2026-10-19 · 依据 park-desktop `main@a2fbad8` · 以实现为准
## 概述
**DPM**（Digital Playback Media）—— 基于 **Tauri 2 + React 19** 的园区大屏客户端，为昆明市大学生创业园 OPC 运营中心提供数据大屏、数字孪生、AI 助手、媒体轮播、任务大屏与企业墙。
DPM 是一套完整的数字标牌（Digital Signage）解决方案，包含两大界面：
- **大屏展示页** (`/screen`) — 全屏自动轮播，支持视频与图片，具备沉浸式空间视觉背景
- **管理后台** (`/admin`) — 登录保护的管理面板，用于媒体上传、播放列表编排、播放控制与系统设置
系统通过 **SSE（Server-Sent Events）** 实现管理端与展示端的实时状态同步，支持局域网内远程管理。
> 园区后端已并入 **server-core `/park`**（不再有独立 `:10085` 后端）；管理后台为后端 **FastAPI + Jinja** 页面（`GET /admin`），**不由 React 路由接管**。实时控制走 **MQTT（EMQX `:8083`）**，不再使用内置 Axum HTTP 服务 / SSE / nps。
## 技术栈
| 层级 | 技术 |
|------|------|
| 前端框架 | React 19 + React Router 7 |
| 构建工具 | Vite 7 |
| 桌面框架 | Tauri 2 (Rust) |
| HTTP 服务 | Axum 0.8 (嵌入式 HTTP 服务器) |
| 数据持久化 | JSON 文件存储 |
| 实时通信 | Server-Sent Events (SSE) |
| 内网穿透 | nps 客户端嵌入式集成 |
| 构建工具 | Vite 7 + Tailwind 4.3（`@tailwindcss/vite`） |
| 桌面框架 | Tauri 2（Rust，`src-tauri/`，本地 `wry` 补丁） |
| 三维 / 可视化 | three 0.185（`@react-three/fiber` / `drei`）、`@appica/ui-react` |
| 实时通信 | MQTT 5.15（`mqtt.js`，EMQX） |
| 二维码 | `qrcode.react` |
## 功能特性
## 页面（`src/App.jsx`）
### 媒体管理
- **本地上传** — 支持 .mp4、.mkv、.avi、.jpg、.jpeg、.png 格式
- **远程 URL** — 添加网络媒体资源链接
- **媒体预览** — 图片与视频的模态框预览
- **文件删除** — 从媒体库移除文件
| 路由 | 页面 | 说明 |
|------|------|------|
| `/` | `DataScreen` | 园区数据大屏（概览/数据快照） |
| `/twin` | `DigitalTwin` | 数字孪生（3D 园区） |
| `/ai` | `AiAssistant` | 园区 AI 助手（含语音 s2s） |
| `/screen` | `MediaScreen` | 全屏媒体轮播（视频/图片，MQTT 受控） |
| `/tasks` | `TaskDisplay` | 任务大屏（轮播卡 + 二维码扫码接单） |
| `/wall` | `CompanyWall` | 入驻企业展示墙 |
### 播放控制
- **播放/暂停** — 实时控制展示端的播放状态
- **上一曲/下一曲** — 切换播放内容
- **顺序/随机播放** — 两种播放模式
- **图片时长可调** — 1~300 秒
- **音量控制** — 实时同步调节
- 统一页眉布局 `components/ScreenLayout`；`/voice` 有 `VoiceAssistant` 组件但**当前未挂路由**。
- 首启可走 **屏幕绑定**（`components/BindScreen` + `utils/tenant`，绑定后按租户拉数据）；支持双屏（`set_dual_screen`）、全屏、开机自启（`tauri-plugin-autostart`）、应用内自动更新（`components/UpdateNotify` + `utils/updateCheck`）。
### 展示端体验
- **沉浸式空间背景** — 深邃星空背景 + 透视网格 + 动态环境光晕
- **自动播放** — 启动后自动加载播放列表
- **视频/图片自适应** — 全屏覆盖显示
- **声音管理** — 浏览器自动播放策略处理
- **点击暂停/恢复** — 现场快速控制
## 功能概览
### 系统功能
- **全屏/窗口模式切换** — 自由切换展示形态
- **最小化窗口** — 后台运行
- **开机自启动** — 系统级自启（Tauri autostart 插件）
- **关闭 → 最小化** — 防止误关闭
- **内网穿透** — 内置 nps 客户端，支持外网远程访问
### 管理后台
- **登录保护** — 账号密码验证
- **实时状态显示** — 当前播放内容、状态
- **上传进度条** — 文件上传实时反馈
- **响应式设计** — 桌面/移动端自适应
- **Toast 通知** — 操作即时反馈
- **媒体轮播**（`pages/MediaScreen.jsx`）：视频/图片全屏轮播、沉浸式空间背景、自动播放、点击暂停/恢复、音量与顺序/随机播放、播放状态上报（`opc/display/*` MQTT 主题）。
- **任务大屏**（`pages/TaskDisplay.jsx`）：任务轮播卡 + 二维码扫码接单。
- **园区数据 / 数字孪生 / 企业墙**：数据快照（`opc/dashboard/tick`）、3D 园区、入驻企业展示。
- **AI 助手**：对话面板 + 语音 s2s（`src/voice/`）。
- **设备与运维**：屏幕绑定/租户隔离、心跳上报（`opc/display/heartbeat`，后端统计在线）、双屏、全屏、开机自启、自动更新。
- **管理后台**：媒体上传、播放列表编排与播放控制等由 **server-core `/park`** 的后端 `/admin` 页面提供（前端不再内置管理页）。
## 快速开始
### 环境要求
- **Rust** (edition 2021)
- **Node.js** >= 18
- **Yarn** 或 npm
- **Tauri CLI** (`cargo install tauri-cli`)
- **Rust**（edition 2021）、**Node.js** >= 18、**Yarn**（或 npm）、Tauri 2 CLI（`yarn tauri` 走本地依赖）
### 安装
### 安装与运行
```bash
# 安装前端依赖
yarn install
# 开发模式运行（同时启动 Vite 开发服务器和 Tauri 应用）
yarn tauri dev
# 仅启动 Web 开发服务器（浏览器中预览）
yarn dev
yarn dev # 仅启动 Vite（http://localhost:1420，浏览器预览大屏）
yarn tauri dev # Tauri 桌面端（前端 + Rust 壳）
yarn build # 前端产物 dist/
yarn tauri build # 桌面安装包，产物在 src-tauri/target/release/
```
### 构建生产版本
> ⚠️ 按团队铁律：**AI 不启动/重启任何服务（含 vite / Tauri）**，需要时通知用户亲自操作。
```bash
yarn tauri build
```
### 配置（`src/config.js`）
构建产物位于 `src-tauri/target/release/` 目录。
地址解析优先级：**exe 旁 `config.json`（Tauri `read_runtime_config`）> 后端 `/park/api/config` 下发 > 构建期 `VITE_*` > 内置默认**。
| 项 | 默认 | 覆盖方式 |
|----|------|---------|
| 园区 API | `http://<当前主机>:8090/park`（打包生产回退 `opc.pinesound.cn`） | `window.__DPM_API__`、`VITE_API_BASE` |
| MQTT | `ws(s)://<当前主机>:8083/mqtt`（生产 `wss`） | `window.__DPM_MQTT__`、`VITE_MQTT_URL` |
| 视频识别 | 空 = 禁用 | `window.__DPM_VISION__`、`VITE_VISION_API_BASE` |
| 大屏引导令牌 | 空 | `window.__DPM_BOOTSTRAP__`、`VITE_PARK_BOOTSTRAP_TOKEN` |
旧 `:10085` 地址一律判为失效并回退 server-core 统一入口。
## 项目结构
```
dpm/
├── index.html # HTML 入口
├── package.json # 前端依赖配置
├── vite.config.js # Vite 构建配置（API 代理到 :10801）
├── public/
│ └── npc.zip # 内网穿透客户端（嵌入二进制）
├── src/ # 前端源代码
│ ├── main.jsx # React 入口
│ ├── App.jsx # 路由配置（/admin, /screen）
│ ├── pages/
│ │ ├── Admin.jsx # 管理后台页面
│ │ └── Screen.jsx # 大屏展示页面
│ ├── utils/
│ │ └── api.js # API 封装（REST + SSE）
│ └── styles/
│ ├── tokens.css # CSS 基础重置
│ ├── admin.css # 管理后台样式
│ └── screen.css # 大屏展示样式
└── src-tauri/ # Rust 后端源代码
├── Cargo.toml # Rust 依赖配置
├── tauri.conf.json # Tauri 应用配置
├── capabilities/
│ └── default.json # Tauri 权限配置
└── src/
├── main.rs # 程序入口
├── lib.rs # 模块导出 + 启动逻辑
├── server.rs # Axum HTTP 服务器（路由 + 处理器）
├── models.rs # 数据模型（Settings, PlaybackState, etc.）
├── storage.rs # JSON 文件持久化存储
└── events.rs # SSE 事件广播管理器
index.html
package.json # 包名 dpm
vite.config.js # 端口 1420；无 dev 代理（API 由 src/config.js 直连 server-core）
public/ # logo、语音 worklets 等静态资源
src/
main.jsx # React 入口 + 运行时配置引导 + 致命错误兜底
App.jsx # 6 个大屏路由
config.js # API / MQTT / Vision / bootstrap 令牌解析
pages/ # DataScreen / DigitalTwin / AiAssistant / MediaScreen / TaskDisplay / CompanyWall
components/ # ScreenLayout / BindScreen / PageHeader / 各类面板、弹窗
utils/ # api.js、mqtt.js、tenant.js、taskData.js、updateCheck.js、pageNav.js、sounds.js
voice/ # s2s 语音客户端、orb 可视化、worklets
styles/ # tokens/global/datascreen/mediascreen/task-display 等
src-tauri/
Cargo.toml # tauri 2 + opener/autostart + 本地 wry 补丁
tauri.conf.json # productName「云超服昆创园OPC运营中心」，1200x800 全屏
capabilities/default.json # 窗口/自启/opener 权限
src/{main.rs,lib.rs} # 入口；命令：set_dual_screen / install_update / read_runtime_config
```
## API 参考
系统内置 HTTP 服务器监听 `0.0.0.0:10801`，提供以下 REST API：
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/login` | 管理员登录 |
| GET | `/api/settings` | 获取系统设置 |
| POST | `/api/settings` | 更新系统设置 |
| GET | `/api/playlist` | 获取播放列表（含音量/模式/时长） |
| POST | `/api/playlist/add` | 添加到播放列表 |
| POST | `/api/playlist/remove` | 从播放列表移除 |
| GET | `/media` | 获取所有媒体文件列表 |
| POST | `/upload` | 上传媒体文件（multipart） |
| POST | `/api/media/add-url` | 添加 URL 媒体 |
| POST | `/api/delete` | 删除媒体文件 |
| POST | `/api/control` | 播放控制（play/pause/next/prev） |
| GET | `/api/state` | 获取当前播放状态 |
| POST | `/api/state` | 更新播放状态 |
| GET | `/api/events` | SSE 实时事件流 |
| POST | `/api/display-command` | 显示命令（minimize 等） |
| GET | `/file/*` | 静态媒体文件服务 |
### 默认登录凭据
- **账号**: `admin`
- **密码**: `**********`
> 可通过编辑系统数据目录下的 `dpm/data.json` 修改。
### 数据存储位置
系统数据存储在操作系统标准数据目录下的 `dpm/` 文件夹中：
- **macOS**: `~/Library/Application Support/dpm/data.json`
- **Linux**: `~/.local/share/dpm/data.json`
- **Windows**: `C:\Users\<用户>\AppData\Roaming\dpm/data.json`
媒体文件存储在用户 `~/Downloads/Media/` 目录。
## 内网穿透
系统内置 [nps](https://github.com/ehang-io/nps) 客户端，自动从嵌入的 `public/npc.zip` 解压并启动，实现外网远程访问管理后台。
- 启动参数在 `server.rs` 中配置
- *仅支持 Windows*
- 自动设置 Unix 可执行权限
- 解压到系统数据目录 `dpm/npc/`
## 开发说明
### 端口
## 端口一览
| 端口 | 用途 |
|------|------|
| 10801 | 后端 HTTP API 服务器 |
| 1420 | Vite 前端开发服务器 |
### Vite 开发代理
开发模式下，Vite 自动将 `/api`、`/file`、`/media`、`/upload` 路径代理到 `localhost:10801`，前端无需关心跨域问题。
### 构建
前端构建产物（`dist/`）通过 `RustEmbed` 编译到 Rust 二进制中，发布时只需分发单个可执行文件。
| 1420 | Vite 前端开发服务器（`strictPort`） |
| 8090 | server-core（园区 API 前缀 `/park`） |
| 8083 | MQTT Broker（EMQX，`/mqtt`） |
| 10085 | **已废弃**的旧园区后端（源码已回退到统一入口，勿再使用） |
## 许可