1237 lines
36 KiB
Markdown
1237 lines
36 KiB
Markdown
#
|
||
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 | 初始版本，汇总各领域实现状态与差异 | - |
|