# smart-park

**Repository Path**: wdb123/smart-park

## Basic Information

- **Project Name**: smart-park
- **Description**: 智慧园区（基于Qoder开发的全栈3D项目）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-05-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Smart Park —— 数字孪生智慧园区管理系统

基于 **NestJS + Vue 3 + Three.js** 的数字孪生智慧园区管理平台，支持园区的 3D 可视化展示与后台数据管理。

## 项目结构

```
smart-park/
├── server/          # 后端服务 (NestJS)
├── web-3d/          # 3D 可视化前端 (Vue 3 + Three.js)
├── web-admin/       # 管理后台前端 (Vue 3 + Element Plus)
└── .gitignore
```

---

## 子项目概览

### 1. server —— 后端 API 服务

基于 **NestJS** 框架构建的 RESTful API 服务，提供认证鉴权与数据管理能力。

| 技术 | 说明 |
|------|------|
| 框架 | NestJS 11 |
| 数据库 | SQLite (better-sqlite3 + TypeORM) |
| 认证 | JWT + Passport |
| 密码加密 | bcrypt |
| 数据校验 | class-validator / class-transformer |

**核心模块：**

| 模块 | 说明 |
|------|------|
| AuthModule | 用户登录认证、JWT 签发与策略、角色守卫 |
| UsersModule | 用户 CRUD，首次启动自动创建管理员账号 (admin/admin123) 和编辑者账号 (editor/editor123) |
| BuildingsModule | 园区建筑管理（名称、类型、状态、坐标、缩放、模型路径等） |
| BuildingPartsModule | 建筑部件管理，关联所属建筑（名称、类型、状态、Mesh 映射等） |
| CampusConfigModule | 园区全局配置键值对管理 |

**端口：** `http://localhost:3000`  
**API 前缀：** `/api`

---

### 2. web-3d —— 3D 数字孪生可视化

基于 **Vue 3 + Three.js + Element Plus + TailwindCSS** 构建的园区 3D 可视化前端，支持场景漫游与建筑交互。

| 技术 | 说明 |
|------|------|
| 框架 | Vue 3 |
| UI 库 | Element Plus 2.13 + TailwindCSS 4 |
| 构建工具 | Vite 6 |
| 3D 引擎 | Three.js 0.170 |
| 模型加载 | GLTFLoader |

**核心模块：**

| 模块 | 文件 | 说明 |
|------|------|------|
| 场景管理 | [src/three/scene.js](web-3d/src/three/scene.js) | 场景初始化、灯光阴影、背景、相机控制器 |
| 园区构建 | [src/three/campus.js](web-3d/src/three/campus.js) | 地面、道路系统、树木、路灯、围栏、中心花坛、GLTF 工业建筑加载 |
| 交互系统 | [src/three/interaction.js](web-3d/src/three/interaction.js) | 射线检测、建筑/部件点击高亮、悬停效果、信息面板联动 |

**功能特性：**
- 完整的园区场景搭建（地面 / 路网 / 绿化 / 装饰）
- 工业建筑 GLTF 模型加载，含 12 个可交互子部件
- 鼠标悬停高亮 + 点击选中展示详细信息
- 左右分栏布局：左侧 3D 场景 (75%) + 右侧信息面板 (25%)

**端口：** `http://localhost:5173`

---

### 3. web-admin —— 管理后台

基于 **Vue 3 + Element Plus + TailwindCSS** 构建的后台管理系统。

| 技术 | 说明 |
|------|------|
| 框架 | Vue 3.5 |
| UI 库 | Element Plus 2.13 + TailwindCSS 4 |
| 状态管理 | Pinia 3 |
| 路由 | Vue Router 4 |
| HTTP | Axios |
| 构建工具 | Vite 8 |

**页面路由：**

| 路由 | 页面 | 说明 |
|------|------|------|
| `/login` | 登录页 | 用户登录认证 |
| `/dashboard` | 仪表盘 | 园区数据概览 |
| `/buildings` | 建筑管理 | 园区建筑列表管理 |
| `/buildings/:id/parts` | 部件管理 | 建筑子部件管理 |
| `/config` | 园区配置 | 全局配置项管理 (KV) |
| `/users` | 用户管理 | 用户 CRUD（仅管理员） |

**功能特性：**
- JWT 认证 + 路由守卫
- 基于角色 (admin / editor) 的权限控制
- Element Plus 组件按需自动导入
- 开发代理转发 API 到后端 `localhost:3000`

**端口：** `http://localhost:5173`

---

## 快速开始

### 环境要求

- Node.js >= 18
- npm >= 9

### 1. 启动后端服务

```bash
cd server
npm install
npm run start:dev
```

首次启动会自动创建 `database.sqlite` 并初始化以下默认用户：

| 用户名 | 密码 | 角色 |
|--------|------|------|
| admin | admin123 | 管理员 |
| editor | editor123 | 编辑者 |

### 2. 启动 3D 可视化前端

```bash
cd web-3d
npm install
npm run dev
```

> ⚠️ 注意：3D 可视化前端与 Admin 管理后台默认占用同一端口 (5173)，请勿同时启动两个前端。

### 3. 启动管理后台

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

---

## 系统架构

```
┌──────────────────────────┐
│     web-admin            │
│   Vue 3 + Element Plus   │
│   管理后台 (端口 5173)    │
└──────────┬───────────────┘
           │ HTTP /api/*
           ▼
┌──────────────────────────┐
│       server             │
│   NestJS + TypeORM       │
│   后端 API (端口 3000)    │
│   SQLite 数据库           │
└──────────────────────────┘
           ▲
           │ 3D 模型数据
┌──────────┴───────────────┐
│      web-3d              │
│   Vue 3 + Three.js       │
│   3D 可视化 (端口 5173)   │
└──────────────────────────┘
```

---

## 数据库说明

- 使用 **SQLite** 轻量级数据库（文件：`server/database.sqlite`）
- TypeORM 的 `synchronize: true` 在开发阶段自动同步表结构
- 主要数据表：`users`、`buildings`、`building_parts`、`campus_config`

---

## 角色权限

| 角色 | 权限 |
|------|------|
| admin | 完整权限，可管理用户、建筑、部件、配置 |
| editor | 可管理建筑、部件、配置，不可管理用户 |

---

## 开发说明

- 所有子项目需独立安装依赖 (`npm install`)
- 后端 `.env` 可用于配置 JWT 密钥等敏感信息
- 3D 模型资源位于 `web-3d/src/assets/models/`
- 前端开发时代理 `/api` 请求到后端，无需手动处理跨域