BuildingAI 二开 平台配置菜单和页面功能PRD
1. 文档概述
1.1 文档目的
本文档用于描述系统设置菜单下“平台配置”模块的功能需求、页面设计、技术实现细节、权限与测试要求，统一规范不同智能体平台的对接方式，便于开发、测试与后续维护。
1.2 文档范围
- 菜单位置与信息架构（系统设置 → 支付配置之后 → 平台配置）
- 平台配置页面与弹窗的UI与交互
- OAuth应用配置的后端API与数据结构
- 权限控制与国际化
- 使用流程与安全要求
- OAuth应用对接原理与流程（以 Coze 为例）
1.3 术语定义
| 术语 | 定义 |
|---|---|
| PlatformConfig | 平台配置模块简称 |
| 智能体平台 | 提供智能体服务的第三方平台，如 Coze、Dify 等 |
| OAuth 应用 | 在第三方平台创建的应用，用于授权与 API 访问 |
| client_id | OAuth 应用的客户端ID，公开标识 |
| client_secret | OAuth 应用的客户端密钥，需加密保存并脱敏展示 |
| redirect_uri | 本系统用于接收授权回调的URL |
| scope | OAuth 申请的权限范围 |
2. 功能需求
2.1 核心功能
- 智能体平台列表展示：显示系统支持的所有平台卡片（Logo、名称、已接入应用数）。
- 平台管理入口：点击某平台“管理”，打开该平台的 OAuth 应用列表弹窗。
- OAuth 应用的增删查改：在弹窗中对应用进行新增、编辑、删除与查看。
- 搜索与排序：支持按站点名称或客户端ID搜索，按添加时间排序。
- 授权引导与测试：在新增/编辑弹窗提供创建应用与授权引导，支持授权后校验回调状态。
- 平台启用/禁用：支持平台维度启用/禁用，用于控制该平台是否在业务流程中可选。
2.2 辅助功能
- 表单验证：校验站点名称、client_id、client_secret、redirect_uri、scope 的必填与格式。
- 权限控制：仅授权角色可管理 OAuth 应用；普通管理员可查看。
- 国际化支持：中/英/日语言包。
- 错误提示与操作引导：失败重试、复制引导链接、一键复制回调URL。
- 安全要求：client_secret 加密存储、脱敏展示，严禁日志打印与导出。
3. 页面设计
3.1 平台配置列表页（系统设置 → 支付配置之后）
3.1.1 页面布局
- 页面标题：平台配置
- 栅格卡片：平台Logo、平台名称、已接入应用数、状态徽标（已启用/已禁用）、操作按钮（管理、添加）、右上角状态开关（USwitch）。
- 卡片交互：
- 点击“管理”打开该平台的 OAuth 应用列表弹窗；“添加”直接打开新增应用弹窗并预选平台。
- 切换 USwitch（启用/禁用）立即更新平台状态；禁用后卡片灰态，“添加”按钮禁用并显示提示“禁用后在业务流程中不可选”。
3.1.2 关键组件
- UGrid / Card：平台卡片栅格展示
- UAvatar：Logo展示
- UBadge：应用计数与状态徽标（启用/禁用）
- USwitch：平台启用/禁用切换（右上角）
- UTooltip：禁用状态与权限说明提示
- UButton：管理、添加（禁用态下“添加”禁用）
- UConfirmDialog（可选）：当平台存在已接入应用时禁用需二次确认
3.1.3 交互与逻辑
- 状态切换：
- 有
system-platformconfig:update权限的用户可操作 USwitch；无权限则隐藏或禁用并展示UTooltip提示。 - 切换时调用
apiUpdatePlatformStatus(platformId, isEnable)；成功提示并刷新列表，失败则提示并回滚 USwitch 状态。
- 有
- 禁用态行为：
- 卡片灰态并显示
UBadge“已禁用”。 - “添加”按钮禁用并提示“请先启用平台后再添加应用”。
- “管理”允许进入查看，但增删改由权限与状态共同约束。
- 卡片灰态并显示
- 可访问性：同时显示文本状态（“已启用/已禁用”），避免仅依赖颜色。
3.1.4 示例代码（文档示例）
const togglePlatformEnable = useThrottleFn(async (platformId: string, nextEnable: BooleanNumberType) => {try {await apiUpdatePlatformStatus(platformId, nextEnable);message.success($t('system.platformConfig.messages.saveSuccess'));await getPlatformList();} catch (_error) {message.error($t('system.platformConfig.messages.saveFailed'));// 回滚：重新拉取列表或本地恢复旧状态await getPlatformList();}
}, 800);
3.1.5 页面截图
参见需求图片（智能体平台卡片列表，含“管理”“添加”与右上角状态开关示意）。
3.2 OAuth 应用列表弹窗（平台管理）
3.2.1 页面布局
- 标题：平台名称（如“扣子/Coze”）
- 搜索框：按站点名称或客户端ID搜索
- 表格列：站点名称、客户端ID、添加时间、操作（编辑、删除）
- 右上角按钮：添加
3.2.2 关键组件
- UDialog：弹窗容器
- UTable：应用列表
- UInput：搜索框
- UButton：添加、编辑、删除
3.2.3 页面截图
参见需求图片（Coze 应用列表）。
3.3 OAuth 应用新增/编辑弹窗
3.3.1 页面布局与引导
- 顶部引导：三步指引
- 前往平台 OAuth 应用创建页（如 Coze 链接）。
- 在平台端设置重定向URL为系统提供的地址。
- 将客户端ID与客户端密钥填写到表单并保存。
- 表单区：站点名称、client_id、client_secret、redirect_uri（只读，可复制）、scope（复选或输入）。
- 底部按钮：取消、保存；提供“复制回调URL”按钮与“授权测试”入口。
3.3.2 表单字段
| 字段名称 | 类型 | 说明 |
|---|---|---|
| 站点名称 | 文本输入 | 与平台端应用名对应，便于识别 |
| 客户端ID | 文本输入 | 平台端生成的 client_id |
| 客户端密钥 | 文本输入 | 平台端生成的 client_secret（保存加密、展示脱敏） |
| 重定向URL | 只读文本 | 系统提供的授权回调地址，可一键复制 |
| 权限范围 | 文本/复选 | 平台端所需 scope，按需填写或选择 |
3.3.3 页面截图
参见需求图片（授权引导与表单）。
4. 技术实现
4.1 前端实现
4.1.1 主要文件结构
/app/pages/console/system-setting/platformconfig/
├── index.vue # 平台列表页
├── manage.vue # 某平台的 OAuth 应用列表弹窗/页面
├── edit.vue # OAuth 应用新增/编辑弹窗
4.1.2 核心功能实现（示例）
- 平台列表获取
const getPlatformList = async () => {const data = await apiGetPlatformList();platformList.value = data.map(({ id, name, logo, appCount, isEnable }) => ({ id, name, logo, appCount, isEnable }));
};
- OAuth 应用列表获取
const getOauthAppList = async (platformId: string) => {const data = await apiGetOauthAppList(platformId);appList.value = data.map(({ id, siteName, clientId, createdAt }) => ({ id, siteName, clientId, createdAt }));
};
- 新增/编辑应用保存
const saveOauthApp = async () => {const payload = { ...formData.value };if (formData.value.id) await apiUpdateOauthApp(formData.value.id, payload);else await apiAddOauthApp(platformId.value, payload);message.success(