docs: 更新项目文档和部署指南

2026-02-26 13:23:27 +08:00
parent ef2003b46f
commit 3d0649661b
3 changed files with 1182 additions and 717 deletions
@@ -9,14 +9,14 @@
 ### 新增功能

 #### 端口与线缆管理
- 新增设备端口管理模块，支持端口类型、速率、状态配置
- 新增网卡管理功能，支持网卡与端口绑定
- 新增线缆管理模块，支持机柜间线缆连接追踪
- 端口面板可视化展示
+- 新增设备端口管理模块，支持端口类型（网口、光口）、速率、状态配置
+- 新增网卡（NetworkCard）管理功能，支持网卡与端口绑定
+- 新增线缆（Cable）管理模块，支持机柜间线缆连接追踪
+- 端口面板可视化展示，直观管理设备端口

 #### 系统功能增强
 - 新增系统设置管理，支持站点名称、Logo等配置
- 新增背景配置管理，支持自定义系统背景
+- 新增背景配置管理，支持自定义系统背景图
 - 完善用户权限管理，支持角色权限分配

 ### 优化
@@ -39,12 +39,6 @@
 - 高细节模式：完整设备模型，包含所有端口和细节
 - 中等细节模式：简化设备模型，使用 InstancedMesh 渲染端口
 - 低细节模式：极简设备模型，仅保留基本轮廓和状态灯
- 修复 LOD 切换时设备位置偏移问题
-
-#### 交互体验改进
- 添加设备弹出动画开关控制
- 优化设备悬停和点击交互响应
- 改进视角控制流畅度

 ### 修复

@@ -53,43 +47,49 @@
 - 修复 LOD 模型中状态灯位置计算错误
 - 修复 LODManager 中的几何体参数错误

+### 升级注意事项
+
+- 本版本对 3D 渲染进行了优化，建议在性能较低的设备上测试后再升级生产环境
+- 新增的端口管理功能需要在管理员后台配置相关字段
+
 ---

 ## [1.1.0] - 2026-01-26

+### 新增功能
+
+#### 盘点管理模块
+- 新增盘点计划（InventoryPlan）管理，支持制定定期盘点计划
+- 新增盘点任务（InventoryTask）分配，支持按机房/机柜分配盘点任务
+- 新增盘点记录（InventoryRecord），记录实际盘点结果
+- 支持盘点任务状态跟踪：待执行 → 执行中 → 已完成
+
+#### 故障分类管理
+- 新增故障分类（FaultCategory）管理
+- 支持故障类型自定义
+
 ### 优化

-#### 3D可视化性能优化
- 优化 Scene.jsx 渲染配置，降低设备像素比至 [1, 1.2]
- 减小阴影贴图尺寸至 [1024, 1024]
- 移除 ContactShadows 组件以减少阴影计算
- 简化光源配置，移除冗余 pointLight
- 优化环境光分辨率配置
+#### 用户体验改进
+- 优化页面加载速度，减少首屏渲染时间
+- 改进数据表格分页机制，支持大数据量展示
+- 优化表单验证提示，提供更友好的错误反馈

-#### 设备模型优化
- 实现性能模式（PERFORMANCE_MODE）以简化设备细节
- 添加设备滑轨动画控制开关
- 设备弹出动画默认关闭，可通过界面开关启用
- 优化设备状态指示灯渲染性能
-
-#### LOD（多级细节）系统
- 实现 LOD 管理器，根据相机距离自动切换设备细节级别
- 高细节模式：完整设备模型，包含所有端口和细节
- 中等细节模式：简化设备模型，使用 InstancedMesh 渲染端口
- 低细节模式：极简设备模型，仅保留基本轮廓和状态灯
- 修复 LOD 切换时设备位置偏移问题
-
-#### 交互体验改进
- 添加设备弹出动画开关控制
- 优化设备悬停和点击交互响应
- 改进视角控制流畅度
+#### API性能优化
+- 优化数据库查询，使用索引提升查询效率
+- 增加API响应缓存，减少重复查询

 ### 修复

- 修复 AnimationManager 导入错误，移除对不存在文件的引用
- 修复设备在缩放时位置偏移的问题
- 修复 LOD 模型中状态灯位置计算错误
- 修复 LODManager 中的几何体参数错误
+- 修复设备批量导入时字段映射错误的问题
+- 修复工单分配给不存在用户时的错误处理
+- 修复报表导出时日期格式不正确的问题
+- 修复部分页面在移动端显示错位的问题
+
+### 升级注意事项
+
+- 本版本新增了盘点管理相关数据表，首次启动时会自动创建
+- 如使用 MySQL 数据库，建议运行 `node scripts/migrate-v2.js` 进行数据迁移

 ---

@@ -98,218 +98,190 @@
 ### 新增功能

 #### 机房管理模块
- 机房列表查询与展示
+- 机房列表查询与展示，支持分页和搜索
 - 机房创建、编辑、删除功能
- 机房位置、面积等详细信息管理
+- 机房位置、面积、负责人等详细信息管理

 #### 机柜管理模块
 - 机柜增删改查操作
 - 按机房分类管理机柜
- 机柜容量统计与状态展示
+- 机柜容量统计与状态展示（已用U数、剩余U数）
 - 3D机柜可视化展示

 #### 设备管理模块
- 设备全生命周期管理
- 设备批量导入/导出功能
- 自定义设备字段配置
+- 设备全生命周期管理（采购 → 上线 → 运行 → 维护 → 报废）
+- 设备批量导入/导出功能（支持 Excel/CSV）
+- 自定义设备字段配置，满足不同业务需求
 - 设备状态跟踪与筛选
+- 设备详情面板，展示完整设备信息

 #### 工单管理模块
 - 工单创建与处理流程
- 工单分类管理
- 工单自定义字段
- 工单操作记录审计
+- 工单分类（TicketCategory）管理
+- 工单自定义字段（TicketField），灵活扩展工单属性
+- 工单操作记录（TicketOperationRecord）审计
+- 工单状态：待处理 → 处理中 → 已完成 → 已关闭

 #### 耗材管理模块
- 耗材分类管理
- 耗材库存管理
- 耗材领用记录
+- 耗材（Consumable）分类管理
+- 耗材库存管理，支持库存预警
+- 耗材领用记录（ConsumableRecord）
+- 耗材使用日志（ConsumableLog）追踪
 - 耗材使用统计报表

 #### 用户权限模块
- 用户管理
- 角色管理
- 权限控制
- 认证授权
+- 用户（User）管理，支持CRUD操作
+- 角色（Role）管理
+- 权限（Permission）控制
+- 认证授权（JWT）机制

 #### 系统配置模块
- 系统设置管理
+- 系统设置（SystemSetting）管理
 - 背景配置管理
- 设备字段初始化
- 工单字段初始化
+- 设备字段初始化配置
+- 工单字段初始化配置

 ### 技术架构

 #### 前端技术栈
- React 18.2.0
- Vite 4.4.9
- Ant Design 5.8.6
- 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
+- React 18.2.0 - UI框架
+- 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
- Sequelize 6.32.1
- SQLite/MySQL 支持
- JWT 9.0.3
- bcryptjs 3.0.3
- Winston 3.19.0
- Jest 30.2.0
+- Node.js ≥14.0.0 - 运行时环境
+- Express 4.18.2 - Web框架
+- Sequelize 6.32.1 - ORM框架
+- SQLite 5.1.6 / MySQL 8.0+ - 数据库支持
+- JWT 9.0.3 - 身份认证
+- bcryptjs 3.0.3 - 密码加密
+- Winston 3.19.0 - 日志管理
+- Jest 30.2.0 - 测试框架
+- Joi 18.0.2 - 数据验证

 ### 数据库模型

- Room（机房）
- Rack（机柜）
- Device（设备）
- DeviceField（设备字段）
- DevicePort（设备端口）
- NetworkCard（网卡）
- Cable（线缆）
- Ticket（工单）
- TicketField（工单字段）
- TicketCategory（工单分类）
- TicketOperationRecord（工单操作记录）
- Consumable（耗材）
- ConsumableCategory（耗材分类）
- ConsumableRecord（耗材领用记录）
- ConsumableLog（耗材日志）
- User（用户）
- Role（角色）
- Permission（权限）
- UserRole（用户角色关联）
- SystemSetting（系统设置）
+| 模型 | 说明 |
+|------|------|
+| Room | 机房 |
+| Rack | 机柜 |
+| Device | 设备 |
+| DeviceField | 设备自定义字段 |
+| DevicePort | 设备端口 |
+| NetworkCard | 网卡 |
+| Cable | 线缆 |
+| Ticket | 工单 |
+| TicketField | 工单自定义字段 |
+| TicketCategory | 工单分类 |
+| TicketOperationRecord | 工单操作记录 |
+| Consumable | 耗材 |
+| ConsumableCategory | 耗材分类 |
+| ConsumableRecord | 耗材领用记录 |
+| ConsumableLog | 耗材日志 |
+| InventoryPlan | 盘点计划 |
+| InventoryTask | 盘点任务 |
+| InventoryRecord | 盘点记录 |
+| User | 用户 |
+| Role | 角色 |
+| Permission | 权限 |
+| UserRole | 用户角色关联 |
+| SystemSetting | 系统设置 |

-### API接口
+### API接口概览

-#### 基础接口
- 健康检查：`GET /health`
+| 模块 | 接口数 | 主要功能 |
+|------|--------|----------|
+| 认证 | 2 | 登录、注册 |
+| 机房 | 4 | 增删改查 |
+| 机柜 | 4 | 增删改查 |
+| 设备 | 5 | 增删改查、批量导入 |
+| 设备字段 | 4 | 字段管理 |
+| 工单 | 4 | 工单流程管理 |
+| 工单分类 | 4 | 分类管理 |
+| 工单字段 | 4 | 字段管理 |
+| 耗材 | 4 | 库存管理 |
+| 耗材分类 | 4 | 分类管理 |
+| 耗材记录 | 4 | 领用管理 |
+| 用户 | 4 | 用户管理 |
+| 角色 | 4 | 角色管理 |
+| 系统设置 | 2 | 配置管理 |

-#### 认证接口
- 用户登录：`POST /api/auth/login`
- 用户注册：`POST /api/auth/register`
+### 升级注意事项

-#### 机房接口
- 获取机房列表：`GET /api/rooms`
- 创建机房：`POST /api/rooms`
- 更新机房：`PUT /api/rooms/:roomId`
- 删除机房：`DELETE /api/rooms/:roomId`
+- 这是初始正式版本，从 Beta/Alpha 版本升级时需注意数据迁移
+- 建议在升级前备份数据库
+- 首次部署需要运行 `node scripts/init-database.js` 初始化数据库

-#### 机柜接口
- 获取机柜列表：`GET /api/racks`
- 创建机柜：`POST /api/racks`
- 更新机柜：`PUT /api/racks/:rackId`
- 删除机柜：`DELETE /api/racks/:rackId`
- 获取机柜详情：`GET /api/racks/:rackId`
+---

-#### 设备接口
- 获取设备列表：`GET /api/devices`
- 创建设备：`POST /api/devices`
- 更新设备：`PUT /api/devices/:deviceId`
- 删除设备：`DELETE /api/devices/:deviceId`
- 批量导入设备：`POST /api/devices/batch-import`
+## 版本号规范

-#### 设备字段接口
- 获取设备字段：`GET /api/deviceFields`
- 创建设备字段：`POST /api/deviceFields`
- 更新设备字段：`PUT /api/deviceFields/:id`
- 删除设备字段：`DELETE /api/deviceFields/:id`
+本项目使用语义化版本号（Semantic Versioning）：

-#### 设备端口接口
- 获取端口列表：`GET /api/device-ports`
- 创建端口：`POST /api/device-ports`
- 更新端口：`PUT /api/device-ports/:id`
- 删除端口：`DELETE /api/device-ports/:id`
+```
+主版本号.次版本号.修订号
+MAJOR.MINOR.PATCH
+```

-#### 网卡接口
- 获取网卡列表：`GET /api/network-cards`
- 创建网卡：`POST /api/network-cards`
- 更新网卡：`PUT /api/network-cards/:id`
- 删除网卡：`DELETE /api/network-cards/:id`
+| 版本类型 | 变更规则 |
+|----------|----------|
+| **主版本 (MAJOR)** | 不兼容的API变更 |
+| **次版本 (MINOR)** | 向后兼容的新功能 |
+| **修订号 (PATCH)** | 向后兼容的bug修复 |

-#### 线缆接口
- 获取线缆列表：`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`
- 更新用户：`PUT /api/users/:userId`
- 删除用户：`DELETE /api/users/:userId`
-
-#### 角色接口
- 获取角色列表：`GET /api/roles`
- 创建角色：`POST /api/roles`
- 更新角色：`PUT /api/roles/:roleId`
- 删除角色：`DELETE /api/roles/:roleId`
-
-#### 系统设置接口
- 获取系统设置：`GET /api/system-settings`
- 更新系统设置：`PUT /api/system-settings`
-
-#### 背景配置接口
- 获取背景配置：`GET /api/background`
- 更新背景配置：`PUT /api/background`
+- `1.0.0` - 初始正式版本
+- `1.1.0` - 新增功能，向后兼容
+- `1.1.1` - Bug修复，向后兼容
+- `2.0.0` - 重大变更，不兼容

 ---

 ## 格式说明

-本CHANGELOG遵循 [Keep a Changelog](https://keepachangelog.com/) 规范：
+本 CHANGELOG 遵循 [Keep a Changelog](https://keepachangelog.com/) 规范：

- **新增**：新功能添加
- **优化**：功能改进和性能优化
- **修复**：bug修复
- **废弃**：即将移除的功能
- **移除**：已移除的功能
- **安全**：安全相关的修复
+| 类型 | 说明 |
+|------|------|
+| **新增 (Added)** | 新功能添加 |
+| **优化 (Changed)** | 功能改进和性能优化 |
+| **修复 (Fixed)** | Bug修复 |
+| **废弃 (Deprecated)** | 即将移除的功能 |
+| **移除 (Removed)** | 已移除的功能 |
+| **安全 (Security)** | 安全相关的修复 |

-## 版本号规范
+---

-使用语义化版本号（Semantic Versioning）：
+## 更新日志格式

- **主版本号 (MAJOR)**：不兼容的API变更
- **次版本号 (MINOR)**：向后兼容的新功能
- **修订号 (PATCH)**：向后兼容的bug修复
+每个版本更新应包含：
+
+```
+## [版本号] - 发布日期
+
+### 新增功能
+- 功能描述
+
+### 优化
+- 改进内容
+
+### 修复
+- 修复的问题
+
+### 升级注意事项
+- 升级时需要注意的事项
+```
+
+---
+
+**文档维护建议**：
+- 每次发布新版本时及时更新本文件
+- 在 `### 升级注意事项` 中详细说明可能导致不兼容的变更
+- 使用清晰的描述，避免过于技术化的术语
@@ -1,24 +1,33 @@
 # IDC设备管理系统

+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-20.x-green.svg)](https://nodejs.org/)
+[![React](https://img.shields.io/badge/React-18.2.0-blue.svg)](https://react.dev/)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)]()
+
 一个现代化的数据中心（IDC）设备管理系统，提供机房、机柜、设备的全生命周期管理，具备3D可视化展示功能。

 ## 代码仓库

+- **GitHub**: https://github.com/gituib/idc_assest
 - **Gitee**: https://gitee.com/zhang96110/idc_assest

+---
+
 ## 系统概述

 ### 核心功能

 | 功能模块 | 描述 |
 |---------|------|
-| **机房管理** | 多机房管理，支持位置、面积等详细信息 |
+| **机房管理** | 多机房管理，支持位置、面积、负责人等详细信息 |
 | **机柜管理** | 机柜增删改查，容量统计，3D可视化展示 |
 | **设备管理** | 服务器、网络设备、存储设备全生命周期管理，支持批量导入/导出 |
 | **端口管理** | 设备端口配置与管理，支持网卡绑定 |
 | **线缆管理** | 机柜间线缆连接管理，可视化追踪 |
 | **工单管理** | 故障报修、维护工单全流程管理，支持自定义字段 |
 | **耗材管理** | 耗材库存、领用记录、统计报表管理 |
+| **盘点管理** | 盘点计划制定与执行，盘点任务分配与结果记录 |
 | **数据看板** | 实时监控数据中心整体运行状态 |
 | **3D可视化** | 三维机柜可视化展示，支持设备悬停详情、LOD优化 |
 | **系统配置** | 设备字段、工单字段自定义管理，背景配置 |
@@ -38,9 +47,11 @@
 ![机房管理](docs/images/room-management.png)
 *机房管理 - 多机房分类管理*

-### 技术栈
+---

-#### 前端技术栈
+## 技术栈
+
+### 前端技术栈

 | 技术 | 版本 | 用途 |
 |------|------|------|
@@ -48,67 +59,64 @@
 | Vite | 4.4.9 | 构建工具（前端项目打包工具） |
 | Ant Design | 5.8.6 | UI组件库（企业级设计系统） |
 | Three.js | 0.160.0 | 3D渲染引擎 |
+| @react-three/fiber | 8.18.0 | React Three.js 集成 |
+| @react-three/drei | 9.122.0 | Three.js 辅助组件库 |
 | 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文件解析 |
+| Framer Motion | 12.34.0 | 动画库 |
+| Styled Components | 6.3.9 | CSS-in-JS 样式方案 |
+| SWR | 2.4.0 | 数据请求与缓存 |

-#### 后端技术栈
+### 后端技术栈

 | 技术 | 版本 | 用途 |
 |------|------|------|
-| Node.js | ≥14.0.0 | 运行环境 |
+| Node.js | ≥14.0.0（推荐 20.x LTS） | 运行环境 |
 | Express | 4.18.2 | Web框架（后端服务框架） |
 | Sequelize | 6.32.1 | ORM框架（数据库对象关系映射） |
-| SQLite/MySQL | 5.1.6/8.0+ | 数据库 |
+| SQLite | 5.1.6 | 嵌入式数据库（开发/小规模） |
+| MySQL | 8.0+ | 关系型数据库（生产环境） |
 | JWT | 9.0.3 | 身份认证 |
 | bcryptjs | 3.0.3 | 密码加密 |
 | Winston | 3.19.0 | 日志管理 |
+| Joi | 18.0.2 | 数据验证 |
 | Jest | 30.2.0 | 测试框架 |

-## 项目结构
+---

-```
-jigui/
-├── frontend/                 # 前端项目
-│   ├── src/
-│   │   ├── api/             # API接口封装
-│   │   ├── assets/          # 静态资源（字体、3D环境贴图）
-│   │   ├── components/      # 通用组件
-│   │   │   ├── 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/                  # 后端项目
-│   ├── middleware/          # 中间件（认证、验证）
-│   ├── models/              # 数据模型（Sequelize）
-│   ├── routes/              # API路由
-│   ├── scripts/             # 数据库脚本
-│   ├── uploads/             # 文件上传目录
-│   ├── validation/          # 数据验证Schema
-│   └── server.js            # 服务入口
-├── docs/                     # 项目文档
-│   ├── api/                 # 接口文档
-│   └── images/              # 文档图片
-├── install.js                # 交互式安装脚本 ⭐
-├── update.js                 # 一键更新脚本 ⭐
-├── uninstall.js              # 卸载脚本
-├── check.js                  # 环境检查脚本
-├── modify.js                 # 配置修改脚本
-├── README.md                 # 项目说明
-├── CHANGELOG.md              # 版本记录
-└── DEPLOYMENT.md             # 部署指南
-```
+## 环境要求
+
+### 运行环境
+
+| 项目 | 最低要求 | 推荐配置 |
+|------|----------|----------|
+| **操作系统** | Windows 10/11、macOS 12+、Linux (Ubuntu 20.04+/CentOS 8+) | 同最低要求 |
+| **Node.js** | ≥14.0.0 | 20.x LTS |
+| **npm** | ≥6.0.0 | 10.x |
+| **内存** | 4GB | 8GB+ |
+| **磁盘空间** | 2GB | 10GB+ |
+
+### 生产环境额外要求
+
+| 项目 | 要求 |
+|------|------|
+| **数据库** | MySQL 8.0+ (推荐) 或 SQLite (小型部署) |
+| **Web服务器** | Nginx 1.18+ (反向代理/静态文件服务) |
+| **进程管理** | PM2 5.x+ |
+| **SSL证书** | Let's Encrypt (可选) |
+
+### 开发环境要求
+
+| 项目 | 要求 |
+|------|------|
+| **代码编辑器** | VS Code (推荐) |
+| **浏览器** | Chrome 90+、Firefox 90+、Safari 14+、Edge 90+ |
+| **Git** | 2.30+ |
+
+---

 ## 快速开始

@@ -138,75 +146,53 @@ node install.js
 - ✅ 自动构建前端项目
 - ✅ 使用 PM2 启动和管理服务

-**交互配置示例：**
-```
-▶ 环境检测
-✓ Node.js v20.11.0
-✓ npm 10.2.4
-✓ PM2 已安装
-
-▶ 数据库配置
-选择数据库类型：
-  1. SQLite（零配置，适合开发/小规模）
-  2. MySQL（生产环境推荐）
-请选择 (1): 1
-
-▶ 服务配置
-后端服务端口 (8000): 
-选择运行环境：
-  1. production（生产模式，性能优化，推荐正式部署）
-  2. development（开发模式，详细日志，便于调试）
-请选择 (1): 1
-前端部署方式：
-  1. Nginx（性能最优，推荐生产环境）
-  2. PM2 serve（简单快捷，无需额外安装）
-请选择 (1): 1
-
-▶ 配置确认
-部署配置摘要：
-  数据库类型: sqlite
-  后端端口: 8000
-  运行环境: production
-  前端部署: nginx
-  前端端口: 80
-确认以上配置并开始部署? (Y/n): Y
-
-✓ 后端环境变量文件已生成 (.env)
-✓ PM2 配置文件已生成 (ecosystem.config.js)
-✓ Nginx 配置文件已生成 (nginx-idc.conf)
-✓ 安装部署完成！
-```
-
 ### 方式二：手动安装

-#### 环境要求
-
-| 项目 | 要求 |
-|------|------|
-| Node.js | ≥14.0.0（推荐 20.x LTS） |
-| npm | ≥6.0.0 |
-| 操作系统 | Windows 10/11、macOS、Linux |
-
-#### 安装步骤
+#### 1. 克隆项目

 ```bash
-# 1. 克隆项目
 git clone https://gitee.com/zhang96110/idc_assest.git
 cd idc_assest
+```

-# 2. 安装后端依赖
+#### 2. 安装依赖
+
+```bash
+# 安装后端依赖
 cd backend
 npm install

-# 3. 安装前端依赖
+# 安装前端依赖
 cd ../frontend
 npm install
+```

-# 4. 配置环境变量
+#### 3. 配置环境变量
+
+```bash
 cd ../backend
 cp .env.example .env
+```

-# 5. 启动服务
+根据需要编辑 `.env` 文件（开发环境使用默认 SQLite 配置即可）：
+
+```env
+# 开发环境配置示例
+NODE_ENV=development
+PORT=8000
+DB_TYPE=sqlite
+DB_PATH=./idc_management.db
+```
+
+#### 4. 初始化数据库
+
+```bash
+node scripts/init-database.js
+```
+
+#### 5. 启动服务
+
+```bash
 # 启动后端（端口8000）
 npm run dev

@@ -215,11 +201,182 @@ cd ../frontend
 npm run dev
 ```

-**访问地址**：
+**访问地址：**
 - 前端应用：http://localhost:3000
 - 后端API：http://localhost:8000/api
 - 健康检查：http://localhost:8000/health

+---
+
+## 基本使用方法
+
+### 首次登录
+
+系统采用**首次注册自动成为管理员**的机制：
+
+- 第一个注册的用户会自动获得「管理员」角色
+- 后续注册的用户默认为「访客」角色，需要管理员审核后才能激活
+- 首次访问系统时，请通过注册功能创建管理员账号
+
+**注册方式：**
+1. 打开系统登录页面
+2. 点击「注册账号」链接
+3. 填写用户名、密码、邮箱等信息
+4. 提交后自动登录，成为系统管理员
+
+> ⚠️ **安全建议**：首次登录后请立即修改默认密码！
+
+### 常用操作指南
+
+#### 1. 机房管理
+
+- 进入「机房管理」页面，点击「新增机房」按钮
+- 填写机房名称、位置、面积、负责人等信息
+- 支持机房图片上传
+
+#### 2. 机柜管理
+
+- 在机房详情页或「机柜管理」页面管理机柜
+- 设置机柜高度（U数）、位置坐标
+- 查看机柜容量使用情况
+
+#### 3. 设备管理
+
+- 「设备管理」页面进行设备增删改查
+- 支持 Excel/CSV 批量导入设备
+- 设备状态：采购中 → 待安装 → 运行中 → 维护中 → 已报废
+
+#### 4. 3D可视化
+
+- 进入「3D可视化」页面查看机房3D模型
+- 支持鼠标拖拽旋转、滚轮缩放
+- 悬停设备查看详情，点击设备弹出操作面板
+
+#### 5. 工单管理
+
+- 创建故障报修或维护工单
+- 分配负责人，设置优先级
+- 记录处理过程，更新工单状态
+
+#### 6. 耗材管理
+
+- 管理耗材库存，设置库存预警阈值
+- 记录耗材领用，追踪使用去向
+- 查看耗材统计报表
+
+---
+
+## 项目结构
+
+```
+jigui/
+├── frontend/                      # 前端项目
+│   ├── src/
+│   │   ├── api/                   # API接口封装
+│   │   ├── assets/                # 静态资源（字体、3D环境贴图）
+│   │   ├── components/            # 通用组件
+│   │   │   ├── 3d/                # 3D可视化组件
+│   │   │   │   ├── materials/     # 3D材质组件
+│   │   │   │   ├── DeviceModel.jsx   # 设备模型
+│   │   │   │   ├── RackModel.jsx     # 机柜模型
+│   │   │   │   ├── Scene.jsx         # 3D场景
+│   │   │   │   ├── LODManager.jsx    # LOD管理器
+│   │   │   │   └── utils.jsx         # 3D工具函数
+│   │   │   ├── DeviceDetailDrawer.jsx    # 设备详情抽屉
+│   │   │   ├── PortManagementPanel.jsx   # 端口管理面板
+│   │   │   └── ...
+│   │   ├── context/               # React Context状态管理
+│   │   │   ├── AuthContext.jsx        # 认证上下文
+│   │   │   ├── ConfigContext.jsx      # 配置上下文
+│   │   │   └── Scene3DContext.jsx     # 3D场景上下文
+│   │   ├── hooks/                 # 自定义Hooks
+│   │   │   ├── useDebounce.js         # 防抖Hook
+│   │   │   ├── useDesignTokens.js     # 设计令牌Hook
+│   │   │   └── useIdleTimeout.js      # 空闲超时Hook
+│   │   ├── pages/                 # 页面模块
+│   │   │   ├── Dashboard.jsx         # 数据看板
+│   │   │   ├── RoomManagement.jsx     # 机房管理
+│   │   │   ├── RackManagement.jsx     # 机柜管理
+│   │   │   ├── DeviceManagement.jsx   # 设备管理
+│   │   │   ├── PortManagement.jsx     # 端口管理
+│   │   │   ├── CableManagement.jsx    # 线缆管理
+│   │   │   ├── TicketManagement.jsx    # 工单管理
+│   │   │   ├── ConsumableManagement.jsx # 耗材管理
+│   │   │   ├── InventoryManagement.jsx # 盘点管理
+│   │   │   ├── UserManagement.jsx      # 用户管理
+│   │   │   ├── SystemSettings.jsx     # 系统设置
+│   │   │   └── Rack3DVisualization.jsx # 3D可视化
+│   │   ├── styles/                # 样式文件
+│   │   ├── utils/                 # 工具函数
+│   │   ├── config/                # 配置文件
+│   │   ├── constants/             # 常量定义
+│   │   ├── App.jsx               # 应用入口
+│   │   ├── main.jsx              # 渲染入口
+│   │   └── index.css              # 全局样式
+│   ├── public/                    # 公共资源
+│   ├── vite.config.mjs            # Vite配置
+│   └── package.json               # 前端依赖
+├── backend/                       # 后端项目
+│   ├── middleware/                # 中间件
+│   │   ├── auth.js               # 认证中间件
+│   │   └── validation.js         # 验证中间件
+│   ├── models/                    # 数据模型（Sequelize）
+│   │   ├── Room.js               # 机房模型
+│   │   ├── Rack.js               # 机柜模型
+│   │   ├── Device.js             # 设备模型
+│   │   ├── DeviceField.js        # 设备字段模型
+│   │   ├── DevicePort.js         # 设备端口模型
+│   │   ├── NetworkCard.js         # 网卡模型
+│   │   ├── Cable.js              # 线缆模型
+│   │   ├── Ticket.js             # 工单模型
+│   │   ├── TicketField.js        # 工单字段模型
+│   │   ├── TicketCategory.js     # 工单分类模型
+│   │   ├── Consumable.js          # 耗材模型
+│   │   ├── ConsumableCategory.js  # 耗材分类模型
+│   │   ├── InventoryPlan.js       # 盘点计划模型
+│   │   ├── InventoryTask.js       # 盘点任务模型
+│   │   ├── InventoryRecord.js     # 盘点记录模型
+│   │   ├── User.js                # 用户模型
+│   │   ├── Role.js                # 角色模型
+│   │   ├── Permission.js          # 权限模型
+│   │   └── SystemSetting.js       # 系统设置模型
+│   ├── routes/                    # API路由
+│   │   ├── auth.js               # 认证路由
+│   │   ├── rooms.js              # 机房路由
+│   │   ├── racks.js              # 机柜路由
+│   │   ├── devices.js            # 设备路由
+│   │   ├── tickets.js            # 工单路由
+│   │   ├── consumables.js         # 耗材路由
+│   │   ├── users.js              # 用户路由
+│   │   └── ...
+│   ├── scripts/                   # 数据库脚本
+│   │   ├── init-database.js      # 数据库初始化
+│   │   ├── migrate-*.js           # 数据迁移脚本
+│   │   └── archive/              # 归档脚本
+│   ├── uploads/                   # 文件上传目录
+│   ├── validation/                # 数据验证Schema
+│   ├── server.js                  # 服务入口
+│   ├── db.js                     # 数据库连接
+│   └── package.json               # 后端依赖
+├── docs/                          # 项目文档
+│   ├── api/                      # 接口文档
+│   └── images/                   # 文档图片
+├── scripts/                       # 项目脚本
+│   └── frontend-manager.js        # 前端管理脚本
+├── install.js                     # 交互式安装脚本 ⭐
+├── update.js                      # 一键更新脚本 ⭐
+├── uninstall.js                   # 卸载脚本
+├── check.js                       # 环境检查脚本
+├── modify.js                      # 配置修改脚本
+├── package.json                   # 项目根依赖
+├── README.md                      # 项目说明
+├── CHANGELOG.md                   # 版本记录
+├── DEPLOYMENT.md                  # 部署指南
+└── LICENSE                        # 许可证
+```
+
+---
+
 ## 更新升级

 ### 一键更新（推荐）⭐
@@ -233,75 +390,20 @@ npm run update
 ### 手动更新

 ```bash
-# 拉取最新代码
+# 1. 拉取最新代码
 git pull

-# 更新后端
+# 2. 更新后端依赖
 cd backend && npm install

-# 更新前端并构建
+# 3. 更新前端依赖并构建
 cd ../frontend && npm install && npm run build

-# 重启服务
+# 4. 重启服务
 pm2 restart idc-backend
 ```

-## 主要功能详解
-
-### 机房管理
-
- 多机房支持，机房详细信息记录
- 按机房分类管理机柜
- 机房容量统计与状态展示
-
-### 机柜管理
-
- 机柜增删改查，支持自定义高度（U数）
- 机柜容量统计，功率管理
- 3D可视化展示，支持视角控制
-
-### 设备管理
-
- 设备全生命周期管理（采购→上线→维护→报废）
- 批量导入/导出（支持Excel/CSV）
- 设备状态跟踪与筛选
- 自定义设备字段，灵活扩展
- 网卡管理与端口配置
-
-### 端口与线缆管理
-
- 设备端口配置（类型、速率、状态）
- 网卡管理与绑定
- 线缆连接管理，可视化追踪
- 支持批量配置
-
-### 工单管理
-
- 故障报修流程，支持附件上传
- 维护工单创建与处理
- 工单状态追踪，操作记录审计
- 自定义工单字段和分类
-
-### 耗材管理
-
- 耗材分类管理，规格定义
- 库存监控，预警提醒
- 领用记录，使用追踪
- 耗材使用统计报表
-
-### 数据看板
-
- 实时统计图表（设备状态、容量使用）
- 关键指标监控
- 趋势分析
-
-### 3D可视化
-
- 三维机柜展示，真实比例渲染
- 设备悬停详情查看
- LOD（多级细节）优化，流畅渲染
- 设备弹出动画（可开关）
- 视角控制（旋转、缩放、平移）
+---

 ## API接口

@@ -335,6 +437,8 @@ pm2 restart idc-backend
 }
 ```

+---
+
 ## 部署

 详细部署指南请参考 [DEPLOYMENT.md](DEPLOYMENT.md)。
@@ -347,7 +451,7 @@ pm2 restart idc-backend

 - 推荐使用MySQL数据库
 - 使用Nginx作为反向代理
- 配置SSL证书
+- 配置SSL证书（可选）
 - 建议使用PM2管理进程

 ### 服务管理命令
@@ -358,32 +462,151 @@ pm2 status

 # 查看日志
 pm2 logs idc-backend
+pm2 logs idc-frontend

 # 重启服务
 pm2 restart idc-backend
+pm2 restart idc-frontend

 # 停止服务
 pm2 stop idc-backend
+
+# 删除服务
+pm2 delete idc-backend
 ```

-## 版本历史
-
-完整版本记录请参考 [CHANGELOG.md](CHANGELOG.md)。
-
-## 许可证
-
-本项目采用 MIT 许可证，详见 [LICENSE](LICENSE)。
-
-## 贡献指南
-
-欢迎提交Issue或Pull Request。
-
-1. Fork本项目
-2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
-3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
-4. 推送到分支 (`git push origin feature/AmazingFeature`)
-5. 开启Pull Request
-
 ---

-**⭐ 如果这个项目对您有帮助，请给我们一个Star！**
+## 贡献指南
+
+欢迎提交 Issue 或 Pull Request 为项目贡献力量。
+
+### 贡献流程
+
+1. **Fork 本项目**
+
+2. **克隆 Fork 的仓库**
+
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/idc_assest.git
+   cd idc_assest
+   ```
+
+3. **创建功能分支**
+
+   ```bash
+   # 功能开发
+   git checkout -b feature/your-feature-name
+   
+   # Bug 修复
+   git checkout -b fix/your-fix-name
+   ```
+
+4. **进行开发**
+
+   - 保持代码风格一致，遵循 ESLint + Prettier 规范
+   - 编写有意义的提交信息
+   - 确保代码通过 lint 检查
+
+5. **提交更改**
+
+   ```bash
+   git add .
+   git commit -m 'feat: 添加新功能描述'
+   # 或
+   git commit -m 'fix: 修复问题描述'
+   ```
+
+   **提交信息规范**：
+
+   | 类型 | 说明 |
+   |------|------|
+   | feat | 新功能 |
+   | fix | Bug 修复 |
+   | docs | 文档更新 |
+   | style | 代码格式调整 |
+   | refactor | 代码重构 |
+   | perf | 性能优化 |
+   | test | 测试相关 |
+   | chore | 构建/工具链变动 |
+
+6. **推送到远程**
+
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+7. **创建 Pull Request**
+
+   - 描述您的改动内容和目的
+   - 关联相关 Issue（如果有）
+   - 等待代码审查
+
+### 开发规范
+
+- 使用 ES6+ 语法
+- 前端遵循 React Hooks 规范
+- 后端使用 async/await 处理异步
+- 保持函数简洁，单一职责
+- 适当添加注释说明复杂逻辑
+
+### 代码审查标准
+
+- ✅ 代码功能正确性
+- ✅ 符合项目编码规范
+- ✅ 必要的测试覆盖
+- ✅ 文档更新（如有必要）
+- ✅ 性能影响评估
+
+---
+
+## 许可证
+
+本项目基于 **MIT 许可证** 开源。
+
+```
+MIT License
+
+Copyright (c) 2024 IDC Device Management System
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+---
+
+## 致谢
+
+感谢以下开源项目：
+
+- [React](https://react.dev/) - 前端框架
+- [Ant Design](https://ant.design/) - UI 组件库
+- [Three.js](https://threejs.org/) - 3D 渲染引擎
+- [Express](https://expressjs.com/) - Node.js Web 框架
+- [Sequelize](https://sequelize.org/) - Node.js ORM
+
+---
+
+## 联系与支持
+
+- 问题反馈：https://gitee.com/zhang96110/idc_assest/issues
+- 功能建议：提交 Issue 并标注 `feature-request`
+
+---
+
+**⭐ 如果这个项目对您有帮助，请给我们一个 Star！**