# 设备与资产域 - 详细设计

**文档编号**: 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 | 改为分页查询 |