# mht-ui-admin-vben

**Repository Path**: bright-source-intelligence_0/mht-ui-admin-vben

## Basic Information

- **Project Name**: mht-ui-admin-vben
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 2
- **Created**: 2026-09-24
- **Last Updated**: 2026-10-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 铭灏天物联网平台 · 前端

基于 Vue 3 和 Vben Admin 的通用物联网管理平台，配套 `smart-lighting` 后端，覆盖设备接入、产品与物模型、项目区域布点、运行规则、告警、视频监控，以及大屏和组态设计。智能照明是当前业务场景之一，产品模型、项目目录和可视化组件也可用于暖通、能耗等场景的扩展。

当前业务主应用为 **`apps/web-antdv-next`**。本仓库保留了多套 UI 应用和上游业务页面，具体可用菜单由后端权限配置决定；其他应用与主应用的业务更新进度可能不同。

## 系统能力

| 能力域 | 当前代码提供的能力 |
| --- | --- |
| 物联网总览 | 设备数量、在线状态、设备分布、消息趋势等概览，结合后端统计接口展示运行情况。 |
| 产品与物模型 | 产品分类、产品管理、设备类型与协议配置；定义属性、服务和事件，编辑数据规格、输入输出参数，查看物模型 TSL JSON。 |
| 设备全生命周期 | 设备注册与导入、卡片/列表、设备分组、网关与子设备管理；设备详情包含基础信息、最新属性、历史曲线、消息、配置、Topic 和模拟设备入口。 |
| 协议配置与控制 | 管理产品接入协议、Modbus 连接和点表；通过物模型进行属性设置、服务调用，结合后端适配器完成设备通信。具体收发能力以对应适配器和设备为准。 |
| 项目与区域 | 项目维护、负责人和部门信息、真实设备统计、区域树、区域图纸、设备规划、项目与设备关联；详情包含指标概览、区域管理、设备分组、场景管理、设备规划五个页签，支持图纸缩放、点位编辑、批量选择及现场身份补录。 |
| 项目设备分组与控制 | 在项目内跨区域组织设备分组，选择整组、区域或部分成员进行控制预检，提交控制任务并查看逐设备结果及历史记录。照明专项适配与真实执行确认仍需按设备协议验收。 |
| 场景与数据规则 | IoT 场景联动、触发条件和动作、数据流转规则与目的地；项目场景配置、范围预览、重复日历和策略模板。实际调度与设备执行由后端和网关完成。 |
| 告警与升级 | 告警配置、告警记录与处理备注；固件库、OTA 升级任务、任务详情及逐设备升级记录。 |
| 视频中心 | 流媒体服务、SIP 信令管理、监控设备接入配置、通道管理、URL 拉流、国标目录同步、直播与分屏；已有国标录像查询、单路回放及播放控制入口。媒体能力依赖网关、ZLMediaKit 和设备。 |
| 可视化大屏与组态 | 空间和页面管理、模板与素材、组件库、图层、属性面板；拖拽、连线、对齐分布、组合锁定、撤销重做、JSON 导入导出；支持图表、仪表、状态、设备、泵阀和管线等组件。 |
| 数据绑定与发布 | 静态/API/IoT 数据源、字段映射与转换、WebSocket 实时数据；草稿、发布预检、发布快照、历史版本、运行页面及公开令牌访问。公开运行数据与登录后的控制权限分别校验。 |
| 系统管理与开发支撑 | 用户、角色、菜单、部门、岗位、租户、字典、通知及日志；文件管理、配置、定时任务、代码生成等管理入口，配合后端 RBAC 和数据权限使用。 |

### 使用边界

- 上表说明当前代码覆盖的业务范围，不代表所有协议、硬件、部署环境均已完成端到端验收。控制接口受理、消息发送、设备应答和实际执行确认需要分别判断。
- 视频已具备国标接入、直播和设备录像回放代码。后端已提供录像任务、归档和私有文件接口，独立录像管理页面及完整前端流程尚待完善；ONVIF 完整接入、云台/对讲和多路同步回放仍按各自需求文档推进。
- 可视化编辑能力与真实数据能力需要分别配置。不能仅凭画布中的统计选项就认定后端具备任意指标、任意时间范围的聚合能力。
- `artifacts/`、`work/` 以及明确标记为 Demo 的页面包含设计演示或联调材料；演示数据和交互不作为生产功能验收依据。
- 仓库还保留 CRM、ERP、商城、支付、工作流、AI 等扩展页面。当前配套后端只装配实际启用的模块，这些目录不表示相关完整系统已经交付。

## 前后端架构

前端负责页面、交互、状态和 API 调用；后端负责业务校验、租户与权限、数据持久化、任务及设备消息处理。IoT 网关独立承载协议接入，视频链路按需连接流媒体服务。

```mermaid
flowchart LR
    Browser[浏览器] --> Web[Vue / Vben 前端]
    Web -->|HTTP / admin-api| Server[smart-lighting 管理服务]
    Web <-->|WebSocket| Server
    Server --> Modules[系统 / 基础设施 / 项目 / IoT / 可视化]
    Modules --> Storage[MySQL / Redis / TDengine]
    Modules <--> Gateway[IoT 网关]
    Gateway <--> Devices[现场设备]
    Gateway <--> Media[ZLMediaKit 视频服务]
```

建议在本地使用相邻目录，便于查阅前后端文档：

```text
workspace/
├─ mht-ui-admin-vben/       # 本仓库：前端 monorepo
└─ smart-lighting/          # 配套后端：管理服务、IoT 网关及数据库脚本
```

后端的环境变量、数据库初始化、迁移、网关及启动方式见 [后端 README](../smart-lighting/README.md)。

## 技术栈

| 层次 | 技术 |
| --- | --- |
| 应用框架 | Vue 3、TypeScript、Vben Admin |
| 主应用 UI | antdv-next、Vben 公共组件、VXE Table |
| 路由与状态 | Vue Router、Pinia；后端动态菜单与权限 |
| 请求与实时数据 | Axios / `@vben/request`、WebSocket、VueUse |
| 图表与组态 | ECharts、AntV X6、可扩展组件注册与属性面板 |
| 样式与国际化 | Tailwind CSS、Sass、Vue I18n |
| 工程化 | pnpm workspace、Turborepo、Vite、Vitest、ESLint、oxlint、oxfmt |
| 配套后端 | Java 17、Spring Boot、MyBatis Plus、MySQL、Redis、TDengine；详见后端 README |

依赖版本以根目录 `package.json`、`pnpm-workspace.yaml` 和锁文件为准。

## 目录说明

```text
mht-ui-admin-vben/
├─ apps/
│  ├─ web-antdv-next/       # 当前业务主应用
│  │  ├─ src/api/          # 认证、系统、IoT、项目、可视化等类型与 API
│  │  ├─ src/router/       # 基础路由、权限路由和详情页路由
│  │  ├─ src/store/        # 应用状态与登录状态
│  │  ├─ src/components/   # 应用公共组件
│  │  └─ src/views/
│  │     ├─ iot/          # 产品、物模型、设备、规则、告警、OTA、视频
│  │     ├─ bizmeta/      # 项目、区域、设备分组、场景与策略模板
│  │     ├─ visual/       # 可视化管理、设计器、运行态和素材
│  │     ├─ system/       # 用户、角色、菜单、租户等
│  │     └─ infra/        # 文件、配置、任务、日志等
│  ├─ web-antd/           # Ant Design Vue 应用
│  ├─ web-ele/            # Element Plus 应用
│  ├─ web-naive/          # Naive UI 应用
│  └─ web-tdesign/        # TDesign 应用
├─ packages/              # Vben 核心、公共 UI、请求、权限、状态、国际化等
├─ internal/              # Vite、TypeScript、样式和代码检查配置
├─ design-plans/          # 各功能产品规格、实施与验证文档
├─ docs/                  # 框架及组件文档
├─ scripts/               # 工程工具与部署参考
├─ artifacts/             # 原型和视觉演示材料
└─ work/                  # 调研、导入、联调及部署参考材料
```

## 本地开发

### 1. 环境要求

- Node.js：`^22.18.0` 或 `^24.12.0`，当前 `.node-version` 为 `24.16.0`。
- pnpm：`>=11.0.0`，项目固定使用 `pnpm@11.16.0`，建议保持一致。
- 配套后端及其 MySQL、Redis、TDengine / taosAdapter 已由开发者准备好。当前启用 IoT 的后端会在启动时初始化 TDengine 表，时序库也是启动依赖。设备通信还需相应 IoT 网关，视频功能还需配置流媒体服务和设备。

前后端服务由开发者手动启动、停止和重启。以下命令是操作说明。

### 2. 安装依赖

在本仓库根目录执行：

```powershell
corepack enable
corepack install
pnpm install --frozen-lockfile
```

若当前 Node.js 环境没有 Corepack，可先自行安装 Corepack，或直接安装项目指定版本的 pnpm。请使用 pnpm，保留仓库锁文件。

### 3. 配置主应用

应用已包含 `.env`、`.env.development` 和 `.env.production`。本机差异建议写入已被 Git 忽略的 `apps/web-antdv-next/.env.development.local`：

```dotenv
VITE_PORT=5999
VITE_BASE=/
VITE_BASE_URL=http://127.0.0.1:48080
VITE_GLOB_API_URL=/admin-api
VITE_UPLOAD_TYPE=server
VITE_NITRO_MOCK=false
VITE_APP_TENANT_ENABLE=true
VITE_APP_CAPTCHA_ENABLE=false
```

| 配置项 | 作用 |
| --- | --- |
| `VITE_PORT` | 开发页面端口，当前默认 `5999`。 |
| `VITE_GLOB_API_URL` | HTTP API 基址；开发时 `/admin-api` 通过 Vite 代理转发。 |
| `VITE_BASE_URL` | 后端基础地址；可视化运行态用它生成 WebSocket 地址，须对浏览器可达。 |
| `VITE_PROXY_TARGET` | Vite 配置从进程环境读取的代理目标，默认 `http://localhost:48080/admin-api`；包含 `/admin-api` 前缀。 |
| `VITE_APP_TENANT_ENABLE` | 租户交互开关，应与后端租户配置一致。 |
| `VITE_APP_CAPTCHA_ENABLE` | 验证码开关，应与后端一致；生产配置当前启用验证码。 |
| `VITE_UPLOAD_TYPE` | `server` 经后端上传；`client` 为前端直传，当前仅支持 S3 服务。 |

API 加解密配置也需与后端一致。登录账号由后端初始化数据和管理员维护，前端默认填充值不代表数据库中一定存在该账号。

### 4. 手动启动

先按后端 README 完成初始化并启动需要的服务，再在本仓库执行：

```powershell
pnpm dev:antdv-next
```

默认访问 [本地管理页面](http://localhost:5999)。端口被占用时，以终端实际输出为准。

若后端不在默认地址，需同时调整 HTTP 代理和 `VITE_BASE_URL`。例如在启动前设置代理目标：

```powershell
$env:VITE_PROXY_TARGET = 'http://127.0.0.1:48080/admin-api'
pnpm dev:antdv-next
```

其他 UI 应用可分别使用 `pnpm dev:antd`、`pnpm dev:ele`、`pnpm dev:naive`、`pnpm dev:tdesign` 启动。它们有各自的环境配置，切换前应核对业务支持范围。

## 接口与权限约定

- 管理接口通常位于 `/admin-api` 下，前端请求实现见 `apps/web-antdv-next/src/api/`。
- 登录使用 `/admin-api/system/auth/login`；认证请求携带 `Authorization: Bearer <accessToken>`，客户端处理令牌刷新和登录失效。
- 启用租户时，请求客户端按登录上下文携带 `tenant-id` 和 `visit-tenant-id`。租户隔离、业务权限和数据权限由后端最终校验。
- 常规 JSON 响应采用 `{ code, data, msg }`，`code = 0` 为成功；下载和流式接口按各自契约处理。
- 菜单采用后端权限模式。页面文件存在但没有菜单时，应核对后端菜单、组件路径、角色及权限初始化。
- 可视化实时数据需要 WebSocket。登录运行态使用 `/infra/ws`；公开运行态先向后端申请短期票据，再按返回路径连接。

## 构建与部署

构建主应用：

```powershell
pnpm build:antdv-next
```

产物位于 `apps/web-antdv-next/dist/`。生产参数通过 `.env.production` 或本地覆盖文件 `.env.production.local` 配置，部署前重点核对：

1. `VITE_GLOB_API_URL` 指向实际管理 API，不能沿用开发机回环地址。
2. `VITE_BASE_URL` 指向浏览器可访问的后端或同源反向代理入口；HTTPS 页面应配套 HTTPS / WSS。
3. 反向代理同时转发管理 API、WebSocket 和需要的文件访问路径；WebSocket 需配置连接升级。
4. 路由模式默认使用生产配置中的 `hash`；改为 history 模式时配置页面回退，部署子路径时同步设置 `VITE_BASE`。
5. 部署主应用的 `dist/`，并核对验证码、上传、API 加解密以及视频网络配置。

`scripts/deploy/` 提供上游部署参考，当前 Dockerfile 仍复制 `playground/dist`，不能直接作为本业务主应用的交付镜像；使用前需按实际应用调整构建产物和代理配置。

## 开发与验证

| 目的             | 命令                                           |
| ---------------- | ---------------------------------------------- |
| 主应用类型检查   | `pnpm --filter @vben/web-antdv-next typecheck` |
| 主应用生产构建   | `pnpm build:antdv-next`                        |
| 指定现有单元测试 | `pnpm test:unit <测试文件路径>`                |
| README 格式检查  | `pnpm exec oxfmt --check README.md`            |
| 全仓代码检查     | `pnpm lint`                                    |
| 全仓组合检查     | `pnpm check`                                   |

按修改风险选择检查，在一组连贯修改完成后集中执行。文档和局部样式通常只需差异与格式检查；业务功能应覆盖相关类型、逻辑和接口；跨模块或交付节点再扩大检查范围。依赖运行中服务的联调应使用开发者已启动的环境。

新增功能先查阅相关 `design-plans/<功能>/Product-Spec.md`。表单复用右侧 Drawer；卡片/列表切换采用有 Tooltip 和可访问名称的图标按钮；上传选择与图片操作集成在上传框内。完整协作规范见 [AGENTS.md](AGENTS.md)。

## 相关文档

- [配套后端 README](../smart-lighting/README.md)
- [通用物联网交付平台需求](design-plans/iot-platform-v2/Product-Spec.md)
- [现有系统能力与通用化增量基线](design-plans/universal-iot-platform/Product-Spec.md)
- [项目设备分组与控制](design-plans/project-device-control/Product-Spec.md)
- [视频接入与能力边界](design-plans/camera-video-access/Product-Spec.md)
- [录像管理规划](design-plans/video-recording-management/Product-Spec.md)
- [可视化发布完整性](design-plans/visual-publication-integrity/Product-Spec.md)

## 许可证

本仓库基于 Vben Admin，采用 [MIT License](LICENSE)。使用和分发时保留原有版权与许可声明。