ether-docs/DOMAIN_IMPLEMENTATION_PLAN.md at cd86a97007e011916ecc4317cec7011808f89cf5

36 KiB

Raw Blame History

Ether 智慧物业管理平台 - 领域技术实现方案

文档版本: v1.0
最后更新: 2026-02-10
编制依据: 需求规格说明书、领域模型详细设计、现有代码实现

一、领域划分总览

根据需求规格说明书，系统划分为 6大领域：

领域	微服务	核心职责	实现状态
4.1 空间与主数据领域	ether-mdm	物理数字孪生底座	🟡 部分实现
4.2 运营调度领域	ether-ops	工单、巡检、排班、访客	🟢 基本实现
4.3 设施设备领域	ether-asset	资产台账、维保计划	🟡 部分实现
4.4 财务计费领域	ether-finance	账单、支付、退款	🟡 部分实现
4.5 权限与账户领域	ether-auth	RBAC、访客凭证、项目隔离	🟢 基本实现
4.6 集成中心领域	ether-hub	外部系统适配、IoT网关	🔴 未实现

图例说明: 🟢 基本实现 | 🟡 部分实现 | 🔴 未实现

二、各领域技术实现方案

2.1 空间与主数据领域 (ether-mdm)

2.1.1 领域职责

管理物理空间的数字孪生（园区→楼栋→楼层→房间）
房产明细与权属关系
业主信息管理
巡检管理（计划、任务、记录）
访客管理（预约、记录、黑名单）

2.1.2 核心聚合根设计

// 聚合根: SpaceNode - 空间节点
@Entity
@Table(name = "mdm_space_node")
public class SpaceNode {
    @Id
    private UUID id;
    
    private UUID projectId;
    private String code;           // 节点编码
    private String name;           // 节点名称
    private SpaceNodeType nodeType; // 类型: PROJECT/BUILDING/FLOOR/ROOM/AREA
    private SpaceNodeStatus status;
    
    // 树形结构
    private UUID parentId;
    private String treePath;       // Ltree路径: 1.2.3.4
    private Integer level;
    
    // 空间属性
    private BigDecimal areaSqm;
    private BigDecimal longitude;
    private BigDecimal latitude;
    private String address;
    
    // 扩展属性(JSONB)
    private String attributes;
}

// 聚合根: RoomDetail - 房间详情
@Entity
@Table(name = "mdm_room_detail")
public class RoomDetail {
    @Id
    private UUID id;
    private UUID spaceNodeId;      // 关联SpaceNode
    
    // 房产属性
    private String roomType;       // 住宅/商铺/办公/仓库
    private BigDecimal buildArea;  // 建筑面积
    private BigDecimal usableArea; // 使用面积
    private String orientation;    // 朝向
    private Integer floor;         // 所在楼层
    
    // 状态
    private RoomStatus status;     // 空置/已售/已租/装修中
}

// 聚合根: Ownership - 产权信息
@Entity
@Table(name = "mdm_ownership")
public class Ownership {
    @Id
    private UUID id;
    
    private UUID spaceNodeId;      // 关联房产
    private UUID ownerId;          // 关联业主
    
    // 产权属性
    private OwnershipType type;    // 产权/使用权/租赁权
    private BigDecimal sharePercent; // 产权份额
    private LocalDate startDate;   // 起始日期
    private LocalDate endDate;     // 结束日期(租赁)
    
    // 证件信息
    private String certType;       // 证件类型
    private String certNo;         // 证件号码
    private String certFileUrl;    // 证件扫描件
}

// 聚合根: Owner - 业主
@Entity
@Table(name = "mdm_owner")
public class Owner {
    @Id
    private UUID id;
    private UUID projectId;
    
    // 基本信息
    private String name;
    private String phone;
    private String email;
    private OwnerType type;        // 个人/企业
    
    // 证件信息
    private String idCardType;
    private String idCardNo;
    
    // 关联账户
    private UUID userId;           // 关联系统用户
}

2.1.3 现有实现与设计方案差异

设计项	设计方案	现有实现	差异分析
SpaceNode	使用PostGIS的geometry类型	使用longitude/latitude字段	⚠️ 移除了PostGIS依赖，简化实现
RoomDetail	独立实体，关联SpaceNode	已实现	✅ 符合设计
Ownership	独立聚合根	已实现	✅ 符合设计
Owner	独立聚合根	已实现	✅ 符合设计
树形结构	使用PostgreSQL ltree扩展	使用treePath字符串	⚠️ 未使用ltree扩展

2.1.4 巡检管理实现

// 聚合根: InspectionPlan - 巡检计划
@Entity
@Table(name = "mdm_inspection_plan")
public class InspectionPlan {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String name;
    private String description;
    
    // 巡检类型
    private InspectionType type;   // 日常/定期/专项
    
    // 周期配置
    private String cronExpression; // Cron表达式
    private LocalTime executeTime; // 执行时间
    
    // 关联巡检点
    @OneToMany(mappedBy = "plan")
    private List<InspectionPoint> points;
}

// 实体: InspectionPoint - 巡检点
@Entity
@Table(name = "mdm_inspection_point")
public class InspectionPoint {
    @Id
    private UUID id;
    private UUID planId;
    
    private UUID spaceNodeId;      // 关联空间节点
    private String name;
    private String description;
    private Integer sortOrder;
    
    // 检查项(JSONB)
    private String checkItems;     // [{"item":"消防设施","standard":"正常"}]
}

// 聚合根: InspectionTask - 巡检任务
@Entity
@Table(name = "mdm_inspection_task")
public class InspectionTask {
    @Id
    private UUID id;
    private UUID projectId;
    private UUID planId;           // 关联计划
    
    private String taskNo;
    private LocalDate planDate;    // 计划日期
    
    // 执行人
    private UUID inspectorId;
    private String inspectorName;
    
    // 状态
    private TaskStatus status;     // 待执行/执行中/已完成/逾期
    
    // 时间记录
    private LocalDateTime startTime;
    private LocalDateTime endTime;
    
    // 关联记录
    @OneToMany(mappedBy = "task")
    private List<InspectionRecord> records;
}

实现状态: ✅ 已实现 InspectionPlan、InspectionPoint、InspectionTask、InspectionRecord

2.1.5 访客管理实现

// 聚合根: VisitorAppointment - 访客预约
@Entity
@Table(name = "mdm_visitor_appointment")
public class VisitorAppointment {
    @Id
    private UUID id;
    private UUID projectId;
    
    // 访客信息
    private String visitorName;
    private String visitorPhone;
    private String visitorIdCard;
    private VisitorType visitorType; // 访客/快递/外卖/维修
    
    // 被访人信息
    private UUID hostId;
    private String hostName;
    private String hostPhone;
    private UUID spaceNodeId;      // 访问地点
    
    // 预约信息
    private LocalDate visitDate;
    private LocalTime visitTime;
    private String purpose;
    
    // 凭证
    private String qrCode;         // 动态二维码
    private LocalDateTime qrExpireTime;
    
    // 状态
    private AppointmentStatus status; // 待确认/已确认/已取消/已完成
}

// 实体: VisitorAccessRecord - 访客通行记录
@Entity
@Table(name = "mdm_visitor_access_record")
public class VisitorAccessRecord {
    @Id
    private UUID id;
    private UUID appointmentId;
    
    // 通行信息
    private LocalDateTime entryTime;
    private LocalDateTime exitTime;
    private String entryGate;      // 入口
    private String exitGate;       // 出口
    
    // 验证方式
    private VerifyType verifyType; // 二维码/身份证/人脸识别
    private String verifyCode;
}

// 实体: VisitorBlacklist - 访客黑名单
@Entity
@Table(name = "mdm_visitor_blacklist")
public class VisitorBlacklist {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String visitorName;
    private String visitorPhone;
    private String visitorIdCard;
    
    private String reason;         // 拉黑原因
    private LocalDateTime blockTime;
    private LocalDateTime expireTime; // 过期时间(null为永久)
}

实现状态: ✅ 已实现 VisitorAppointment、VisitorAccessRecord、VisitorBlacklist

2.1.6 改进计划

优先级	改进项	说明
P1	完善SpaceNode树形结构	考虑引入ltree扩展或实现路径枚举模式
P2	添加空间搜索功能	基于经纬度的附近空间查询
P3	优化房产绑定流程	实现业主-房产-账户的自动关联

2.2 运营调度领域 (ether-ops)

2.2.1 领域职责

综合工单管理（创建、分配、处理、关闭）
工单流转记录
消息通知系统（模板、规则、渠道）
工单统计与分析

2.2.2 核心聚合根设计

// 聚合根: WorkOrder - 综合工单
@Entity
@Table(name = "ops_work_order")
public class WorkOrder {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String orderNo;        // 工单编号: WO2024021000001
    
    // 工单类型
    private WorkOrderType orderType; // 维修/投诉/保洁/安保/其他
    private WorkOrderStatus status;  // 状态机
    private WorkOrderPriority priority; // 紧急/高/中/低
    private WorkOrderSource source;   // 来源: APP/电话/巡检/IoT
    
    // 基本信息
    private String title;
    private String description;
    
    // 报修人信息
    private UUID reporterId;
    private String reporterName;
    private String reporterPhone;
    private String reporterAddress;
    
    // 关联信息
    private UUID spaceNodeId;      // 关联空间
    private UUID equipmentId;      // 关联设备
    
    // 处理人信息
    private UUID assigneeId;
    private String assigneeName;
    private LocalDateTime assignedAt;
    private LocalDateTime acceptedAt;
    private LocalDateTime startedAt;
    private LocalDateTime completedAt;
    private LocalDateTime closedAt;
    
    // 费用
    private BigDecimal actualCost;
    private BigDecimal materialCost;
    private BigDecimal laborCost;
    
    // 结果
    private String resultDescription;
    private Integer satisfactionScore;
    private String satisfactionComment;
    
    // 附件
    private String images;
    private String attachments;
    
    // 扩展属性
    private String attributes;
}

// 实体: WorkOrderFlow - 工单流转记录
@Entity
@Table(name = "ops_work_order_flow")
public class WorkOrderFlow {
    @Id
    private UUID id;
    private UUID workOrderId;
    
    // 流转信息
    private WorkOrderStatus fromStatus;
    private WorkOrderStatus toStatus;
    private String action;         // 操作: 分配/接单/完成/关闭
    
    // 操作人
    private UUID operatorId;
    private String operatorName;
    private LocalDateTime operateTime;
    
    // 备注
    private String remark;
}

实现状态: ✅ 已实现 WorkOrder、WorkOrderFlow，包含完整状态机

2.2.3 状态机设计

CREATED(已创建)
    ↓ [分配]
ASSIGNED(已分配)
    ↓ [接单]
ACCEPTED(已接单)
    ↓ [开始处理]
IN_PROGRESS(处理中)
    ↓ [完成]
COMPLETED(已完成)
    ↓ [关闭]
CLOSED(已关闭)

特殊流转:
- 任意状态 → SUSPENDED(已挂起) → 恢复
- ASSIGNED → RETURNED(已退回) → 重新分配

实现状态: ✅ 状态机已实现，包含所有状态流转

2.2.4 消息通知系统

// 聚合根: NotificationChannel - 通知渠道
@Entity
@Table(name = "ops_notification_channel")
public class NotificationChannel {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String name;
    private ChannelType type;      // 站内信/短信/邮件/推送/企业微信
    
    // 配置(JSONB)
    private String config;         // 渠道配置参数
    private Boolean enabled;
    private Integer priority;      // 优先级
}

// 聚合根: NotificationTemplate - 消息模板
@Entity
@Table(name = "ops_notification_template")
public class NotificationTemplate {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String name;
    private String code;           // 模板编码
    
    // 模板内容
    private String titleTemplate;
    private String contentTemplate;
    
    // 变量定义
    private String variables;      // ["orderNo", "title", "assigneeName"]
    
    // 适用渠道
    private String channels;       // ["SITE_MESSAGE", "SMS"]
}

// 聚合根: NotificationRule - 通知规则
@Entity
@Table(name = "ops_notification_rule")
public class NotificationRule {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String name;
    private String eventType;      // 事件类型: WORK_ORDER_CREATED
    
    // 触发条件
    private String conditions;     // JSON条件表达式
    
    // 通知配置
    private String templateCode;   // 关联模板
    private String receivers;      // 接收人配置: ["CREATOR", "ASSIGNEE"]
    private String channels;       // 通知渠道
    
    private Boolean enabled;
}

// 实体: NotificationHistory - 通知历史
@Entity
@Table(name = "ops_notification_history")
public class NotificationHistory {
    @Id
    private UUID id;
    private UUID projectId;
    
    // 通知内容
    private String title;
    private String content;
    private String eventType;
    
    // 接收人
    private UUID receiverId;
    private String receiverName;
    private String receiverPhone;
    
    // 渠道信息
    private ChannelType channel;
    private String channelMsgId;   // 渠道消息ID
    
    // 状态
    private NotificationStatus status; // 待发送/已发送/发送失败/已读
    private LocalDateTime sendTime;
    private LocalDateTime readTime;
    
    // 关联业务
    private String businessType;
    private String businessId;
}

实现状态: ✅ 已实现 NotificationChannel、NotificationTemplate、NotificationRule、NotificationHistory

2.2.5 工单与通知集成

// 工单事件监听器
@Component
public class WorkOrderEventListener {
    
    @EventListener
    public void onWorkOrderCreated(WorkOrderCreatedEvent event) {
        // 触发通知规则
        notificationService.triggerRule("WORK_ORDER_CREATED", event.getWorkOrder());
    }
    
    @EventListener
    public void onWorkOrderAssigned(WorkOrderAssignedEvent event) {
        notificationService.triggerRule("WORK_ORDER_ASSIGNED", event.getWorkOrder());
    }
}

实现状态: ✅ 已实现工单与通知系统集成

2.2.6 改进计划

优先级	改进项	说明
P2	添加工单满意度评价	业主对工单处理结果的评价
P2	实现SLA监控	工单超时预警和升级机制
P3	智能派单算法	基于位置、负载、技能的自动派单

2.3 设施设备领域 (ether-asset)

2.3.1 领域职责

设备台账管理
设备维保计划
设备故障管理
设备与工单联动

2.3.2 核心聚合根设计

// 聚合根: Equipment - 设备台账
@Entity
@Table(name = "asset_equipment")
public class Equipment {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String code;           // 设备编码
    private String name;           // 设备名称
    
    // 分类
    private EquipmentType equipmentType; // 电梯/空调/消防/给排水/供配电
    private EquipmentStatus status;      // 正常/故障/维修中/报废
    
    // 品牌型号
    private String brand;
    private String model;
    private String specifications;
    private String serialNumber;
    
    // 厂商信息
    private String manufacturer;
    private String supplier;
    
    // 位置
    private UUID spaceNodeId;
    private String locationDesc;
    
    // 时间
    private LocalDate purchaseDate;
    private LocalDate installDate;
    private LocalDate warrantyDate;
    
    // 维保
    private Integer maintenanceCycle;    // 保养周期(天)
    private LocalDate lastMaintenanceDate;
    private LocalDate nextMaintenanceDate;
    
    // 负责人
    private UUID managerId;
    private String managerName;
    private String contactPhone;
    
    // 扩展属性
    private Map<String, Object> attributes;
}

// 聚合根: MaintenancePlan - 维保计划
@Entity
@Table(name = "asset_maintenance_plan")
public class MaintenancePlan {
    @Id
    private UUID id;
    private UUID projectId;
    private UUID equipmentId;
    
    private String name;
    private MaintenanceType type;  // 日常保养/定期检修/大修
    
    // 周期
    private Integer cycleDays;     // 周期天数
    private String cronExpression;
    
    // 内容
    private String content;        // 保养内容
    private String checkItems;     // 检查项清单
    
    // 负责人
    private UUID maintainerId;
    private String maintainerName;
}

// 实体: MaintenanceRecord - 维保记录
@Entity
@Table(name = "asset_maintenance_record")
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; // 正常/异常/需维修
    private String remark;
    private String images;
    
    // 关联工单
    private UUID workOrderId;      // 如产生维修工单
}

实现状态: ✅ 已实现 Equipment，⚠️ MaintenancePlan、MaintenanceRecord 在 ether-mdm 中实现

2.3.3 现有实现与设计方案差异

设计项	设计方案	现有实现	差异分析
Equipment	在 ether-asset 服务	在 ether-asset 服务	✅ 符合设计
MaintenancePlan	在 ether-asset 服务	在 ether-mdm 服务	❌ 领域归属错误
MaintenanceRecord	在 ether-asset 服务	在 ether-mdm 服务	❌ 领域归属错误

2.3.4 设备与工单联动

// 设备故障自动创建工单
@Component
public class EquipmentFaultHandler {
    
    @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);
    }
}

实现状态: ⚠️ 设计已定义，待实现

2.3.5 改进计划

优先级	改进项	说明
P1	迁移维保相关实体	将 MaintenancePlan、MaintenanceRecord 从 ether-mdm 迁移到 ether-asset
P2	实现设备故障自动工单	设备状态变更时自动创建维修工单
P2	添加设备二维码	为每台设备生成唯一二维码，支持扫码查看/报修
P3	设备IoT集成	对接传感器数据，实现故障预警

2.4 财务计费领域 (ether-finance)

2.4.1 领域职责

收费项目管理
账单生成与管理
支付处理
费用催缴通知

2.4.2 核心聚合根设计

// 聚合根: FeeItem - 收费项目
@Entity
@Table(name = "fin_fee_item")
public class FeeItem {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String code;           // 项目编码
    private String name;           // 项目名称
    private FeeType type;          // 物业费/停车费/水电费/维修基金
    
    // 计费规则
    private BillingMethod billingMethod; // 固定金额/按面积/按用量/自定义
    private BigDecimal unitPrice;  // 单价
    private String unit;           // 单位: 元/月、元/㎡·月
    
    // 账期
    private Integer billDay;       // 账单日(每月几号)
    private Integer dueDay;        // 到期日(每月几号)
    private Integer overdueDay;    // 逾期日(每月几号)
    
    // 滞纳金
    private Boolean enableLateFee;
    private BigDecimal lateFeeRate; // 滞纳金比例(日)
    
    // 状态
    private Boolean enabled;
}

// 聚合根: FeeBill - 收费账单
@Entity
@Table(name = "fin_fee_bill")
public class FeeBill {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String billNo;         // 账单编号
    
    // 关联信息
    private UUID feeItemId;        // 收费项目
    private UUID spaceNodeId;      // 关联房产
    private UUID ownerId;          // 关联业主
    
    // 账期
    private String billPeriod;     // 账期: 2024-02
    private LocalDate billDate;    // 账单日期
    private LocalDate dueDate;     // 到期日期
    private LocalDate overdueDate; // 逾期日期
    
    // 金额
    private BigDecimal amount;     // 应收金额
    private BigDecimal lateFee;    // 滞纳金
    private BigDecimal discount;   // 优惠金额
    private BigDecimal payableAmount; // 应付金额
    private BigDecimal paidAmount; // 已付金额
    
    // 状态
    private BillStatus status;     // 未缴费/部分缴费/已缴费/已逾期/已取消
    
    // 关联支付记录
    @OneToMany(mappedBy = "bill")
    private List<FeePayment> payments;
}

// 实体: FeePayment - 支付记录
@Entity
@Table(name = "fin_fee_payment")
public class FeePayment {
    @Id
    private UUID id;
    private UUID billId;
    
    private String paymentNo;      // 支付流水号
    private BigDecimal amount;     // 支付金额
    
    // 支付方式
    private PaymentMethod method;  // 微信支付/支付宝/现金/转账
    private String thirdPartyNo;   // 第三方支付流水号
    
    // 状态
    private PaymentStatus status;  // 待支付/支付成功/支付失败/已退款
    
    // 时间
    private LocalDateTime paymentTime;
    private String remark;
}

实现状态: ✅ 已实现 FeeItem、FeeBill、FeePayment

2.4.3 费用催缴通知

// 定时任务: 费用催缴
@Component
public class FeeReminderJob {
    
    @Scheduled(cron = "0 0 9 * * ?") // 每天9点执行
    public void remindUpcomingDue() {
        // 查询3天内到期的账单
        List<FeeBill> upcomingBills = feeBillRepository
            .findByDueDateBetweenAndStatus(LocalDate.now(), LocalDate.now().plusDays(3), BillStatus.UNPAID);
        
        for (FeeBill bill : upcomingBills) {
            notificationService.sendFeeReminder(bill, "FEE_UPCOMING_DUE");
        }
    }
    
    @Scheduled(cron = "0 0 9,18 * * ?") // 每天9点和18点执行
    public void remindOverdue() {
        // 查询已逾期的账单
        List<FeeBill> overdueBills = feeBillRepository
            .findByOverdueDateBeforeAndStatus(LocalDate.now(), BillStatus.UNPAID);
        
        for (FeeBill bill : overdueBills) {
            // 计算滞纳金
            calculateLateFee(bill);
            notificationService.sendFeeReminder(bill, "FEE_OVERDUE");
        }
    }
}

实现状态: ✅ 已实现费用催缴定时任务

2.4.4 现有实现与设计方案差异

设计项	设计方案	现有实现	差异分析
FeeItem	在 ether-finance 服务	在 ether-finance 服务	✅ 符合设计
FeeBill	在 ether-finance 服务	ether-finance + ether-mdm 重复	❌ 存在重复实体
FeePayment	在 ether-finance 服务	ether-finance + ether-mdm 重复	❌ 存在重复实体

2.4.5 改进计划

优先级	改进项	说明
P1	清理重复实体	删除 ether-mdm 中的 FeeItem、FeeBill、FeePayment
P2	实现退款功能	支持账单退款和退款审批流程
P2	添加财务报表	收费统计、欠费分析、收入趋势
P3	对接支付网关	集成微信支付、支付宝 SDK

2.5 权限与账户领域 (ether-auth)

2.5.1 领域职责

用户认证与授权
RBAC权限模型
项目隔离
访客凭证管理

2.5.2 核心聚合根设计

// 聚合根: User - 系统用户
@Entity
@Table(name = "auth_user")
public class User {
    @Id
    private UUID id;
    
    private String username;
    private String password;
    private String salt;           // 密码盐值
    
    // 基本信息
    private String realName;
    private String phone;
    private String email;
    
    // 状态
    private UserStatus status;
    private LocalDateTime lastLoginTime;
    
    // 关联角色
    @ManyToMany
    @JoinTable(name = "auth_user_role")
    private List<Role> roles;
}

// 聚合根: Role - 角色
@Entity
@Table(name = "auth_role")
public class Role {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String name;
    private String code;
    private RoleType type;         // 系统预设/自定义
    private DataScope dataScope;   // 数据权限范围
    
    // 关联权限
    @ManyToMany
    @JoinTable(name = "auth_role_permission")
    private List<Permission> permissions;
}

// 聚合根: Permission - 权限
@Entity
@Table(name = "auth_permission")
public class Permission {
    @Id
    private UUID id;
    
    private String name;
    private String code;           // 权限编码: user:create
    private PermissionType type;   // 菜单/按钮/API
    
    // 菜单属性
    private String path;           // 路由路径
    private String component;      // 组件路径
    private String icon;           // 图标
    private Integer sortOrder;
    
    // 树形结构
    private UUID parentId;
}

实现状态: ✅ 已实现 User、Role、Permission、UserRole、RolePermission

2.5.3 项目隔离实现

// 项目上下文拦截器
@Component
public class ProjectContextInterceptor implements HandlerInterceptor {
    
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        String projectId = request.getHeader("X-Project-ID");
        if (StringUtils.hasText(projectId)) {
            ProjectContextHolder.setCurrentProjectId(UUID.fromString(projectId));
        }
        return true;
    }
}

// 项目上下文持有者
public class ProjectContextHolder {
    private static final ThreadLocal<UUID> PROJECT_CONTEXT = new ThreadLocal<>();
    
    public static void setCurrentProjectId(UUID projectId) {
        PROJECT_CONTEXT.set(projectId);
    }
    
    public static UUID getCurrentProjectId() {
        return PROJECT_CONTEXT.get();
    }
}

实现状态: ✅ 已实现 ProjectContextInterceptor、ProjectContextHolder

2.5.4 访客凭证系统

// 访客凭证已在 ether-mdm 的 VisitorAppointment 中实现
// 包含动态二维码生成和过期机制

实现状态: ✅ 已实现动态二维码凭证

2.5.5 改进计划

优先级	改进项	说明
P2	完善数据权限	实现基于角色的数据范围控制（全部/部门/个人）
P3	添加操作日志	记录用户关键操作，支持审计
P3	实现单点登录	支持多端统一登录态

2.6 集成中心领域 (ether-hub)

2.6.1 领域职责

外部系统适配（停车系统、门禁系统、政府监管平台）
IoT设备接入
数据同步与转换
集成日志记录

2.6.2 核心聚合根设计

// 聚合根: IntegrationAdapter - 集成适配器
@Entity
@Table(name = "hub_integration_adapter")
public class IntegrationAdapter {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String name;
    private String systemType;     // PARKING/ACCESS/GOVERNMENT/IOT
    private String protocol;       // HTTP/MQTT/HTTPS/SOAP
    
    // 连接配置
    private String baseUrl;
    private String authType;       // NONE/API_KEY/OAUTH2/JWT
    private String authConfig;     // 认证配置(JSON)
    
    // 状态
    private Boolean enabled;
    private AdapterStatus status;  // 在线/离线/错误
    private LocalDateTime lastPingTime;
}

// 实体: IntegrationLog - 集成日志
@Entity
@Table(name = "hub_integration_log")
public class IntegrationLog {
    @Id
    private UUID id;
    private UUID adapterId;
    
    // 请求信息
    private String requestId;
    private String operation;      // 操作类型
    private String requestData;    // 请求数据
    
    // 响应信息
    private String responseData;   // 响应数据
    private Integer httpStatus;    // HTTP状态码
    private String errorMessage;   // 错误信息
    
    // 时间
    private LocalDateTime requestTime;
    private LocalDateTime responseTime;
    private Long durationMs;       // 耗时
    
    // 状态
    private LogStatus status;      // 成功/失败/超时
}

// IoT设备接入
@Entity
@Table(name = "hub_iot_device")
public class IoTDevice {
    @Id
    private UUID id;
    private UUID projectId;
    
    private String deviceId;       // 设备唯一标识
    private String deviceType;     // 传感器类型
    private String protocol;       // MQTT/CoAP/HTTP
    
    // 关联信息
    private UUID equipmentId;      // 关联设备台账
    
    // MQTT配置
    private String mqttTopic;      // 订阅主题
    private String lastPayload;    // 最后上报数据
    private LocalDateTime lastReportTime;
    
    // 状态
    private DeviceStatus status;   // 在线/离线/故障
}

实现状态: 🔴 未实现，需要新建 ether-hub 微服务

2.6.3 集成场景

集成系统	协议	功能
停车系统	HTTP API	车牌识别、车位状态同步
门禁系统	HTTP/MQTT	访客二维码下发、通行记录上报
政府监管	HTTP API	投诉工单同步、数据上报
IoT传感器	MQTT	实时数据采集、故障报警

2.6.4 改进计划

优先级	改进项	说明
P2	创建 ether-hub 服务	新建集成中心微服务
P3	实现停车系统集成	对接停车系统API
P3	实现门禁系统集成	对接门禁系统，支持访客二维码
P3	实现IoT接入	MQTT Broker配置，设备接入

三、领域间关系图

┌─────────────────────────────────────────────────────────────────┐
│                        前端层 (B端/C端/G端)                        │
└─────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────────┐
│                      API网关 (ether-gateway)                      │
│                    JWT认证 / 限流 / 路由转发                       │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
┌───────▼──────┐    ┌────────▼────────┐   ┌──────▼──────┐
│ ether-auth   │    │   ether-mdm     │   │  ether-ops  │
│ 权限与账户    │◄──►│  空间与主数据    │◄──►│  运营调度    │
│              │    │                 │   │             │
│ • User       │    │ • SpaceNode     │   │ • WorkOrder │
│ • Role       │    │ • RoomDetail    │   │ • Notification│
│ • Permission │    │ • Owner         │   │             │
└──────────────┘    │ • Visitor       │   └─────────────┘
        │           │ • Inspection    │          │
        │           └─────────────────┘          │
        │                     │                  │
        │    ┌────────────────┼────────────────┐ │
        │    │                │                │ │
┌───────▼────▼───┐  ┌────────▼────────┐ ┌────▼─▼──────┐
│ ether-asset    │  │ ether-finance   │ │  ether-hub  │
│ 设施设备        │  │ 财务计费         │ │  集成中心    │
│                │  │                 │ │             │
│ • Equipment    │  │ • FeeItem       │ │ • Adapter   │
│ • Maintenance  │  │ • FeeBill       │ │ • IoTDevice │
│                │  │ • FeePayment    │ │             │
└────────────────┘  └─────────────────┘ └─────────────┘

四、总体差异分析汇总

4.1 领域归属差异

实体	设计归属	实际归属	差异等级
EquipmentMaintenance	ether-asset	ether-mdm	🔴 高
FeeItem/FeeBill/FeePayment	ether-finance	ether-mdm + ether-finance	🔴 高
InspectionPlan/Task	ether-ops	ether-mdm	🟡 中
VisitorAppointment	ether-ops	ether-mdm	🟡 中

4.2 缺失实现

领域	缺失内容	优先级
ether-hub	整个微服务未创建	P2
ether-asset	MaintenancePlan/Record 迁移	P1
ether-finance	退款功能、财务报表	P2
ether-ops	SLA监控、智能派单	P3

4.3 技术实现差异

设计项	设计方案	实际实现	影响
空间坐标	PostGIS geometry	longitude/latitude	功能降级
树形结构	PostgreSQL ltree	字符串路径	性能影响
设备联动	事件驱动	未实现	功能缺失

五、改进路线图

Phase 1: 领域归属调整（1-2周）

迁移 Maintenance 相关实体
- 将 EquipmentMaintenance 从 ether-mdm 迁移到 ether-asset
- 更新外键关联和查询逻辑
清理财务重复实体
- 删除 ether-mdm 中的 FeeItem、FeeBill、FeePayment
- 统一使用 ether-finance 的实体
调整巡检和访客归属
- 评估是否需要将 Inspection、Visitor 迁移到 ether-ops
- 或保持现状，在文档中明确领域边界

Phase 2: 功能完善（2-4周）

创建设备联动
- 实现设备故障自动创建工单
- 工单完成后更新设备状态
完善财务功能
- 实现退款功能
- 添加财务报表
增强权限系统
- 实现数据权限范围控制
- 添加操作日志

Phase 3: 集成中心（4-6周）

创建 ether-hub 服务
- 基础框架搭建
- 数据库表设计
实现停车系统集成
- 对接停车系统API
- 车位状态同步
实现门禁集成
- 访客二维码下发
- 通行记录上报

六、文档维护

维护原则:

每次领域调整时更新本文档
新增实体时必须明确领域归属
定期（每季度）审查领域边界

更新记录:

版本	日期	更新内容	作者
v1.0	2026-02-10	初始版本，汇总各领域实现状态与差异	-

36 KiB Raw Blame History Unescape Escape