1037 lines
43 KiB
Markdown
1037 lines
43 KiB
Markdown
# 设备与资产域 - 详细设计
|
||
|
||
**文档编号**: DETAIL-ASSET
|
||
**版本**: v1.0
|
||
**模块**: module-asset
|
||
**生成日期**: 2026-05-18
|
||
**数据来源**: ether-pms/module-asset 实际代码 + REVERSE-ASSET.md 反推文档
|
||
|
||
---
|
||
|
||
## 一、功能点清单
|
||
|
||
| 功能ID | 功能名称 | 优先级 | 实现状态 | 对应需求ID |
|
||
|--------|----------|--------|----------|------------|
|
||
| ASSET-001 | 设备台账CRUD | P0 | 已完成 | 03-ASSET-001 |
|
||
| ASSET-002 | 设备批量删除 | P1 | 已完成 | 03-ASSET-001 |
|
||
| ASSET-003 | 设备按项目查询 | P0 | 已完成 | 03-ASSET-002 |
|
||
| ASSET-004 | 设备按空间查询 | P0 | 已完成 | 03-ASSET-002 |
|
||
| ASSET-005 | 设备按类型查询 | P1 | 已完成 | 03-ASSET-002 |
|
||
| ASSET-006 | 设备按归属查询 | P1 | 已完成 | 03-ASSET-002 |
|
||
| ASSET-007 | 设备按类型统计 | P1 | 已完成 | 03-ASSET-003 |
|
||
| ASSET-008 | 设备按归属统计 | P1 | 已完成 | 03-ASSET-003 |
|
||
| ASSET-009 | 项目设备总数 | P1 | 已完成 | 03-ASSET-003 |
|
||
| ASSET-010 | 电梯扩展表管理 | P0 | 已完成 | 03-ASSET-004 |
|
||
| ASSET-011 | 暖通扩展表管理 | P0 | 已完成 | 03-ASSET-004 |
|
||
| ASSET-012 | 消防扩展表管理 | P0 | 已完成 | 03-ASSET-004 |
|
||
| ASSET-013 | 能源计量扩展表管理 | P0 | 已完成 | 03-ASSET-004 |
|
||
| ASSET-014 | 设备Excel导入 | P1 | 已完成 | 03-ASSET-005 |
|
||
| ASSET-015 | 设备Excel导出 | P1 | 已完成 | 03-ASSET-005 |
|
||
| ASSET-016 | 设备健康评分计算 | P1 | Beta | 03-ASSET-006 |
|
||
| ASSET-017 | 设备健康历史查询 | P1 | Beta | 03-ASSET-006 |
|
||
| ASSET-018 | MTBF计算 | P1 | Beta | 03-ASSET-006 |
|
||
| ASSET-019 | MTTR计算 | P1 | Beta | 03-ASSET-006 |
|
||
| ASSET-020 | 故障历史记录 | P0 | 已完成 | 03-ASSET-007 |
|
||
| ASSET-021 | 故障历史查询 | P0 | 已完成 | 03-ASSET-007 |
|
||
| ASSET-022 | 归属主体CRUD | P1 | 已完成 | 03-ASSET-008 |
|
||
| ASSET-023 | 归属主体按类型查询 | P1 | 已完成 | 03-ASSET-008 |
|
||
| ASSET-024 | 设备照片管理 | P2 | 已完成 | 03-ASSET-009 |
|
||
| ASSET-025 | 设备文档管理 | P2 | 已完成 | 03-ASSET-009 |
|
||
| ASSET-026 | 设备二维码 | P2 | 未实现 | 03-ASSET-010 |
|
||
| ASSET-027 | IoT集成 | P3 | 未实现 | 03-ASSET-011 |
|
||
| ASSET-028 | 故障自动工单(事件驱动) | P2 | 未实现 | 03-ASSET-012 |
|
||
| ASSET-029 | 维保到期定时提醒 | P2 | 未实现 | 03-ASSET-013 |
|
||
|
||
---
|
||
|
||
## 二、数据结构设计
|
||
|
||
### 2.1 实体定义
|
||
|
||
#### 2.1.1 Equipment（设备主表）
|
||
|
||
**表名**: `asset_equipment`
|
||
**实体类**: `com.ether.pms.asset.entity.Equipment`
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| id | UUID | 是 | 自动生成 | 主键 |
|
||
| projectId | UUID | 是 | - | 所属项目ID |
|
||
| spaceNodeId | UUID | 否 | - | 关联空间节点ID |
|
||
| equipmentCode | VARCHAR(50) | 是 | - | 设备编码，全局唯一 |
|
||
| equipmentName | VARCHAR(100) | 是 | - | 设备名称 |
|
||
| equipmentType | VARCHAR(30) | 是 | - | 设备类型枚举（10种） |
|
||
| equipmentCategory | VARCHAR(50) | 否 | - | 设备分类 |
|
||
| systemType | VARCHAR(50) | 否 | - | 系统类型枚举（9种） |
|
||
| ownershipType | VARCHAR(20) | 是 | PROJECT | 归属类型枚举（4种） |
|
||
| owningEntityId | UUID | 否 | - | 归属主体ID |
|
||
| owningEntityName | VARCHAR(100) | 否 | - | 归属主体名称（冗余） |
|
||
| assetCode | VARCHAR(50) | 否 | - | 资产编号 |
|
||
| serialNumber | VARCHAR(100) | 否 | - | 出厂编号 |
|
||
| model | VARCHAR(100) | 否 | - | 型号 |
|
||
| manufacturer | VARCHAR(100) | 否 | - | 厂商 |
|
||
| supplier | VARCHAR(100) | 否 | - | 供应商 |
|
||
| status | VARCHAR(20) | 是 | ACTIVE | 设备状态枚举（4种） |
|
||
| operationStatus | VARCHAR(20) | 否 | - | 运行状态 |
|
||
| installationLocation | VARCHAR(200) | 否 | - | 安装位置 |
|
||
| installationDate | DATE | 否 | - | 安装日期 |
|
||
| designLifeYears | INTEGER | 否 | - | 设计寿命(年) |
|
||
| ratedPower | DECIMAL(10,2) | 否 | - | 额定功率(kW) |
|
||
| ratedVoltage | VARCHAR(20) | 否 | - | 额定电压(V) |
|
||
| ratedCurrent | DECIMAL(10,2) | 否 | - | 额定电流(A) |
|
||
| maintenanceVendor | VARCHAR(100) | 否 | - | 维保商 |
|
||
| maintenanceVendorContact | VARCHAR(50) | 否 | - | 维保联系人 |
|
||
| maintenanceVendorPhone | VARCHAR(20) | 否 | - | 维保电话 |
|
||
| maintenanceContractNo | VARCHAR(50) | 否 | - | 维保合同编号 |
|
||
| maintenanceContractStart | DATE | 否 | - | 维保合同开始日期 |
|
||
| maintenanceContractEnd | DATE | 否 | - | 维保合同结束日期 |
|
||
| purchaseDate | DATE | 否 | - | 购置日期 |
|
||
| purchasePrice | DECIMAL(12,2) | 否 | - | 购置价格(元) |
|
||
| warrantyExpireDate | DATE | 否 | - | 保修到期日期 |
|
||
| energyConsumptionStandard | DECIMAL(12,2) | 否 | - | 能耗标准(kW*h/年) |
|
||
| inspectionCycle | INTEGER | 否 | - | 年检周期(月) |
|
||
| nextInspectionDate | DATE | 否 | - | 下次年检日期 |
|
||
| lastInspectionDate | DATE | 否 | - | 上次年检日期 |
|
||
| lastInspectionResult | VARCHAR(20) | 否 | - | 上次年检结果 |
|
||
| specialEquipmentType | VARCHAR(50) | 否 | - | 特种设备类型 |
|
||
| specialEquipmentCert | VARCHAR(100) | 否 | - | 特种设备证书 |
|
||
| attributes | JSON/TEXT | 否 | - | 扩展属性(JSON) |
|
||
| photos | JSONB | 否 | - | 设备照片列表(List\<EquipmentPhoto\>) |
|
||
| documents | JSONB | 否 | - | 电子文档列表(List\<EquipmentDocument\>) |
|
||
| manualUrl | VARCHAR(500) | 否 | - | 手册URL |
|
||
| remarks | VARCHAR(1000) | 否 | - | 备注 |
|
||
| isDeleted | BOOLEAN | 否 | false | 逻辑删除标记 |
|
||
| createdAt | DATETIME | 是 | now() | 创建时间 |
|
||
| updatedAt | DATETIME | 是 | now() | 更新时间 |
|
||
| createdBy | UUID | 否 | - | 创建人 |
|
||
| updatedBy | UUID | 否 | - | 更新人 |
|
||
|
||
**索引**:
|
||
|
||
| 索引名 | 字段 | 类型 | 用途 |
|
||
|--------|------|------|------|
|
||
| idx_equipment_project | project_id | 普通索引 | 按项目查询 |
|
||
| idx_equipment_space | space_node_id | 普通索引 | 按空间查询 |
|
||
| idx_equipment_type | equipment_type | 普通索引 | 按类型查询 |
|
||
| idx_equipment_ownership | ownership_type | 普通索引 | 按归属查询 |
|
||
| idx_equipment_code | equipment_code | 唯一索引 | 编码唯一性 |
|
||
| idx_equipment_status | status | 普通索引 | 按状态查询 |
|
||
| idx_eq_project_status | project_id, status | 联合索引 | 项目+状态组合查询 |
|
||
| idx_eq_project_type | project_id, equipment_type | 联合索引 | 项目+类型组合查询 |
|
||
| idx_eq_project_deleted | project_id, is_deleted | 联合索引 | 项目+未删除组合查询 |
|
||
|
||
**内嵌类型**:
|
||
|
||
EquipmentPhoto（设备照片）:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| type | String | 照片类型：外观/铭牌/安装位置/环境 |
|
||
| url | String | 照片URL |
|
||
| remark | String | 备注 |
|
||
|
||
EquipmentDocument（电子文档）:
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| name | String | 文档名称 |
|
||
| url | String | 文档URL |
|
||
| size | Long | 文件大小 |
|
||
| type | String | 文档类型：manual/certificate/contract/other |
|
||
| remark | String | 备注 |
|
||
|
||
#### 2.1.2 EquipmentElevator（电梯扩展表）
|
||
|
||
**表名**: `asset_equipment_elevator`
|
||
**实体类**: `com.ether.pms.asset.entity.EquipmentElevator`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | UUID | 是 | 主键 |
|
||
| equipmentId | UUID | 是 | 关联设备ID（UNIQUE外键） |
|
||
| elevatorType | VARCHAR(30) | 否 | 电梯类型 |
|
||
| elevatorModel | VARCHAR(50) | 否 | 电梯型号 |
|
||
| loadCapacity | INTEGER | 否 | 载重(kg) |
|
||
| speed | DECIMAL(10,2) | 否 | 速度(m/s) |
|
||
| floorCount | INTEGER | 否 | 楼层数 |
|
||
| shaftDimensions | VARCHAR(50) | 否 | 井道尺寸 |
|
||
| pitDepth | DECIMAL(10,2) | 否 | 底坑深度 |
|
||
| overheadHeight | DECIMAL(10,2) | 否 | 顶层高度 |
|
||
| registrationNo | VARCHAR(50) | 否 | 注册登记号 |
|
||
| inspectionCertificate | VARCHAR(100) | 否 | 检验证书 |
|
||
| nextInspectionDate | DATE | 否 | 下次检验日期 |
|
||
| energyConsumption | DECIMAL(12,2) | 否 | 能耗 |
|
||
| maintenanceLevel | VARCHAR(20) | 否 | 维保等级 |
|
||
| rescuePlan | VARCHAR(5000) | 否 | 应急救援预案 |
|
||
| createdAt | DATETIME | 否 | 创建时间 |
|
||
| updatedAt | DATETIME | 否 | 更新时间 |
|
||
|
||
#### 2.1.3 EquipmentHvac（暖通空调扩展表）
|
||
|
||
**表名**: `asset_equipment_hvac`
|
||
**实体类**: `com.ether.pms.asset.entity.EquipmentHvac`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | UUID | 是 | 主键 |
|
||
| equipmentId | UUID | 是 | 关联设备ID（UNIQUE外键） |
|
||
| hvacType | VARCHAR(30) | 否 | 暖通类型 |
|
||
| coolingCapacity | DECIMAL(12,2) | 否 | 制冷量 |
|
||
| heatingCapacity | DECIMAL(12,2) | 否 | 制热量 |
|
||
| airFlow | DECIMAL(12,2) | 否 | 风量 |
|
||
| refrigerantType | VARCHAR(30) | 否 | 制冷剂类型 |
|
||
| refrigerantCharge | DECIMAL(10,2) | 否 | 制冷剂充注量 |
|
||
| energyEfficiencyRatio | DECIMAL(10,2) | 否 | 能效比(EER) |
|
||
| coefficientOfPerformance | DECIMAL(10,2) | 否 | 性能系数(COP) |
|
||
| installationDate | DATE | 否 | 安装日期 |
|
||
| warrantyExpireDate | DATE | 否 | 保修到期日期 |
|
||
| filterReplacementCycle | INTEGER | 否 | 滤网更换周期 |
|
||
| lastFilterReplacement | DATE | 否 | 上次滤网更换日期 |
|
||
| ductType | VARCHAR(30) | 否 | 风管类型 |
|
||
| ductDimensions | VARCHAR(50) | 否 | 风管尺寸 |
|
||
| createdAt | DATETIME | 否 | 创建时间 |
|
||
| updatedAt | DATETIME | 否 | 更新时间 |
|
||
|
||
#### 2.1.4 EquipmentFire（消防扩展表）
|
||
|
||
**表名**: `asset_equipment_fire`
|
||
**实体类**: `com.ether.pms.asset.entity.EquipmentFire`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | UUID | 是 | 主键 |
|
||
| equipmentId | UUID | 是 | 关联设备ID（UNIQUE外键） |
|
||
| fireEquipmentType | VARCHAR(30) | 否 | 消防设备类型 |
|
||
| installationArea | DECIMAL(10,2) | 否 | 安装面积 |
|
||
| installationHeight | DECIMAL(10,2) | 否 | 安装高度 |
|
||
| detectionRange | DECIMAL(10,2) | 否 | 探测范围 |
|
||
| systemType | VARCHAR(30) | 否 | 系统类型 |
|
||
| zoneNumber | VARCHAR(20) | 否 | 分区编号 |
|
||
| loopNumber | VARCHAR(20) | 否 | 回路编号 |
|
||
| linkageEnabled | BOOLEAN | 否 | 是否启用联动 |
|
||
| linkageAction | VARCHAR(100) | 否 | 联动动作 |
|
||
| inspectionCycle | INTEGER | 否 | 巡检周期 |
|
||
| lastInspectionDate | DATE | 否 | 上次巡检日期 |
|
||
| nextInspectionDate | DATE | 否 | 下次巡检日期 |
|
||
| inspectionResult | VARCHAR(20) | 否 | 巡检结果 |
|
||
| specialRequirement | VARCHAR(2000) | 否 | 特殊要求 |
|
||
| createdAt | DATETIME | 否 | 创建时间 |
|
||
| updatedAt | DATETIME | 否 | 更新时间 |
|
||
|
||
#### 2.1.5 EquipmentEnergy（能源计量扩展表）
|
||
|
||
**表名**: `asset_equipment_energy`
|
||
**实体类**: `com.ether.pms.asset.entity.EquipmentEnergy`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | UUID | 是 | 主键 |
|
||
| equipmentId | UUID | 是 | 关联设备ID（UNIQUE外键） |
|
||
| meterType | VARCHAR(30) | 否 | 表计类型 |
|
||
| energyType | VARCHAR(30) | 否 | 能源类型 |
|
||
| meterModel | VARCHAR(50) | 否 | 表计型号 |
|
||
| meterSpecification | VARCHAR(50) | 否 | 表计规格 |
|
||
| meterConstant | DECIMAL(10,4) | 否 | 表常数 |
|
||
| accuracyClass | VARCHAR(10) | 否 | 精度等级 |
|
||
| readingType | VARCHAR(20) | 否 | 抄表方式 |
|
||
| lastReadingDate | DATE | 否 | 上次抄表日期 |
|
||
| lastReadingValue | DECIMAL(12,2) | 否 | 上次读数 |
|
||
| currentReadingValue | DECIMAL(12,2) | 否 | 当前读数 |
|
||
| unitPrice | DECIMAL(10,4) | 否 | 单价 |
|
||
| billingType | VARCHAR(20) | 否 | 计费方式 |
|
||
| communicationType | VARCHAR(30) | 否 | 通讯方式 |
|
||
| communicationAddress | VARCHAR(50) | 否 | 通讯地址 |
|
||
| verificationCycle | INTEGER | 否 | 检定周期 |
|
||
| nextVerificationDate | DATE | 否 | 下次检定日期 |
|
||
| verificationCertificate | VARCHAR(100) | 否 | 检定证书 |
|
||
| createdAt | DATETIME | 否 | 创建时间 |
|
||
| updatedAt | DATETIME | 否 | 更新时间 |
|
||
|
||
#### 2.1.6 EquipmentHealthScore（健康评分表）
|
||
|
||
**表名**: `ops_equipment_health_score`
|
||
**实体类**: `com.ether.pms.asset.entity.EquipmentHealthScore`
|
||
**状态**: Beta -- 数据准确性待验证
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | UUID | 是 | 主键 |
|
||
| projectId | UUID | 是 | 项目ID |
|
||
| equipmentId | UUID | 是 | 设备ID |
|
||
| equipmentCode | VARCHAR(50) | 否 | 设备编码（冗余） |
|
||
| equipmentName | VARCHAR(100) | 否 | 设备名称（冗余） |
|
||
| healthScore | DECIMAL(5,2) | 是 | 健康度评分(0-100) |
|
||
| failureDeduction | DECIMAL(5,2) | 否 | 故障扣分 |
|
||
| maintenanceDeduction | DECIMAL(5,2) | 否 | 维保扣分 |
|
||
| ageDeduction | DECIMAL(5,2) | 否 | 年龄扣分 |
|
||
| failureCount30d | INTEGER | 否 | 近30天故障次数 |
|
||
| maintenanceCompletionRate | DECIMAL(5,4) | 否 | 维保完成率 |
|
||
| equipmentAgeYears | DECIMAL(10,2) | 否 | 设备年龄(年) |
|
||
| operationHours30d | DECIMAL(12,2) | 否 | 近30天运行时长 |
|
||
| mtbfHours | DECIMAL(12,2) | 否 | MTBF(小时) |
|
||
| mttrHours | DECIMAL(12,2) | 否 | MTTR(小时) |
|
||
| healthLevel | VARCHAR(20) | 否 | 健康等级枚举（5级） |
|
||
| calculatedAt | DATETIME | 是 | 计算时间 |
|
||
| calculationPeriodDays | INTEGER | 否 | 计算周期天数 |
|
||
| remarks | VARCHAR(1000) | 否 | 备注 |
|
||
| createdAt | DATETIME | 否 | 创建时间 |
|
||
| updatedAt | DATETIME | 否 | 更新时间 |
|
||
|
||
**索引**:
|
||
|
||
| 索引名 | 字段 | 用途 |
|
||
|--------|------|------|
|
||
| idx_health_equipment | equipment_id | 按设备查询 |
|
||
| idx_health_calc_time | calculated_at | 按计算时间查询 |
|
||
| idx_health_project | project_id | 按项目查询 |
|
||
|
||
#### 2.1.7 EquipmentFailureHistory（故障历史表）
|
||
|
||
**表名**: `ops_equipment_failure_history`
|
||
**实体类**: `com.ether.pms.asset.entity.EquipmentFailureHistory`
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| id | UUID | 是 | 自动生成 | 主键 |
|
||
| projectId | UUID | 是 | - | 项目ID |
|
||
| equipmentId | UUID | 是 | - | 设备ID |
|
||
| equipmentCode | VARCHAR(50) | 否 | - | 设备编码（冗余） |
|
||
| equipmentName | VARCHAR(100) | 否 | - | 设备名称（冗余） |
|
||
| failureTime | DATETIME | 是 | - | 故障时间 |
|
||
| failureType | VARCHAR(50) | 否 | - | 故障类型枚举（4种） |
|
||
| failureLevel | VARCHAR(20) | 否 | - | 故障等级枚举（4级） |
|
||
| failureReason | VARCHAR(2000) | 否 | - | 故障原因 |
|
||
| failureDescription | VARCHAR(2000) | 否 | - | 故障描述 |
|
||
| repairStartTime | DATETIME | 否 | - | 修复开始时间 |
|
||
| repairEndTime | DATETIME | 否 | - | 修复结束时间 |
|
||
| repairDurationHours | DOUBLE | 否 | 自动计算 | 修复时长(小时) |
|
||
| repairPerson | VARCHAR(100) | 否 | - | 修复人 |
|
||
| repairResult | VARCHAR(20) | 否 | - | 修复结果枚举（4种） |
|
||
| downtimeHours | DOUBLE | 否 | 自动计算 | 停机时长(小时) |
|
||
| maintenanceCost | DECIMAL(12,2) | 否 | - | 维修费用 |
|
||
| isScheduled | BOOLEAN | 是 | false | 是否计划停机 |
|
||
| relatedTaskId | UUID | 否 | - | 关联工单ID |
|
||
| remarks | VARCHAR(1000) | 否 | - | 备注 |
|
||
| createdAt | DATETIME | 否 | - | 创建时间 |
|
||
| updatedAt | DATETIME | 否 | - | 更新时间 |
|
||
| createdBy | UUID | 否 | - | 创建人 |
|
||
|
||
**索引**:
|
||
|
||
| 索引名 | 字段 | 用途 |
|
||
|--------|------|------|
|
||
| idx_failure_equipment | equipment_id | 按设备查询 |
|
||
| idx_failure_time | failure_time | 按时间查询 |
|
||
| idx_failure_project | project_id | 按项目查询 |
|
||
| idx_efh_project_time | project_id, failure_time | 项目+时间组合查询 |
|
||
| idx_efh_equipment_time | equipment_id, failure_time DESC | 设备+时间倒序查询 |
|
||
|
||
#### 2.1.8 OwnershipEntity（归属主体表）
|
||
|
||
**表名**: `asset_ownership_entity`
|
||
**实体类**: `com.ether.pms.asset.entity.OwnershipEntity`
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| id | UUID | 是 | 自动生成 | 主键 |
|
||
| entityType | VARCHAR(20) | 是 | - | 主体类型枚举（3种） |
|
||
| entityName | VARCHAR(100) | 是 | - | 主体名称 |
|
||
| entityCode | VARCHAR(50) | 否 | - | 主体编码 |
|
||
| contactPerson | VARCHAR(50) | 否 | - | 联系人 |
|
||
| contactPhone | VARCHAR(20) | 否 | - | 联系电话 |
|
||
| contactAddress | VARCHAR(255) | 否 | - | 联系地址 |
|
||
| businessLicense | VARCHAR(50) | 否 | - | 营业执照号 |
|
||
| legalRepresentative | VARCHAR(50) | 否 | - | 法人代表 |
|
||
| contractNo | VARCHAR(50) | 否 | - | 合同编号 |
|
||
| contractStartDate | DATE | 否 | - | 合同开始日期 |
|
||
| contractEndDate | DATE | 否 | - | 合同结束日期 |
|
||
| rentalFee | DECIMAL(12,2) | 否 | - | 租赁费用 |
|
||
| status | VARCHAR(20) | 否 | ACTIVE | 状态 |
|
||
| isDeleted | BOOLEAN | 否 | false | 逻辑删除 |
|
||
| createdAt | DATETIME | 否 | - | 创建时间 |
|
||
| updatedAt | DATETIME | 否 | - | 更新时间 |
|
||
|
||
**索引**:
|
||
|
||
| 索引名 | 字段 | 用途 |
|
||
|--------|------|------|
|
||
| idx_ownership_entity_type | entity_type | 按类型查询 |
|
||
| idx_ownership_entity_code | entity_code | 按编码查询 |
|
||
|
||
### 2.2 枚举定义
|
||
|
||
#### EquipmentType（设备类型 -- 10种）
|
||
|
||
| 枚举值 | 中文 | 对应扩展表 | 说明 |
|
||
|--------|------|------------|------|
|
||
| ELEVATOR | 电梯系统 | EquipmentElevator | 含载重/速度/注册号/检验证书/应急救援预案 |
|
||
| HVAC | 暖通空调 | EquipmentHvac | 含制冷/制热量/制冷剂/能效比(EER)/性能系数(COP) |
|
||
| FIRE_PROTECTION | 消防系统 | EquipmentFire | 含探测范围/分区/回路编号/联动控制/巡检周期 |
|
||
| ENERGY_METER | 能源计量 | EquipmentEnergy | 含表常数/精度等级/通讯方式/检定周期 |
|
||
| PLUMBING | 给排水系统 | -- | 使用主表通用字段 + attributes JSON |
|
||
| ELECTRICAL | 电气系统 | -- | 使用主表通用字段 + attributes JSON |
|
||
| SECURITY | 弱电系统 | -- | 使用主表通用字段 + attributes JSON |
|
||
| LANDSCAPE | 景观绿化 | -- | 使用主表通用字段 + attributes JSON |
|
||
| KITCHEN | 厨余设备 | -- | 使用主表通用字段 + attributes JSON |
|
||
| OTHER | 其他设备 | -- | 使用主表通用字段 + attributes JSON |
|
||
|
||
#### SystemType（系统类型 -- 9种，商业地产8大系统+其他）
|
||
|
||
| 枚举值 | 中文 | 说明 |
|
||
|--------|------|------|
|
||
| HVAC | 暖通空调 | 对应设备类型 HVAC |
|
||
| FIRE | 消防系统 | 对应设备类型 FIRE_PROTECTION |
|
||
| ELEVATOR | 电梯系统 | 对应设备类型 ELEVATOR |
|
||
| ELECTRICAL | 电气系统 | 对应设备类型 ELECTRICAL |
|
||
| PLUMBING | 给排水 | 对应设备类型 PLUMBING |
|
||
| BAS | 弱电智能化 | 对应设备类型 SECURITY |
|
||
| KITCHEN | 餐饮厨房 | 对应设备类型 KITCHEN |
|
||
| LANDSCAPE | 景观 | 对应设备类型 LANDSCAPE |
|
||
| OTHER | 其他 | 对应设备类型 OTHER |
|
||
|
||
#### EquipmentStatus（设备状态 -- 4种）
|
||
|
||
| 枚举值 | 中文 | 说明 |
|
||
|--------|------|------|
|
||
| ACTIVE | 在用 | 设备正常运行 |
|
||
| INACTIVE | 停用 | 设备暂停使用 |
|
||
| MAINTENANCE | 维保中 | 设备正在维保 |
|
||
| SCRAPPED | 已报废 | 设备已报废处理 |
|
||
|
||
#### OwnershipType（归属类型 -- 4种）
|
||
|
||
| 枚举值 | 中文 | 关联主体类型 | 说明 |
|
||
|--------|------|-------------|------|
|
||
| PROJECT | 项目自有 | 无需关联 | 项目自有的设备 |
|
||
| COMPANY | 公司统筹 | EntityType=COMPANY | 公司统一调配的设备 |
|
||
| OWNER | 业主自置 | EntityType=OWNER | 业主自行购置的设备 |
|
||
| RENTAL | 租赁设备 | EntityType=RENTAL_COMPANY | 租赁使用的设备 |
|
||
|
||
#### FailureType（故障类型 -- 4种）
|
||
|
||
| 枚举值 | 中文 | 说明 |
|
||
|--------|------|------|
|
||
| SUDDEN | 突发故障 | 非预期的设备故障 |
|
||
| SCHEDULED | 计划停机 | 计划内的设备停机 |
|
||
| WARNING | 预警 | 设备异常预警 |
|
||
| OTHER | 其他 | 其他类型故障 |
|
||
|
||
#### FailureLevel（故障等级 -- 4级）
|
||
|
||
| 枚举值 | 中文 | 典型场景 | 响应时间要求 |
|
||
|--------|------|----------|-------------|
|
||
| LOW | 轻微 | 指示灯故障、外观损伤 | 48小时内 |
|
||
| MEDIUM | 一般 | 单个传感器故障、局部渗漏 | 24小时内 |
|
||
| HIGH | 严重 | 主控制器故障、系统部分失效 | 4小时内 |
|
||
| CRITICAL | 危急 | 电梯困人、消防系统瘫痪 | 立即响应(30分钟内) |
|
||
|
||
#### RepairResult（修复结果 -- 4种）
|
||
|
||
| 枚举值 | 中文 | 说明 |
|
||
|--------|------|------|
|
||
| FIXED | 已修复 | 故障已完全修复 |
|
||
| PARTIAL_FIXED | 部分修复 | 故障部分修复，需后续跟进 |
|
||
| REPLACED | 更换新设备 | 设备整体更换 |
|
||
| PENDING | 待处理 | 故障尚未处理 |
|
||
|
||
#### HealthLevel（健康等级 -- 5级）
|
||
|
||
| 枚举值 | 中文 | 分数范围 | 前端颜色 |
|
||
|--------|------|----------|----------|
|
||
| EXCELLENT | 优秀 | [90, 100) | 绿色 |
|
||
| GOOD | 良好 | [75, 90) | 青色 |
|
||
| FAIR | 一般 | [60, 75) | 橙色 |
|
||
| POOR | 较差 | [40, 60) | 红色 |
|
||
| CRITICAL | 危急 | [0, 40) | 红色 |
|
||
|
||
#### EntityType（归属主体类型 -- 3种）
|
||
|
||
| 枚举值 | 中文 | 对应归属类型 |
|
||
|--------|------|-------------|
|
||
| COMPANY | 公司 | OwnershipType=COMPANY |
|
||
| OWNER | 业主 | OwnershipType=OWNER |
|
||
| RENTAL_COMPANY | 租赁公司 | OwnershipType=RENTAL |
|
||
|
||
### 2.3 ER关系图
|
||
|
||
```mermaid
|
||
erDiagram
|
||
Equipment ||--o| EquipmentElevator : "1:1 equipmentId"
|
||
Equipment ||--o| EquipmentHvac : "1:1 equipmentId"
|
||
Equipment ||--o| EquipmentFire : "1:1 equipmentId"
|
||
Equipment ||--o| EquipmentEnergy : "1:1 equipmentId"
|
||
Equipment ||--o{ EquipmentHealthScore : "1:N equipmentId"
|
||
Equipment ||--o{ EquipmentFailureHistory : "1:N equipmentId"
|
||
Equipment }o--o| OwnershipEntity : "owningEntityId"
|
||
Equipment }o--o| SpaceNode : "spaceNodeId (module-mdm)"
|
||
|
||
Equipment {
|
||
UUID id PK
|
||
UUID projectId FK
|
||
UUID spaceNodeId FK
|
||
String equipmentCode UK
|
||
String equipmentName
|
||
EquipmentType equipmentType
|
||
SystemType systemType
|
||
OwnershipType ownershipType
|
||
UUID owningEntityId FK
|
||
String owningEntityName
|
||
EquipmentStatus status
|
||
}
|
||
|
||
EquipmentElevator {
|
||
UUID id PK
|
||
UUID equipmentId UK_FK
|
||
String elevatorType
|
||
Integer loadCapacity
|
||
BigDecimal speed
|
||
String registrationNo
|
||
String rescuePlan
|
||
}
|
||
|
||
EquipmentHvac {
|
||
UUID id PK
|
||
UUID equipmentId UK_FK
|
||
String hvacType
|
||
BigDecimal coolingCapacity
|
||
BigDecimal heatingCapacity
|
||
BigDecimal energyEfficiencyRatio
|
||
}
|
||
|
||
EquipmentFire {
|
||
UUID id PK
|
||
UUID equipmentId UK_FK
|
||
String fireEquipmentType
|
||
BigDecimal detectionRange
|
||
Boolean linkageEnabled
|
||
String zoneNumber
|
||
}
|
||
|
||
EquipmentEnergy {
|
||
UUID id PK
|
||
UUID equipmentId UK_FK
|
||
String meterType
|
||
String energyType
|
||
BigDecimal meterConstant
|
||
String accuracyClass
|
||
}
|
||
|
||
EquipmentHealthScore {
|
||
UUID id PK
|
||
UUID equipmentId FK
|
||
BigDecimal healthScore
|
||
BigDecimal failureDeduction
|
||
BigDecimal maintenanceDeduction
|
||
BigDecimal ageDeduction
|
||
HealthLevel healthLevel
|
||
}
|
||
|
||
EquipmentFailureHistory {
|
||
UUID id PK
|
||
UUID equipmentId FK
|
||
LocalDateTime failureTime
|
||
FailureType failureType
|
||
FailureLevel failureLevel
|
||
RepairResult repairResult
|
||
}
|
||
|
||
OwnershipEntity {
|
||
UUID id PK
|
||
EntityType entityType
|
||
String entityName
|
||
String entityCode
|
||
String contactPerson
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、API设计
|
||
|
||
### 3.1 EquipmentController
|
||
|
||
**基础路径**: `/api/asset/equipment`
|
||
**控制器类**: `com.ether.pms.asset.controller.EquipmentController`
|
||
|
||
#### 设备主表 CRUD
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| POST | `/` | 创建设备 | Equipment | ApiResponse\<Equipment\> | ASSET-001 |
|
||
| GET | `/{id}` | 获取设备详情 | - | ApiResponse\<Equipment\> | ASSET-001 |
|
||
| PUT | `/{id}` | 更新设备 | Equipment | ApiResponse\<Equipment\> | ASSET-001 |
|
||
| DELETE | `/{id}` | 删除设备（逻辑删除） | - | ApiResponse\<Void\> | ASSET-001 |
|
||
| POST | `/batch-delete` | 批量删除 | List\<UUID\> | ApiResponse\<Void\> | ASSET-002 |
|
||
|
||
#### 设备导入导出
|
||
|
||
| 方法 | 路径 | 说明 | 请求 | 响应 | 功能ID |
|
||
|------|------|------|------|------|--------|
|
||
| POST | `/import` | Excel导入 | MultipartFile + projectId | ApiResponse\<Map\<String, Object\>\> | ASSET-014 |
|
||
| GET | `/export` | Excel导出 | projectId | ResponseEntity\<byte[]\> | ASSET-015 |
|
||
|
||
**导入返回结构**:
|
||
```json
|
||
{
|
||
"successCount": 95,
|
||
"failCount": 5,
|
||
"failDetails": [
|
||
{"row": 3, "reason": "设备编码已存在"},
|
||
{"row": 7, "reason": "设备类型无效"}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 设备查询
|
||
|
||
| 方法 | 路径 | 说明 | 参数 | 响应 | 功能ID |
|
||
|------|------|------|------|------|--------|
|
||
| GET | `/by-project/{projectId}` | 按项目查询 | - | ApiResponse\<List\<Equipment\>\> | ASSET-003 |
|
||
| GET | `/by-space/{spaceNodeId}` | 按空间查询 | - | ApiResponse\<List\<Equipment\>\> | ASSET-004 |
|
||
| GET | `/by-type` | 按类型查询 | type: EquipmentType | ApiResponse\<List\<Equipment\>\> | ASSET-005 |
|
||
| GET | `/by-ownership` | 按归属查询 | ownership: OwnershipType | ApiResponse\<List\<Equipment\>\> | ASSET-006 |
|
||
|
||
#### 设备统计
|
||
|
||
| 方法 | 路径 | 说明 | 参数 | 响应 | 功能ID |
|
||
|------|------|------|------|------|--------|
|
||
| GET | `/stats/by-type/{projectId}` | 按类型统计 | - | ApiResponse\<Map\<String, Long\>\> | ASSET-007 |
|
||
| GET | `/stats/by-ownership/{projectId}` | 按归属统计 | - | ApiResponse\<Map\<String, Long\>\> | ASSET-008 |
|
||
| GET | `/stats/count/{projectId}` | 项目设备总数 | - | ApiResponse\<Long\> | ASSET-009 |
|
||
|
||
#### 电梯扩展
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| GET | `/{id}/elevator` | 获取电梯扩展 | - | ApiResponse\<EquipmentElevator\> | ASSET-010 |
|
||
| PUT | `/{id}/elevator` | 更新电梯扩展 | EquipmentElevator | ApiResponse\<EquipmentElevator\> | ASSET-010 |
|
||
|
||
#### 暖通扩展
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| GET | `/{id}/hvac` | 获取暖通扩展 | - | ApiResponse\<EquipmentHvac\> | ASSET-011 |
|
||
| PUT | `/{id}/hvac` | 更新暖通扩展 | EquipmentHvac | ApiResponse\<EquipmentHvac\> | ASSET-011 |
|
||
|
||
#### 能源计量扩展
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| GET | `/{id}/energy` | 获取能源扩展 | - | ApiResponse\<EquipmentEnergy\> | ASSET-013 |
|
||
| PUT | `/{id}/energy` | 更新能源扩展 | EquipmentEnergy | ApiResponse\<EquipmentEnergy\> | ASSET-013 |
|
||
|
||
#### 消防扩展
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| GET | `/{id}/fire` | 获取消防扩展 | - | ApiResponse\<EquipmentFire\> | ASSET-012 |
|
||
| PUT | `/{id}/fire` | 更新消防扩展 | EquipmentFire | ApiResponse\<EquipmentFire\> | ASSET-012 |
|
||
|
||
### 3.2 EquipmentHealthController
|
||
|
||
**基础路径**: `/api/asset/equipment-health`
|
||
**控制器类**: `com.ether.pms.asset.controller.EquipmentHealthController`
|
||
|
||
| 方法 | 路径 | 说明 | 请求体/参数 | 响应 | 功能ID |
|
||
|------|------|------|-------------|------|--------|
|
||
| GET | `/{equipmentId}` | 获取最新健康度 | - | ApiResponse\<EquipmentHealthScore\> | ASSET-016 |
|
||
| GET | `/{equipmentId}/history` | 健康度历史 | - | ApiResponse\<List\<EquipmentHealthScore\>\> | ASSET-017 |
|
||
| POST | `/calculate` | 计算健康度 | { equipmentId: UUID } | ApiResponse\<EquipmentHealthScore\> | ASSET-016 |
|
||
| POST | `/failure-history` | 记录故障 | EquipmentFailureHistory | ApiResponse\<EquipmentFailureHistory\> | ASSET-020 |
|
||
| GET | `/failure-history/{equipmentId}` | 获取故障历史 | - | ApiResponse\<List\<EquipmentFailureHistory\>\> | ASSET-021 |
|
||
| GET | `/mtbf/{equipmentId}` | 计算MTBF | days: Integer (默认30) | ApiResponse\<MTBFResponse\> | ASSET-018 |
|
||
| GET | `/mttr/{equipmentId}` | 计算MTTR | days: Integer (默认30) | ApiResponse\<MTTRResponse\> | ASSET-019 |
|
||
|
||
**请求体定义**:
|
||
|
||
```java
|
||
// 计算健康度请求
|
||
CalculateHealthRequest {
|
||
@NotNull UUID equipmentId;
|
||
}
|
||
|
||
// MTBF响应
|
||
MTBFResponse {
|
||
UUID equipmentId;
|
||
Integer days;
|
||
BigDecimal mtbfHours;
|
||
}
|
||
|
||
// MTTR响应
|
||
MTTRResponse {
|
||
UUID equipmentId;
|
||
Integer days;
|
||
BigDecimal mttrHours;
|
||
}
|
||
```
|
||
|
||
> 注意: 健康评分相关接口返回时附带 "[Beta] 健康评分数据准确性待验证" 提示信息。
|
||
|
||
### 3.3 OwnershipEntityController
|
||
|
||
**基础路径**: `/api/asset/ownership-entity`
|
||
**控制器类**: `com.ether.pms.asset.controller.OwnershipEntityController`
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 | 响应 | 功能ID |
|
||
|------|------|------|--------|------|--------|
|
||
| POST | `/` | 创建归属主体 | OwnershipEntity | ApiResponse\<OwnershipEntity\> | ASSET-022 |
|
||
| GET | `/{id}` | 获取归属主体 | - | ApiResponse\<OwnershipEntity\> | ASSET-022 |
|
||
| PUT | `/{id}` | 更新归属主体 | OwnershipEntity | ApiResponse\<OwnershipEntity\> | ASSET-022 |
|
||
| DELETE | `/{id}` | 删除归属主体（逻辑删除） | - | ApiResponse\<Void\> | ASSET-022 |
|
||
| GET | `/by-type` | 按类型查询 | type: EntityType | ApiResponse\<List\<OwnershipEntity\>\> | ASSET-023 |
|
||
| GET | `/` | 获取全部（未删除） | - | ApiResponse\<List\<OwnershipEntity\>\> | ASSET-022 |
|
||
|
||
> 注意: OwnershipEntityController 直接注入 Repository，未经过 Service 层，属于简化实现，后续应重构为标准三层架构。
|
||
|
||
---
|
||
|
||
## 四、业务规则
|
||
|
||
### 4.1 设备分类体系（EquipmentType x SystemType矩阵）
|
||
|
||
设备分类采用双维度体系：设备类型(EquipmentType)描述设备专业属性，系统类型(SystemType)描述设备所属的建筑机电系统。
|
||
|
||
| EquipmentType \ SystemType | HVAC | FIRE | ELEVATOR | ELECTRICAL | PLUMBING | BAS | KITCHEN | LANDSCAPE | OTHER |
|
||
|---------------------------|------|------|----------|------------|----------|-----|---------|-----------|-------|
|
||
| ELEVATOR | | | V | | | | | | |
|
||
| HVAC | V | | | | | | | | |
|
||
| FIRE_PROTECTION | | V | | | | | | | |
|
||
| ENERGY_METER | | | | V | | | | | |
|
||
| PLUMBING | | | | | V | | | | |
|
||
| ELECTRICAL | | | | V | | | | | |
|
||
| SECURITY | | | | | | V | | | |
|
||
| LANDSCAPE | | | | | | | | V | |
|
||
| KITCHEN | | | | | | | V | | |
|
||
| OTHER | | | | | | | | | V |
|
||
|
||
**扩展策略**:
|
||
- 4种有扩展表的设备类型（ELEVATOR/HVAC/FIRE_PROTECTION/ENERGY_METER）通过扩展表存储专业参数
|
||
- 6种无扩展表的设备类型通过主表的 `attributes` JSON 字段存储额外属性
|
||
- 设备类型与系统类型存在对应关系，但非严格1:1映射
|
||
|
||
### 4.2 主表+扩展表模式
|
||
|
||
**设计原则**:
|
||
- 主表(Equipment)存储所有设备类型的公共字段（约40个）
|
||
- 扩展表通过 `equipment_id`（UNIQUE约束）一对一关联主表
|
||
- 扩展表仅存储专业特有字段
|
||
- 扩展表的读写通过主设备ID路径：`GET /{id}/elevator`、`PUT /{id}/elevator`
|
||
|
||
**创建设备时扩展表处理规则**:
|
||
|
||
| 操作 | 规则 |
|
||
|------|------|
|
||
| 创建设备 | 按equipmentType自动创建对应扩展表记录（仅4种有扩展表的类型） |
|
||
| 更新设备类型 | 不允许修改equipmentType（避免扩展表数据不一致） |
|
||
| 删除设备 | 级联删除对应扩展表记录 |
|
||
| 读取扩展表 | 通过 `GET /{id}/{type}` 获取，不存在返回null |
|
||
| 更新扩展表 | 采用saveOrUpdate模式：存在则更新，不存在则新建 |
|
||
|
||
**扩展表服务接口模式**（以电梯为例）:
|
||
```java
|
||
public interface EquipmentElevatorService {
|
||
Optional<EquipmentElevator> getByEquipmentId(UUID equipmentId);
|
||
EquipmentElevator saveOrUpdate(EquipmentElevator elevator);
|
||
}
|
||
```
|
||
|
||
### 4.3 归属管理
|
||
|
||
**4种归属类型**:
|
||
|
||
| 归属类型 | 说明 | 关联主体 | 维保责任方 |
|
||
|----------|------|----------|-----------|
|
||
| PROJECT | 项目自有 | 无需关联外部主体 | 项目物业团队 |
|
||
| COMPANY | 公司统筹 | 可关联 EntityType=COMPANY 的主体 | 公司指定维保商 |
|
||
| OWNER | 业主自置 | 可关联 EntityType=OWNER 的主体 | 业主自行负责或委托 |
|
||
| RENTAL | 租赁设备 | 可关联 EntityType=RENTAL_COMPANY 的主体 | 租赁合同约定 |
|
||
|
||
**归属主体与设备的关联**:
|
||
- Equipment 表同时存储 `owningEntityId` 和 `owningEntityName`，避免频繁关联查询
|
||
- 归属类型与主体类型存在对应关系：PROJECT无需关联主体，COMPANY对应公司主体，OWNER对应业主主体，RENTAL对应租赁公司主体
|
||
- 归属主体变更时需同步更新 `owningEntityName` 冗余字段
|
||
|
||
**维保责任划分**:
|
||
- PROJECT/COMPANY 归属的设备：由物业方统一安排维保
|
||
- OWNER 归属的设备：业主自行负责维保，物业方监督
|
||
- RENTAL 归属的设备：按租赁合同约定维保责任方
|
||
|
||
### 4.4 健康评分算法[Beta]
|
||
|
||
#### 评分公式
|
||
|
||
```
|
||
健康度 = 基础分(100) - 故障扣分 - 维保扣分 - 年龄扣分
|
||
```
|
||
|
||
即：
|
||
|
||
```
|
||
H = 100 - D_failure - D_maintenance - D_age
|
||
```
|
||
|
||
其中：
|
||
- `H` 为健康度评分，范围 [0, 100]
|
||
- `D_failure` 为故障扣分
|
||
- `D_maintenance` 为维保扣分
|
||
- `D_age` 为年龄扣分
|
||
|
||
#### 三维扣分算法
|
||
|
||
**1. 故障扣分（D_failure）**
|
||
|
||
```
|
||
D_failure = N_30d x P_failure
|
||
```
|
||
|
||
| 参数 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| N_30d | 近30天故障次数 | 从 EquipmentFailureHistory 统计 |
|
||
| P_failure | 5 | 每次故障扣5分（FAILURE_DEDUCTION_PER_COUNT） |
|
||
| 上限 | 无 | 故障次数无上限，扣分可超过100 |
|
||
|
||
**2. 维保扣分（D_maintenance）**
|
||
|
||
```
|
||
D_maintenance = (1 - R_completion) x F_maintenance
|
||
```
|
||
|
||
| 参数 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| R_completion | 维保完成率 | 范围 [0, 1]，当前固定为1.0（TODO） |
|
||
| F_maintenance | 20 | 维保扣分系数（MAINTENANCE_DEDUCTION_FACTOR） |
|
||
| 上限 | 20分 | 最大维保扣分 |
|
||
|
||
> 当前实现中维保完成率固定为1.0，维保扣分始终为0，标记为TODO待实现。
|
||
|
||
**3. 年龄扣分（D_age）**
|
||
|
||
```
|
||
D_age = min(Y_equipment x P_age, M_age)
|
||
```
|
||
|
||
| 参数 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| Y_equipment | 设备年龄(年) | 计算方式见下方 |
|
||
| P_age | 2 | 每年扣2分（AGE_DEDUCTION_PER_YEAR） |
|
||
| M_age | 10 | 最大年龄扣分（MAX_AGE_DEDUCTION） |
|
||
|
||
**设备年龄计算**:
|
||
|
||
```
|
||
Y_equipment = years + months / 12
|
||
```
|
||
|
||
- 优先使用 `installationDate`（安装日期）
|
||
- 若无安装日期，使用 `createdAt` 的日期部分
|
||
- 均无则返回 0
|
||
|
||
**最终评分**:
|
||
|
||
```
|
||
H = max(0, 100 - D_failure - D_maintenance - D_age)
|
||
```
|
||
|
||
评分精度：保留2位小数，四舍五入。
|
||
|
||
#### MTBF计算（平均故障间隔时间）
|
||
|
||
```
|
||
MTBF = T_operating / N_failure
|
||
```
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| T_operating | 运行时间（小时）= 最后故障时间 - 首次故障时间 |
|
||
| N_failure | 故障次数 |
|
||
|
||
**计算规则**:
|
||
- 计算周期：默认30天，可通过 `days` 参数自定义
|
||
- 若仅1次故障：T_operating 使用 `days x 24` 小时
|
||
- 若 T_operating <= 0：使用 `days x 24` 小时
|
||
- 无故障时返回 0
|
||
- 精度：保留2位小数
|
||
|
||
#### MTTR计算（平均修复时间）
|
||
|
||
```
|
||
MTTR = T_repair_total / N_repair
|
||
```
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| T_repair_total | 总修复时间（小时）= SUM(repairDurationHours) |
|
||
| N_repair | 修复次数 |
|
||
|
||
**计算规则**:
|
||
- 仅统计已完成修复的故障记录（repairDurationHours 不为空）
|
||
- 无修复记录时返回 0
|
||
- 精度：保留2位小数
|
||
|
||
#### 5级等级划分
|
||
|
||
```java
|
||
public static HealthLevel fromScore(BigDecimal score) {
|
||
if (score == null) return CRITICAL;
|
||
double s = score.doubleValue();
|
||
if (s >= 90 && s < 100) return EXCELLENT; // 优秀
|
||
if (s >= 75 && s < 90) return GOOD; // 良好
|
||
if (s >= 60 && s < 75) return FAIR; // 一般
|
||
if (s >= 40 && s < 60) return POOR; // 较差
|
||
return CRITICAL; // 危急 [0, 40)
|
||
}
|
||
```
|
||
|
||
> 注意：score=100 时返回 CRITICAL，因为所有区间都是左闭右开 [min, max)，100 不在任何区间内。这是当前实现的已知问题。
|
||
|
||
### 4.5 故障等级体系
|
||
|
||
#### 4级故障等级
|
||
|
||
| 等级 | 中文 | 典型场景 | 建议响应时间 | 升级规则 |
|
||
|------|------|----------|-------------|---------|
|
||
| LOW | 轻微 | 指示灯故障、外观损伤 | 48小时内 | 超过48小时未处理升级为MEDIUM |
|
||
| MEDIUM | 一般 | 单个传感器故障、局部渗漏 | 24小时内 | 超过24小时未处理升级为HIGH |
|
||
| HIGH | 严重 | 主控制器故障、系统部分失效 | 4小时内 | 超过4小时未处理升级为CRITICAL |
|
||
| CRITICAL | 危急 | 电梯困人、消防系统瘫痪 | 30分钟内 | 立即通知项目经理 |
|
||
|
||
#### 故障记录自动计算
|
||
|
||
记录故障时自动计算以下字段：
|
||
|
||
```
|
||
repairDurationHours = (repairEndTime - repairStartTime) / 60 (分钟转小时)
|
||
downtimeHours = (repairStartTime - failureTime) / 60 (故障到开始修复的时间)
|
||
```
|
||
|
||
**计算条件**:
|
||
- repairDurationHours: 仅当 repairStartTime 和 repairEndTime 均不为空时计算
|
||
- downtimeHours: 仅当 repairStartTime > failureTime 时计算
|
||
|
||
### 4.6 特种设备管理
|
||
|
||
**特种设备识别规则**:
|
||
- Equipment 表中 `specialEquipmentType` 不为空时，该设备为特种设备
|
||
- 主要涉及：电梯(ELEVATOR)、消防(FIRE_PROTECTION)、压力容器等
|
||
|
||
**年检提醒机制**:
|
||
- `inspectionCycle`：年检周期（月），如12表示每年年检一次
|
||
- `nextInspectionDate`：下次年检日期
|
||
- `lastInspectionDate`：上次年检日期
|
||
- `lastInspectionResult`：上次年检结果
|
||
|
||
**证书管理**:
|
||
- `specialEquipmentCert`：特种设备证书编号
|
||
- 电梯扩展表：`inspectionCertificate`（检验证书）、`registrationNo`（注册登记号）
|
||
- 能源计量扩展表：`verificationCertificate`（检定证书）、`nextVerificationDate`（下次检定日期）
|
||
|
||
**法规合规**:
|
||
- 电梯：需按《特种设备安全法》定期检验，注册登记号唯一
|
||
- 消防：需按《消防法》定期巡检，联动系统需定期测试
|
||
- 能源计量：需按《计量法》定期检定，精度等级需符合标准
|
||
|
||
> 当前实现中无后端定时提醒功能，仅前端展示下次年检日期。
|
||
|
||
### 4.7 设备导入导出
|
||
|
||
**Excel导入校验规则**:
|
||
|
||
| 校验项 | 规则 | 错误码 |
|
||
|--------|------|--------|
|
||
| 文件为空 | file.isEmpty() = true | FILE_001 |
|
||
| 文件类型 | 仅支持 .xlsx / .xls | FILE_002 |
|
||
| Content-Type | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet 或 application/vnd.ms-excel | FILE_002 |
|
||
| 文件扩展名 | .xlsx 或 .xls | FILE_002 |
|
||
| 文件大小 | 最大 10MB | FILE_003 |
|
||
| 行数限制 | 最大 1000 行 | FILE_004 |
|
||
| 文件解析 | Workbook可正常打开 | FILE_001 |
|
||
|
||
**Excel导出规则**:
|
||
- 按项目导出所有未删除设备
|
||
- 输出文件名：`设备列表.xlsx`
|
||
- Content-Type：`application/octet-stream`
|
||
|
||
---
|
||
|
||
## 五、执行约束
|
||
|
||
### 5.1 设备编码唯一性
|
||
|
||
- `equipmentCode` 字段在数据库层设置 UNIQUE 约束
|
||
- 索引 `idx_equipment_code` 确保唯一性
|
||
- 创建设备时若编码已存在，数据库将抛出唯一约束异常
|
||
- 导入时编码重复将记入 failDetails
|
||
|
||
### 5.2 扩展表与主表1:1约束
|
||
|
||
- 扩展表的 `equipment_id` 字段设置 UNIQUE 约束
|
||
- 每个设备最多只能有一条对应类型的扩展表记录
|
||
- 更新扩展表采用 saveOrUpdate 模式：先查询是否存在，存在则更新，不存在则新建
|
||
- 扩展表类型必须与主表 equipmentType 匹配（如不能给电梯设备创建暖通扩展表）
|
||
|
||
### 5.3 健康评分范围约束
|
||
|
||
- healthScore 范围为 [0, 100]
|
||
- 计算结果低于0时强制设为0
|
||
- 精度：DECIMAL(5,2)，保留2位小数
|
||
- HealthLevel.fromScore(null) 返回 CRITICAL
|
||
|
||
### 5.4 故障时间约束
|
||
|
||
- `repairStartTime <= repairEndTime`：修复开始时间不能晚于修复结束时间
|
||
- `failureTime <= repairStartTime`：故障时间不能晚于修复开始时间
|
||
- 当时间约束不满足时，对应自动计算字段（repairDurationHours/downtimeHours）不计算
|
||
|
||
---
|
||
|
||
## 六、权限控制
|
||
|
||
| API路径 | 操作 | 所需权限 | 说明 |
|
||
|---------|------|----------|------|
|
||
| POST /api/asset/equipment | 创建设备 | asset:equipment:create | 需项目级权限 |
|
||
| GET /api/asset/equipment/{id} | 查看设备 | asset:equipment:read | 需项目级权限 |
|
||
| PUT /api/asset/equipment/{id} | 更新设备 | asset:equipment:update | 需项目级权限 |
|
||
| DELETE /api/asset/equipment/{id} | 删除设备 | asset:equipment:delete | 需项目级权限 |
|
||
| POST /api/asset/equipment/batch-delete | 批量删除 | asset:equipment:delete | 需项目级权限 |
|
||
| POST /api/asset/equipment/import | 导入设备 | asset:equipment:import | 需项目级权限 |
|
||
| GET /api/asset/equipment/export | 导出设备 | asset:equipment:export | 需项目级权限 |
|
||
| PUT /api/asset/equipment/{id}/elevator | 更新电梯扩展 | asset:equipment:update | 同设备更新权限 |
|
||
| PUT /api/asset/equipment/{id}/hvac | 更新暖通扩展 | asset:equipment:update | 同设备更新权限 |
|
||
| PUT /api/asset/equipment/{id}/fire | 更新消防扩展 | asset:equipment:update | 同设备更新权限 |
|
||
| PUT /api/asset/equipment/{id}/energy | 更新能源扩展 | asset:equipment:update | 同设备更新权限 |
|
||
| POST /api/asset/equipment-health/calculate | 计算健康度 | asset:health:calculate | 需项目级权限 |
|
||
| POST /api/asset/equipment-health/failure-history | 记录故障 | asset:failure:create | 需项目级权限 |
|
||
| POST /api/asset/ownership-entity | 创建归属主体 | asset:ownership:create | 需系统级权限 |
|
||
| PUT /api/asset/ownership-entity/{id} | 更新归属主体 | asset:ownership:update | 需系统级权限 |
|
||
| DELETE /api/asset/ownership-entity/{id} | 删除归属主体 | asset:ownership:delete | 需系统级权限 |
|
||
|
||
> 当前实现中权限控制尚未集成Spring Security，以上为设计预期权限矩阵。
|
||
|
||
---
|
||
|
||
## 七、例外情况处理
|
||
|
||
| 例外场景 | 触发条件 | 处理方式 | 错误码 |
|
||
|----------|----------|----------|--------|
|
||
| 设备编码已存在 | 创建/导入设备时equipmentCode重复 | 抛出数据库唯一约束异常，导入时记入failDetails | DB约束 |
|
||
| 扩展表类型不匹配 | 给非电梯设备创建电梯扩展表 | 允许创建（当前无校验），建议增加类型匹配校验 | - |
|
||
| 健康评分计算数据不足 | 设备无故障历史记录 | MTBF/MTTR返回0，维保完成率默认1.0 | - |
|
||
| 故障记录关联设备不存在 | equipmentId指向不存在的设备 | 抛出BusinessException("设备不存在") | 6001 |
|
||
| 无健康度记录 | 查询设备从未计算过健康度 | 抛出BusinessException("没有健康度记录") | 6003 |
|
||
| 导入文件格式错误 | 文件非xlsx/xls格式 | 抛出BusinessException("不支持的文件类型") | FILE_002 |
|
||
| 导入文件过大 | 文件超过10MB | 抛出BusinessException("文件大小不能超过10MB") | FILE_003 |
|
||
| 导入行数超限 | Excel行数超过1000 | 抛出BusinessException("Excel行数不能超过1000行") | FILE_004 |
|
||
| 归属主体不存在 | 更新/删除时ID不存在 | 抛出RuntimeException("归属主体不存在") | - |
|
||
| 设备不存在 | 操作的设备ID不存在或已删除 | 抛出BusinessException("设备不存在") | 6001 |
|
||
| 导入文件解析失败 | Excel文件损坏 | 抛出BusinessException("文件解析失败") | FILE_001 |
|
||
|
||
---
|
||
|
||
**附录：已知代码问题**
|
||
|
||
| 问题 | 位置 | 影响 | 建议 |
|
||
|------|------|------|------|
|
||
| HealthLevel.fromScore(100) 返回 CRITICAL | EquipmentHealthScore.HealthLevel | 评分100分的设备被判定为危急 | 修改区间为 [90, 100] 或添加 score==100 特判 |
|
||
| 维保完成率固定为1.0 | EquipmentHealthServiceImpl | 维保扣分始终为0 | 对接ops模块查询工单数据计算完成率 |
|
||
| OwnershipEntityController绕过Service层 | OwnershipEntityController | 不符合分层架构，缺少业务校验 | 重构为标准三层架构 |
|
||
| 前端SystemType与后端不一致 | equipment.ts vs SystemType枚举 | 前端FIRE_PROTECTION vs 后端FIRE | 统一前后端枚举值 |
|
||
| 查询接口无分页 | by-project/by-space等 | 数据量大时可能OOM | 改为分页查询 |
|