kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7f19f3c99c
datai/datai-scenes/datai-scene-salesforce/docs/sessions/2026-02-03-003-06-session.md

4.3 KiB
Raw Blame History

会话记录 - 检索操作

元数据

  • 需求编号：003-06
  • 需求名称：检索操作
  • 开始时间：2026-02-03
  • 结束时间：2026-02-03
  • 当前阶段：阶段 4：数据库结构生成

阶段记录

阶段 1：需求定义

阶段 2：方案设计

  • 状态：已完成
  • 设计文档：2026-02-03-003-06-检索操作-设计.md
  • 关键设计决策：
    1. 架构设计：采用分层架构（Controller → Service → Repository → Metadata API），复用 003-01 的连接管理
    2. 异步处理机制：由于检索操作通常较为耗时，采用"提交请求-轮询状态-获取结果"的异步流程
    3. 技术选型：
      • Spring Boot 2.7+ (配合若依框架)
      • MyBatis Plus 进行数据库交互
      • Salesforce Metadata API (WSC/Partner JAR)
      • MySQL 5.7+ 数据库
    4. 数据模型：创建 datai_metadata_retrieve 表，包含 9 个字段和 2 个索引
      • 字段：id, async_id, status, done, message, error_message, retrieve_time, update_time, user_id
      • 索引：idx_async_id, idx_retrieve_time
    5. 核心算法：
      • 提交检索：调用 connection.retrieve(request) → 获取 AsyncResult → 立即存入数据库 → 返回 AsyncResult
      • 轮询状态：循环调用 checkRetrieveStatus(asyncId) → 检查状态 → 更新数据库 → 返回结果或继续等待
      • 超时机制：设置 5 分钟超时，防止无限等待
    6. 接口设计：3 个 REST API 接口
      • POST /salesforce/metadata/retrieve - 提交检索请求
      • GET /salesforce/metadata/retrieve/{asyncId} - 获取检索状态/结果
      • GET /salesforce/metadata/retrieve/history - 获取检索历史
    7. 实体类设计：MetadataRetrieveEntity 使用 MyBatis Plus 注解映射数据库表
    8. 异常处理：
      • 捕获 ConnectionException，转换为 SalesforceAuthException 或 SalesforceOperationException
      • 即使 API 调用失败，也要尽可能记录失败状态到数据库
    9. 性能优化：
      • 长轮询策略：Controller 层实现长轮询或立即返回，由前端控制轮询间隔
      • ZIP 文件不存储到数据库，仅在 API 响应中返回
    10. 安全设计：
      • 验证 RetrieveRequest 中的包名和文件路径，防止非法访问
      • 记录操作用户 ID (userId)，确保审计可追溯

阶段 3：方案决策

  • 状态：已完成
  • 决策文档：2026-02-03-003-06-ADR-检索操作技术选型.md
  • 关键决策：
    1. ZIP 文件处理：不持久化到数据库，直接在 API 响应中返回
      • 理由：避免数据库性能问题，简化系统复杂度
    2. 状态管理：创建专用历史表 datai_metadata_retrieve
      • 理由：审计追踪，状态同步
    3. 架构模式：复用通用异步策略
      • 理由：保持一致性，简化客户端

阶段 4：数据库结构生成

  • 状态：已完成
  • 涉及数据库变更：是
  • SQL 脚本：2026-02-03-003-06-检索操作日志.sql
  • 数据库变更内容：
    1. 创建表：datai_metadata_retrieve
      • 13 个字段：id, async_id, status, done, message, error_message, retrieve_time, update_time, user_id, create_by, create_time, update_by, del_flag
      • 4 个索引：idx_async_id, idx_retrieve_time, idx_user_id, idx_create_time
      • 字符集：utf8mb4
      • 存储引擎：InnoDB

待完成阶段

  • 阶段 1：需求定义
  • 阶段 2：方案设计
  • 阶段 3：方案决策
  • 阶段 4：数据库结构生成
  • 阶段 5：提示词生成
  • 阶段 6：代码生成
  • 阶段 7：会话记录
  • 阶段 8：变更日志
  • 阶段 9：复盘和 API 文档
  • 阶段 10：代码提交

相关文档