DPM/README.md

# 大屏媒体轮播系统 (DPM)

**Digital Playback Media** — 基于 Tauri + React 的全屏媒体轮播控制系统，专为昆明市大学生创业园展播大屏设计。

## 概述

DPM 是一套完整的数字标牌（Digital Signage）解决方案，包含两大界面：

- **大屏展示页** (`/screen`) — 全屏自动轮播，支持视频与图片，具备沉浸式空间视觉背景
- **管理后台** (`/admin`) — 登录保护的管理面板，用于媒体上传、播放列表编排、播放控制与系统设置

系统通过 **SSE（Server-Sent Events）** 实现管理端与展示端的实时状态同步，支持局域网内远程管理。

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端框架 | React 19 + React Router 7 |
| 构建工具 | Vite 7 |
| 桌面框架 | Tauri 2 (Rust) |
| HTTP 服务 | Axum 0.8 (嵌入式 HTTP 服务器) |
| 数据持久化 | JSON 文件存储 |
| 实时通信 | Server-Sent Events (SSE) |
| 内网穿透 | nps 客户端嵌入式集成 |

## 功能特性

### 媒体管理
- **本地上传** — 支持 .mp4、.mkv、.avi、.jpg、.jpeg、.png 格式
- **远程 URL** — 添加网络媒体资源链接
- **媒体预览** — 图片与视频的模态框预览
- **文件删除** — 从媒体库移除文件

### 播放控制
- **播放/暂停** — 实时控制展示端的播放状态
- **上一曲/下一曲** — 切换播放内容
- **顺序/随机播放** — 两种播放模式
- **图片时长可调** — 1~300 秒
- **音量控制** — 实时同步调节

### 展示端体验
- **沉浸式空间背景** — 深邃星空背景 + 透视网格 + 动态环境光晕
- **自动播放** — 启动后自动加载播放列表
- **视频/图片自适应** — 全屏覆盖显示
- **声音管理** — 浏览器自动播放策略处理
- **点击暂停/恢复** — 现场快速控制

### 系统功能
- **全屏/窗口模式切换** — 自由切换展示形态
- **最小化窗口** — 后台运行
- **开机自启动** — 系统级自启（Tauri autostart 插件）
- **关闭 → 最小化** — 防止误关闭
- **内网穿透** — 内置 nps 客户端，支持外网远程访问

### 管理后台
- **登录保护** — 账号密码验证
- **实时状态显示** — 当前播放内容、状态
- **上传进度条** — 文件上传实时反馈
- **响应式设计** — 桌面/移动端自适应
- **Toast 通知** — 操作即时反馈

## 快速开始

### 环境要求

- **Rust** (edition 2021)
- **Node.js** >= 18
- **Yarn** 或 npm
- **Tauri CLI** (`cargo install tauri-cli`)

### 安装

```bash
# 安装前端依赖
yarn install

# 开发模式运行（同时启动 Vite 开发服务器和 Tauri 应用）
yarn tauri dev

# 仅启动 Web 开发服务器（浏览器中预览）
yarn dev
```

### 构建生产版本

```bash
yarn tauri build
```

构建产物位于 `src-tauri/target/release/` 目录。

## 项目结构

```
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 事件广播管理器
```

## 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 二进制中，发布时只需分发单个可执行文件。

## 许可

本项目为昆明市大学生创业园公益定制开发。

---

*云南派音人工智能科技提供技术支持*