# device-tree

**Repository Path**: pg_apps/device-tree

## Basic Information

- **Project Name**: device-tree
- **Description**: 设备树满足多种逻辑的设备树
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-03
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 设备树管理平台

> 版本 **3.0.0** ｜ 后端 Java 17 + Spring Boot 3.5 ｜ 前端 Vue 3 + Vite 6 + Element Plus

面向工业设备台账与设备树管理的展示型项目：支持设备树、工艺/监测系统、设备类型与参数模板、
设备参数、设备图片/图纸、备品备件、设备标签、摄像头关联、监测点位与点位权限。

> [!IMPORTANT]
> 本项目只保留设备树业务。**登录、权限与租户由外部系统负责**，仓库内不包含 RBAC、登录、
> 租户管理与操作日志实现；前端使用假登录与写死路由，方便直接查看页面。
>
> **版权与授权**：本项目仅供**个人学习、研究**使用，**禁止任何形式的商业用途**。
> 如需商用，请先联系 **pg_tech@163.com** 获取书面授权。完整条款见 [LICENSE.md](./LICENSE.md)。

---

## 功能特性

| 模块 | 能力 |
|---|---|
| 设备树 | 工艺系统 → 设备层级树、子设备、设备详情、按位号/名称搜索、设备照片与图纸 |
| 设备类型 | 类型维护、参数模板维护、Excel 导入导出；新增/切换类型时按模板生成参数 |
| 工艺/监测系统 | EDIS 工艺系统、监测系统维护；删除前检查设备/类型/点位引用 |
| 设备参数 | 设备参数实例编辑、宽表导入导出、按类型模板重建并保留同名参数值 |
| 备品备件 | 设备备件台账、Excel 导入导出、资产编号租户内唯一 |
| 设备标签 | 标签维护、设备多标签关联 |
| 摄像头 | 显式 `is_camera` 标记、设备-摄像头关联、删除引用检查 |
| 监测点位 | 点位维护、点位参数（实时库映射）、Excel 导入导出 |
| 点位权限 | 权限模板 → 点位集合，角色 → 模板集合（角色 ID 由外部权限系统提供） |
| 文件上传 | 本地磁盘存储，按日期/UUID 命名，供设备照片与图纸引用 |

## 技术栈

| 分类 | 组件 |
|---|---|
| 后端 | Java 17、Spring Boot 3.5.16、Undertow |
| 持久层 | MyBatis-Plus 3.5.9（分页 + 乐观锁拦截器）、MySQL 8.x、Druid |
| Excel | EasyExcel 3.3.4 |
| 接口文档 | SpringDoc OpenAPI 3 + Knife4j |
| 前端 | Vue 3.5、Vite 6、TypeScript 5.7、Element Plus 2.9、Pinia、Vue Router |
| 公共返回结构 | 外部 `io.github.na-tool:na-common`（Result / R / 分页基类） |

## 系统架构

```text
浏览器 / H5
   │  /api/na-upms/**、/na-upms/files/**
   ▼
Nginx（生产）或 Vite 代理（开发）
   │
   ▼
na-upms :10061  ──直连──▶  MySQL（device_tree）
```

- 后端只有一个 Maven 模块 `na-upms`。
- 所有 Controller 统一使用 `/api/na-upms/**` 前缀。
- 本项目不连接 Redis，不启动 WebSocket，不做登录态校验。
- 数据表保留 `tenant_id` 字段（默认 0），便于后续接入外部租户体系。

## 目录结构

```text
device-tree/
├── pom.xml                     # 父 POM，仅聚合 na-upms
├── na-upms/
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/na/
│       │   ├── admin/          # Controller / Service / VO / Excel / 配置
│       │   ├── common/         # 通用返回结构扩展
│       │   ├── core/           # Mapper
│       │   ├── entity/         # 16 张 dev_* 实体
│       │   └── params/         # 设备查询参数
│       └── resources/
│           ├── application.yml
│           ├── logback-spring.xml
│           └── mapper/mysql/   # 设备 Mapper XML
├── web/                        # Vue 3 前端（假登录 + 静态路由）
├── doc/
│   ├── device_tree.sql         # 设备表初始化脚本
│   ├── usage-guide.md          # 配置顺序与使用流程
│   └── nginx-direct.conf
└── README.md
```

## 快速开始

### 1. 初始化数据库

在 MySQL 8.x 中执行：

```bash
mysql -uroot -p < doc/device_tree.sql
```

脚本会：

- 创建数据库 `device_tree`；
- 创建 16 张 `dev_*` 设备业务表；
- 写入示例工艺系统、监测系统、设备类型、参数模板、设备树、点位、权限模板等演示数据。

> 脚本包含 `DROP TABLE IF EXISTS`，请勿直接在生产库执行。

### 2. 启动后端

默认连接本机 MySQL，可用环境变量覆盖：

| 环境变量 | 默认值 | 说明 |
|---|---|---|
| `MYSQL_HOST` | `127.0.0.1` | MySQL 地址 |
| `MYSQL_PORT` | `3306` | MySQL 端口 |
| `MYSQL_DATABASE` | `device_tree` | 数据库名 |
| `MYSQL_USERNAME` | `root` | 数据库账号 |
| `MYSQL_PASSWORD` | `123456` | 数据库密码 |

```bash
mvn clean package -DskipTests
java -jar na-upms/target/na-upms.jar
```

启动后：

- 服务端口：`10061`
- 接口文档：`http://localhost:10061/doc.html`
- Druid 监控：`http://localhost:10061/druid/`（默认 `admin / 123456`）

### 3. 启动前端

```bash
cd web
npm install
npm run dev
```

开发地址 `http://localhost:5173`，Vite 会把 `/api/na-upms` 与 `/na-upms` 代理到 `http://localhost:10061`。

> 登录页为演示登录：账号、密码可任意填写，不请求后端认证。

生产构建：

```bash
npm run build
```

构建产物在 `web/dist`，由 Nginx 托管。

## 设备数据模型

| 表 | 说明 |
|---|---|
| `dev_edis_system` | 工艺系统（EDIS） |
| `dev_mon_sys` | 监测系统 |
| `dev_device_type` | 设备类型 |
| `dev_param_template` | 设备参数模板 |
| `dev_device_tree` | 设备树（自关联 parent_id，`is_camera` 标记摄像头） |
| `dev_device_param` | 设备参数实例 |
| `dev_device_image` | 设备照片 / 图纸文档 |
| `dev_device_tag` | 设备标签 |
| `dev_device_tag_rel` | 设备-标签关联 |
| `dev_device_camera` | 设备-摄像头关联 |
| `dev_device_sparepart` | 备品备件 |
| `dev_mon_point` | 监测点位 |
| `dev_point_param` | 点位参数（实时库映射） |
| `dev_jur_template` | 点位权限模板 |
| `dev_jur_template_point` | 模板-点位关联 |
| `dev_jur_role_template` | 角色-模板关联（角色 ID 来自外部权限系统） |

关键规则：

- 设备位号 / 旧位号 / 设备号租户内唯一，可选字段空白存 `NULL`。
- 设备类型变更时按模板重建参数，同名参数保留旧值。
- 工艺系统变更时同步更新所有子孙设备。
- 删除设备前检查子设备与摄像头引用，并级联清理参数/图片记录/备件/点位等。
- 设备域采用物理删除。

## 前端页面

| 路径 | 页面 |
|---|---|
| `/login` | 演示登录（任意账号密码） |
| `/deviceTree` | 设备树（左侧树 + 右侧详情/参数/图片/备件/点位） |
| `/deviceType` | 设备类型与参数模板 |
| `/deviceSystem` | 工艺系统 / 监测系统 |
| `/deviceTag` | 设备标签 |
| `/devicePoint` | 监测点位 |
| `/devicePermission` | 点位权限模板与角色绑定 |

路由全部写死在 `web/src/router/routes.ts`，侧边栏菜单来自同文件的 `staticMenus`。

完整的配置顺序、各页面必填字段与批量导入顺序见 [`doc/usage-guide.md`](./doc/usage-guide.md)。

## Excel 导入导出

| 功能 | 接口 |
|---|---|
| 设备多 Sheet 导入 | `POST /api/na-upms/device-tree/import` |
| 设备批量更新 | `POST /api/na-upms/device-tree/import/update` |
| 设备台账导出 | `GET /api/na-upms/device-tree/export` |
| 设备参数导入/导出 | `/device-tree/param/import`、`/device-tree/param/export` |
| 参数模板导入/导出 | `/device-type/template/import`、`/device-type/template/export` |
| 点位导入/导出 | `/device-point/import`、`/device-point/export` |
| 备件导入/导出 | `/device-sparepart/import`、`/device-sparepart/export` |

导入失败会整体回滚，并返回带 Sheet / 行号的错误列表。单次导入上限 5000 行。

## 已知限制

1. 仓库内不实现登录、权限、租户与操作日志，统一由外部系统负责。
2. 前端为演示登录，任意账号密码均可进入。
3. 设备表保留 `tenant_id` 字段但当前固定为 0。
4. 静态文件 URL 不做访问鉴权，依靠 UUID + 目录隔离。
5. 密码、Token 等认证数据不在本仓库中存储。

## 版权声明

版权所有 © 2025-2026 pg_tech。保留所有权利。

本项目仅供个人学习、研究使用，禁止任何形式的商业用途。完整条款见 [LICENSE.md](./LICENSE.md)。