datai/datai-scenes/datai-scene-salesforce/docs/decisions/2026-02-03-003-07-ADR-检查部署和检索状态技术选型.md

ADR-003-07: 检查部署和检索状态技术选型

状态

已接受

日期

2026-02-03

背景

Salesforce Metadata API 的 deploy 和 retrieve 操作是异步的。为了获取操作的最终结果（如部署是否成功、检索到的 ZIP 文件），客户端需要使用 asyncId 调用 checkDeployStatus 或 checkRetrieveStatus 接口。 我们需要确定：

1. 如何实现状态检查机制？
2. 如何与现有的异步操作轮询策略保持一致？
3. 如何存储状态检查的历史记录以满足审计需求？

决策

1. 状态检查机制

选择 主动查询 (Active Polling) 方案。 直接调用 Metadata API 的 checkDeployStatus 和 checkRetrieveStatus 接口。 理由：

• Metadata API 不支持 Webhook 或其他被动通知机制。
• 这是官方推荐的标准做法。

2. 轮询策略

选择 复用服务端同步轮询 (Server-side Synchronous Polling) 策略（遵循 ADR-003-04）。

• 服务端提供 pollDeployStatus 和 pollRetrieveStatus 方法。
• 使用 Thread.sleep 进行阻塞式轮询，直到状态变为 Succeeded、Failed、Canceled 或超时。 理由：
• 一致性：保持与项目其他异步模块一致的架构风格。
• 简化客户端：客户端无需维护复杂的定时器逻辑。

3. 数据存储与审计

选择 独立审计表 + 主表状态同步 方案。

• 新增 datai_metadata_status_check 表，记录每一次状态查询的结果（包括时间、状态、错误信息）。
• 同时更新 datai_metadata_deploy 或 datai_metadata_retrieve 主表的最新状态。 理由：
• 可追溯性：元数据操作通常耗时较长且容易出错，保留完整的状态变更历史有助于排查“为什么操作卡住”或“何时失败”的问题。
• 数据完整性：主表始终反映最新状态，便于列表展示；审计表反映过程，便于详情查看。

后果

正面影响

1. 高可靠性：通过服务端轮询和重试机制，确保在网络波动时也能稳定获取结果。
2. 审计合规：详细的检查日志满足企业级审计需求。
3. 开发效率：复用现有轮询模式，减少重复设计。

负面影响

1. 存储开销：datai_metadata_status_check 表的数据量可能随时间增长，需要定期的清理策略（归档或删除）。
2. 线程占用：长轮询会占用 Web 容器线程，但在 Metadata 操作低并发场景下可接受。

替代方案

方案 2：仅更新主表（无审计表）

• 描述：每次检查只更新 datai_metadata_deploy 表。
• 优点：节省存储空间，逻辑简单。
• 缺点：丢失状态变更的历史轨迹，无法分析操作耗时分布或中间状态异常。

方案 3：客户端轮询

• 描述：服务端只提供单次检查接口，前端负责轮询。
• 优点：服务端无状态，扩展性好。
• 缺点：如果后续有“部署成功后自动触发测试”的需求，服务端仍需实现轮询逻辑，导致逻辑割裂。

相关文档

• 需求文档
• 设计文档
• ADR-003-04: 异步操作轮询策略