datai/datai-scenes/datai-scene-salesforce/docs/prompts/028-file-infrastructure-enums.md

Prompt - 基础设施和枚举定义实现

输入引用

引用相关的 docs 文档链接：

• REQ-011.md - 父需求文档
• REQ-011-1.md - 子需求文档
• 0027-file-infrastructure-enums.md - 架构决策记录 (ADR)
• Authentication.canvas - 项目架构视觉化展示

Context Maps

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

• Authentication.canvas - 项目架构视觉化展示
• 相关节点: 通用常量 - 定义Salesforce相关的常量
• 相关节点: 通用异常 - 定义Salesforce相关的异常类

目标

本提示词的目标是指导 AI 实现 REQ-011-1 需求，在 datai-salesforce-common 模块定义文件上传下载所需的基础设施，包括：

1. 文件对象类型枚举（FileObjectType）：支持 Attachment、ContentDocument、Document 三种类型
2. 文件上传下载参数类：FileUploadRequest、FileDownloadRequest、FileUploadResponse、FileDownloadResponse
3. 文件上传下载异常类：FileUploadException、FileDownloadException、FileSizeExceededException、FileTypeNotSupportedException、FileObjectNotFoundException、OrgConfigNotFoundException、FileValidationException
4. 文件验证工具类（FileValidationUtils）：提供文件大小和类型的验证方法

预期效果：

• 所有基础设施类能够正常工作，提供完整的枚举、参数、异常和验证功能
• 代码符合项目编码规范，有清晰的注释
• 代码结构清晰，易于扩展和维护
• 代码易于单元测试

输出格式

代码输出格式

语言：Java 22

代码结构：

datai-salesforce-common/src/main/java/com/datai/common/
├── enums/
│   └── FileObjectType.java
├── exception/
│   ├── FileErrorCode.java
│   ├── FileUploadException.java
│   ├── FileDownloadException.java
│   ├── FileSizeExceededException.java
│   ├── FileTypeNotSupportedException.java
│   ├── FileObjectNotFoundException.java
│   ├── OrgConfigNotFoundException.java
│   └── FileValidationException.java
├── param/
│   ├── FileUploadRequest.java
│   ├── FileDownloadRequest.java
│   ├── FileUploadResponse.java
│   └── FileDownloadResponse.java
└── utils/
    └── FileValidationUtils.java

代码要求：

• 使用 Lombok 注解简化代码（@Data、@Builder、@NoArgsConstructor、@AllArgsConstructor、@Slf4j）
• 使用 JSR-303 验证注解（@NotNull、@NotBlank、@Size、@Valid）
• 使用 Javadoc 注释，包含参数说明、返回值说明、异常说明
• 遵循阿里巴巴 Java 开发手册
• 代码行数不超过 200 行/文件

单元测试输出格式

语言：Java 22 + JUnit 5 + Mockito

测试结构：

datai-salesforce-common/src/test/java/com/datai/common/
├── enums/
│   └── FileObjectTypeTest.java
├── exception/
│   ├── FileUploadExceptionTest.java
│   ├── FileDownloadExceptionTest.java
│   ├── FileSizeExceededExceptionTest.java
│   ├── FileTypeNotSupportedExceptionTest.java
│   ├── FileObjectNotFoundExceptionTest.java
│   ├── OrgConfigNotFoundExceptionTest.java
│   └── FileValidationExceptionTest.java
├── param/
│   ├── FileUploadRequestTest.java
│   ├── FileDownloadRequestTest.java
│   ├── FileUploadResponseTest.java
│   └── FileDownloadResponseTest.java
└── utils/
    └── FileValidationUtilsTest.java

测试要求：

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

文档输出格式

格式：Markdown

文档要求：

• 为每个类提供 Javadoc 注释
• 为每个公共方法提供 Javadoc 注释
• 为每个枚举值提供 Javadoc 注释
• 为每个异常类提供使用示例

约束

技术栈限制

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

架构约束

• 必须遵循 Authentication.canvas 中定义的架构和调用关系
• 必须在 datai-salesforce-common 模块下实现
• 必须遵循现有的异常处理机制
• 必须遵循现有的日志记录规范

依赖约束

• 可以引入 Apache Tika 依赖（用于文件 MIME 类型检测）
• 不能引入与项目现有依赖冲突的依赖

性能约束

• 文件验证方法必须在 100ms 内完成
• 枚举转换方法必须在 10ms 内完成
• 参数验证方法必须在 50ms 内完成

安全性约束

• 文件类型验证必须使用白名单机制
• 文件名验证必须防止路径遍历攻击
• 文件大小验证必须防止 DoS 攻击

兼容性约束

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

Rule Set

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

具体规则：

• 必须使用 Canvas 中定义的类名和方法名
• 必须遵循 Canvas 中定义的调用关系
• 必须参考 Canvas 中的流程图逻辑
• 必须遵循现有的异常处理机制
• 必须遵循现有的日志记录规范
• 必须遵循项目编码规范
• 必须使用 Lombok 注解简化代码
• 必须使用 JSR-303 验证注解
• 必须提供完整的 Javadoc 注释

验收标准

功能完整性

• FileObjectType 枚举包含 ATTACHMENT、CONTENT_DOCUMENT、DOCUMENT 三个枚举值
• FileObjectType 枚举提供描述、文件大小限制、推荐等级等元数据
• FileObjectType 枚举提供枚举值与字符串的转换方法
• FileUploadRequest 包含所有必需字段
• FileDownloadRequest 包含所有必需字段
• FileUploadResponse 包含所有必需字段
• FileDownloadResponse 包含所有必需字段
• 所有异常类继承自 RuntimeException
• 所有异常类提供错误代码和错误消息
• FileValidationUtils 提供所有必需的验证方法

代码正确性

• 代码符合项目编码规范
• 代码有清晰的注释
• 代码通过 SonarQube 静态代码分析
• 代码通过 Checkstyle 检查
• 代码通过 SpotBugs 检查

文档准确性

• 每个类提供 Javadoc 注释
• 每个公共方法提供 Javadoc 注释
• 每个枚举值提供 Javadoc 注释
• 每个异常类提供使用示例

性能指标

• 文件验证方法在 100ms 内完成
• 枚举转换方法在 10ms 内完成
• 参数验证方法在 50ms 内完成
• 单元测试覆盖率 ≥ 90%

风险

输出质量风险

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

技术实现风险

• 风险描述：Apache Tika 依赖可能与项目现有依赖冲突
• 影响程度：中
• 缓解措施：
  1. 使用 Maven 依赖树检查冲突
  2. 必要时使用 exclusions
  3. 提供备选方案（使用 Java 内置的 Files.probeContentType() 方法）

时间成本风险

• 风险描述：实现所有基础设施类可能需要较长时间
• 影响程度：低
• 缓解措施：
  1. 优先实现核心类（FileObjectType、参数类）
  2. 逐步实现异常类和验证工具类
  3. 分批进行单元测试

其他潜在风险

• 风险描述：枚举扩展性不足，未来可能需要支持更多文件对象类型
• 影响程度：低
• 缓解措施：
  1. 枚举设计时考虑扩展性
  2. 提供清晰的扩展文档
  3. 使用配置文件管理文件对象类型（备选方案）

使用记录

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