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-07-session.md

5.0 KiB
Raw Blame History

会话记录 - 检查部署和检索状态

元数据

  • 需求编号：003-07
  • 需求名称：检查部署和检索状态
  • 开始时间：2026-02-03
  • 结束时间：2026-02-03
  • 当前阶段：阶段 4：数据库结构生成

阶段记录

阶段 1：需求定义

阶段 2：方案设计

  • 状态：已完成
  • 设计文档：2026-02-03-003-07-检查部署和检索状态-设计.md
  • 关键设计决策：
    1. 架构设计：采用分层架构（Controller → Service → Repository → Metadata API），复用 003-01 的连接管理
    2. 核心功能：
      • 检查部署状态：checkDeployStatus(asyncId, includeDetails) → DeployResult
      • 检查检索状态：checkRetrieveStatus(asyncId, includeDetails) → RetrieveResult
    3. 技术选型：
      • Spring Boot 2.7.x (配合若依框架)
      • MyBatis Plus 3.5.x 进行数据库交互
      • Salesforce Metadata API (WSC/Partner JAR)
      • MySQL 8.0 数据库
    4. 数据模型：创建 datai_metadata_status_check 表，包含 8 个字段
      • 字段：check_id, async_id, operation_type, status, check_time, error_message, created_by, create_time
      • 关联表更新：同步更新 datai_metadata_deploy 和 datai_metadata_retrieve 表的状态
    5. 核心算法：
      • 状态检查：调用 connection.checkDeployStatus(asyncId) 或 connection.checkRetrieveStatus(asyncId) → 获取结果 → 更新关联表 → 记录检查历史
      • 数据同步：根据 asyncId 查询本地记录 → 更新状态、完成时间、错误信息等字段
      • 审计日志：每次检查结果写入 datai_metadata_status_check 表
    6. 接口设计：2 个 REST API 接口
      • GET /metadata/deploy/{asyncId}/status?includeDetails={boolean} - 检查部署状态
      • GET /metadata/retrieve/{asyncId}/status?includeDetails={boolean} - 检查检索状态
    7. 实体类设计：
      • MetadataStatusCheckEntity：状态检查记录实体
      • 复用 MetadataDeployEntity 和 MetadataRetrieveEntity 进行关联表更新
    8. 异常处理：
      • 捕获 ConnectionException，转换为 SalesforceOperationException
      • 即使 API 调用失败，也要记录检查失败的日志到 datai_metadata_status_check
    9. 性能优化：
      • 支持轻量级调用（includeDetails=false），仅在需要详细错误信息时开启详情
      • 数据库更新操作使用事务，确保一致性
    10. 安全设计：
      • 验证 asyncId 的格式合法性
      • 基于 Spring Security 确保只有授权用户可以查询状态

阶段 3：方案决策

  • 状态：已完成
  • 决策文档：2026-02-03-003-07-ADR-检查部署和检索状态技术选型.md
  • 关键决策：
    1. 状态检查机制：主动查询 (Active Polling)
      • 理由：Metadata API 不支持 Webhook，主动查询是官方推荐的标准做法
    2. 轮询策略：复用服务端同步轮询 (Server-side Synchronous Polling)
      • 理由：保持一致性，简化客户端，复用 ADR-003-04 的轮询策略
    3. 数据存储与审计：独立审计表 + 主表状态同步
      • 理由：可追溯性（排查操作卡住或失败的原因），数据完整性（主表展示最新状态，审计表展示过程）

阶段 4：数据库结构生成

  • 状态：已完成
  • 涉及数据库变更：是
  • SQL 脚本：2026-02-03-003-07-状态检查日志.sql
  • 数据库变更内容：
    1. 创建表：datai_metadata_status_check
      • 12 个字段：id, check_id, async_id, operation_type, status, check_time, error_message, create_by, create_time, update_by, update_time, del_flag
      • 6 个索引：idx_check_id, idx_async_id, idx_operation_type, idx_status, idx_check_time, idx_create_time
      • 字符集：utf8mb4
      • 存储引擎：InnoDB

待完成阶段

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

相关文档