236 lines
8.2 KiB
Markdown
236 lines
8.2 KiB
Markdown
# 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 需求文档 | 待执行 | - | - |
|