38 KiB

Raw Blame History

资产设备领域反推设计文档（基于实际代码）

领域编号: 4.3
模块: module-asset
反推日期: 2026-04-23
数据来源: ether-pms/module-asset + ether-admin/src

一、领域概述

1.1 领域职责

资产设备领域负责物业设备资产的全生命周期管理，核心职责包括：

设备台账管理：设备主表 + 4张扩展表的分类扩展模式，覆盖电梯/暖通/消防/能源计量四大专业设备
设备健康预测：基于 MTBF/MTTR 指标的健康评分算法，5级健康等级评估
故障历史管理：4级故障等级、4种故障类型、4种修复结果的全流程故障记录
归属主体管理：4种归属类型（项目自有/公司统筹/业主自置/租赁设备），3种主体类型
设备导入导出：Excel 批量导入导出，含文件校验与行数限制
设备与空间关联：通过 spaceNodeId 关联空间节点树

1.2 核心概念

概念	说明	对应实体
设备台账	设备基础信息与运行状态	Equipment
电梯扩展	电梯专业参数（载重/速度/注册号等）	EquipmentElevator
暖通扩展	暖通空调专业参数（制冷量/制热量/能效比等）	EquipmentHvac
消防扩展	消防设备专业参数（探测范围/联动/分区等）	EquipmentFire
能源计量扩展	能源表计专业参数（表常数/精度/通讯等）	EquipmentEnergy
健康评分	设备健康度评估结果	EquipmentHealthScore
故障历史	设备故障与维修记录	EquipmentFailureHistory
归属主体	设备归属方信息	OwnershipEntity

1.3 架构模式

主表 + 扩展表模式：Equipment 为主表，通过 equipmentType 字段区分设备类型，每种专业设备类型对应一张扩展表，通过 equipment_id（unique）一对一关联。这种设计避免了主表字段膨胀，同时保持了扩展的灵活性。

Equipment (主表)
  ├── EquipmentElevator (电梯扩展) ← equipment_id UNIQUE
  ├── EquipmentHvac (暖通扩展) ← equipment_id UNIQUE
  ├── EquipmentFire (消防扩展) ← equipment_id UNIQUE
  └── EquipmentEnergy (能源计量扩展) ← equipment_id UNIQUE

二、数据结构设计

2.1 Equipment（设备主表）

表名: asset_equipment

字段	类型	必填	说明
id	UUID	是	主键，自动生成
projectId	UUID	是	所属项目ID
spaceNodeId	UUID	否	关联空间节点ID
equipmentCode	VARCHAR(50)	是	设备编码，全局唯一
equipmentName	VARCHAR(100)	是	设备名称
equipmentType	VARCHAR(30)	是	设备类型枚举
equipmentCategory	VARCHAR(50)	否	设备分类
systemType	VARCHAR(50)	否	系统类型枚举（8大系统）
ownershipType	VARCHAR(20)	是	归属类型枚举，默认 PROJECT
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
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	否	设备照片列表
documents	JSONB	否	电子文档列表
manualUrl	VARCHAR(500)	否	手册URL
remarks	VARCHAR(1000)	否	备注
isDeleted	BOOLEAN	否	逻辑删除标记，默认 false
createdAt	DATETIME	是	创建时间
updatedAt	DATETIME	是	更新时间
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) — UNIQUE
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.2 EquipmentElevator（电梯扩展表）

表名: asset_equipment_elevator

字段	类型	必填	说明
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.3 EquipmentHvac（暖通空调扩展表）

表名: asset_equipment_hvac

字段	类型	必填	说明
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.4 EquipmentFire（消防扩展表）

表名: asset_equipment_fire

字段	类型	必填	说明
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.5 EquipmentEnergy（能源计量扩展表）

表名: asset_equipment_energy

字段	类型	必填	说明
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.6 EquipmentHealthScore（健康评分表）

表名: ops_equipment_health_score

字段	类型	必填	说明
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)	否	健康等级枚举
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.7 EquipmentFailureHistory（故障历史表）

表名: ops_equipment_failure_history

字段	类型	必填	说明
id	UUID	是	主键
projectId	UUID	是	项目ID
equipmentId	UUID	是	设备ID
equipmentCode	VARCHAR(50)	否	设备编码（冗余）
equipmentName	VARCHAR(100)	否	设备名称（冗余）
failureTime	DATETIME	是	故障时间
failureType	VARCHAR(50)	否	故障类型枚举
failureLevel	VARCHAR(20)	否	故障等级枚举
failureReason	VARCHAR(2000)	否	故障原因
failureDescription	VARCHAR(2000)	否	故障描述
repairStartTime	DATETIME	否	修复开始时间
repairEndTime	DATETIME	否	修复结束时间
repairDurationHours	DOUBLE	否	修复时长(小时)
repairPerson	VARCHAR(100)	否	修复人
repairResult	VARCHAR(20)	否	修复结果枚举
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.8 OwnershipEntity（归属主体表）

表名: asset_ownership_entity

字段	类型	必填	说明
id	UUID	是	主键
entityType	VARCHAR(20)	是	主体类型枚举
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.9 枚举定义汇总

EquipmentType（设备类型 — 10种）

枚举值	中文	对应扩展表
ELEVATOR	电梯系统	EquipmentElevator
HVAC	暖通空调	EquipmentHvac
FIRE_PROTECTION	消防系统	EquipmentFire
PLUMBING	给排水系统	—
ELECTRICAL	电气系统	—
ENERGY_METER	能源计量	EquipmentEnergy
SECURITY	弱电系统	—
LANDSCAPE	景观绿化	—
KITCHEN	厨余设备	—
OTHER	其他设备	—

EquipmentStatus（设备状态 — 4种）

枚举值	中文
ACTIVE	在用
INACTIVE	停用
MAINTENANCE	维保中
SCRAPPED	已报废

OwnershipType（归属类型 — 4种）

枚举值	中文
PROJECT	项目自有
COMPANY	公司统筹
OWNER	业主自置
RENTAL	租赁设备

SystemType（系统类型 — 9种，商业地产8大系统+其他）

枚举值	中文
HVAC	暖通空调
FIRE	消防系统
ELEVATOR	电梯系统
ELECTRICAL	电气系统
PLUMBING	给排水
BAS	弱电智能化
KITCHEN	餐饮厨房
LANDSCAPE	景观
OTHER	其他

FailureType（故障类型 — 4种）

枚举值	中文
SUDDEN	突发故障
SCHEDULED	计划停机
WARNING	预警
OTHER	其他

FailureLevel（故障等级 — 4级）

枚举值	中文
LOW	轻微
MEDIUM	一般
HIGH	严重
CRITICAL	危急

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	公司
OWNER	业主
RENTAL_COMPANY	租赁公司

2.10 实体关系图

┌──────────────────┐     1:1     ┌───────────────────────┐
│   Equipment      │─────────────│  EquipmentElevator    │
│   (主表)          │             └───────────────────────┘
│                  │     1:1     ┌───────────────────────┐
│  equipmentType ──│─────────────│  EquipmentHvac        │
│  determines →    │             └───────────────────────┘
│                  │     1:1     ┌───────────────────────┐
│  owningEntityId ─│─────────────│  EquipmentFire        │
│       ↓          │             └───────────────────────┘
│                  │     1:1     ┌───────────────────────┐
│  spaceNodeId ────│─────────────│  EquipmentEnergy      │
│       ↓          │             └───────────────────────┘
│                  │
│                  │     1:N     ┌───────────────────────┐
│                  │─────────────│ EquipmentHealthScore  │
│                  │             └───────────────────────┘
│                  │     1:N     ┌───────────────────────┐
│                  │─────────────│ EquipmentFailureHist. │
│                  │             └───────────────────────┘
└──────────────────┘
       │
       │ owningEntityId
       ↓
┌──────────────────┐
│ OwnershipEntity  │
└──────────────────┘

外部关联:
  Equipment.spaceNodeId → SpaceNode.id (module-mdm)

三、API接口设计

3.1 EquipmentController

基础路径: /api/asset/equipment

设备主表 CRUD

方法	路径	说明	请求体	响应
POST	`/`	创建设备	Equipment	Equipment
GET	`/{id}`	获取设备详情	—	Equipment
PUT	`/{id}`	更新设备	Equipment	Equipment
DELETE	`/{id}`	删除设备	—	Void
POST	`/batch-delete`	批量删除	List<UUID>	Void

设备导入导出

方法	路径	说明	请求	响应
POST	`/import`	Excel导入	MultipartFile + projectId	Map(successCount, failCount, failDetails)
GET	`/export`	Excel导出	projectId	byte[] (xlsx)

导入校验规则:

文件类型：仅支持 .xlsx / .xls
文件大小：最大 10MB
行数限制：最大 1000 行
文件不能为空

设备查询

方法	路径	说明	参数	响应
GET	`/by-project/{projectId}`	按项目查询	—	List<Equipment>
GET	`/by-space/{spaceNodeId}`	按空间查询	—	List<Equipment>
GET	`/by-type`	按类型查询	type: EquipmentType	List<Equipment>
GET	`/by-ownership`	按归属查询	ownership: OwnershipType	List<Equipment>

设备统计

方法	路径	说明	参数	响应
GET	`/stats/by-type/{projectId}`	按类型统计	—	Map<String, Long>
GET	`/stats/by-ownership/{projectId}`	按归属统计	—	Map<String, Long>
GET	`/stats/count/{projectId}`	项目设备总数	—	Long

电梯扩展

方法	路径	说明	请求体	响应
GET	`/{id}/elevator`	获取电梯扩展	—	EquipmentElevator
PUT	`/{id}/elevator`	更新电梯扩展	EquipmentElevator	EquipmentElevator

暖通扩展

方法	路径	说明	请求体	响应
GET	`/{id}/hvac`	获取暖通扩展	—	EquipmentHvac
PUT	`/{id}/hvac`	更新暖通扩展	EquipmentHvac	EquipmentHvac

能源计量扩展

方法	路径	说明	请求体	响应
GET	`/{id}/energy`	获取能源扩展	—	EquipmentEnergy
PUT	`/{id}/energy`	更新能源扩展	EquipmentEnergy	EquipmentEnergy

消防扩展

方法	路径	说明	请求体	响应
GET	`/{id}/fire`	获取消防扩展	—	EquipmentFire
PUT	`/{id}/fire`	更新消防扩展	EquipmentFire	EquipmentFire

3.2 EquipmentHealthController

基础路径: /api/asset/equipment-health

方法	路径	说明	请求体/参数	响应
GET	`/{equipmentId}`	获取最新健康度	—	EquipmentHealthScore
GET	`/{equipmentId}/history`	健康度历史	—	List<EquipmentHealthScore>
POST	`/calculate`	计算健康度	{ equipmentId: UUID }	EquipmentHealthScore
POST	`/failure-history`	记录故障	EquipmentFailureHistory	EquipmentFailureHistory
GET	`/failure-history/{equipmentId}`	获取故障历史	—	List<EquipmentFailureHistory>
GET	`/mtbf/{equipmentId}`	计算MTBF	days: Integer (默认30)	{ equipmentId, days, mtbfHours }
GET	`/mttr/{equipmentId}`	计算MTTR	days: Integer (默认30)	{ equipmentId, days, mttrHours }

3.3 OwnershipEntityController

基础路径: /api/asset/ownership-entity

方法	路径	说明	请求体	响应
POST	`/`	创建归属主体	OwnershipEntity	OwnershipEntity
GET	`/{id}`	获取归属主体	—	OwnershipEntity
PUT	`/{id}`	更新归属主体	OwnershipEntity	OwnershipEntity
DELETE	`/{id}`	删除归属主体（逻辑删除）	—	Void
GET	`/by-type`	按类型查询	type: EntityType	List<OwnershipEntity>
GET	`/`	获取全部（未删除）	—	List<OwnershipEntity>

注意: OwnershipEntityController 直接注入 Repository，未经过 Service 层，属于简化实现。

四、业务规则

4.1 设备分类体系（10种 EquipmentType）

设备类型采用 10 大分类体系，其中 4 种有专业扩展表：

设备类型	扩展表	专业参数特点
ELEVATOR（电梯系统）	EquipmentElevator	载重、速度、楼层数、注册号、检验证书、应急救援预案
HVAC（暖通空调）	EquipmentHvac	制冷/制热量、制冷剂、能效比(EER)、性能系数(COP)、滤网更换
FIRE_PROTECTION（消防系统）	EquipmentFire	探测范围、分区/回路编号、联动控制、巡检周期
ENERGY_METER（能源计量）	EquipmentEnergy	表常数、精度等级、通讯方式、检定周期
PLUMBING（给排水系统）	—	使用主表通用字段
ELECTRICAL（电气系统）	—	使用主表通用字段
SECURITY（弱电系统）	—	使用主表通用字段
LANDSCAPE（景观绿化）	—	使用主表通用字段
KITCHEN（厨余设备）	—	使用主表通用字段
OTHER（其他设备）	—	使用主表通用字段 + attributes JSON 扩展

扩展策略: 无扩展表的设备类型通过主表的 attributes JSON 字段存储额外属性。

4.2 归属管理（4种 OwnershipType）

归属类型	说明	关联主体
PROJECT	项目自有	无需关联外部主体
COMPANY	公司统筹	可关联 EntityType=COMPANY 的主体
OWNER	业主自置	可关联 EntityType=OWNER 的主体
RENTAL	租赁设备	可关联 EntityType=RENTAL_COMPANY 的主体

数据冗余: Equipment 表同时存储 owningEntityId 和 owningEntityName，避免频繁关联查询。

4.3 主表+扩展表模式

设计原则:

主表存储所有设备类型的公共字段（约40个）
扩展表通过 equipment_id（UNIQUE）一对一关联主表
扩展表仅存储专业特有字段
扩展表的读写通过主设备ID路径：GET /{id}/elevator、PUT /{id}/elevator
扩展表采用 saveOrUpdate 模式：存在则更新，不存在则新建

扩展表服务接口模式（以电梯为例）:

public interface EquipmentElevatorService {
    Optional<EquipmentElevator> getByEquipmentId(UUID equipmentId);
    EquipmentElevator saveOrUpdate(EquipmentElevator elevator);
}

4.4 健康评分算法

评分公式

健康度 = 基础分(100) - 故障扣分 - 维保扣分 - 年龄扣分

扣分规则

扣分项	计算公式	参数	上限
故障扣分	故障次数(近30天) × 5	FAILURE_DEDUCTION_PER_COUNT = 5	无上限
维保扣分	(1 - 维保完成率) × 20	MAINTENANCE_DEDUCTION_FACTOR = 20	20分
年龄扣分	设备年龄(年) × 2	AGE_DEDUCTION_PER_YEAR = 2	10分(MAX_AGE_DEDUCTION)

最低分: 0分（不会为负数）

健康等级映射

等级	分数范围	颜色(前端)
EXCELLENT（优秀）	[90, 100)	绿色
GOOD（良好）	[75, 90)	青色
FAIR（一般）	[60, 75)	橙色
POOR（较差）	[40, 60)	红色
CRITICAL（危急）	[0, 40)	红色

MTBF 计算（平均故障间隔时间）

MTBF = 运行时间(小时) / 故障次数

计算周期：默认30天，可自定义
运行时间：从第一个故障到最后一个故障的时间跨度
若仅1次故障：使用默认期间天数 × 24小时
无故障时返回 0

MTTR 计算（平均修复时间）

MTTR = 总修复时间(小时) / 修复次数

仅统计已完成修复的故障记录（repairDurationHours 不为空）
无修复记录时返回 0

设备年龄计算

设备年龄 = 安装年份 + 安装月份/12

优先使用 installationDate
若无安装日期，使用 createdAt 的日期部分
均无则返回 0

已知问题: 当前实现中 calculateEquipmentAge() 方法错误地使用了 SpaceNode.maintenanceContractStart 而非 Equipment.installationDate，因为健康评分服务查询的是 SpaceNode 而非 Equipment 实体。

4.5 故障等级（4级 FailureLevel）

等级	中文	典型场景
LOW	轻微	指示灯故障、外观损伤
MEDIUM	一般	单个传感器故障、局部渗漏
HIGH	严重	主控制器故障、系统部分失效
CRITICAL	危急	电梯困人、消防系统瘫痪

4.6 故障记录自动计算

记录故障时自动计算：

修复时长：repairDurationHours = (repairEndTime - repairStartTime) / 60（分钟转小时）
停机时长：downtimeHours = (repairStartTime - failureTime) / 60（故障到开始修复的时间）

4.7 设备导入规则

规则	限制
文件格式	.xlsx / .xls
文件大小	最大 10MB
行数限制	最大 1000 行
文件编码	UTF-8
空文件	拒绝

4.8 逻辑删除

所有实体采用逻辑删除模式：

Equipment: isDeleted 字段，默认 false
OwnershipEntity: isDeleted 字段，默认 false
查询时过滤已删除记录：findByIdAndIsDeletedFalse

五、前端操作流程

5.1 页面结构

页面	路径	说明
设备列表	EquipmentList.vue	设备台账主列表，含筛选/新增/编辑/删除/导入导出
设备详情	EquipmentDetail.vue	设备完整信息展示（基本信息/技术参数/维保/财务/照片/文档）
设备健康	EquipmentHealth.vue	健康度评分/趋势图/MTBF/MTTR/故障历史
巡检管理	Inspection.vue	巡检标准项 + 巡检记录
维保计划	MaintenancePlan.vue	维保计划管理
维保工单	MaintenanceTask.vue	维保工单管理（创建/分配/执行/完成/验证）
照片管理	components/PhotoManager.vue	设备照片上传与管理
文档管理	components/DocumentManager.vue	电子文档上传与管理

5.2 设备台账管理流程

设备列表页
  ├── 筛选条件：项目(必选) + 设备类型 + 归属类型 + 关键词
  ├── 操作按钮：新增设备 / 导入 / 导出 / 批量删除
  ├── 列表展示：编码/名称/类型/归属/状态/安装位置/维保商/年检日期
  ├── 行操作：查看详情 / 编辑 / 删除
  └── 统计标签：按类型统计 + 按归属统计

5.3 设备详情展示流程

设备详情页
  ├── 基本信息：编码/名称/类型/归属/型号/厂商/供应商/出厂编号/资产编号/安装位置/安装日期
  ├── 技术参数：额定功率/额定电压/额定电流/设计寿命/能耗标准
  ├── 维保信息：维保单位/联系人/电话/合同编号/合同起止日期
  ├── 财务信息：购置日期/购置价格/保修到期日期
  ├── 特种设备信息（条件显示）：设备类型/证书/检验周期/上次/下次检验
  ├── 设备照片：照片画廊 + 上传
  └── 电子文档：文档列表 + 上传

5.4 健康预测操作流程

设备健康页
  ├── 选择项目 → 加载设备列表
  ├── 选择设备 → 点击查询
  ├── 健康度概览（4个统计卡片）
  │   ├── 健康度评分（颜色随分数变化：≥80绿/≥60橙/<60红）
  │   ├── 健康等级（Tag标签）
  │   ├── 风险等级（Tag标签）
  │   └── 最后检测时间
  ├── MTBF/MTTR 指标卡片
  │   ├── MTBF：平均故障间隔天数 + 总故障次数 + 总运行时长
  │   └── MTTR：平均修复小时 + 总维修次数 + 总维修时长
  ├── 健康度趋势图（ECharts 折线图，近30天）
  ├── 风险因素 + 维护建议
  └── 故障历史表格（时间/类型/等级/描述/维修时间/状态）

5.5 维保管理流程

维保计划页
  ├── 选择项目 → 加载设备列表
  ├── 创建计划：名称/设备/类型/周期/下次维保日期
  └── 计划列表：名称/设备/类型/周期/下次日期/状态

维保工单页
  ├── 工单列表：编号/标题/设备/类型/触发类型/优先级/状态
  ├── 工单操作：创建/分配/开始执行/完成/验证/取消
  └── 工单统计卡片

5.6 归属主体管理流程

归属主体（在设备表单中通过下拉选择使用）
  ├── 创建主体：类型/名称/联系人/电话/地址/营业执照/法人/合同信息/租赁费用
  ├── 按类型筛选：公司/业主/租赁公司
  └── 设备表单中：归属类型 → 联动归属主体下拉

六、与原需求文档 03-ASSET.md 的差异对比

6.1 数据模型差异

对比项	原需求文档(03-ASSET.md)	实际实现	差异分析
设备类型枚举	8种(ELEVATOR/AC/FIRE_FIGHTING/PLUMBING/POWER_SUPPLY/SECURITY/PARKING/OTHER)	10种(ELEVATOR/HVAC/FIRE_PROTECTION/PLUMBING/ELECTRICAL/ENERGY_METER/SECURITY/LANDSCAPE/KITCHEN/OTHER)	⚠️ 枚举值名称和数量均不同；新增ENERGY_METER/LANDSCAPE/KITCHEN；AC→HVAC；FIRE_FIGHTING→FIRE_PROTECTION；POWER_SUPPLY→ELECTRICAL；删除PARKING
设备状态枚举	NORMAL/FAULT/MAINTAINING/SCRAPPED	ACTIVE/INACTIVE/MAINTENANCE/SCRAPPED	⚠️ 枚举值名称不同：NORMAL→ACTIVE, FAULT→INACTIVE, MAINTAINING→MAINTENANCE
扩展表	无（仅attributes JSONB）	4张扩展表(Elevator/Hvac/Fire/Energy)	🔴 重大差异：实际实现了专业扩展表模式
系统类型	无	SystemType(9种，商业地产8大系统)	🔴 新增：原需求无此概念
归属管理	无	OwnershipType(4种) + OwnershipEntity(3种主体)	🔴 新增：原需求无此概念
健康评分	无	EquipmentHealthScore + MTBF/MTTR算法	🔴 新增：原需求无此概念
故障历史	无	EquipmentFailureHistory(4级故障/4种类型/4种修复结果)	🔴 新增：原需求无此概念
设备照片/文档	无	JSONB内嵌(EquipmentPhoto/EquipmentDocument)	🔴 新增：原需求无此概念
维保计划	MaintenancePlan实体(在asset模块)	迁移至独立API(maintenance-plan.ts)	⚠️ 架构调整：维保计划独立
维保记录	MaintenanceRecord实体(在asset模块)	迁移至维保工单(maintenance-task.ts)	⚠️ 架构调整：维保记录升级为工单
设备编码字段	code	equipmentCode	⚠️ 字段名不同
设备名称字段	name	equipmentName	⚠️ 字段名不同
位置描述	locationDesc	installationLocation	⚠️ 字段名不同
品牌字段	brand	无(使用manufacturer)	⚠️ 原需求有brand，实际用manufacturer替代
规格字段	specifications	无	🔴 原需求有，实际未实现
负责人	managerId/managerName/contactPhone	无(使用维保商字段替代)	🔴 原需求有设备负责人，实际改为维保商
二维码	qrCode	无	🔴 原需求有，实际未实现
导入导出	无	Excel导入导出(含校验)	🔴 新增：原需求无此概念
批量删除	无	batch-delete接口	🔴 新增
财务信息	purchaseDate/installDate/warrantyDate	purchaseDate/purchasePrice/warrantyExpireDate + 更多	⚠️ 实际更丰富
特种设备	无	specialEquipmentType/specialEquipmentCert/inspectionCycle	🔴 新增
能耗标准	无	energyConsumptionStandard	🔴 新增

6.2 功能差异

功能	原需求文档	实际实现	差异
设备CRUD	✅	✅	一致
设备与空间关联	✅	✅	一致
设备二维码	✅	❌	未实现
故障自动工单	✅ (事件驱动)	🟡 (故障记录+关联工单ID)	部分实现，非事件驱动
IoT集成	🟡 (计划)	❌	未实现
维保到期提醒	✅ (定时任务)	🟡 (前端展示下次维保日期)	无后端定时提醒
设备健康预测	❌	✅ (完整算法+前端图表)	超出原需求
归属主体管理	❌	✅ (3种主体+4种归属)	超出原需求
专业扩展表	❌	✅ (4张扩展表)	超出原需求
Excel导入导出	❌	✅ (含校验)	超出原需求
MTBF/MTTR	❌	✅ (可配置周期)	超出原需求
设备照片/文档	❌	✅ (JSONB内嵌)	超出原需求
维保计划	✅ (asset模块内)	✅ (独立API)	架构调整
维保记录	✅ (asset模块内)	✅ (升级为维保工单)	架构升级

6.3 实现状态总结

模块	状态	说明
设备主表CRUD	🟢 完成	含批量删除
4张扩展表	🟢 完成	电梯/暖通/消防/能源
健康评分算法	🟢 完成	含MTBF/MTTR
故障历史管理	🟢 完成	含自动计算修复/停机时长
归属主体管理	🟢 完成	直接Repository操作
Excel导入导出	🟢 完成	含完整校验
设备统计	🟢 完成	按类型/归属/总数
前端设备列表	🟢 完成	含筛选/分页/操作
前端设备详情	🟢 完成	含照片/文档管理
前端健康预测	🟢 完成	含ECharts趋势图
维保完成率计算	🟡 TODO	代码中标记TODO，暂返回1.0
设备二维码	🔴 未实现	原需求有但未实现
IoT集成	🔴 未实现	原需求有但未实现
故障自动工单(事件驱动)	🔴 未实现	原需求有但未实现
维保到期定时提醒	🔴 未实现	原需求有但未实现

6.4 已知代码问题

问题	位置	说明
健康评分查询SpaceNode而非Equipment	EquipmentHealthServiceImpl	calculateHealthScore() 查询 SpaceNode 而非 Equipment 实体，导致设备年龄计算使用 maintenanceContractStart 而非 installationDate
projectId硬编码为全零UUID	EquipmentHealthServiceImpl	`UUID.fromString("00000000-0000-0000-0000-000000000000")`，应从设备实体获取
OwnershipEntityController绕过Service层	OwnershipEntityController	直接注入Repository，不符合分层架构
维保完成率固定为1.0	EquipmentHealthServiceImpl	TODO标记，暂跳过维保完成率计算
前端EquipmentType与后端SystemType不一致	equipment.ts	前端SystemType含FIRE_PROTECTION，后端SystemType含FIRE
扩展表仅4种有对应	EquipmentType vs 扩展表	PLUMBING/ELECTRICAL/SECURITY/LANDSCAPE/KITCHEN/OTHER 无扩展表

文档说明: 本文档基于 module-asset 模块的实际代码反推生成，与原需求文档 03-ASSET.md 存在显著差异，主要体现在：实际实现远超原需求（健康预测/归属管理/扩展表/导入导出），但部分原需求功能未实现（二维码/IoT/事件驱动工单/定时提醒）。

38 KiB Raw Blame History Unescape Escape