#
 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 核心聚合根设计

```java
// 聚合根: 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 巡检管理实现

```java
// 聚合根: 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 访客管理实现

```java
// 聚合根: 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 核心聚合根设计

```java
// 聚合根: 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 消息通知系统

```java
// 聚合根: 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 工单与通知集成

```java
// 工单事件监听器
@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 核心聚合根设计

```java
// 聚合根: 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 设备与工单联动

```java
// 设备故障自动创建工单
@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 核心聚合根设计

```java
// 聚合根: 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 费用催缴通知

```java
// 定时任务: 费用催缴
@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 核心聚合根设计

```java
// 聚合根: 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 项目隔离实现

```java
// 项目上下文拦截器
@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 访客凭证系统

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

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

#### 2.5.5 改进计划

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

---

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

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

#### 2.6.2 核心聚合根设计

```java
// 聚合根: 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周）

1. **迁移 Maintenance 相关实体**
   - 将 EquipmentMaintenance 从 ether-mdm 迁移到 ether-asset
   - 更新外键关联和查询逻辑

2. **清理财务重复实体**
   - 删除 ether-mdm 中的 FeeItem、FeeBill、FeePayment
   - 统一使用 ether-finance 的实体

3. **调整巡检和访客归属**
   - 评估是否需要将 Inspection、Visitor 迁移到 ether-ops
   - 或保持现状，在文档中明确领域边界

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

1. **创建设备联动**
   - 实现设备故障自动创建工单
   - 工单完成后更新设备状态

2. **完善财务功能**
   - 实现退款功能
   - 添加财务报表

3. **增强权限系统**
   - 实现数据权限范围控制
   - 添加操作日志

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

1. **创建 ether-hub 服务**
   - 基础框架搭建
   - 数据库表设计

2. **实现停车系统集成**
   - 对接停车系统API
   - 车位状态同步

3. **实现门禁集成**
   - 访客二维码下发
   - 通行记录上报

---

## 六、文档维护

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

**更新记录**:

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