From 719812f01268f9530f2eb189c4ea31d8571b43b5 Mon Sep 17 00:00:00 2001
From: zhang1106 <849185023@qq.com>
Date: Thu, 5 Feb 2026 13:59:28 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E9=A1=B9=E7=9B=AE?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=92=8CAPI=E6=8E=A5=E5=8F=A3=E8=AF=B4?=
 =?UTF-8?q?=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

更新CHANGELOG.md记录1.2.0版本变更
完善README.md项目说明和技术栈信息
重构DEPLOYMENT.md部署指南
详细编写API接口文档
---
 CHANGELOG.md       | 117 +++++-
 DEPLOYMENT.md      | 465 ++++++++++++++++--------
 README.md          | 283 ++++++++++++---
 docs/api/README.md | 861 ++++++++++++++++++++++++++++++++++++++-------
 4 files changed, 1408 insertions(+), 318 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c4d7717..7596dab 100644
--- a/CHANGELOG.md
+++ b/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**：破坏性变更
+- **移除**：已移除的功能
+- **安全**：安全相关的修复
 
 ## 版本号规范
 
diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
index 7c45d3b..f1f79f2 100644
--- a/DEPLOYMENT.md
+++ b/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） |
-| npm | ≥6.0.0（随 Node.js 安装） |
-| 操作系统 | Windows 10/11、macOS、Linux |
-| 内存 | 开发：4GB+ / 生产：8GB+ |
+| 项目 | 要求 | 说明 |
+|------|------|------|
+| Node.js | ≥14.0.0（推荐 20.x LTS） | 运行环境 |
+| npm | ≥6.0.0 | 包管理器（随 Node.js 安装） |
+| 操作系统 | Windows 10/11、macOS、Linux | 支持主流操作系统 |
+| 内存 | 开发：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. 数据库配置
-
-**默认配置（推荐）**：使用SQLite，无需额外配置
-
-**MySQL配置**：
-```sql
-CREATE DATABASE idc_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-```
-
-修改 `.env` 文件：
+编辑 `.env` 文件（开发环境使用默认SQLite配置即可）：
 ```env
-DB_TYPE=mysql
-MYSQL_HOST=localhost
-MYSQL_PORT=3306
-MYSQL_USERNAME=root
-MYSQL_PASSWORD=your_password
-MYSQL_DATABASE=idc_management
+NODE_ENV=development
+PORT=8000
+DB_TYPE=sqlite
 ```
 
-#### 3. 启动后端
+### 4. 启动服务
 
+**启动后端（端口8000）：**
 ```bash
+cd backend
 npm run dev
 ```
 
-### 前端配置
-
-#### 1. 启动开发服务器
-
+**启动前端（端口3000）- 新终端：**
 ```bash
 cd frontend
 npm run dev
 ```
 
-#### 2. 修改API地址（如需要）
+**访问地址：**
+- 前端应用：http://localhost:3000
+- 后端API：http://localhost:8000/api
+- 健康检查：http://localhost:8000/health
 
-编辑 `vite.config.js`：
-```javascript
-proxy: {
-  '/api': {
-    target: 'http://localhost:8000',
-    changeOrigin: true
-  }
-}
+### 5. 开发脚本
+
+```bash
+# 同时启动前后端（项目根目录）
+npm start
+
+# 仅启动后端
+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
-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                   # 配置开机自启
+创建 `docker-compose.yml`：
+
+```yaml
+version: '3.8'
+
+services:
+  backend:
+    build:
+      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                 # 测试配置
-sudo systemctl restart nginx  # 重启服务
-sudo systemctl status nginx   # 查看状态
-```
-
-**Windows:**
-```cmd
-nginx -t                      # 测试配置
-nginx -s reload               # 重载配置
-nginx -s stop                 # 停止Nginx
+docker-compose up -d
 ```
 
 ---
 
 ## 数据库配置
 
-### 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**：
-- 检查服务状态：`systemctl status mysql`
-- 验证连接参数
+**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/       # 中间件
-│   ├── models/           # 数据模型
+│   ├── middleware/       # 中间件（认证、验证）
+│   ├── models/           # 数据模型（Sequelize）
 │   ├── routes/           # API路由
 │   ├── scripts/          # 数据库脚本
 │   ├── uploads/          # 文件上传目录
+│   ├── validation/       # 数据验证Schema
 │   ├── server.js         # 服务入口
 │   └── package.json
 ├── frontend/             # 前端应用
@@ -616,12 +800,17 @@ idc_assest/
 │   │   └── utils/        # 工具函数
 │   ├── dist/             # 构建输出
 │   └── package.json
-├── deploy/               # 部署配置
-│   ├── ecosystem.config.js   # PM2配置
-│   └── nginx-idc.conf        # Nginx配置
+├── docs/                 # 项目文档
+│   ├── api/              # 接口文档
+│   └── images/           # 文档图片
 ├── install.js            # 交互式安装脚本 ⭐
 ├── update.js             # 一键更新脚本 ⭐
+├── uninstall.js          # 卸载脚本
+├── check.js              # 环境检查脚本
+├── modify.js             # 配置修改脚本
 ├── package.json
+├── README.md             # 项目说明
+├── CHANGELOG.md          # 版本记录
 └── DEPLOYMENT.md         # 本文件
 ```
 
diff --git a/README.md b/README.md
index d164035..abf44a8 100644
--- a/README.md
+++ b/README.md
@@ -11,14 +11,19 @@
 
 ### 核心功能
 
-- **机房管理**：管理多个机房的详细信息、容量和使用状态
-- **机柜管理**：机柜的增删改查，支持按机房分类管理
-- **设备管理**：服务器、网络设备、存储设备的全生命周期管理
-- **工单管理**：设备故障报修、维护工单全流程管理
-- **耗材管理**：耗材库存、领用记录、统计报表管理
-- **数据看板**：实时监控数据中心整体运行状态
-- **3D可视化**：三维机柜可视化展示，支持设备悬停详情查看
-- **系统配置**：设备字段、工单字段自定义管理
+| 功能模块 | 描述 |
+|---------|------|
+| **机房管理** | 多机房管理，支持位置、面积等详细信息 |
+| **机柜管理** | 机柜增删改查，容量统计，3D可视化展示 |
+| **设备管理** | 服务器、网络设备、存储设备全生命周期管理，支持批量导入/导出 |
+| **端口管理** | 设备端口配置与管理，支持网卡绑定 |
+| **线缆管理** | 机柜间线缆连接管理，可视化追踪 |
+| **工单管理** | 故障报修、维护工单全流程管理，支持自定义字段 |
+| **耗材管理** | 耗材库存、领用记录、统计报表管理 |
+| **数据看板** | 实时监控数据中心整体运行状态 |
+| **3D可视化** | 三维机柜可视化展示，支持设备悬停详情、LOD优化 |
+| **系统配置** | 设备字段、工单字段自定义管理，背景配置 |
+| **用户权限** | 基于角色的权限控制（RBAC） |
 
 ### 项目截图
 
@@ -36,15 +41,32 @@
 
 ### 技术栈
 
-| 类别 | 技术 | 版本 |
+#### 前端技术栈
+
+| 技术 | 版本 | 用途 |
 |------|------|------|
-| 前端框架 | React | 18.2.0 |
-| 构建工具 | Vite | 4.4.9 |
-| UI组件库 | Ant Design | 5.8.6 |
-| 3D渲染 | Three.js | 0.160.0 |
-| 后端框架 | Express | 4.18.2 |
-| ORM框架 | Sequelize | 6.32.1 |
-| 数据库 | SQLite/MySQL | 5.1.6/8.0+ |
+| React | 18.2.0 | 前端框架（用户界面开发库） |
+| Vite | 4.4.9 | 构建工具（前端项目打包工具） |
+| Ant Design | 5.8.6 | UI组件库（企业级设计系统） |
+| Three.js | 0.160.0 | 3D渲染引擎 |
+| React Router | 6.15.0 | 路由管理 |
+| Axios | 1.5.0 | HTTP客户端 |
+| 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/         # 状态管理
-│   │   └── pages/           # 页面模块
+│   │   │   ├── 3d/          # 3D可视化组件
+│   │   │   │   ├── 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/                 # 接口文档
-├── install.js                # 交互式安装脚本 ⭐ NEW
-├── update.js                 # 一键更新脚本 ⭐ NEW
+│   ├── api/                 # 接口文档
+│   └── images/              # 文档图片
+├── 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)
-✓ Nginx 配置文件已生成 (deploy/nginx-idc.conf)
+✓ PM2 配置文件已生成 (ecosystem.config.js)
+✓ 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,
diff --git a/docs/api/README.md b/docs/api/README.md
index 6129675..ac051f2 100644
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -1,6 +1,34 @@
 # API接口文档
 
-本文档描述IDC设备管理系统的后端API接口，遵循OpenAPI 3.0规范。
+本文档描述IDC设备管理系统的后端API接口，遵循RESTful设计规范。
+
+---
+
+## 目录
+
+- [基础信息](#基础信息)
+- [认证接口](#认证接口)
+- [机房管理接口](#机房管理接口)
+- [机柜管理接口](#机柜管理接口)
+- [设备管理接口](#设备管理接口)
+- [设备字段接口](#设备字段接口)
+- [设备端口接口](#设备端口接口)
+- [网卡接口](#网卡接口)
+- [线缆接口](#线缆接口)
+- [工单管理接口](#工单管理接口)
+- [工单分类接口](#工单分类接口)
+- [工单字段接口](#工单字段接口)
+- [耗材管理接口](#耗材管理接口)
+- [耗材分类接口](#耗材分类接口)
+- [耗材记录接口](#耗材记录接口)
+- [用户管理接口](#用户管理接口)
+- [角色管理接口](#角色管理接口)
+- [系统设置接口](#系统设置接口)
+- [背景配置接口](#背景配置接口)
+- [健康检查接口](#健康检查接口)
+- [错误码说明](#错误码说明)
+
+---
 
 ## 基础信息
 
@@ -10,9 +38,16 @@
 | Content-Type | `application/json` |
 | 认证方式 | Bearer Token (JWT) |
 
-## 通用响应格式
+### 通用请求头
 
-### 成功响应
+```http
+Content-Type: application/json
+Authorization: Bearer <token>
+```
+
+### 通用响应格式
+
+#### 成功响应
 
 ```json
 {
@@ -22,7 +57,7 @@
 }
 ```
 
-### 错误响应
+#### 错误响应
 
 ```json
 {
@@ -32,6 +67,32 @@
 }
 ```
 
+### 分页参数
+
+列表接口支持以下分页参数：
+
+| 参数名 | 类型 | 必填 | 默认值 | 描述 |
+|--------|------|------|--------|------|
+| page | number | 否 | 1 | 页码 |
+| pageSize | number | 否 | 10 | 每页数量 |
+
+**分页响应示例：**
+```json
+{
+  "success": true,
+  "data": {
+    "list": [...],
+    "total": 100,
+    "page": 1,
+    "pageSize": 10,
+    "totalPages": 10
+  },
+  "message": "操作成功"
+}
+```
+
+---
+
 ## 认证接口
 
 ### 用户登录
@@ -40,14 +101,14 @@
 POST /api/auth/login
 ```
 
-**请求参数**：
+**请求参数：**
 
 | 参数名 | 类型 | 必填 | 描述 |
 |--------|------|------|------|
 | username | string | 是 | 用户名 |
 | password | string | 是 | 密码 |
 
-**请求示例**：
+**请求示例：**
 
 ```json
 {
@@ -56,7 +117,7 @@ POST /api/auth/login
 }
 ```
 
-**响应示例**：
+**响应示例：**
 
 ```json
 {
@@ -66,7 +127,15 @@ POST /api/auth/login
     "user": {
       "userId": "user001",
       "username": "admin",
-      "role": "admin"
+      "email": "admin@example.com",
+      "phone": "13800138000",
+      "status": "active",
+      "Roles": [
+        {
+          "roleId": "role001",
+          "roleName": "管理员"
+        }
+      ]
     }
   },
   "message": "登录成功"
@@ -79,6 +148,49 @@ POST /api/auth/login
 POST /api/auth/register
 ```
 
+**请求参数：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| username | string | 是 | 用户名（3-20字符） |
+| password | string | 是 | 密码（6-20字符） |
+| email | string | 否 | 邮箱 |
+| phone | string | 否 | 电话 |
+
+**请求示例：**
+
+```json
+{
+  "username": "newuser",
+  "password": "password123",
+  "email": "user@example.com",
+  "phone": "13800138000"
+}
+```
+
+### 获取当前用户信息
+
+```http
+GET /api/auth/me
+```
+
+**响应示例：**
+
+```json
+{
+  "success": true,
+  "data": {
+    "userId": "user001",
+    "username": "admin",
+    "email": "admin@example.com",
+    "Roles": [...]
+  },
+  "message": "操作成功"
+}
+```
+
+---
+
 ## 机房管理接口
 
 ### 获取机房列表
@@ -87,7 +199,14 @@ POST /api/auth/register
 GET /api/rooms
 ```
 
-**响应示例**：
+**查询参数：**
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| keyword | string | 按名称搜索 |
+| status | string | 按状态筛选 |
+
+**响应示例：**
 
 ```json
 {
@@ -98,6 +217,8 @@ GET /api/rooms
       "name": "A区机房",
       "location": "一楼东侧",
       "area": 500,
+      "description": "主要服务器机房",
+      "status": "active",
       "createdAt": "2024-01-01T00:00:00.000Z",
       "updatedAt": "2024-01-01T00:00:00.000Z"
     }
@@ -112,23 +233,27 @@ GET /api/rooms
 POST /api/rooms
 ```
 
-**请求参数**：
+**请求参数：**
 
 | 参数名 | 类型 | 必填 | 描述 |
 |--------|------|------|------|
-| roomId | string | 是 | 机房ID |
+| roomId | string | 是 | 机房ID（唯一标识） |
 | name | string | 是 | 机房名称 |
 | location | string | 否 | 机房位置 |
 | area | number | 否 | 面积(平方米) |
+| description | string | 否 | 描述 |
+| status | string | 否 | 状态（active/inactive） |
 
-**请求示例**：
+**请求示例：**
 
 ```json
 {
   "roomId": "room002",
   "name": "B区机房",
   "location": "二楼西侧",
-  "area": 600
+  "area": 600,
+  "description": "网络设备机房",
+  "status": "active"
 }
 ```
 
@@ -138,12 +263,18 @@ POST /api/rooms
 PUT /api/rooms/:roomId
 ```
 
+**请求参数：** 同创建机房（roomId除外）
+
 ### 删除机房
 
 ```http
 DELETE /api/rooms/:roomId
 ```
 
+**说明：** 删除机房前需确保机房下无机柜
+
+---
+
 ## 机柜管理接口
 
 ### 获取机柜列表
@@ -152,13 +283,14 @@ DELETE /api/rooms/:roomId
 GET /api/racks
 ```
 
-**查询参数**：
+**查询参数：**
 
 | 参数名 | 类型 | 描述 |
 |--------|------|------|
 | roomId | string | 按机房ID筛选 |
+| keyword | string | 按名称搜索 |
 
-**响应示例**：
+**响应示例：**
 
 ```json
 {
@@ -175,6 +307,8 @@ GET /api/racks
         "name": "A区机房"
       },
       "Devices": [],
+      "deviceCount": 5,
+      "usedHeight": 10,
       "createdAt": "2024-01-01T00:00:00.000Z",
       "updatedAt": "2024-01-01T00:00:00.000Z"
     }
@@ -189,17 +323,18 @@ GET /api/racks
 POST /api/racks
 ```
 
-**请求参数**：
+**请求参数：**
 
 | 参数名 | 类型 | 必填 | 描述 |
 |--------|------|------|------|
-| rackId | string | 是 | 机柜ID |
+| rackId | string | 是 | 机柜ID（唯一标识） |
 | name | string | 是 | 机柜名称 |
-| height | number | 否 | 高度(U) |
+| height | number | 否 | 高度(U)，默认42 |
 | powerRating | number | 否 | 额定功率(W) |
 | RoomId | string | 是 | 所属机房ID |
+| description | string | 否 | 描述 |
 
-**请求示例**：
+**请求示例：**
 
 ```json
 {
@@ -207,7 +342,8 @@ POST /api/racks
   "name": "机柜A2",
   "height": 42,
   "powerRating": 5000,
-  "RoomId": "room001"
+  "RoomId": "room001",
+  "description": "核心交换机机柜"
 }
 ```
 
@@ -223,12 +359,43 @@ PUT /api/racks/:rackId
 DELETE /api/racks/:rackId
 ```
 
+**说明：** 删除机柜前需确保机柜下无设备
+
 ### 获取机柜详情
 
 ```http
 GET /api/racks/:rackId
 ```
 
+**响应示例：**
+
+```json
+{
+  "success": true,
+  "data": {
+    "rackId": "rack001",
+    "name": "机柜A1",
+    "height": 42,
+    "powerRating": 5000,
+    "RoomId": "room001",
+    "Room": {...},
+    "Devices": [
+      {
+        "deviceId": "dev001",
+        "name": "Web服务器01",
+        "rackPosition": 1,
+        "height": 2
+      }
+    ],
+    "createdAt": "2024-01-01T00:00:00.000Z",
+    "updatedAt": "2024-01-01T00:00:00.000Z"
+  },
+  "message": "操作成功"
+}
+```
+
+---
+
 ## 设备管理接口
 
 ### 获取设备列表
@@ -237,16 +404,18 @@ GET /api/racks/:rackId
 GET /api/devices
 ```
 
-**查询参数**：
+**查询参数：**
 
 | 参数名 | 类型 | 描述 |
 |--------|------|------|
 | rackId | string | 按机柜ID筛选 |
 | deviceType | string | 按设备类型筛选 |
+| status | string | 按状态筛选 |
+| keyword | string | 按名称/IP搜索 |
 | page | number | 页码，默认1 |
 | pageSize | number | 每页数量，默认10 |
 
-**响应示例**：
+**响应示例：**
 
 ```json
 {
@@ -270,7 +439,11 @@ GET /api/devices
         "RackId": "rack001",
         "Rack": {
           "rackId": "rack001",
-          "name": "机柜A1"
+          "name": "机柜A1",
+          "Room": {
+            "roomId": "room001",
+            "name": "A区机房"
+          }
         },
         "createdAt": "2024-01-01T00:00:00.000Z",
         "updatedAt": "2024-01-01T00:00:00.000Z"
@@ -290,26 +463,27 @@ GET /api/devices
 POST /api/devices
 ```
 
-**请求参数**：
+**请求参数：**
 
 | 参数名 | 类型 | 必填 | 描述 |
 |--------|------|------|------|
-| deviceId | string | 是 | 设备ID |
+| deviceId | string | 是 | 设备ID（唯一标识） |
 | name | string | 是 | 设备名称 |
-| deviceType | string | 是 | 设备类型 |
+| deviceType | string | 是 | 设备类型（服务器/网络设备/存储设备/其他） |
 | manufacturer | string | 否 | 厂商 |
 | model | string | 否 | 型号 |
 | RackId | string | 否 | 所属机柜ID |
-| rackPosition | number | 否 | 机柜位置 |
+| rackPosition | number | 否 | 机柜位置（从1开始） |
 | height | number | 否 | 占用高度(U) |
 | ipAddress | string | 否 | IP地址 |
 | macAddress | string | 否 | MAC地址 |
-| status | string | 否 | 状态 |
-| purchaseDate | string | 否 | 购买日期 |
-| warrantyDate | string | 否 | 保修日期 |
+| status | string | 否 | 状态（运行中/已关机/维护中/故障） |
+| purchaseDate | string | 否 | 购买日期（YYYY-MM-DD） |
+| warrantyDate | string | 否 | 保修日期（YYYY-MM-DD） |
 | description | string | 否 | 描述 |
+| customFields | object | 否 | 自定义字段值 |
 
-**请求示例**：
+**请求示例：**
 
 ```json
 {
@@ -322,7 +496,11 @@ POST /api/devices
   "rackPosition": 3,
   "height": 2,
   "ipAddress": "192.168.1.101",
-  "status": "运行中"
+  "status": "运行中",
+  "customFields": {
+    "cpuModel": "Intel Xeon E5-2680",
+    "memorySize": "64GB"
+  }
 }
 ```
 
@@ -346,13 +524,20 @@ POST /api/devices/batch-import
 
 **Content-Type**: `multipart/form-data`
 
-**请求参数**：
+**请求参数：**
 
 | 参数名 | 类型 | 必填 | 描述 |
 |--------|------|------|------|
-| file | File | 是 | CSV格式的设备数据文件 |
+| file | File | 是 | Excel或CSV格式的设备数据文件 |
 
-## 设备字段管理接口
+**文件格式要求：**
+- 支持 .xlsx, .xls, .csv 格式
+- 第一行为表头
+- 必需字段：deviceId, name, deviceType
+
+---
+
+## 设备字段接口
 
 ### 获取设备字段列表
 
@@ -360,7 +545,7 @@ POST /api/devices/batch-import
 GET /api/deviceFields
 ```
 
-**响应示例**：
+**响应示例：**
 
 ```json
 {
@@ -373,6 +558,9 @@ GET /api/deviceFields
       "fieldType": "text",
       "isRequired": false,
       "defaultValue": "",
+      "options": null,
+      "sortOrder": 1,
+      "isSystem": false,
       "createdAt": "2024-01-01T00:00:00.000Z",
       "updatedAt": "2024-01-01T00:00:00.000Z"
     }
@@ -387,28 +575,17 @@ GET /api/deviceFields
 POST /api/deviceFields
 ```
 
-**请求参数**：
+**请求参数：**
 
 | 参数名 | 类型 | 必填 | 描述 |
 |--------|------|------|------|
-| fieldName | string | 是 | 字段名(英文) |
-| displayName | string | 是 | 显示名称(中文) |
-| fieldType | string | 是 | 字段类型(text/number/date/select) |
-| isRequired | boolean | 否 | 是否必填 |
+| fieldName | string | 是 | 字段名（英文，唯一） |
+| displayName | string | 是 | 显示名称（中文） |
+| fieldType | string | 是 | 字段类型（text/number/date/select） |
+| isRequired | boolean | 否 | 是否必填，默认false |
 | defaultValue | string | 否 | 默认值 |
-| options | string | 否 | 选项(逗号分隔，select类型使用) |
-
-**请求示例**：
-
-```json
-{
-  "fieldName": "cpuModel",
-  "displayName": "CPU型号",
-  "fieldType": "text",
-  "isRequired": false,
-  "defaultValue": ""
-}
-```
+| options | string | 否 | 选项（逗号分隔，select类型使用） |
+| sortOrder | number | 否 | 排序顺序 |
 
 ### 更新设备字段
 
@@ -422,6 +599,151 @@ PUT /api/deviceFields/:id
 DELETE /api/deviceFields/:id
 ```
 
+**说明：** 系统字段（isSystem=true）不可删除
+
+---
+
+## 设备端口接口
+
+### 获取端口列表
+
+```http
+GET /api/device-ports
+```
+
+**查询参数：**
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| deviceId | string | 按设备ID筛选 |
+
+### 创建端口
+
+```http
+POST /api/device-ports
+```
+
+**请求参数：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| deviceId | string | 是 | 所属设备ID |
+| portName | string | 是 | 端口名称 |
+| portType | string | 是 | 端口类型（RJ45/SFP/SFP+/QSFP等） |
+| speed | string | 否 | 速率（10M/100M/1G/10G/25G/40G/100G） |
+| status | string | 否 | 状态（active/inactive） |
+| description | string | 否 | 描述 |
+
+### 更新端口
+
+```http
+PUT /api/device-ports/:id
+```
+
+### 删除端口
+
+```http
+DELETE /api/device-ports/:id
+```
+
+---
+
+## 网卡接口
+
+### 获取网卡列表
+
+```http
+GET /api/network-cards
+```
+
+**查询参数：**
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| deviceId | string | 按设备ID筛选 |
+
+### 创建网卡
+
+```http
+POST /api/network-cards
+```
+
+**请求参数：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| deviceId | string | 是 | 所属设备ID |
+| name | string | 是 | 网卡名称 |
+| macAddress | string | 否 | MAC地址 |
+| ipAddress | string | 否 | IP地址 |
+| portIds | array | 否 | 绑定的端口ID列表 |
+| description | string | 否 | 描述 |
+
+### 更新网卡
+
+```http
+PUT /api/network-cards/:id
+```
+
+### 删除网卡
+
+```http
+DELETE /api/network-cards/:id
+```
+
+---
+
+## 线缆接口
+
+### 获取线缆列表
+
+```http
+GET /api/cables
+```
+
+**查询参数：**
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| fromRackId | string | 按源机柜筛选 |
+| toRackId | string | 按目标机柜筛选 |
+| status | string | 按状态筛选 |
+
+### 创建线缆
+
+```http
+POST /api/cables
+```
+
+**请求参数：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| cableId | string | 是 | 线缆ID（唯一标识） |
+| name | string | 是 | 线缆名称 |
+| cableType | string | 是 | 线缆类型（光纤/网线/电源线等） |
+| fromRackId | string | 是 | 源机柜ID |
+| toRackId | string | 是 | 目标机柜ID |
+| fromPortId | string | 否 | 源端口ID |
+| toPortId | string | 否 | 目标端口ID |
+| length | number | 否 | 长度(米) |
+| status | string | 否 | 状态（active/inactive） |
+| description | string | 否 | 描述 |
+
+### 更新线缆
+
+```http
+PUT /api/cables/:id
+```
+
+### 删除线缆
+
+```http
+DELETE /api/cables/:id
+```
+
+---
+
 ## 工单管理接口
 
 ### 获取工单列表
@@ -430,16 +752,18 @@ DELETE /api/deviceFields/:id
 GET /api/tickets
 ```
 
-**查询参数**：
+**查询参数：**
 
 | 参数名 | 类型 | 描述 |
 |--------|------|------|
-| status | string | 按状态筛选 |
-| priority | string | 按优先级筛选 |
+| status | string | 按状态筛选（待处理/处理中/已完成/已关闭） |
+| priority | string | 按优先级筛选（高/中/低） |
+| categoryId | string | 按分类筛选 |
+| assigneeId | string | 按负责人筛选 |
 | page | number | 页码 |
 | pageSize | number | 每页数量 |
 
-**响应示例**：
+**响应示例：**
 
 ```json
 {
@@ -453,8 +777,20 @@ GET /api/tickets
         "status": "处理中",
         "priority": "高",
         "categoryId": "cat001",
+        "Category": {
+          "categoryId": "cat001",
+          "name": "硬件故障"
+        },
         "assigneeId": "user001",
+        "Assignee": {
+          "userId": "user001",
+          "username": "admin"
+        },
         "requesterId": "user002",
+        "Requester": {
+          "userId": "user002",
+          "username": "operator"
+        },
         "createdAt": "2024-01-01T00:00:00.000Z",
         "updatedAt": "2024-01-01T00:00:00.000Z"
       }
@@ -473,15 +809,17 @@ GET /api/tickets
 POST /api/tickets
 ```
 
-**请求参数**：
+**请求参数：**
 
 | 参数名 | 类型 | 必填 | 描述 |
 |--------|------|------|------|
 | title | string | 是 | 工单标题 |
 | description | string | 是 | 工单描述 |
 | categoryId | string | 是 | 工单分类ID |
-| priority | string | 是 | 优先级(高/中/低) |
+| priority | string | 是 | 优先级（高/中/低） |
 | assigneeId | string | 否 | 指派用户ID |
+| deviceId | string | 否 | 关联设备ID |
+| customFields | object | 否 | 自定义字段值 |
 
 ### 更新工单
 
@@ -495,58 +833,91 @@ PUT /api/tickets/:ticketId
 DELETE /api/tickets/:ticketId
 ```
 
-## 工单分类管理接口
-
-### 获取工单分类列表
+### 获取工单操作记录
 
 ```http
-GET /api/ticketCategories
+GET /api/tickets/:ticketId/operations
 ```
 
-### 创建工单分类
+---
+
+## 工单分类接口
+
+### 获取分类列表
 
 ```http
-POST /api/ticketCategories
+GET /api/ticket-categories
 ```
 
-### 更新工单分类
+### 创建分类
 
 ```http
-PUT /api/ticketCategories/:categoryId
+POST /api/ticket-categories
 ```
 
-### 删除工单分类
+**请求参数：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| categoryId | string | 是 | 分类ID（唯一标识） |
+| name | string | 是 | 分类名称 |
+| description | string | 否 | 描述 |
+| sortOrder | number | 否 | 排序顺序 |
+
+### 更新分类
 
 ```http
-DELETE /api/ticketCategories/:categoryId
+PUT /api/ticket-categories/:id
 ```
 
-## 工单字段管理接口
-
-### 获取工单字段列表
+### 删除分类
 
 ```http
-GET /api/ticketFields
+DELETE /api/ticket-categories/:id
 ```
 
-### 创建设单字段
+---
+
+## 工单字段接口
+
+### 获取字段列表
 
 ```http
-POST /api/ticketFields
+GET /api/ticket-fields
 ```
 
-### 更新工单字段
+### 创建字段
 
 ```http
-PUT /api/ticketFields/:id
+POST /api/ticket-fields
 ```
 
-### 删除工单字段
+**请求参数：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| fieldName | string | 是 | 字段名（英文，唯一） |
+| displayName | string | 是 | 显示名称（中文） |
+| fieldType | string | 是 | 字段类型（text/number/date/select/textarea） |
+| isRequired | boolean | 否 | 是否必填 |
+| defaultValue | string | 否 | 默认值 |
+| options | string | 否 | 选项（逗号分隔） |
+| sortOrder | number | 否 | 排序顺序 |
+
+### 更新字段
 
 ```http
-DELETE /api/ticketFields/:id
+PUT /api/ticket-fields/:id
 ```
 
+### 删除字段
+
+```http
+DELETE /api/ticket-fields/:id
+```
+
+---
+
 ## 耗材管理接口
 
 ### 获取耗材列表
@@ -555,7 +926,15 @@ DELETE /api/ticketFields/:id
 GET /api/consumables
 ```
 
-**响应示例**：
+**查询参数：**
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| categoryId | string | 按分类筛选 |
+| keyword | string | 按名称搜索 |
+| lowStock | boolean | 仅显示库存不足 |
+
+**响应示例：**
 
 ```json
 {
@@ -565,9 +944,14 @@ GET /api/consumables
       "consumableId": "cons001",
       "name": "硬盘",
       "categoryId": "cat001",
+      "Category": {
+        "categoryId": "cat001",
+        "name": "存储设备"
+      },
       "specification": "1TB SSD",
       "unit": "个",
       "stock": 100,
+      "minStock": 10,
       "unitPrice": 500,
       "description": "固态硬盘",
       "createdAt": "2024-01-01T00:00:00.000Z",
@@ -584,16 +968,17 @@ GET /api/consumables
 POST /api/consumables
 ```
 
-**请求参数**：
+**请求参数：**
 
 | 参数名 | 类型 | 必填 | 描述 |
 |--------|------|------|------|
-| consumableId | string | 是 | 耗材ID |
+| consumableId | string | 是 | 耗材ID（唯一标识） |
 | name | string | 是 | 耗材名称 |
 | categoryId | string | 是 | 分类ID |
 | specification | string | 否 | 规格 |
 | unit | string | 否 | 单位 |
-| stock | number | 否 | 库存数量 |
+| stock | number | 否 | 库存数量，默认0 |
+| minStock | number | 否 | 最低库存预警值 |
 | unitPrice | number | 否 | 单价 |
 | description | string | 否 | 描述 |
 
@@ -609,53 +994,80 @@ PUT /api/consumables/:consumableId
 DELETE /api/consumables/:consumableId
 ```
 
-## 耗材分类管理接口
+---
 
-### 获取耗材分类列表
+## 耗材分类接口
+
+### 获取分类列表
 
 ```http
-GET /api/consumableCategories
+GET /api/consumable-categories
 ```
 
-### 创建耗材分类
+### 创建分类
 
 ```http
-POST /api/consumableCategories
+POST /api/consumable-categories
 ```
 
-### 更新耗材分类
+**请求参数：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| categoryId | string | 是 | 分类ID（唯一标识） |
+| name | string | 是 | 分类名称 |
+| description | string | 否 | 描述 |
+
+### 更新分类
 
 ```http
-PUT /api/consumableCategories/:categoryId
+PUT /api/consumable-categories/:id
 ```
 
-### 删除耗材分类
+### 删除分类
 
 ```http
-DELETE /api/consumableCategories/:categoryId
+DELETE /api/consumable-categories/:id
 ```
 
-## 耗材领用记录接口
+---
 
-### 获取耗材领用记录
+## 耗材记录接口
+
+### 获取领用记录列表
 
 ```http
-GET /api/consumableRecords
+GET /api/consumable-records
 ```
 
-### 创建耗材领用记录
+**查询参数：**
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| consumableId | string | 按耗材筛选 |
+| userId | string | 按用户筛选 |
+| type | string | 按类型筛选（领用/归还/报废） |
+| startDate | string | 开始日期 |
+| endDate | string | 结束日期 |
+
+### 创建领用记录
 
 ```http
-POST /api/consumableRecords
+POST /api/consumable-records
 ```
 
-## 耗材日志接口
+**请求参数：**
 
-### 获取耗材日志
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| consumableId | string | 是 | 耗材ID |
+| quantity | number | 是 | 数量 |
+| type | string | 是 | 类型（领用/归还/报废） |
+| userId | string | 是 | 用户ID |
+| deviceId | string | 否 | 关联设备ID |
+| description | string | 否 | 说明 |
 
-```http
-GET /api/consumableLogs
-```
+---
 
 ## 用户管理接口
 
@@ -665,7 +1077,14 @@ GET /api/consumableLogs
 GET /api/users
 ```
 
-**响应示例**：
+**查询参数：**
+
+| 参数名 | 类型 | 描述 |
+|--------|------|------|
+| keyword | string | 按用户名/邮箱搜索 |
+| status | string | 按状态筛选 |
+
+**响应示例：**
 
 ```json
 {
@@ -677,7 +1096,12 @@ GET /api/users
       "email": "admin@example.com",
       "phone": "13800138000",
       "status": "active",
-      "Roles": [],
+      "Roles": [
+        {
+          "roleId": "role001",
+          "roleName": "管理员"
+        }
+      ],
       "createdAt": "2024-01-01T00:00:00.000Z",
       "updatedAt": "2024-01-01T00:00:00.000Z"
     }
@@ -692,15 +1116,16 @@ GET /api/users
 POST /api/users
 ```
 
-**请求参数**：
+**请求参数：**
 
 | 参数名 | 类型 | 必填 | 描述 |
 |--------|------|------|------|
-| userId | string | 是 | 用户ID |
+| userId | string | 是 | 用户ID（唯一标识） |
 | username | string | 是 | 用户名 |
 | password | string | 是 | 密码 |
 | email | string | 否 | 邮箱 |
 | phone | string | 否 | 电话 |
+| roleIds | array | 否 | 角色ID列表 |
 
 ### 更新用户
 
@@ -714,6 +1139,21 @@ PUT /api/users/:userId
 DELETE /api/users/:userId
 ```
 
+### 修改密码
+
+```http
+PUT /api/users/:userId/password
+```
+
+**请求参数：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| oldPassword | string | 是 | 旧密码 |
+| newPassword | string | 是 | 新密码 |
+
+---
+
 ## 角色管理接口
 
 ### 获取角色列表
@@ -722,7 +1162,7 @@ DELETE /api/users/:userId
 GET /api/roles
 ```
 
-**响应示例**：
+**响应示例：**
 
 ```json
 {
@@ -731,8 +1171,13 @@ GET /api/roles
     {
       "roleId": "role001",
       "roleName": "管理员",
-      "description": "系统管理员",
-      "Permissions": [],
+      "description": "系统管理员，拥有所有权限",
+      "Permissions": [
+        {
+          "permissionId": "perm001",
+          "permissionName": "设备管理"
+        }
+      ],
       "createdAt": "2024-01-01T00:00:00.000Z",
       "updatedAt": "2024-01-01T00:00:00.000Z"
     }
@@ -747,14 +1192,14 @@ GET /api/roles
 POST /api/roles
 ```
 
-**请求参数**：
+**请求参数：**
 
 | 参数名 | 类型 | 必填 | 描述 |
 |--------|------|------|------|
-| roleId | string | 是 | 角色ID |
+| roleId | string | 是 | 角色ID（唯一标识） |
 | roleName | string | 是 | 角色名称 |
 | description | string | 否 | 描述 |
-| permissions | array | 否 | 权限列表 |
+| permissionIds | array | 否 | 权限ID列表 |
 
 ### 更新角色
 
@@ -768,28 +1213,27 @@ PUT /api/roles/:roleId
 DELETE /api/roles/:roleId
 ```
 
+---
+
 ## 系统设置接口
 
 ### 获取系统设置
 
 ```http
-GET /api/systemSettings
+GET /api/system-settings
 ```
 
-**响应示例**：
+**响应示例：**
 
 ```json
 {
   "success": true,
   "data": {
-    "id": 1,
-    "key": "system_config",
-    "value": {
-      "siteName": "IDC设备管理系统",
-      "siteLogo": "/logo.png"
-    },
-    "createdAt": "2024-01-01T00:00:00.000Z",
-    "updatedAt": "2024-01-01T00:00:00.000Z"
+    "siteName": "IDC设备管理系统",
+    "siteLogo": "/uploads/logo.png",
+    "siteDescription": "专业的数据中心设备管理平台",
+    "copyright": "© 2024 IDC Management",
+    "version": "1.0.0"
   },
   "message": "操作成功"
 }
@@ -798,9 +1242,20 @@ GET /api/systemSettings
 ### 更新系统设置
 
 ```http
-PUT /api/systemSettings
+PUT /api/system-settings
 ```
 
+**请求参数：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| siteName | string | 否 | 站点名称 |
+| siteLogo | string | 否 | 站点Logo路径 |
+| siteDescription | string | 否 | 站点描述 |
+| copyright | string | 否 | 版权信息 |
+
+---
+
 ## 背景配置接口
 
 ### 获取背景配置
@@ -809,12 +1264,36 @@ PUT /api/systemSettings
 GET /api/background
 ```
 
+**响应示例：**
+
+```json
+{
+  "success": true,
+  "data": {
+    "loginBackground": "/uploads/bg/login.jpg",
+    "dashboardBackground": "/uploads/bg/dashboard.jpg",
+    "primaryColor": "#1890ff"
+  },
+  "message": "操作成功"
+}
+```
+
 ### 更新背景配置
 
 ```http
 PUT /api/background
 ```
 
+**请求参数：**
+
+| 参数名 | 类型 | 必填 | 描述 |
+|--------|------|------|------|
+| loginBackground | string | 否 | 登录页背景图 |
+| dashboardBackground | string | 否 | 仪表盘背景图 |
+| primaryColor | string | 否 | 主题主色 |
+
+---
+
 ## 健康检查接口
 
 ### 服务状态检查
@@ -823,22 +1302,138 @@ PUT /api/background
 GET /health
 ```
 
-**响应示例**：
+**响应示例：**
 
 ```json
 {
   "status": "ok",
   "message": "IDC设备管理系统后端服务正常运行",
-  "timestamp": "2024-01-01T00:00:00.000Z"
+  "timestamp": "2024-01-01T00:00:00.000Z",
+  "version": "1.0.0",
+  "uptime": 3600
 }
 ```
 
+### 数据库连接检查
+
+```http
+GET /api/health/db
+```
+
+**响应示例：**
+
+```json
+{
+  "success": true,
+  "data": {
+    "status": "connected",
+    "type": "mysql",
+    "responseTime": "5ms"
+  },
+  "message": "数据库连接正常"
+}
+```
+
+---
+
 ## 错误码说明
 
-| 错误码 | 说明 |
-|--------|------|
-| 400 | 请求参数错误 |
-| 401 | 未授权访问 |
-| 403 | 禁止访问 |
-| 404 | 资源不存在 |
-| 500 | 服务器内部错误 |
+| 状态码 | 错误码 | 说明 |
+|--------|--------|------|
+| 400 | BAD_REQUEST | 请求参数错误 |
+| 401 | UNAUTHORIZED | 未授权访问，Token无效或过期 |
+| 403 | FORBIDDEN | 禁止访问，权限不足 |
+| 404 | NOT_FOUND | 资源不存在 |
+| 409 | CONFLICT | 资源冲突（如重复ID） |
+| 422 | VALIDATION_ERROR | 数据验证失败 |
+| 500 | INTERNAL_ERROR | 服务器内部错误 |
+| 503 | SERVICE_UNAVAILABLE | 服务暂不可用 |
+
+### 常见错误示例
+
+**认证失败：**
+```json
+{
+  "success": false,
+  "error": "UNAUTHORIZED",
+  "message": "Token已过期，请重新登录"
+}
+```
+
+**参数错误：**
+```json
+{
+  "success": false,
+  "error": "VALIDATION_ERROR",
+  "message": "设备ID不能为空"
+}
+```
+
+**资源不存在：**
+```json
+{
+  "success": false,
+  "error": "NOT_FOUND",
+  "message": "设备不存在"
+}
+```
+
+**权限不足：**
+```json
+{
+  "success": false,
+  "error": "FORBIDDEN",
+  "message": "您没有权限执行此操作"
+}
+```
+
+---
+
+## 接口汇总
+
+| 接口路径 | 方法 | 描述 |
+|----------|------|------|
+| /api/auth/login | POST | 用户登录 |
+| /api/auth/register | POST | 用户注册 |
+| /api/auth/me | GET | 获取当前用户信息 |
+| /api/rooms | GET/POST | 机房列表/创建 |
+| /api/rooms/:id | PUT/DELETE | 机房更新/删除 |
+| /api/racks | GET/POST | 机柜列表/创建 |
+| /api/racks/:id | GET/PUT/DELETE | 机柜详情/更新/删除 |
+| /api/devices | GET/POST | 设备列表/创建 |
+| /api/devices/:id | PUT/DELETE | 设备更新/删除 |
+| /api/devices/batch-import | POST | 批量导入设备 |
+| /api/deviceFields | GET/POST | 设备字段列表/创建 |
+| /api/deviceFields/:id | PUT/DELETE | 设备字段更新/删除 |
+| /api/device-ports | GET/POST | 端口列表/创建 |
+| /api/device-ports/:id | PUT/DELETE | 端口更新/删除 |
+| /api/network-cards | GET/POST | 网卡列表/创建 |
+| /api/network-cards/:id | PUT/DELETE | 网卡更新/删除 |
+| /api/cables | GET/POST | 线缆列表/创建 |
+| /api/cables/:id | PUT/DELETE | 线缆更新/删除 |
+| /api/tickets | GET/POST | 工单列表/创建 |
+| /api/tickets/:id | PUT/DELETE | 工单更新/删除 |
+| /api/tickets/:id/operations | GET | 工单操作记录 |
+| /api/ticket-categories | GET/POST | 工单分类列表/创建 |
+| /api/ticket-categories/:id | PUT/DELETE | 工单分类更新/删除 |
+| /api/ticket-fields | GET/POST | 工单字段列表/创建 |
+| /api/ticket-fields/:id | PUT/DELETE | 工单字段更新/删除 |
+| /api/consumables | GET/POST | 耗材列表/创建 |
+| /api/consumables/:id | PUT/DELETE | 耗材更新/删除 |
+| /api/consumable-categories | GET/POST | 耗材分类列表/创建 |
+| /api/consumable-categories/:id | PUT/DELETE | 耗材分类更新/删除 |
+| /api/consumable-records | GET/POST | 耗材记录列表/创建 |
+| /api/users | GET/POST | 用户列表/创建 |
+| /api/users/:id | PUT/DELETE | 用户更新/删除 |
+| /api/users/:id/password | PUT | 修改密码 |
+| /api/roles | GET/POST | 角色列表/创建 |
+| /api/roles/:id | PUT/DELETE | 角色更新/删除 |
+| /api/system-settings | GET/PUT | 系统设置获取/更新 |
+| /api/background | GET/PUT | 背景配置获取/更新 |
+| /health | GET | 服务健康检查 |
+| /api/health/db | GET | 数据库健康检查 |
+
+---
+
+**文档版本：** 1.2.0  
+**最后更新：** 2026-02-05