kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/requirements/2026-02-03-005-Apex模块代码存储重构.md

6.0 KiB
Raw Permalink Blame History

需求文档

元数据

  • 需求编号：005
  • 创建时间：2026-02-03
  • 创建人：AI Assistant
  • 状态：进行中
  • 优先级：高

需求概述

重构 Apex 模块（002），将所有涉及代码存储的子需求改为使用 datai-scene-file 模块进行文件存储，替代原有的数据库直接存储方式。通过集成 file 模块，实现代码文件的统一管理，支持多种存储方式（local、minio、oss），提升系统的可扩展性和灵活性。

目标

  1. 将 Apex 模块中所有涉及代码存储的子需求改为使用 file 模块存储
  2. 调整数据库表结构，将代码字段改为 file_path 字段
  3. 支持多种存储方式（local、minio、oss），默认使用 local，可通过配置切换
  4. 保持 API 接口不变，确保向后兼容
  5. 实现文件同步删除机制，防止孤立文件
  6. 建立 Apex 代码文件的唯一索引，确保文件管理的一致性

功能需求

核心功能

1. 数据库表结构调整

  • 将 datai_apex_wsdl_class 表的 class_code 字段改为 file_path 字段
  • 将 datai_apex_compile_history 表的代码相关字段改为 file_path 字段（如果有）
  • 将 datai_apex_test_result 表的代码相关字段改为 file_path 字段（如果有）
  • 将 datai_apex_code_coverage 表的代码相关字段改为 file_path 字段（如果有）
  • 为所有涉及文件存储的表添加 file_path 字段
  • 建立 Apex 代码文件的唯一索引（基于 file_path）

2. File 模块集成

  • 在 datai-salesforce-apex 模块中引入 datai-scene-file 依赖
  • 使用 FileOperateUtils 工具类进行文件上传和下载
  • 使用 StorageService 进行文件管理操作
  • 配置 file 模块的存储方式（默认 local）

3. 代码文件存储

  • WSDL 转换生成的 Apex 类代码存储到 file 模块
  • 文件路径命名规则：/apex/wsdl/{conversionId}/{className}.cls
  • 编译历史中的代码存储到 file 模块（如果有）
  • 测试结果中的代码存储到 file 模块（如果有）
  • 代码覆盖率相关的代码存储到 file 模块（如果有）

4. 代码文件下载

  • 从 file 模块读取文件内容
  • 保持现有 API 接口的响应格式不变
  • 支持单个文件下载
  • 支持批量文件下载（ZIP 格式）

5. 文件同步删除

  • 删除数据库记录时，同步删除 file 模块中的文件
  • 使用事务确保数据一致性
  • 提供文件清理机制，定期清理孤立文件

6. 存储方式配置

  • 支持通过数据库配置存储方式（local、minio、oss）
  • 默认使用 local 存储方式
  • 支持运行时动态切换存储方式
  • 存储方式切换后，已存储的文件无需迁移

次要功能

1. 文件唯一索引管理

  • 建立 Apex 代码文件的唯一索引
  • 所有文件的增删操作都需要更新该唯一索引
  • 防止重复文件存储

2. 文件访问日志

  • 记录文件上传、下载、删除操作
  • 记录操作时间、用户、文件路径等信息

3. 文件清理机制

  • 定期扫描数据库和 file 模块，发现孤立文件
  • 提供手动清理孤立文件的功能
  • 清理前进行确认，避免误删

非功能需求

性能要求

  • 文件上传和下载的响应时间保持现有水平
  • 支持大文件上传（如批量下载 ZIP 文件）
  • 文件存储不影响现有功能的性能

安全要求

  • 文件同步删除，防止数据泄露
  • 文件访问需要权限控制
  • 敏感代码文件需要加密存储（可选）

兼容性要求

  • API 接口保持不变，前端无需修改
  • 向后兼容，不影响现有功能
  • 支持多种存储方式（local、minio、oss）

可维护性要求

  • 代码结构清晰，易于理解和维护
  • 提供配置文件，方便调整存储方式
  • 提供日志记录，方便问题排查

技术约束

必须使用的框架或库

  • datai-scene-file: 使用 FileOperateUtils、StorageService 进行文件管理
  • datai-salesforce-apex: 现有 Apex 模块代码
  • MyBatis Plus: 用于数据库操作
  • Spring Boot: 用于依赖注入和配置管理

必须遵循的设计模式

  • Service 层模式：封装文件存储逻辑
  • 事务管理：确保数据库和文件操作的一致性
  • 配置化驱动：通过配置文件管理存储方式

必须继承的基类

  • 无特殊基类要求

数据库设计原则

  • 将代码字段改为 file_path 字段
  • 为 file_path 字段添加索引
  • 建立 Apex 代码文件的唯一索引

文件命名规则

  • WSDL 转换：/apex/wsdl/{conversionId}/{className}.cls
  • 编译历史：/apex/compile/{historyId}/{className}.cls（如果有）
  • 测试结果：/apex/test/{testId}/{className}.cls（如果有）
  • 代码覆盖率：/apex/coverage/{coverageId}/{className}.cls（如果有）

成功标准

  1. 功能完整性: 所有涉及代码存储的子需求都已改为使用 file 模块存储
  2. 数据库变更: 数据库表结构已调整，代码字段改为 file_path 字段
  3. API 兼容性: API 接口保持不变，前端无需修改
  4. 文件管理: 文件上传、下载、删除功能正常工作
  5. 存储方式: 支持多种存储方式（local、minio、oss），可通过配置切换
  6. 数据一致性: 文件同步删除机制正常工作，无孤立文件
  7. 唯一索引: Apex 代码文件的唯一索引已建立并正常工作
  8. 代码质量: 代码符合项目规范，无编译错误和警告
  9. 测试通过: 所有功能通过单元测试和集成测试

相关文档