ether-docs/02-DESIGN/domains/03-ASSET.md

设施设备领域技术方案

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

---

一、领域概述

1.1 领域职责

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

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

1.2 核心概念

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

---

二、领域模型

2.1 聚合根设计

Equipment（设备台账）

@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;
}

设备类型枚举:

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

MaintenancePlan（维保计划）

@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（维保记录）

@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 故障自动报修

@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 维保到期提醒

@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传感器接入	对接传感器数据

---

五、数据库表结构

-- 设备台账表
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 服务负责人维护