diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/001-convert-lead.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/001-convert-lead.md new file mode 100644 index 00000000..702c0383 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/001-convert-lead.md @@ -0,0 +1,126 @@ +# API 文档 - 转换线索 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：001 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +将 Salesforce 线索（Lead）转换为账户（Account）、联系人（Contact）和商机（Opportunity）。 + +## 基本信息 + +- **功能描述**：转换线索为账户、联系人和商机 +- **请求方式**：POST +- **请求路径**：`/partner/advanced/convert-lead` +- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:convertLead')")` + +## 请求参数 + +### 请求体（JSON） + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| leadId | String | 是 | 线索 ID | 00Qxx0000001Gw2EAE | +| convertedStatus | String | 是 | 转换状态 | Qualified | +| accountId | String | 否 | 账户 ID（可选），如果不指定则自动创建新账户 | 001xx0000001Gw2EAA | +| contactId | String | 否 | 联系人 ID（可选），如果不指定则自动创建新联系人 | 003xx0000001Gw2EAA | +| opportunityId | String | 否 | 商机 ID（可选），如果不指定则自动创建新商机 | 006xx0000001Gw2EAA | +| overwriteLeadSource | Boolean | 否 | 是否覆盖线索来源，默认 false | false | +| doNotCreateOpportunity | Boolean | 否 | 是否不创建商机，默认 false | false | +| sendNotificationEmail | Boolean | 否 | 是否发送通知邮件，默认 false | false | + +### 请求示例 + +```json +{ + "leadId": "00Qxx0000001Gw2EAE", + "convertedStatus": "Qualified", + "accountId": "001xx0000001Gw2EAA", + "contactId": "003xx0000001Gw2EAA", + "opportunityId": "006xx0000001Gw2EAA", + "overwriteLeadSource": false, + "doNotCreateOpportunity": false, + "sendNotificationEmail": false +} +``` + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.accountId | String | 账户 ID | +| data.contactId | String | 联系人 ID | +| data.opportunityId | String | 商机 ID | +| data.leadId | String | 原线索 ID | +| data.success | Boolean | 是否成功 | +| data.errors | Array | 错误信息列表 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "accountId": "001xx0000001Gw2EAA", + "contactId": "003xx0000001Gw2EAA", + "opportunityId": "006xx0000001Gw2EAA", + "leadId": "00Qxx0000001Gw2EAE", + "success": true, + "errors": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "线索转换失败", + "data": { + "accountId": null, + "contactId": null, + "opportunityId": null, + "leadId": "00Qxx0000001Gw2EAE", + "success": false, + "errors": [ + { + "statusCode": "INVALID_ID_FIELD", + "message": "Invalid ID field", + "fields": ["leadId"] + } + ] + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 403 | 无权限访问 | 请检查用户权限 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 线索转换后，原线索会被标记为已转换，不能再进行转换 +2. 如果不指定 accountId、contactId 或 opportunityId，系统会自动创建新记录 +3. convertedStatus 必须是 Salesforce 中配置的有效转换状态 +4. 一次只能转换一个线索 +5. 转换操作是原子性的，要么全部成功，要么全部失败 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/002-empty-recycle-bin.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/002-empty-recycle-bin.md new file mode 100644 index 00000000..dc5be874 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/002-empty-recycle-bin.md @@ -0,0 +1,156 @@ +# API 文档 - 清空回收站 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：002 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +永久删除 Salesforce 回收站中的记录，释放存储空间。 + +## 基本信息 + +- **功能描述**：永久删除回收站中的记录 +- **请求方式**：POST +- **请求路径**：`/partner/advanced/empty-recycle-bin` +- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:emptyRecycleBin')")` + +## 请求参数 + +### 请求体（JSON） + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| ids | Array[String] | 是 | 记录 ID 列表（最多 200 个） | ["001xx0000001Gw2EAA", "001xx0000001Gw3EAA"] | + +### 请求示例 + +```json +{ + "ids": [ + "001xx0000001Gw2EAA", + "001xx0000001Gw3EAA", + "001xx0000001Gw4EAA" + ] +} +``` + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.results | Array | 结果列表 | +| data.results[].id | String | 记录 ID | +| data.results[].success | Boolean | 是否成功 | +| data.results[].errors | Array | 错误信息列表 | +| data.success | Boolean | 是否全部成功 | +| data.errors | Array | 整体错误信息列表 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "results": [ + { + "id": "001xx0000001Gw2EAA", + "success": true, + "errors": null + }, + { + "id": "001xx0000001Gw3EAA", + "success": true, + "errors": null + }, + { + "id": "001xx0000001Gw4EAA", + "success": true, + "errors": null + } + ], + "success": true, + "errors": null + } +} +``` + +### 部分失败响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "results": [ + { + "id": "001xx0000001Gw2EAA", + "success": true, + "errors": null + }, + { + "id": "001xx0000001Gw3EAA", + "success": false, + "errors": [ + { + "statusCode": "INVALID_ID_FIELD", + "message": "Invalid ID field", + "fields": ["id"] + } + ] + } + ], + "success": false, + "errors": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "清空回收站失败", + "data": { + "results": null, + "success": false, + "errors": [ + { + "statusCode": "INVALID_OPERATION", + "message": "Cannot delete records that are not in the recycle bin" + } + ] + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 403 | 无权限访问 | 请检查用户权限 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 此操作是永久删除，无法恢复，请谨慎操作 +2. 只能删除回收站中的记录，不能删除未删除的记录 +3. 单次最多删除 200 条记录 +4. 某些记录可能因为权限限制或其他原因无法删除 +5. 删除操作是原子性的，每条记录独立处理 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/003-process-submit-request.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/003-process-submit-request.md new file mode 100644 index 00000000..0910dee5 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/003-process-submit-request.md @@ -0,0 +1,104 @@ +# API 文档 - 流程提交 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：003 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +将 Salesforce 记录提交到审批流程进行审批。 + +## 基本信息 + +- **功能描述**：提交记录到审批流程 +- **请求方式**：POST +- **请求路径**：`/partner/advanced/process-submit-request` +- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:processSubmit')")` + +## 请求参数 + +### 请求体（JSON） + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectId | String | 是 | 对象 ID | 001xx0000001Gw2EAA | +| comments | String | 否 | 评论（可选） | 请审批此记录 | + +### 请求示例 + +```json +{ + "objectId": "001xx0000001Gw2EAA", + "comments": "请审批此记录，所有信息已核对无误" +} +``` + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.processInstanceId | String | 流程实例 ID | +| data.success | Boolean | 是否成功 | +| data.errors | Array | 错误信息列表 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "processInstanceId": "04gxx0000001Gw2EAA", + "success": true, + "errors": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "流程提交失败", + "data": { + "processInstanceId": null, + "success": false, + "errors": [ + { + "statusCode": "NO_APPLICABLE_PROCESS", + "message": "No applicable approval process found for this record" + } + ] + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 403 | 无权限访问 | 请检查用户权限 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 记录必须配置了审批流程才能提交 +2. 用户必须有提交审批的权限 +3. 一条记录只能同时处于一个审批流程中 +4. 提交后，记录会被锁定，直到审批完成或被拒绝 +5. 可以通过 processInstanceId 查询审批进度 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/004-get-user-info.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/004-get-user-info.md new file mode 100644 index 00000000..c356c939 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/004-get-user-info.md @@ -0,0 +1,95 @@ +# API 文档 - 获取用户信息 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：004 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +获取当前登录用户的详细信息，包括用户 ID、用户名、邮箱、组织信息、配置文件信息等。 + +## 基本信息 + +- **功能描述**：获取当前登录用户的基本信息 +- **请求方式**：GET +- **请求路径**：`/partner/advanced/user-info` +- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:userInfo')")` + +## 请求参数 + +无 + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.userId | String | 用户 ID | +| data.username | String | 用户名 | +| data.email | String | 邮箱 | +| data.organizationId | String | 组织 ID | +| data.organizationName | String | 组织名称 | +| data.profileId | String | 配置文件 ID | +| data.profileName | String | 配置文件名称 | +| data.userFullName | String | 用户全名 | +| data.userType | String | 用户类型 | +| data.userLanguage | String | 用户语言 | +| data.userLocale | String | 用户区域设置 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "userId": "0055w00000AaBCD", + "username": "admin@example.com", + "email": "admin@example.com", + "organizationId": "00D5w00000AaBC", + "organizationName": "Example Company", + "profileId": "00e5w00000AaBCD", + "profileName": "System Administrator", + "userFullName": "John Doe", + "userType": "Standard", + "userLanguage": "en_US", + "userLocale": "en_US" + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "获取用户信息失败: 未找到有效的会话", + "data": null +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 403 | 无权限访问 | 请检查用户权限 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 此接口返回的是当前登录用户的信息 +2. 用户信息包含敏感数据，请妥善保管 +3. 用户类型包括：Standard、PowerCustomer、PowerPartner、CSPLitePortal 等 +4. 用户语言和区域设置可能影响某些 API 的返回结果 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/005-get-server-timestamp.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/005-get-server-timestamp.md new file mode 100644 index 00000000..0b4b5a77 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerAdvancedController/005-get-server-timestamp.md @@ -0,0 +1,91 @@ +# API 文档 - 获取服务器时间戳 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：005 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +获取 Salesforce 服务器的当前时间戳和时区信息。 + +## 基本信息 + +- **功能描述**：获取 Salesforce 服务器当前时间戳 +- **请求方式**：GET +- **请求路径**：`/partner/advanced/server-timestamp` +- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:advanced:serverTimestamp')")` + +## 请求参数 + +无 + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.timestamp | String | 服务器时间戳（ISO 8601 格式） | +| data.timeZone | String | 时区 | +| data.success | Boolean | 是否成功 | +| data.errors | Array | 错误信息列表 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "timestamp": "2026-02-02T10:30:00.000Z", + "timeZone": "Asia/Shanghai", + "success": true, + "errors": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "获取服务器时间戳失败", + "data": { + "timestamp": null, + "timeZone": null, + "success": false, + "errors": [ + { + "statusCode": "UNKNOWN_EXCEPTION", + "message": "Failed to retrieve server timestamp" + } + ] + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 403 | 无权限访问 | 请检查用户权限 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 时间戳格式为 ISO 8601 标准（YYYY-MM-DDTHH:mm:ss.sssZ） +2. 时区信息可用于时间转换和显示 +3. 此接口可用于同步本地时间与服务器时间 +4. 建议在需要精确时间操作时调用此接口 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerBatchController/001-batch-create.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerBatchController/001-batch-create.md new file mode 100644 index 00000000..6d365b49 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerBatchController/001-batch-create.md @@ -0,0 +1,176 @@ +# API 文档 - 批量创建记录 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：001 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +批量创建 Salesforce 记录，支持最多 1000 条记录，每批最多 200 条，自动分批处理。 + +## 基本信息 + +- **功能描述**：批量创建 Salesforce 记录 +- **请求方式**：POST +- **请求路径**：`/partner/batch/create` +- **权限要求**：`@PreAuthorize("@ss.hasLogin()")` + +## 请求参数 + +### 请求体（JSON） + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型 | Account | +| records | Array[Object] | 是 | 记录列表 | [{"Name": "Test Account"}] | +| allOrNone | Boolean | 否 | 是否全部成功或全部失败，默认 false | false | +| sleepTime | Long | 否 | 批次间休眠时间（毫秒），默认 100 | 100 | + +### 请求示例 + +```json +{ + "objectType": "Account", + "records": [ + { + "Name": "Test Account 1", + "Industry": "Technology", + "Phone": "555-1234" + }, + { + "Name": "Test Account 2", + "Industry": "Finance", + "Phone": "555-5678" + } + ], + "allOrNone": false, + "sleepTime": 100 +} +``` + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.success | Boolean | 是否全部成功 | +| data.successCount | Integer | 成功数量 | +| data.failureCount | Integer | 失败数量 | +| data.totalCount | Integer | 总数量 | +| data.results | Array | 结果列表 | +| data.results[].success | Boolean | 是否成功 | +| data.results[].id | String | 记录 ID | +| data.results[].errors | Array | 错误列表 | +| data.results[].index | Integer | 索引 | +| data.errorMessage | String | 错误消息 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "批量创建成功", + "data": { + "success": true, + "successCount": 2, + "failureCount": 0, + "totalCount": 2, + "results": [ + { + "success": true, + "id": "001xx0000001Gw2EAA", + "errors": null, + "index": 0 + }, + { + "success": true, + "id": "001xx0000001Gw3EAA", + "errors": null, + "index": 1 + } + ], + "errorMessage": null + } +} +``` + +### 部分失败响应示例 + +```json +{ + "code": 200, + "msg": "批量创建部分失败", + "data": { + "success": false, + "successCount": 1, + "failureCount": 1, + "totalCount": 2, + "results": [ + { + "success": true, + "id": "001xx0000001Gw2EAA", + "errors": null, + "index": 0 + }, + { + "success": false, + "id": null, + "errors": [ + { + "statusCode": "REQUIRED_FIELD_MISSING", + "message": "Required fields are missing: [Name]", + "fields": ["Name"] + } + ], + "index": 1 + } + ], + "errorMessage": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "批量创建记录失败", + "data": { + "success": false, + "successCount": 0, + "failureCount": 0, + "totalCount": 0, + "results": null, + "errorMessage": "Invalid object type: InvalidObject" + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 单次最多创建 1000 条记录 +2. 每批最多 200 条记录，超过会自动分批 +3. allOrNone 为 true 时，任何一条记录失败都会导致整个操作失败 +4. sleepTime 用于控制批次间的间隔，避免 API 限流 +5. 记录中的字段名必须与 Salesforce 对象字段名匹配 +6. 必填字段必须提供，否则创建失败 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerBatchController/002-batch-update.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerBatchController/002-batch-update.md new file mode 100644 index 00000000..1944ec53 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerBatchController/002-batch-update.md @@ -0,0 +1,179 @@ +# API 文档 - 批量更新记录 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：002 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +批量更新 Salesforce 记录，支持最多 1000 条记录，每批最多 200 条，自动分批处理。 + +## 基本信息 + +- **功能描述**：批量更新 Salesforce 记录 +- **请求方式**：POST +- **请求路径**：`/partner/batch/update` +- **权限要求**：`@PreAuthorize("@ss.hasLogin()")` + +## 请求参数 + +### 请求体（JSON） + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型 | Account | +| records | Array[Object] | 是 | 记录列表（每条记录必须包含 id） | [{"id": "001xx...", "Name": "New Name"}] | +| allOrNone | Boolean | 否 | 是否全部成功或全部失败，默认 false | false | +| sleepTime | Long | 否 | 批次间休眠时间（毫秒），默认 100 | 100 | + +### 请求示例 + +```json +{ + "objectType": "Account", + "records": [ + { + "id": "001xx0000001Gw2EAA", + "Name": "Updated Account 1", + "Industry": "Technology", + "Phone": "555-9999" + }, + { + "id": "001xx0000001Gw3EAA", + "Name": "Updated Account 2", + "Industry": "Finance", + "Phone": "555-8888" + } + ], + "allOrNone": false, + "sleepTime": 100 +} +``` + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.success | Boolean | 是否全部成功 | +| data.successCount | Integer | 成功数量 | +| data.failureCount | Integer | 失败数量 | +| data.totalCount | Integer | 总数量 | +| data.results | Array | 结果列表 | +| data.results[].success | Boolean | 是否成功 | +| data.results[].id | String | 记录 ID | +| data.results[].errors | Array | 错误列表 | +| data.results[].index | Integer | 索引 | +| data.errorMessage | String | 错误消息 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "批量更新成功", + "data": { + "success": true, + "successCount": 2, + "failureCount": 0, + "totalCount": 2, + "results": [ + { + "success": true, + "id": "001xx0000001Gw2EAA", + "errors": null, + "index": 0 + }, + { + "success": true, + "id": "001xx0000001Gw3EAA", + "errors": null, + "index": 1 + } + ], + "errorMessage": null + } +} +``` + +### 部分失败响应示例 + +```json +{ + "code": 200, + "msg": "批量更新部分失败", + "data": { + "success": false, + "successCount": 1, + "failureCount": 1, + "totalCount": 2, + "results": [ + { + "success": true, + "id": "001xx0000001Gw2EAA", + "errors": null, + "index": 0 + }, + { + "success": false, + "id": "001xx0000001Gw3EAA", + "errors": [ + { + "statusCode": "INVALID_FIELD", + "message": "Invalid field: InvalidField__c", + "fields": ["InvalidField__c"] + } + ], + "index": 1 + } + ], + "errorMessage": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "批量更新记录失败", + "data": { + "success": false, + "successCount": 0, + "failureCount": 0, + "totalCount": 0, + "results": null, + "errorMessage": "Invalid object type: InvalidObject" + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 单次最多更新 1000 条记录 +2. 每批最多 200 条记录，超过会自动分批 +3. 每条记录必须包含 id 字段 +4. allOrNone 为 true 时，任何一条记录失败都会导致整个操作失败 +5. sleepTime 用于控制批次间的间隔，避免 API 限流 +6. 只更新提供的字段，未提供的字段保持不变 +7. 更新操作需要记录的编辑权限 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerBatchController/003-batch-delete.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerBatchController/003-batch-delete.md new file mode 100644 index 00000000..ad4e1ec8 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerBatchController/003-batch-delete.md @@ -0,0 +1,182 @@ +# API 文档 - 批量删除记录 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：003 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +批量删除 Salesforce 记录，支持最多 1000 条记录，每批最多 200 条，自动分批处理。 + +## 基本信息 + +- **功能描述**：批量删除 Salesforce 记录 +- **请求方式**：POST +- **请求路径**：`/partner/batch/delete` +- **权限要求**：`@PreAuthorize("@ss.hasLogin()")` + +## 请求参数 + +### 请求体（JSON） + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型 | Account | +| ids | Array[String] | 是 | 记录 ID 列表 | ["001xx...", "001xx..."] | +| allOrNone | Boolean | 否 | 是否全部成功或全部失败，默认 false | false | +| sleepTime | Long | 否 | 批次间休眠时间（毫秒），默认 100 | 100 | + +### 请求示例 + +```json +{ + "objectType": "Account", + "ids": [ + "001xx0000001Gw2EAA", + "001xx0000001Gw3EAA", + "001xx0000001Gw4EAA" + ], + "allOrNone": false, + "sleepTime": 100 +} +``` + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.success | Boolean | 是否全部成功 | +| data.successCount | Integer | 成功数量 | +| data.failureCount | Integer | 失败数量 | +| data.totalCount | Integer | 总数量 | +| data.results | Array | 结果列表 | +| data.results[].success | Boolean | 是否成功 | +| data.results[].id | String | 记录 ID | +| data.results[].errors | Array | 错误列表 | +| data.results[].index | Integer | 索引 | +| data.errorMessage | String | 错误消息 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "批量删除成功", + "data": { + "success": true, + "successCount": 3, + "failureCount": 0, + "totalCount": 3, + "results": [ + { + "success": true, + "id": "001xx0000001Gw2EAA", + "errors": null, + "index": 0 + }, + { + "success": true, + "id": "001xx0000001Gw3EAA", + "errors": null, + "index": 1 + }, + { + "success": true, + "id": "001xx0000001Gw4EAA", + "errors": null, + "index": 2 + } + ], + "errorMessage": null + } +} +``` + +### 部分失败响应示例 + +```json +{ + "code": 200, + "msg": "批量删除部分失败", + "data": { + "success": false, + "successCount": 2, + "failureCount": 1, + "totalCount": 3, + "results": [ + { + "success": true, + "id": "001xx0000001Gw2EAA", + "errors": null, + "index": 0 + }, + { + "success": true, + "id": "001xx0000001Gw3EAA", + "errors": null, + "index": 1 + }, + { + "success": false, + "id": "001xx0000001Gw4EAA", + "errors": [ + { + "statusCode": "ENTITY_IS_DELETED", + "message": "The entity is already deleted", + "fields": [] + } + ], + "index": 2 + } + ], + "errorMessage": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "批量删除记录失败", + "data": { + "success": false, + "successCount": 0, + "failureCount": 0, + "totalCount": 0, + "results": null, + "errorMessage": "Invalid object type: InvalidObject" + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 单次最多删除 1000 条记录 +2. 每批最多 200 条记录，超过会自动分批 +3. 删除操作是永久性的，无法恢复 +4. allOrNone 为 true 时，任何一条记录失败都会导致整个操作失败 +5. sleepTime 用于控制批次间的间隔，避免 API 限流 +6. 删除操作需要记录的删除权限 +7. 某些记录可能因为关联关系或其他限制无法删除 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerBatchController/004-batch-upsert.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerBatchController/004-batch-upsert.md new file mode 100644 index 00000000..5504e4f8 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerBatchController/004-batch-upsert.md @@ -0,0 +1,229 @@ +# API 文档 - 批量 Upsert 记录 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：004 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +批量更新或插入 Salesforce 记录，支持最多 1000 条记录，每批最多 200 条，自动分批处理。 + +## 基本信息 + +- **功能描述**：批量更新或插入 Salesforce 记录 +- **请求方式**：POST +- **请求路径**：`/partner/batch/upsert` +- **权限要求**：`@PreAuthorize("@ss.hasLogin()")` + +## 请求参数 + +### 请求体（JSON） + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型 | Account | +| externalIdField | String | 是 | 外部 ID 字段 | ExternalId__c | +| records | Array[Object] | 是 | 记录列表（每条记录必须包含外部 ID 字段） | [{"ExternalId__c": "EXT001", "Name": "Test"}] | +| allOrNone | Boolean | 否 | 是否全部成功或全部失败，默认 false | false | +| sleepTime | Long | 否 | 批次间休眠时间（毫秒），默认 100 | 100 | + +### 请求示例 + +```json +{ + "objectType": "Account", + "externalIdField": "ExternalId__c", + "records": [ + { + "ExternalId__c": "EXT001", + "Name": "Test Account 1", + "Industry": "Technology", + "Phone": "555-1234" + }, + { + "ExternalId__c": "EXT002", + "Name": "Test Account 2", + "Industry": "Finance", + "Phone": "555-5678" + } + ], + "allOrNone": false, + "sleepTime": 100 +} +``` + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.success | Boolean | 是否全部成功 | +| data.successCount | Integer | 成功数量 | +| data.failureCount | Integer | 失败数量 | +| data.createdCount | Integer | 创建数量 | +| data.updatedCount | Integer | 更新数量 | +| data.totalCount | Integer | 总数量 | +| data.results | Array | 结果列表 | +| data.results[].success | Boolean | 是否成功 | +| data.results[].id | String | 记录 ID | +| data.results[].errors | Array | 错误列表 | +| data.results[].created | Boolean | 是否创建 | +| data.results[].index | Integer | 索引 | +| data.errorMessage | String | 错误消息 | + +### 成功响应示例（全部创建） + +```json +{ + "code": 200, + "msg": "批量 Upsert 成功", + "data": { + "success": true, + "successCount": 2, + "failureCount": 0, + "createdCount": 2, + "updatedCount": 0, + "totalCount": 2, + "results": [ + { + "success": true, + "id": "001xx0000001Gw2EAA", + "errors": null, + "created": true, + "index": 0 + }, + { + "success": true, + "id": "001xx0000001Gw3EAA", + "errors": null, + "created": true, + "index": 1 + } + ], + "errorMessage": null + } +} +``` + +### 成功响应示例（部分更新） + +```json +{ + "code": 200, + "msg": "批量 Upsert 成功", + "data": { + "success": true, + "successCount": 2, + "failureCount": 0, + "createdCount": 1, + "updatedCount": 1, + "totalCount": 2, + "results": [ + { + "success": true, + "id": "001xx0000001Gw2EAA", + "errors": null, + "created": true, + "index": 0 + }, + { + "success": true, + "id": "001xx0000001Gw4EAA", + "errors": null, + "created": false, + "index": 1 + } + ], + "errorMessage": null + } +} +``` + +### 部分失败响应示例 + +```json +{ + "code": 200, + "msg": "批量 Upsert 部分失败", + "data": { + "success": false, + "successCount": 1, + "failureCount": 1, + "createdCount": 1, + "updatedCount": 0, + "totalCount": 2, + "results": [ + { + "success": true, + "id": "001xx0000001Gw2EAA", + "errors": null, + "created": true, + "index": 0 + }, + { + "success": false, + "id": null, + "errors": [ + { + "statusCode": "REQUIRED_FIELD_MISSING", + "message": "Required fields are missing: [Name]", + "fields": ["Name"] + } + ], + "created": null, + "index": 1 + } + ], + "errorMessage": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "批量 Upsert 记录失败", + "data": { + "success": false, + "successCount": 0, + "failureCount": 0, + "createdCount": 0, + "updatedCount": 0, + "totalCount": 0, + "results": null, + "errorMessage": "Invalid external ID field: InvalidField__c" + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 单次最多 Upsert 1000 条记录 +2. 每批最多 200 条记录，超过会自动分批 +3. 每条记录必须包含外部 ID 字段 +4. 外部 ID 字段必须在 Salesforce 对象中定义为 External ID +5. 如果外部 ID 已存在，则更新记录；否则创建新记录 +6. allOrNone 为 true 时，任何一条记录失败都会导致整个操作失败 +7. sleepTime 用于控制批次间的间隔，避免 API 限流 +8. created 字段指示记录是创建还是更新 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerConnectionController/001-get-session-info.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerConnectionController/001-get-session-info.md new file mode 100644 index 00000000..0c9a0069 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerConnectionController/001-get-session-info.md @@ -0,0 +1,83 @@ +# API 文档 - 获取会话信息 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：001 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +获取当前用户的 Session ID 和实例 URL，用于后续的 Salesforce API 调用。 + +## 基本信息 + +- **功能描述**：获取当前用户的 Session ID 和实例 URL +- **请求方式**：GET +- **请求路径**：`/partner/connection/session` +- **权限要求**：`@PreAuthorize("@ss.hasLogin()")` + +## 请求参数 + +无 + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.sessionId | String | Session ID，用于后续的 Salesforce API 调用 | +| data.instanceUrl | String | 实例 URL，用于后续的 Salesforce API 调用 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "sessionId": "00D5w00000AaBC!AQEAQKx...", + "instanceUrl": "https://yourinstance.my.salesforce.com" + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "获取会话信息失败: 未找到有效的会话", + "data": null +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. Session ID 是访问 Salesforce API 的关键凭证，请妥善保管 +2. Session ID 有有效期限制，过期后需要重新获取 +3. instanceUrl 用于构建完整的 API 请求 URL +4. 此接口需要用户已登录到系统 +5. Session ID 可以用于直接调用 Salesforce API，无需再次认证 + +## 使用场景 + +- 在需要直接调用 Salesforce API 时获取认证信息 +- 验证当前会话是否有效 +- 获取 Salesforce 实例 URL 用于 API 调用 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerConnectionController/002-get-user-info.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerConnectionController/002-get-user-info.md new file mode 100644 index 00000000..38c599b3 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerConnectionController/002-get-user-info.md @@ -0,0 +1,102 @@ +# API 文档 - 获取用户信息 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：002 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +获取当前用户的详细信息，包括用户 ID、用户名、邮箱、组织信息、配置文件信息等。 + +## 基本信息 + +- **功能描述**：获取当前用户的详细信息 +- **请求方式**：GET +- **请求路径**：`/partner/connection/user` +- **权限要求**：`@PreAuthorize("@ss.hasLogin()")` + +## 请求参数 + +无 + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.userId | String | 用户 ID | +| data.username | String | 用户名 | +| data.email | String | 邮箱 | +| data.organizationId | String | 组织 ID | +| data.organizationName | String | 组织名称 | +| data.profileId | String | 配置文件 ID | +| data.profileName | String | 配置文件名称 | +| data.userFullName | String | 用户全名 | +| data.userType | String | 用户类型 | +| data.userLanguage | String | 用户语言 | +| data.userLocale | String | 用户区域设置 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "userId": "0055w00000AaBCD", + "username": "admin@example.com", + "email": "admin@example.com", + "organizationId": "00D5w00000AaBC", + "organizationName": "Example Company", + "profileId": "00e5w00000AaBCD", + "profileName": "System Administrator", + "userFullName": "John Doe", + "userType": "Standard", + "userLanguage": "en_US", + "userLocale": "en_US" + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "获取用户信息失败: 未找到有效的会话", + "data": null +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 此接口返回的是当前登录用户的信息 +2. 用户信息包含敏感数据，请妥善保管 +3. 用户类型包括：Standard、PowerCustomer、PowerPartner、CSPLitePortal 等 +4. 用户语言和区域设置可能影响某些 API 的返回结果 +5. 配置文件信息可用于权限控制和功能访问判断 + +## 使用场景 + +- 显示当前用户信息 +- 根据用户权限控制功能访问 +- 根据用户语言和区域设置本地化显示 +- 审计和日志记录 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerConnectionController/003-change-password.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerConnectionController/003-change-password.md new file mode 100644 index 00000000..b67ed0d7 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerConnectionController/003-change-password.md @@ -0,0 +1,102 @@ +# API 文档 - 修改密码 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：003 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +修改当前用户的密码。 + +## 基本信息 + +- **功能描述**：修改当前用户的密码 +- **请求方式**：POST +- **请求路径**：`/partner/connection/password` +- **权限要求**：`@PreAuthorize("@ss.hasLogin()")` + +## 请求参数 + +### 请求体（JSON） + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| newPassword | String | 是 | 新密码 | NewPassword123! | + +### 请求示例 + +```json +{ + "newPassword": "NewPassword123!" +} +``` + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据（通常为 null） | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "修改密码成功", + "data": null +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "修改密码失败: 密码不符合要求", + "data": null +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 新密码必须符合 Salesforce 密码策略要求 +2. 密码通常要求包含：大小写字母、数字、特殊字符 +3. 密码长度通常要求至少 8 个字符 +4. 新密码不能与最近使用过的密码相同 +5. 修改密码后，当前会话可能失效，需要重新登录 +6. 建议用户定期修改密码以保证账户安全 + +## 密码策略 + +Salesforce 默认密码策略通常包括： +- 最小长度：8 个字符 +- 必须包含：大写字母、小写字母、数字、特殊字符 +- 不能包含用户名 +- 不能与最近 5 次使用的密码相同 +- 密码有效期：通常为 90 天 + +## 使用场景 + +- 用户首次登录后修改默认密码 +- 用户定期更换密码 +- 管理员重置密码后用户修改密码 +- 安全审计要求强制修改密码 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/001-create-record.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/001-create-record.md new file mode 100644 index 00000000..d9aa98d3 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/001-create-record.md @@ -0,0 +1,175 @@ +# API 文档 - 创建记录 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：001 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +创建新的 Salesforce 记录，支持单个创建和批量创建。 + +## 基本信息 + +- **功能描述**：创建新的 Salesforce 记录 +- **请求方式**：POST +- **请求路径**：`/partner/crud/create` +- **权限要求**：`@PreAuthorize("@ss.hasLogin()")` + +## 请求参数 + +### 请求体（JSON）- 单个创建 + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型 | Account | +| fields | Object | 是 | 字段值 | {"Name": "Test Account"} | + +### 请求体（JSON）- 批量创建 + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型 | Account | +| records | Array[Object] | 是 | 批量创建记录列表 | [{"Name": "Account 1"}, {"Name": "Account 2"}] | + +### 单个创建请求示例 + +```json +{ + "objectType": "Account", + "fields": { + "Name": "Test Account", + "Industry": "Technology", + "BillingCity": "San Francisco", + "Phone": "555-1234" + } +} +``` + +### 批量创建请求示例 + +```json +{ + "objectType": "Account", + "records": [ + { + "Name": "Test Account 1", + "Industry": "Technology" + }, + { + "Name": "Test Account 2", + "Industry": "Finance" + } + ] +} +``` + +## 响应参数 + +### 单个创建响应 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.id | String | 记录 ID | +| data.success | Boolean | 是否成功 | +| data.errors | Array | 错误信息列表 | +| data.created | Boolean | 是否创建 | + +### 批量创建响应 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Array | 响应数据数组 | +| data[].id | String | 记录 ID | +| data[].success | Boolean | 是否成功 | +| data[].errors | Array | 错误信息列表 | +| data[].created | Boolean | 是否创建 | + +### 单个创建成功响应示例 + +```json +{ + "code": 200, + "msg": "创建成功", + "data": { + "id": "001xx0000001Gw2EAA", + "success": true, + "errors": null, + "created": true + } +} +``` + +### 批量创建成功响应示例 + +```json +{ + "code": 200, + "msg": "批量创建成功", + "data": [ + { + "id": "001xx0000001Gw2EAA", + "success": true, + "errors": null, + "created": true + }, + { + "id": "001xx0000001Gw3EAA", + "success": true, + "errors": null, + "created": true + } + ] +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "创建记录失败", + "data": { + "id": null, + "success": false, + "errors": [ + { + "statusCode": "REQUIRED_FIELD_MISSING", + "message": "Required fields are missing: [Name]", + "fields": ["Name"] + } + ], + "created": false + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 必填字段必须提供，否则创建失败 +2. 字段名必须与 Salesforce 对象字段名匹配 +3. 批量创建时，每条记录独立处理，部分失败不影响其他记录 +4. 某些字段可能有特定的格式要求（如日期、数字等） +5. 创建记录需要对象的创建权限 +6. 系统字段（如 Id、CreatedDate）不能手动设置 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/002-retrieve-record.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/002-retrieve-record.md new file mode 100644 index 00000000..fb36080d --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/002-retrieve-record.md @@ -0,0 +1,138 @@ +# API 文档 - 检索单个记录 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：002 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +根据 ID 检索单个 Salesforce 记录。 + +## 基本信息 + +- **功能描述**：根据 ID 检索单个 Salesforce 记录 +- **请求方式**：GET +- **请求路径**：`/partner/crud/retrieve` +- **权限要求**：`@PreAuthorize("@ss.hasLogin()")` + +## 请求参数 + +### 查询参数 + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型 | Account | +| id | String | 是 | 记录 ID | 001xx0000001Gw2EAA | +| fieldNames | String | 否 | 字段名称列表（多个字段用逗号分隔） | Name,Industry,Phone | + +### 请求示例 + +``` +GET /partner/crud/retrieve?objectType=Account&id=001xx0000001Gw2EAA&fieldNames=Name,Industry,Phone +``` + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.sObject | Object | 记录对象（包含所有字段或指定字段） | +| data.success | Boolean | 是否成功 | +| data.errors | Array | 错误信息列表 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "检索成功", + "data": { + "sObject": { + "Id": "001xx0000001Gw2EAA", + "Name": "Test Account", + "Industry": "Technology", + "Phone": "555-1234", + "BillingCity": "San Francisco", + "BillingState": "CA", + "BillingCountry": "USA" + }, + "success": true, + "errors": null + } +} +``` + +### 指定字段响应示例 + +```json +{ + "code": 200, + "msg": "检索成功", + "data": { + "sObject": { + "Id": "001xx0000001Gw2EAA", + "Name": "Test Account", + "Industry": "Technology", + "Phone": "555-1234" + }, + "success": true, + "errors": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "检索记录失败", + "data": { + "sObject": null, + "success": false, + "errors": [ + { + "statusCode": "INVALID_ID_FIELD", + "message": "Invalid ID field", + "fields": ["id"] + } + ] + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 404 | 记录不存在 | 检查记录 ID 是否正确 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 记录 ID 必须是有效的 Salesforce 记录 ID +2. 如果不指定 fieldNames，则返回所有可访问的字段 +3. 指定字段可以减少数据传输量，提高性能 +4. 检索记录需要对象的读取权限 +5. 某些字段可能因为权限限制无法访问 +6. 记录可能已被删除或归档 + +## 使用场景 + +- 根据记录 ID 获取记录详情 +- 获取记录的特定字段 +- 验证记录是否存在 +- 在编辑前获取记录当前值 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/003-update-record.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/003-update-record.md new file mode 100644 index 00000000..f349dcc5 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/003-update-record.md @@ -0,0 +1,184 @@ +# API 文档 - 更新记录 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：003 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +更新现有的 Salesforce 记录，支持单个更新和批量更新。 + +## 基本信息 + +- **功能描述**：更新现有的 Salesforce 记录 +- **请求方式**：PUT +- **请求路径**：`/partner/crud/update` +- **权限要求**：`@PreAuthorize("@ss.hasLogin()")` + +## 请求参数 + +### 请求体（JSON）- 单个更新 + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型 | Account | +| id | String | 是 | 记录 ID | 001xx0000001Gw2EAA | +| fields | Object | 是 | 字段值 | {"BillingCity": "New York"} | + +### 请求体（JSON）- 批量更新 + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型 | Account | +| records | Array[Object] | 是 | 批量更新记录列表 | [{"id": "001xx...", "fields": {...}}] | + +### 单个更新请求示例 + +```json +{ + "objectType": "Account", + "id": "001xx0000001Gw2EAA", + "fields": { + "BillingCity": "New York", + "BillingState": "NY", + "Phone": "555-9999" + } +} +``` + +### 批量更新请求示例 + +```json +{ + "objectType": "Account", + "records": [ + { + "id": "001xx0000001Gw2EAA", + "fields": { + "BillingCity": "New York", + "Phone": "555-9999" + } + }, + { + "id": "001xx0000001Gw3EAA", + "fields": { + "BillingCity": "Los Angeles", + "Phone": "555-8888" + } + } + ] +} +``` + +## 响应参数 + +### 单个更新响应 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.id | String | 记录 ID | +| data.success | Boolean | 是否成功 | +| data.errors | Array | 错误信息列表 | +| data.created | Boolean | 是否创建（更新时为 false） | + +### 批量更新响应 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Array | 响应数据数组 | +| data[].id | String | 记录 ID | +| data[].success | Boolean | 是否成功 | +| data[].errors | Array | 错误信息列表 | +| data[].created | Boolean | 是否创建（更新时为 false） | + +### 单个更新成功响应示例 + +```json +{ + "code": 200, + "msg": "更新成功", + "data": { + "id": "001xx0000001Gw2EAA", + "success": true, + "errors": null, + "created": false + } +} +``` + +### 批量更新成功响应示例 + +```json +{ + "code": 200, + "msg": "批量更新成功", + "data": [ + { + "id": "001xx0000001Gw2EAA", + "success": true, + "errors": null, + "created": false + }, + { + "id": "001xx0000001Gw3EAA", + "success": true, + "errors": null, + "created": false + } + ] +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "更新记录失败", + "data": { + "id": "001xx0000001Gw2EAA", + "success": false, + "errors": [ + { + "statusCode": "INVALID_FIELD", + "message": "Invalid field: InvalidField__c", + "fields": ["InvalidField__c"] + } + ], + "created": false + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 404 | 记录不存在 | 检查记录 ID 是否正确 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 必须提供记录 ID，否则更新失败 +2. 只更新提供的字段，未提供的字段保持不变 +3. 字段名必须与 Salesforce 对象字段名匹配 +4. 批量更新时，每条记录独立处理，部分失败不影响其他记录 +5. 更新记录需要对象的编辑权限 +6. 系统字段（如 Id、CreatedDate）不能更新 +7. 某些字段可能有特定的格式要求（如日期、数字等） + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/004-delete-record.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/004-delete-record.md new file mode 100644 index 00000000..80840e86 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/004-delete-record.md @@ -0,0 +1,180 @@ +# API 文档 - 删除记录 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：004 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +删除 Salesforce 记录，支持单个删除和批量删除。 + +## 基本信息 + +- **功能描述**：删除 Salesforce 记录 +- **请求方式**：DELETE +- **请求路径**：`/partner/crud/delete` +- **权限要求**：`@PreAuthorize("@ss.hasLogin()")` + +## 请求参数 + +### 请求体（JSON）- 单个删除 + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型 | Account | +| id | String | 是 | 记录 ID | 001xx0000001Gw2EAA | + +### 请求体（JSON）- 批量删除 + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型 | Account | +| ids | Array[String] | 是 | 批量删除记录 ID 列表 | ["001xx...", "001xx..."] | + +### 单个删除请求示例 + +```json +{ + "objectType": "Account", + "id": "001xx0000001Gw2EAA" +} +``` + +### 批量删除请求示例 + +```json +{ + "objectType": "Account", + "ids": [ + "001xx0000001Gw2EAA", + "001xx0000001Gw3EAA", + "001xx0000001Gw4EAA" + ] +} +``` + +## 响应参数 + +### 单个删除响应 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.id | String | 记录 ID | +| data.success | Boolean | 是否成功 | +| data.errors | Array | 错误信息列表 | +| data.created | Boolean | 是否创建（删除时为 null） | + +### 批量删除响应 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Array | 响应数据数组 | +| data[].id | String | 记录 ID | +| data[].success | Boolean | 是否成功 | +| data[].errors | Array | 错误信息列表 | +| data[].created | Boolean | 是否创建（删除时为 null） | + +### 单个删除成功响应示例 + +```json +{ + "code": 200, + "msg": "删除成功", + "data": { + "id": "001xx0000001Gw2EAA", + "success": true, + "errors": null, + "created": null + } +} +``` + +### 批量删除成功响应示例 + +```json +{ + "code": 200, + "msg": "批量删除成功", + "data": [ + { + "id": "001xx0000001Gw2EAA", + "success": true, + "errors": null, + "created": null + }, + { + "id": "001xx0000001Gw3EAA", + "success": true, + "errors": null, + "created": null + }, + { + "id": "001xx0000001Gw4EAA", + "success": true, + "errors": null, + "created": null + } + ] +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "删除记录失败", + "data": { + "id": "001xx0000001Gw2EAA", + "success": false, + "errors": [ + { + "statusCode": "ENTITY_IS_DELETED", + "message": "The entity is already deleted", + "fields": [] + } + ], + "created": null + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 404 | 记录不存在 | 检查记录 ID 是否正确 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 删除操作是永久性的，无法恢复 +2. 删除的记录会进入回收站，可以在一定时间内恢复 +3. 批量删除时，每条记录独立处理，部分失败不影响其他记录 +4. 删除记录需要对象的删除权限 +5. 某些记录可能因为关联关系或其他限制无法删除 +6. 删除记录可能会触发级联删除（如果配置了） +7. 记录删除后，其 ID 可能被重新分配给新记录 + +## 使用场景 + +- 删除不需要的记录 +- 批量清理过期数据 +- 删除测试数据 +- 数据清理和维护 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/005-upsert-record.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/005-upsert-record.md new file mode 100644 index 00000000..d1620c99 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/005-upsert-record.md @@ -0,0 +1,204 @@ +# API 文档 - 更新或插入记录 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：005 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +根据外部 ID 更新或插入 Salesforce 记录，支持单个 Upsert 和批量 Upsert。 + +## 基本信息 + +- **功能描述**：根据外部 ID 更新或插入 Salesforce 记录 +- **请求方式**：POST +- **请求路径**：`/partner/crud/upsert` +- **权限要求**：`@PreAuthorize("@ss.hasLogin()")` + +## 请求参数 + +### 请求体（JSON）- 单个 Upsert + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型 | Account | +| externalIdField | String | 是 | 外部 ID 字段 | ExternalId__c | +| fields | Object | 是 | 字段值（必须包含外部 ID 字段） | {"ExternalId__c": "EXT-001", "Name": "Test"} | + +### 请求体（JSON）- 批量 Upsert + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型 | Account | +| externalIdField | String | 是 | 外部 ID 字段 | ExternalId__c | +| records | Array[Object] | 是 | 批量 Upsert 记录列表（每条必须包含外部 ID 字段） | [{"ExternalId__c": "EXT-001", "Name": "Account 1"}] | + +### 单个 Upsert 请求示例 + +```json +{ + "objectType": "Account", + "externalIdField": "ExternalId__c", + "fields": { + "ExternalId__c": "EXT-001", + "Name": "Test Account", + "Industry": "Technology", + "BillingCity": "San Francisco" + } +} +``` + +### 批量 Upsert 请求示例 + +```json +{ + "objectType": "Account", + "externalIdField": "ExternalId__c", + "records": [ + { + "ExternalId__c": "EXT-001", + "Name": "Test Account 1", + "Industry": "Technology" + }, + { + "ExternalId__c": "EXT-002", + "Name": "Test Account 2", + "Industry": "Finance" + } + ] +} +``` + +## 响应参数 + +### 单个 Upsert 响应 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.id | String | 记录 ID | +| data.success | Boolean | 是否成功 | +| data.errors | Array | 错误信息列表 | +| data.created | Boolean | 是否创建（true 为创建，false 为更新） | + +### 批量 Upsert 响应 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Array | 响应数据数组 | +| data[].id | String | 记录 ID | +| data[].success | Boolean | 是否成功 | +| data[].errors | Array | 错误信息列表 | +| data[].created | Boolean | 是否创建（true 为创建，false 为更新） | + +### 单个 Upsert 成功响应示例（创建） + +```json +{ + "code": 200, + "msg": "Upsert 成功", + "data": { + "id": "001xx0000001Gw2EAA", + "success": true, + "errors": null, + "created": true + } +} +``` + +### 单个 Upsert 成功响应示例（更新） + +```json +{ + "code": 200, + "msg": "Upsert 成功", + "data": { + "id": "001xx0000001Gw2EAA", + "success": true, + "errors": null, + "created": false + } +} +``` + +### 批量 Upsert 成功响应示例 + +```json +{ + "code": 200, + "msg": "批量 Upsert 成功", + "data": [ + { + "id": "001xx0000001Gw2EAA", + "success": true, + "errors": null, + "created": true + }, + { + "id": "001xx0000001Gw3EAA", + "success": true, + "errors": null, + "created": false + } + ] +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "Upsert 记录失败", + "data": { + "id": null, + "success": false, + "errors": [ + { + "statusCode": "INVALID_FIELD", + "message": "Invalid external ID field: InvalidField__c", + "fields": ["externalIdField"] + } + ], + "created": null + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 外部 ID 字段必须在 Salesforce 对象中定义为 External ID +2. 每条记录必须包含外部 ID 字段 +3. 如果外部 ID 已存在，则更新记录；否则创建新记录 +4. 批量 Upsert 时，每条记录独立处理，部分失败不影响其他记录 +5. Upsert 操作需要对象的创建和编辑权限 +6. 系统字段（如 Id、CreatedDate）不能手动设置 +7. created 字段指示记录是创建还是更新 + +## 使用场景 + +- 数据同步：根据外部 ID 同步数据到 Salesforce +- 数据导入：批量导入数据，自动判断创建或更新 +- 避免重复：使用外部 ID 避免创建重复记录 +- 集成系统：与外部系统集成时使用外部 ID + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/006-merge-records.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/006-merge-records.md new file mode 100644 index 00000000..72bff67b --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerCrudController/006-merge-records.md @@ -0,0 +1,141 @@ +# API 文档 - 合并记录 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：006 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 + +合并多个 Salesforce 记录到一个主记录。 + +## 基本信息 + +- **功能描述**：合并多个 Salesforce 记录 +- **请求方式**：POST +- **请求路径**：`/partner/crud/merge` +- **权限要求**：`@PreAuthorize("@ss.hasLogin()")` + +## 请求参数 + +### 请求体（JSON） + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型 | Account | +| masterRecordId | String | 是 | 主记录 ID（保留的记录） | 001xx0000001Gw2EAA | +| recordToMergeIds | Array[String] | 是 | 要合并的记录 ID 列表 | ["001xx...", "001xx..."] | + +### 请求示例 + +```json +{ + "objectType": "Account", + "masterRecordId": "001xx0000001Gw2EAA", + "recordToMergeIds": [ + "001xx0000001Gw3EAA", + "001xx0000001Gw4EAA" + ] +} +``` + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.id | String | 主记录 ID | +| data.success | Boolean | 是否成功 | +| data.errors | Array | 错误信息列表 | +| data.created | Boolean | 是否创建（合并时为 null） | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "合并成功", + "data": { + "id": "001xx0000001Gw2EAA", + "success": true, + "errors": null, + "created": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "合并记录失败", + "data": { + "id": null, + "success": false, + "errors": [ + { + "statusCode": "CANNOT_EXECUTE_FLOW_TRIGGER", + "message": "The record couldn't be saved because it failed to trigger a flow", + "fields": [] + } + ], + "created": null + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 404 | 记录不存在 | 检查记录 ID 是否正确 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 合并操作是永久性的，无法撤销 +2. 主记录保留，其他记录被删除 +3. 合并的记录必须属于同一对象类型 +4. 某些对象不支持合并操作（如 Opportunity） +5. 合并操作需要对象的编辑和删除权限 +6. 合并可能会触发业务规则和流程 +7. 合并后的记录会保留主记录的所有字段值 +8. 子记录（如 Contact）会重新关联到主记录 + +## 合并规则 + +1. **主记录保留**：主记录的所有字段值保持不变 +2. **从记录删除**：从记录被删除，无法恢复 +3. **子记录重新关联**：从记录的子记录会重新关联到主记录 +4. **共享规则**：合并后的记录继承主记录的共享规则 +5. **审计字段**：CreatedDate 和 CreatedBy 保持主记录的值 + +## 支持的对象 + +支持合并的对象包括： +- Account +- Contact +- Lead +- Solution +- Case + +## 使用场景 + +- 数据清理：合并重复的账户或联系人 +- 客户整合：将同一客户的不同记录合并 +- 数据质量：消除重复数据，提高数据质量 +- 业务需求：根据业务规则合并相关记录 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/001-describe-global.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/001-describe-global.md new file mode 100644 index 00000000..3d60538b --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/001-describe-global.md @@ -0,0 +1,142 @@ +# API 文档 - 描述所有可用对象 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：001 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +获取 Salesforce 中所有可用的对象列表。 + +## 基本信息 + +- **功能描述**：获取 Salesforce 中所有可用的对象列表 +- **请求方式**：GET +- **请求路径**：`/partner/describe/global` +- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:describe:global')")` + +## 请求参数 + +无 + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.sObjects | Array | 对象描述列表 | +| data.sObjects[].name | String | 对象名称 | +| data.sObjects[].label | String | 对象标签 | +| data.sObjects[].keyPrefix | String | 对象键前缀 | +| data.sObjects[].custom | Boolean | 是否为自定义对象 | +| data.sObjects[].createable | Boolean | 是否可创建 | +| data.sObjects[].updateable | Boolean | 是否可更新 | +| data.sObjects[].deletable | Boolean | 是否可删除 | +| data.sObjects[].queryable | Boolean | 是否可查询 | +| data.sObjects[].replicateable | Boolean | 是否可复制 | +| data.sObjects[].retrieveable | Boolean | 是否可检索 | +| data.sObjects[].undeletable | Boolean | 是否可恢复 | +| data.sObjects[].triggerable | Boolean | 是否可触发 | +| data.maxBatchSize | Integer | 最大批次大小 | +| data.success | Boolean | 是否成功 | +| data.errors | Array | 错误信息列表 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "sObjects": [ + { + "name": "Account", + "label": "Account", + "keyPrefix": "001", + "custom": false, + "createable": true, + "updateable": true, + "deletable": true, + "queryable": true, + "replicateable": true, + "retrieveable": true, + "undeletable": true, + "triggerable": true + }, + { + "name": "Contact", + "label": "Contact", + "keyPrefix": "003", + "custom": false, + "createable": true, + "updateable": true, + "deletable": true, + "queryable": true, + "replicateable": true, + "retrieveable": true, + "undeletable": true, + "triggerable": true + } + ], + "maxBatchSize": 200, + "success": true, + "errors": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "描述所有可用对象失败", + "data": { + "sObjects": null, + "maxBatchSize": null, + "success": false, + "errors": [ + { + "statusCode": "UNKNOWN_EXCEPTION", + "message": "Failed to retrieve object descriptions" + } + ] + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 403 | 无权限访问 | 请检查用户权限 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 返回的对象列表包含当前用户有权限访问的所有对象 +2. 自定义对象的 custom 字段为 true +3. keyPrefix 可用于识别记录 ID 的对象类型 +4. maxBatchSize 表示批量操作的最大记录数 +5. 某些对象可能因为权限限制不可访问 +6. 对象列表可能很大，建议缓存结果 + +## 使用场景 + +- 获取所有可用对象列表 +- 动态生成对象选择器 +- 验证对象是否存在 +- 构建元数据浏览器 +- 权限检查和验证 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/002-describe-sobject.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/002-describe-sobject.md new file mode 100644 index 00000000..bc2c4434 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/002-describe-sobject.md @@ -0,0 +1,186 @@ +# API 文档 - 描述特定对象 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：002 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +获取特定对象的详细定义，包含字段列表、子关系、权限信息等。 + +## 基本信息 + +- **功能描述**：获取特定对象的详细定义 +- **请求方式**：POST +- **请求路径**：`/partner/describe/sobject` +- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:describe:sobject')")` + +## 请求参数 + +### 请求体（JSON） + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型（如 Account、Contact） | Account | + +### 请求示例 + +```json +{ + "objectType": "Account" +} +``` + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.sObject | Object | 对象描述 | +| data.sObject.name | String | 对象名称 | +| data.sObject.label | String | 对象标签 | +| data.sObject.keyPrefix | String | 对象键前缀 | +| data.sObject.custom | Boolean | 是否为自定义对象 | +| data.sObject.createable | Boolean | 是否可创建 | +| data.sObject.updateable | Boolean | 是否可更新 | +| data.sObject.deletable | Boolean | 是否可删除 | +| data.sObject.queryable | Boolean | 是否可查询 | +| data.sObject.fields | Array | 字段列表 | +| data.sObject.fields[].name | String | 字段名称 | +| data.sObject.fields[].label | String | 字段标签 | +| data.sObject.fields[].type | String | 字段类型 | +| data.sObject.fields[].length | Integer | 字段长度 | +| data.sObject.fields[].custom | Boolean | 是否为自定义字段 | +| data.sObject.fields[].createable | Boolean | 是否可创建 | +| data.sObject.fields[].updateable | Boolean | 是否可更新 | +| data.sObject.fields[].nillable | Boolean | 是否可为空 | +| data.sObject.fields[].defaultedOnCreate | Boolean | 创建时是否有默认值 | +| data.sObject.childRelationships | Array | 子关系列表 | +| data.success | Boolean | 是否成功 | +| data.errors | Array | 错误信息列表 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "sObject": { + "name": "Account", + "label": "Account", + "keyPrefix": "001", + "custom": false, + "createable": true, + "updateable": true, + "deletable": true, + "queryable": true, + "fields": [ + { + "name": "Id", + "label": "Account ID", + "type": "id", + "length": 18, + "custom": false, + "createable": false, + "updateable": false, + "nillable": false, + "defaultedOnCreate": false + }, + { + "name": "Name", + "label": "Account Name", + "type": "string", + "length": 255, + "custom": false, + "createable": true, + "updateable": true, + "nillable": false, + "defaultedOnCreate": false + }, + { + "name": "Industry", + "label": "Industry", + "type": "picklist", + "length": 40, + "custom": false, + "createable": true, + "updateable": true, + "nillable": true, + "defaultedOnCreate": false + } + ], + "childRelationships": [ + { + "relationshipName": "Contacts", + "childSObject": "Contact", + "field": "AccountId" + }, + { + "relationshipName": "Opportunities", + "childSObject": "Opportunity", + "field": "AccountId" + } + ] + }, + "success": true, + "errors": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "描述特定对象失败", + "data": { + "sObject": null, + "success": false, + "errors": [ + { + "statusCode": "INVALID_TYPE", + "message": "Invalid object type: InvalidObject" + } + ] + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 403 | 无权限访问 | 请检查用户权限 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 对象名称区分大小写 +2. 返回的字段列表包含当前用户有权限访问的所有字段 +3. 字段类型包括：string、int、double、boolean、date、datetime、picklist 等 +4. 子关系列表可用于查询相关对象 +5. 某些字段可能因为权限限制不可访问 +6. 对象描述可能很大，建议缓存结果 + +## 使用场景 + +- 获取对象的完整元数据 +- 动态生成表单 +- 验证字段是否存在 +- 构建查询构建器 +- 权限检查和验证 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/003-describe-sobjects.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/003-describe-sobjects.md new file mode 100644 index 00000000..07e41f84 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/003-describe-sobjects.md @@ -0,0 +1,203 @@ +# API 文档 - 描述多个对象 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：003 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +批量获取多个对象的详细定义。 + +## 基本信息 + +- **功能描述**：批量获取多个对象的详细定义 +- **请求方式**：POST +- **请求路径**：`/partner/describe/sobjects` +- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:describe:sobjects')")` + +## 请求参数 + +### 请求体（JSON） + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectTypes | Array[String] | 是 | 对象类型列表 | ["Account", "Contact", "Opportunity"] | + +### 请求示例 + +```json +{ + "objectTypes": [ + "Account", + "Contact", + "Opportunity" + ] +} +``` + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Array | 响应数据数组 | +| data[].sObject | Object | 对象描述 | +| data[].sObject.name | String | 对象名称 | +| data[].sObject.label | String | 对象标签 | +| data[].sObject.keyPrefix | String | 对象键前缀 | +| data[].sObject.custom | Boolean | 是否为自定义对象 | +| data[].sObject.createable | Boolean | 是否可创建 | +| data[].sObject.updateable | Boolean | 是否可更新 | +| data[].sObject.deletable | Boolean | 是否可删除 | +| data[].sObject.queryable | Boolean | 是否可查询 | +| data[].sObject.fields | Array | 字段列表 | +| data[].sObject.fields[].name | String | 字段名称 | +| data[].sObject.fields[].label | String | 字段标签 | +| data[].sObject.fields[].type | String | 字段类型 | +| data[].sObject.fields[].length | Integer | 字段长度 | +| data[].sObject.fields[].custom | Boolean | 是否为自定义字段 | +| data[].sObject.fields[].createable | Boolean | 是否可创建 | +| data[].sObject.fields[].updateable | Boolean | 是否可更新 | +| data[].sObject.fields[].nillable | Boolean | 是否可为空 | +| data[].success | Boolean | 是否成功 | +| data[].errors | Array | 错误信息列表 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": [ + { + "sObject": { + "name": "Account", + "label": "Account", + "keyPrefix": "001", + "custom": false, + "createable": true, + "updateable": true, + "deletable": true, + "queryable": true, + "fields": [ + { + "name": "Id", + "label": "Account ID", + "type": "id", + "length": 18, + "custom": false, + "createable": false, + "updateable": false, + "nillable": false + }, + { + "name": "Name", + "label": "Account Name", + "type": "string", + "length": 255, + "custom": false, + "createable": true, + "updateable": true, + "nillable": false + } + ] + }, + "success": true, + "errors": null + }, + { + "sObject": { + "name": "Contact", + "label": "Contact", + "keyPrefix": "003", + "custom": false, + "createable": true, + "updateable": true, + "deletable": true, + "queryable": true, + "fields": [ + { + "name": "Id", + "label": "Contact ID", + "type": "id", + "length": 18, + "custom": false, + "createable": false, + "updateable": false, + "nillable": false + }, + { + "name": "FirstName", + "label": "First Name", + "type": "string", + "length": 40, + "custom": false, + "createable": true, + "updateable": true, + "nillable": true + } + ] + }, + "success": true, + "errors": null + } + ] +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "描述多个对象失败", + "data": [ + { + "sObject": null, + "success": false, + "errors": [ + { + "statusCode": "INVALID_TYPE", + "message": "Invalid object type: InvalidObject" + } + ] + } + ] +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 403 | 无权限访问 | 请检查用户权限 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 对象名称区分大小写 +2. 每个对象独立处理，部分失败不影响其他对象 +3. 返回的字段列表包含当前用户有权限访问的所有字段 +4. 批量描述比单个描述更高效，减少 API 调用次数 +5. 某些对象可能因为权限限制不可访问 +6. 建议缓存结果以提高性能 + +## 使用场景 + +- 批量获取多个对象的元数据 +- 动态生成多个对象的表单 +- 验证多个对象是否存在 +- 构建多对象查询构建器 +- 权限检查和验证 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/004-describe-layout.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/004-describe-layout.md new file mode 100644 index 00000000..4ac897c6 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/004-describe-layout.md @@ -0,0 +1,168 @@ +# API 文档 - 描述对象布局 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：004 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +获取对象的页面布局信息。 + +## 基本信息 + +- **功能描述**：获取对象的页面布局信息 +- **请求方式**：POST +- **请求路径**：`/partner/describe/layout` +- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:describe:layout')")` + +## 请求参数 + +### 请求体（JSON） + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 是 | 对象类型（如 Account、Contact） | Account | +| recordTypeId | String | 否 | 记录类型 ID（可选，未指定则返回默认布局） | 012xx0000000001AAA | + +### 请求示例 + +```json +{ + "objectType": "Account", + "recordTypeId": "012xx0000000001AAA" +} +``` + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.layouts | Array | 布局描述列表 | +| data.layouts[].id | String | 布局 ID | +| data.layouts[].name | String | 布局名称 | +| data.layouts[].layoutType | String | 布局类型（如：Compact、Full） | +| data.layouts[].recordTypeId | String | 记录类型 ID | +| data.layouts[].sections | Array | 布局部分列表 | +| data.layouts[].sections[].heading | String | 部分标题 | +| data.layouts[].sections[].columns | Integer | 列数 | +| data.layouts[].sections[].rows | Array | 行列表 | +| data.layouts[].sections[].rows[].layoutItems | Array | 布局项列表 | +| data.layouts[].sections[].rows[].layoutItems[].field | String | 字段名称 | +| data.layouts[].sections[].rows[].layoutItems[].label | String | 字段标签 | +| data.layouts[].sections[].rows[].layoutItems[].required | Boolean | 是否必填 | +| data.success | Boolean | 是否成功 | +| data.errors | Array | 错误信息列表 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "layouts": [ + { + "id": "00hxx0000000001AAA", + "name": "Account Layout", + "layoutType": "Full", + "recordTypeId": "012xx0000000001AAA", + "sections": [ + { + "heading": "Account Information", + "columns": 2, + "rows": [ + { + "layoutItems": [ + { + "field": "Name", + "label": "Account Name", + "required": true + }, + { + "field": "Type", + "label": "Account Type", + "required": false + } + ] + }, + { + "layoutItems": [ + { + "field": "Industry", + "label": "Industry", + "required": false + }, + { + "field": "Phone", + "label": "Phone", + "required": false + } + ] + } + ] + } + ] + } + ], + "success": true, + "errors": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "描述对象布局失败", + "data": { + "layouts": null, + "success": false, + "errors": [ + { + "statusCode": "INVALID_TYPE", + "message": "Invalid object type: InvalidObject" + } + ] + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 403 | 无权限访问 | 请检查用户权限 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 对象名称区分大小写 +2. 如果不指定 recordTypeId，则返回默认布局 +3. 记录类型 ID 必须是有效的记录类型 ID +4. 布局信息包含字段顺序、必填状态等 +5. 某些对象可能没有布局信息 +6. 布局信息可能因为权限限制不可访问 + +## 使用场景 + +- 动态生成表单 +- 获取字段的显示顺序 +- 验证必填字段 +- 构建自定义页面 +- 权限检查和验证 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/005-describe-tabs.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/005-describe-tabs.md new file mode 100644 index 00000000..2a245a7a --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/005-describe-tabs.md @@ -0,0 +1,147 @@ +# API 文档 - 描述标签页 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：005 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +获取 Salesforce 中的所有标签页信息。 + +## 基本信息 + +- **功能描述**：获取 Salesforce 中的所有标签页信息 +- **请求方式**：GET +- **请求路径**：`/partner/describe/tabs` +- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:describe:tabs')")` + +## 请求参数 + +无 + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.tabs | Array | 标签页描述列表 | +| data.tabs[].id | String | 标签页 ID | +| data.tabs[].label | String | 标签页标签 | +| data.tabs[].name | String | 标签页名称 | +| data.tabs[].sobjectName | String | 关联的对象名称 | +| data.tabs[].url | String | 标签页 URL | +| data.tabs[].iconUrl | String | 图标 URL | +| data.tabs[].custom | Boolean | 是否为自定义标签页 | +| data.tabs[].visible | Boolean | 是否可见 | +| data.success | Boolean | 是否成功 | +| data.errors | Array | 错误信息列表 | + +### 成功响应示例 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "tabs": [ + { + "id": "01rxx0000000001AAA", + "label": "Home", + "name": "home", + "sobjectName": null, + "url": "/home/home.jsp", + "iconUrl": "/img/icon/home16.png", + "custom": false, + "visible": true + }, + { + "id": "01rxx0000000002AAA", + "label": "Accounts", + "name": "Account", + "sobjectName": "Account", + "url": "/001", + "iconUrl": "/img/icon/account16.png", + "custom": false, + "visible": true + }, + { + "id": "01rxx0000000003AAA", + "label": "Contacts", + "name": "Contact", + "sobjectName": "Contact", + "url": "/003", + "iconUrl": "/img/icon/contact16.png", + "custom": false, + "visible": true + }, + { + "id": "01rxx0000000004AAA", + "label": "Opportunities", + "name": "Opportunity", + "sobjectName": "Opportunity", + "url": "/006", + "iconUrl": "/img/icon/opportunity16.png", + "custom": false, + "visible": true + } + ], + "success": true, + "errors": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "描述标签页失败", + "data": { + "tabs": null, + "success": false, + "errors": [ + { + "statusCode": "UNKNOWN_EXCEPTION", + "message": "Failed to retrieve tab descriptions" + } + ] + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 403 | 无权限访问 | 请检查用户权限 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 返回的标签页列表包含当前用户有权限访问的所有标签页 +2. 自定义标签页的 custom 字段为 true +3. visible 字段表示标签页是否对用户可见 +4. sobjectName 为 null 表示标签页不是对象标签页 +5. 某些标签页可能因为权限限制不可访问 +6. 标签页列表可能很大，建议缓存结果 + +## 使用场景 + +- 获取所有可用标签页 +- 动态生成导航菜单 +- 验证标签页是否存在 +- 构建自定义导航 +- 权限检查和验证 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/006-describe-quick-actions.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/006-describe-quick-actions.md new file mode 100644 index 00000000..060c622e --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerDescribeController/006-describe-quick-actions.md @@ -0,0 +1,209 @@ +# API 文档 - 描述快速操作 + +## 元数据 +- 需求编号：001 +- 子需求编号：001-01 +- 接口编号：006 +- 创建时间：2026-02-02 +- 创建人：AI Assistant +- 状态：已完成 + +## 接口概述 +获取对象的快速操作定义。 + +## 基本信息 + +- **功能描述**：获取对象的快速操作定义 +- **请求方式**：POST +- **请求路径**：`/partner/describe/quick-actions` +- **权限要求**：`@PreAuthorize("@ss.hasPermi('partner:describe:quickActions')")` + +## 请求参数 + +### 请求体（JSON） + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| objectType | String | 否 | 对象类型（可选，如 Account、Contact） | Account | + +### 请求示例 + +```json +{ + "objectType": "Account" +} +``` + +### 请求示例（不指定对象类型） + +```json +{} +``` + +## 响应参数 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 状态码（200 成功，其他失败） | +| msg | String | 提示信息 | +| data | Object | 响应数据 | +| data.quickActions | Array | 快速操作描述列表 | +| data.quickActions[].id | String | 快速操作 ID | +| data.quickActions[].name | String | 快速操作名称 | +| data.quickActions[].label | String | 快速操作标签 | +| data.quickActions[].type | String | 快速操作类型（如：Create、Update、Custom） | +| data.quickActions[].actionType | String | 操作类型（如：Create、Update、Delete） | +| data.quickActions[].targetObject | String | 目标对象 | +| data.quickActions[].targetParentField | String | 目标父字段 | +| data.quickActions[].url | String | 快速操作 URL | +| data.quickActions[].iconUrl | String | 图标 URL | +| data.quickActions[].custom | Boolean | 是否为自定义快速操作 | +| data.quickActions[].standard | Boolean | 是否为标准快速操作 | +| data.success | Boolean | 是否成功 | +| data.errors | Array | 错误信息列表 | + +### 成功响应示例（指定对象类型） + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "quickActions": [ + { + "id": "01ixx0000000001AAA", + "name": "NewAccount", + "label": "New Account", + "type": "Create", + "actionType": "Create", + "targetObject": "Account", + "targetParentField": null, + "url": "/001/e", + "iconUrl": "/img/icon/account16.png", + "custom": false, + "standard": true + }, + { + "id": "01ixx0000000002AAA", + "name": "LogACall", + "label": "Log a Call", + "type": "Update", + "actionType": "Update", + "targetObject": "Task", + "targetParentField": "WhatId", + "url": "/00T/e", + "iconUrl": "/img/icon/task16.png", + "custom": false, + "standard": true + }, + { + "id": "01ixx0000000003AAA", + "name": "SendEmail", + "label": "Send Email", + "type": "Custom", + "actionType": "Custom", + "targetObject": null, + "targetParentField": null, + "url": "/_ui/core/email/author/EmailAuthor?p2_lkid={!Account.Id}", + "iconUrl": "/img/icon/email16.png", + "custom": true, + "standard": false + } + ], + "success": true, + "errors": null + } +} +``` + +### 成功响应示例（不指定对象类型） + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "quickActions": [ + { + "id": "01ixx0000000001AAA", + "name": "NewAccount", + "label": "New Account", + "type": "Create", + "actionType": "Create", + "targetObject": "Account", + "targetParentField": null, + "url": "/001/e", + "iconUrl": "/img/icon/account16.png", + "custom": false, + "standard": true + }, + { + "id": "01ixx0000000004AAA", + "name": "NewContact", + "label": "New Contact", + "type": "Create", + "actionType": "Create", + "targetObject": "Contact", + "targetParentField": null, + "url": "/003/e", + "iconUrl": "/img/icon/contact16.png", + "custom": false, + "standard": true + } + ], + "success": true, + "errors": null + } +} +``` + +### 失败响应示例 + +```json +{ + "code": 500, + "msg": "描述快速操作失败", + "data": { + "quickActions": null, + "success": false, + "errors": [ + { + "statusCode": "INVALID_TYPE", + "message": "Invalid object type: InvalidObject" + } + ] + } +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 200 | 操作成功 | - | +| 400 | 请求参数错误 | 检查请求参数格式和必填项 | +| 401 | 未登录或登录已过期 | 请重新登录 | +| 403 | 无权限访问 | 请检查用户权限 | +| 500 | 服务器内部错误 | 请联系管理员或稍后重试 | + +## 注意事项 + +1. 如果不指定 objectType，则返回所有快速操作 +2. 指定 objectType 则只返回该对象的快速操作 +3. 快速操作类型包括：Create、Update、Delete、Custom 等 +4. 自定义快速操作的 custom 字段为 true +5. 某些快速操作可能因为权限限制不可访问 +6. 快速操作列表可能很大，建议缓存结果 + +## 使用场景 + +- 获取对象的快速操作 +- 动态生成快速操作菜单 +- 验证快速操作是否存在 +- 构建自定义快速操作 +- 权限检查和验证 + +## 相关文档 +- [需求文档](../../requirements/2026-01-28-001-PartnerAPI源org实现.md) +- [设计文档](../../design/2026-01-29-001-01-认证和会话管理-设计.md) +- [决策记录](../../decisions/2026-01-29-001-01-ADR-认证和会话管理技术选型.md) diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerQueryController/001-query.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerQueryController/001-query.md new file mode 100644 index 00000000..7eb962f0 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerQueryController/001-query.md @@ -0,0 +1,174 @@ +# 执行 SOQL 查询 + +## 接口概述 + +执行标准的 SOQL (Salesforce Object Query Language) 查询语句，从 Salesforce 获取数据。 + +## 基本信息 + +| 属性 | 值 | +|------|-----| +| 接口名称 | 执行 SOQL 查询 | +| 接口路径 | `/partner/query` | +| 请求方法 | `POST` | +| Content-Type | `application/json` | +| 需要认证 | 是 | +| 所属模块 | datai-salesforce-partner | + +## 请求参数 + +### 请求体 (Request Body) + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| soql | String | 是 | SOQL 查询语句 | `SELECT Id, Name FROM Account LIMIT 10` | +| batchSize | Integer | 否 | 批次大小，默认 500，最大 2000 | `500` | + +### 请求示例 + +```json +{ + "soql": "SELECT Id, Name, BillingCity, Industry FROM Account WHERE Industry = 'Technology' LIMIT 10", + "batchSize": 500 +} +``` + +## 响应参数 + +### 响应体 (Response Body) + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 响应状态码，200 表示成功 | +| msg | String | 响应消息 | +| data | Object | 响应数据 | + +### data 对象结构 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| records | Array | 记录列表，每个记录是一个键值对对象 | +| queryLocator | String | 查询定位器，用于 QueryMore 获取下一页 | +| done | Boolean | 是否完成（true 表示没有更多数据） | +| size | Integer | 记录数量 | +| success | Boolean | 是否成功 | +| errors | Array | 错误信息列表 | + +### 响应示例 + +**成功响应** + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "records": [ + { + "Id": "001xx000003DHb2AAG", + "Name": "Acme Corporation", + "BillingCity": "San Francisco", + "Industry": "Technology" + }, + { + "Id": "001xx000003DHb3AAH", + "Name": "Tech Solutions Inc", + "BillingCity": "New York", + "Industry": "Technology" + } + ], + "queryLocator": "01gD0000002J6ozIAC-2000", + "done": false, + "size": 2, + "success": true, + "errors": [] + } +} +``` + +**错误响应** + +```json +{ + "code": 500, + "msg": "SOQL 查询失败: Invalid query", + "data": null +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 400 | 请求参数错误 | 检查 soql 语句格式是否正确 | +| 401 | 认证失败 | 检查 Salesforce 认证信息是否有效 | +| 500 | 服务器内部错误 | 检查 SOQL 语句语法是否正确 | + +## 使用说明 + +### SOQL 语法示例 + +1. **基本查询** + +```json +{ + "soql": "SELECT Id, Name FROM Account" +} +``` + +2. **带条件查询** + +```json +{ + "soql": "SELECT Id, Name, BillingCity FROM Account WHERE Industry = 'Technology' AND BillingCity = 'San Francisco'" +} +``` + +3. **排序和限制** + +```json +{ + "soql": "SELECT Id, Name, CreatedDate FROM Account ORDER BY CreatedDate DESC LIMIT 10" +} +``` + +4. **关联查询** + +```json +{ + "soql": "SELECT Id, Name, Account.Name, Account.Industry FROM Contact WHERE Account.Industry = 'Technology'" +} +``` + +5. **聚合查询** + +```json +{ + "soql": "SELECT Industry, COUNT(Id) FROM Account GROUP BY Industry" +} +``` + +### 分页处理 + +当查询结果超过批次大小时，使用返回的 `queryLocator` 调用 `queryMore` 接口获取下一页数据。 + +### 注意事项 + +1. SOQL 语句必须以 `SELECT` 开头 +2. 批次大小范围：1-2000，默认 500 +3. 查询结果最大记录数限制为 50,000 +4. 复杂查询可能超时，建议添加适当的过滤条件和 LIMIT +5. 字段名区分大小写 +6. 字符串值需要用单引号包裹 + +## 相关接口 + +- [获取查询结果的下一页](./003-query-more.md) +- [查询所有记录（包括已删除的）](./002-query-all.md) +- [执行 SOSL 搜索](./004-search.md) + +## 更新日志 + +| 版本 | 日期 | 更新内容 | 作者 | +|------|------|----------|------| +| 1.0.0 | 2026-01-30 | 初始版本 | AI Assistant | diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerQueryController/002-query-all.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerQueryController/002-query-all.md new file mode 100644 index 00000000..172e87d2 --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerQueryController/002-query-all.md @@ -0,0 +1,171 @@ +# 查询所有记录（包括已删除的） + +## 接口概述 + +查询所有记录，包括已删除的记录（回收站中的记录）。使用 QueryAll 可以检索已删除但未从回收站中永久删除的记录。 + +## 基本信息 + +| 属性 | 值 | +|------|-----| +| 接口名称 | 查询所有记录 | +| 接口路径 | `/partner/queryAll` | +| 请求方法 | `POST` | +| Content-Type | `application/json` | +| 需要认证 | 是 | +| 所属模块 | datai-salesforce-partner | + +## 请求参数 + +### 请求体 (Request Body) + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| soql | String | 是 | SOQL 查询语句 | `SELECT Id, Name FROM Account LIMIT 10` | +| batchSize | Integer | 否 | 批次大小，默认 500，最大 2000 | `500` | + +### 请求示例 + +```json +{ + "soql": "SELECT Id, Name, IsDeleted FROM Account WHERE IsDeleted = true LIMIT 10", + "batchSize": 500 +} +``` + +## 响应参数 + +### 响应体 (Response Body) + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 响应状态码，200 表示成功 | +| msg | String | 响应消息 | +| data | Object | 响应数据 | + +### data 对象结构 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| records | Array | 记录列表，每个记录是一个键值对对象 | +| queryLocator | String | 查询定位器，用于 QueryMore 获取下一页 | +| done | Boolean | 是否完成（true 表示没有更多数据） | +| size | Integer | 记录数量 | +| success | Boolean | 是否成功 | +| errors | Array | 错误信息列表 | + +### 响应示例 + +**成功响应** + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "records": [ + { + "Id": "001xx000003DHb2AAG", + "Name": "Acme Corporation", + "IsDeleted": true + }, + { + "Id": "001xx000003DHb3AAH", + "Name": "Tech Solutions Inc", + "IsDeleted": true + } + ], + "queryLocator": "01gD0000002J6ozIAC-2000", + "done": false, + "size": 2, + "success": true, + "errors": [] + } +} +``` + +**错误响应** + +```json +{ + "code": 500, + "msg": "QueryAll 查询失败: Invalid query", + "data": null +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 400 | 请求参数错误 | 检查 soql 语句格式是否正确 | +| 401 | 认证失败 | 检查 Salesforce 认证信息是否有效 | +| 500 | 服务器内部错误 | 检查 SOQL 语句语法是否正确 | + +## 使用说明 + +### QueryAll 与 Query 的区别 + +| 特性 | Query | QueryAll | +|------|-------|----------| +| 查询范围 | 仅查询未删除的记录 | 查询所有记录，包括已删除的 | +| 性能 | 更快 | 稍慢 | +| 使用场景 | 正常业务查询 | 数据恢复、审计、回收站管理 | + +### 常用查询场景 + +1. **查询已删除的账户** + +```json +{ + "soql": "SELECT Id, Name, CreatedDate, LastModifiedDate FROM Account WHERE IsDeleted = true ORDER BY LastModifiedDate DESC LIMIT 10" +} +``` + +2. **查询特定时间范围内删除的记录** + +```json +{ + "soql": "SELECT Id, Name, DeletedDate FROM Account WHERE IsDeleted = true AND DeletedDate >= 2026-01-01T00:00:00Z" +} +``` + +3. **查询所有记录（包括已删除的）** + +```json +{ + "soql": "SELECT Id, Name, IsDeleted FROM Account ORDER BY CreatedDate DESC LIMIT 10" +} +``` + +4. **查询已删除的联系人及其账户信息** + +```json +{ + "soql": "SELECT Id, FirstName, LastName, Account.Name, IsDeleted FROM Contact WHERE IsDeleted = true" +} +``` + +### 数据恢复 + +查询到已删除的记录后，可以使用 `Undelete` 操作恢复记录（需要通过 CRUD 接口实现）。 + +### 注意事项 + +1. QueryAll 只能查询仍在回收站中的记录 +2. 已永久删除的记录无法通过 QueryAll 查询 +3. 回收站中的记录会根据 Salesforce 的保留策略自动清理 +4. 查询性能可能低于普通 Query +5. 建议在查询时添加适当的过滤条件和 LIMIT 以提高性能 + +## 相关接口 + +- [执行 SOQL 查询](./001-query.md) +- [获取查询结果的下一页](./003-query-more.md) +- [执行 SOSL 搜索](./004-search.md) + +## 更新日志 + +| 版本 | 日期 | 更新内容 | 作者 | +|------|------|----------|------| +| 1.0.0 | 2026-01-30 | 初始版本 | AI Assistant | diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerQueryController/003-query-more.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerQueryController/003-query-more.md new file mode 100644 index 00000000..f685674c --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerQueryController/003-query-more.md @@ -0,0 +1,225 @@ +# 获取查询结果的下一页 + +## 接口概述 + +使用 queryLocator 获取查询结果的下一页数据。当查询结果超过批次大小时，可以通过此接口分页获取剩余数据。 + +## 基本信息 + +| 属性 | 值 | +|------|-----| +| 接口名称 | 获取查询结果的下一页 | +| 接口路径 | `/partner/queryMore` | +| 请求方法 | `POST` | +| Content-Type | `application/json` | +| 需要认证 | 是 | +| 所属模块 | datai-salesforce-partner | + +## 请求参数 + +### 请求体 (Request Body) + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| queryLocator | String | 是 | 查询定位器，从 Query 或 QueryAll 的结果中获取 | `01gD0000002J6ozIAC-2000` | + +### 请求示例 + +```json +{ + "queryLocator": "01gD0000002J6ozIAC-2000" +} +``` + +## 响应参数 + +### 响应体 (Response Body) + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 响应状态码，200 表示成功 | +| msg | String | 响应消息 | +| data | Object | 响应数据 | + +### data 对象结构 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| records | Array | 记录列表，每个记录是一个键值对对象 | +| queryLocator | String | 查询定位器，用于继续获取下一页 | +| done | Boolean | 是否完成（true 表示没有更多数据） | +| size | Integer | 当前页记录数量 | +| success | Boolean | 是否成功 | +| errors | Array | 错误信息列表 | + +### 响应示例 + +**成功响应（还有更多数据）** + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "records": [ + { + "Id": "001xx000003DHb4AAI", + "Name": "Global Tech Solutions", + "BillingCity": "Los Angeles", + "Industry": "Technology" + }, + { + "Id": "001xx000003DHb5AAJ", + "Name": "Innovate Corp", + "BillingCity": "Chicago", + "Industry": "Technology" + } + ], + "queryLocator": "01gD0000002J6ozIAC-4000", + "done": false, + "size": 2, + "success": true, + "errors": [] + } +} +``` + +**成功响应（最后一页）** + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "records": [ + { + "Id": "001xx000003DHb6AAK", + "Name": "Future Systems", + "BillingCity": "Boston", + "Industry": "Technology" + } + ], + "queryLocator": null, + "done": true, + "size": 1, + "success": true, + "errors": [] + } +} +``` + +**错误响应** + +```json +{ + "code": 500, + "msg": "QueryMore 查询失败: Invalid query locator", + "data": null +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 400 | 请求参数错误 | 检查 queryLocator 是否有效 | +| 401 | 认证失败 | 检查 Salesforce 认证信息是否有效 | +| 404 | 查询定位器不存在 | queryLocator 可能已过期或无效 | +| 500 | 服务器内部错误 | 检查 queryLocator 格式是否正确 | + +## 使用说明 + +### 分页查询流程 + +1. **首次查询** + +调用 `query` 或 `queryAll` 接口获取第一批数据： + +```json +{ + "soql": "SELECT Id, Name, BillingCity FROM Account", + "batchSize": 500 +} +``` + +2. **检查是否还有更多数据** + +查看响应中的 `done` 字段： +- `done: false` - 还有更多数据 +- `done: true` - 已获取所有数据 + +3. **获取下一页** + +如果 `done` 为 false，使用返回的 `queryLocator` 调用 `queryMore`： + +```json +{ + "queryLocator": "01gD0000002J6ozIAC-2000" +} +``` + +4. **重复步骤 2-3** + +直到 `done` 为 true。 + +### 完整分页示例 + +```javascript +// 伪代码示例 +let queryLocator = null; +let allRecords = []; + +// 首次查询 +const firstResult = await query({ + soql: "SELECT Id, Name FROM Account", + batchSize: 500 +}); +allRecords = allRecords.concat(firstResult.data.records); +queryLocator = firstResult.data.queryLocator; + +// 循环获取剩余数据 +while (queryLocator && !firstResult.data.done) { + const result = await queryMore({ queryLocator }); + allRecords = allRecords.concat(result.data.records); + queryLocator = result.data.queryLocator; + + if (result.data.done) { + break; + } +} + +console.log(`总共获取 ${allRecords.length} 条记录`); +``` + +### 注意事项 + +1. **queryLocator 有效期** + - queryLocator 在查询会话期间有效 + - 会话超时后 queryLocator 会失效 + - 建议在合理时间内完成分页查询 + +2. **批次大小** + - 首次查询的 batchSize 决定每页的记录数 + - queryMore 无法修改批次大小 + - 建议根据实际需求设置合适的批次大小 + +3. **性能优化** + - 避免一次性获取过多数据 + - 根据业务需求合理设置批次大小 + - 考虑使用更精确的查询条件减少数据量 + +4. **错误处理** + - 捕获并处理 queryLocator 过期的情况 + - 当 queryLocator 失效时，需要重新执行初始查询 + +## 相关接口 + +- [执行 SOQL 查询](./001-query.md) +- [查询所有记录（包括已删除的）](./002-query-all.md) +- [执行 SOSL 搜索](./004-search.md) + +## 更新日志 + +| 版本 | 日期 | 更新内容 | 作者 | +|------|------|----------|------| +| 1.0.0 | 2026-01-30 | 初始版本 | AI Assistant | diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerQueryController/004-search.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerQueryController/004-search.md new file mode 100644 index 00000000..7eb3ad3b --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerQueryController/004-search.md @@ -0,0 +1,238 @@ +# 执行 SOSL 搜索 + +## 接口概述 + +执行 SOSL (Salesforce Object Search Language) 全文搜索，在多个对象中快速查找匹配的记录。 + +## 基本信息 + +| 属性 | 值 | +|------|-----| +| 接口名称 | 执行 SOSL 搜索 | +| 接口路径 | `/partner/search` | +| 请求方法 | `POST` | +| Content-Type | `application/json` | +| 需要认证 | 是 | +| 所属模块 | datai-salesforce-partner | + +## 请求参数 + +### 请求体 (Request Body) + +| 参数名 | 类型 | 必填 | 说明 | 示例值 | +|--------|------|------|------|--------| +| sosl | String | 是 | SOSL 搜索语句 | `FIND {Acme} IN ALL FIELDS RETURNING Account(Id, Name), Contact(Id, Name)` | + +### 请求示例 + +```json +{ + "sosl": "FIND {Acme} IN ALL FIELDS RETURNING Account(Id, Name, BillingCity), Contact(Id, FirstName, LastName, Email)" +} +``` + +## 响应参数 + +### 响应体 (Response Body) + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| code | Integer | 响应状态码，200 表示成功 | +| msg | String | 响应消息 | +| data | Object | 响应数据 | + +### data 对象结构 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| searchRecords | Array | 搜索结果列表 | +| success | Boolean | 是否成功 | +| errors | Array | 错误信息列表 | + +### searchRecords 对象结构 + +| 参数名 | 类型 | 说明 | +|--------|------|------| +| objectName | String | 对象名称 | +| records | Array | 该对象的匹配记录列表 | + +### 响应示例 + +**成功响应** + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "searchRecords": [ + { + "objectName": "Account", + "records": [ + { + "Id": "001xx000003DHb2AAG", + "Name": "Acme Corporation", + "BillingCity": "San Francisco" + }, + { + "Id": "001xx000003DHb3AAH", + "Name": "Acme Solutions", + "BillingCity": "New York" + } + ] + }, + { + "objectName": "Contact", + "records": [ + { + "Id": "003xx000003DHb2AAG", + "FirstName": "John", + "LastName": "Acme", + "Email": "john.acme@example.com" + } + ] + } + ], + "success": true, + "errors": [] + } +} +``` + +**错误响应** + +```json +{ + "code": 500, + "msg": "SOSL 搜索失败: Invalid search query", + "data": null +} +``` + +## 错误码 + +| 错误码 | 说明 | 处理建议 | +|--------|------|----------| +| 400 | 请求参数错误 | 检查 sosl 语句格式是否正确 | +| 401 | 认证失败 | 检查 Salesforce 认证信息是否有效 | +| 500 | 服务器内部错误 | 检查 SOSL 语句语法是否正确 | + +## 使用说明 + +### SOSL 语法结构 + +``` +FIND {搜索词} IN {搜索范围} RETURNING {对象列表} +``` + +### 搜索范围选项 + +| 搜索范围 | 说明 | +|----------|------| +| ALL FIELDS | 所有可搜索字段 | +| NAME FIELDS | 名称字段 | +| EMAIL FIELDS | 邮箱字段 | +| PHONE FIELDS | 电话字段 | +| SIDEBAR FIELDS | 侧边栏字段 | + +### SOSL 语法示例 + +1. **基本搜索** + +```json +{ + "sosl": "FIND {Acme} IN ALL FIELDS RETURNING Account(Id, Name)" +} +``` + +2. **多对象搜索** + +```json +{ + "sosl": "FIND {Technology} IN ALL FIELDS RETURNING Account(Id, Name, Industry), Contact(Id, FirstName, LastName), Opportunity(Id, Name, Amount)" +} +``` + +3. **指定搜索范围** + +```json +{ + "sosl": "FIND {john@example.com} IN EMAIL FIELDS RETURNING Contact(Id, FirstName, LastName, Email), Lead(Id, FirstName, LastName, Email)" +} +``` + +4. **限制结果数量** + +```json +{ + "sosl": "FIND {Acme} IN NAME FIELDS RETURNING Account(Id, Name, BillingCity LIMIT 10), Contact(Id, FirstName, LastName LIMIT 5)" +} +``` + +5. **带条件的搜索** + +```json +{ + "sosl": "FIND {Technology} IN ALL FIELDS RETURNING Account(Id, Name, Industry WHERE Industry = 'Technology' LIMIT 10)" +} +``` + +6. **短语搜索** + +```json +{ + "sosl": "FIND {\"San Francisco\"} IN ALL FIELDS RETURNING Account(Id, Name, BillingCity)" +} +``` + +7. **通配符搜索** + +```json +{ + "sosl": "FIND {Acme*} IN ALL FIELDS RETURNING Account(Id, Name)" +} +``` + +### SOSL 与 SOQL 的区别 + +| 特性 | SOSL | SOQL | +|------|------|------| +| 搜索类型 | 全文搜索 | 精确查询 | +| 搜索范围 | 多个对象 | 单个对象 | +| 搜索字段 | 可搜索字段 | 任意字段 | +| 性能 | 适合模糊搜索 | 适合精确查询 | +| 使用场景 | 全局搜索、快速查找 | 数据报表、复杂查询 | + +### 注意事项 + +1. **搜索词限制** + - 搜索词长度至少 2 个字符 + - 不区分大小写 + - 支持通配符 (*) + +2. **结果限制** + - 每个对象最多返回 200 条记录 + - 总记录数限制为 2000 条 + - 建议使用 LIMIT 限制结果数量 + +3. **性能优化** + - 避免使用过于宽泛的搜索词 + - 合理使用搜索范围缩小结果集 + - 限制返回的对象和字段数量 + +4. **特殊字符** + - 短语搜索需要使用双引号 + - 转义特殊字符：\, *, ", ' + - 空格表示 AND 关系 + +## 相关接口 + +- [执行 SOQL 查询](./001-query.md) +- [查询所有记录（包括已删除的）](./002-query-all.md) +- [获取查询结果的下一页](./003-query-more.md) + +## 更新日志 + +| 版本 | 日期 | 更新内容 | 作者 | +|------|------|----------|------| +| 1.0.0 | 2026-01-30 | 初始版本 | AI Assistant | diff --git a/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/index.md b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/index.md new file mode 100644 index 00000000..2685100d --- /dev/null +++ b/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/index.md @@ -0,0 +1,232 @@ +# Partner API 接口文档索引 + +## 概述 + +本文档是 `datai-salesforce-partner` 模块所有 API 接口文档的唯一真源索引，记录了所有已创建的接口文档及其元数据。 + +## 文档元数据 + +| 属性 | 值 | +|------|-----| +| 文档名称 | Partner API 接口文档索引 | +| 文档编号 | PARTNER-API-INDEX-001 | +| 创建日期 | 2026-02-02 | +| 最后更新 | 2026-02-02 | +| 状态 | 已完成 | +| 维护者 | AI Assistant | + +## 文档统计 + +| Controller | 文档数量 | 接口数量 | +|------------|----------|----------| +| PartnerAdvancedController | 5 | 5 | +| PartnerBatchController | 4 | 4 | +| PartnerConnectionController | 3 | 3 | +| PartnerCrudController | 6 | 6 | +| PartnerDescribeController | 6 | 6 | +| PartnerQueryController | 4 | 4 | +| **总计** | **28** | **28** | + +--- + +## 1. PartnerAdvancedController - 高级功能接口 + +### 接口列表 + +| 序号 | 文档名称 | 接口路径 | 接口名称 | 状态 | +|------|----------|----------|----------|------| +| 1 | [001-convert-lead.md](./PartnerAdvancedController/001-convert-lead.md) | `/partner/convertLead` | 转换潜在客户 | ✅ 已完成 | +| 2 | [002-empty-recycle-bin.md](./PartnerAdvancedController/002-empty-recycle-bin.md) | `/partner/emptyRecycleBin` | 清空回收站 | ✅ 已完成 | +| 3 | [003-process-submit-request.md](./PartnerAdvancedController/003-process-submit-request.md) | `/partner/processSubmitRequest` | 提交流程请求 | ✅ 已完成 | +| 4 | [004-get-user-info.md](./PartnerAdvancedController/004-get-user-info.md) | `/partner/getUserInfo` | 获取用户信息 | ✅ 已完成 | +| 5 | [005-get-server-timestamp.md](./PartnerAdvancedController/005-get-server-timestamp.md) | `/partner/getServerTimestamp` | 获取服务器时间戳 | ✅ 已完成 | + +### 功能说明 + +提供 Salesforce 高级功能接口，包括潜在客户转换、回收站管理、流程请求处理、用户信息获取等。 + +--- + +## 2. PartnerBatchController - 批量操作接口 + +### 接口列表 + +| 序号 | 文档名称 | 接口路径 | 接口名称 | 状态 | +|------|----------|----------|----------|------| +| 1 | [001-batch-create.md](./PartnerBatchController/001-batch-create.md) | `/partner/batchCreate` | 批量创建记录 | ✅ 已完成 | +| 2 | [002-batch-update.md](./PartnerBatchController/002-batch-update.md) | `/partner/batchUpdate` | 批量更新记录 | ✅ 已完成 | +| 3 | [003-batch-delete.md](./PartnerBatchController/003-batch-delete.md) | `/partner/batchDelete` | 批量删除记录 | ✅ 已完成 | +| 4 | [004-batch-upsert.md](./PartnerBatchController/004-batch-upsert.md) | `/partner/batchUpsert` | 批量 Upsert 记录 | ✅ 已完成 | + +### 功能说明 + +提供批量操作接口，支持批量创建、更新、删除和 Upsert 记录，提高数据操作效率。 + +--- + +## 3. PartnerConnectionController - 连接管理接口 + +### 接口列表 + +| 序号 | 文档名称 | 接口路径 | 接口名称 | 状态 | +|------|----------|----------|----------|------| +| 1 | [001-get-session-info.md](./PartnerConnectionController/001-get-session-info.md) | `/partner/getSessionInfo` | 获取会话信息 | ✅ 已完成 | +| 2 | [002-get-user-info.md](./PartnerConnectionController/002-get-user-info.md) | `/partner/getUserInfo` | 获取用户信息 | ✅ 已完成 | +| 3 | [003-change-password.md](./PartnerConnectionController/003-change-password.md) | `/partner/changePassword` | 修改密码 | ✅ 已完成 | + +### 功能说明 + +提供连接管理接口，包括会话信息获取、用户信息获取和密码修改等。 + +--- + +## 4. PartnerCrudController - CRUD 操作接口 + +### 接口列表 + +| 序号 | 文档名称 | 接口路径 | 接口名称 | 状态 | +|------|----------|----------|----------|------| +| 1 | [001-create-record.md](./PartnerCrudController/001-create-record.md) | `/partner/createRecord` | 创建记录 | ✅ 已完成 | +| 2 | [002-retrieve-record.md](./PartnerCrudController/002-retrieve-record.md) | `/partner/retrieveRecord` | 检索记录 | ✅ 已完成 | +| 3 | [003-update-record.md](./PartnerCrudController/003-update-record.md) | `/partner/updateRecord` | 更新记录 | ✅ 已完成 | +| 4 | [004-delete-record.md](./PartnerCrudController/004-delete-record.md) | `/partner/deleteRecord` | 删除记录 | ✅ 已完成 | +| 5 | [005-upsert-record.md](./PartnerCrudController/005-upsert-record.md) | `/partner/upsertRecord` | Upsert 记录 | ✅ 已完成 | +| 6 | [006-merge-records.md](./PartnerCrudController/006-merge-records.md) | `/partner/mergeRecords` | 合并记录 | ✅ 已完成 | + +### 功能说明 + +提供完整的 CRUD 操作接口，支持记录的创建、检索、更新、删除、Upsert 和合并操作。 + +--- + +## 5. PartnerDescribeController - 对象描述接口 + +### 接口列表 + +| 序号 | 文档名称 | 接口路径 | 接口名称 | 状态 | +|------|----------|----------|----------|------| +| 1 | [001-describe-global.md](./PartnerDescribeController/001-describe-global.md) | `/partner/describeGlobal` | 描述所有可用对象 | ✅ 已完成 | +| 2 | [002-describe-sobject.md](./PartnerDescribeController/002-describe-sobject.md) | `/partner/describeSObject` | 描述特定对象 | ✅ 已完成 | +| 3 | [003-describe-sobjects.md](./PartnerDescribeController/003-describe-sobjects.md) | `/partner/describeSObjects` | 描述多个对象 | ✅ 已完成 | +| 4 | [004-describe-layout.md](./PartnerDescribeController/004-describe-layout.md) | `/partner/describeLayout` | 描述对象布局 | ✅ 已完成 | +| 5 | [005-describe-tabs.md](./PartnerDescribeController/005-describe-tabs.md) | `/partner/describeTabs` | 描述标签页 | ✅ 已完成 | +| 6 | [006-describe-quick-actions.md](./PartnerDescribeController/006-describe-quick-actions.md) | `/partner/describeQuickActions` | 描述快速操作 | ✅ 已完成 | + +### 功能说明 + +提供对象描述接口，用于获取 Salesforce 对象的元数据信息，包括对象结构、字段定义、布局信息等。 + +--- + +## 6. PartnerQueryController - 查询接口 + +### 接口列表 + +| 序号 | 文档名称 | 接口路径 | 接口名称 | 状态 | +|------|----------|----------|----------|------| +| 1 | [001-query.md](./PartnerQueryController/001-query.md) | `/partner/query` | 执行 SOQL 查询 | ✅ 已完成 | +| 2 | [002-query-all.md](./PartnerQueryController/002-query-all.md) | `/partner/queryAll` | 查询所有记录（包括已删除的） | ✅ 已完成 | +| 3 | [003-query-more.md](./PartnerQueryController/003-query-more.md) | `/partner/queryMore` | 获取查询结果的下一页 | ✅ 已完成 | +| 4 | [004-search.md](./PartnerQueryController/004-search.md) | `/partner/search` | 执行 SOSL 搜索 | ✅ 已完成 | + +### 功能说明 + +提供查询接口，支持 SOQL 查询、QueryAll 查询（包括已删除记录）、分页查询和 SOSL 全文搜索。 + +--- + +## 文档变更日志 + +| 版本 | 日期 | 变更内容 | 作者 | +|------|------|----------|------| +| 1.0.0 | 2026-02-02 | 初始版本，创建所有 28 个接口文档的索引 | AI Assistant | + +--- + +## 交叉引用 + +### 相关文档 + +- [datai-scene-salesforce 模块文档](../../index.md) +- [Partner API 总览](../partner-api-overview.md) + +### 外部链接 + +- [Salesforce Partner API 官方文档](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/) + +--- + +## 维护说明 + +### 文档更新规则 + +1. **新增接口**：当添加新的接口时，必须： + - 创建对应的接口文档 + - 更新本文档索引 + - 更新文档统计信息 + - 添加变更日志记录 + +2. **修改接口**：当修改现有接口时，必须： + - 更新对应的接口文档 + - 更新接口文档的版本号和变更日志 + - 在本文档中记录变更 + +3. **删除接口**：当删除接口时，必须： + - 标记对应的接口文档为已废弃 + - 更新本文档索引状态 + - 添加变更日志记录 + +### 文档命名规范 + +- Controller 文档夹：`{ControllerName}` +- 接口文档：`{序号}-{接口名称}.md` +- 序号格式：3 位数字，从 001 开始递增 + +### 文档模板 + +所有接口文档应遵循统一的模板格式，包含以下章节： +- 接口概述 +- 基本信息 +- 请求参数 +- 响应参数 +- 错误码 +- 使用说明 +- 相关接口 +- 更新日志 + +--- + +## 附录 + +### A. 接口分类统计 + +| 分类 | 接口数量 | 占比 | +|------|----------|------| +| 高级功能 | 5 | 17.86% | +| 批量操作 | 4 | 14.29% | +| 连接管理 | 3 | 10.71% | +| CRUD 操作 | 6 | 21.43% | +| 对象描述 | 6 | 21.43% | +| 查询功能 | 4 | 14.29% | +| **总计** | **28** | **100%** | + +### B. 请求方法统计 + +| 方法 | 接口数量 | 占比 | +|------|----------|------| +| POST | 28 | 100% | +| GET | 0 | 0% | +| PUT | 0 | 0% | +| DELETE | 0 | 0% | + +### C. 文档完成状态 + +| 状态 | 文档数量 | 占比 | +|------|----------|------| +| ✅ 已完成 | 28 | 100% | +| 🚧 进行中 | 0 | 0% | +| ❌ 未开始 | 0 | 0% | + +--- + +**文档结束**