# API 文档：AI 和智能功能

## 元数据
- **需求编号**: 004-04
- **文档版本**: v1.0.0
- **创建时间**: 2026-02-05
- **创建人**: AI Assistant
- **关联需求**: [AI 和智能功能](../requirements/sub/2026-01-28-004-04-AI和智能功能.md)

## API 概述

### 功能描述
AI 和智能功能 API 提供对 Salesforce Tooling API 中 AI 相关功能的访问，包括：
- AI 应用管理（创建、查询、更新、删除）
- AI 评估配置查询（评估主题类型、处理状态、指标类型）
- AI 创作工具查询（创作包类型、版本状态、助手模板状态）

### 基础信息
- **基础路径**: `/salesforce/tooling/ai`
- **权限前缀**: `tooling:ai`
- **Content-Type**: `application/json`
- **认证方式**: JWT Token + Session

### 通用响应格式
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}
```

### 通用错误码
| 错误码 | 说明 |
|--------|------|
| 200 | 操作成功 |
| 500 | 服务器内部错误 |
| 401 | 未授权 |
| 403 | 权限不足 |

## 接口列表

### 一、AI 应用管理接口

#### 1. 创建 AI 应用

**功能描述**: 通过 Tooling API 创建 AI 应用（AIApplication）

**请求方式**: POST

**请求路径**: `/salesforce/tooling/ai/application`

**权限要求**: `tooling:ai:create`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| developerName | String | 是 | 开发者名称，唯一标识 | "MyAIApp" |
| masterLabel | String | 是 | 主标签，显示名称 | "My AI Application" |
| description | String | 否 | 描述 | "This is my AI application" |
| status | String | 是 | 状态（Active/Inactive） | "Active" |
| applicationType | String | 是 | 应用类型 | "EinsteinGPT" |

**请求示例**:
```json
{
  "developerName": "MyAIApp",
  "masterLabel": "My AI Application",
  "description": "This is my AI application",
  "status": "Active",
  "applicationType": "EinsteinGPT"
}
```

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码 |
| msg | String | 提示信息 |
| data | Object | 创建结果 |
| data.id | String | 创建的记录 ID |
| data.success | Boolean | 是否成功 |
| data.errors | Array | 错误信息列表 |

**成功响应示例**:
```json
{
  "code": 200,
  "msg": "创建 AI 应用成功",
  "data": {
    "id": "0Afxx0000000001CAA",
    "success": true,
    "errors": []
  }
}
```

**失败响应示例**:
```json
{
  "code": 500,
  "msg": "创建 AI 应用失败",
  "data": {
    "id": null,
    "success": false,
    "errors": ["DeveloperName already exists"]
  }
}
```

**错误码**:
- TOOLING_AI_001: Session 无效或已过期
- TOOLING_AI_002: 创建 AI 应用失败
- TOOLING_AI_007: 权限不足

---

#### 2. 查询 AI 应用列表

**功能描述**: 查询 Salesforce 组织中的所有 AI 应用

**请求方式**: GET

**请求路径**: `/salesforce/tooling/ai/applications`

**权限要求**: `tooling:ai:query`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| status | String | 否 | 状态筛选 | "Active" |
| pageNum | Integer | 否 | 页码，默认 1 | 1 |
| pageSize | Integer | 否 | 每页大小，默认 10 | 10 |

**请求示例**:
```
GET /salesforce/tooling/ai/applications?status=Active&pageNum=1&pageSize=10
```

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码 |
| msg | String | 提示信息 |
| data | Object | 查询结果 |
| data.total | Integer | 总记录数 |
| data.rows | Array | AI 应用列表 |
| data.rows[].id | String | 记录 ID |
| data.rows[].developerName | String | 开发者名称 |
| data.rows[].masterLabel | String | 主标签 |
| data.rows[].description | String | 描述 |
| data.rows[].status | String | 状态 |
| data.rows[].applicationType | String | 应用类型 |
| data.rows[].createdDate | String | 创建日期 |
| data.rows[].lastModifiedDate | String | 最后修改日期 |

**成功响应示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "total": 2,
    "rows": [
      {
        "id": "0Afxx0000000001CAA",
        "developerName": "MyAIApp",
        "masterLabel": "My AI Application",
        "description": "This is my AI application",
        "status": "Active",
        "applicationType": "EinsteinGPT",
        "createdDate": "2026-02-05T10:00:00.000Z",
        "lastModifiedDate": "2026-02-05T10:00:00.000Z"
      }
    ]
  }
}
```

**错误码**:
- TOOLING_AI_001: Session 无效或已过期
- TOOLING_AI_005: 查询 AI 应用失败

---

#### 3. 更新 AI 应用

**功能描述**: 通过 Tooling API 更新 AI 应用

**请求方式**: PUT

**请求路径**: `/salesforce/tooling/ai/application`

**权限要求**: `tooling:ai:update`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| id | String | 是 | 记录 ID | "0Afxx0000000001CAA" |
| developerName | String | 否 | 开发者名称 | "MyAIApp" |
| masterLabel | String | 否 | 主标签 | "My AI Application" |
| description | String | 否 | 描述 | "Updated description" |
| status | String | 否 | 状态 | "Inactive" |
| applicationType | String | 否 | 应用类型 | "EinsteinGPT" |

**请求示例**:
```json
{
  "id": "0Afxx0000000001CAA",
  "masterLabel": "My AI Application Updated",
  "description": "Updated description"
}
```

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码 |
| msg | String | 提示信息 |
| data | Object | 更新结果 |
| data.id | String | 记录 ID |
| data.success | Boolean | 是否成功 |
| data.errors | Array | 错误信息列表 |

**成功响应示例**:
```json
{
  "code": 200,
  "msg": "更新 AI 应用成功",
  "data": {
    "id": "0Afxx0000000001CAA",
    "success": true,
    "errors": []
  }
}
```

**错误码**:
- TOOLING_AI_001: Session 无效或已过期
- TOOLING_AI_003: 更新 AI 应用失败
- TOOLING_AI_008: 记录不存在

---

#### 4. 删除 AI 应用

**功能描述**: 通过 Tooling API 删除 AI 应用

**请求方式**: DELETE

**请求路径**: `/salesforce/tooling/ai/application/{id}`

**权限要求**: `tooling:ai:delete`

**路径参数**:

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| id | String | 是 | 记录 ID | "0Afxx0000000001CAA" |

**请求示例**:
```
DELETE /salesforce/tooling/ai/application/0Afxx0000000001CAA
```

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码 |
| msg | String | 提示信息 |
| data | Object | 删除结果 |
| data.id | String | 记录 ID |
| data.success | Boolean | 是否成功 |
| data.errors | Array | 错误信息列表 |

**成功响应示例**:
```json
{
  "code": 200,
  "msg": "删除 AI 应用成功",
  "data": {
    "id": "0Afxx0000000001CAA",
    "success": true,
    "errors": []
  }
}
```

**错误码**:
- TOOLING_AI_001: Session 无效或已过期
- TOOLING_AI_004: 删除 AI 应用失败
- TOOLING_AI_008: 记录不存在

---

### 二、AI 评估配置查询接口

#### 5. 查询评估主题类型

**功能描述**: 查询 Salesforce 组织中的 AI 评估主题类型（AiEvaluationSubjectType）

**请求方式**: GET

**请求路径**: `/salesforce/tooling/ai/evaluation-subject-types`

**权限要求**: `tooling:ai:query`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| pageNum | Integer | 否 | 页码，默认 1 | 1 |
| pageSize | Integer | 否 | 每页大小，默认 10 | 10 |

**请求示例**:
```
GET /salesforce/tooling/ai/evaluation-subject-types?pageNum=1&pageSize=10
```

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码 |
| msg | String | 提示信息 |
| data | Object | 查询结果 |
| data.total | Integer | 总记录数 |
| data.rows | Array | 评估主题类型列表 |
| data.rows[].id | String | 记录 ID |
| data.rows[].developerName | String | 开发者名称 |
| data.rows[].masterLabel | String | 主标签 |
| data.rows[].description | String | 描述 |

**成功响应示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "total": 3,
    "rows": [
      {
        "id": "0Agxx0000000001CAA",
        "developerName": "Flow",
        "masterLabel": "Flow",
        "description": "Flow evaluation subject"
      }
    ]
  }
}
```

**错误码**:
- TOOLING_AI_001: Session 无效或已过期
- TOOLING_AI_010: 查询 AI 类型失败

---

#### 6. 查询评估处理状态

**功能描述**: 查询 Salesforce 组织中的 AI 评估处理状态（AiEvaluationProcessingStatus）

**请求方式**: GET

**请求路径**: `/salesforce/tooling/ai/evaluation-processing-statuses`

**权限要求**: `tooling:ai:query`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| pageNum | Integer | 否 | 页码，默认 1 | 1 |
| pageSize | Integer | 否 | 每页大小，默认 10 | 10 |

**响应参数**: 同"查询评估主题类型"

**错误码**:
- TOOLING_AI_001: Session 无效或已过期
- TOOLING_AI_010: 查询 AI 类型失败

---

#### 7. 查询评估指标类型

**功能描述**: 查询 Salesforce 组织中的 AI 评估指标类型（AiEvaluationMetricType）

**请求方式**: GET

**请求路径**: `/salesforce/tooling/ai/evaluation-metric-types`

**权限要求**: `tooling:ai:query`

**请求参数**: 同"查询评估主题类型"

**响应参数**: 同"查询评估主题类型"

**错误码**:
- TOOLING_AI_001: Session 无效或已过期
- TOOLING_AI_010: 查询 AI 类型失败

---

### 三、AI 创作工具查询接口

#### 8. 查询创作包类型

**功能描述**: 查询 Salesforce 组织中的 AI 创作包类型（AiAuthoringBundleType）

**请求方式**: GET

**请求路径**: `/salesforce/tooling/ai/authoring-bundle-types`

**权限要求**: `tooling:ai:query`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| pageNum | Integer | 否 | 页码，默认 1 | 1 |
| pageSize | Integer | 否 | 每页大小，默认 10 | 10 |

**响应参数**: 同"查询评估主题类型"

**错误码**:
- TOOLING_AI_001: Session 无效或已过期
- TOOLING_AI_010: 查询 AI 类型失败

---

#### 9. 查询创作包版本状态

**功能描述**: 查询 Salesforce 组织中的 AI 创作包版本状态（AiAuthoringBundleVersionStatus）

**请求方式**: GET

**请求路径**: `/salesforce/tooling/ai/authoring-bundle-version-statuses`

**权限要求**: `tooling:ai:query`

**请求参数**: 同"查询创作包类型"

**响应参数**: 同"查询评估主题类型"

**错误码**:
- TOOLING_AI_001: Session 无效或已过期
- TOOLING_AI_010: 查询 AI 类型失败

---

#### 10. 查询助手模板状态

**功能描述**: 查询 Salesforce 组织中的 AI 助手模板状态（AiAssistantTemplateStatus）

**请求方式**: GET

**请求路径**: `/salesforce/tooling/ai/assistant-template-statuses`

**权限要求**: `tooling:ai:query`

**请求参数**: 同"查询创作包类型"

**响应参数**: 同"查询评估主题类型"

**错误码**:
- TOOLING_AI_001: Session 无效或已过期
- TOOLING_AI_010: 查询 AI 类型失败

---

## 错误码列表

### 系统错误码

| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| TOOLING_AI_001 | Session 无效或已过期 | 重新登录获取有效 Session |
| TOOLING_AI_002 | 创建 AI 应用失败 | 检查请求参数是否正确，DeveloperName 是否已存在 |
| TOOLING_AI_003 | 更新 AI 应用失败 | 检查记录 ID 是否存在，请求参数是否正确 |
| TOOLING_AI_004 | 删除 AI 应用失败 | 检查记录 ID 是否存在，是否有权限删除 |
| TOOLING_AI_005 | 查询 AI 应用失败 | 检查查询条件是否正确，Session 是否有效 |
| TOOLING_AI_006 | 网络超时 | 检查网络连接，稍后重试 |
| TOOLING_AI_007 | 权限不足 | 检查用户是否有相应权限 |
| TOOLING_AI_008 | 记录不存在 | 检查记录 ID 是否正确 |
| TOOLING_AI_009 | 用户未登录 | 请先登录系统 |
| TOOLING_AI_010 | 查询 AI 类型失败 | 检查 Session 是否有效，网络连接是否正常 |
| TOOLING_AI_011 | 操作类型不支持 | 检查操作类型是否正确 |

### HTTP 状态码

| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 未授权，需要登录 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

## 相关文档
- [需求文档](../requirements/sub/2026-01-28-004-04-AI和智能功能.md)
- [设计文档](../design/2026-02-03-004-04-AI和智能功能-设计.md)
- [决策记录](../decisions/2026-02-03-004-04-ADR-AI和智能功能技术选型.md)
- [变更日志](../changelog/2026-02-05-004-04-changelog.md)
- [复盘文档](../retros/2026-02-05-004-04-retro.md)
- [会话记录](../sessions/2026-02-03-004-04-session.md)

## 附录

### 附录 A：AI 应用状态枚举

| 状态值 | 说明 |
|--------|------|
| Active | 活跃状态 |
| Inactive | 非活跃状态 |

### 附录 B：AI 应用类型枚举

| 类型值 | 说明 |
|--------|------|
| EinsteinGPT | Einstein GPT 应用 |
| EinsteinBots | Einstein 机器人 |
| Other | 其他类型 |

### 附录 C：Postman 测试示例

#### 创建 AI 应用
```bash
curl -X POST "http://localhost:8080/salesforce/tooling/ai/application" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "developerName": "TestAIApp",
    "masterLabel": "Test AI Application",
    "description": "This is a test AI application",
    "status": "Active",
    "applicationType": "EinsteinGPT"
  }'
```

#### 查询 AI 应用列表
```bash
curl -X GET "http://localhost:8080/salesforce/tooling/ai/applications?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer ${TOKEN}"
```

#### 更新 AI 应用
```bash
curl -X PUT "http://localhost:8080/salesforce/tooling/ai/application" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -d '{
    "id": "0Afxx0000000001CAA",
    "masterLabel": "Updated AI Application"
  }'
```

#### 删除 AI 应用
```bash
curl -X DELETE "http://localhost:8080/salesforce/tooling/ai/application/0Afxx0000000001CAA" \
  -H "Authorization: Bearer ${TOKEN}"
```