From 244ffe8f31d42d96dc3622ad0d17aa357e4501cb Mon Sep 17 00:00:00 2001 From: Pine Date: Wed, 21 Oct 2026 17:57:46 +0800 Subject: [PATCH] =?UTF-8?q?docs(readme):=20=E5=AF=B9=E9=BD=90=20park-deskt?= =?UTF-8?q?op=20README=20=E8=87=B3=202026-10=20=E5=AE=9E=E7=8E=B0=E7=8E=B0?= =?UTF-8?q?=E7=8A=B6=EF=BC=88=E5=90=8E=E7=AB=AF=E5=B9=B6=E5=85=A5=20server?= =?UTF-8?q?-core=20/park=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 222 +++++++++++++++++------------------------------------- 1 file changed, 68 insertions(+), 154 deletions(-) diff --git a/README.md b/README.md index 29016bd..5def7bf 100644 --- a/README.md +++ b/README.md @@ -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 | **已废弃**的旧园区后端（源码已回退到统一入口，勿再使用） | ## 许可