kris/datai

Fork 0

Kris e86a497693 feat：Apex、Metadata、Partner初步

2026-02-03 16:51:09 +08:00

5.8 KiB

Raw Permalink Blame History

设计文档

元数据

需求编号：003
子需求编号：003-01
创建时间：2026-02-02
创建人：AI Assistant
状态：进行中

设计概述

本设计文档描述 Metadata API 连接管理的实现方案，面向 source org 的连接创建、会话头管理与调用选项配置。设计目标是基于 datai-salesforce-auth 的 SessionManager 与 AbstractConnectionFactory，提供可复用、可缓存的 MetadataConnection，并提供 REST API 进行连接状态与生命周期操作。

架构设计

系统架构

graph TB
    subgraph "Controller 层"
        A[MetadataConnectionController]
    end

    subgraph "Service 层"
        B[MetadataConnectionService]
    end

    subgraph "Factory 层"
        C[MetadataConnectionFactory]
    end

    subgraph "Auth 模块"
        D[SessionManager]
        E[AbstractConnectionFactory]
    end

    subgraph "Common 模块"
        F[SalesforceConstants]
        G[异常体系]
    end

    subgraph "Salesforce Metadata API"
        H[Connector]
        I[MetadataConnection]
    end

    A --> B
    B --> C
    C --> D
    C --> E
    C --> F
    B --> G
    H --> I
    C --> H

模块架构

datai-salesforce-metadata/
├── controller
│   └── MetadataConnectionController.java
├── service
│   ├── IMetadataConnectionService.java
│   └── impl
│       └── MetadataConnectionServiceImpl.java
├── factory
│   └── MetadataConnectionFactory.java
├── mapper
│   └── DataiMetadataConnectionMapper.java
├── model
│   ├── domain
│   │   └── DataiMetadataConnection.java
│   ├── dto
│   │   └── SetCallOptionsDto.java
│   └── vo
│       └── ConnectionStatusVo.java
└── config
    └── MetadataConnectionConfig.java

数据流设计

Client
  │
  ▼
MetadataConnectionController
  │
  ▼
MetadataConnectionService
  │
  ▼
MetadataConnectionFactory
  │
  ▼
SessionManager -> Salesforce Metadata API

技术方案

技术选型

技术组件	版本/类型	选择理由
Spring Boot	2.7.x	与现有模块一致，提供 REST API 支持
Spring Web	2.7.x	控制器层基础能力
Spring Security	5.x	接口权限控制
MyBatis Plus	3.x	数据持久化与实体建模
force-wsc	58.0.0	Salesforce WSC 基础库
Salesforce Metadata API	metadata.jar	官方 Metadata API 客户端
Lombok	1.18.x	简化实体与 DTO

连接创建方案

固定使用 source orgType 获取 Session ID 与 Server URL
使用 Connector 创建 MetadataConnection
设置 SessionHeader 与 CallOptions
通过 AbstractConnectionFactory 进行连接缓存与刷新

异常处理方案

Session 失效与未授权统一转化为 SalesforceAuthException
连接创建失败与远程调用异常转化为 SalesforceOperationException
统一在 Service 层记录连接状态与错误信息

数据模型

数据库表设计

表名：datai_metadata_connection

字段名	类型	说明
id	BIGINT	主键
status	VARCHAR(50)	连接状态
error_message	TEXT	错误消息
connect_time	DATETIME	连接时间
user_id	VARCHAR(50)	用户 ID

索引：

idx_status：status
idx_connect_time：connect_time

实体类设计

DataiMetadataConnection

字段	类型	说明
id	Long	主键
status	String	连接状态
errorMessage	String	错误消息
connectTime	LocalDateTime	连接时间
userId	String	用户 ID

接口设计

RESTful API 设计

接口	HTTP 方法	URL	功能
获取连接状态	GET	/api/metadata/connection/status	获取连接状态
测试连接	POST	/api/metadata/connection/test	测试连接可用性
刷新连接	POST	/api/metadata/connection/refresh	刷新连接缓存
关闭连接	POST	/api/metadata/connection/close	关闭并清理连接

接口权限设计

接口	权限标识	说明
获取连接状态	metadata:connection:status	读取连接状态
测试连接	metadata:connection:test	测试连接
刷新连接	metadata:connection:refresh	刷新连接
关闭连接	metadata:connection:close	关闭连接

接口响应模型

ConnectionStatusVo

字段	类型	说明
connected	boolean	是否已连接
timestamp	LocalDateTime	状态时间

实现要点

MetadataConnectionFactory 继承 AbstractConnectionFactory，固定 source orgType
通过 SessionManager 获取 Session ID 与 Server URL
连接创建成功后设置 SessionHeader 与 CallOptions
Service 层记录连接成功与失败状态到 datai_metadata_connection
Controller 层通过 AjaxResult 输出统一响应
异常统一映射为 SalesforceAuthException 与 SalesforceOperationException

实现详情

代码实现

MetadataConnectionFactory: com.datai.metadata.factory.MetadataConnectionFactory
IMetadataConnectionService: com.datai.metadata.service.IMetadataConnectionService
MetadataConnectionServiceImpl: com.datai.metadata.service.impl.MetadataConnectionServiceImpl
MetadataConnectionController: com.datai.metadata.controller.MetadataConnectionController
DataiMetadataConnection: com.datai.metadata.model.domain.DataiMetadataConnection
DataiMetadataConnectionMapper: com.datai.metadata.mapper.DataiMetadataConnectionMapper

状态

代码已生成，等待测试验证。

5.8 KiB Raw Permalink Blame History Unescape Escape