datai/datai-scenes/datai-scene-salesforce/docs/requirements/0001-salesforce-realtime-sync.md

# Requirements 模板

## 需求信息

- **需求名称**: Salesforce数据及时同步至本地数据库
- **需求类型**: 功能需求
- **需求编号**: REQ-001
- **创建日期**: 2026-01-09
- **需求版本**: v1.4.0
- **需求提出人**: 系统管理员
- **需求状态**: 待审核

## 输入引用

引用相关的 docs 文档链接：

- [0000-template.md](0000-template.md) - 需求文档模板
- [架构决策](../decisions/adr/0001-salesforce-cdc-sync.md) - Salesforce Pub/Sub API同步方案
- [设计文档](../design/0001-salesforce-cdc-realtime-sync.md) - Salesforce Pub/Sub API实时同步设计

## Context Maps

强制列出本次需求依赖的 Canvas 文件：

- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
- **相关节点**: [集成任务](node_integration_task) - 处理Salesforce的定时同步任务
- **相关节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务
- **相关节点**: [Salesforce连接类型](node_integration_connections) - 提供与Salesforce的各种连接方式

## 需求目标

明确描述此需求的目标和预期效果，包括要解决的问题、实现的功能或达成的结果。

本需求的目标是通过Salesforce Pub/Sub API 同步方案，实现Salesforce数据的实时同步至本地数据库，确保本地系统能够实时获取Salesforce中的最新数据，支持业务系统的高效运行和数据分析。通过建立可靠的同步机制，解决数据延迟和不一致的问题，提高系统的整体性能和用户体验。

## 需求描述

### 概述

简要描述需求的整体内容和范围。

本需求旨在实现Salesforce数据的实时同步功能，采用Salesforce Pub/Sub API 同步方案，包括配置同步策略、执行同步操作、监控同步状态、处理同步异常等功能。同步范围包括Salesforce中的标准对象和自定义对象，仅支持基于Pub/Sub API的实时同步模式，并提供同步历史记录和统计分析功能。

### 详细需求

#### 1. 同步配置管理

- **需求描述**: 提供同步配置管理功能，支持配置同步对象、字段映射、同步频率、同步模式等参数。在对象表中增加is_realtime_sync字段（tinyint(1)类型）用于判断是否开启实时数据同步。在对象启用Pub/Sub API时，检查本地数据库中的batch表是否已经全量拉取存量数据，若没有则提示但仍可启用Pub/Sub API。
- **优先级**: 高
- **验收标准**: 
  - 能够成功配置同步对象和字段映射
  - 能够设置同步频率和同步模式
  - 对象表中成功添加is_realtime_sync字段（tinyint(1)类型）
  - 配置变更后能够正确生效
  - 启用Pub/Sub API时能够检查batch表并提示存量数据拉取状态
- **依赖关系**: 依赖于配置模块和集成模块
- **实现建议**: 基于现有的配置管理功能，扩展同步配置的支持，并在对象表中添加实时同步开关字段

#### 2. 实时数据同步

- **需求描述**: 实现Salesforce数据的实时同步功能，采用Salesforce Pub/Sub API 同步方案，仅支持基于Pub/Sub API的实时同步模式。事件处理采用异步执行方式，upsert操作参考DataiIntegrationBatchServiceImpl中的processQueryResult方法实现。利用Pub/Sub API的自动重连和消息重试机制，提高系统可靠性。暂不考虑额外的失败重试机制。
- **优先级**: 高
- **验收标准**: 
  - 能够成功使用Pub/Sub API订阅Salesforce事件总线并捕获变更
  - 能够成功处理和同步捕获的变更数据
  - 同步数据与Salesforce中的数据一致
  - 同步操作能够在规定时间内完成
  - 事件处理采用异步执行方式
  - upsert操作正确实现
  - Pub/Sub API的自动重连机制正常工作
- **依赖关系**: 依赖于集成模块和会话管理
- **实现建议**: 基于现有的集成核心功能，集成Salesforce Pub/Sub API客户端库，实现数据同步逻辑，参考DataiIntegrationBatchServiceImpl中的processQueryResult方法实现upsert操作

#### 3. 同步监控与日志

- **需求描述**: 提供同步监控和日志功能，记录同步操作的执行状态、结果和异常信息。为实时数据同步创建专门的日志表，用于记录对象数据同步的详细信息。
- **优先级**: 中
- **验收标准**: 
  - 能够实时监控同步操作的执行状态
  - 能够查看同步操作的详细日志
  - 能够统计同步操作的执行情况
  - 成功创建实时数据同步日志表
  - 日志表能够记录对象数据同步的详细信息
  - 已实现DataiIntegrationRealtimeSyncLog实体类
  - 已实现DataiIntegrationRealtimeSyncLogController控制器
  - 提供日志查询、导出和详情查看功能
- **依赖关系**: 依赖于集成模块和日志系统
- **实现建议**: 基于现有的日志功能，扩展同步监控的支持，并创建专门的实时数据同步日志表

#### 4. 异常处理

- **需求描述**: 实现同步异常的处理机制，确保同步操作的可靠性。暂不考虑失败重试。
- **优先级**: 中
- **验收标准**: 
  - 能够正确捕获和处理同步异常
  - 能够提供异常信息的详细记录
- **依赖关系**: 依赖于集成模块和异常处理机制
- **实现建议**: 基于现有的异常处理功能，扩展同步异常的处理支持

## 约束

列出需求实现时的约束条件，例如：
- 技术栈限制：基于现有的Spring Boot3+Vue3技术栈
- 性能要求：同步操作不能影响系统的正常运行
- 安全性要求：确保同步过程中的数据安全
- 兼容性要求：支持不同版本的Salesforce API
- 时间限制：需要在规定的时间内完成实现
- 其他约束：需要遵守Salesforce的API使用限制

## Rule Set

"请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。"

**具体规则**：
- 必须使用 Canvas 中定义的类名和方法名
- 必须遵循 Canvas 中定义的调用关系
- 必须参考 Canvas 中的流程图逻辑

## 验收标准

定义验证需求是否满足的具体标准，例如：
- 功能完整性：所有同步功能能够正常工作
- 性能指标：同步操作的执行时间在可接受范围内
- 安全性要求：同步过程中的数据传输和存储安全
- 用户体验：同步操作的操作界面友好易用
- 其他验收标准：同步数据的准确性和一致性

## 风险

识别需求可能带来的风险，例如：
- 技术实现风险：Salesforce API的变更可能影响同步功能
- 时间风险：实现复杂度可能导致项目延期
- 成本风险：可能需要额外的资源投入
- 质量风险：同步数据的准确性可能受到影响
- 其他潜在风险：网络连接不稳定可能影响同步可靠性

## 需求变更记录

| 日期 | 变更内容 | 变更原因 | 变更人 | 审核人 | 状态 |
|------|---------|---------|--------|--------|------|
| 2026-01-09 | 更新需求文档，明确is_realtime_sync字段类型、batch表检查逻辑、upsert实现方式和事件处理方式 | 需求细节确认 | 系统管理员 | - | 待审核 |
| 2026-01-09 | 更新需求文档，移除全量和增量同步，只保留CDC同步 | 需求范围调整 | 系统管理员 | - | 待审核 |
| 2026-01-09 | 更新需求文档，添加Salesforce CDC相关内容 | 架构决策变更 | 系统管理员 | - | 待审核 |
| 2026-01-09 | 创建需求文档 | 初始需求 | 系统管理员 | - | 待审核 |

## 相关人员

- **需求提出人**: 系统管理员 - 联系方式
- **需求负责人**: 系统管理员 - 联系方式
- **技术负责人**: 开发工程师 - 联系方式
- **测试负责人**: 测试工程师 - 联系方式
- **其他相关人员**: 运维工程师 - 联系方式

## 评审信息

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