yunrui_asset/CHANGELOG.md

# CHANGELOG

所有版本变更记录按时间倒序排列。

---

## [2.1.0] - 2026-06-12

### 新增功能

#### 设备字段必填规则与可见性同步
- 新增动态 Joi Schema 生成器（`dynamicDeviceSchema.js`），设备创建/编辑时从 `DeviceField` 表动态读取字段配置
- 前端设备表单（`DeviceFormModal`）完全适配字段管理配置，取消 `rackId/position/height` 的硬编码排除
- 新增字段管理页面防护，强制锁定系统核心字段（`name`/`serialNumber`/`position`/`height`）的必填和可见性开关
- 同步前端默认常量与后端 `initDeviceFields.js` 一致（`deviceId` required 改为 `false`，`powerConsumption` required 改为 `true`）

### 修复

- 修复字段管理页面修改配置后，设备添加/编辑页面配置不生效的问题
- 修复 `powerConsumption` 前后端默认值不一致的问题

---

## [2.0.0] - 2026-05-06

### 新增功能

#### 备份管理模块
- 新增数据库备份与恢复功能，支持手动创建备份
- 新增自动备份调度，支持 Cron 表达式配置定时备份
- 新增远端备份，支持 FTP/SFTP/WebDAV/SMB 多协议上传
- 新增备份文件上传/下载/删除/验证管理
- 新增备份恢复进度实时推送（SSE）
- 新增备份日志管理，支持日志查询/详情/清理
- 新增 BackupLog 数据模型

#### 操作日志审计模块
- 新增操作日志查询，支持按模块/操作类型/时间范围筛选
- 新增操作日志统计，提供模块和操作类型维度分析
- 新增 OperationLog 数据模型
- 新增操作日志页面，支持日志详情查看

#### 空闲设备管理模块
- 新增空闲设备列表查询与管理
- 新增设备转入空闲状态功能
- 新增空闲设备激活（重新上架）功能
- 新增 IdleDeviceManagement 前端页面

#### 仓库管理模块
- 新增仓库增删改查功能
- 新增 Warehouse 数据模型
- 支持仓库与耗材关联管理

#### 网络拓扑可视化模块
- 新增网络拓扑图可视化展示（基于 ReactFlow）
- 新增交换机拓扑查询，展示设备间连接关系
- 新增设备拓扑查询，展示单设备网络连接
- 新增拓扑控制面板（缩放/布局/筛选）
- 新增拓扑侧边栏（设备详情/连接信息）
- 新增自定义拓扑节点组件（服务器/交换机/路由器/防火墙/存储/通用）
- 新增拓扑数据与布局自定义 Hooks

#### 机房平面图模块
- 新增机房平面图可视化展示（Canvas 渲染）
- 新增机柜位置拖拽编辑功能
- 新增热力图模式，按机柜使用率着色
- 新增小地图导航，快速定位机柜
- 新增平面图工具栏（缩放/搜索/视图切换/机房选择）
- 新增机柜详情面板，展示机柜容量与设备信息
- 新增布局编辑器与位置验证器
- 新增机房布局 API（获取/更新/初始化/批量更新机柜位置）

#### 危险操作日志模块
- 新增危险操作记录功能
- 新增危险操作日志查询与清理
- 新增危险操作确认弹窗组件

#### 维护模式
- 新增维护模式状态查询与解除功能
- 新增维护模式横幅组件

#### Swagger API 文档
- 集成 swagger-jsdoc + swagger-ui-express
- 新增交互式 API 文档，访问路径 `/api-docs`
- 支持在线调试 API 接口

#### 设备管理增强
- 新增设备导入预览功能，导入前可预览数据
- 新增设备 ID 自动生成规则配置
- 新增设备搜索支持自定义字段
- 新增设备导入模板字段与字段配置同步
- 新增设备导入必填验证与机房机柜区分
- 新增设备批量导入性能优化
- 新增设备转入空闲状态 API（`PUT /api/devices/:deviceId/to-idle`）
- 新增设备 U 位可用性检查 API

#### 耗材管理增强
- 新增耗材批量导入功能（支持 Excel/CSV）
- 新增耗材导入模板下载
- 新增耗材导入任务状态查询
- 新增耗材 SN 序列号追踪功能
- 新增耗材操作日志归档功能
- 新增耗材日志修改与修改历史查询
- 新增耗材日志导出与导入
- 新增耗材出入库记录导出
- 新增耗材库存调整功能（增加/减少/设置）
- 新增耗材乐观锁并发安全控制
- 新增耗材与操作日志解耦
- 新增 ConsumableLogArchive 数据模型
- 新增耗材扫码添加功能

#### 工单管理增强
- 新增工单导出功能
- 新增工单统计页面
- 新增工单评价功能
- 新增工单操作记录（操作步骤/配件/耗时/结果）
- 新增工单分类统计 API

#### 端口与网卡管理增强
- 新增网卡批量导入功能
- 新增端口批量导出功能
- 新增端口添加引导弹窗
- 新增端口命名模板功能
- 新增端口批量导入重新设计
- 新增服务器背板面板组件
- 新增服务器网卡组件

#### 线缆管理增强
- 新增线缆向导弹窗（CableWizardModal）
- 新增设备选择弹窗性能优化
- 新新增设备选择弹窗筛选优化

#### 系统配置增强
- 新增系统设置导出/导入功能
- 新增系统 Logo 上传功能
- 新增系统信息公开查询 API
- 新增背景图片上传功能
- 新增字段管理选项可视化编辑功能

#### 业务关联
- 新增 Business 数据模型
- 新增 DeviceBusiness 数据模型
- 支持设备与业务关联管理

#### 待确认设备管理
- 新增 PendingDevice 数据模型
- 新增待确认设备管理页面
- 支持盘点暂存设备管理

### 优化

#### 3D 可视化性能优化
- 优化 Canvas DPR 配置，提升渲染清晰度
- 优化背板渲染控制，减少不必要的渲染
- 重构状态管理，分离 3D 场景状态
- 优化回调函数引用稳定性
- 优化几何体和材质复用
- 优化 LODManager 距离计算性能
- 优化 DeviceModel useFrame 状态更新
- 优化悬停状态避免频繁更新
- 优化 3D 机柜相机控制，支持完整查看
- 固定旋转中心为机柜中轴线
- 为机柜添加 U 位标识
- 优化 3D 设备视觉区分
- 新增 3D 机柜头部重新设计
- 新增纹理缓存机制（TextureCache）

#### 前端性能优化
- 优化前端组件渲染性能
- 新增虚拟列表支持（react-window）
- 新增 html2canvas 截图支持
- 优化设备详情抽屉展示

#### 安全优化
- 修复注册权限漏洞
- 修复 JWT Secret 安全问题
- 新增全局认证中间件
- 新增路由自动注册机制
- 新增路由排序 Bug 修复

#### 数据库优化
- 新增外键约束修复脚本
- 新增线缆字段迁移脚本
- 新增日志迁移脚本
- 优化迁移脚本幂等执行

### 修复

- 修复设备字段初始化覆盖自定义配置问题
- 修复设备导入必填验证问题
- 修复设备导入机房机柜区分问题
- 修复设备详情功率字段显示问题
- 修复 3D 设备详情自定义字段 displayName 显示问题
- 修复机柜已用 U 统计不准确问题
- 修复空闲设备状态不同步问题
- 修复空闲设备状态不更新问题
- 修复耗材乐观锁并发安全问题
- 修复数据恢复外键约束错误
- 修复 ID 生成器错误处理
- 修复路由排序 Bug

### 数据库模型

| 模型 | 说明 | 状态 |
|------|------|------|
| BackupLog | 备份日志 | 新增 |
| Business | 业务 | 新增 |
| ConsumableLogArchive | 耗材日志归档 | 新增 |
| DeviceBusiness | 设备业务关联 | 新增 |
| OperationLog | 操作日志 | 新增 |
| PendingDevice | 待确认设备 | 新增 |
| Warehouse | 仓库 | 新增 |

### API 接口概览

| 模块 | 接口数 | 主要功能 |
|------|--------|----------|
| 备份管理 | 28 | 备份创建/恢复/上传/下载/自动备份/远端备份/日志 |
| 统计分析 | 1 | 仪表盘统计数据 |
| 操作日志 | 5 | 日志查询/模块/类型/统计/详情 |
| 空闲设备 | 4 | 空闲设备管理 |
| 仓库管理 | 5 | 仓库增删改查 |
| 危险操作 | 3 | 危险操作日志 |
| 拓扑管理 | 2 | 网络拓扑查询 |
| 维护模式 | 2 | 维护模式管理 |
| 背景设置 | 3 | 背景配置/上传 |

### 技术栈更新

| 依赖 | 旧版本 | 新版本 | 说明 |
|------|--------|--------|------|
| Three.js | 0.160.0 | 0.183.2 | 3D 渲染引擎升级 |
| basic-ftp | - | 5.0.3 | 新增 FTP 协议支持 |
| ssh2-sftp-client | - | 9.1.0 | 新增 SFTP 协议支持 |
| webdav | - | 5.3.1 | 新增 WebDAV 协议支持 |
| smb2 | - | 0.2.2 | 新增 SMB 协议支持 |
| node-cron | - | 4.2.1 | 新增定时任务调度 |
| swagger-jsdoc | - | 新增 | API 文档生成 |
| swagger-ui-express | - | 新增 | API 文档展示 |
| framer-motion | - | 12.34.0 | 新增动画库 |
| reactflow | - | 新增 | 新增拓扑图组件 |
| dagre | - | 新增 | 新增图布局算法 |
| styled-components | - | 6.3.9 | 新增 CSS-in-JS |
| swr | - | 2.4.0 | 新增数据请求缓存 |
| html2canvas | - | 新增 | 新增截图功能 |
| react-window | - | 新增 | 新增虚拟列表 |

### 升级注意事项

- 本版本为重大更新，新增多个功能模块，建议在升级前完整备份数据库
- 新增了备份管理、操作日志、空闲设备、仓库、拓扑等数据表，首次启动时会自动创建
- 如使用 MySQL 数据库，务必运行 `node scripts/migrate-all.js` 进行数据迁移
- 3D 渲染引擎已升级到 Three.js 0.183.2，请确认浏览器兼容性
- 新增了 Swagger API 文档，可通过 `/api-docs` 访问
- JWT Secret 安全性已增强，建议更新生产环境的 JWT_SECRET 配置

---

## [1.2.0] - 2026-02-05

### 新增功能

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

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

### 优化

#### 3D可视化性能优化
- 优化 Scene.jsx 渲染配置，降低设备像素比至 [1, 1.2]
- 减小阴影贴图尺寸至 [1024, 1024]
- 移除 ContactShadows 组件以减少阴影计算
- 简化光源配置，移除冗余 pointLight
- 优化环境光分辨率配置

#### 设备模型优化
- 实现性能模式（PERFORMANCE_MODE）以简化设备细节
- 添加设备滑轨动画控制开关
- 设备弹出动画默认关闭，可通过界面开关启用
- 优化设备状态指示灯渲染性能

#### LOD（多级细节）系统
- 实现 LOD 管理器，根据相机距离自动切换设备细节级别
- 高细节模式：完整设备模型，包含所有端口和细节
- 中等细节模式：简化设备模型，使用 InstancedMesh 渲染端口
- 低细节模式：极简设备模型，仅保留基本轮廓和状态灯

### 修复

- 修复 AnimationManager 导入错误，移除对不存在文件的引用
- 修复设备在缩放时位置偏移的问题
- 修复 LOD 模型中状态灯位置计算错误
- 修复 LODManager 中的几何体参数错误

### 升级注意事项

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

---

## [1.1.0] - 2026-01-26

### 新增功能

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

#### 故障分类管理
- 新增故障分类（FaultCategory）管理
- 支持故障类型自定义

### 优化

#### 用户体验改进
- 优化页面加载速度，减少首屏渲染时间
- 改进数据表格分页机制，支持大数据量展示
- 优化表单验证提示，提供更友好的错误反馈

#### API性能优化
- 优化数据库查询，使用索引提升查询效率
- 增加API响应缓存，减少重复查询

### 修复

- 修复设备批量导入时字段映射错误的问题
- 修复工单分配给不存在用户时的错误处理
- 修复报表导出时日期格式不正确的问题
- 修复部分页面在移动端显示错位的问题

### 升级注意事项

- 本版本新增了盘点管理相关数据表，首次启动时会自动创建
- 如使用 MySQL 数据库，建议运行 `node scripts/migrate-v2.js` 进行数据迁移

---

## [1.0.0] - 2026-01-21

### 新增功能

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

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

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

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

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

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

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

### 技术架构

#### 前端技术栈
- 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 - 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 | 耗材日志 |
| InventoryPlan | 盘点计划 |
| InventoryTask | 盘点任务 |
| InventoryRecord | 盘点记录 |
| User | 用户 |
| Role | 角色 |
| Permission | 权限 |
| UserRole | 用户角色关联 |
| SystemSetting | 系统设置 |

### API接口概览

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

### 升级注意事项

- 这是初始正式版本，从 Beta/Alpha 版本升级时需注意数据迁移
- 建议在升级前备份数据库
- 首次部署需要运行 `node scripts/init-database.js` 初始化数据库

---

## 版本号规范

本项目使用语义化版本号（Semantic Versioning）：

```
主版本号.次版本号.修订号
MAJOR.MINOR.PATCH
```

| 版本类型 | 变更规则 |
|----------|----------|
| **主版本 (MAJOR)** | 不兼容的API变更 |
| **次版本 (MINOR)** | 向后兼容的新功能 |
| **修订号 (PATCH)** | 向后兼容的bug修复 |

### 版本号示例

- `1.0.0` - 初始正式版本
- `1.1.0` - 新增功能，向后兼容
- `1.1.1` - Bug修复，向后兼容
- `2.0.0` - 重大变更，不兼容

---

## 格式说明

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

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

---

## 更新日志格式

每个版本更新应包含：

```
## [版本号] - 发布日期

### 新增功能
- 功能描述

### 优化
- 改进内容

### 修复
- 修复的问题

### 升级注意事项
- 升级时需要注意的事项
```

---

**文档维护建议**：
- 每次发布新版本时及时更新本文件
- 在 `### 升级注意事项` 中详细说明可能导致不兼容的变更
- 使用清晰的描述，避免过于技术化的术语