2026-01-18 19:44:13 +08:00
|
|
|
|
# Requirements - 元数据部署核心功能
|
|
|
|
|
|
|
|
|
|
|
|
## 需求信息
|
|
|
|
|
|
|
|
|
|
|
|
- **需求名称**: 元数据部署核心功能
|
|
|
|
|
|
- **需求类型**: 功能需求
|
|
|
|
|
|
- **需求编号**: REQ-010-8
|
|
|
|
|
|
- **父需求**: REQ-010
|
|
|
|
|
|
- **创建日期**: 2026-01-17
|
|
|
|
|
|
- **需求版本**: v1.0.0
|
|
|
|
|
|
- **需求提出人**: 系统管理员
|
|
|
|
|
|
- **需求状态**: 待审核
|
|
|
|
|
|
|
|
|
|
|
|
## 输入引用
|
|
|
|
|
|
|
|
|
|
|
|
引用相关的 docs 文档链接：
|
|
|
|
|
|
|
|
|
|
|
|
- [REQ-010.md](REQ-010.md) - Salesforce元数据拉取和部署主需求文档
|
|
|
|
|
|
- [REQ-010-1.md](REQ-010-1.md) - 数据库表结构设计和创建
|
|
|
|
|
|
- [REQ-010-2.md](REQ-010-2.md) - 基础实体类和Mapper创建
|
|
|
|
|
|
- [REQ-010-3.md](REQ-010-3.md) - Salesforce组织配置管理
|
|
|
|
|
|
- [REQ-010-4.md](REQ-010-4.md) - 元数据任务定义管理
|
|
|
|
|
|
- [REQ-010-5.md](REQ-010-5.md) - Metadata API客户端封装
|
|
|
|
|
|
- [004-元数据部署网页资料链接地址](../reference-code/metadata/004-元数据部署网页资料链接地址) - 官方文档和开源项目参考
|
|
|
|
|
|
- [010-metadata-retrieve-deploy-sub-requirements.md](010-metadata-retrieve-deploy-sub-requirements.md) - REQ-010子需求拆分文档
|
2026-01-19 10:06:09 +08:00
|
|
|
|
- [metadata-module.md](../reference-code/com/docs/metadata-module.md) - Salesforce Metadata API 模块说明（唯一真源）
|
|
|
|
|
|
- [index.md](../reference-code/com/docs/index.md) - Salesforce SOAP API Java 客户端参考文档（唯一真源）
|
2026-01-18 19:44:13 +08:00
|
|
|
|
|
|
|
|
|
|
## Context Maps
|
|
|
|
|
|
|
|
|
|
|
|
强制列出本次需求依赖的 Canvas 文件：
|
|
|
|
|
|
|
|
|
|
|
|
- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
|
|
|
|
|
|
- **相关节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
|
|
|
|
|
- **相关节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务
|
|
|
|
|
|
|
|
|
|
|
|
## 需求目标
|
|
|
|
|
|
|
|
|
|
|
|
实现Salesforce元数据部署的核心功能，使用Metadata API的deploy()方法，支持异步执行、状态轮询、部署结果解析。
|
|
|
|
|
|
|
|
|
|
|
|
## 需求描述
|
|
|
|
|
|
|
|
|
|
|
|
### 概述
|
|
|
|
|
|
|
|
|
|
|
|
本需求旨在实现Salesforce元数据部署的核心功能，包括手动触发部署、异步部署执行、状态监控、部署历史记录、部署进度查询、部署取消功能等。
|
|
|
|
|
|
|
|
|
|
|
|
### 详细需求
|
|
|
|
|
|
|
|
|
|
|
|
#### 1. 手动触发部署功能
|
|
|
|
|
|
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **需求描述**: 实现手动触发部署功能，使用RESTful API接口调用MetadataApiClient的deploy()方法
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **优先级**: 高
|
|
|
|
|
|
- **验收标准**:
|
|
|
|
|
|
- 能够成功手动触发部署
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- 支持选择任务ID（taskId）
|
|
|
|
|
|
- 支持选择组织配置（orgConfigId）
|
|
|
|
|
|
- 支持上传Zip文件或指定Zip文件路径
|
|
|
|
|
|
- 触发成功返回Job ID（datai_meta_job_execution.id）
|
|
|
|
|
|
- 初始化作业执行记录到datai_meta_job_execution表
|
|
|
|
|
|
- 设置初始状态为Pending
|
|
|
|
|
|
- 记录创建时间（startTime）
|
|
|
|
|
|
- 记录创建人（createdBy）
|
|
|
|
|
|
- API接口符合RESTful规范（POST /metadata/deploy/trigger）
|
|
|
|
|
|
- 使用MetadataDeployController控制器
|
|
|
|
|
|
- 调用IMetadataDeployService.triggerDeploy()方法
|
|
|
|
|
|
- 返回DeployTriggerResponse响应
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **依赖关系**: 依赖于REQ-010-1, REQ-010-2, REQ-010-3, REQ-010-4, REQ-010-5
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **实现建议**: 使用MetadataDeployController控制器，提供POST /metadata/deploy/trigger接口，调用IMetadataDeployService的triggerDeploy()方法，使用异步线程池执行部署任务
|
2026-01-18 19:44:13 +08:00
|
|
|
|
|
|
|
|
|
|
#### 2. 异步部署执行
|
|
|
|
|
|
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **需求描述**: 实现异步部署执行，使用Spring的@Async注解和自定义线程池避免阻塞主线程
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **优先级**: 高
|
|
|
|
|
|
- **验收标准**:
|
|
|
|
|
|
- 异步部署执行正常工作
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- 使用Spring的@Async注解标记异步方法
|
|
|
|
|
|
- 使用自定义线程池（ThreadPoolTaskExecutor）管理异步任务
|
|
|
|
|
|
- 支持并发部署（核心线程数5，最大线程数10，队列容量100）
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- 部署任务不阻塞系统响应
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- 使用Future对象跟踪异步任务状态
|
|
|
|
|
|
- 使用ConcurrentHashMap缓存异步任务Future对象
|
|
|
|
|
|
- 异步方法：deployAsync(Long jobExecutionId, Long taskId, Long orgConfigId, String zipFilePath)
|
|
|
|
|
|
- 更新作业执行记录状态为Processing
|
|
|
|
|
|
- 调用IMetadataApiService.deploy()方法执行部署
|
|
|
|
|
|
- 部署完成后更新作业执行记录状态为Success或Failed
|
|
|
|
|
|
- 解析部署结果并存储到datai_meta_job_execution表
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **依赖关系**: 依赖于手动触发部署功能
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **实现建议**: 使用Spring的@Async注解和自定义线程池（deployExecutor）实现异步执行，配置核心线程数、最大线程数、队列容量等参数，使用Future对象跟踪异步任务状态
|
2026-01-18 19:44:13 +08:00
|
|
|
|
|
|
|
|
|
|
#### 3. 状态监控
|
|
|
|
|
|
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **需求描述**: 实现部署状态监控，使用状态机模式管理部署状态（Pending/Processing/Success/Failed/Partial_Success/Cancelled）
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **优先级**: 高
|
|
|
|
|
|
- **验收标准**:
|
|
|
|
|
|
- 状态监控正常工作
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- 使用状态机模式管理部署状态
|
|
|
|
|
|
- 定义DeployStatus枚举（Pending/Processing/Success/Failed/Partial_Success/Cancelled）
|
|
|
|
|
|
- 支持状态查询（GET /metadata/deploy/progress/{jobId}）
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- 状态更新及时
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- 使用轮询机制检查部署状态
|
|
|
|
|
|
- 使用定时任务轮询部署状态（@Scheduled注解）
|
|
|
|
|
|
- 轮询间隔可配置（metadata.deploy.poll-interval，默认5000毫秒）
|
|
|
|
|
|
- 将状态更新到datai_meta_job_execution表
|
|
|
|
|
|
- 记录状态变更时间
|
|
|
|
|
|
- 支持状态转换验证（Pending -> Processing -> Success/Failed/Partial_Success/Cancelled）
|
|
|
|
|
|
- 实现状态机管理类
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **依赖关系**: 依赖于异步部署执行
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **实现建议**: 使用状态机模式管理部署状态，使用轮询机制检查部署状态，使用定时任务（@Scheduled注解）定期查询部署状态，将状态更新到数据库
|
2026-01-18 19:44:13 +08:00
|
|
|
|
|
|
|
|
|
|
#### 4. 部署历史记录
|
|
|
|
|
|
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **需求描述**: 实现部署历史记录功能，使用MyBatis Plus的BaseMapper实现查询
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **优先级**: 高
|
|
|
|
|
|
- **验收标准**:
|
|
|
|
|
|
- 部署历史记录成功
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- 使用datai_meta_job_execution表存储部署历史记录
|
|
|
|
|
|
- 支持分页查询（使用Page对象）
|
|
|
|
|
|
- 支持条件查询（使用QueryWrapper）
|
|
|
|
|
|
- 支持按任务ID查询（taskId）
|
|
|
|
|
|
- 支持按组织配置ID查询（orgConfigId）
|
|
|
|
|
|
- 支持按状态查询（status）
|
|
|
|
|
|
- 支持按时间范围查询（startTime, endTime）
|
|
|
|
|
|
- 支持按创建人查询（createdBy）
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- 历史记录完整
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- 返回DeployHistoryResponse响应
|
|
|
|
|
|
- 包含完整的部署信息（任务信息、组织信息、状态、时间、结果等）
|
|
|
|
|
|
- API接口符合RESTful规范（GET /metadata/deploy/history）
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **依赖关系**: 依赖于状态监控
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **实现建议**: 使用MyBatis Plus的BaseMapper实现历史记录查询，使用Page对象实现分页查询，使用QueryWrapper实现条件查询，支持多种查询条件组合
|
2026-01-18 19:44:13 +08:00
|
|
|
|
|
|
|
|
|
|
#### 5. 部署进度查询
|
|
|
|
|
|
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **需求描述**: 实现部署进度查询功能，使用轮询机制获取进度，使用缓存提高查询性能
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **优先级**: 高
|
|
|
|
|
|
- **验收标准**:
|
|
|
|
|
|
- 部署进度查询成功
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- 支持实时进度查询（GET /metadata/deploy/progress/{jobId}）
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- 进度信息准确
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- 支持进度百分比显示（progressPercent）
|
|
|
|
|
|
- 支持已处理组件数显示（numberComponentsDeployed）
|
|
|
|
|
|
- 支持总组件数显示（numberComponentsTotal）
|
|
|
|
|
|
- 支持错误组件数显示（numberComponentErrors）
|
|
|
|
|
|
- 支持测试结果显示（runTestResult）
|
|
|
|
|
|
- 支持测试警告数显示（numberTestWarnings）
|
|
|
|
|
|
- 支持测试错误数显示（numberTestErrors）
|
|
|
|
|
|
- 支持总测试数显示（numberTestsTotal）
|
|
|
|
|
|
- 支持已完成测试数显示（numberTestsCompleted）
|
|
|
|
|
|
- 使用轮询机制获取进度
|
|
|
|
|
|
- 使用ConcurrentHashMap缓存部署进度信息
|
|
|
|
|
|
- 缓存更新及时
|
|
|
|
|
|
- 返回DeployProgressResponse响应
|
|
|
|
|
|
- 进度查询响应时间 < 500ms
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **依赖关系**: 依赖于状态监控
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **实现建议**: 使用轮询机制获取进度，使用ConcurrentHashMap缓存部署进度信息以提高查询性能，提供GET /metadata/deploy/progress/{jobId}接口查询进度，支持多种进度信息显示
|
2026-01-18 19:44:13 +08:00
|
|
|
|
|
|
|
|
|
|
#### 6. 部署取消功能
|
|
|
|
|
|
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **需求描述**: 实现部署取消功能，使用Future.cancel()取消异步任务，使用状态机管理取消状态
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **优先级**: 高
|
|
|
|
|
|
- **验收标准**:
|
|
|
|
|
|
- 部署取消功能正常工作
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- 支持取消正在进行的部署任务（POST /metadata/deploy/cancel/{jobId}）
|
|
|
|
|
|
- 使用Future.cancel()取消异步任务
|
|
|
|
|
|
- 将状态更新为Cancelled
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- 取消后资源正确释放
|
|
|
|
|
|
- 取消状态更新及时
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- 记录取消日志
|
|
|
|
|
|
- 从ConcurrentHashMap中移除Future对象
|
|
|
|
|
|
- 从ConcurrentHashMap中移除进度缓存
|
|
|
|
|
|
- 支持取消验证（只能取消Processing状态的任务）
|
|
|
|
|
|
- 返回取消结果（Boolean）
|
|
|
|
|
|
- API接口符合RESTful规范
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **依赖关系**: 依赖于异步部署执行
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **实现建议**: 使用Future.cancel()取消异步任务，使用状态机管理取消状态，确保资源正确释放，记录取消日志，提供POST /metadata/deploy/cancel/{jobId}接口
|
2026-01-18 19:44:13 +08:00
|
|
|
|
|
|
|
|
|
|
#### 7. 部署结果解析
|
|
|
|
|
|
|
|
|
|
|
|
- **需求描述**: 实现部署结果解析，提取错误信息和代码覆盖率
|
|
|
|
|
|
- **优先级**: 高
|
|
|
|
|
|
- **验收标准**:
|
|
|
|
|
|
- 部署结果解析成功
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- 使用JSON解析库（Jackson）处理API响应
|
|
|
|
|
|
- 使用正则表达式提取错误信息
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- 错误信息提取正确
|
|
|
|
|
|
- 代码覆盖率提取正确
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- 支持多种部署状态（Success/Failed/Partial_Success）
|
|
|
|
|
|
- 错误信息详细（包含组件类型、文件名、错误消息、行号、列号等）
|
|
|
|
|
|
- 支持测试结果解析（runTestResult）
|
|
|
|
|
|
- 支持组件统计信息解析（numberComponentsTotal, numberComponentsDeployed, numberComponentErrors）
|
|
|
|
|
|
- 支持测试统计信息解析（numberTestsTotal, numberTestsCompleted, numberTestWarnings, numberTestErrors）
|
|
|
|
|
|
- 将解析结果存储到datai_meta_job_execution表
|
|
|
|
|
|
- 部署详情存储到deployDetails字段
|
|
|
|
|
|
- 错误信息存储到errorMessage字段
|
|
|
|
|
|
- 实现parseDeployResult()方法
|
|
|
|
|
|
- 返回DeployResult响应
|
|
|
|
|
|
- 支持多种错误类型识别
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **依赖关系**: 依赖于状态监控
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **实现建议**: 使用Jackson解析API响应，使用正则表达式提取错误信息，将解析结果存储到数据库（datai_meta_job_execution表），支持多种部署状态和错误类型识别
|
2026-01-18 19:44:13 +08:00
|
|
|
|
|
|
|
|
|
|
## 约束
|
|
|
|
|
|
|
|
|
|
|
|
- **技术栈限制**: 必须基于现有的Spring Boot 3 + Vue 3技术栈
|
|
|
|
|
|
- **架构约束**: 必须遵循Authentication.canvas中定义的架构和调用关系
|
|
|
|
|
|
- **模块约束**: 必须在datai-salesforce-metadata模块下实现
|
|
|
|
|
|
- **数据库约束**: 必须使用MyBatis Plus作为持久层框架
|
|
|
|
|
|
- **认证约束**: 必须使用SessionManager进行会话管理和自动重新登录
|
|
|
|
|
|
- **API约束**: 必须使用现有的集成核心功能进行Salesforce API调用
|
|
|
|
|
|
- **异步约束**: 必须使用异步线程池执行长时间任务
|
|
|
|
|
|
- **文档约束**: 必须遵循REQ-010中定义的验收标准
|
|
|
|
|
|
- **依赖约束**: 必须依赖于REQ-010-1, REQ-010-2, REQ-010-3, REQ-010-4, REQ-010-5
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **控制器约束**: 必须使用MetadataDeployController控制器
|
|
|
|
|
|
- **服务接口约束**: 必须实现IMetadataDeployService接口
|
|
|
|
|
|
- **服务实现约束**: 必须实现MetadataDeployServiceImpl实现类
|
|
|
|
|
|
- **异步注解约束**: 必须使用Spring的@Async注解标记异步方法
|
|
|
|
|
|
- **线程池约束**: 必须使用自定义线程池（ThreadPoolTaskExecutor）管理异步任务
|
|
|
|
|
|
- **线程池配置约束**: 核心线程数5，最大线程数10，队列容量100，线程名称前缀deploy-async-，拒绝策略CallerRunsPolicy
|
|
|
|
|
|
- **Future对象约束**: 必须使用Future对象跟踪异步任务状态
|
|
|
|
|
|
- **ConcurrentHashMap约束**: 必须使用ConcurrentHashMap缓存异步任务Future对象和部署进度信息
|
|
|
|
|
|
- **状态机约束**: 必须使用状态机模式管理部署状态
|
|
|
|
|
|
- **状态枚举约束**: 必须定义DeployStatus枚举（Pending/Processing/Success/Failed/Partial_Success/Cancelled）
|
|
|
|
|
|
- **状态转换约束**: 必须支持状态转换验证（Pending -> Processing -> Success/Failed/Partial_Success/Cancelled）
|
|
|
|
|
|
- **定时任务约束**: 必须使用Spring的@Scheduled注解实现定时任务
|
|
|
|
|
|
- **轮询间隔约束**: 轮询间隔可配置（metadata.deploy.poll-interval，默认5000毫秒）
|
|
|
|
|
|
- **状态更新约束**: 必须将状态更新到datai_meta_job_execution表
|
|
|
|
|
|
- **状态变更时间约束**: 必须记录状态变更时间
|
|
|
|
|
|
- **分页查询约束**: 必须使用Page对象实现分页查询
|
|
|
|
|
|
- **条件查询约束**: 必须使用QueryWrapper实现条件查询
|
|
|
|
|
|
- **查询条件约束**: 必须支持按任务ID、组织配置ID、状态、时间范围、创建人查询
|
|
|
|
|
|
- **进度缓存约束**: 必须使用ConcurrentHashMap缓存部署进度信息
|
|
|
|
|
|
- **进度字段约束**: 必须支持进度百分比、已处理组件数、总组件数、错误组件数、测试结果、测试警告数、测试错误数、总测试数、已完成测试数
|
|
|
|
|
|
- **进度查询响应时间约束**: 进度查询响应时间 < 500ms
|
|
|
|
|
|
- **Future.cancel约束**: 必须使用Future.cancel()取消异步任务
|
|
|
|
|
|
- **取消状态约束**: 必须将状态更新为Cancelled
|
|
|
|
|
|
- **取消验证约束**: 必须支持取消验证（只能取消Processing状态的任务）
|
|
|
|
|
|
- **资源释放约束**: 必须确保取消后资源正确释放
|
|
|
|
|
|
- **取消日志约束**: 必须记录取消日志
|
|
|
|
|
|
- **缓存清理约束**: 必须从ConcurrentHashMap中移除Future对象和进度缓存
|
|
|
|
|
|
- **JSON解析约束**: 必须使用Jackson解析API响应
|
|
|
|
|
|
- **正则表达式约束**: 必须使用正则表达式提取错误信息
|
|
|
|
|
|
- **错误信息约束**: 必须支持组件类型、文件名、错误消息、行号、列号等错误信息
|
|
|
|
|
|
- **测试结果约束**: 必须支持测试结果解析（runTestResult）
|
|
|
|
|
|
- **组件统计约束**: 必须支持组件统计信息解析（numberComponentsTotal, numberComponentsDeployed, numberComponentErrors）
|
|
|
|
|
|
- **测试统计约束**: 必须支持测试统计信息解析（numberTestsTotal, numberTestsCompleted, numberTestWarnings, numberTestErrors）
|
|
|
|
|
|
- **结果存储约束**: 必须将解析结果存储到datai_meta_job_execution表
|
|
|
|
|
|
- **部署详情存储约束**: 部署详情必须存储到deployDetails字段
|
|
|
|
|
|
- **错误信息存储约束**: 错误信息必须存储到errorMessage字段
|
|
|
|
|
|
- **DTO约束**: 必须实现DeployTriggerRequest、DeployTriggerResponse、DeployProgressResponse、DeployHistoryResponse、DeployResult等DTO类
|
|
|
|
|
|
- **枚举类约束**: 必须实现DeployStatus枚举类
|
|
|
|
|
|
- **异常类约束**: 必须实现DeployException异常类
|
|
|
|
|
|
- **配置类约束**: 必须实现AsyncConfig配置类
|
|
|
|
|
|
- **RESTful API约束**: 必须符合RESTful规范
|
|
|
|
|
|
- **接口路径约束**: 必须使用/metadata/deploy作为基础路径
|
|
|
|
|
|
- **触发接口约束**: 必须实现POST /metadata/deploy/trigger接口
|
|
|
|
|
|
- **进度查询接口约束**: 必须实现GET /metadata/deploy/progress/{jobId}接口
|
|
|
|
|
|
- **历史查询接口约束**: 必须实现GET /metadata/deploy/history接口
|
|
|
|
|
|
- **取消接口约束**: 必须实现POST /metadata/deploy/cancel/{jobId}接口
|
|
|
|
|
|
- **响应格式约束**: 必须使用R<T>统一响应格式
|
|
|
|
|
|
- **日志记录约束**: 必须遵循现有的日志记录规范
|
|
|
|
|
|
- **异常处理约束**: 必须遵循现有的异常处理机制
|
|
|
|
|
|
- **事务管理约束**: 必须使用@Transactional注解管理事务
|
|
|
|
|
|
- **实体类约束**: 必须使用DataiMetaJobExecution实体类
|
|
|
|
|
|
- **Mapper约束**: 必须使用DataiMetaJobExecutionMapper进行数据库操作
|
|
|
|
|
|
- **任务实体约束**: 必须使用DataiMetaTask实体类
|
|
|
|
|
|
- **任务Mapper约束**: 必须使用DataiMetaTaskMapper进行数据库操作
|
|
|
|
|
|
- **部署方法约束**: 必须调用IMetadataApiService.deploy()方法执行部署
|
|
|
|
|
|
- **作业类型约束**: 必须使用DataiMetaTask.getTaskType()获取作业类型
|
|
|
|
|
|
- **初始化记录约束**: 必须初始化作业执行记录到datai_meta_job_execution表
|
|
|
|
|
|
- **初始状态约束**: 必须设置初始状态为Pending
|
|
|
|
|
|
- **创建时间约束**: 必须记录创建时间（startTime）
|
|
|
|
|
|
- **创建人约束**: 必须记录创建人（createdBy）
|
|
|
|
|
|
- **状态更新方法约束**: 必须实现updateJobStatus()方法更新作业状态
|
|
|
|
|
|
- **进度更新方法约束**: 必须实现updateJobProgress()方法更新作业进度
|
|
|
|
|
|
- **结果解析方法约束**: 必须实现parseDeployResult()方法解析部署结果
|
|
|
|
|
|
- **部署触发方法约束**: 必须实现triggerDeploy()方法触发部署
|
|
|
|
|
|
- **异步部署方法约束**: 必须实现deployAsync()方法执行异步部署
|
|
|
|
|
|
- **进度查询方法约束**: 必须实现getProgress()方法查询进度
|
|
|
|
|
|
- **历史查询方法约束**: 必须实现getHistory()方法查询历史
|
|
|
|
|
|
- **取消部署方法约束**: 必须实现cancelDeploy()方法取消部署
|
|
|
|
|
|
- **Lombok约束**: 必须使用Lombok的@Data、@Slf4j等注解简化代码
|
|
|
|
|
|
- **Swagger约束**: 必须使用Swagger注解（@Schema）标注API文档
|
|
|
|
|
|
- **Excel约束**: 必须使用@Excel注解标注导出字段
|
|
|
|
|
|
- **Jackson约束**: 必须使用Jackson的@JsonFormat注解格式化日期时间
|
|
|
|
|
|
- **性能约束**: 部署触发响应时间 < 1s，并发触发10个部署任务无性能下降，状态轮询任务执行时间 < 1s，历史记录查询响应时间 < 1s，分页查询100条记录无性能下降
|
|
|
|
|
|
- **安全性约束**: 部署操作需要认证，部署数据传输加密，敏感信息不记录到日志，部署历史记录权限控制
|
|
|
|
|
|
- **兼容性约束**: 必须使用现有的集成核心功能进行Salesforce API调用，必须使用现有的认证模块进行OAuth认证，必须遵循现有的异常处理机制，必须遵循现有的日志记录规范
|
2026-01-18 19:44:13 +08:00
|
|
|
|
|
|
|
|
|
|
## Rule Set
|
|
|
|
|
|
|
|
|
|
|
|
"请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。"
|
|
|
|
|
|
|
|
|
|
|
|
**具体规则**：
|
|
|
|
|
|
- 必须使用Canvas中定义的类名和方法名
|
|
|
|
|
|
- 必须遵循Canvas中定义的调用关系
|
|
|
|
|
|
- 必须参考Canvas中的流程图逻辑
|
|
|
|
|
|
- 必须使用SessionManager进行会话管理和自动重新登录
|
|
|
|
|
|
- 必须使用现有的认证模块进行OAuth认证
|
|
|
|
|
|
- 必须使用现有的集成核心功能进行API调用
|
|
|
|
|
|
- 必须遵循现有的异常处理机制
|
|
|
|
|
|
- 必须遵循现有的日志记录规范
|
|
|
|
|
|
|
|
|
|
|
|
## 验收标准
|
|
|
|
|
|
|
|
|
|
|
|
- **功能完整性**: 所有部署功能能够正常工作，异步执行机制正常
|
|
|
|
|
|
- **性能指标**: 部署操作不影响系统响应，状态轮询频率合理
|
|
|
|
|
|
- **代码规范性**: 代码符合项目编码规范，有清晰的注释
|
|
|
|
|
|
- **可维护性**: 代码结构清晰，易于扩展和维护
|
|
|
|
|
|
- **可测试性**: 代码易于单元测试和集成测试
|
|
|
|
|
|
|
|
|
|
|
|
## 风险
|
|
|
|
|
|
|
|
|
|
|
|
- **异步执行风险**: 异步执行机制复杂可能导致状态管理困难
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **缓解措施**: 使用状态机模式管理状态，使用Future对象跟踪异步任务
|
|
|
|
|
|
- **监控指标**: 监控异步任务执行时间和状态转换
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **状态轮询风险**: 状态轮询频率不当可能导致API限流
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **缓解措施**: 设置合理的轮询间隔（如5秒），使用指数退避策略
|
|
|
|
|
|
- **监控指标**: 监控API调用次数和响应时间
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **部署取消风险**: 部署取消功能复杂可能导致资源泄漏
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **缓解措施**: 使用Future.cancel()安全取消，确保资源正确释放
|
|
|
|
|
|
- **监控指标**: 监控取消操作的成功率和资源释放情况
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **历史记录风险**: 部署历史记录过多可能影响查询性能
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **缓解措施**: 使用分页查询，定期清理过期历史记录
|
|
|
|
|
|
- **监控指标**: 监控历史记录查询性能
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **进度查询风险**: 进度查询不准确可能导致用户体验差
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **缓解措施**: 使用缓存提高查询性能，优化轮询策略
|
|
|
|
|
|
- **监控指标**: 监控进度查询的准确性和响应时间
|
2026-01-18 19:44:13 +08:00
|
|
|
|
- **结果解析风险**: 部署结果解析不完善可能导致错误信息不准确
|
2026-01-26 23:10:05 +08:00
|
|
|
|
- **缓解措施**: 使用JSON解析库和正则表达式双重验证，充分测试
|
|
|
|
|
|
- **监控指标**: 监控结果解析的成功率和准确性
|
|
|
|
|
|
- **线程池配置风险**: 线程池参数配置不当可能导致资源耗尽或任务积压
|
|
|
|
|
|
- **缓解措施**: 根据实际负载调整线程池参数，使用合理的拒绝策略
|
|
|
|
|
|
- **监控指标**: 监控线程池的活跃线程数、队列大小、拒绝任务数
|
|
|
|
|
|
- **ConcurrentHashMap风险**: ConcurrentHashMap缓存数据丢失可能导致进度查询失败
|
|
|
|
|
|
- **缓解措施**: 使用持久化存储作为备份，定期检查缓存一致性
|
|
|
|
|
|
- **监控指标**: 监控缓存的命中率和数据一致性
|
|
|
|
|
|
- **状态机风险**: 状态机状态转换逻辑错误可能导致状态异常
|
|
|
|
|
|
- **缓解措施**: 充分测试状态转换逻辑，使用状态机框架
|
|
|
|
|
|
- **监控指标**: 监控状态转换的成功率和异常状态数
|
|
|
|
|
|
- **定时任务风险**: 定时任务执行失败可能导致状态更新不及时
|
|
|
|
|
|
- **缓解措施**: 使用异常处理和重试机制，监控定时任务执行情况
|
|
|
|
|
|
- **监控指标**: 监控定时任务的执行成功率和执行时间
|
|
|
|
|
|
- **轮询间隔风险**: 轮询间隔设置不当可能导致API限流或状态更新不及时
|
|
|
|
|
|
- **缓解措施**: 使用动态轮询间隔，根据负载调整轮询频率
|
|
|
|
|
|
- **监控指标**: 监控API调用次数和状态更新延迟
|
|
|
|
|
|
- **Future对象管理风险**: Future对象管理不当可能导致内存泄漏
|
|
|
|
|
|
- **缓解措施**: 定期清理已完成的Future对象，使用弱引用
|
|
|
|
|
|
- **监控指标**: 监控Future对象的数量和内存使用情况
|
|
|
|
|
|
- **分页查询风险**: 分页查询参数不当可能导致查询性能下降
|
|
|
|
|
|
- **缓解措施**: 限制分页大小，使用索引优化查询
|
|
|
|
|
|
- **监控指标**: 监控分页查询的响应时间和数据库负载
|
|
|
|
|
|
- **条件查询风险**: 条件查询过于复杂可能导致查询性能下降
|
|
|
|
|
|
- **缓解措施**: 限制查询条件数量，使用索引优化查询
|
|
|
|
|
|
- **监控指标**: 监控条件查询的响应时间和数据库负载
|
|
|
|
|
|
- **JSON解析风险**: JSON解析失败可能导致结果解析异常
|
|
|
|
|
|
- **缓解措施**: 使用异常处理和重试机制，验证JSON格式
|
|
|
|
|
|
- **监控指标**: 监控JSON解析的成功率和错误率
|
|
|
|
|
|
- **正则表达式风险**: 正则表达式性能不佳可能导致解析缓慢
|
|
|
|
|
|
- **缓解措施**: 优化正则表达式，使用预编译正则表达式
|
|
|
|
|
|
- **监控指标**: 监控正则表达式的执行时间
|
|
|
|
|
|
- **错误信息提取风险**: 错误信息提取不完整可能导致问题排查困难
|
|
|
|
|
|
- **缓解措施**: 充分测试错误信息提取逻辑，使用多种提取策略
|
|
|
|
|
|
- **监控指标**: 监控错误信息提取的完整性和准确性
|
|
|
|
|
|
- **测试结果解析风险**: 测试结果解析错误可能导致测试状态显示错误
|
|
|
|
|
|
- **缓解措施**: 充分测试测试结果解析逻辑，使用多种测试场景
|
|
|
|
|
|
- **监控指标**: 监控测试结果解析的准确性和错误率
|
|
|
|
|
|
- **组件统计风险**: 组件统计信息不准确可能导致进度显示错误
|
|
|
|
|
|
- **缓解措施**: 充分测试组件统计逻辑，使用多种统计策略
|
|
|
|
|
|
- **监控指标**: 监控组件统计的准确性和一致性
|
|
|
|
|
|
- **测试统计风险**: 测试统计信息不准确可能导致测试状态显示错误
|
|
|
|
|
|
- **缓解措施**: 充分测试测试统计逻辑，使用多种统计策略
|
|
|
|
|
|
- **监控指标**: 监控测试统计的准确性和一致性
|
|
|
|
|
|
- **数据库操作风险**: 数据库操作失败可能导致数据不一致
|
|
|
|
|
|
- **缓解措施**: 使用事务管理，使用异常处理和重试机制
|
|
|
|
|
|
- **监控指标**: 监控数据库操作的成功率和错误率
|
|
|
|
|
|
- **事务管理风险**: 事务管理不当可能导致数据不一致
|
|
|
|
|
|
- **缓解措施**: 合理设置事务边界，使用事务传播机制
|
|
|
|
|
|
- **监控指标**: 监控事务的成功率和回滚率
|
|
|
|
|
|
- **Mapper操作风险**: Mapper操作失败可能导致数据库操作失败
|
|
|
|
|
|
- **缓解措施**: 充分测试Mapper操作，使用异常处理机制
|
|
|
|
|
|
- **监控指标**: 监控Mapper操作的成功率和错误率
|
|
|
|
|
|
- **API调用风险**: API调用失败可能导致部署失败
|
|
|
|
|
|
- **缓解措施**: 使用异常处理和重试机制，监控API调用情况
|
|
|
|
|
|
- **监控指标**: 监控API调用的成功率和响应时间
|
|
|
|
|
|
- **SessionManager风险**: SessionManager失效可能导致认证失败
|
|
|
|
|
|
- **缓解措施**: 使用自动重新登录机制，监控SessionManager状态
|
|
|
|
|
|
- **监控指标**: 监控SessionManager的成功率和错误率
|
|
|
|
|
|
- **OAuth认证风险**: OAuth认证失败可能导致API调用失败
|
|
|
|
|
|
- **缓解措施**: 使用Token刷新机制，监控OAuth认证状态
|
|
|
|
|
|
- **监控指标**: 监控OAuth认证的成功率和错误率
|
|
|
|
|
|
- **文件存储风险**: 文件存储失败可能导致部署失败
|
|
|
|
|
|
- **缓解措施**: 使用文件存储抽象层，支持多种存储方式
|
|
|
|
|
|
- **监控指标**: 监控文件存储的成功率和错误率
|
|
|
|
|
|
- **文件读取风险**: 文件读取失败可能导致部署失败
|
|
|
|
|
|
- **缓解措施**: 使用异常处理和重试机制，验证文件完整性
|
|
|
|
|
|
- **监控指标**: 监控文件读取的成功率和错误率
|
|
|
|
|
|
- **文件删除风险**: 文件删除失败可能导致磁盘空间不足
|
|
|
|
|
|
- **缓解措施**: 使用文件清理机制，监控磁盘空间
|
|
|
|
|
|
- **监控指标**: 监控文件删除的成功率和磁盘空间使用情况
|
|
|
|
|
|
- **磁盘空间风险**: 磁盘空间不足可能导致文件存储失败
|
|
|
|
|
|
- **缓解措施**: 使用磁盘空间监控，定期清理过期文件
|
|
|
|
|
|
- **监控指标**: 监控磁盘空间使用情况和清理频率
|
|
|
|
|
|
- **内存使用风险**: 内存使用不当可能导致内存溢出
|
|
|
|
|
|
- **缓解措施**: 使用流式处理，限制内存使用，监控内存使用情况
|
|
|
|
|
|
- **监控指标**: 监控内存使用情况和GC频率
|
|
|
|
|
|
- **CPU使用风险**: CPU使用过高可能导致系统性能下降
|
|
|
|
|
|
- **缓解措施**: 使用异步处理，限制并发数，优化算法
|
|
|
|
|
|
- **监控指标**: 监控CPU使用情况和系统负载
|
|
|
|
|
|
- **网络风险**: 网络不稳定可能导致API调用失败
|
|
|
|
|
|
- **缓解措施**: 使用重试机制，使用超时设置，监控网络状态
|
|
|
|
|
|
- **监控指标**: 监控网络延迟和丢包率
|
|
|
|
|
|
- **并发控制风险**: 并发控制不当可能导致数据不一致
|
|
|
|
|
|
- **缓解措施**: 使用锁机制，使用事务管理，使用乐观锁
|
|
|
|
|
|
- **监控指标**: 监控并发操作的成功率和冲突率
|
|
|
|
|
|
- **日志记录风险**: 日志记录不当可能导致问题排查困难
|
|
|
|
|
|
- **缓解措施**: 使用结构化日志，记录关键信息，监控日志级别
|
|
|
|
|
|
- **监控指标**: 监控日志的完整性和可读性
|
|
|
|
|
|
- **异常处理风险**: 异常处理不当可能导致系统崩溃
|
|
|
|
|
|
- **缓解措施**: 使用统一的异常处理机制，记录异常信息，监控异常情况
|
|
|
|
|
|
- **监控指标**: 监控异常的发生率和类型分布
|
|
|
|
|
|
- **性能风险**: 性能不佳可能导致用户体验差
|
|
|
|
|
|
- **缓解措施**: 使用缓存，使用异步处理，优化算法，监控性能指标
|
|
|
|
|
|
- **监控指标**: 监控响应时间、吞吐量、资源使用情况
|
|
|
|
|
|
- **可扩展性风险**: 可扩展性不佳可能导致系统难以扩展
|
|
|
|
|
|
- **缓解措施**: 使用模块化设计，使用接口抽象，使用配置化设计
|
|
|
|
|
|
- **监控指标**: 监控系统的扩展能力和扩展成本
|
|
|
|
|
|
- **可维护性风险**: 可维护性不佳可能导致代码难以维护
|
|
|
|
|
|
- **缓解措施**: 使用清晰的代码结构，使用注释，使用文档，使用代码审查
|
|
|
|
|
|
- **监控指标**: 监控代码的复杂度和可读性
|
|
|
|
|
|
- **可测试性风险**: 可测试性不佳可能导致测试困难
|
|
|
|
|
|
- **缓解措施**: 使用依赖注入，使用接口抽象，使用Mock对象
|
|
|
|
|
|
- **监控指标**: 监控测试覆盖率和测试成功率
|
|
|
|
|
|
- **安全性风险**: 安全性不佳可能导致数据泄露
|
|
|
|
|
|
- **缓解措施**: 使用认证和授权，使用加密，使用输入验证，使用安全审计
|
|
|
|
|
|
- **监控指标**: 监控安全事件和漏洞扫描结果
|
|
|
|
|
|
- **兼容性风险**: 兼容性不佳可能导致系统无法运行
|
|
|
|
|
|
- **缓解措施**: 使用版本控制，使用兼容性测试，使用降级策略
|
|
|
|
|
|
- **监控指标**: 监控兼容性问题和降级触发频率
|
|
|
|
|
|
- **可靠性风险**: 可靠性不佳可能导致系统不稳定
|
|
|
|
|
|
- **缓解措施**: 使用冗余设计，使用故障恢复，使用监控告警
|
|
|
|
|
|
- **监控指标**: 监控系统的可用性和故障恢复时间
|
|
|
|
|
|
- **可观测性风险**: 可观测性不佳可能导致问题排查困难
|
|
|
|
|
|
- **缓解措施**: 使用日志，使用监控，使用追踪，使用告警
|
|
|
|
|
|
- **监控指标**: 监控日志的完整性，监控的覆盖率，追踪的成功率
|
2026-01-18 19:44:13 +08:00
|
|
|
|
|
|
|
|
|
|
## 需求变更记录
|
|
|
|
|
|
|
|
|
|
|
|
| 日期 | 变更内容 | 变更原因 | 变更人 | 审核人 | 状态 |
|
|
|
|
|
|
|------|---------|---------|--------|--------|------|
|
|
|
|
|
|
| 2026-01-17 | 创建需求文档 | 初始需求 | 系统管理员 | - | 待审核 |
|
2026-01-26 23:10:05 +08:00
|
|
|
|
| 2026-01-26 | 优化需求文档 | 基于当前项目实际情况，优化需求文档，包括：1. 明确了使用DataiMetaJobExecution实体类存储部署信息；2. 明确了使用IMetadataApiService.deploy()方法执行部署；3. 明确了使用MetadataDeployController控制器；4. 明确了使用IMetadataDeployService接口和MetadataDeployServiceImpl实现类；5. 明确了使用Spring的@Async注解和自定义线程池；6. 明确了使用状态机模式管理部署状态；7. 明确了使用定时任务轮询部署状态；8. 明确了使用ConcurrentHashMap缓存部署进度信息；9. 明确了使用Future.cancel()取消异步任务；10. 明确了使用Jackson解析API响应；11. 明确了使用正则表达式提取错误信息；12. 明确了使用MyBatis Plus的BaseMapper实现查询；13. 明确了使用Page对象实现分页查询；14. 明确了使用QueryWrapper实现条件查询；15. 明确了使用R<T>统一响应格式；16. 明确了使用@Transactional注解管理事务；17. 明确了使用Lombok的@Data、@Slf4j等注解；18. 明确了使用Swagger注解标注API文档；19. 明确了使用@Excel注解标注导出字段；20. 明确了使用Jackson的@JsonFormat注解格式化日期时间；21. 增加了详细的约束条件；22. 增加了详细的风险评估和缓解措施 | 根据架构决策文档和提示词文档优化需求文档，确保需求与实际实现一致 | 系统管理员 | - | 待审核 |
|
2026-01-18 19:44:13 +08:00
|
|
|
|
|
|
|
|
|
|
## 相关人员
|
|
|
|
|
|
|
|
|
|
|
|
- **需求提出人**: 系统管理员 - 联系方式
|
|
|
|
|
|
- **需求负责人**: 系统管理员 - 联系方式
|
|
|
|
|
|
- **技术负责人**: 开发工程师 - 联系方式
|
|
|
|
|
|
- **测试负责人**: 测试工程师 - 联系方式
|
|
|
|
|
|
- **其他相关人员**: - 联系方式
|
|
|
|
|
|
|
|
|
|
|
|
## 评审信息
|
|
|
|
|
|
|
|
|
|
|
|
- **评审日期**: -
|
|
|
|
|
|
- **评审人员**: -
|
|
|
|
|
|
- **评审结果**: -
|
|
|
|
|
|
- **评审意见**: -
|
|
|
|
|
|
- **修改建议**: -
|
