kris/datai

Kris 2e6f087732 docs: 完成REQ-010-17和REQ-010-2的文档创建

- 完成REQ-010-17（性能优化和限流处理）的所有6个阶段
  - 创建ADR文档：0026-performance-optimization.md
  - 创建Prompt文档：027-performance-optimization.md
  - 创建会话记录：20260119-performance-optimization.md
  - 创建变更记录：20260119-performance-optimization.md
  - 创建复盘报告：20260119-performance-optimization-retro.md
  - 更新index.md和CHANGELOG.md

- 完成REQ-010-2（基础实体类和Mapper创建）的前3个阶段
  - 更新ADR文档：0011-entity-mapper-create.md
  - 创建Prompt文档：002-entity-mapper-create.md
  - 更新index.md

所有文档均按照SSOT方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。

2026-01-19 10:06:09 +08:00

41 KiB

Raw Blame History

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 (详细日志)

子需求优先级排序

第一批（高优先级，无依赖）

REQ-010-1: 数据库表结构设计和创建
REQ-010-2: 基础实体类和Mapper创建

第二批（高优先级，依赖第一批）

REQ-010-3: Salesforce组织配置管理
REQ-010-5: Metadata API客户端封装

第三批（高优先级，依赖第二批）

REQ-010-4: 元数据任务定义管理
REQ-010-6: 元数据拉取核心功能
REQ-010-8: 元数据部署核心功能

第四批（高优先级，依赖第三批）

REQ-010-7: 文件存储和解压处理
REQ-010-9: Quick Deploy功能实现
REQ-010-10: Destructive Changes功能实现

第五批（中优先级，依赖第四批）

REQ-010-11: 元数据组件索引和查询
REQ-010-14: 作业执行监控
REQ-010-15: 详细日志记录和查询

第六批（中优先级，依赖第五批）

REQ-010-12: 文件哈希对比和增量检测
REQ-010-16: 异常处理机制完善

第七批（中优先级，依赖第六批）

REQ-010-13: 版本回溯功能
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人天

依赖关系风险

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

工作量评估风险

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

技术方案风险

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

优先级风险

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

下一步行动

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

41 KiB Raw Blame History Unescape Escape

REQ-010 子需求拆分文档

文档信息

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

需求信息

需求描述

功能范围

验收标准

依赖关系

技术要点

数据库设计

API接口

风险点

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

需求信息

需求描述

功能范围

验收标准

依赖关系

技术要点

数据库设计

API接口

风险点

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

需求信息

需求描述

功能范围

验收标准

依赖关系

技术要点

数据库设计

API接口

风险点

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

需求信息

需求描述

功能范围

验收标准

依赖关系

技术要点

数据库设计

API接口

风险点

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

需求信息

需求描述

功能范围

验收标准

依赖关系

技术要点

数据库设计

API接口

风险点

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

需求信息

需求描述

功能范围

验收标准

依赖关系

技术要点

数据库设计

API接口

风险点

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

需求信息

需求描述

功能范围

验收标准

依赖关系

技术要点

数据库设计

API接口

风险点

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

需求信息

需求描述

功能范围

验收标准

依赖关系

技术要点

41 KiB

Raw Blame History