kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/prompts/2026-01-30-002-prompt-CRUD操作.md

10 KiB
Raw Permalink Blame History

提示词：CRUD 操作

引用真源

需求描述

根据需求文档，实现 Salesforce Partner API 的 CRUD 操作功能，包括：

  1. Create: 创建新记录，支持批量创建
  2. Retrieve: 检索单个记录
  3. Update: 更新记录，支持批量更新
  4. Delete: 删除记录，支持批量删除
  5. Upsert: 更新或插入记录，支持批量 Upsert
  6. Merge: 合并记录

核心要求：

  • 通过 PartnerConnectionFactory 获取 PartnerConnection 实例
  • 使用 PartnerConnection 的 CRUD 方法执行操作
  • 支持单个和批量操作
  • 正确处理各种异常情况
  • 返回统一的响应格式

设计方案

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

技术栈

  • 框架: Spring Boot 3.x、Spring Security 6.x、若依框架
  • API: Salesforce Partner API（partner.jar）
  • 工具: Lombok、Swagger 3.x
  • 测试: JUnit 5、Mockito

系统架构

采用分层架构：

  • Controller 层: PartnerCrudController - REST API 控制器
  • Service 层: IPartnerCrudService 接口 + PartnerCrudServiceImpl 实现
  • Factory 层: PartnerConnectionFactory - 连接工厂
  • Model 层: DTO（请求参数）、VO（响应结果）
  • Util 层: SObjectConverter - SObject 转换工具类

核心功能

  1. 连接管理: 通过 PartnerConnectionFactory 获取 PartnerConnection 实例
  2. 数据转换: 将 Map<String, Object> 转换为 SObject 对象
  3. 批量操作: 支持批量创建、更新、删除、Upsert
  4. 异常处理: 捕获并转换 ConnectionException、ApiFault 等异常
  5. 结果处理: 处理 SaveResult、DeleteResult、UpsertResult、MergeResult

接口设计

提供 6 个 REST API 接口：

  1. POST /api/partner/crud/create - 创建记录
  2. GET /api/partner/crud/retrieve - 检索单个记录
  3. PUT /api/partner/crud/update - 更新记录
  4. DELETE /api/partner/crud/delete - 删除记录
  5. POST /api/partner/crud/upsert - 更新或插入记录
  6. POST /api/partner/crud/merge - 合并记录

异常处理

  • 使用 datai-salesforce-common 模块的异常体系
  • 使用若依的 GlobalExceptionHandler 处理异常
  • 转换 Salesforce API 异常为业务异常

输出格式要求

必须包含的文件

  1. Controller:

    • PartnerCrudController.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/controller/PartnerCrudController.java）
    • 功能：提供 6 个 REST API 接口

  2. Service 接口:

    • IPartnerCrudService.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/service/IPartnerCrudService.java）
    • 功能：定义 CRUD 操作的服务接口

  3. Service 实现:

    • PartnerCrudServiceImpl.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/service/impl/PartnerCrudServiceImpl.java）
    • 功能：实现 CRUD 操作的业务逻辑

  4. DTO 类:

    • CreateRecordDto.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/CreateRecordDto.java）
    • UpdateRecordDto.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/UpdateRecordDto.java）
    • DeleteRecordDto.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/DeleteRecordDto.java）
    • UpsertRecordDto.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/UpsertRecordDto.java）
    • MergeRecordDto.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/model/dto/MergeRecordDto.java）

  5. VO 类:

    • RecordResultVo.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/RecordResultVo.java）
    • RetrieveResultVo.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/RetrieveResultVo.java）
    • ErrorVo.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/model/vo/ErrorVo.java）

  6. 工具类:

    • SObjectConverter.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/util/SObjectConverter.java）
    • 功能：Map<String, Object> 与 SObject 之间的转换

  7. 单元测试:

    • PartnerCrudServiceImplTest.java（路径：datai-salesforce-partner/src/test/java/com/datai/partner/service/impl/PartnerCrudServiceImplTest.java）

代码结构要求

  • 必须遵循 Spring Boot 最佳实践
  • 必须遵循若依框架规范
  • 必须使用分层架构（Controller → Service → Factory）
  • 必须使用依赖注入（@Autowired 或构造器注入）
  • 必须使用 Lombok 注解简化代码

REST API 定义要求

  • 必须使用 RESTful 风格的 API 设计
  • 必须使用 Swagger 注解（@ApiOperation、@ApiParam）
  • 必须使用若依的统一响应格式（AjaxResult）
  • 必须使用权限控制注解（@PreAuthorize("@ss.hasLogin()")）
  • 必须使用参数验证注解（@Validated、@NotNull、@NotBlank）

代码规范要求

命名规范

  1. 类命名: 首字母大写，驼峰命名，如 PartnerCrudController
  2. 接口命名: 首字母大写，驼峰命名，以 I 开头，如 IPartnerCrudService
  3. 方法命名: 首字母小写，驼峰命名，如 createRecord
  4. 变量命名: 首字母小写，驼峰命名，如 objectType
  5. 常量命名: 全大写，下划线分隔，如 MAX_BATCH_SIZE

注释规范

  1. 类注释: 使用 /** */，包含类功能描述、作者、创建时间
  2. 方法注释: 使用 /** */，包含方法功能、参数、返回值、异常描述
  3. 字段注释: 使用 /** */，包含字段功能描述
  4. Swagger 注释: 使用 @ApiOperation 描述 API 功能，使用 @ApiParam 描述参数

代码格式

  1. 使用 4 个空格缩进
  2. 行宽不超过 120 字符
  3. 每个方法不超过 50 行
  4. 每个类不超过 500 行

导入规范

  1. 按照以下顺序导入：
    • Java 标准库
    • 第三方库
    • 项目内部库
  2. 避免通配符导入（import *）
  3. 使用静态导入（import static）

异常处理规范

  1. 使用 try-catch 捕获 Salesforce API 异常
  2. 使用 datai-salesforce-common 模块的异常类
  3. 将 ConnectionException 转换为 SalesforceConnectionException
  4. 将 ApiFault 转换为 SalesforceOperationException
  5. 记录详细的错误日志

日志规范

  1. 使用 SLF4J + Logback
  2. 使用 Lombok 的 @Slf4j 注解
  3. 记录关键操作日志（创建、更新、删除）
  4. 记录异常日志（包含堆栈信息）

测试要求

单元测试覆盖率

  • 单元测试覆盖率不低于 80%
  • 每个公共方法必须有对应的测试用例

测试场景

  1. 正常场景:

    • 创建记录成功
    • 检索单个记录成功
    • 更新记录成功
    • 删除记录成功
    • Upsert 记录成功（创建）
    • Upsert 记录成功（更新）
    • 合并记录成功

  2. 批量操作场景:

    • 批量创建记录成功
    • 批量更新记录成功
    • 批量删除记录成功
    • 批量 Upsert 记录成功

  3. 异常场景:

    • 连接失败
    • 记录不存在
    • 字段验证失败
    • 权限不足
    • 外部 ID 冲突
    • 合并记录冲突

测试框架

  • 使用 JUnit 5 进行单元测试
  • 使用 Mockito 模拟依赖对象
  • 使用 @ExtendWith(MockitoExtension.class) 注解

测试用例命名规范

  • 格式：test+方法名+场景
  • 示例：testCreateRecordSuccess、testRetrieveRecordNotFound

测试数据

  • 使用 Mockito 模拟 PartnerConnection
  • 使用 Mockito 模拟 SaveResult、DeleteResult 等结果对象
  • 测试数据应覆盖各种边界情况

注意事项

必须使用的现有类

  1. PartnerConnectionFactory: 从 datai-salesforce-auth 模块获取连接

    • 方法：getConnection() 返回 PartnerConnection
    • 自动处理连接缓存和 Session 有效性检查

  2. 异常类: 从 datai-salesforce-common 模块导入

    • SalesforceConnectionException: 连接异常
    • SalesforceOperationException: 操作异常
    • SalesforceValidationException: 验证异常

  3. 常量类: 从 datai-salesforce-common 模块导入

    • SalesforceConstants: 包含常量定义

必须处理的特殊情况

  1. 空值处理: 必须处理 Salesforce API 的空值情况
  2. 批量操作限制: 必须遵守 Salesforce API 的批量操作限制（默认 200 条）
  3. 字段清空: 必须支持字段清空功能（setFieldsToNull）
  4. 子对象关系: 必须支持子对象关系（setSObjectField）
  5. 日期时间: 必须正确处理日期时间字段

必须遵循的若依框架规范

  1. 权限控制: 使用 @PreAuthorize("@ss.hasLogin()") 进行权限控制
  2. 参数验证: 使用 @Validated 和 @NotNull、@NotBlank 进行参数验证
  3. 响应格式: 使用 AjaxResult 作为统一的响应格式
  4. 异常处理: 使用若依的 GlobalExceptionHandler 处理异常
  5. 日志记录: 使用若依的 @Log 注解记录操作日志

必须遵循的 Salesforce API 规范

  1. SObject 转换: 必须正确转换 Map<String, Object> 为 SObject
  2. 字段类型: 必须正确处理各种字段类型（字符串、数字、日期、布尔值等）
  3. 外部 ID: 必须正确处理外部 ID 字段（Upsert 操作）
  4. 合并记录: 必须正确处理记录合并逻辑
  5. 错误处理: 必须正确处理 Salesforce API 返回的错误信息

性能优化要求

  1. 连接复用: 必须使用连接缓存，避免频繁创建连接
  2. 批量操作: 必须支持批量操作，提高性能
  3. 异步处理: 对于大批量操作，考虑使用异步处理

安全要求

  1. 参数验证: 必须验证所有输入参数
  2. 权限控制: 必须进行权限检查
  3. 防注入: 必须防止 SOQL 注入攻击
  4. 数据脱敏: 敏感数据必须脱敏处理

文档要求

  1. Swagger 文档: 必须使用 Swagger 注解生成 API 文档
  2. 代码注释: 必须添加详细的代码注释
  3. README: 必须编写 README 文档，说明使用方法

依赖注入要求

  1. Service 注入: Controller 必须注入 IPartnerCrudService
  2. Factory 注入: Service 必须注入 PartnerConnectionFactory
  3. 构造器注入: 推荐使用构造器注入，而不是字段注入

错误处理要求

  1. 统一异常: 必须使用统一的异常处理机制
  2. 错误信息: 必须返回清晰的错误信息
  3. 错误码: 必须使用标准的错误码
  4. 日志记录: 必须记录详细的错误日志