# 设施设备领域技术方案

**领域编号**: 4.3  
**微服务**: ether-asset  
**最后更新**: 2026-02-14

---

## 一、领域概述

### 1.1 领域职责

设施设备领域负责管理物业资产全生命周期：

- 设备台账管理（电梯、空调、消防、给排水、供配电等）
- 设备维保计划与记录
- 设备故障管理
- 设备与工单联动

### 1.2 核心概念

| 概念         | 说明                         | 对应实体          |
| ------------ | ---------------------------- | ----------------- |
| **设备台账** | 设备基础信息和运行状态       | Equipment         |
| **维保计划** | 定期保养计划                 | MaintenancePlan   |
| **维保记录** | 保养执行记录                 | MaintenanceRecord |
| **设备类型** | 设备分类（电梯/空调/消防等） | EquipmentType     |

---

## 二、领域模型

### 2.1 聚合根设计

#### Equipment（设备台账）

```java
@Entity
@Table(name = "asset_equipment")
@Data
public class Equipment {
    @Id
    private UUID id;
    private UUID projectId;

    private String code;           // 设备编码
    private String name;           // 设备名称

    // 分类
    private EquipmentType type;    // ELEVATOR/AC/FIRE/PLUMBING/POWER
    private EquipmentStatus status; // NORMAL/FAULT/MAINTAINING/SCRAPPED

    // 品牌型号
    private String brand;
    private String model;
    private String specifications;
    private String serialNumber;

    // 厂商信息
    private String manufacturer;
    private String supplier;
    private String supplierPhone;

    // 位置
    private UUID spaceNodeId;      // 关联空间节点
    private String locationDesc;   // 位置描述

    // 时间
    private LocalDate purchaseDate;
    private LocalDate installDate;
    private LocalDate warrantyDate;
    private Integer lifespanYears; // 设计寿命(年)

    // 维保
    private Integer maintenanceCycle;    // 保养周期(天)
    private LocalDate lastMaintenanceDate;
    private LocalDate nextMaintenanceDate;

    // 负责人
    private UUID managerId;
    private String managerName;
    private String contactPhone;

    // 二维码
    private String qrCode;

    // 扩展属性(JSONB)
    private String attributes;

    // 审计字段
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}
```

**设备类型枚举**:

```java
public enum EquipmentType {
    ELEVATOR("电梯"),
    AIR_CONDITIONER("空调"),
    FIRE_FIGHTING("消防设备"),
    PLUMBING("给排水"),
    POWER_SUPPLY("供配电"),
    SECURITY("安防设备"),
    PARKING("停车设备"),
    OTHER("其他");
}
```

#### MaintenancePlan（维保计划）

```java
@Entity
@Table(name = "asset_maintenance_plan")
@Data
public class MaintenancePlan {
    @Id
    private UUID id;
    private UUID projectId;
    private UUID equipmentId;      // 关联设备

    private String name;
    private MaintenanceType type;  // DAILY/WEEKLY/MONTHLY/QUARTERLY/YEARLY

    // 周期
    private Integer cycleDays;     // 周期天数
    private String cronExpression; // Cron表达式

    // 内容
    private String content;        // 保养内容描述
    private String checkItems;     // 检查项清单(JSON)

    // 负责人
    private UUID maintainerId;
    private String maintainerName;

    // 提醒
    private Integer remindDays;    // 提前提醒天数

    // 状态
    private Boolean enabled;

    // 审计字段
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}
```

#### MaintenanceRecord（维保记录）

```java
@Entity
@Table(name = "asset_maintenance_record")
@Data
public class MaintenanceRecord {
    @Id
    private UUID id;
    private UUID equipmentId;
    private UUID planId;           // 关联计划

    // 维保信息
    private LocalDate maintenanceDate;
    private MaintenanceType type;
    private String content;

    // 执行人
    private UUID maintainerId;
    private String maintainerName;

    // 结果
    private MaintenanceResult result; // NORMAL/ABNORMAL
    private String remark;
    private String images;

    // 检查项结果
    private String checkResults;   // [{"item":"检查A","result":"PASS"}]

    // 关联工单
    private UUID workOrderId;      // 异常时关联的维修工单

    // 下次维保
    private LocalDate nextMaintenanceDate;

    // 审计字段
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
}
```

---

## 三、设备与工单联动

### 3.1 故障自动报修

```java
@Component
public class EquipmentFaultHandler {

    @Autowired
    private WorkOrderService workOrderService;

    @EventListener
    public void onEquipmentFault(EquipmentFaultEvent event) {
        Equipment equipment = event.getEquipment();

        // 创建设备维修工单
        WorkOrder workOrder = new WorkOrder();
        workOrder.setOrderType(WorkOrderType.REPAIR);
        workOrder.setTitle("设备故障: " + equipment.getName());
        workOrder.setDescription(event.getFaultDescription());
        workOrder.setEquipmentId(equipment.getId());
        workOrder.setSpaceNodeId(equipment.getSpaceNodeId());
        workOrder.setPriority(WorkOrderPriority.HIGH);
        workOrder.setSource(WorkOrderSource.IOT);

        workOrderService.create(workOrder);

        // 更新设备状态
        equipment.setStatus(EquipmentStatus.FAULT);
        equipmentRepository.save(equipment);
    }
}
```

### 3.2 维保到期提醒

```java
@Component
public class MaintenanceReminderJob {

    @Scheduled(cron = "0 0 9 * * ?") // 每天9点执行
    public void remindUpcomingMaintenance() {
        // 查询7天内到期的维保计划
        LocalDate targetDate = LocalDate.now().plusDays(7);

        List<Equipment> equipments = equipmentRepository
            .findByNextMaintenanceDateBeforeAndStatus(targetDate, EquipmentStatus.NORMAL);

        for (Equipment equipment : equipments) {
            notificationService.sendMaintenanceReminder(equipment);
        }
    }
}
```

---

## 四、实现状态与差异

### 4.1 实现状态

| 功能模块          | 实现状态    | 备注                   |
| ----------------- | ----------- | ---------------------- |
| Equipment         | 🟢 已实现   | 基础CRUD、二维码生成   |
| MaintenancePlan   | 🟢 已实现   | 已迁移至 ether-asset   |
| MaintenanceRecord | 🟢 已实现   | 已迁移至 ether-asset   |
| 设备二维码        | 🟢 已实现   | 支持扫码查看设备信息   |
| 故障自动工单      | 🟡 部分实现 | 设备状态变更可关联工单 |
| IoT集成           | 🔴 未实现   | 待开发                 |

### 4.2 与设计方案的差异

| 设计项       | 设计方案     | 现有实现    | 差异分析                                |
| ------------ | ------------ | ----------- | --------------------------------------- |
| **维保归属** | ether-asset  | ether-asset | ✅ 已修正：维保实体已统一在 ether-asset |
| **设备管理** | ether-asset  | ether-asset | ✅ 已修正：设备实体已统一在 ether-asset |
| **设备联动** | 故障自动工单 | 部分实现    | 🟡 功能完善中                           |

### 4.3 改进计划

| 优先级 | 改进项             | 说明                                                 |
| ------ | ------------------ | ---------------------------------------------------- |
| ~~P1~~ | ~~迁移维保实体~~   | ~~将MaintenancePlan/Record迁移到ether-asset~~ 已完成 |
| P2     | 完善故障自动工单   | 设备状态变更时自动创建维修工单                       |
| P2     | 完善设备二维码功能 | 支持扫码报修                                         |
| P3     | IoT传感器接入      | 对接传感器数据                                       |

---

## 五、数据库表结构

```sql
-- 设备台账表
CREATE TABLE asset_equipment (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    code VARCHAR(50) NOT NULL,
    name VARCHAR(100) NOT NULL,
    type VARCHAR(20) NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'NORMAL',
    brand VARCHAR(100),
    model VARCHAR(100),
    specifications VARCHAR(500),
    serial_number VARCHAR(100),
    manufacturer VARCHAR(100),
    supplier VARCHAR(100),
    supplier_phone VARCHAR(20),
    space_node_id UUID,
    location_desc VARCHAR(255),
    purchase_date DATE,
    install_date DATE,
    warranty_date DATE,
    lifespan_years INTEGER,
    maintenance_cycle INTEGER,
    last_maintenance_date DATE,
    next_maintenance_date DATE,
    manager_id UUID,
    manager_name VARCHAR(100),
    contact_phone VARCHAR(20),
    qr_code VARCHAR(255),
    attributes JSONB,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE(project_id, code)
);

-- 维保计划表
CREATE TABLE asset_maintenance_plan (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    equipment_id UUID NOT NULL,
    name VARCHAR(100) NOT NULL,
    type VARCHAR(20) NOT NULL,
    cycle_days INTEGER,
    cron_expression VARCHAR(50),
    content TEXT,
    check_items JSONB,
    maintainer_id UUID,
    maintainer_name VARCHAR(100),
    remind_days INTEGER DEFAULT 3,
    enabled BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- 维保记录表
CREATE TABLE asset_maintenance_record (
    id UUID PRIMARY KEY,
    equipment_id UUID NOT NULL,
    plan_id UUID,
    maintenance_date DATE NOT NULL,
    type VARCHAR(20) NOT NULL,
    content TEXT,
    maintainer_id UUID,
    maintainer_name VARCHAR(100),
    result VARCHAR(20),
    remark VARCHAR(500),
    images TEXT,
    check_results JSONB,
    work_order_id UUID,
    next_maintenance_date DATE,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

-- 创建索引
CREATE INDEX idx_equipment_project ON asset_equipment(project_id);
CREATE INDEX idx_equipment_type ON asset_equipment(type);
CREATE INDEX idx_equipment_status ON asset_equipment(status);
CREATE INDEX idx_equipment_space ON asset_equipment(space_node_id);
CREATE INDEX idx_equipment_next_maintenance ON asset_equipment(next_maintenance_date);
CREATE INDEX idx_maintenance_plan_equipment ON asset_maintenance_plan(equipment_id);
CREATE INDEX idx_maintenance_record_equipment ON asset_maintenance_record(equipment_id);
```

---

**文档维护**: 本领域技术方案由 ether-asset 服务负责人维护