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

6.3 KiB
Raw Blame History

会话记录 - 描述和列出元数据

元数据

  • 需求编号：003-08
  • 需求名称：描述和列出元数据
  • 开始时间：2026-02-03
  • 结束时间：2026-02-03
  • 当前阶段：阶段 4：数据库结构生成

阶段记录

阶段 1：需求定义

阶段 2：方案设计

  • 状态：已完成
  • 设计文档：2026-02-03-003-08-描述和列出元数据-设计.md
  • 关键设计决策：
    1. 架构设计：采用分层架构（Controller → Service → Repository → Metadata API），复用 003-01 的连接管理
    2. 核心功能：
      • 描述元数据：describeMetadata(apiVersion) → DescribeMetadataResult
      • 列出元数据：listMetadata(queries) → ListMetadataResult[]
    3. 技术选型：
      • Spring Boot 2.7+ (配合若依框架)
      • MyBatis Plus 进行数据库交互
      • Salesforce Metadata API (WSC/Partner JAR)
      • MySQL 8.0 数据库
    4. 数据模型：创建 datai_metadata_describe 表，包含 14 个字段和 2 个索引
      • 字段：id, operation_type, metadata_type, folder, server_version, namespace_prefix, metadata_object_count, result_count, status, error_message, query_time, user_id, create_time, created_by
      • 索引：idx_metadata_describe_op_type, idx_metadata_describe_time
    5. 核心算法：
      • 描述元数据：获取连接 → 调用 describeMetadata(apiVersion) → 记录元数据对象数量 → 保存审计日志 → 返回结果
      • 列出元数据：获取连接 → 处理批量查询（最多3个Query）→ 调用 listMetadata(queries) → 对每个Query记录审计日志 → 返回结果
    6. 接口设计：3 个 REST API 接口
      • GET /salesforce/metadata/describe?apiVersion={double} - 描述元数据
      • POST /salesforce/metadata/list - 列出元数据
      • GET /salesforce/metadata/describe/history - 查询历史
    7. 实体类设计：MetadataDescribeEntity 使用 MyBatis Plus 注解映射数据库表
    8. 异常处理：
      • 捕获 ConnectionException，转换为 SalesforceAuthException 或 SalesforceOperationException
      • 即使 API 调用失败，也要记录失败状态到数据库
    9. 性能优化：
      • 批量查询处理：Metadata API 限制每次调用最多3个Query，需要分批处理
      • 审计日志：对每个Query记录一条审计日志，保证审计细粒度
    10. 安全设计：
      • 接口需要鉴权（依赖 Spring Security / 若依框架）
      • 敏感信息（如 Session ID）不记录在日志或数据库中

阶段 3：方案决策

  • 状态：已完成
  • 决策记录：2026-02-03-003-08-ADR-描述和列出元数据技术选型.md
  • 关键决策：
    1. API 交互方式：直接调用 WSC (Web Service Connector)
      • 使用 MetadataConnection.describeMetadata() 和 MetadataConnection.listMetadata() 方法
      • 理由：类型安全，与项目其他模块保持一致
    2. ListMetadata 批处理策略：服务层自动分批
      • Service 层接收 List<ListMetadataQuery>，自动拆分为多个子列表（每组 3 个）
      • 理由：客户端无需关注 API 限制，提升用户体验
    3. 审计记录策略：同步数据库审计
      • 调用 API 后立即将查询信息写入 datai_metadata_describe 表
      • 理由：数据完整性，确保每次 API 调用都有据可查

阶段 4：数据库结构生成

  • 状态：已完成（重新生成）
  • 涉及数据库变更：是
  • SQL 脚本：2026-02-03-003-08-describe-metadata.sql
  • 重新生成时间：2026-02-04
  • 重新生成原因：原 SQL 文件丢失，重新进入阶段 4 生成
  • 数据库变更内容：
    1. 创建表 datai_metadata_describe
      • 用途：元数据查询审计表
      • 引擎：InnoDB
      • 字符集：utf8mb4
      • 字段数：18 个
      • 索引数：5 个
    2. 字段详情：
      • id (BIGINT, PRIMARY KEY, AUTO_INCREMENT) - 主键
      • operation_type (VARCHAR(20), NOT NULL) - 操作类型（describe/list）
      • metadata_type (VARCHAR(50)) - 元数据类型
      • folder (VARCHAR(255)) - 文件夹
      • server_version (VARCHAR(50)) - 服务器版本
      • namespace_prefix (VARCHAR(50)) - 命名空间前缀
      • metadata_object_count (INT, DEFAULT 0) - 元数据对象数量
      • result_count (INT, DEFAULT 0) - 结果数量
      • status (VARCHAR(50), NOT NULL) - 状态（Succeeded/Failed）
      • error_message (TEXT) - 错误信息
      • query_time (DATETIME, NOT NULL) - 查询时间
      • user_id (VARCHAR(50)) - 操作用户ID
      • create_time (DATETIME, NOT NULL, DEFAULT CURRENT_TIMESTAMP) - 创建时间
      • created_by (VARCHAR(64)) - 创建者
      • update_time (DATETIME, NOT NULL, DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP) - 更新时间
      • update_by (VARCHAR(64)) - 更新者
      • del_flag (TINYINT(1), DEFAULT 0) - 删除标志
    3. 索引设计：
      • idx_metadata_describe_op_type (operation_type) - 按操作类型查询
      • idx_metadata_describe_time (query_time) - 按查询时间查询
      • idx_metadata_describe_type (metadata_type) - 按元数据类型查询
      • idx_metadata_describe_user (user_id) - 按操作用户查询
      • idx_metadata_describe_status (status) - 按状态查询

待完成阶段

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

相关文档