datai/docs/archive/REQ-006.md

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

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

## 相关人员

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

## 评审信息

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