6aspec 2.0.0-dev.10

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

@@ -0,0 +1,719 @@
+# 后台任务开发规范
+
+## 概述
+
+本规范定义了系统中后台任务（BackgroundJob）的开发标准，包括包结构、注解使用、命名规范、批量处理等。
+
+后台任务与定时任务的区别：
+- **定时任务**：按时间周期自动执行（如每天凌晨执行）
+- **后台任务**：由业务触发异步执行（如批量操作、耗时操作）
+
+---
+
+## 一、后台任务开发规范
+
+### 1.1 包路径规范
+
+```
+**.job.backgroundjob
+```
+
+**示例**：
+```
+com.mysoft.rental.caretaker.job.backgroundjob
+com.mysoft.rental.charging.job.backgroundjob
+```
+
+### 1.2 类命名规范
+
+**格式**：`{业务描述}BackgroundJob`
+
+| 场景 | 命名格式 | 示例 |
+|------|---------|------|
+| 批量绑定 | `{Entity}BatchBindBackgroundJob` | `DeviceMeterBatchAutoBindBackgroundJob` |
+| 批量解绑 | `{Entity}BatchUnBindBackgroundJob` | `DeviceMeterBatchAutoUnBindBackgroundJob` |
+| 批量更新 | `{Entity}BatchUpdateBackgroundJob` | `MeterDeviceBindUpdatePayerAndPayeeBackgroundJob` |
+| 批量作废 | `{Entity}BatchInvalidateBackgroundJob` | `DeviceMeterRoomChargeInvalidateBackgroundJob` |
+| 批量处理 | `{Entity}BatchProcessBackgroundJob` | `DataBatchProcessBackgroundJob` |
+| 数据同步 | `{Entity}SyncBackgroundJob` | `OrderDataSyncBackgroundJob` |
+
+**命名规则**：
+- 使用清晰、语义化的名称
+- 体现任务的业务目的
+- 统一以 `BackgroundJob` 结尾
+
+---
+
+## 二、基础开发规范
+
+### 2.1 类结构
+
+```java
+package com.mysoft.rental.{module}.job.backgroundjob;
+
+import com.mysoft.framework.backgroudbjob.BackgroundJob;
+import com.mysoft.framework.backgroudbjob.annotation.JobName;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+
+/**
+ * {任务描述}后台任务
+ *
+ * @author {作者}
+ * @description {详细描述任务的作用}
+ * @date {创建日期}
+ */
+@Slf4j
+@JobName(name = "任务名称", jobGroup = "任务分组")
+public class XxxBackgroundJob implements BackgroundJob<MessageType> {
+    
+    @Autowired
+    private XxxService xxxService;
+    
+    @Override
+    public void execute(MessageType message) throws Exception {
+        log.info("收到XXX任务消息：{}", JsonUtil.toString(message));
+        
+        try {
+            // 业务处理逻辑
+            xxxService.process(message);
+            
+            log.info("XXX任务执行完成");
+        } catch (Exception e) {
+            log.error("XXX任务执行失败", e);
+            throw e;  // 抛出异常，框架会记录失败状态
+        }
+    }
+}
+```
+
+### 2.2 关键要点
+
+#### 2.2.1 类注解（必需）
+
+**@Slf4j**
+- 用于日志记录
+- 必须添加
+
+**@JobName**
+- 定义任务名称和分组
+- 参数说明：
+  - `name`：任务名称（中文），用于识别和展示
+  - `jobGroup`：任务分组，用于任务分类管理
+
+```java
+@Slf4j
+@JobName(name = "房源关联水表批量解绑", jobGroup = "device")
+public class DeviceMeterBatchAutoUnBindBackgroundJob implements BackgroundJob<BatchOperateMessageDTO> {
+    // ...
+}
+```
+
+**常用任务分组（jobGroup）**：
+
+| 分组名 | 说明 | 示例场景 |
+|--------|------|---------|
+| `device` | 设备相关 | 设备绑定、解绑、同步 |
+| `caretaker` | 管家相关 | 入住、退房、换房 |
+| `charging` | 计费相关 | 账单生成、费用作废 |
+| `contract` | 合同相关 | 合同签订、变更 |
+| `data` | 数据处理 | 数据同步、数据清理 |
+| `notification` | 通知相关 | 消息推送、邮件发送 |
+
+#### 2.2.2 实现接口
+
+**BackgroundJob<T>**
+- `T` 为消息类型（DTO）
+- 必须实现 `execute(T message)` 方法
+
+```java
+public class XxxBackgroundJob implements BackgroundJob<XxxDTO> {
+    @Override
+    public void execute(XxxDTO message) throws Exception {
+        // 处理逻辑
+    }
+}
+```
+
+**常用消息类型**：
+
+| 消息类型 | 说明 | 使用场景 |
+|---------|------|---------|
+| `BatchOperateMessageDTO` | 批量操作消息 | 批量绑定、解绑、更新等 |
+| 自定义 DTO | 业务特定消息 | 单个业务处理 |
+
+#### 2.2.3 execute 方法规范
+
+**方法签名**：
+```java
+@Override
+public void execute(MessageType message) throws Exception
+```
+
+**关键点**：
+- `public` 访问修饰符
+- `void` 返回类型
+- `throws Exception` - 允许抛出异常
+- 异常处理：
+  - 捕获并记录日志
+  - **可以抛出异常**，框架会处理失败状态
+  - 与定时任务不同，后台任务可以抛出异常
+
+#### 2.2.4 日志规范
+
+**必需日志**：
+```java
+// 任务开始
+log.info("收到XXX任务消息：{}", JsonUtil.toString(message));
+
+// 任务完成
+log.info("XXX任务执行完成");
+
+// 任务失败
+log.error("XXX任务执行失败", e);
+```
+
+**建议日志**：
+- 记录关键步骤
+- 记录处理数量和结果
+
+---
+
+## 三、批量操作任务规范
+
+### 3.1 使用场景
+
+批量操作任务通常用于：
+- 批量绑定/解绑
+- 批量更新
+- 批量作废
+- 批量导入/导出
+
+### 3.2 标准结构
+
+```java
+@Slf4j
+@JobName(name = "房源关联水表批量解绑", jobGroup = "device")
+public class DeviceMeterBatchAutoUnBindBackgroundJob implements BackgroundJob<BatchOperateMessageDTO> {
+
+    @Autowired
+    private BatchOperateFacade batchOperateFacade;
+    
+    @Autowired
+    private UsageDeviceService usageDeviceService;
+
+    @Override
+    public void execute(BatchOperateMessageDTO batchOperateMessage) throws Exception {
+        log.info("房源关联水表批量解绑，{}", JsonUtil.toString(batchOperateMessage));
+        
+        // 1. 获取批量操作数据
+        List<BatchOperateBusinessDTO> businesses = batchOperateFacade.getData(batchOperateMessage.getDataId());
+        TaskDTO taskDTO = batchOperateFacade.queryTask(batchOperateMessage.getTaskId());
+        
+        // 2. 分组处理（大批量数据时）
+        List<List<UUID>> groups = buildGroups(businesses);
+        List<TaskItemDTO> taskItemList = new ArrayList<>();
+        
+        // 3. 处理每个组
+        groups.forEach(group -> {
+            if (CollectionUtils.isEmpty(group)) {
+                return;
+            }
+            List<TaskItemDTO> currentTaskItemList = new ArrayList<>();
+            try {
+                // 执行业务逻辑
+                currentTaskItemList = usageDeviceService.batchUnBindUsageDeviceForBackGround(
+                    group, 
+                    batchOperateMessage.getTaskId(), 
+                    taskDTO.getBusinessExtendedField()
+                );
+            } catch (Exception exception) {
+                log.error("房源关联水表批量解绑失败：", exception);
+                // 构建失败任务项
+                currentTaskItemList = group.stream()
+                    .map(x -> new TaskItemDTO(batchOperateMessage.getTaskId(), x.toString(), Constant.SYSTEM_ERROR))
+                    .collect(Collectors.toList());
+            } finally {
+                // 更新任务状态
+                taskItemList.addAll(currentTaskItemList);
+                batchOperateFacade.updateTaskAndResetTaskItems(taskItemList, false);
+            }
+        });
+        
+        // 4. 最终更新任务状态
+        batchOperateFacade.updateTaskAndResetTaskItems(taskItemList, true);
+    }
+    
+    /**
+     * 分组处理逻辑
+     */
+    public static List<List<UUID>> buildGroups(List<BatchOperateBusinessDTO> businesses) {
+        if (CollectionUtils.isEmpty(businesses)) {
+            return Collections.emptyList();
+        }
+        
+        List<UUID> businessIds = businesses.stream()
+            .map(x -> UUID.fromString(x.getId()))
+            .collect(Collectors.toList());
+
+        final int maxGroups = 10;  // 最多分10组
+        List<List<UUID>> groups = new ArrayList<>(maxGroups);
+        int size = businessIds.size();
+
+        // 初始化所有需要的组
+        int actualGroups = calculateActualGroups(size, maxGroups);
+        for (int i = 0; i < actualGroups; i++) {
+            groups.add(new ArrayList<>());
+        }
+
+        // 分配元素到各组
+        if (size <= maxGroups * 10) {
+            // ≤100 时的分配方式（每10个一组）
+            for (int i = 0; i < size; i++) {
+                int groupIndex = i / 10;
+                groups.get(groupIndex).add(businessIds.get(i));
+            }
+        } else {
+            // >100 时的均匀分配
+            int elementsPerGroup = size / maxGroups;
+            int remainder = size % maxGroups;
+
+            int currentIndex = 0;
+            for (int i = 0; i < maxGroups; i++) {
+                int groupSize = elementsPerGroup + (i < remainder ? 1 : 0);
+                List<UUID> group = businessIds.subList(currentIndex, currentIndex + groupSize);
+                groups.set(i, new ArrayList<>(group));
+                currentIndex += groupSize;
+            }
+        }
+
+        return groups;
+    }
+
+    public static int calculateActualGroups(int size, int maxGroups) {
+        if (size <= maxGroups * 10) {
+            return Math.max(1, (size + 9) / 10); // 向上取整计算需要的组数
+        }
+        return maxGroups;
+    }
+}
+```
+
+### 3.3 分组策略
+
+**为什么要分组？**
+- 避免一次处理过多数据导致超时
+- 提高任务的容错性（部分失败不影响整体）
+- 便于任务进度跟踪
+
+**分组规则**（推荐）：
+- 数据量 ≤ 100：每 10 个一组
+- 数据量 > 100：均匀分配到 10 组
+- 最多分 10 组
+
+**分组处理模式**：
+```java
+// 1. 分组
+List<List<UUID>> groups = buildGroups(businesses);
+
+// 2. 逐组处理
+groups.forEach(group -> {
+    try {
+        // 处理当前组
+        processGroup(group);
+    } catch (Exception e) {
+        // 记录失败，继续处理下一组
+        log.error("处理分组失败", e);
+    }
+});
+```
+
+### 3.4 任务状态更新
+
+**使用 BatchOperateFacade**：
+
+```java
+// 获取数据
+List<BatchOperateBusinessDTO> businesses = batchOperateFacade.getData(dataId);
+
+// 查询任务
+TaskDTO taskDTO = batchOperateFacade.queryTask(taskId);
+
+// 更新任务项（中间更新）
+batchOperateFacade.updateTaskAndResetTaskItems(taskItemList, false);
+
+// 最终更新（完成）
+batchOperateFacade.updateTaskAndResetTaskItems(taskItemList, true);
+
+// 删除数据
+batchOperateFacade.deleteData(dataId);
+
+// 更新任务状态
+batchOperateFacade.updateTask(taskId, errorMessage, businesses, isSuccess);
+```
+
+---
+
+## 四、简单任务规范
+
+### 4.1 使用场景
+
+简单任务通常用于：
+- 单个业务处理
+- 数据同步
+- 消息通知
+- 数据更新
+
+### 4.2 标准结构
+
+```java
+@Slf4j
+@JobName(name = "用量类设备绑定同步收付款方", jobGroup = "caretaker")
+public class MeterDeviceBindUpdatePayerAndPayeeBackgroundJob implements BackgroundJob<MeterDeviceBindDTO> {
+    
+    @Autowired
+    private UsageDeviceService usageDeviceService;
+
+    @Override
+    public void execute(MeterDeviceBindDTO meterDeviceBind) throws Exception {
+        log.info("收到用量类设备绑定：{}", JsonUtil.toString(meterDeviceBind));
+        
+        try {
+            usageDeviceService.meterDeviceBindUpdatePayerAndPayee(meterDeviceBind);
+            log.info("用量类设备绑定同步收付款方完成");
+        } catch (Exception e) {
+            log.error("用量类设备绑定同步收付款方失败", e);
+            throw e;
+        }
+    }
+}
+```
+
+### 4.3 关键点
+
+- 消息类型为自定义 DTO
+- 处理逻辑简单直接
+- 异常可以直接抛出
+- 日志记录开始和结束
+
+---
+
+## 五、异常处理规范
+
+### 5.1 批量操作任务的异常处理
+
+**原则**：部分失败不影响整体
+
+```java
+groups.forEach(group -> {
+    List<TaskItemDTO> currentTaskItemList = new ArrayList<>();
+    try {
+        // 执行业务逻辑
+        currentTaskItemList = service.batchProcess(group);
+    } catch (Exception exception) {
+        log.error("批量处理失败：", exception);
+        // 构建失败任务项
+        currentTaskItemList = group.stream()
+            .map(x -> new TaskItemDTO(taskId, x.toString(), Constant.SYSTEM_ERROR))
+            .collect(Collectors.toList());
+    } finally {
+        // 更新任务状态
+        taskItemList.addAll(currentTaskItemList);
+        batchOperateFacade.updateTaskAndResetTaskItems(taskItemList, false);
+    }
+});
+```
+
+**关键点**：
+- 每个分组独立处理
+- 异常时构建失败任务项
+- `finally` 块中更新状态
+- 继续处理下一组
+
+### 5.2 简单任务的异常处理
+
+**原则**：抛出异常，由框架处理
+
+```java
+@Override
+public void execute(MessageType message) throws Exception {
+    log.info("收到任务消息：{}", JsonUtil.toString(message));
+    
+    try {
+        service.process(message);
+        log.info("任务执行完成");
+    } catch (Exception e) {
+        log.error("任务执行失败", e);
+        throw e;  // 抛出异常，框架会标记任务失败
+    }
+}
+```
+
+**关键点**：
+- 记录详细的错误日志
+- 抛出异常给框架处理
+- 框架会自动标记任务失败
+
+---
+
+## 六、最佳实践
+
+### 6.1 任务幂等性
+
+**问题**：任务可能重复执行
+
+**解决方案**：
+
+**方式一：业务层面幂等**
+```java
+@Override
+public void execute(MessageType message) throws Exception {
+    // 检查是否已处理
+    if (service.isProcessed(message.getId())) {
+        log.info("任务已处理，跳过：{}", message.getId());
+        return;
+    }
+    
+    // 执行业务逻辑
+    service.process(message);
+    
+    // 标记已处理
+    service.markProcessed(message.getId());
+}
+```
+
+**方式二：使用事务和唯一索引**
+```java
+@Transactional
+public void process(MessageType message) {
+    // 业务逻辑
+    // 数据库唯一索引保证幂等性
+}
+```
+
+### 6.2 大数据量处理
+
+**问题**：数据量过大导致内存溢出或超时
+
+**解决方案：分组 + 分页**
+
+```java
+@Override
+public void execute(BatchOperateMessageDTO message) throws Exception {
+    // 1. 分组处理
+    List<List<UUID>> groups = buildGroups(businesses);
+    
+    // 2. 每组内再分页
+    groups.forEach(group -> {
+        int pageSize = 10;
+        for (int i = 0; i < group.size(); i += pageSize) {
+            int end = Math.min(i + pageSize, group.size());
+            List<UUID> page = group.subList(i, end);
+            
+            try {
+                service.batchProcess(page);
+            } catch (Exception e) {
+                log.error("处理分页失败", e);
+            }
+        }
+    });
+}
+```
+
+### 6.3 任务监控
+
+**建议**：记录任务执行统计
+
+```java
+@Override
+public void execute(BatchOperateMessageDTO message) throws Exception {
+    long startTime = System.currentTimeMillis();
+    int successCount = 0;
+    int failCount = 0;
+    
+    try {
+        // 业务处理
+        for (Item item : items) {
+            try {
+                service.process(item);
+                successCount++;
+            } catch (Exception e) {
+                failCount++;
+                log.error("处理失败：{}", item.getId(), e);
+            }
+        }
+        
+        long duration = System.currentTimeMillis() - startTime;
+        log.info("任务执行完成，耗时：{}ms，成功：{}，失败：{}", duration, successCount, failCount);
+        
+    } catch (Exception e) {
+        log.error("任务执行异常", e);
+        throw e;
+    }
+}
+```
+
+### 6.4 资源释放
+
+**注意**：及时释放资源
+
+```java
+@Override
+public void execute(MessageType message) throws Exception {
+    Connection conn = null;
+    try {
+        conn = getConnection();
+        // 业务处理
+    } finally {
+        // 释放资源
+        if (conn != null) {
+            conn.close();
+        }
+    }
+}
+```
+
+---
+
+## 七、检查清单
+
+在提交代码前，请确认：
+
+- [ ] 类名符合命名规范（以 BackgroundJob 结尾）
+- [ ] 包路径正确（`**.job.backgroundjob`）
+- [ ] 添加了 `@Slf4j` 和 `@JobName` 注解
+- [ ] 实现了 `BackgroundJob<T>` 接口
+- [ ] 实现了 `execute(T message)` 方法
+- [ ] `@JobName` 的 `name` 和 `jobGroup` 配置正确
+- [ ] 添加了日志记录（开始、完成、异常）
+- [ ] 添加了异常处理
+- [ ] 批量任务使用了分组处理
+- [ ] 考虑了任务幂等性
+- [ ] 添加了 JavaDoc 注释
+
+---
+
+## 八、常见问题
+
+### Q1: 后台任务和定时任务的区别？
+- **定时任务**：
+  - 按时间周期自动执行
+  - 使用 Cron 表达式配置
+  - 需要 XML 配置文件
+  - 不需要外部触发
+  
+- **后台任务**：
+  - 由业务代码触发执行
+  - 异步处理耗时操作
+  - 不需要配置文件
+  - 需要业务调用触发
+
+### Q2: 如何触发后台任务？
+```java
+// 注入后台任务执行器
+@Autowired
+private BackgroundJobExecutor backgroundJobExecutor;
+
+// 触发任务
+MessageType message = new MessageType();
+// 设置消息内容
+backgroundJobExecutor.execute(XxxBackgroundJob.class, message);
+```
+
+### Q3: 后台任务的异常处理和定时任务有什么不同？
+- **定时任务**：不能抛出异常，必须捕获所有异常
+- **后台任务**：可以抛出异常，框架会处理失败状态
+
+### Q4: 为什么批量任务要分组处理？
+- 避免一次处理过多数据导致超时
+- 提高容错性（部分失败不影响整体）
+- 便于进度跟踪和监控
+- 降低内存占用
+
+### Q5: jobGroup 如何选择？
+- 按业务领域分组
+- 便于任务管理和监控
+- 常用分组：`device`、`caretaker`、`charging`、`contract`、`data`、`notification`
+
+### Q6: 后台任务支持重试吗？
+- 框架通常支持任务重试机制
+- 重试次数和策略由框架配置
+- 任务需要保证幂等性
+
+### Q7: 如何查看后台任务的执行状态？
+- 通过管理后台查看任务列表
+- 查看日志文件
+- 使用监控平台（如有）
+
+### Q8: 批量任务的分组数量如何确定？
+- 推荐最多分 10 组
+- 数据量小（≤100）：每 10 个一组
+- 数据量大（>100）：均匀分配到 10 组
+- 根据实际业务调整
+
+---
+
+## 九、任务触发示例
+
+### 9.1 在 Service 中触发
+
+```java
+@Service
+public class DeviceService {
+    
+    @Autowired
+    private BackgroundJobExecutor backgroundJobExecutor;
+    
+    public void batchUnbindDevices(List<UUID> deviceIds, UUID taskId) {
+        // 构建消息
+        BatchOperateMessageDTO message = new BatchOperateMessageDTO();
+        message.setTaskId(taskId);
+        message.setDataId(dataId);
+        
+        // 触发后台任务
+        backgroundJobExecutor.execute(
+            DeviceMeterBatchAutoUnBindBackgroundJob.class, 
+            message
+        );
+    }
+}
+```
+
+### 9.2 在 Controller 中触发
+
+```java
+@PubAction(value = "/batchUnbind", method = RequestMethod.POST)
+public void batchUnbind(@RequestBody List<UUID> deviceIds) {
+    // 创建任务
+    UUID taskId = batchOperateFacade.createTask("批量解绑设备");
+    
+    // 保存数据
+    UUID dataId = batchOperateFacade.saveData(deviceIds);
+    
+    // 构建消息
+    BatchOperateMessageDTO message = new BatchOperateMessageDTO();
+    message.setTaskId(taskId);
+    message.setDataId(dataId);
+    
+    // 触发后台任务
+    backgroundJobExecutor.execute(
+        DeviceMeterBatchAutoUnBindBackgroundJob.class, 
+        message
+    );
+}
+```
+
+---
+
+## 十、相关文档
+
+- 定时任务开发规范
+- 批量操作接口规范
+- 异步任务处理指南
+
+---
+
+**文档版本**：v1.0  
+**最后更新**：2026-01-11  
+**维护人**：开发团队
+