docs: 更新项目文档和API接口说明

更新CHANGELOG.md记录1.2.0版本变更
完善README.md项目说明和技术栈信息
重构DEPLOYMENT.md部署指南
详细编写API接口文档

CHANGELOG.md

@@ -2,6 +2,59 @@
 
 所有版本变更记录按时间倒序排列。
 
+---
+
+## [1.2.0] - 2026-02-05
+
+### 新增功能
+
+#### 端口与线缆管理
+- 新增设备端口管理模块，支持端口类型、速率、状态配置
+- 新增网卡管理功能，支持网卡与端口绑定
+- 新增线缆管理模块，支持机柜间线缆连接追踪
+- 端口面板可视化展示
+
+#### 系统功能增强
+- 新增系统设置管理，支持站点名称、Logo等配置
+- 新增背景配置管理，支持自定义系统背景
+- 完善用户权限管理，支持角色权限分配
+
+### 优化
+
+#### 3D可视化性能优化
+- 优化 Scene.jsx 渲染配置，降低设备像素比至 [1, 1.2]
+- 减小阴影贴图尺寸至 [1024, 1024]
+- 移除 ContactShadows 组件以减少阴影计算
+- 简化光源配置，移除冗余 pointLight
+- 优化环境光分辨率配置
+
+#### 设备模型优化
+- 实现性能模式（PERFORMANCE_MODE）以简化设备细节
+- 添加设备滑轨动画控制开关
+- 设备弹出动画默认关闭，可通过界面开关启用
+- 优化设备状态指示灯渲染性能
+
+#### LOD（多级细节）系统
+- 实现 LOD 管理器，根据相机距离自动切换设备细节级别
+- 高细节模式：完整设备模型，包含所有端口和细节
+- 中等细节模式：简化设备模型，使用 InstancedMesh 渲染端口
+- 低细节模式：极简设备模型，仅保留基本轮廓和状态灯
+- 修复 LOD 切换时设备位置偏移问题
+
+#### 交互体验改进
+- 添加设备弹出动画开关控制
+- 优化设备悬停和点击交互响应
+- 改进视角控制流畅度
+
+### 修复
+
+- 修复 AnimationManager 导入错误，移除对不存在文件的引用
+- 修复设备在缩放时位置偏移的问题
+- 修复 LOD 模型中状态灯位置计算错误
+- 修复 LODManager 中的几何体参数错误
+
+---
+
 ## [1.1.0] - 2026-01-26
 
 ### 优化
@@ -94,13 +147,19 @@
 - Three.js 0.160.0
 - React Router 6.15.0
 - Axios 1.5.0
+- Day.js 1.11.19
+- SheetJS (xlsx) 0.18.5
+- PapaParse 5.5.3
 
 #### 后端技术栈
 - Node.js ≥14.0.0
 - Express 4.18.2
 - Sequelize 6.32.1
 - SQLite/MySQL 支持
-- CORS 跨域配置
+- JWT 9.0.3
+- bcryptjs 3.0.3
+- Winston 3.19.0
+- Jest 30.2.0
 
 ### 数据库模型
 
@@ -108,6 +167,9 @@
 - Rack（机柜）
 - Device（设备）
 - DeviceField（设备字段）
+- DevicePort（设备端口）
+- NetworkCard（网卡）
+- Cable（线缆）
 - Ticket（工单）
 - TicketField（工单字段）
 - TicketCategory（工单分类）
@@ -157,18 +219,60 @@
 - 更新设备字段：`PUT /api/deviceFields/:id`
 - 删除设备字段：`DELETE /api/deviceFields/:id`
 
+#### 设备端口接口
+- 获取端口列表：`GET /api/device-ports`
+- 创建端口：`POST /api/device-ports`
+- 更新端口：`PUT /api/device-ports/:id`
+- 删除端口：`DELETE /api/device-ports/:id`
+
+#### 网卡接口
+- 获取网卡列表：`GET /api/network-cards`
+- 创建网卡：`POST /api/network-cards`
+- 更新网卡：`PUT /api/network-cards/:id`
+- 删除网卡：`DELETE /api/network-cards/:id`
+
+#### 线缆接口
+- 获取线缆列表：`GET /api/cables`
+- 创建线缆：`POST /api/cables`
+- 更新线缆：`PUT /api/cables/:id`
+- 删除线缆：`DELETE /api/cables/:id`
+
 #### 工单接口
 - 获取工单列表：`GET /api/tickets`
 - 创建工单：`POST /api/tickets`
 - 更新工单：`PUT /api/tickets/:ticketId`
 - 删除工单：`DELETE /api/tickets/:ticketId`
 
+#### 工单分类接口
+- 获取分类列表：`GET /api/ticket-categories`
+- 创建分类：`POST /api/ticket-categories`
+- 更新分类：`PUT /api/ticket-categories/:id`
+- 删除分类：`DELETE /api/ticket-categories/:id`
+
+#### 工单字段接口
+- 获取字段列表：`GET /api/ticket-fields`
+- 创建字段：`POST /api/ticket-fields`
+- 更新字段：`PUT /api/ticket-fields/:id`
+- 删除字段：`DELETE /api/ticket-fields/:id`
+
 #### 耗材接口
 - 获取耗材列表：`GET /api/consumables`
 - 创建耗材：`POST /api/consumables`
 - 更新耗材：`PUT /api/consumables/:consumableId`
 - 删除耗材：`DELETE /api/consumables/:consumableId`
 
+#### 耗材分类接口
+- 获取分类列表：`GET /api/consumable-categories`
+- 创建分类：`POST /api/consumable-categories`
+- 更新分类：`PUT /api/consumable-categories/:id`
+- 删除分类：`DELETE /api/consumable-categories/:id`
+
+#### 耗材记录接口
+- 获取记录列表：`GET /api/consumable-records`
+- 创建记录：`POST /api/consumable-records`
+- 更新记录：`PUT /api/consumable-records/:id`
+- 删除记录：`DELETE /api/consumable-records/:id`
+
 #### 用户接口
 - 获取用户列表：`GET /api/users`
 - 创建用户：`POST /api/users`
@@ -181,6 +285,14 @@
 - 更新角色：`PUT /api/roles/:roleId`
 - 删除角色：`DELETE /api/roles/:roleId`
 
+#### 系统设置接口
+- 获取系统设置：`GET /api/system-settings`
+- 更新系统设置：`PUT /api/system-settings`
+
+#### 背景配置接口
+- 获取背景配置：`GET /api/background`
+- 更新背景配置：`PUT /api/background`
+
 ---
 
 ## 格式说明
@@ -191,7 +303,8 @@
 - **优化**：功能改进和性能优化
 - **修复**：bug修复
 - **废弃**：即将移除的功能
-- ** Breaking Change**：破坏性变更
+- **移除**：已移除的功能
+- **安全**：安全相关的修复
 
 ## 版本号规范
 

DEPLOYMENT.md

@@ -1,8 +1,26 @@
 # IDC设备管理系统 - 安装部署指南
 
-## 快速开始（推荐）
+本文档详细介绍IDC设备管理系统的多种部署方式，包括开发环境、生产环境的配置方法。
 
-### 一键部署脚本（交互式）
+---
+
+## 目录
+
+- [快速开始](#快速开始)
+- [环境要求](#环境要求)
+- [开发环境部署](#开发环境部署)
+- [生产环境部署](#生产环境部署)
+- [Docker部署](#docker部署)
+- [数据库配置](#数据库配置)
+- [更新升级](#更新升级)
+- [监控维护](#监控维护)
+- [常见问题](#常见问题)
+
+---
+
+## 快速开始
+
+### 一键部署脚本（推荐）⭐
 
 我们提供了交互式安装脚本，自动完成环境检测、依赖安装、数据库初始化和服务启动。
 
@@ -31,59 +49,20 @@ node install.js
 
 ---
 
-## 传统手动部署
-
-如需手动部署，请参考以下步骤：
-
-### 1. 克隆项目
-
-**方式一：从GitHub克隆（推荐）**
-```bash
-git clone https://github.com/gituib/idc_assest.git
-cd idc_assest
-```
-
-**方式二：从Gitee克隆（国内访问更快）**
-```bash
-git clone https://gitee.com/zhang96110/idc_assest.git
-cd idc_assest
-```
-
-### 2. 安装依赖
-
-```bash
-cd backend && npm install
-cd ../frontend && npm install
-```
-
-### 3. 启动服务
-
-```bash
-# 后端（端口8000）
-cd backend && npm run dev
-
-# 前端（端口3000）- 新终端
-cd frontend && npm run dev
-```
-
-**访问地址**：
-- 前端：http://localhost:3000
-- 后端API：http://localhost:8000/api
-
----
-
 ## 环境要求
 
-| 项目 | 要求 |
+| 项目 | 要求 | 说明 |
-|------|------|
+|------|------|------|
-| Node.js | ≥14.0.0（推荐 20.x LTS） |
+| Node.js | ≥14.0.0（推荐 20.x LTS） | 运行环境 |
-| npm | ≥6.0.0（随 Node.js 安装） |
+| npm | ≥6.0.0 | 包管理器（随 Node.js 安装） |
-| 操作系统 | Windows 10/11、macOS、Linux |
+| 操作系统 | Windows 10/11、macOS、Linux | 支持主流操作系统 |
-| 内存 | 开发：4GB+ / 生产：8GB+ |
+| 内存 | 开发：4GB+ / 生产：8GB+ | 根据数据量调整 |
+| 磁盘空间 | ≥2GB | 包含依赖和日志 |
 
 ### Node.js 安装
 
 #### Linux（自动安装）
+
 运行 `node install.js`，选择自动安装即可。
 
 #### Linux（手动安装）
@@ -136,7 +115,7 @@ winget install OpenJS.NodeJS.LTS
 
 **方式一：Homebrew（推荐）**
 ```bash
-brew install node@
+brew install node@20
 ```
 
 **方式二：官方安装包**
@@ -157,59 +136,77 @@ nvm use 20
 
 ## 开发环境部署
 
-### 后端配置
+### 1. 克隆项目
 
-#### 1. 环境变量
+**方式一：从GitHub克隆（推荐）**
+```bash
+git clone https://github.com/gituib/idc_assest.git
+cd idc_assest
+```
+
+**方式二：从Gitee克隆（国内访问更快）**
+```bash
+git clone https://gitee.com/zhang96110/idc_assest.git
+cd idc_assest
+```
+
+### 2. 安装依赖
 
 ```bash
-cd backend
+# 安装后端依赖
+cd backend && npm install
+
+# 安装前端依赖
+cd ../frontend && npm install
+```
+
+### 3. 配置环境变量
+
+```bash
+cd ../backend
 cp .env.example .env
 ```
 
-#### 2. 数据库配置
+编辑 `.env` 文件（开发环境使用默认SQLite配置即可）：
-
-**默认配置（推荐）**：使用SQLite，无需额外配置
-
-**MySQL配置**：
-```sql
-CREATE DATABASE idc_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-```
-
-修改 `.env` 文件：
 ```env
-DB_TYPE=mysql
+NODE_ENV=development
-MYSQL_HOST=localhost
+PORT=8000
-MYSQL_PORT=3306
+DB_TYPE=sqlite
-MYSQL_USERNAME=root
-MYSQL_PASSWORD=your_password
-MYSQL_DATABASE=idc_management
 ```
 
-#### 3. 启动后端
+### 4. 启动服务
 
+**启动后端（端口8000）：**
 ```bash
+cd backend
 npm run dev
 ```
 
-### 前端配置
+**启动前端（端口3000）- 新终端：**
-
-#### 1. 启动开发服务器
-
 ```bash
 cd frontend
 npm run dev
 ```
 
-#### 2. 修改API地址（如需要）
+**访问地址：**
+- 前端应用：http://localhost:3000
+- 后端API：http://localhost:8000/api
+- 健康检查：http://localhost:8000/health
 
-编辑 `vite.config.js`：
+### 5. 开发脚本
-```javascript
+
-proxy: {
+```bash
-  '/api': {
+# 同时启动前后端（项目根目录）
-    target: 'http://localhost:8000',
+npm start
-    changeOrigin: true
+
-  }
+# 仅启动后端
-}
+npm run start:backend
+
+# 仅启动前端
+npm run start:frontend
+
+# 安装所有依赖
+npm run install:all
 ```
 
 ---
@@ -248,16 +245,18 @@ MYSQL_PORT=3306
 MYSQL_USERNAME=idc_user
 MYSQL_PASSWORD=secure_password
 MYSQL_DATABASE=idc_management
+JWT_SECRET=your_jwt_secret_key_here
 ```
 
 ##### 2. 安装生产依赖
 
 ```bash
-npm install
+npm install --production
 ```
 
 ##### 3. 配置数据库
 
+**创建数据库：**
 ```sql
 CREATE DATABASE idc_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
 CREATE USER 'idc_user'@'localhost' IDENTIFIED BY 'secure_password';
@@ -274,8 +273,13 @@ node scripts/init-database.js
 ##### 5. 使用PM2管理进程
 
 ```bash
+# 安装 PM2
 npm install -g pm2
-pm2 start server.js --name "idc-backend" --env production
+
+# 启动服务
+pm2 start server.js --name "idc-backend" --cwd ./backend --env production
+
+# 配置开机自启
 pm2 startup
 pm2 save
 ```
@@ -290,11 +294,14 @@ npm install
 npm run build
 ```
 
+构建输出目录：`frontend/dist/`
+
 ##### 2. 部署静态文件
 
-**Nginx 方式：**
+**Nginx 方式（推荐）：**
 ```bash
-sudo cp -r dist/* /var/www/idc-frontend/
+# 复制构建文件到Nginx目录
+sudo cp -r frontend/dist/* /var/www/idc-frontend/
 sudo chown -R www-data:www-data /var/www/idc-frontend
 sudo chmod -R 755 /var/www/idc-frontend
 ```
@@ -302,17 +309,21 @@ sudo chmod -R 755 /var/www/idc-frontend
 **PM2 serve 方式：**
 ```bash
 npm install -g serve
-pm2 start serve --name "idc-frontend" -- -s dist -l 3000
+pm2 start serve --name "idc-frontend" -- -s frontend/dist -l 3000
 ```
 
 ### Nginx配置
 
 #### 1. 创建配置文件
 
+**Linux:**
 ```bash
 sudo nano /etc/nginx/sites-available/idc_assest
 ```
 
+**Windows:**
+编辑 `C:\nginx\conf\nginx.conf` 或在 `conf.d` 目录创建新配置
+
 #### 2. 配置内容
 
 ```nginx
@@ -335,10 +346,12 @@ server {
         add_header Cache-Control "public, immutable";
     }
     
+    # 前端路由支持
     location / {
         try_files $uri $uri/ /index.html;
     }
     
+    # API代理
     location /api {
         proxy_pass http://127.0.0.1:8000;
         proxy_http_version 1.1;
@@ -350,6 +363,7 @@ server {
         proxy_read_timeout 60s;
     }
     
+    # 文件上传代理
     location /uploads {
         proxy_pass http://127.0.0.1:8000;
         proxy_http_version 1.1;
@@ -362,62 +376,123 @@ server {
 
 #### 3. 启用配置
 
+**Linux:**
 ```bash
 sudo ln -s /etc/nginx/sites-available/idc_assest /etc/nginx/sites-enabled/
 sudo nginx -t
 sudo systemctl restart nginx
 ```
 
-### SSL证书（可选）
+**Windows:**
+```cmd
+nginx -t
+nginx -s reload
+```
 
+### SSL证书配置（可选）
+
+**使用 Let's Encrypt（Linux）：**
 ```bash
 sudo apt install certbot python3-certbot-nginx
 sudo certbot --nginx -d your-domain.com
 ```
 
+**手动配置SSL：**
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+    
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    
+    # ... 其他配置
+}
+
+# HTTP重定向到HTTPS
+server {
+    listen 80;
+    server_name your-domain.com;
+    return 301 https://$server_name$request_uri;
+}
+```
+
 ---
 
-## 服务管理
+## Docker部署
 
-### PM2 管理命令
+### 使用 Docker Compose（推荐）
 
-```bash
+创建 `docker-compose.yml`：
-pm2 status                    # 查看服务状态
+
-pm2 logs idc-backend          # 查看后端日志
+```yaml
-pm2 logs idc-frontend         # 查看前端日志（PM2方式）
+version: '3.8'
-pm2 restart idc-backend       # 重启后端服务
+
-pm2 stop idc-backend          # 停止后端服务
+services:
-pm2 delete idc-backend        # 删除后端服务
+  backend:
-pm2 save                      # 保存当前进程列表
+    build:
-pm2 startup                   # 配置开机自启
+      context: ./backend
+      dockerfile: Dockerfile
+    ports:
+      - "8000:8000"
+    environment:
+      - NODE_ENV=production
+      - DB_TYPE=mysql
+      - MYSQL_HOST=mysql
+      - MYSQL_PORT=3306
+      - MYSQL_USERNAME=idc_user
+      - MYSQL_PASSWORD=idc_password
+      - MYSQL_DATABASE=idc_management
+    volumes:
+      - ./backend/uploads:/app/uploads
+    depends_on:
+      - mysql
+    restart: unless-stopped
+
+  frontend:
+    build:
+      context: ./frontend
+      dockerfile: Dockerfile
+    ports:
+      - "80:80"
+    depends_on:
+      - backend
+    restart: unless-stopped
+
+  mysql:
+    image: mysql:8.0
+    environment:
+      - MYSQL_ROOT_PASSWORD=root_password
+      - MYSQL_DATABASE=idc_management
+      - MYSQL_USER=idc_user
+      - MYSQL_PASSWORD=idc_password
+    volumes:
+      - mysql_data:/var/lib/mysql
+    restart: unless-stopped
+
+volumes:
+  mysql_data:
 ```
 
-### Nginx 管理命令
+启动服务：
-
-**Linux:**
 ```bash
-sudo nginx -t                 # 测试配置
+docker-compose up -d
-sudo systemctl restart nginx  # 重启服务
-sudo systemctl status nginx   # 查看状态
-```
-
-**Windows:**
-```cmd
-nginx -t                      # 测试配置
-nginx -s reload               # 重载配置
-nginx -s stop                 # 停止Nginx
 ```
 
 ---
 
 ## 数据库配置
 
-### SQLite（开发环境）
+### SQLite（开发环境/小规模）
 
 - 默认配置，无需额外设置
 - 数据库文件：`backend/idc_management.db`
+- 优点：零配置，便携
+- 缺点：不适合高并发，单文件限制
 
-### MySQL（生产环境）
+### MySQL（生产环境推荐）
 
 #### 创建数据库
 
@@ -433,29 +508,49 @@ GRANT ALL PRIVILEGES ON idc_management.* TO 'idc_user'@'localhost';
 FLUSH PRIVILEGES;
 ```
 
+#### 配置优化
+
+```ini
+# my.cnf 或 my.ini
+[mysqld]
+character-set-server=utf8mb4
+collation-server=utf8mb4_unicode_ci
+max_connections=200
+innodb_buffer_pool_size=1G
+```
+
 ### 数据备份
 
 #### SQLite备份
 
 ```bash
+# 手动备份
 cp backend/idc_management.db backup/database_$(date +%Y%m%d).db
+
+# 自动备份脚本
+#!/bin/bash
+BACKUP_DIR="/var/backups/idc_assest"
+DATE=$(date +%Y%m%d_%H%M%S)
+mkdir -p $BACKUP_DIR
+cp backend/idc_management.db "$BACKUP_DIR/database_$DATE.db"
+gzip "$BACKUP_DIR/database_$DATE.db"
+
+# 清理30天前的备份
+find $BACKUP_DIR -name "database_*.gz" -mtime +30 -delete
 ```
 
 #### MySQL备份
 
 ```bash
+# 手动备份
 mysqldump -u idc_user -p idc_management > backup/database_$(date +%Y%m%d).sql
-```
 
-#### 自动备份脚本
+# 自动备份脚本
-
-```bash
 #!/bin/bash
 BACKUP_DIR="/var/backups/idc_assest"
 DATE=$(date +%Y%m%d_%H%M%S)
 mkdir -p $BACKUP_DIR
 
-# MySQL备份
 mysqldump -u idc_user -pYourPassword idc_management > "$BACKUP_DIR/database_$DATE.sql"
 gzip "$BACKUP_DIR/database_$DATE.sql"
 
@@ -487,17 +582,15 @@ npm run update
 #### 1. 备份数据
 
 ```bash
+# MySQL
 mysqldump -u idc_user -p idc_management > backup.sql
+
+# SQLite
+cp backend/idc_management.db backup.db
 ```
 
 #### 2. 拉取最新代码
 
-**从GitHub拉取**：
-```bash
-git pull origin master
-```
-
-**从Gitee拉取**：
 ```bash
 git pull origin master
 ```
@@ -523,19 +616,31 @@ sudo systemctl restart nginx
 ### 查看日志
 
 ```bash
+# PM2 日志
 pm2 logs idc-backend
+pm2 logs idc-frontend
+
+# Nginx 日志（Linux）
 tail -f /var/log/nginx/idc_assest-error.log
+tail -f /var/log/nginx/idc_assest-access.log
+
+# 系统日志（Linux）
+journalctl -u idc-backend -f
 ```
 
 ### 健康检查
 
 ```bash
+# 服务状态
 curl http://localhost:8000/health
+
+# 数据库连接检查
+curl http://localhost:8000/api/health/db
 ```
 
-### 性能优化
+### 性能监控
 
-**PM2配置**（`deploy/ecosystem.config.js`）：
+**PM2配置**（`ecosystem.config.js`）：
 ```javascript
 module.exports = {
   apps: [{
@@ -545,11 +650,43 @@ module.exports = {
     instances: 1,
     exec_mode: 'fork',
     max_memory_restart: '1G',
-    autorestart: true
+    autorestart: true,
+    env: {
+      NODE_ENV: 'production'
+    },
+    log_file: './logs/combined.log',
+    out_file: './logs/out.log',
+    error_file: './logs/error.log',
+    log_date_format: 'YYYY-MM-DD HH:mm:ss Z'
   }]
 };
 ```
 
+### 服务管理命令
+
+```bash
+# PM2 管理
+pm2 status                    # 查看服务状态
+pm2 logs idc-backend          # 查看后端日志
+pm2 logs idc-frontend         # 查看前端日志（PM2方式）
+pm2 restart idc-backend       # 重启后端服务
+pm2 stop idc-backend          # 停止后端服务
+pm2 delete idc-backend        # 删除后端服务
+pm2 save                      # 保存当前进程列表
+pm2 startup                   # 配置开机自启
+pm2 monit                     # 实时监控
+
+# Nginx 管理（Linux）
+sudo nginx -t                 # 测试配置
+sudo systemctl restart nginx  # 重启服务
+sudo systemctl status nginx   # 查看状态
+
+# Nginx 管理（Windows）
+nginx -t                      # 测试配置
+nginx -s reload               # 重载配置
+nginx -s stop                 # 停止Nginx
+```
+
 ---
 
 ## 常见问题
@@ -558,7 +695,10 @@ module.exports = {
 
 ```bash
 # 检查端口占用
+# Linux
 netstat -tulpn | grep :8000
+# Windows
+netstat -ano | findstr :8000
 
 # 修改端口
 PORT=8001 npm run dev
@@ -567,21 +707,29 @@ PORT=8001 npm run dev
 ### 依赖安装失败
 
 ```bash
+# 清理缓存
 npm cache clean --force
+
+# 删除 node_modules
 rm -rf node_modules package-lock.json
+
+# 重新安装
 npm install
 ```
 
 ### 数据库连接失败
 
-**SQLite**：
+**SQLite：**
 - 检查文件权限
 - 确保磁盘空间充足
+- 检查文件是否被其他进程占用
 
-**MySQL**：
+**MySQL：**
-- 检查服务状态：`systemctl status mysql`
+- 检查服务状态：`systemctl status mysql`（Linux）
-- 验证连接参数
+- 验证连接参数（主机、端口、用户名、密码）
 - 确认数据库已创建
+- 检查防火墙设置
+- 确认用户权限：`SHOW GRANTS FOR 'idc_user'@'localhost'`
 
 ### 部署脚本问题
 
@@ -594,6 +742,41 @@ npm install
 - Windows：脚本会询问是否自动下载安装
 - Linux/macOS：脚本会显示安装命令，需手动安装
 
+### 前端构建失败
+
+```bash
+# 检查 Node.js 版本
+node -v
+
+# 清理并重新构建
+cd frontend
+rm -rf node_modules dist
+npm install
+npm run build
+```
+
+### 权限问题
+
+**Linux:**
+```bash
+# 修复文件权限
+sudo chown -R $(whoami):$(whoami) /path/to/project
+sudo chmod -R 755 /path/to/project
+
+# 上传目录权限
+sudo chmod -R 777 backend/uploads
+```
+
+### 内存不足
+
+```bash
+# 增加 Node.js 内存限制
+node --max-old-space-size=4096 server.js
+
+# PM2 配置
+pm2 start server.js --name "idc-backend" --node-args="--max-old-space-size=4096"
+```
+
 ---
 
 ## 项目结构
@@ -601,11 +784,12 @@ npm install
 ```
 idc_assest/
 ├── backend/              # 后端服务
-│   ├── middleware/       # 中间件
+│   ├── middleware/       # 中间件（认证、验证）
-│   ├── models/           # 数据模型
+│   ├── models/           # 数据模型（Sequelize）
 │   ├── routes/           # API路由
 │   ├── scripts/          # 数据库脚本
 │   ├── uploads/          # 文件上传目录
+│   ├── validation/       # 数据验证Schema
 │   ├── server.js         # 服务入口
 │   └── package.json
 ├── frontend/             # 前端应用
@@ -616,12 +800,17 @@ idc_assest/
 │   │   └── utils/        # 工具函数
 │   ├── dist/             # 构建输出
 │   └── package.json
-├── deploy/               # 部署配置
+├── docs/                 # 项目文档
-│   ├── ecosystem.config.js   # PM2配置
+│   ├── api/              # 接口文档
-│   └── nginx-idc.conf        # Nginx配置
+│   └── images/           # 文档图片
 ├── install.js            # 交互式安装脚本 ⭐
 ├── update.js             # 一键更新脚本 ⭐
+├── uninstall.js          # 卸载脚本
+├── check.js              # 环境检查脚本
+├── modify.js             # 配置修改脚本
 ├── package.json
+├── README.md             # 项目说明
+├── CHANGELOG.md          # 版本记录
 └── DEPLOYMENT.md         # 本文件
 ```
 

README.md

@@ -11,14 +11,19 @@
 
 ### 核心功能
 
-- **机房管理**：管理多个机房的详细信息、容量和使用状态
+| 功能模块 | 描述 |
-- **机柜管理**：机柜的增删改查，支持按机房分类管理
+|---------|------|
-- **设备管理**：服务器、网络设备、存储设备的全生命周期管理
+| **机房管理** | 多机房管理，支持位置、面积等详细信息 |
-- **工单管理**：设备故障报修、维护工单全流程管理
+| **机柜管理** | 机柜增删改查，容量统计，3D可视化展示 |
-- **耗材管理**：耗材库存、领用记录、统计报表管理
+| **设备管理** | 服务器、网络设备、存储设备全生命周期管理，支持批量导入/导出 |
-- **数据看板**：实时监控数据中心整体运行状态
+| **端口管理** | 设备端口配置与管理，支持网卡绑定 |
-- **3D可视化**：三维机柜可视化展示，支持设备悬停详情查看
+| **线缆管理** | 机柜间线缆连接管理，可视化追踪 |
-- **系统配置**：设备字段、工单字段自定义管理
+| **工单管理** | 故障报修、维护工单全流程管理，支持自定义字段 |
+| **耗材管理** | 耗材库存、领用记录、统计报表管理 |
+| **数据看板** | 实时监控数据中心整体运行状态 |
+| **3D可视化** | 三维机柜可视化展示，支持设备悬停详情、LOD优化 |
+| **系统配置** | 设备字段、工单字段自定义管理，背景配置 |
+| **用户权限** | 基于角色的权限控制（RBAC） |
 
 ### 项目截图
 
@@ -36,15 +41,32 @@
 
 ### 技术栈
 
-| 类别 | 技术 | 版本 |
+#### 前端技术栈
+
+| 技术 | 版本 | 用途 |
 |------|------|------|
-| 前端框架 | React | 18.2.0 |
+| React | 18.2.0 | 前端框架（用户界面开发库） |
-| 构建工具 | Vite | 4.4.9 |
+| Vite | 4.4.9 | 构建工具（前端项目打包工具） |
-| UI组件库 | Ant Design | 5.8.6 |
+| Ant Design | 5.8.6 | UI组件库（企业级设计系统） |
-| 3D渲染 | Three.js | 0.160.0 |
+| Three.js | 0.160.0 | 3D渲染引擎 |
-| 后端框架 | Express | 4.18.2 |
+| React Router | 6.15.0 | 路由管理 |
-| ORM框架 | Sequelize | 6.32.1 |
+| Axios | 1.5.0 | HTTP客户端 |
-| 数据库 | SQLite/MySQL | 5.1.6/8.0+ |
+| Day.js | 1.11.19 | 日期处理库 |
+| SheetJS (xlsx) | 0.18.5 | Excel文件处理 |
+| PapaParse | 5.5.3 | CSV文件解析 |
+
+#### 后端技术栈
+
+| 技术 | 版本 | 用途 |
+|------|------|------|
+| Node.js | ≥14.0.0 | 运行环境 |
+| Express | 4.18.2 | Web框架（后端服务框架） |
+| Sequelize | 6.32.1 | ORM框架（数据库对象关系映射） |
+| SQLite/MySQL | 5.1.6/8.0+ | 数据库 |
+| JWT | 9.0.3 | 身份认证 |
+| bcryptjs | 3.0.3 | 密码加密 |
+| Winston | 3.19.0 | 日志管理 |
+| Jest | 30.2.0 | 测试框架 |
 
 ## 项目结构
 
@@ -53,22 +75,37 @@ jigui/
 ├── frontend/                 # 前端项目
 │   ├── src/
 │   │   ├── api/             # API接口封装
+│   │   ├── assets/          # 静态资源（字体、3D环境贴图）
 │   │   ├── components/      # 通用组件
-│   │   ├── context/         # 状态管理
+│   │   │   ├── 3d/          # 3D可视化组件
-│   │   └── pages/           # 页面模块
+│   │   │   │   ├── materials/   # 3D材质组件
+│   │   │   │   ├── DeviceModel.jsx  # 设备模型
+│   │   │   │   ├── RackModel.jsx    # 机柜模型
+│   │   │   │   ├── Scene.jsx        # 3D场景
+│   │   │   │   └── LODManager.jsx   # LOD管理器
+│   │   │   └── *.jsx        # 业务组件
+│   │   ├── context/         # React Context状态管理
+│   │   ├── hooks/           # 自定义Hooks
+│   │   ├── pages/           # 页面模块
+│   │   └── utils/           # 工具函数
+│   ├── public/              # 公共资源
 │   └── vite.config.js       # Vite配置
 ├── backend/                  # 后端项目
-│   ├── models/              # 数据模型
+│   ├── middleware/          # 中间件（认证、验证）
+│   ├── models/              # 数据模型（Sequelize）
 │   ├── routes/              # API路由
-│   ├── middleware/          # 中间件
+│   ├── scripts/             # 数据库脚本
+│   ├── uploads/             # 文件上传目录
+│   ├── validation/          # 数据验证Schema
 │   └── server.js            # 服务入口
-├── deploy/                   # 部署配置 ⭐ NEW
-│   ├── ecosystem.config.js  # PM2配置
-│   └── nginx-idc.conf       # Nginx配置
 ├── docs/                     # 项目文档
-│   └── api/                 # 接口文档
+│   ├── api/                 # 接口文档
-├── install.js                # 交互式安装脚本 ⭐ NEW
+│   └── images/              # 文档图片
-├── update.js                 # 一键更新脚本 ⭐ NEW
+├── install.js                # 交互式安装脚本 ⭐
+├── update.js                 # 一键更新脚本 ⭐
+├── uninstall.js              # 卸载脚本
+├── check.js                  # 环境检查脚本
+├── modify.js                 # 配置修改脚本
 ├── README.md                 # 项目说明
 ├── CHANGELOG.md              # 版本记录
 └── DEPLOYMENT.md             # 部署指南
@@ -76,7 +113,7 @@ jigui/
 
 ## 快速开始
 
-### 方式一：一键部署脚本（推荐）⭐ NEW
+### 方式一：一键部署脚本（推荐）⭐
 
 我们提供了交互式安装脚本，自动完成所有部署步骤：
 
@@ -136,8 +173,8 @@ node install.js
 确认以上配置并开始部署? (Y/n): Y
 
 ✓ 后端环境变量文件已生成 (.env)
-✓ PM2 配置文件已生成 (deploy/ecosystem.config.js)
+✓ PM2 配置文件已生成 (ecosystem.config.js)
-✓ Nginx 配置文件已生成 (deploy/nginx-idc.conf)
+✓ Nginx 配置文件已生成 (nginx-idc.conf)
 ✓ 安装部署完成！
 ```
 
@@ -145,9 +182,11 @@ node install.js
 
 #### 环境要求
 
-- Node.js ≥14.0.0（推荐 20.x LTS）
+| 项目 | 要求 |
-- npm ≥6.0.0
+|------|------|
-- 操作系统：Windows 10/11、macOS、Linux
+| Node.js | ≥14.0.0（推荐 20.x LTS） |
+| npm | ≥6.0.0 |
+| 操作系统 | Windows 10/11、macOS、Linux |
 
 #### 安装步骤
 
@@ -180,10 +219,134 @@ npm run dev
 **访问地址**：
 - 前端应用：http://localhost:3000
 - 后端API：http://localhost:8000/api
+- 健康检查：http://localhost:8000/health
+
+## 安装部署脚本
+
+项目提供多个实用脚本，简化安装、更新、卸载等操作：
+
+### 脚本列表
+
+| 脚本 | 命令 | 功能说明 |
+|------|------|----------|
+| **install.js** | `npm run deploy` / `node install.js` | 交互式安装部署脚本 |
+| **update.js** | `npm run update` / `node update.js` | 一键更新脚本 |
+| **uninstall.js** | `node uninstall.js` | 卸载清理脚本 |
+| **check.js** | `node check.js` | 环境检查脚本 |
+| **modify.js** | `node modify.js` | 配置修改脚本 |
+
+### install.js - 交互式安装部署
+
+**功能特性：**
+- ✅ 自动检测 Node.js、npm、PM2、Nginx 环境
+- ✅ **Linux 支持自动安装 Node.js**（交互式）
+- ✅ 交互式配置数据库（SQLite/MySQL）
+- ✅ 交互式选择运行环境（development/production）
+- ✅ 交互式选择前端部署方式（Nginx/PM2 serve）
+- ✅ 自动安装项目依赖
+- ✅ 自动初始化数据库
+- ✅ 自动构建前端项目
+- ✅ 使用 PM2 启动和管理服务
+
+**使用方式：**
+```bash
+# 方式一：使用 npm 命令
+npm run deploy
+
+# 方式二：直接运行脚本
+node install.js
+```
+
+### update.js - 一键更新
+
+**功能特性：**
+- ✅ 自动备份数据
+- ✅ 拉取最新代码
+- ✅ 更新前后端依赖
+- ✅ 重建前端项目
+- ✅ 重启服务
+
+**使用方式：**
+```bash
+# 方式一：使用 npm 命令
+npm run update
+
+# 方式二：直接运行脚本
+node update.js
+```
+
+### uninstall.js - 卸载清理
+
+**功能特性：**
+- ✅ 停止 PM2 服务
+- ✅ 删除 PM2 进程配置
+- ✅ 清理 Nginx 配置（可选）
+- ✅ 备份数据（可选）
+- ✅ 清理日志文件（可选）
+
+**使用方式：**
+```bash
+node uninstall.js
+```
+
+**卸载流程：**
+```
+▶ 停止服务
+✓ 已停止 idc-backend
+✓ 已停止 idc-frontend
+
+▶ 删除 PM2 配置
+✓ 已删除 PM2 进程
+
+▶ 清理 Nginx 配置
+是否删除 Nginx 配置? (y/N): n
+
+▶ 数据备份
+是否备份数据库? (Y/n): y
+✓ 数据库已备份到 backup/database_20240205_143022.sql
+
+▶ 清理完成
+✓ 卸载完成，感谢使用！
+```
+
+**注意事项：**
+- 卸载前建议备份数据
+- 默认保留数据库文件，可手动删除
+- 上传的文件（avatars、uploads）需手动清理
+
+### check.js - 环境检查
+
+**功能特性：**
+- ✅ 检查 Node.js 版本
+- ✅ 检查 npm 版本
+- ✅ 检查 PM2 安装状态
+- ✅ 检查 Nginx 安装状态
+- ✅ 检查端口占用情况
+- ✅ 检查磁盘空间
+
+**使用方式：**
+```bash
+node check.js
+```
+
+### modify.js - 配置修改
+
+**功能特性：**
+- ✅ 修改数据库配置
+- ✅ 修改服务端口
+- ✅ 修改运行环境
+- ✅ 修改前端部署方式
+
+**使用方式：**
+```bash
+node modify.js
+```
+
+---
 
 ## 更新升级
 
-### 一键更新（推荐）⭐ NEW
+### 一键更新（推荐）⭐
 
 ```bash
 npm run update
@@ -207,35 +370,62 @@ cd ../frontend && npm install && npm run build
 pm2 restart idc-backend
 ```
 
-## 主要功能
+## 主要功能详解
 
 ### 机房管理
 
-多机房支持，机房详细信息记录，按机房分类管理机柜。
+- 多机房支持，机房详细信息记录
+- 按机房分类管理机柜
+- 机房容量统计与状态展示
 
 ### 机柜管理
 
-机柜增删改查，机柜容量统计，可视化机柜状态展示。
+- 机柜增删改查，支持自定义高度（U数）
+- 机柜容量统计，功率管理
+- 3D可视化展示，支持视角控制
 
 ### 设备管理
 
-设备全生命周期管理，批量导入/导出，设备状态跟踪，自定义设备字段。
+- 设备全生命周期管理（采购→上线→维护→报废）
+- 批量导入/导出（支持Excel/CSV）
+- 设备状态跟踪与筛选
+- 自定义设备字段，灵活扩展
+- 网卡管理与端口配置
+
+### 端口与线缆管理
+
+- 设备端口配置（类型、速率、状态）
+- 网卡管理与绑定
+- 线缆连接管理，可视化追踪
+- 支持批量配置
 
 ### 工单管理
 
-故障报修流程，维护工单创建与处理，工单状态追踪，操作记录审计。
+- 故障报修流程，支持附件上传
+- 维护工单创建与处理
+- 工单状态追踪，操作记录审计
+- 自定义工单字段和分类
 
 ### 耗材管理
 
-耗材分类管理，库存监控，领用记录，耗材使用统计报表。
+- 耗材分类管理，规格定义
+- 库存监控，预警提醒
+- 领用记录，使用追踪
+- 耗材使用统计报表
 
 ### 数据看板
 
-实时统计图表，设备状态分布，容量使用率分析，关键指标监控。
+- 实时统计图表（设备状态、容量使用）
+- 关键指标监控
+- 趋势分析
 
 ### 3D可视化
 
-三维机柜展示，设备悬停详情，实时交互体验，视角控制功能，支持设备弹出动画开关。
+- 三维机柜展示，真实比例渲染
+- 设备悬停详情查看
+- LOD（多级细节）优化，流畅渲染
+- 设备弹出动画（可开关）
+- 视角控制（旋转、缩放、平移）
 
 ## API接口
 
@@ -243,11 +433,15 @@ pm2 restart idc-backend
 
 ### 基础信息
 
-- Base URL: `http://localhost:8000/api`
+| 项目 | 值 |
-- Content-Type: `application/json`
+|------|-----|
+| Base URL | `http://localhost:8000/api` |
+| Content-Type | `application/json` |
+| 认证方式 | Bearer Token (JWT) |
 
 ### 通用响应格式
 
+**成功响应：**
 ```json
 {
   "success": true,
@@ -256,8 +450,7 @@ pm2 restart idc-backend
 }
 ```
 
-### 错误响应
+**错误响应：**
-
 ```json
 {
   "success": false,