# REQ-010 子需求拆分文档

## 文档信息

- **父需求**: REQ-010 - Salesforce元数据拉取和部署
- **创建日期**: 2026-01-17
- **拆分原则**: 独立性、优先级、粒度（3-5人天）、完整性、可测试性
- **子需求总数**: 17个

---

## 子需求 1: 数据库表结构设计和创建

### 需求信息
- **子需求编号**: REQ-010-1
- **父需求**: REQ-010
- **需求类型**: 数据需求
- **优先级**: 高
- **预计工作量**: 3人天

### 需求描述
设计和创建Salesforce元数据拉取和部署系统所需的9张核心数据库表，包括datai_meta_org_config、datai_meta_task、datai_meta_package_item、datai_meta_component、datai_meta_component_version、datai_meta_job_execution、datai_meta_job_log、datai_meta_deploy_history、datai_meta_deploy_component_result。

### 功能范围
- 设计datai_meta_org_config表结构（组织配置表）
- 设计datai_meta_task表结构（任务定义表）
- 设计datai_meta_package_item表结构（元数据包定义明细表）
- 设计datai_meta_component表结构（元数据组件索引表）
- 设计datai_meta_component_version表结构（元数据版本内容表）
- 设计datai_meta_job_execution表结构（作业执行流水表）
- 设计datai_meta_job_log表结构（作业详细日志表）
- 设计datai_meta_deploy_history表结构（部署历史表）
- 设计datai_meta_deploy_component_result表结构（部署组件结果明细表）
- 创建数据库表DDL脚本
- 创建索引优化查询性能
- 添加外键约束保证数据完整性

### 验收标准
- 所有9张表的DDL脚本创建成功
- 表结构符合参考资料中的设计规范
- 所有必需字段都包含在内
- 主键、外键、索引创建正确
- DDL脚本可以在MySQL中成功执行
- 表结构支持后续功能扩展
- 字段类型和长度合理
- 添加必要的注释说明

### 依赖关系
- **前置依赖**: 无
- **被依赖**: REQ-010-2, REQ-010-3, REQ-010-4, REQ-010-6, REQ-010-8, REQ-010-11, REQ-010-14, REQ-010-15

### 技术要点
- 使用MyBatis Plus的@Table注解定义表名
- 使用@TableName注解指定表名
- 设计合理的字段类型（VARCHAR、TEXT、BIGINT、DATETIME等）
- 考虑字符集和排序规则（utf8mb4）
- 设计合理的索引策略
- 考虑分表分库的扩展性

### 数据库设计
- **datai_meta_org_config**: id, org_name, org_id, environment_type, auth_config(JSON), storage_root_path, status, created_time, updated_time
- **datai_meta_task**: id, org_config_id, task_name, package_xml_content(TEXT), api_version, schedule_type, cron_expression, created_time, updated_time
- **datai_meta_package_item**: id, group_id, metadata_type, member_name, description, created_time, updated_time
- **datai_meta_component**: id, job_id, component_type, component_name, file_path, file_hash, file_size, created_time, updated_time
- **datai_meta_component_version**: id, component_id, version_number, content_hash, content_body(LONGTEXT), is_binary, commit_message, job_execution_id, created_at
- **datai_meta_job_execution**: id, task_id, start_time, end_time, status, storage_path, file_count, zip_file_location, error_message(TEXT), created_time, updated_time
- **datai_meta_job_log**: id, job_id, step_name, step_status, start_time, end_time, log_message(TEXT), created_time
- **datai_meta_deploy_history**: id, task_id, start_time, end_time, status, deploy_options(JSON), deploy_result(JSON), validation_id, created_time, updated_time
- **datai_meta_deploy_component_result**: id, deploy_history_id, component_name, component_type, file_name, is_success, is_changed, line_number, column_number, problem(TEXT), problem_type, created_time

### API接口
无

### 风险点
- 表结构设计不合理可能导致后续扩展困难
- 索引设计不当可能影响查询性能
- 字段类型选择不当可能导致数据丢失
- 外键约束可能影响数据插入性能

---

## 子需求 2: 基础实体类和Mapper创建

### 需求信息
- **子需求编号**: REQ-010-2
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 高
- **预计工作量**: 4人天

### 需求描述
为9张数据库表创建对应的Java实体类、Mapper接口和XML映射文件，使用MyBatis Plus框架。

### 功能范围
- 创建DataiMetaOrgConfig实体类
- 创建DataiMetaTask实体类
- 创建DataiMetaPackageItem实体类
- 创建DataiMetaComponent实体类
- 创建DataiMetaComponentVersion实体类
- 创建DataiMetaJobExecution实体类
- 创建DataiMetaJobLog实体类
- 创建DataiMetaDeployHistory实体类
- 创建DataiMetaDeployComponentResult实体类
- 创建对应的Mapper接口
- 创建对应的Mapper XML文件
- 添加基础CRUD方法

### 验收标准
- 9个实体类创建成功，使用MyBatis Plus注解
- 9个Mapper接口创建成功，继承BaseMapper
- 9个Mapper XML文件创建成功
- 实体类字段与数据库表字段一一对应
- Mapper接口包含基础的CRUD方法
- XML映射文件配置正确
- 代码符合项目编码规范
- 添加必要的注释说明

### 依赖关系
- **前置依赖**: REQ-010-1
- **被依赖**: REQ-010-3, REQ-010-4, REQ-010-6, REQ-010-8, REQ-010-11, REQ-010-14, REQ-010-15

### 技术要点
- 使用MyBatis Plus的@TableName注解
- 使用@TableId注解标识主键
- 使用@TableField注解处理字段映射
- 继承BaseMapper获取基础CRUD方法
- 使用@Mapper注解标记Mapper接口
- 配置XML映射文件的namespace
- 处理JSON类型字段的序列化和反序列化
- 处理TEXT类型大字段

### 数据库设计
无（使用REQ-010-1创建的表）

### API接口
无

### 风险点
- 实体类字段映射错误可能导致数据读写失败
- Mapper XML配置错误可能导致SQL执行失败
- JSON类型字段处理不当可能导致数据丢失
- 大字段处理不当可能导致性能问题

---

## 子需求 3: Salesforce组织配置管理

### 需求信息
- **子需求编号**: REQ-010-3
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 高
- **预计工作量**: 5人天

### 需求描述
提供Salesforce组织配置的CRUD管理功能，支持多环境配置、OAuth认证管理、存储路径配置等。

### 功能范围
- 创建SfOrgConfigService服务接口
- 创建SfOrgConfigServiceImpl服务实现
- 创建SfOrgConfigController控制器
- 实现组织配置的增删改查功能
- 实现OAuth认证信息加密存储
- 实现环境类型选择（Sandbox/Production）
- 实现存储根路径配置
- 实现连接状态管理（Active/Inactive/Auth_Invalid）
- 实现配置验证功能
- 实现配置查询接口

### 验收标准
- 能够成功添加Salesforce组织配置
- 能够成功编辑组织配置
- 能够成功删除组织配置
- 能够查询组织配置列表
- OAuth认证信息加密存储成功
- 支持环境类型选择
- 支持存储根路径配置
- 支持连接状态管理
- 配置验证功能正常工作
- API接口符合RESTful规范
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-1, REQ-010-2
- **被依赖**: REQ-010-4, REQ-010-6, REQ-010-8

### 技术要点
- 使用SessionManager获取当前登录信息
- 使用AES加密算法加密OAuth认证信息
- 使用枚举类型管理环境类型和连接状态
- 使用@Valid注解进行参数验证
- 使用统一的异常处理机制
- 使用统一的响应格式
- 遵循RESTful API设计规范
- 使用事务管理保证数据一致性

### 数据库设计
使用REQ-010-1创建的datai_meta_org_config表

### API接口
- POST /api/metadata/org-config - 创建组织配置
- PUT /api/metadata/org-config/{id} - 更新组织配置
- DELETE /api/metadata/org-config/{id} - 删除组织配置
- GET /api/metadata/org-config/{id} - 查询组织配置详情
- GET /api/metadata/org-config - 查询组织配置列表
- POST /api/metadata/org-config/{id}/validate - 验证组织配置

### 风险点
- OAuth认证信息加密不当可能导致安全风险
- 配置验证逻辑复杂可能导致验证不准确
- 多环境配置管理复杂可能导致配置混乱
- 连接状态管理不当可能导致状态不一致

---

## 子需求 4: 元数据任务定义管理

### 需求信息
- **子需求编号**: REQ-010-4
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 高
- **预计工作量**: 5人天

### 需求描述
提供元数据任务定义的CRUD管理功能，支持配置拉取规则、package.xml内容、API版本、调度类型等。

### 功能范围
- 创建SfMetadataTaskService服务接口
- 创建SfMetadataTaskServiceImpl服务实现
- 创建SfMetadataTaskController控制器
- 实现任务定义的增删改查功能
- 实现package.xml内容配置
- 实现package.xml可视化编辑
- 实现API版本选择
- 实现调度类型选择（Manual/Cron）
- 实现Cron表达式配置
- 实现任务验证功能
- 实现任务查询接口

### 验收标准
- 能够成功创建元数据任务
- 能够成功编辑元数据任务
- 能够成功删除元数据任务
- 能够查询元数据任务列表
- package.xml内容配置成功
- package.xml格式符合Salesforce Metadata API规范
- 支持API版本选择
- 支持调度类型选择
- 支持Cron表达式配置
- 任务验证功能正常工作
- API接口符合RESTful规范
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-1, REQ-010-2, REQ-010-3
- **被依赖**: REQ-010-6, REQ-010-8

### 技术要点
- 使用XML解析库处理package.xml
- 使用Cron表达式解析库验证Cron表达式
- 使用枚举类型管理调度类型
- 使用@Valid注解进行参数验证
- 使用统一的异常处理机制
- 使用统一的响应格式
- 遵循RESTful API设计规范
- 使用事务管理保证数据一致性

### 数据库设计
使用REQ-010-1创建的datai_meta_task表

### API接口
- POST /api/metadata/task - 创建元数据任务
- PUT /api/metadata/task/{id} - 更新元数据任务
- DELETE /api/metadata/task/{id} - 删除元数据任务
- GET /api/metadata/task/{id} - 查询元数据任务详情
- GET /api/metadata/task - 查询元数据任务列表
- POST /api/metadata/task/{id}/validate - 验证元数据任务

### 风险点
- package.xml格式验证复杂可能导致验证不准确
- Cron表达式解析错误可能导致任务调度失败
- 任务验证逻辑复杂可能导致验证不准确
- 多任务管理复杂可能导致任务冲突

---

## 子需求 5: Metadata API客户端封装

### 需求信息
- **子需求编号**: REQ-010-5
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 高
- **预计工作量**: 5人天

### 需求描述
封装Salesforce Metadata API客户端，提供retrieve()和deploy()方法的调用接口，支持异步执行和状态轮询。

### 功能范围
- 创建MetadataApiClient客户端类
- 实现retrieve()方法调用
- 实现deploy()方法调用
- 实现异步执行机制
- 实现状态轮询机制
- 实现Job ID获取
- 实现Zip文件下载
- 实现部署结果解析
- 实现错误处理机制
- 集成SessionManager进行会话管理

### 验收标准
- MetadataApiClient创建成功
- retrieve()方法调用成功
- deploy()方法调用成功
- 异步执行机制正常工作
- 状态轮询机制正常工作
- Job ID获取成功
- Zip文件下载成功
- 部署结果解析成功
- 错误处理机制正常工作
- 与SessionManager集成成功
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-1, REQ-010-2
- **被依赖**: REQ-010-6, REQ-010-8

### 技术要点
- 使用Salesforce WSC (Web Service Connector)库
- 使用SessionManager获取当前会话
- 使用异步线程池执行长时间任务
- 使用轮询机制检查任务状态
- 使用HTTP客户端下载Zip文件
- 使用ZipInputStream处理Zip文件
- 使用JSON解析库处理API响应
- 使用统一的异常处理机制
- 遵循Salesforce Metadata API调用规范

### 数据库设计
无

### API接口
无（内部服务类）

### 风险点
- WSC库版本兼容性问题
- 异步执行机制复杂可能导致状态管理困难
- 状态轮询频率不当可能导致API限流
- Zip文件处理不当可能导致内存溢出
- 错误处理不完善可能导致任务失败无法恢复

---

## 子需求 6: 元数据拉取核心功能

### 需求信息
- **子需求编号**: REQ-010-6
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 高
- **预计工作量**: 5人天

### 需求描述
实现Salesforce元数据拉取的核心功能，使用Metadata API的retrieve()方法，支持异步执行、状态轮询、Zip文件下载。

### 功能范围
- 创建MetadataRetrieveService服务接口
- 创建MetadataRetrieveServiceImpl服务实现
- 创建MetadataRetrieveController控制器
- 实现手动触发拉取功能
- 实现异步拉取执行
- 实现状态监控（Pending/Processing/Success/Failed/Partial_Success）
- 实现拉取历史记录
- 实现拉取进度查询
- 实现拉取取消功能
- 集成MetadataApiClient
- 集成SessionManager

### 验收标准
- 能够成功手动触发拉取
- 异步拉取执行正常工作
- 状态监控正常工作
- 拉取历史记录成功
- 拉取进度查询成功
- 拉取取消功能正常工作
- 与MetadataApiClient集成成功
- 与SessionManager集成成功
- API接口符合RESTful规范
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-1, REQ-010-2, REQ-010-3, REQ-010-4, REQ-010-5
- **被依赖**: REQ-010-7, REQ-010-11, REQ-010-14, REQ-010-15

### 技术要点
- 使用MetadataApiClient调用retrieve()方法
- 使用异步线程池执行拉取任务
- 使用状态机管理拉取状态
- 使用轮询机制检查拉取状态
- 使用SessionManager获取当前会话
- 使用事务管理保证数据一致性
- 使用统一的异常处理机制
- 使用统一的响应格式
- 遵循RESTful API设计规范

### 数据库设计
使用REQ-010-1创建的datai_meta_job_execution表

### API接口
- POST /api/metadata/retrieve/{taskId} - 触发元数据拉取
- GET /api/metadata/retrieve/{jobId} - 查询拉取进度
- GET /api/metadata/retrieve/history - 查询拉取历史
- DELETE /api/metadata/retrieve/{jobId} - 取消拉取任务

### 风险点
- 异步执行机制复杂可能导致状态管理困难
- 状态轮询频率不当可能导致API限流
- 拉取取消功能复杂可能导致资源泄漏
- 拉取历史记录过多可能影响查询性能

---

## 子需求 7: 文件存储和解压处理

### 需求信息
- **子需求编号**: REQ-010-7
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 高
- **预计工作量**: 4人天

### 需求描述
实现拉取的Zip文件的存储和解压处理，支持OSS和本地文件系统存储，符合规范的目录结构。

### 功能范围
- 创建FileStorageService服务接口
- 创建FileStorageServiceImpl服务实现
- 实现Zip文件存储功能
- 实现Zip文件解压功能
- 实现文件哈希计算（MD5/SHA256）
- 实现文件数量统计
- 实现存储路径管理
- 支持OSS存储
- 支持本地文件系统存储
- 实现文件清理功能
- 集成MetadataRetrieveService

### 验收标准
- Zip文件存储成功
- Zip文件解压成功
- 文件哈希计算成功
- 文件数量统计成功
- 存储路径管理成功
- OSS存储功能正常工作
- 本地文件系统存储功能正常工作
- 文件清理功能正常工作
- 与MetadataRetrieveService集成成功
- 存储路径结构符合规范：/{org_name}/{task_name}/{job_id_timestamp}/src/
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-1, REQ-010-2, REQ-010-6
- **被依赖**: REQ-010-11, REQ-010-15

### 技术要点
- 使用ZipInputStream处理Zip文件
- 使用MessageDigest计算文件哈希
- 使用OSS SDK上传文件到OSS
- 使用File API操作本地文件系统
- 使用递归算法遍历文件目录
- 使用线程池并行处理文件
- 使用事务管理保证数据一致性
- 使用统一的异常处理机制

### 数据库设计
使用REQ-010-1创建的datai_meta_job_execution表和datai_meta_component表

### API接口
无（内部服务类）

### 风险点
- Zip文件处理不当可能导致内存溢出
- 文件哈希计算不当可能导致性能问题
- OSS存储不稳定可能导致文件丢失
- 文件清理不当可能导致误删重要文件
- 并发文件处理可能导致文件冲突

---

## 子需求 8: 元数据部署核心功能

### 需求信息
- **子需求编号**: REQ-010-8
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 高
- **预计工作量**: 5人天

### 需求描述
实现Salesforce元数据部署的核心功能，使用Metadata API的deploy()方法，支持异步执行、状态轮询、部署结果解析。

### 功能范围
- 创建MetadataDeployService服务接口
- 创建MetadataDeployServiceImpl服务实现
- 创建MetadataDeployController控制器
- 实现手动触发部署功能
- 实现异步部署执行
- 实现状态监控（Pending/Processing/Success/Failed/Partial_Success）
- 实现部署历史记录
- 实现部署进度查询
- 实现部署取消功能
- 实现部署选项配置（checkOnly、testLevel、runTests等）
- 集成MetadataApiClient
- 集成SessionManager

### 验收标准
- 能够成功手动触发部署
- 异步部署执行正常工作
- 状态监控正常工作
- 部署历史记录成功
- 部署进度查询成功
- 部署取消功能正常工作
- 部署选项配置成功
- 与MetadataApiClient集成成功
- 与SessionManager集成成功
- API接口符合RESTful规范
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-1, REQ-010-2, REQ-010-3, REQ-010-5
- **被依赖**: REQ-010-9, REQ-010-10, REQ-010-14, REQ-010-15, REQ-010-16

### 技术要点
- 使用MetadataApiClient调用deploy()方法
- 使用异步线程池执行部署任务
- 使用状态机管理部署状态
- 使用轮询机制检查部署状态
- 使用SessionManager获取当前会话
- 使用事务管理保证数据一致性
- 使用统一的异常处理机制
- 使用统一的响应格式
- 遵循RESTful API设计规范

### 数据库设计
使用REQ-010-1创建的datai_meta_deploy_history表

### API接口
- POST /api/metadata/deploy/{taskId} - 触发元数据部署
- GET /api/metadata/deploy/{jobId} - 查询部署进度
- GET /api/metadata/deploy/history - 查询部署历史
- DELETE /api/metadata/deploy/{jobId} - 取消部署任务

### 风险点
- 异步执行机制复杂可能导致状态管理困难
- 状态轮询频率不当可能导致API限流
- 部署取消功能复杂可能导致资源泄漏
- 部署历史记录过多可能影响查询性能
- 部署选项配置复杂可能导致配置错误

---

## 子需求 9: Quick Deploy功能实现

### 需求信息
- **子需求编号**: REQ-010-9
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 高
- **预计工作量**: 3人天

### 需求描述
实现Quick Deploy功能，使用ValidationID进行秒级部署，提高部署效率。

### 功能范围
- 实现ValidationID保存功能
- 实现Quick Deploy调用
- 实现ValidationID查询
- 实现Quick Deploy状态监控
- 实现Quick Deploy历史记录
- 集成MetadataDeployService
- 集成MetadataApiClient

### 验收标准
- ValidationID保存成功
- Quick Deploy调用成功
- ValidationID查询成功
- Quick Deploy状态监控成功
- Quick Deploy历史记录成功
- 与MetadataDeployService集成成功
- 与MetadataApiClient集成成功
- Quick Deploy能够在几秒内完成
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-8
- **被依赖**: REQ-010-16

### 技术要点
- 使用MetadataApiClient调用Quick Deploy
- 使用ValidationID进行快速部署
- 使用状态机管理Quick Deploy状态
- 使用轮询机制检查Quick Deploy状态
- 使用事务管理保证数据一致性
- 使用统一的异常处理机制

### 数据库设计
使用REQ-010-1创建的datai_meta_deploy_history表，添加validation_id字段

### API接口
- POST /api/metadata/deploy/quick/{validationId} - 触发Quick Deploy
- GET /api/metadata/deploy/validation/{jobId} - 查询ValidationID

### 风险点
- ValidationID过期可能导致Quick Deploy失败
- Quick Deploy状态监控复杂可能导致状态管理困难
- ValidationID查询不当可能导致查询失败

---

## 子需求 10: Destructive Changes功能实现

### 需求信息
- **子需求编号**: REQ-010-10
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 高
- **预计工作量**: 4人天

### 需求描述
实现Destructive Changes功能，支持删除Salesforce中的元数据（字段、类、对象等）。

### 功能范围
- 实现destructiveChanges.xml生成
- 实现destructiveChanges.xml解析
- 实现删除元数据功能
- 实现删除预览功能
- 实现删除历史记录
- 实现删除回滚功能
- 集成MetadataDeployService
- 集成MetadataApiClient

### 验收标准
- destructiveChanges.xml生成成功
- destructiveChanges.xml解析成功
- 删除元数据功能正常工作
- 删除预览功能正常工作
- 删除历史记录成功
- 删除回滚功能正常工作
- 与MetadataDeployService集成成功
- 与MetadataApiClient集成成功
- destructiveChanges.xml格式符合Salesforce Metadata API规范
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-8
- **被依赖**: REQ-010-16

### 技术要点
- 使用XML解析库处理destructiveChanges.xml
- 使用MetadataApiClient调用deploy()方法
- 使用状态机管理删除状态
- 使用轮询机制检查删除状态
- 使用事务管理保证数据一致性
- 使用统一的异常处理机制
- 遵循Salesforce Metadata API调用规范

### 数据库设计
使用REQ-010-1创建的datai_meta_deploy_history表

### API接口
- POST /api/metadata/deploy/destructive - 触发删除部署
- GET /api/metadata/deploy/destructive/preview - 预览删除内容
- GET /api/metadata/deploy/destructive/history - 查询删除历史

### 风险点
- destructiveChanges.xml格式错误可能导致删除失败
- 删除操作不可逆可能导致数据丢失
- 删除回滚功能复杂可能导致回滚失败
- 删除预览功能不准确可能导致误删

---

## 子需求 11: 元数据组件索引和查询

### 需求信息
- **子需求编号**: REQ-010-11
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 中
- **预计工作量**: 4人天

### 需求描述
实现元数据组件的结构化存储和查询功能，支持按类型、名称、Job ID等多维度查询。

### 功能范围
- 创建SfMetadataComponentService服务接口
- 创建SfMetadataComponentServiceImpl服务实现
- 创建SfMetadataComponentController控制器
- 实现组件详情查询
- 实现按Job ID查询组件列表
- 实现按组件类型查询
- 实现按组件名称查询
- 实现组件分页查询
- 实现组件统计功能
- 集成FileStorageService

### 验收标准
- 组件详情查询成功
- 按Job ID查询组件列表成功
- 按组件类型查询成功
- 按组件名称查询成功
- 组件分页查询成功
- 组件统计功能正常工作
- 与FileStorageService集成成功
- API接口符合RESTful规范
- 查询性能满足要求
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-1, REQ-010-2, REQ-010-7
- **被依赖**: REQ-010-12, REQ-010-13

### 技术要点
- 使用MyBatis Plus的QueryWrapper构建查询条件
- 使用分页插件实现分页查询
- 使用聚合查询实现统计功能
- 使用索引优化查询性能
- 使用统一的异常处理机制
- 使用统一的响应格式
- 遵循RESTful API设计规范

### 数据库设计
使用REQ-010-1创建的datai_meta_component表

### API接口
- GET /api/metadata/component/{id} - 查询组件详情
- GET /api/metadata/component/job/{jobId} - 按Job ID查询组件列表
- GET /api/metadata/component/type/{type} - 按组件类型查询
- GET /api/metadata/component/name/{name} - 按组件名称查询
- GET /api/metadata/component - 分页查询组件
- GET /api/metadata/component/statistics - 组件统计

### 风险点
- 查询条件复杂可能导致SQL性能问题
- 分页查询不当可能导致内存溢出
- 组件统计功能复杂可能导致统计不准确
- 索引设计不当可能影响查询性能

---

## 子需求 12: 文件哈希对比和增量检测

### 需求信息
- **子需求编号**: REQ-010-12
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 中
- **预计工作量**: 4人天

### 需求描述
实现文件哈希对比功能，通过对比datai_meta_component表的哈希值，实现增量检测和变更分析。

### 功能范围
- 实现哈希值对比算法
- 实现增量检测功能
- 实现变更分析功能
- 实现变更统计（新增、修改、删除）
- 实现变更报告生成
- 实现变更历史查询
- 集成SfMetadataComponentService
- 集成FileStorageService

### 验收标准
- 哈希值对比算法正确
- 增量检测功能正常工作
- 变更分析功能正常工作
- 变更统计功能正常工作
- 变更报告生成成功
- 变更历史查询成功
- 与SfMetadataComponentService集成成功
- 与FileStorageService集成成功
- 增量检测性能满足要求
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-11
- **被依赖**: REQ-010-13

### 技术要点
- 使用MessageDigest计算文件哈希
- 使用哈希值对比算法检测变更
- 使用集合操作计算差异（新增、修改、删除）
- 使用递归算法遍历文件目录
- 使用线程池并行处理文件
- 使用事务管理保证数据一致性
- 使用统一的异常处理机制

### 数据库设计
使用REQ-010-1创建的datai_meta_component表

### API接口
- POST /api/metadata/component/compare - 对比两次Job的差异
- GET /api/metadata/component/increment/{jobId} - 查询增量变更
- GET /api/metadata/component/change-report/{jobId} - 生成变更报告
- GET /api/metadata/component/change-history - 查询变更历史

### 风险点
- 哈希值对比算法不当可能导致检测不准确
- 增量检测复杂可能导致性能问题
- 变更分析复杂可能导致分析不准确
- 变更报告生成复杂可能导致报告不完整

---

## 子需求 13: 版本回溯功能

### 需求信息
- **子需求编号**: REQ-010-13
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 中
- **预计工作量**: 4人天

### 需求描述
实现版本回溯功能，支持查询历史版本的元数据组件，并支持恢复到指定版本。

### 功能范围
- 实现历史版本查询
- 实现版本对比功能
- 实现版本恢复功能
- 实现版本预览功能
- 实现版本标签管理
- 实现版本历史导出
- 集成SfMetadataComponentService
- 集成FileStorageService

### 验收标准
- 历史版本查询成功
- 版本对比功能正常工作
- 版本恢复功能正常工作
- 版本预览功能正常工作
- 版本标签管理成功
- 版本历史导出成功
- 与SfMetadataComponentService集成成功
- 与FileStorageService集成成功
- 版本回溯性能满足要求
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-11, REQ-010-12
- **被依赖**: REQ-010-16

### 技术要点
- 使用时间戳标识版本
- 使用哈希值对比算法对比版本
- 使用文件复制算法恢复版本
- 使用递归算法遍历文件目录
- 使用线程池并行处理文件
- 使用事务管理保证数据一致性
- 使用统一的异常处理机制

### 数据库设计
使用REQ-010-1创建的datai_meta_component表

### API接口
- GET /api/metadata/component/version/{jobId} - 查询历史版本
- POST /api/metadata/component/compare - 对比两个版本
- POST /api/metadata/component/restore/{jobId} - 恢复到指定版本
- GET /api/metadata/component/preview/{jobId} - 预览指定版本
- POST /api/metadata/component/tag - 添加版本标签
- GET /api/metadata/component/export/{jobId} - 导出版本历史

### 风险点
- 版本恢复不当可能导致数据覆盖
- 版本对比复杂可能导致对比不准确
- 版本预览功能复杂可能导致预览不完整
- 版本标签管理复杂可能导致标签混乱

---

## 子需求 14: 作业执行监控

### 需求信息
- **子需求编号**: REQ-010-14
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 中
- **预计工作量**: 3人天

### 需求描述
实现作业执行监控功能，实时监控拉取和部署操作的执行状态、进度和结果。

### 功能范围
- 创建JobMonitorService服务接口
- 创建JobMonitorServiceImpl服务实现
- 创建JobMonitorController控制器
- 实现实时状态监控
- 实现进度查询
- 实现执行统计（成功率、平均耗时等）
- 实现告警功能
- 实现监控大屏展示
- 集成MetadataRetrieveService
- 集成MetadataDeployService

### 验收标准
- 实时状态监控正常工作
- 进度查询成功
- 执行统计功能正常工作
- 告警功能正常工作
- 监控大屏展示成功
- 与MetadataRetrieveService集成成功
- 与MetadataDeployService集成成功
- 监控数据实时性满足要求
- API接口符合RESTful规范
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-6, REQ-010-8
- **被依赖**: REQ-010-15

### 技术要点
- 使用WebSocket实现实时推送
- 使用定时任务统计执行数据
- 使用缓存提高查询性能
- 使用告警规则引擎实现告警
- 使用图表库展示监控数据
- 使用统一的异常处理机制
- 使用统一的响应格式
- 遵循RESTful API设计规范

### 数据库设计
使用REQ-010-1创建的datai_meta_job_execution表和datai_meta_deploy_history表

### API接口
- GET /api/metadata/monitor/status - 查询实时状态
- GET /api/metadata/monitor/progress/{jobId} - 查询执行进度
- GET /api/metadata/monitor/statistics - 查询执行统计
- POST /api/metadata/monitor/alert - 配置告警规则
- GET /api/metadata/monitor/dashboard - 监控大屏数据

### 风险点
- 实时推送频率不当可能导致性能问题
- 监控数据量大可能导致查询缓慢
- 告警规则复杂可能导致告警不准确
- 监控大屏展示复杂可能导致展示不完整

---

## 子需求 15: 详细日志记录和查询

### 需求信息
- **子需求编号**: REQ-010-15
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 中
- **预计工作量**: 4人天

### 需求描述
实现详细日志记录功能，记录拉取和部署操作的详细执行步骤（鉴权成功→开始下载→解压完成→上传OSS完成）。

### 功能范围
- 创建JobLogService服务接口
- 创建JobLogServiceImpl服务实现
- 创建JobLogController控制器
- 实现详细日志记录
- 实现日志查询
- 实现日志分页
- 实现日志导出
- 实现日志详情查看
- 实现日志统计
- 集成MetadataRetrieveService
- 集成MetadataDeployService
- 集成FileStorageService

### 验收标准
- 详细日志记录成功
- 日志查询成功
- 日志分页成功
- 日志导出成功
- 日志详情查看成功
- 日志统计功能正常工作
- 与MetadataRetrieveService集成成功
- 与MetadataDeployService集成成功
- 与FileStorageService集成成功
- 日志记录完整性满足要求
- API接口符合RESTful规范
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-1, REQ-010-2, REQ-010-6, REQ-010-7, REQ-010-8
- **被依赖**: REQ-010-16

### 技术要点
- 使用AOP切面记录日志
- 使用异步日志写入提高性能
- 使用分页插件实现分页查询
- 使用Excel导出库实现日志导出
- 使用日志分析库实现日志统计
- 使用事务管理保证数据一致性
- 使用统一的异常处理机制
- 使用统一的响应格式
- 遵循RESTful API设计规范

### 数据库设计
使用REQ-010-1创建的datai_meta_job_log表

### API接口
- POST /api/metadata/log - 记录日志
- GET /api/metadata/log/{id} - 查询日志详情
- GET /api/metadata/log/job/{jobId} - 按Job ID查询日志
- GET /api/metadata/log - 分页查询日志
- GET /api/metadata/log/export - 导出日志
- GET /api/metadata/log/statistics - 日志统计

### 风险点
- 日志记录过多可能影响性能
- 日志导出复杂可能导致内存溢出
- 日志统计复杂可能导致统计不准确
- 异步日志写入可能导致日志丢失

---

## 子需求 16: 异常处理机制完善

### 需求信息
- **子需求编号**: REQ-010-16
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 中
- **预计工作量**: 4人天

### 需求描述
完善拉取和部署操作的异常处理机制，确保操作的可靠性，支持Session过期处理、API限制处理、网络异常处理等。

### 功能范围
- 创建MetadataExceptionHandler异常处理器
- 实现Session过期自动重新登录
- 实现API限制处理
- 实现网络异常重试
- 实现常见部署错误分类和解析
- 实现异常信息详细记录
- 实现异常告警
- 实现异常统计
- 集成SessionManager
- 集成MetadataRetrieveService
- 集成MetadataDeployService

### 验收标准
- Session过期自动重新登录成功
- API限制处理正常工作
- 网络异常重试成功
- 常见部署错误分类和解析成功
- 异常信息详细记录成功
- 异常告警功能正常工作
- 异常统计功能正常工作
- 与SessionManager集成成功
- 与MetadataRetrieveService集成成功
- 与MetadataDeployService集成成功
- 异常处理覆盖率满足要求
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-6, REQ-010-8, REQ-010-9, REQ-010-10, REQ-010-13, REQ-010-15
- **被依赖**: REQ-010-17

### 技术要点
- 使用@ExceptionHandler注解处理异常
- 使用重试机制处理网络异常
- 使用限流算法处理API限制
- 使用错误码分类解析部署错误
- 使用告警规则引擎实现异常告警
- 使用事务管理保证数据一致性
- 使用统一的异常处理机制
- 使用统一的响应格式

### 数据库设计
使用REQ-010-1创建的datai_meta_job_execution表和datai_meta_deploy_history表

### API接口
无（内部异常处理）

### 风险点
- 异常处理逻辑复杂可能导致处理不准确
- 重试机制不当可能导致重复操作
- API限制处理复杂可能导致限流不准确
- 异常告警规则复杂可能导致告警不准确

---

## 子需求 17: 性能优化和限流处理

### 需求信息
- **子需求编号**: REQ-010-17
- **父需求**: REQ-010
- **需求类型**: 功能需求
- **优先级**: 中
- **预计工作量**: 4人天

### 需求描述
实现性能优化和限流处理，确保系统在大规模元数据操作时的稳定性和性能。

### 功能范围
- 实现API调用限流
- 实现并发控制
- 实现缓存优化
- 实现数据库查询优化
- 实现文件处理优化
- 实现异步任务优化
- 实现性能监控
- 实现性能报告生成
- 集成MetadataRetrieveService
- 集成MetadataDeployService

### 验收标准
- API调用限流正常工作
- 并发控制正常工作
- 缓存优化有效提高性能
- 数据库查询优化有效提高性能
- 文件处理优化有效提高性能
- 异步任务优化有效提高性能
- 性能监控正常工作
- 性能报告生成成功
- 与MetadataRetrieveService集成成功
- 与MetadataDeployService集成成功
- 系统性能满足要求
- 代码符合项目架构规范

### 依赖关系
- **前置依赖**: REQ-010-16
- **被依赖**: 无

### 技术要点
- 使用令牌桶算法实现限流
- 使用线程池实现并发控制
- 使用Redis实现缓存
- 使用索引优化数据库查询
- 使用流式处理优化文件处理
- 使用异步任务队列优化异步任务
- 使用性能监控工具监控性能
- 使用性能分析工具分析性能瓶颈

### 数据库设计
无

### API接口
- GET /api/metadata/performance/monitor - 性能监控数据
- GET /api/metadata/performance/report - 性能报告
- POST /api/metadata/performance/configure - 配置性能参数

### 风险点
- 限流算法复杂可能导致限流不准确
- 并发控制复杂可能导致资源竞争
- 缓存策略不当可能导致缓存不一致
- 性能优化复杂可能导致优化效果不明显

---

## 子需求依赖关系图

```
REQ-010-1 (数据库表结构)
    ↓
REQ-010-2 (实体类和Mapper)
    ↓
    ├→ REQ-010-3 (组织配置管理)
    │       ↓
    │       ├→ REQ-010-4 (任务定义管理)
    │       │       ↓
    │       │       ├→ REQ-010-6 (元数据拉取)
    │       │       │       ↓
    │       │       │       ├→ REQ-010-7 (文件存储和解压)
    │       │       │       │       ↓
    │       │       │       │       ├→ REQ-010-11 (组件索引和查询)
    │       │       │       │       │       ↓
    │       │       │       │       │       ├→ REQ-010-12 (哈希对比和增量检测)
    │       │       │       │       │       │       ↓
    │       │       │       │       │       │       └→ REQ-010-13 (版本回溯)
    │       │       │       │       │       │               ↓
    │       │       │       │       │       │               └→ REQ-010-16 (异常处理)
    │       │       │       │       │       ↓                       ↓
    │       │       │       │       │       └→ REQ-010-14 (作业执行监控)  └→ REQ-010-17 (性能优化)
    │       │       │       │               ↓
    │       │       │       │               └→ REQ-010-15 (详细日志)
    │       │       │       ↓                       ↓
    │       │       │       └→ REQ-010-15 (详细日志)  └→ REQ-010-16 (异常处理)
    │       │       ↓
    │       └→ REQ-010-5 (Metadata API客户端封装)
    │               ↓
    │               ├→ REQ-010-6 (元数据拉取)
    │               └→ REQ-010-8 (元数据部署)
    │                       ↓
    │                       ├→ REQ-010-9 (Quick Deploy)
    │                       └→ REQ-010-10 (Destructive Changes)
    │                               ↓
    │                               └→ REQ-010-16 (异常处理)
    ↓
    └→ REQ-010-8 (元数据部署)
            ↓
            ├→ REQ-010-14 (作业执行监控)
            └→ REQ-010-15 (详细日志)
```

## 子需求优先级排序

### 第一批（高优先级，无依赖）
1. REQ-010-1: 数据库表结构设计和创建
2. REQ-010-2: 基础实体类和Mapper创建

### 第二批（高优先级，依赖第一批）
3. REQ-010-3: Salesforce组织配置管理
4. REQ-010-5: Metadata API客户端封装

### 第三批（高优先级，依赖第二批）
5. REQ-010-4: 元数据任务定义管理
6. REQ-010-6: 元数据拉取核心功能
7. REQ-010-8: 元数据部署核心功能

### 第四批（高优先级，依赖第三批）
8. REQ-010-7: 文件存储和解压处理
9. REQ-010-9: Quick Deploy功能实现
10. REQ-010-10: Destructive Changes功能实现

### 第五批（中优先级，依赖第四批）
11. REQ-010-11: 元数据组件索引和查询
12. REQ-010-14: 作业执行监控
13. REQ-010-15: 详细日志记录和查询

### 第六批（中优先级，依赖第五批）
14. REQ-010-12: 文件哈希对比和增量检测
15. REQ-010-16: 异常处理机制完善

### 第七批（中优先级，依赖第六批）
16. REQ-010-13: 版本回溯功能
17. REQ-010-17: 性能优化和限流处理

## 总体工作量估算

| 批次 | 子需求 | 工作量（人天） |
|------|--------|----------------|
| 第一批 | REQ-010-1, REQ-010-2 | 7 |
| 第二批 | REQ-010-3, REQ-010-5 | 10 |
| 第三批 | REQ-010-4, REQ-010-6, REQ-010-8 | 15 |
| 第四批 | REQ-010-7, REQ-010-9, REQ-010-10 | 11 |
| 第五批 | REQ-010-11, REQ-010-14, REQ-010-15 | 11 |
| 第六批 | REQ-010-12, REQ-010-16 | 8 |
| 第七批 | REQ-010-13, REQ-010-17 | 8 |
| **总计** | **17个子需求** | **70人天** |

## 验收标准总结

### 完整性检查
- ✅ 所有子需求覆盖REQ-010的所有功能点
- ✅ 每个子需求都有明确的范围和边界
- ✅ 每个子需求都包含完整的CRUD操作

### 独立性检查
- ✅ 每个子需求都可以独立开发
- ✅ 每个子需求都可以独立测试
- ✅ 每个子需求都可以独立部署

### 可追溯性检查
- ✅ 每个子需求都能追溯到REQ-010的具体需求项
- ✅ 每个子需求都引用了相关的参考资料

### 可测试性检查
- ✅ 每个子需求都有清晰的验收标准
- ✅ 每个子需求的验收标准都是可测试的
- ✅ 每个子需求都有明确的交付物

### 可行性检查
- ✅ 每个子需求的工作量评估合理（3-5人天）
- ✅ 每个子需求的技术方案都是可行的
- ✅ 每个子需求都符合现有的项目架构

### 依赖关系检查
- ✅ 子需求之间的依赖关系清晰明确
- ✅ 没有循环依赖
- ✅ 优先级排序合理

## 风险总结

### 拆分粒度风险
- **风险**: 子需求拆分过细或过粗，影响开发效率
- **缓解**: 控制每个子需求的工作量在3-5人天

### 依赖关系风险
- **风险**: 子需求之间的依赖关系不清晰，导致开发阻塞
- **缓解**: 绘制依赖关系图，明确依赖关系

### 工作量评估风险
- **风险**: 工作量评估不准确，影响项目进度
- **缓解**: 参考类似项目的经验，预留缓冲时间

### 技术方案风险
- **风险**: 某些子需求的技术方案可能存在技术难点
- **缓解**: 提前进行技术预研，识别技术难点

### 优先级风险
- **风险**: 子需求的优先级排序不合理，影响整体进度
- **缓解**: 按依赖关系和业务价值排序优先级

## 下一步行动

1. **评审子需求拆分文档**: 组织团队评审子需求拆分的合理性
2. **调整子需求**: 根据评审结果调整子需求的范围和优先级
3. **制定开发计划**: 根据子需求的优先级和依赖关系制定开发计划
4. **分配开发资源**: 根据子需求的工作量分配开发资源
5. **开始开发**: 按照优先级顺序开始开发子需求