kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
5983d3c8ca
datai/datai-scenes/datai-scene-salesforce/docs/prompts/031-document-upload-download.md

9.5 KiB
Raw Blame History

Prompt - Document 文件上传下载功能实现

输入引用

引用相关的 docs 文档链接：

Context Maps

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

目标

本提示词的目标是指导 AI 实现 REQ-011-4 需求，在 datai-salesforce-integration 模块实现 Salesforce Document 对象的文件上传下载功能，使用 Partner API (SOAP) 方式，支持最大 20-30MB 文件。

预期效果：

  • DocumentUploadStrategy 类能够成功上传本地文件到 Salesforce Document 对象
  • DocumentDownloadStrategy 类能够成功从 Salesforce Document 对象下载文件到本地
  • DocumentFileService 接口和实现类能够封装上传下载逻辑
  • 使用策略模式封装上传下载逻辑，符合开闭原则
  • 使用流式处理避免内存溢出
  • 代码符合项目编码规范，有清晰的注释
  • 代码结构清晰，易于扩展和维护
  • 代码易于单元测试

输出格式

代码输出格式

语言：Java 22

代码结构：

datai-salesforce-integration/src/main/java/com/datai/integration/
├── strategy/
│   ├── impl/
│   │   ├── DocumentUploadStrategy.java
│   │   └── DocumentDownloadStrategy.java
└── service/
    ├── DocumentFileService.java
    └── impl/
        └── DocumentFileServiceImpl.java

代码要求：

  • 使用 Lombok 注解简化代码（@Data、@Builder、@NoArgsConstructor、@AllArgsConstructor、@Slf4j）
  • 使用 JSR-303 验证注解（@NotNull、@NotBlank、@Size、@Valid）
  • 使用 Spring 注解（@Service、@Autowired、@Component）
  • 使用 Javadoc 注释，包含参数说明、返回值说明、异常说明
  • 遵循阿里巴巴 Java 开发手册
  • 代码行数不超过 200 行/文件
  • 使用策略模式封装上传下载逻辑
  • 使用流式处理避免内存溢出

单元测试输出格式

语言：Java 22 + JUnit 5 + Mockito

测试结构：

datai-salesforce-integration/src/test/java/com/datai/integration/
├── strategy/
│   └── impl/
│       ├── DocumentUploadStrategyTest.java
│       └── DocumentDownloadStrategyTest.java
└── service/
    └── impl/
        └── DocumentFileServiceImplTest.java

测试要求：

  • 使用 JUnit 5 的 @Test、@ParameterizedTest、@Nested 等注解
  • 使用 Mockito 的 @Mock、@InjectMocks 等注解
  • 测试覆盖率 ≥ 90%
  • 测试用例包含：正常场景、边界场景、异常场景

文档输出格式

格式：Markdown

文档要求：

  • 为每个类提供 Javadoc 注释
  • 为每个公共方法提供 Javadoc 注释
  • 为每个策略类提供使用示例

约束

技术栈限制

  • 必须基于现有的 Spring Boot 3 技术栈
  • 必须使用 Java 22
  • 必须使用 Lombok（如果项目已引入）
  • 必须使用 JSR-303 Bean Validation
  • 必须使用 JUnit 5
  • 必须使用 Mockito

架构约束

  • 必须遵循 Authentication.canvas 中定义的架构和调用关系
  • 必须在 datai-salesforce-integration 模块下实现
  • 必须使用 SessionManager 进行会话管理和自动重新登录
  • 必须使用 PartnerV1Connection 处理 SOAP API 调用
  • 必须使用策略模式封装上传下载逻辑

依赖约束

  • 必须依赖 REQ-011-1 的基础设施（FileObjectType、FileErrorCode、FileUploadRequest、FileDownloadRequest、FileUploadResponse、FileDownloadResponse、FileValidationUtils）
  • 必须依赖 datai-salesforce-integration 模块的 SessionManager
  • 必须依赖 datai-salesforce-integration 模块的 PartnerV1Connection
  • 不能引入与项目现有依赖冲突的依赖

性能约束

  • 文件上传方法必须在合理时间内完成（20-30MB 文件）
  • 文件下载方法必须在合理时间内完成（20-30MB 文件）
  • 流式处理必须有效避免内存溢出
  • 文件验证方法必须在 100ms 内完成

安全性约束

  • 文件类型验证必须使用白名单机制
  • 文件名验证必须防止路径遍历攻击
  • 文件大小验证必须防止 DoS 攻击
  • 必须使用 SessionManager 进行认证，防止未授权访问

兼容性约束

  • 必须兼容 Windows、Linux、macOS 操作系统
  • 必须兼容 UTF-8 编码
  • 必须兼容 Salesforce API v58.0+
  • 必须兼容 Partner API (SOAP)

Rule Set

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

具体规则：

  • 必须使用 Canvas 中定义的类名和方法名
  • 必须遵循 Canvas 中定义的调用关系
  • 必须参考 Canvas 中的流程图逻辑
  • 必须使用 SessionManager 进行会话管理和自动重新登录
  • 必须使用 PartnerV1Connection 处理 SOAP API 调用
  • 必须遵循现有的异常处理机制
  • 必须遵循现有的日志记录规范
  • 必须使用策略模式封装上传下载逻辑
  • 必须使用流式处理避免内存溢出
  • 必须遵循项目编码规范
  • 必须使用 Lombok 注解简化代码
  • 必须使用 JSR-303 验证注解
  • 必须提供完整的 Javadoc 注释

验收标准

功能完整性

  • DocumentUploadStrategy 类实现 FileUploadStrategy 接口
  • DocumentUploadStrategy 类能够成功上传本地文件到 Salesforce Document 对象
  • DocumentUploadStrategy 类支持指定组织配置 ID
  • DocumentUploadStrategy 类支持指定 FolderId（必填）
  • DocumentUploadStrategy 类支持指定文件名和 DeveloperName
  • DocumentUploadStrategy 类使用 Base64 编码文件内容
  • DocumentUploadStrategy 类上传成功返回 Document ID
  • DocumentUploadStrategy 类支持文件大小验证（建议不超过 20-30MB）
  • DocumentUploadStrategy 类支持文件类型验证
  • DocumentUploadStrategy 类提供详细的错误信息
  • DocumentDownloadStrategy 类实现 FileDownloadStrategy 接口
  • DocumentDownloadStrategy 类能够成功从 Salesforce Document 对象下载文件到本地
  • DocumentDownloadStrategy 类支持指定组织配置 ID
  • DocumentDownloadStrategy 类支持指定 Document ID
  • DocumentDownloadStrategy 类支持指定保存路径
  • DocumentDownloadStrategy 类使用流式处理避免内存溢出
  • DocumentDownloadStrategy 类下载成功返回文件信息
  • DocumentDownloadStrategy 类支持大文件下载
  • DocumentDownloadStrategy 类提供详细的错误信息
  • DocumentFileService 接口定义 uploadDocument 方法
  • DocumentFileService 接口定义 downloadDocument 方法
  • DocumentFileServiceImpl 实现类使用策略模式封装上传下载逻辑
  • DocumentFileServiceImpl 实现类提供参数验证
  • DocumentFileServiceImpl 实现类提供异常处理
  • DocumentFileServiceImpl 实现类提供日志记录

代码正确性

  • 代码符合项目编码规范
  • 代码有清晰的注释
  • 代码通过 IDE 诊断检查，无编译错误或警告
  • 代码通过 SonarQube 静态代码分析
  • 代码通过 Checkstyle 检查
  • 代码通过 SpotBugs 检查

文档准确性

  • 每个类提供 Javadoc 注释
  • 每个公共方法提供 Javadoc 注释
  • 每个策略类提供使用示例

性能指标

  • 文件上传性能良好，不影响系统响应
  • 文件下载性能良好，不影响系统响应
  • 流式处理有效避免内存溢出
  • 20-30MB 文件上传下载性能良好
  • 单元测试覆盖率 ≥ 90%

风险

输出质量风险

  • 风险描述：AI 可能生成不符合项目规范的代码
  • 影响程度：中
  • 缓解措施：
    1. 严格遵循项目编码规范
    2. 参考现有代码风格
    3. 使用 Lombok 注解简化代码
    4. 提供完整的 Javadoc 注释

技术实现风险

  • 风险描述：SOAP API 调用复杂度高，可能增加实现难度
  • 影响程度：高
  • 缓解措施：
    1. 参考官方文档和示例代码
    2. 使用成熟的 SOAP 客户端库
    3. 参考 Attachment 和 ContentDocument 的实现方式
    4. 提供详细的错误处理和日志记录

性能风险

  • 风险描述：Base64 编码可能导致文件大小增加约 33%
  • 影响程度：中
  • 缓解措施：
    1. 限制文件大小，建议不超过 20-30MB
    2. 使用流式处理避免内存溢出
    3. 优化 Base64 编码和解码性能

时间成本风险

  • 风险描述：实现所有类可能需要较长时间
  • 影响程度：低
  • 缓解措施：
    1. 优先实现核心类（DocumentUploadStrategy、DocumentDownloadStrategy）
    2. 逐步实现 Service 接口和实现类
    3. 分批进行单元测试

其他潜在风险

  • 风险描述：Document 功能受限，仅适用于特定场景
  • 影响程度：低
  • 缓解措施：
    1. 提供清晰的文档说明
    2. 提供迁移方案，建议用户使用 ContentDocument
    3. 保持 Document 对象的兼容性

使用记录

日期 使用场景 输入参数 输出结果 反馈 改进措施
2026-01-19 初始实现 REQ-011-4 需求文档 待执行 - -