6aspec 2.0.0-dev.2

package/.6aspec/rules/biz/event_subscriber_rule.md

@@ -0,0 +1,529 @@
+# 事件订阅开发规范
+
+## 概述
+
+本规范定义了系统中事件订阅的开发标准，包括包结构、注解使用、命名规范、异常处理等。
+
+---
+
+## 一、事件订阅模式
+
+系统支持两种事件订阅模式，推荐使用**框架 EventSubscriber 模式**。
+
+### 1.1 框架 EventSubscriber 模式（推荐）
+
+**适用场景**：所有事件订阅场景
+
+**包路径规范**：
+```
+**.event.subscriber
+**.event.subscriber.{业务分类}    # 可选：按业务领域分类
+```
+
+**开发规范**：
+- **继承**：`extends EventSubscriber<TEvent, TResult>`
+  - `TEvent`：事件类型（如 `ContractSignedEvent`）
+  - `TResult`：返回结果类型，通常为 `Void`
+- **类注解**：
+  - `@Subscriber(name = "订阅名称")` - 必需，定义订阅器名称
+  - `@Slf4j` - 必需，用于日志记录
+- **必须实现的方法**：
+  - `subscribe(TEvent message)` - 订阅处理逻辑
+  - `getMessageType()` - 返回消息类型引用
+
+**参考示例**：
+
+```java
+package com.mysoft.rental.caretaker.event.subscriber;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.mysoft.framework.common.exception.BusinessLogicException;
+import com.mysoft.framework.common.util.JsonUtil;
+import com.mysoft.framework.event.annotation.Subscriber;
+import com.mysoft.framework.event.api.EventSubscriber;
+import com.mysoft.framework.event.enums.EventResultEnum;
+import com.mysoft.framework.event.info.EventArgument;
+import com.mysoft.framework.event.info.Result;
+import com.mysoft.rental.caretaker.service.checkin.CheckInService;
+import com.mysoft.rental.contract.model.event.contract.ContractSignedEvent;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+
+/**
+ * 合同已签订事件订阅器 - 自动创建入住单
+ *
+ * @author yanghui
+ * @description 监听合同签订事件，自动创建入住单
+ * @date 2025/3/7 16:35
+ */
+@Subscriber(name = "入住单创建-合同已签订订阅")
+@Slf4j
+public class ContractSignedEventSubscriber extends EventSubscriber<ContractSignedEvent, Void> {
+
+    @Autowired
+    private CheckInService checkInService;
+    
+    @Override
+    public Result<Void> subscribe(ContractSignedEvent message) {
+        log.info("入住单创建-收到合同已签订事件：{}", JsonUtil.toString(message));
+        try {
+            this.checkInService.autoCreatePersonalCheckIn(message.getBusinessIds().get(0));
+        } catch (BusinessLogicException e) {
+            log.warn("入住单创建-收到合同已签订事件,处理入住单发生业务异常：{}", e.getMessage());
+        } catch (Exception e) {
+            log.error("入住单创建-收到合同已签订事件,处理入住单发生异常", e);
+        }
+        return new Result<>(EventResultEnum.SUCCESS);
+    }
+
+    @Override
+    public TypeReference<EventArgument<ContractSignedEvent, Void>> getMessageType() {
+        return new TypeReference<EventArgument<ContractSignedEvent, Void>>() {};
+    }
+}
+```
+
+---
+
+## 二、包结构规范
+
+### 2.1 基础包结构
+
+```
+com.mysoft.rental.{module}.event.subscriber
+├── {EventName}Subscriber.java              # 顶层事件订阅器
+├── {业务分类}/                              # 按业务领域分类（可选）
+│   └── {EventName}Subscriber.java
+└── ...
+```
+
+### 2.2 业务分类示例
+
+根据业务复杂度，可以创建子包进行分类：
+
+| 分类包名 | 说明 | 示例 |
+|---------|------|------|
+| `device` | 设备相关事件订阅 | `DeviceMeterReadingChargeGeneratedEventSubscriber` |
+| `changeroom` | 换房相关事件订阅 | `ChangeRoomContractAlternationSignedEventSubscriber` |
+| `roomstatus` | 房态相关事件订阅 | `RoomStatusResourceNameChangeSubscriber` |
+| `roomstatusview` | 房态视图相关事件订阅 | - |
+| `smartdevice` | 智能设备相关事件订阅 | `FormalDeviceEleMeterOnOffSubscriber` |
+
+**建议**：
+- 订阅器数量少于 5 个：直接放在 `subscriber` 包下
+- 订阅器数量多于 5 个：按业务领域创建子包分类
+
+---
+
+## 三、命名规范
+
+### 3.1 类命名规范
+
+**格式**：`{事件名称}{Subscriber/EventSubscriber}`
+
+| 场景 | 命名格式 | 示例 |
+|------|---------|------|
+| 通用事件订阅 | `{EventName}Subscriber` | `ContractSignedEventSubscriber` |
+| 特定业务场景 | `{EventName}For{Purpose}Subscriber` | `CheckInHandledEventForResidentPasswordSubscriber` |
+
+**命名建议**：
+- 使用清晰、语义化的名称
+- 体现订阅的事件类型和处理目的
+- 以 `Subscriber` 或 `EventSubscriber` 结尾
+
+### 3.2 订阅器名称（@Subscriber name）
+
+**格式**：`{业务场景}-{事件描述}`
+
+| 场景 | 示例 |
+|------|------|
+| 创建业务单据 | `入住单创建-合同已签订订阅` |
+| 完成业务操作 | `入住完成-自动创建住户密码` |
+| 处理业务事件 | `退房办理-费用结清事件` |
+
+**命名规则**：
+- 前半部分：描述业务场景或目标
+- 后半部分：描述触发的事件
+- 使用中文，便于理解和维护
+
+---
+
+## 四、开发规范详解
+
+### 4.1 类结构
+
+```java
+@Subscriber(name = "订阅器名称")
+@Slf4j
+public class XxxEventSubscriber extends EventSubscriber<EventType, ResultType> {
+    
+    // 1. 依赖注入
+    @Autowired
+    private XxxService xxxService;
+    
+    // 2. 订阅处理方法（必需）
+    @Override
+    public Result<ResultType> subscribe(EventType message) {
+        // 订阅处理逻辑
+    }
+    
+    // 3. 消息类型方法（必需）
+    @Override
+    public TypeReference<EventArgument<EventType, ResultType>> getMessageType() {
+        return new TypeReference<EventArgument<EventType, ResultType>>() {};
+    }
+}
+```
+
+### 4.2 subscribe 方法规范
+
+#### 必需元素：
+1. **日志记录**：记录接收到的事件信息
+2. **异常处理**：捕获业务异常和系统异常
+3. **返回结果**：返回 `Result<T>` 对象
+
+#### 标准模板：
+
+```java
+@Override
+public Result<Void> subscribe(XxxEvent message) {
+    log.info("收到XXX事件：{}", JsonUtil.toString(message));
+    try {
+        // 业务处理逻辑
+        xxxService.handleEvent(message.getBusinessIds());
+    } catch (BusinessLogicException e) {
+        log.warn("处理XXX事件-业务异常：{}", e.getMessage());
+        // 或 log.error("处理XXX事件-业务异常", e);
+    } catch (Exception e) {
+        log.error("处理XXX事件-系统异常", e);
+    }
+    return new Result<>(EventResultEnum.SUCCESS);
+}
+```
+
+### 4.3 异常处理规范
+
+#### 两层异常捕获：
+
+**1. BusinessLogicException（业务异常）**
+- 使用 `log.warn()` 记录（或 `log.error()`，视业务重要性）
+- 不影响事件订阅流程继续执行
+- 通常只记录异常消息
+
+```java
+catch (BusinessLogicException e) {
+    log.warn("业务操作失败：{}", e.getMessage());
+}
+```
+
+**2. Exception（系统异常）**
+- 使用 `log.error()` 记录
+- 记录完整异常堆栈信息
+- 确保问题可追溯
+
+```java
+catch (Exception e) {
+    log.error("系统异常", e);
+}
+```
+
+#### 返回值规范：
+
+**始终返回成功**：
+```java
+return new Result<>(EventResultEnum.SUCCESS);
+```
+
+**原因**：
+- 保证事件订阅不会因为某个订阅器失败而阻塞其他订阅器
+- 异常已通过日志记录，便于排查
+- 失败重试由框架或业务层面处理
+
+---
+
+## 五、高级特性（可选）
+
+### 5.1 分布式锁
+
+**适用场景**：防止并发事件重复处理
+
+**实现方式**：
+
+```java
+@Subscriber(name = "退房单创建-合同终止已签订订阅")
+@Slf4j
+public class TerminationSignedEventSubscriber extends EventSubscriber<TerminationSignedEvent, Void> {
+
+    @Autowired
+    private CheckOutService checkOutService;
+    
+    @Autowired
+    private BaseDistributedLockFactory baseDistributedLockFactory;
+
+    @Override
+    public Result<Void> subscribe(TerminationSignedEvent message) {
+        log.info("退房单创建-收到合同终止已签订事件：{}", JsonUtil.toString(message));
+        UUID contractTerminationId = message.getBusinessIds().get(0);
+        
+        // 构建分布式锁
+        BaseDistributedLock distributedLock = baseDistributedLockFactory
+            .build("checkout_contract-terminationSigned:" + contractTerminationId);
+        
+        try {
+            // 尝试获取锁
+            if (distributedLock.tryLock(3, TimeUnit.SECONDS)) {
+                this.checkOutService.autoCreateCheckOut(contractTerminationId);
+            }
+        } catch (BusinessLogicException e) {
+            log.warn("退房单创建-业务异常：{}", e.getMessage());
+        } catch (Exception e) {
+            log.error("退房单创建-系统异常", e);
+        } finally {
+            // 释放锁
+            if (distributedLock.isLocked() && distributedLock.isHeldByCurrentThread()) {
+                distributedLock.unlock();
+            }
+        }
+        return new Result<>(EventResultEnum.SUCCESS);
+    }
+
+    @Override
+    public TypeReference<EventArgument<TerminationSignedEvent, Void>> getMessageType() {
+        return new TypeReference<EventArgument<TerminationSignedEvent, Void>>() {};
+    }
+}
+```
+
+**关键要点**：
+- **锁命名**：使用业务语义化的锁名称，包含业务ID
+- **超时时间**：根据业务处理时长设置合理的超时时间
+- **finally 释放**：确保在 finally 块中释放锁
+- **判断持有**：释放前判断是否持有锁
+
+### 5.2 批量处理
+
+**适用场景**：事件携带多个业务ID
+
+```java
+@Override
+public Result<Void> subscribe(XxxEvent message) {
+    log.info("收到XXX事件：{}", JsonUtil.toString(message));
+    try {
+        // 批量处理
+        List<UUID> businessIds = message.getBusinessIds();
+        for (UUID businessId : businessIds) {
+            try {
+                xxxService.handle(businessId);
+            } catch (BusinessLogicException e) {
+                log.warn("处理业务ID[{}]失败：{}", businessId, e.getMessage());
+                // 继续处理下一个，不中断整个批次
+            }
+        }
+    } catch (Exception e) {
+        log.error("批量处理异常", e);
+    }
+    return new Result<>(EventResultEnum.SUCCESS);
+}
+```
+
+---
+
+## 六、日志规范
+
+### 6.1 日志级别
+
+| 场景 | 日志级别 | 格式示例 |
+|------|---------|---------|
+| 接收事件 | INFO | `收到合同已签订事件：{}` |
+| 业务成功 | INFO | `入住单创建成功，入住单ID：{}` |
+| 业务警告 | WARN | `处理XXX事件-业务异常：{}` |
+| 业务异常 | ERROR | `处理XXX事件-业务异常`, e |
+| 系统异常 | ERROR | `处理XXX事件-系统异常`, e |
+
+### 6.2 日志内容规范
+
+**必需信息**：
+- 事件描述
+- 业务数据（使用 `JsonUtil.toString()` 序列化）
+- 异常信息或堆栈
+
+**示例**：
+```java
+// 接收事件
+log.info("收到合同已签订事件：{}", JsonUtil.toString(message));
+
+// 业务异常（方式一：只记录消息）
+log.warn("入住单创建-收到合同已签订事件,处理入住单发生业务异常：{}", e.getMessage());
+
+// 业务异常（方式二：记录堆栈）
+log.error("入住单创建-收到合同已签订事件,处理入住单发生业务异常", e);
+
+// 系统异常
+log.error("入住单创建-收到合同已签订事件,处理入住单发生系统异常", e);
+```
+
+---
+
+## 七、检查清单
+
+在提交代码前，请确认：
+
+- [ ] 类名符合命名规范（以 Subscriber 结尾）
+- [ ] 包路径正确（`**.event.subscriber`）
+- [ ] 添加了 `@Subscriber` 和 `@Slf4j` 注解
+- [ ] 继承了 `EventSubscriber<TEvent, TResult>`
+- [ ] 实现了 `subscribe()` 和 `getMessageType()` 方法
+- [ ] 添加了完整的异常处理（BusinessLogicException + Exception）
+- [ ] 添加了日志记录（接收事件 + 异常处理）
+- [ ] 返回 `new Result<>(EventResultEnum.SUCCESS)`
+- [ ] 添加了 JavaDoc 注释（类和方法）
+- [ ] 如需并发控制，使用了分布式锁并正确释放
+
+---
+
+## 八、常见问题
+
+### Q1: 什么时候使用 EventSubscriber 模式，什么时候使用 Spring 事件监听模式？
+- **EventSubscriber 模式**（推荐）：
+  - 跨系统/跨模块的异步事件
+  - 需要解耦的业务场景
+  - 需要事件持久化和重试机制
+  
+- **Spring 事件监听模式**：
+  - 同一应用内的简单同步事件
+  - 不需要持久化的临时事件
+
+### Q2: 为什么即使处理失败也要返回 SUCCESS？
+- 保证其他订阅器不受影响
+- 避免事件消费失败导致的重复消费
+- 失败已通过日志记录，可人工介入处理
+- 如需重试，应在业务层面实现补偿机制
+
+### Q3: 如何处理事件的幂等性？
+- **方式一**：业务层面实现幂等（推荐）
+  - 在 Service 层判断业务是否已处理
+  - 使用唯一索引防止重复数据
+  
+- **方式二**：使用分布式锁
+  - 适用于创建类操作
+  - 锁的粒度要合理
+
+### Q4: 订阅器数量很多时如何组织？
+- 少于 5 个：直接放在 `subscriber` 包下
+- 多于 5 个：按业务领域创建子包
+  - 设备相关 → `device/`
+  - 换房相关 → `changeroom/`
+  - 房态相关 → `roomstatus/`
+
+### Q5: 如何测试事件订阅器？
+```java
+@SpringBootTest
+public class ContractSignedEventSubscriberTest {
+    
+    @Autowired
+    private ContractSignedEventSubscriber subscriber;
+    
+    @Test
+    public void testSubscribe() {
+        // 构造事件
+        ContractSignedEvent event = new ContractSignedEvent();
+        event.setBusinessIds(Collections.singletonList(contractId));
+        
+        // 调用订阅方法
+        Result<Void> result = subscriber.subscribe(event);
+        
+        // 验证结果
+        assertEquals(EventResultEnum.SUCCESS, result.getResultCode());
+    }
+}
+```
+
+---
+
+## 九、最佳实践
+
+### 9.1 单一职责
+
+每个订阅器只处理一个明确的业务场景：
+
+✅ **推荐**：
+```java
+@Subscriber(name = "入住单创建-合同已签订订阅")
+public class ContractSignedEventSubscriber {
+    // 只负责创建入住单
+}
+
+@Subscriber(name = "账单生成-合同已签订订阅")
+public class ContractSignedForBillingEventSubscriber {
+    // 只负责生成账单
+}
+```
+
+❌ **不推荐**：
+```java
+@Subscriber(name = "合同已签订处理")
+public class ContractSignedEventSubscriber {
+    // 处理创建入住单、生成账单、发送通知等多个职责
+}
+```
+
+### 9.2 避免长事务
+
+事件订阅器应该快速处理，避免长时间阻塞：
+
+✅ **推荐**：
+```java
+@Override
+public Result<Void> subscribe(XxxEvent message) {
+    // 快速处理，复杂逻辑交给 Service 异步处理
+    xxxService.asyncHandle(message.getBusinessIds());
+    return new Result<>(EventResultEnum.SUCCESS);
+}
+```
+
+❌ **不推荐**：
+```java
+@Override
+public Result<Void> subscribe(XxxEvent message) {
+    // 在订阅器中执行大量复杂计算或外部调用
+    for (int i = 0; i < 10000; i++) {
+        // 复杂处理...
+    }
+    return new Result<>(EventResultEnum.SUCCESS);
+}
+```
+
+### 9.3 合理使用日志
+
+记录关键信息，避免过度日志：
+
+✅ **推荐**：
+```java
+log.info("收到合同已签订事件，合同ID：{}", message.getBusinessIds());
+log.error("处理入住单创建失败", e);
+```
+
+❌ **不推荐**：
+```java
+log.info("开始处理事件");
+log.info("事件内容：{}", message);
+log.info("获取业务ID");
+log.info("调用服务");
+log.info("处理完成");
+// 过多的 INFO 日志会淹没关键信息
+```
+
+---
+
+## 十、相关文档
+
+- 事件发布规范
+- 领域事件设计指南
+- 分布式锁使用指南
+
+---
+
+**文档版本**：v1.0  
+**最后更新**：2026-01-11  
+**维护人**：开发团队
+

package/.6aspec/rules/biz/project-structure.md

@@ -0,0 +1,90 @@
+---
+alwaysApply: false
+---
+# 项目结构与代码规范
+
+本项目采用多模块分层架构，目录结构及代码规范如下：
+
+## 目录结构
+- 每个业务领域（如合同、客户、租控等）为一个独立模块，模块下分为：
+  - `-service`：服务实现层
+  - `-interfaces`：接口层
+  - `-model`：数据模型层
+- 公共模块如 `rental-common`、`rental-utility` 存放通用工具、基础设施、公共接口和模型。
+
+
+## 命名规范
+- 类/接口名：大驼峰，接口以 `Facade`、`Service`、`Controller` 结尾
+- 方法名：小驼峰，动词+业务含义
+- 常量名：全大写+下划线
+- 枚举名：以 `Enum` 结尾，枚举值全大写
+
+## 注释规范
+- 类、方法、枚举等均有 Javadoc 注释，说明用途、参数、返回值、作者、日期
+- 重要业务逻辑、异常、特殊处理有详细注释
+
+## 接口与实现
+- 接口定义在 `interfaces` 层，通常以 `Facade` 结尾
+- 实现类在 `service` 层，以 `Impl` 结尾，`@Service` 注解
+- 参数、返回值多用 DTO
+
+
+## 设计模式
+- 常用：Facade、Strategy、Template、Enum、注解驱动
+- 业务异常采用统一枚举管理
+
+## 分层规范
+- 必须遵循三层架构规范来写代码
+```
+入口->service层->Repository
+              -> gateway
+```
+- 入口包括controller，定时任务，事件订阅，后台任务
+- service层：处理核心业务逻辑
+- Repository层：数据访问层，数据操作
+- gateway层：封装夸模块，以及跨系统调用
+
+## 上下文用户获取
+- B端用户使用：ContextManager
+```java
+    @Autowired
+    private ContextManager contextManager;
+    
+    contextManager.fetchContextInfo()
+```
+- C端用户使用：类`com.rental.assetrental.component.customerauth.context.IdentityUserInfoThreadContextHolder`
+```java
+IdentityUserInfoThreadContextHolder.get().getTocUserId();
+```
+
+
+## Service 层代码规范
+
+- Service 不需要接口，直接以Service或者ApplicationService结尾，需要继承AppService类；如果是Facade接口，则接口放在interfaces层，实现写在service层，并以Impl结尾
+- 实现类加 `@Service` 注解，扩展点用自定义注解（如 `@Extension`），需要事务支持加 `@Transactional`。
+- 依赖注入用 `@Autowired`。
+- 方法参数、返回值优先用 DTO/Command/Query/VO，避免直接用实体或原始类型。
+- 只处理业务逻辑，不做参数校验，数据操作通过 Repository/DAO。
+- 业务异常抛出自定义异常并配合统一异常码，异常需记录日志并保证事务回滚。
+- 类、方法需有 Javadoc 注释，重要逻辑有详细注释。
+- 方法名小驼峰，动词+业务含义，代码整洁，常量提取。
+- 常用设计模式：模板方法、策略、工厂、单例/枚举，扩展点用接口+注解+工厂注册。
+- Service 层不直接暴露远程服务，需通过接口层（facade）暴露，业务锁、幂等、分布式事务有统一机制。
+
+## Repository 层代码规范
+
+- Repository 类名以 `Repository` 结尾，放在 `repository` 包下，继承 `BaseRepository`，DAO 以 `Dao` 结尾，实体以 `Entity` 结尾。
+- 类上加 `@Repository` 注解，依赖注入用 `@Autowired`。
+- 方法参数优先用实体、DTO、ID、集合，方法名以 `get`、`find`、`query`、`insert`、`update`、`delete`、`save` 开头。
+- 只负责数据持久化，不包含业务逻辑，复杂查询/批量/分页用 Wrapper、Page 等实现。
+- 实体与 DTO/VO 转换用工具类，数据操作异常需抛出自定义异常或统一异常。
+- 需要事务支持的方法加 `@Transactional`，不捕获并吞掉异常。
+- 类、方法需有 Javadoc 注释，重要操作有详细注释。
+- 方法名小驼峰，动词+业务含义，代码整洁，常量提取。
+- 仅做数据访问，不包含业务逻辑，命名规范统一，支持多数据源扩展。
+
+
+## 其他
+- 统一使用 Lombok
+- 统一异常码、常量、业务单元编码有详细分段和注释
+- 代码风格整洁，缩进、空行、注释规范