DPM/README.md

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

> 📍 工作区位置：`code/dpm/`（独立仓库）。系统/运维文档见 `design/dpm/`；权威后端说明见 `backend/README.md`；整体目录规范见根 `CLAUDE.md`。

**Digital Playback Media** — 园区大屏展播控制系统，服务昆明市大学生创业园：数据大屏、数字孪生 3D、AI 助手、语音助手、媒体轮播、企业展示墙，浏览器后台可远程控制。

## 架构总览

```
┌──────────────┐   REST（全部数据/媒体/设置）   ┌────────────────┐
│  Tauri 大屏    │ ◄────────────────────────── │  FastAPI :10085 │
│  (React 前端)  │                             └───────┬────────┘
│               │  MQTT 订阅 opc/display/command       │ MQTT 发布
│   账号: dpm    │ ◄────────────────────────────────────│ 账号: dpmserver
└──────┬───────┘          MQTT Broker (EMQX)           │
       │                     192.168.1.3:1883          │
       └───────────────────────────────────────────────┘
```

- **数据 / 媒体 / 设置** → REST API（FastAPI，JSON 文件持久化）
- **页面与媒体控制** → MQTT（EMQX broker），按 `clientId` 定向下发；SSE `/api/events` 作回退
- **桌面壳** → Tauri 2（Rust），仅负责窗口生命周期与 3 个命令（读运行配置、双屏、安装更新）
- **管理后台** → FastAPI + Jinja 渲染的 `/admin` 页面（非 React 路由）

> **权威说明以 `backend/README.md` 为准**，含全部接口、MQTT 主题、环境变量与 Docker 部署。

## 目录

| 路径 | 说明 |
|------|------|
| `backend/` | **后端**：FastAPI（uv 管理），`:10085`；`app/` 内含全部 REST、MQTT、模拟引擎、AI/语音/RAG、手势识别。 |
| `src/` | **前端**：React 19 + Vite + Tailwind + three.js + MQTT + Tauri API。路由 `/`（数据）、`/twin`（孪生）、`/ai`、`/screen`（媒体）、`/voice`、`/wall`。 |
| `src-tauri/` | Tauri 2 桌面壳（Rust）。 |
| `docs/` | 部署 / 更新 / 语音 / MQTT 手册 / ESP32。 |
| `public/` | 静态资源。 |
| `数据资料/` | 园区本地数据资料（不入库）。 |

## 快速开始

### 前端（vite）

```bash
yarn dev            # Vite 开发服务器 :1420
yarn build          # 构建 dist/
```

### 后端（uv）

```bash
cd backend
uv sync
cp .env.example .env   # 按需填 DashScope Key、MQTT 账号
uv run python main.py  # 监听 0.0.0.0:10085
```

### Docker 部署（后端 + EMQX，推荐）

```bash
export MQTT_PUBLIC_HOST=192.168.1.50   # 展播端可访问的服务器局域网 IP
export DASHSCOPE_API_KEY=sk-xxx        # 未配置时 AI 走本地规则引擎
docker compose up -d --build
curl http://<服务器IP>:10085/api/health
```

端口：`10085`（API/后台/媒体）、`8765`（s2s 语音）、`1883/8083/18083`（EMQX）。数据卷 `dpm_media` / `dpm_knowledge` / `dpm_data`。

## 关键约定

- **进程管理**：见 `AGENTS.md` —— AI 禁止启动/重启/停止任何服务（后端 :10085 / s2s :8765 / vite :1420 / Tauri）。
- **凭据**：`backend/.env` 与根 `.env.local`（`VITE_*` 前缀）含阿里云密钥与 MQTT 凭据，不入库。
- **前端连接配置**：`.env.local` 中 `VITE_API_BASE` / `VITE_MQTT_URL` / `VITE_MQTT_USERNAME` / `VITE_MQTT_PASSWORD`；运行时优先级：exe 旁 `config.json` > 后端 `/api/config` > 内置默认 IP。

## 项目结构（源码）

```
dpm/
├── package.json / vite.config.js
├── src/                      # 前端（React 19）
│   ├── main.jsx              # 入口：读 Tauri 运行配置 + /api/config
│   ├── App.jsx               # 路由（/ /twin /ai /screen /voice /wall）
│   ├── pages/                # 六大屏页面
│   ├── components/           # Building3D、AiChatPanel、GlobalVision 等
│   ├── voice/                # 实时语音栈（s2s-ws-client、worklets）
│   └── utils/                # mqtt、useMqttControl、updateCheck、statusBus
├── backend/
│   ├── main.py               # 启动入口（prepare_env → uvicorn）
│   └── app/                  # config/routers/mqtt/sim_engine/storage/llm/...
└── src-tauri/                # Tauri 2（Rust）
```

## 许可

昆明市大学生创业园公益定制开发，*云南派音人工智能科技提供技术支持*。