# CloudCC 自定义组件使用说明

本文档基于本仓库 `plugins/`
目录下的实际插件结构整理，说明**自定义组件是什么、能做什么、为何使用、解决哪些问题**，以及**典型业务场景**。

---

## 1. 什么是自定义组件（在本项目中的含义）

在本项目中，**自定义组件**指：以 **Vue 2 单文件组件（`.vue`）** 为入口、放在
`plugins/<插件名>/` 下，通过 **`cloudccBuild` / `cloudccBuild2` 等 CLI 命令**
打包后，**嵌入 CloudCC 页面或应用** 的前端能力单元。

每个插件通常包含：

| 内容                               | 作用                                                                                                |
| ---------------------------------- | --------------------------------------------------------------------------------------------------- |
| 入口 `.vue`（如 `cc-ai-chat.vue`） | 组件 UI 与业务逻辑                                                                                  |
| `config.json`                      | 组件标识、名称、描述、分类、懒加载等元数据（部分插件还含 `id`、`bizType`、`category`、`loadModel`） |
| `components/`、`utils/` 等         | 子组件、HTTP、适配器、第三方 SDK 封装                                                               |

入口组件内常见 **`componentInfo`** 对象，与 `config.json`
呼应，用于在平台上展示组件名称与描述，例如：

```javascript
componentInfo: {
  component: "component-cc-ai-chat",
  compName: "AI Chat Component",
  compDesc: "AI chat component that supports multiple content formats",
},
```

本地开发时也可在 `src/App.vue` 中直接 `import`
某个插件入口进行调试（本仓库示例：`cc-ai-chat`）。

---

## 2. 自定义组件能干什么？主要作用是什么？

结合本仓库中的插件，自定义组件主要承担以下能力：

1. **扩展标准 CRM 界面**\
   在记录页、列表、门户等位置挂载**专用界面**（如甘特图 `cc-gantt`、客户 360
   `cc-customer360`、案例附件 `NewPortalCaseDetailFile`）。

2. **对接外部系统与复杂交互**\
   通过 HTTP、OpenAPI、Agent 平台（如 `cc-ai-chat` 的 Dify / cc-agent
   适配器）、地图（高德）、图可视化（G6）等，实现**平台原生配置难以覆盖**的集成体验。

3. **使用 CloudCC 运行时能力（`$CCDK`）**\
   在组件中调用登录态、网关地址、上传、总线事件等，例如：
   - `window.$CCDK.CCUser.getUserInfo()`、`CCToken.getToken()` /
     `getOpenApiToken()`
   - `CCConfig.getBaseUrl()`、`CCHttp.post(...)`
   - `CCBus.$emit("globalBus", ...)` 与全局联动\
     使组件**与当前租户、用户、环境一致**，无需硬编码环境。

4. **独立数据层（按需）**\
   部分组件可直连 **Supabase** 等外部存储（如
   `cc-teacher-entry`），用于演示或特定业务的数据托管；若组织规范要求，应限定在指定
   schema（如 `cloudcc-dev`）并遵守安全策略。

5. **运营与诊断类工具**\
   如同步菜单、H5 调试、内存报告、SQL
   工具等，服务于**实施、运维、开发排查**，而非单一业务对象 CRUD。

**一句话**：自定义组件是 **在 CloudCC
壳内运行的、可独立版本化的前端扩展**，用来交付**品牌化、集成化、可视化、智能化**等超出标准配置的能力。

---

## 3. 为什么要用自定义组件？

| 原因             | 说明                                                                                                  |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| **标准功能边界** | 对象字段、布局、简单按钮无法满足甘特、对话式 AI、拓扑图、复杂分步表单等需求。                         |
| **体验与品牌**   | 需要统一交互范式、动效、多栏布局（如 AI 聊天侧栏 + 可拖拽分栏），与门户风格一致。                     |
| **集成成本**     | 第三方 SaaS、自研 API、Agent、地图密钥等更适合在前端以 SDK + 适配器模式封装，而不是全部堆在后台脚本。 |
| **迭代节奏**     | 前端可独立发版（配合 `build-plugin`），与后台 Apex/流程解耦，便于小步迭代。                           |
| **复用**         | 同一插件可挂到多个菜单或页面，或通过 `config.json` / 平台配置区分环境。                               |

---

## 4. 自定义组件能解决哪些问题？

1. **「平台能配出来但很难用」**\
   用自定义 UI 优化录入路径、批量操作、可视化展示（如 forecast、target
   类业务插件）。

2. **「必须和外部系统实时协同」**\
   聊天、呼叫中心、文件上传至自有服务、地图选点等，通过组件内请求与回调闭环。

3. **「需要强上下文」**\
   利用 `$CCDK` 取当前用户、视图信息（如
   `CCUtils.getViewInfo()`）、Token，避免重复登录或手工传参。

4. **「跨模块事件联动」**\
   通过 `CCBus` 等机制触发全局事件，让多个区域协同（例如 AI 浮层与主界面联动）。

5. **「实施工具化」**\
   部署检查、数据同步、调试面板等，减少对生产数据的手工操作风险（仍需权限与审计配合）。

---

## 5. 什么情况下、什么业务场景要用自定义组件？

建议在出现以下信号时考虑自定义组件：

| 场景类型                | 典型例子（与本仓库对应）                                                 |
| ----------------------- | ------------------------------------------------------------------------ |
| **复杂可视化**          | 项目排期甘特图（`cc-gantt`）、关系/拓扑图（`cc-server-map`）、统计图表类 |
| **对话与智能助手**      | 嵌入式 AI 聊天（`cc-ai-chat`），多适配器切换                             |
| **行业/客户专用工作台** | 客户 360、高尔夫票务（`VaughnsValleyGolf`）、志愿者筛选面板等            |
| **门户与附件增强**      | 案例详情附件上传下载模板（`NewPortalCaseDetailFile`）                    |
| **表单 + 外部库**       | 教师档案 + Supabase（`cc-teacher-entry`）                                |
| **工具与运维**          | SQL 工具、内存上报、同步配置、H5 调试等                                  |

**不太适合**强行用自定义组件的情况：

- 仅用标准字段、列表视图、简单验证即可完成的场景（优先用平台配置）。
- 核心业务规则应集中在服务端保障安全与一致性的逻辑（组件只做展示与编排，不替代权限与校验后端）。

---

## 6. 开发与构建要点（本仓库）

- **依赖与栈**：`package.json` 中可见 Vue
  2、`element-ui`、`vant`、`vue-custom-element`、图表与地图等；按插件需要引入，避免无关依赖膨胀。
- **构建脚本**：`npm run build-plugin`（`cloudccBuild`）等用于产出可发布包，与日常
  `vue-cli-service serve` 本地调试配合使用。
- **全局约定**：ESLint 中声明了 `$CCDK` 为只读全局，说明组件运行在注入 SDK
  的宿主环境中。

---

## 7. 小结

- **自定义组件** = CloudCC 宿主内的 **Vue 插件包**，带 **元数据（`config.json` /
  `componentInfo`）** 与 **可选的 `$CCDK` 集成**。
- **主要作用**：交付标准配置无法覆盖的 **界面、集成、可视化与工具能力**。
- **核心价值**：在保持与平台账号、网关、事件体系一致的前提下，**快速、可版本化地扩展业务**。
- **选型时机**：当出现复杂
  UI、多系统集成、强依赖当前用户/视图上下文、或实施运维工具需求时，优先考虑自定义组件；能用标准配置解决的仍应优先标准配置。