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

**领域编号**: 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 模式：存在则更新，不存在则新建

**扩展表服务接口模式**（以电梯为例）:
```java
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

#### 设备年龄计算

```java
设备年龄 = 安装年份 + 安装月份/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/事件驱动工单/定时提醒）。