kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/docs/archive/REQ-006.md

9.2 KiB
Raw Permalink Blame History

需求: 元数据变更自动同步本地数据库

元数据 (Metadata)

  • 需求编号: REQ-006
  • 需求标题: 元数据变更自动同步本地数据库
  • 需求类型: 功能需求
  • 优先级: 高
  • 状态: Completed
  • 创建日期: 2026-01-16
  • 最后更新: 2026-01-16
  • 创建人: 用户
  • 负责人: AI Assistant

输入引用

Context Maps

  • 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 创建需求文档 用户提出元数据变更自动同步需求 用户 待审核 待审核

相关人员

  • 需求提出人: 用户 - 联系方式：待补充
  • 需求负责人: 待分配 - 联系方式：待补充
  • 技术负责人: 待分配 - 联系方式：待补充
  • 测试负责人: 待分配 - 联系方式：待补充
  • 其他相关人员: 待补充 - 联系方式：待补充

评审信息

  • 评审日期: 待定
  • 评审人员: 待定
  • 评审结果: 待定
  • 评审意见: 待定
  • 修改建议: 待定