datai/docs/archive/prompts/028-file-infrastructure-enums.md

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

## 输入引用

引用相关的 docs 文档链接：

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

## Context Maps

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

- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
- **相关节点**: [通用常量](node_common_constant) - 定义Salesforce相关的常量
- **相关节点**: [通用异常](node_common_exception) - 定义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 需求文档 | 待执行 | - | - |