210 lines
9.2 KiB
Markdown
210 lines
9.2 KiB
Markdown
# 需求: 元数据变更自动同步本地数据库
|
||
|
||
## 元数据 (Metadata)
|
||
|
||
- **需求编号**: REQ-006
|
||
- **需求标题**: 元数据变更自动同步本地数据库
|
||
- **需求类型**: 功能需求
|
||
- **优先级**: 高
|
||
- **状态**: Completed
|
||
- **创建日期**: 2026-01-16
|
||
- **最后更新**: 2026-01-16
|
||
- **创建人**: 用户
|
||
- **负责人**: AI Assistant
|
||
|
||
## 输入引用
|
||
|
||
- [DataiIntegrationMetadataChangeController](../../datai-salesforce-integration/src/main/java/com/datai/integration/controller/DataiIntegrationMetadataChangeController.java) - 对象元数据变更控制器
|
||
- [DataiIntegrationMetadataChange](../../datai-salesforce-integration/src/main/java/com/datai/integration/model/domain/DataiIntegrationMetadataChange.java) - 对象元数据变更实体
|
||
- [REQ-005](REQ-005.md) - 定时任务自动同步、插入和更新对象数据
|
||
|
||
## Context Maps
|
||
|
||
- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
|
||
- **相关节点**: DataiIntegrationMetadataChangeController - 对象元数据变更控制器
|
||
- **相关节点**: DataiIntegrationMetadataChangeService - 对象元数据变更服务
|
||
- **相关节点**: DataiIntegrationObject - 对象同步控制实体
|
||
|
||
## 需求目标
|
||
|
||
在 task 目录下创建定时任务，实现元数据变更自动同步到本地数据库的功能。定时任务会扫描所有未同步的元数据变更记录，判断是否满足自动同步条件，并调用相应的同步方法执行同步操作。这样可以减少手动同步的工作量，提高元数据同步的及时性和自动化程度。
|
||
|
||
## 需求描述
|
||
|
||
### 概述
|
||
|
||
创建定时任务类，自动扫描未同步的元数据变更记录，根据元数据变更的类型、操作类型、对象配置等信息判断是否应该自动同步，并调用 DataiIntegrationMetadataChangeController 中的方法执行同步操作。
|
||
|
||
### 详细需求
|
||
|
||
#### 1. 元数据变更自动同步定时任务
|
||
|
||
- **需求描述**: 在 task 目录下创建定时任务类，自动扫描未同步的元数据变更记录，并执行同步操作
|
||
- **优先级**: 高
|
||
- **验收标准**:
|
||
- 能够正确扫描所有未同步的元数据变更记录（syncStatus = false 或 null）
|
||
- 能够根据元数据变更的类型、操作类型、对象配置等信息判断是否应该自动同步
|
||
- 能够调用 DataiIntegrationMetadataChangeService 的方法执行同步操作
|
||
- 能够记录详细的日志信息
|
||
- 能够正确处理同步过程中的异常
|
||
- **依赖关系**: 依赖 DataiIntegrationMetadataChangeService 的实现
|
||
- **实现建议**: 参考 ObjectSyncTask 的实现方式，使用 @Component、@Slf4j、@Autowired 注解
|
||
|
||
#### 2. 元数据变更自动同步条件判断
|
||
|
||
- **需求描述**: 根据元数据变更的类型、操作类型、对象配置等信息判断是否应该自动同步
|
||
- **优先级**: 高
|
||
- **验收标准**:
|
||
- 能够正确判断对象变更是否应该自动同步
|
||
- 能够正确判断字段变更是否应该自动同步
|
||
- 能够根据操作类型（CREATE、UPDATE、DELETE）判断是否应该自动同步
|
||
- 能够根据对象配置（isWork、syncStatus 等）判断是否应该自动同步
|
||
- 能够根据是否自定义对象（isCustom）判断是否应该自动同步
|
||
- **依赖关系**: 依赖 DataiIntegrationObject 和 DataiIntegrationMetadataChange 的字段定义
|
||
- **实现建议**: 创建独立的条件判断方法，提高代码可读性和可维护性
|
||
|
||
#### 3. 元数据变更同步方法调用
|
||
|
||
- **需求描述**: 调用 DataiIntegrationMetadataChangeService 的方法执行同步操作
|
||
- **优先级**: 高
|
||
- **验收标准**:
|
||
- 能够正确调用 syncToLocalDatabase 方法同步单个元数据变更
|
||
- 能够正确调用 syncBatchToLocalDatabase 方法批量同步元数据变更
|
||
- 能够正确处理同步结果
|
||
- 能够更新元数据变更记录的同步状态
|
||
- **依赖关系**: 依赖 DataiIntegrationMetadataChangeService 的实现
|
||
- **实现建议**: 使用 try-catch 处理异常，单个元数据变更同步失败不影响其他元数据变更的同步
|
||
|
||
## 元数据变更自动同步条件判断规则
|
||
|
||
### 自动同步条件
|
||
|
||
元数据变更需要同时满足以下条件才会被自动同步：
|
||
|
||
#### 通用条件
|
||
1. `syncStatus = false` 或 `syncStatus = null`（未同步）
|
||
2. `retryCount < 3`（重试次数小于3次，避免无限重试）
|
||
|
||
#### 对象变更条件（changeType = OBJECT）
|
||
1. 对象配置完整（objectApi、objectLabel 不为空）
|
||
2. 对象启用同步（DataiIntegrationObject.isWork = true）
|
||
3. 对象当前没有正在执行的同步任务（DataiIntegrationObject.syncStatus = false）
|
||
4. 根据操作类型判断：
|
||
- CREATE：总是允许自动同步
|
||
- UPDATE：总是允许自动同步
|
||
- DELETE：总是允许自动同步
|
||
|
||
#### 字段变更条件（changeType = FIELD）
|
||
1. 字段配置完整（objectApi、fieldApi、fieldLabel 不为空）
|
||
2. 对象启用同步（DataiIntegrationObject.isWork = true）
|
||
3. 对象当前没有正在执行的同步任务（DataiIntegrationObject.syncStatus = false）
|
||
4. 根据操作类型判断：
|
||
- CREATE：总是允许自动同步
|
||
- UPDATE：总是允许自动同步
|
||
- DELETE：总是允许自动同步
|
||
|
||
### 不自动同步的条件
|
||
|
||
元数据变更满足以下任一条件时不自动同步：
|
||
|
||
1. `syncStatus = true`（已同步）
|
||
2. `retryCount >= 3`（重试次数大于等于3次，避免无限重试）
|
||
3. 对象未启用同步（DataiIntegrationObject.isWork = false）
|
||
4. 对象当前正在执行同步任务（DataiIntegrationObject.syncStatus = true）
|
||
5. 对象配置不完整（objectApi、objectLabel 为空）
|
||
6. 字段配置不完整（objectApi、fieldApi、fieldLabel 为空）
|
||
|
||
### 同步失败处理
|
||
|
||
如果元数据变更同步失败，需要：
|
||
1. 更新元数据变更记录的 `syncErrorMessage` 字段，记录失败原因
|
||
2. 增加元数据变更记录的 `retryCount` 字段
|
||
3. 更新元数据变更记录的 `lastRetryTime` 字段
|
||
4. 记录详细的错误日志
|
||
|
||
## 约束
|
||
|
||
- **技术栈限制**: 必须使用现有的 Quartz 框架（datai-quartz 模块）
|
||
- **性能要求**: 定时任务执行时间不应过长，建议在业务低峰期执行
|
||
- **安全性要求**: 定时任务方法需要通过 JobInvokeUtil 工具调用，支持通过反射调用 Spring Bean 方法
|
||
- **兼容性要求**: 必须与现有的元数据变更同步功能兼容
|
||
- **时间限制**: 无
|
||
- **其他约束**: 必须参考 RateLimitResetTask 和 ObjectSyncTask 的代码风格
|
||
|
||
## Rule Set
|
||
|
||
"请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。"
|
||
|
||
**具体规则**：
|
||
- 必须使用 Canvas 中定义的类名和方法名
|
||
- 必须遵循 Canvas 中定义的调用关系
|
||
- 必须参考 Canvas 中的流程图逻辑
|
||
- 必须使用 @Component 注解，指定 bean 名称
|
||
- 必须使用 @Slf4j 注解进行日志记录
|
||
- 必须使用 @Autowired 注入 DataiIntegrationMetadataChangeService
|
||
- 必须定义公共方法作为定时任务的执行方法
|
||
- 必须在方法内部有 try-catch 异常处理
|
||
- 必须记录详细的日志信息
|
||
|
||
## 验收标准
|
||
|
||
### 功能完整性
|
||
- 能够正确扫描所有未同步的元数据变更记录
|
||
- 能够根据元数据变更的类型、操作类型、对象配置等信息判断是否应该自动同步
|
||
- 能够调用 DataiIntegrationMetadataChangeService 的方法执行同步操作
|
||
- 能够更新元数据变更记录的同步状态
|
||
- 能够正确处理同步过程中的异常
|
||
|
||
### 性能指标
|
||
- 定时任务执行时间不应超过 10 分钟（假设有 100 条未同步的元数据变更记录）
|
||
- 单个元数据变更同步时间不应超过 30 秒
|
||
|
||
### 安全性要求
|
||
- 定时任务方法需要通过 JobInvokeUtil 工具调用
|
||
- 定时任务执行日志需要记录到 SysJobLog 表
|
||
|
||
### 用户体验
|
||
- 提供详细的日志信息，便于问题排查
|
||
- 单个元数据变更同步失败不影响其他元数据变更的同步
|
||
|
||
### 其他验收标准
|
||
- 代码风格与 RateLimitResetTask 和 ObjectSyncTask 保持一致
|
||
- 代码能够编译通过，无语法错误
|
||
|
||
## 风险
|
||
|
||
### 技术实现风险
|
||
- 定时任务执行时间可能与业务高峰期冲突，影响系统性能
|
||
- 元数据变更同步失败可能导致数据不一致
|
||
- 条件判断逻辑可能存在错误，导致元数据变更被错误地同步或遗漏
|
||
|
||
### 业务风险
|
||
- 定时任务执行时间配置不当，可能影响元数据同步的及时性
|
||
- 元数据变更同步失败，可能影响后续的数据同步操作
|
||
|
||
### 实施风险
|
||
- 开发人员对元数据变更同步逻辑不熟悉，可能需要一定的学习时间
|
||
- 定时任务的 Cron 表达式配置错误，可能导致任务不按预期执行
|
||
|
||
## 需求变更记录
|
||
|
||
| 日期 | 变更内容 | 变更原因 | 变更人 | 审核人 | 状态 |
|
||
|------|---------|---------|--------|--------|------|
|
||
| 2026-01-16 | 创建需求文档 | 用户提出元数据变更自动同步需求 | 用户 | 待审核 | 待审核 |
|
||
|
||
## 相关人员
|
||
|
||
- **需求提出人**: 用户 - 联系方式：待补充
|
||
- **需求负责人**: 待分配 - 联系方式：待补充
|
||
- **技术负责人**: 待分配 - 联系方式：待补充
|
||
- **测试负责人**: 待分配 - 联系方式：待补充
|
||
- **其他相关人员**: 待补充 - 联系方式：待补充
|
||
|
||
## 评审信息
|
||
|
||
- **评审日期**: 待定
|
||
- **评审人员**: 待定
|
||
- **评审结果**: 待定
|
||
- **评审意见**: 待定
|
||
- **修改建议**: 待定
|