datai/datai-scenes/datai-scene-salesforce/docs/prompts/2026-02-03-003-06-prompt-检索操作.md

提示词：检索操作

引用真源

• 需求文档
• 设计文档
• ADR 文档
• SQL 脚本

需求描述

根据需求文档和设计文档，实现 Salesforce 元数据检索（Retrieve）功能。该功能允许用户提交检索请求，通过异步方式从 Salesforce 组织中获取元数据（ZIP 包），并提供状态轮询和历史查询功能。

核心功能包括：

1. 提交检索请求：接收 RetrieveRequest，调用 Metadata API 的 retrieve 接口，记录异步操作状态到数据库，返回 AsyncResult。
2. 轮询检索状态：根据 asyncId 轮询检索状态，更新数据库记录。当检索完成（Succeeded/Failed）时，获取最终结果（包含 ZIP 文件数据）。
3. 查询检索历史：分页查询 datai_metadata_retrieve 表中的操作记录。

设计方案

根据设计文档和 ADR，采用以下技术方案：

1. 架构模式：Controller-Service-Repository 分层架构。
2. 异步处理：
   • 使用 MetadataConnection.retrieve() 发起请求。
   • 使用 MetadataConnection.checkRetrieveStatus() 轮询状态。
3. 数据持久化：
   • 使用 datai_metadata_retrieve 表记录操作历史（Async ID, Status, Timestamp, User）。
   • 关键约束：ZIP 文件内容 不存储 在数据库中，仅在 API 响应中返回给客户端。
4. 异常处理：
   • 捕获 ConnectionException 并转换为 SalesforceAuthException 或 SalesforceOperationException。
   • 确保失败的操作也能记录在数据库中（Status=Failed, ErrorMessage=...）。
5. 依赖库：
   • 使用 metadata.jar 中的 RetrieveRequest, RetrieveResult, AsyncResult 等类。
   • 使用 datai-salesforce-auth 模块的 MetadataConnectionFactory。

输出格式要求

1. 必须包含以下文件：
   • Entity: MetadataRetrieveEntity.java
     • 路径：datai-salesforce-metadata/src/main/java/com/datai/salesforce/metadata/domain/MetadataRetrieveEntity.java
     • 注解：@TableName("datai_metadata_retrieve")
   • Mapper: MetadataRetrieveMapper.java
     • 路径：datai-salesforce-metadata/src/main/java/com/datai/salesforce/metadata/mapper/MetadataRetrieveMapper.java
     • 继承 BaseMapper<MetadataRetrieveEntity>
   • Service: MetadataRetrieveService.java
     • 路径：datai-salesforce-metadata/src/main/java/com/datai/salesforce/metadata/service/MetadataRetrieveService.java
     • 包含 retrieveMetadata, pollRetrieveResult, getRetrieveHistory 方法
   • Controller: MetadataRetrieveController.java
     • 路径：datai-salesforce-metadata/src/main/java/com/datai/salesforce/metadata/controller/MetadataRetrieveController.java
     • REST API 接口
2. 必须包含单元测试：
   • MetadataRetrieveServiceTest.java
     • 路径：datai-salesforce-metadata/src/test/java/com/datai/salesforce/metadata/service/MetadataRetrieveServiceTest.java
3. 代码规范：
   • 类名、方法名、变量名符合 Java 驼峰命名规范。
   • 必须包含完整的 Javadoc 注释（类、方法、字段）。
   • 使用 @Autowired 进行依赖注入。
   • 使用 SLF4J 记录日志。

代码规范要求

1. 异常处理：
   • 必须捕获 ConnectionException。
   • 区分认证错误（InvalidSessionId）和业务错误。
2. 数据库操作：
   • 使用 MyBatis Plus 提供的 save, updateById 等方法。
   • 查询历史时按 retrieve_time 倒序排列。
3. API 响应：
   • 使用 ResponseEntity 封装响应。
   • 成功返回 200 OK，认证失败返回 401 Unauthorized，其他错误返回 500 Internal Server Error。

测试要求

1. 单元测试：
   • 使用 JUnit 5 和 Mockito。
   • Mock MetadataConnectionFactory 和 MetadataConnection。
   • Mock MetadataRetrieveMapper。
2. 测试场景：
   • testRetrieveMetadata_Success: 模拟检索请求成功提交，验证数据库插入记录。
   • testRetrieveMetadata_AuthFailure: 模拟认证失败，验证抛出 SalesforceAuthException 且数据库记录失败状态。
   • testPollRetrieveResult_Success: 模拟轮询成功（Succeeded），验证返回 ZIP 数据且数据库更新状态。
   • testPollRetrieveResult_Timeout: 模拟轮询超时，验证抛出异常。
3. 覆盖率：核心业务逻辑覆盖率不低于 80%。