# API 文档 - 元数据类型定义

## 元数据
- 需求编号：003-02
- 创建时间：2026-02-03
- 创建人：AI Assistant
- 版本号：v1.0.0

## API 概述
元数据类型定义 API 提供 7 种 Salesforce 元数据类型的部署功能，包括自定义对象、自定义字段、Apex 类、Apex 触发器、Visualforce 页面、Visualforce 组件、Flow。同时提供部署日志查询功能，用于查看历史部署记录。

## 接口列表

### 1. 部署自定义对象
- **功能描述**：将自定义对象定义部署到 Salesforce 组织
- **请求方式**：POST
- **请求路径**：`/salesforce/metadata/type/customObject`
- **权限要求**：`metadata:type:deploy`
- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | customObject | Object | 是 | 自定义对象定义，包含 fullName、label、pluralLabel、fields 等属性 |
  | deployOptions | Object | 是 | 部署选项，包含 allowMissingFiles、autoUpdatePackage、checkOnly 等属性 |

- **请求示例**：
  ```json
  {
    "customObject": {
      "fullName": "MyCustomObject__c",
      "label": "My Custom Object",
      "pluralLabel": "My Custom Objects",
      "nameField": {
        "type": "Text",
        "label": "Name"
      }
    },
    "deployOptions": {
      "allowMissingFiles": false,
      "autoUpdatePackage": false,
      "checkOnly": false,
      "ignoreWarnings": false,
      "performRetrieve": false,
      "purgeOnDelete": false,
      "rollbackOnError": true,
      "singlePackage": true,
      "testLevel": "NoTestRun"
    }
  }
  ```

- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
  | data.success | Boolean | 是否成功 |
  | data.id | String | 部署 ID |
  | data.numberComponentErrors | Integer | 组件错误数 |
  | data.numberComponentsDeployed | Integer | 部署的组件数 |
  | data.numberTestErrors | Integer | 测试错误数 |
  | data.numberTestsCompleted | Integer | 完成的测试数 |
  | data.errorMessage | String | 错误消息（如果有） |

- **成功响应示例**：
  ```json
  {
    "code": 200,
    "msg": "部署自定义对象成功",
    "data": {
      "success": true,
      "id": "04sXXXXXXXXXXXXXXX",
      "numberComponentErrors": 0,
      "numberComponentsDeployed": 1,
      "numberTestErrors": 0,
      "numberTestsCompleted": 0
    }
  }
  ```

- **失败响应示例**：
  ```json
  {
    "code": 500,
    "msg": "部署自定义对象失败: 连接超时",
    "data": null
  }
  ```

### 2. 部署自定义字段
- **功能描述**：将自定义字段定义部署到 Salesforce 组织
- **请求方式**：POST
- **请求路径**：`/salesforce/metadata/type/customField`
- **权限要求**：`metadata:type:deploy`
- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | customField | Object | 是 | 自定义字段定义，包含 fullName、label、type、length 等属性 |
  | objectType | String | 是 | 对象类型，如 "Account"、"Contact"、"MyCustomObject__c" |
  | deployOptions | Object | 是 | 部署选项 |

- **请求示例**：
  ```json
  {
    "customField": {
      "fullName": "MyField__c",
      "label": "My Field",
      "type": "Text",
      "length": 255
    },
    "objectType": "Account",
    "deployOptions": {
      "checkOnly": false,
      "rollbackOnError": true,
      "testLevel": "NoTestRun"
    }
  }
  ```

- **响应参数**：同"部署自定义对象"接口

### 3. 部署 Apex 类
- **功能描述**：将 Apex 类部署到 Salesforce 组织
- **请求方式**：POST
- **请求路径**：`/salesforce/metadata/type/apexClass`
- **权限要求**：`metadata:type:deploy`
- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | apexClass | Object | 是 | Apex 类定义，包含 fullName、apiVersion、status、body 等属性 |
  | deployOptions | Object | 是 | 部署选项 |

- **请求示例**：
  ```json
  {
    "apexClass": {
      "fullName": "MyApexClass",
      "apiVersion": 58.0,
      "status": "Active",
      "body": "public class MyApexClass {\n    public static void myMethod() {\n        System.debug('Hello World');\n    }\n}"
    },
    "deployOptions": {
      "checkOnly": false,
      "rollbackOnError": true,
      "testLevel": "RunLocalTests"
    }
  }
  ```

- **响应参数**：同"部署自定义对象"接口

### 4. 部署 Apex 触发器
- **功能描述**：将 Apex 触发器部署到 Salesforce 组织
- **请求方式**：POST
- **请求路径**：`/salesforce/metadata/type/apexTrigger`
- **权限要求**：`metadata:type:deploy`
- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | apexTrigger | Object | 是 | Apex 触发器定义，包含 fullName、apiVersion、status、object、body 等属性 |
  | deployOptions | Object | 是 | 部署选项 |

- **请求示例**：
  ```json
  {
    "apexTrigger": {
      "fullName": "MyApexTrigger",
      "apiVersion": 58.0,
      "status": "Active",
      "object": "Account",
      "body": "trigger MyApexTrigger on Account (before insert) {\n    for (Account acc : Trigger.new) {\n        acc.Name = 'Updated';\n    }\n}"
    },
    "deployOptions": {
      "checkOnly": false,
      "rollbackOnError": true,
      "testLevel": "RunLocalTests"
    }
  }
  ```

- **响应参数**：同"部署自定义对象"接口

### 5. 部署 Visualforce 页面
- **功能描述**：将 Visualforce 页面部署到 Salesforce 组织
- **请求方式**：POST
- **请求路径**：`/salesforce/metadata/type/apexPage`
- **权限要求**：`metadata:type:deploy`
- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | apexPage | Object | 是 | Visualforce 页面定义，包含 fullName、apiVersion、label、markup 等属性 |
  | deployOptions | Object | 是 | 部署选项 |

- **请求示例**：
  ```json
  {
    "apexPage": {
      "fullName": "MyVisualforcePage",
      "apiVersion": 58.0,
      "label": "My Visualforce Page",
      "markup": "<apex:page>\n    <h1>Hello World</h1>\n</apex:page>"
    },
    "deployOptions": {
      "checkOnly": false,
      "rollbackOnError": true,
      "testLevel": "NoTestRun"
    }
  }
  ```

- **响应参数**：同"部署自定义对象"接口

### 6. 部署 Visualforce 组件
- **功能描述**：将 Visualforce 组件部署到 Salesforce 组织
- **请求方式**：POST
- **请求路径**：`/salesforce/metadata/type/apexComponent`
- **权限要求**：`metadata:type:deploy`
- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | apexComponent | Object | 是 | Visualforce 组件定义，包含 fullName、apiVersion、label、markup 等属性 |
  | deployOptions | Object | 是 | 部署选项 |

- **请求示例**：
  ```json
  {
    "apexComponent": {
      "fullName": "MyVisualforceComponent",
      "apiVersion": 58.0,
      "label": "My Visualforce Component",
      "markup": "<apex:component>\n    <h1>Component Content</h1>\n</apex:component>"
    },
    "deployOptions": {
      "checkOnly": false,
      "rollbackOnError": true,
      "testLevel": "NoTestRun"
    }
  }
  ```

- **响应参数**：同"部署自定义对象"接口

### 7. 部署 Flow
- **功能描述**：将 Flow 定义部署到 Salesforce 组织
- **请求方式**：POST
- **请求路径**：`/salesforce/metadata/type/flow`
- **权限要求**：`metadata:type:deploy`
- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | flow | Object | 是 | Flow 定义，包含 fullName、apiVersion、label、processType、start 等属性 |
  | deployOptions | Object | 是 | 部署选项 |

- **请求示例**：
  ```json
  {
    "flow": {
      "fullName": "MyFlow",
      "apiVersion": 58.0,
      "label": "My Flow",
      "processType": "AutoLaunchedFlow",
      "start": {
        "connector": {
          "targetReference": "myAction"
        }
      }
    },
    "deployOptions": {
      "checkOnly": false,
      "rollbackOnError": true,
      "testLevel": "NoTestRun"
    }
  }
  ```

- **响应参数**：同"部署自定义对象"接口

### 8. 查询部署日志
- **功能描述**：查询元数据部署操作的历史记录
- **请求方式**：GET
- **请求路径**：`/salesforce/metadata/type/logs`
- **权限要求**：`metadata:type:logs`
- **请求参数**：无

- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
  | data | Array | 部署日志列表 |
  | data[].id | Long | 日志 ID |
  | data[].operationType | String | 操作类型（DEPLOY_CUSTOM_OBJECT、DEPLOY_CUSTOM_FIELD 等） |
  | data[].metadataType | String | 元数据类型（CustomObject、CustomField 等） |
  | data[].metadataName | String | 元数据名称 |
  | data[].deployId | String | 部署 ID |
  | data[].status | String | 部署状态（Queued、InProgress、Succeeded、Failed、Cancelled、Timeout） |
  | data[].numberComponentErrors | Integer | 组件错误数 |
  | data[].numberComponentsDeployed | Integer | 部署的组件数 |
  | data[].numberTestErrors | Integer | 测试错误数 |
  | data[].numberTestsCompleted | Integer | 完成的测试数 |
  | data[].errorMessage | String | 错误消息 |
  | data[].operationTime | String | 操作时间（格式：yyyy-MM-dd HH:mm:ss） |

- **成功响应示例**：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": [
      {
        "id": 1,
        "operationType": "DEPLOY_CUSTOM_OBJECT",
        "metadataType": "CustomObject",
        "metadataName": "MyCustomObject__c",
        "deployId": "04sXXXXXXXXXXXXXXX",
        "status": "Succeeded",
        "numberComponentErrors": 0,
        "numberComponentsDeployed": 1,
        "numberTestErrors": 0,
        "numberTestsCompleted": 0,
        "operationTime": "2026-02-03 10:30:00"
      }
    ]
  }
  ```

## 错误码

| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 200 | 操作成功 | 无需处理 |
| 500 | 服务器内部错误 | 检查服务器日志，联系管理员 |
| 401 | 未授权 | 检查用户是否登录，是否有权限 |
| 403 | 禁止访问 | 检查用户是否有相应权限 |
| 404 | 资源不存在 | 检查请求路径是否正确 |
| 400 | 请求参数错误 | 检查请求参数是否符合要求 |
| 408 | 请求超时 | 检查网络连接，稍后重试 |

## 部署选项说明

### DeployOptions 参数

| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| allowMissingFiles | Boolean | false | 是否允许缺失文件 |
| autoUpdatePackage | Boolean | false | 是否自动更新包 |
| checkOnly | Boolean | false | 是否仅检查（不实际部署） |
| ignoreWarnings | Boolean | false | 是否忽略警告 |
| performRetrieve | Boolean | false | 是否执行检索 |
| purgeOnDelete | Boolean | false | 是否在删除时清除 |
| rollbackOnError | Boolean | true | 是否在错误时回滚 |
| runTests | String[] | null | 运行的测试列表 |
| singlePackage | Boolean | true | 是否为单包 |
| testLevel | String | "NoTestRun" | 测试级别（NoTestRun、RunSpecifiedTests、RunLocalTests、RunAllTestsInOrg） |

## 注意事项

1. **部署超时**：部署操作可能需要较长时间（最多 5 分钟），请确保客户端设置合理的超时时间。

2. **并发部署**：建议避免同时部署多个元数据，以免产生冲突。

3. **测试级别**：对于 Apex 类和触发器的部署，建议设置适当的测试级别（RunLocalTests 或 RunAllTestsInOrg）。

4. **错误处理**：部署失败时，请查看响应中的 errorMessage 字段获取详细错误信息。

5. **日志查询**：部署日志会异步记录，可能需要等待几秒钟才能查询到最新的部署记录。

## 相关文档
- [需求文档](../requirements/sub/2026-01-28-003-02-元数据类型定义.md)
- [设计文档](../design/2026-02-03-003-02-元数据类型定义-设计.md)
- [决策记录](../decisions/2026-02-03-003-02-ADR-元数据部署技术选型.md)
- [SQL 脚本](../sql/2026-02-03-003-02-元数据部署日志.sql)
- [提示词文档](../prompts/2026-02-03-003-02-prompt-元数据类型定义.md)
- [会话记录](../sessions/2026-02-03-003-02-session.md)
- [变更日志](../changelog/2026-02-03-003-02-changelog.md)
- [复盘文档](../retros/2026-02-03-003-02-retro.md)