cloudcc-cli 2.2.5 → 2.2.7

package/src/api/ccdk-sdk.md

@@ -0,0 +1,1039 @@
+# CloudCC 前端 SDK（cloudcc-ccdk）使用指南
+
+> 本文档参考 CloudCC 官方「前端 SDK
+> 参考」整理而成：[前端SDK参考](https://help.cloudcc.cn/product03/sdkcan-kao/)。\
+> 目标：指导在自定义组件、客户端脚本等前端场景中正确安装和使用
+> `$CCDK`，并按模块梳理常用 API。
+
+---
+
+## 1. 安装与全局引入
+
+### 1.1 PC 端（Web）
+
+全局可通过 `window.$CCDK` 访问各模块：
+
+```js
+window.$CCDK.CCMessage.showMessage("Hello CloudCC");
+```
+
+### 1.2 App 小程序端（DCloud）
+
+- 通过 DCloud 插件市场安装 `h5-ccdk`
+- 具体用法参考官方 `h5-ccdk` 文档（此处仅关注 Web 端 `cloudcc-ccdk`）
+
+---
+
+## 2. 模块概览
+
+常用模块按功能大致分为：
+
+- **加载与网络**：`CCLoad`、`CCHttp`
+- **后端类调用**：`CCCommon`
+- **认证与用户**：`CCToken`、`CCUser`
+- **对象数据与页面导航**：`CCDetail`、`CCList`、`CCPage`
+- **事件与工具**：`CCBus`、`CCCrypto`、`CCUtils`
+- **日志与消息**：`CCLog`、`CCMessage`
+- **OpenAPI 封装**：`CCOpenAPI`
+- 其他：`CCSide`、`CCApplication`、`CCCall`、`CCRenderer`、`CCLoading`、`CCI18n`
+  等
+
+以下按高频使用场景做简要说明与示例。
+
+---
+
+## 3. CCLoad：加载远程 JS 资源
+
+### 3.1 `loadJs(src): Promise`
+
+在 PC 端通过 JS 动态加载远程脚本：
+
+```js
+const p = $CCDK.CCLoad.loadJs(
+  "https://cdn.bootcdn.net/ajax/libs/echarts/6.0.0/echarts.common.js",
+);
+
+p.then(() => {
+  // 脚本加载完成
+}).catch(console.error);
+```
+
+- 仅 PC 有效（H5/小程序/APP 不支持）
+
+**参数说明：**
+
+| 参数  | 说明         | 类型     | 可选值 | 默认值 |
+| ----- | ------------ | -------- | ------ | ------ |
+| `src` | 远程 JS 地址 | `string` | —      | 必填   |
+
+### 3.2 `createLoadJsComponent()`
+
+创建自定义标签用来加载 JS：
+
+```js
+$CCDK.CCLoad.createLoadJsComponent();
+// 在模板中：
+// <cc-load-script src="js上线地址"></cc-load-script>
+```
+
+`<cc-load-script>` 组件属性：
+
+| 属性  | 说明         | 类型     | 可选值 | 默认值 |
+| ----- | ------------ | -------- | ------ | ------ |
+| `src` | 远程 JS 地址 | `string` | —      | 必填   |
+
+---
+
+## 4. CCHttp：简单网络请求
+
+> 基于 axios 封装，默认已带上必要头信息，适合在 CloudCC
+> 场景下调用外部/内部接口。
+
+常用方法：`get` / `post` / `put` / `patch` / `postParams`，统一返回 Promise。
+
+```js
+const data = { name: "zhangsan" };
+
+$CCDK.CCHttp.post("/api/demo", data)
+  .then((res) => {
+    console.log("res", res);
+  })
+  .catch((error) => {
+    console.log("error", error);
+  });
+```
+
+以 `get(url, data, responseType, config)` 为例，参数说明如下：
+
+| 参数           | 说明         | 类型     | 可选值 | 默认值 |
+| -------------- | ------------ | -------- | ------ | ------ |
+| `url`          | 接口请求地址 | `string` | —      | `''`   |
+| `data`         | 查询参数     | `object` | —      | `{}`   |
+| `responseType` | 响应类型     | `string` | —      | `''`   |
+| `config`       | axios 配置   | `object` | —      | `{}`   |
+
+其他方法参数形态类似：
+
+- `post(url, data, responseType, config)`
+- `put(url, data)` / `patch(url, data)` / `postParams(url, data)`
+
+---
+
+## 5. CCCommon：访问 CloudCC 自定义类（接口）
+
+### `post(className, methodName, params, config): Promise`
+
+用于在前端调用 CloudCC 后端自定义类，避免自己拼接 URL：
+
+```js
+const className = "test";
+const methodName = "func1";
+const params = [
+  { argType: "java.lang.String", argValue: "hello" },
+  { argType: "java.lang.String", argValue: "world" },
+];
+const config = { timeout: 60000 };
+
+$CCDK.CCCommon.post(className, methodName, params, config)
+  .then((res) => {
+    const data = res.data;
+    console.log(data);
+  })
+  .catch((error) => {
+    console.error(error);
+  });
+```
+
+- 仅 PC 有效
+
+**参数说明：**
+
+| 参数                 | 说明                     | 类型     | 可选值 | 默认值 |
+| -------------------- | ------------------------ | -------- | ------ | ------ |
+| `className`          | 自定义类名               | `string` | —      | `''`   |
+| `methodName`         | 自定义类中的方法名       | `string` | —      | `''`   |
+| `params`             | 方法入参列表             | `Array`  | —      | `[]`   |
+| `params[*].argType`  | Java 参数类型            | `string` | —      | —      |
+| `params[*].argValue` | 参数值                   | `any`    | —      | —      |
+| `config`             | 请求配置（如 `timeout`） | `object` | —      | `{}`   |
+
+---
+
+## 6. CCToken：令牌管理
+
+### 6.1 `getToken(): string`
+
+```js
+const token = $CCDK.CCToken.getToken();
+```
+
+**返回值：**
+
+| 返回值  | 说明             | 类型     |
+| ------- | ---------------- | -------- |
+| `token` | 当前用户登录令牌 | `string` |
+
+### 6.2 `setToken(token): void`
+
+```js
+$CCDK.CCToken.setToken("your-token");
+```
+
+| 参数    | 说明     | 类型     | 可选值 | 默认值 |
+| ------- | -------- | -------- | ------ | ------ |
+| `token` | 新的令牌 | `string` | —      | 必填   |
+
+### 6.3 `clearToken(): void`
+
+```js
+$CCDK.CCToken.clearToken();
+```
+
+PC/H5/小程序均可用（APP 暂不支持）。
+
+---
+
+## 7. CCUser：当前登录用户信息
+
+### 7.1 `getUserInfo(keyName): object`
+
+```js
+const userInfo = $CCDK.CCUser.getUserInfo(); // 默认 key 为 cc_user_info
+```
+
+| 参数      | 说明                     | 类型     | 可选值 | 默认值           |
+| --------- | ------------------------ | -------- | ------ | ---------------- |
+| `keyName` | 存储用户信息的键名，可选 | `string` | —      | `"cc_user_info"` |
+
+**返回值：**
+
+| 返回值     | 说明             | 类型     |
+| ---------- | ---------------- | -------- |
+| `userInfo` | 当前登录用户信息 | `object` |
+
+### 7.2 `setUserInfo(userInfo, domain, keyName): void`
+
+```js
+$CCDK.CCUser.setUserInfo({ name: "zhangsan" });
+```
+
+| 参数       | 说明             | 类型     | 可选值 | 默认值           |
+| ---------- | ---------------- | -------- | ------ | ---------------- |
+| `userInfo` | 用户详细信息对象 | `object` | —      | `{}`             |
+| `domain`   | 域名             | `string` | —      | 当前所在域名     |
+| `keyName`  | 存储键名         | `string` | —      | `"cc_user_info"` |
+
+---
+
+## 8. CCDetail：对象详情
+
+> 操作标准详情页数据，常配合客户端脚本/自定义组件使用。
+
+### 8.1 `getDetail(apiname?, detailId?): object`
+
+```js
+// 获取当前详情页全部数据
+const detail = $CCDK.CCDetail.getDetail();
+
+// 获取当前详情页某字段的值
+const field = $CCDK.CCDetail.getDetail("name");
+const value = field.value;
+```
+
+| 参数       | 说明                                          | 类型     | 可选值 | 默认值  |
+| ---------- | --------------------------------------------- | -------- | ------ | ------- |
+| `apiname`  | 指定字段 API 名称，不传则返回整条详情         | `string` | —      | `null`  |
+| `detailId` | 指定详情记录 ID，不传则使用最近访问的详情记录 | `string` | —      | 最新 ID |
+
+**返回值：**
+
+- 不传 `apiname`：返回对象详情整体结构
+- 传入 `apiname`：返回该字段的包装对象（常见属性如 `value`、`label` 等）
+
+### 8.2 `setDetail(detail): void`
+
+```js
+$CCDK.CCDetail.setDetail({
+  id: "00120231...",
+  detail: [/* 详情数据 */],
+});
+```
+
+| 参数            | 说明         | 类型     | 可选值 | 默认值 |
+| --------------- | ------------ | -------- | ------ | ------ |
+| `detail`        | 详情数据对象 | `object` | —      | 必填   |
+| `detail.id`     | 详情记录 ID  | `string` | —      | 必填   |
+| `detail.detail` | 详情字段数组 | `Array`  | —      | 必填   |
+
+### 8.3 其他常用方法
+
+- `getDetailId()` / `setDetailId(id)`：获取/设置当前详情页 ID
+- `refreshRelatedList(ids)`：刷新相关列表
+- `getRelatedSelected(recordId, detailId)`：获取相关列表选中记录
+
+---
+
+## 9. CCList：对象列表页（视图页）
+
+### 9.1 `getSelected(): { ids: string[] }`
+
+```js
+const { ids } = $CCDK.CCList.getSelected();
+```
+
+**返回值：**
+
+| 字段  | 说明                     | 类型       |
+| ----- | ------------------------ | ---------- |
+| `ids` | 当前列表页中选中 ID 集合 | `string[]` |
+
+### 9.2 `getViewId()`、`getViewInfo()`
+
+```js
+const viewId = $CCDK.CCList.getViewId();
+const viewInfo = $CCDK.CCList.getViewInfo();
+// 包含 ids、viewId、prefix、objid、objectApi 等
+```
+
+`getViewId()`：
+
+| 返回值   | 说明        | 类型     |
+| -------- | ----------- | -------- |
+| `viewId` | 当前视图 ID | `string` |
+
+`getViewInfo()` 常见字段：
+
+| 字段        | 说明             | 类型     |
+| ----------- | ---------------- | -------- |
+| `ids`       | 当前选中 ID 集合 | `Array`  |
+| `viewId`    | 当前视图 ID      | `string` |
+| `prefix`    | 对象前缀         | `string` |
+| `objid`     | 对象 ID          | `string` |
+| `objectApi` | 对象 API 名称    | `string` |
+
+---
+
+## 10. CCPage：打开/关闭 CloudCC 页面
+
+> 在组件/脚本中以「官方方式」打开列表、详情、新建、编辑、自定义页面。
+
+### 10.1 打开列表页 `openListPage(obj): string`
+
+```js
+const pageId = $CCDK.CCPage.openListPage({
+  menuId: "aaa-223",
+  prefix: "001",
+  viewId: "ace1111",
+  layoutType: "list", // list / Kanban / splitscreen
+});
+```
+
+| 参数         | 说明     | 类型     | 可选值                                  | 默认值   |
+| ------------ | -------- | -------- | --------------------------------------- | -------- |
+| `menuId`     | 菜单 ID  | `string` | —                                       | 必填     |
+| `prefix`     | 对象前缀 | `string` | —                                       | 必填     |
+| `viewId`     | 视图 ID  | `string` | —                                       | 必填     |
+| `layoutType` | 布局类型 | `string` | `"list"` / `"Kanban"` / `"splitscreen"` | `"list"` |
+
+**返回值：**
+
+| 返回值   | 说明             | 类型     |
+| -------- | ---------------- | -------- |
+| `pageId` | 打开页面唯一标识 | `string` |
+
+### 10.2 打开详情页 `openDetailPage(obj, id, options): string`
+
+```js
+const pageId = $CCDK.CCPage.openDetailPage(
+  {
+    oprateType: "DETAIL",
+    objectName: "客户",
+    objId: "account",
+    objectApi: "Account",
+    prefix: "001",
+  },
+  "00120227805836AlIEL4",
+  {
+    openPlace: "menu2",
+    openMode: "_self",
+  },
+);
+```
+
+`obj` 参数：
+
+| 字段         | 说明               | 类型     | 可选值 | 默认值                |
+| ------------ | ------------------ | -------- | ------ | --------------------- |
+| `oprateType` | 页面类型           | `string` | —      | 必填（如 `"DETAIL"`） |
+| `objectName` | 对象名称（展示用） | `string` | —      | 必填                  |
+| `objId`      | 对象 ID            | `string` | —      | 必填                  |
+| `objectApi`  | 对象 API 名称      | `string` | —      | 必填                  |
+| `prefix`     | 对象前缀           | `string` | —      | 必填                  |
+
+`id` 参数：
+
+| 参数 | 说明    | 类型     | 可选值 | 默认值 |
+| ---- | ------- | -------- | ------ | ------ |
+| `id` | 记录 ID | `string` | —      | 必填   |
+
+`options` 常用字段（节选）：
+
+| 字段        | 说明     | 类型     | 可选值                          | 默认值    |
+| ----------- | -------- | -------- | ------------------------------- | --------- |
+| `pageId`    | 页面 ID  | `string` | —                               | 不传      |
+| `openPlace` | 打开位置 | `string` | `"tab"` / `"menu1"` / `"menu2"` | `"menu1"` |
+| `openMode`  | 打开方式 | `string` | `"_self"` / `"_blank"`          | `"_self"` |
+
+### 10.3 打开新建/编辑页
+
+- `openCreatePage(obj, options)`
+- `openEditPage(obj, id, options)`
+
+可通过 `defalutData` 预填字段值，适用于从组件/脚本跳转并带默认值的场景。
+
+### 10.4 打开自定义页面 `openCustomPage(obj, options)`
+
+```js
+const pageId = $CCDK.CCPage.openCustomPage(
+  { pageApi: "sayhello", data: {} },
+  {
+    openPlace: "dialog",
+    openMode: "_blank",
+    title: "菜单标题",
+    height: "70vh",
+    width: "70vw",
+  },
+);
+```
+
+`obj` 参数：
+
+| 字段      | 说明                 | 类型     | 可选值 | 默认值 |
+| --------- | -------------------- | -------- | ------ | ------ |
+| `pageApi` | 自定义页面标识       | `string` | —      | 必填   |
+| `data`    | 初始化数据（表单等） | `object` | —      | `{}`   |
+
+`options` 常用字段（节选）：
+
+| 字段          | 说明                                      | 类型      | 可选值                                                         | 默认值            |
+| ------------- | ----------------------------------------- | --------- | -------------------------------------------------------------- | ----------------- |
+| `pageId`      | 页面 ID，相同 ID 时复用页面               | `string`  | —                                                              | 不传              |
+| `openPlace`   | 打开位置                                  | `string`  | `"dialog"` / `"tab"` / `"floatDialog"` / `"menu1"` / `"menu2"` | `"tab"`           |
+| `openMode`    | 打开方式                                  | `string`  | `"_self"` / `"_blank"`                                         | `"_blank"`        |
+| `title`       | 弹窗标题或菜单名称                        | `string`  | —                                                              | `''`              |
+| `isIframe`    | 是否以 iframe 渲染（用于缓存自定义页面）  | `boolean` | `true` / `false`                                               | `false`           |
+| `isShowClose` | 是否显示菜单关闭按钮                      | `boolean` | `true` / `false`                                               | `true`            |
+| `tabAction`   | 一级/二级菜单下拉操作项配置               | `Array`   | —                                                              | `[]`              |
+| `width`       | 宽度，支持 `px` / `%` / `vw`              | `string`  | —                                                              | 自动              |
+| `height`      | 高度，支持 `px` / `vh`                    | `string`  | —                                                              | 自动              |
+| `left`        | 距离屏幕左侧距离                          | `string`  | —                                                              | 自动              |
+| `top`         | 距离屏幕顶部距离                          | `string`  | —                                                              | 自动              |
+| `right`       | 距离屏幕右侧距离                          | `string`  | —                                                              | 自动              |
+| `bottom`      | 距离屏幕底部距离                          | `string`  | —                                                              | 自动              |
+| `isShowMenu`  | 是否显示菜单（menu1/menu2 下默认 `true`） | `boolean` | `true` / `false`                                               | 视 openPlace 而定 |
+
+**返回值：**
+
+| 返回值   | 说明                     | 类型     |
+| -------- | ------------------------ | -------- |
+| `pageId` | 打开的自定义页面唯一标识 | `string` |
+
+### 10.5 其他
+
+- `reOpenPage(pageId, options)`：通过 pageId 重新打开/刷新页面
+- `searchPage(pageId)`：查询是否存在指定页面
+- `getCurrentPage()`：获取当前页面菜单数据
+- `close(pageId?)`、`refresh()`：关闭/刷新页面
+
+---
+
+## 11. CCBus：前端事件总线
+
+### 11.1 `$emit(event, ...args)`
+
+```js
+$CCDK.CCBus.$emit("myevent", { foo: 1 });
+```
+
+| 参数      | 说明                 | 类型     | 可选值 | 默认值 |
+| --------- | -------------------- | -------- | ------ | ------ |
+| `event`   | 事件名称（唯一标识） | `string` | —      | 必填   |
+| `...args` | 事件参数             | `any`    | —      | —      |
+
+### 11.2 `$on(event, callback)`
+
+```js
+$CCDK.CCBus.$on("myevent", (payload) => {
+  console.log("收到事件", payload);
+});
+```
+
+| 参数       | 说明     | 类型       | 可选值 | 默认值 |
+| ---------- | -------- | ---------- | ------ | ------ |
+| `event`    | 事件名称 | `string`   | —      | 必填   |
+| `callback` | 回调函数 | `function` | —      | 必填   |
+
+### 11.3 `$off(event)`
+
+```js
+$CCDK.CCBus.$off("myevent");
+```
+
+| 参数    | 说明     | 类型     | 可选值 | 默认值 |
+| ------- | -------- | -------- | ------ | ------ |
+| `event` | 事件名称 | `string` | —      | 必填   |
+
+---
+
+## 12. CCMessage：前端消息提示
+
+### 12.1 `showMessage(text, type, duration, showClose, center)`
+
+```js
+$CCDK.CCMessage.showMessage("操作成功", "success", 2000);
+```
+
+| 参数        | 说明                                 | 类型      | 可选值                                           | 默认值   |
+| ----------- | ------------------------------------ | --------- | ------------------------------------------------ | -------- |
+| `text`      | 提示文案                             | `string`  | —                                                | 必填     |
+| `type`      | 消息类型                             | `string`  | `"success"` / `"warning"` / `"info"` / `"error"` | `"info"` |
+| `duration`  | 显示时间（毫秒），`0` 表示不自动关闭 | `number`  | —                                                | `3000`   |
+| `showClose` | 是否显示关闭按钮                     | `boolean` | —                                                | `false`  |
+| `center`    | 文本是否居中                         | `boolean` | —                                                | `false`  |
+
+### 12.2 `showConfirm(text, title, options, confirm, reject)`
+
+```js
+$CCDK.CCMessage.showConfirm(
+  "确定要执行此操作吗？",
+  "确认提示",
+  { type: "warning" },
+  () => {/* 确认回调 */},
+  () => {/* 取消回调 */},
+);
+```
+
+| 参数      | 说明                  | 类型                | 可选值 | 默认值   |
+| --------- | --------------------- | ------------------- | ------ | -------- |
+| `text`    | 消息正文              | `string` \| `VNode` | —      | 必填     |
+| `title`   | 标题                  | `string`            | —      | `"提示"` |
+| `options` | 其他配置（见下表）    | `object`            | —      | `{}`     |
+| `confirm` | 点击确定时的回调      | `function`          | —      | 必填     |
+| `reject`  | 点击取消/关闭时的回调 | `function`          | —      | 可选     |
+
+`options` 常见字段：
+
+| 字段                | 说明                   | 类型      | 可选值                                           | 默认值                     |
+| ------------------- | ---------------------- | --------- | ------------------------------------------------ | -------------------------- |
+| `type`              | 消息类型               | `string`  | `"success"` / `"info"` / `"warning"` / `"error"` | —                          |
+| `showClose`         | 是否显示右上角关闭按钮 | `boolean` | —                                                | `true`                     |
+| `showCancelButton`  | 是否显示取消按钮       | `boolean` | —                                                | `true`（confirm/prompt）   |
+| `showConfirmButton` | 是否显示确定按钮       | `boolean` | —                                                | `true`                     |
+| `cancelButtonText`  | 取消按钮文本           | `string`  | —                                                | `"取消"`                   |
+| `confirmButtonText` | 确定按钮文本           | `string`  | —                                                | `"确定"`                   |
+| `closeOnClickModal` | 点击遮罩是否关闭       | `boolean` | —                                                | `true`（alert 为 `false`） |
+| `center`            | 是否居中布局           | `boolean` | —                                                | `false`                    |
+| `roundButton`       | 是否圆角按钮           | `boolean` | —                                                | `false`                    |
+
+### 12.3 `showNotification(options)`
+
+```js
+$CCDK.CCMessage.showNotification({
+  title: "提示",
+  message: "这是一条不会自动关闭的消息",
+  duration: 0,
+});
+```
+
+`options` 常见字段：
+
+| 字段                       | 说明                                 | 类型                | 可选值                                                            | 默认值        |
+| -------------------------- | ------------------------------------ | ------------------- | ----------------------------------------------------------------- | ------------- |
+| `title`                    | 标题                                 | `string`            | —                                                                 | `''`          |
+| `message`                  | 内容                                 | `string` \| `VNode` | —                                                                 | `''`          |
+| `dangerouslyUseHTMLString` | 是否将 message 作为 HTML 处理        | `boolean`           | —                                                                 | `false`       |
+| `type`                     | 类型                                 | `string`            | `"success"` / `"warning"` / `"info"` / `"error"`                  | —             |
+| `duration`                 | 显示时间（毫秒），`0` 表示不自动关闭 | `number`            | —                                                                 | `4500`        |
+| `position`                 | 弹出位置                             | `string`            | `"top-right"` / `"top-left"` / `"bottom-right"` / `"bottom-left"` | `"top-right"` |
+| `showClose`                | 是否显示关闭按钮                     | `boolean`           | —                                                                 | `true`        |
+| `onClose`                  | 关闭时回调                           | `function`          | —                                                                 | —             |
+| `onClick`                  | 点击通知时回调                       | `function`          | —                                                                 | —             |
+
+---
+
+## 13. CCLog：日志上报
+
+### 13.1 `reportInfoLog(logInfo)`
+
+```js
+const logInfo = {
+  infoType: "debug",
+  serviceName: "my app",
+  infoMessage: "描述信息",
+};
+
+window.$CCDK.CCLog.reportInfoLog(logInfo);
+```
+
+`logInfo` 字段：
+
+| 字段          | 说明     | 类型     | 可选值               | 默认值   |
+| ------------- | -------- | -------- | -------------------- | -------- |
+| `infoType`    | 日志类型 | `string` | `"info"` / `"debug"` | `"info"` |
+| `serviceName` | 服务名称 | `string` | —                    | 项目名称 |
+| `infoMessage` | 描述信息 | `string` | —                    | `""`     |
+| `remark`      | 备注     | `string` | —                    | `""`     |
+
+### 13.2 `reportErrorLog(logInfo)`
+
+```js
+const logInfo = {
+  serviceName: "my app",
+  errorMessage: "错误描述信息",
+  printStackTraceInfo: "堆栈信息",
+};
+
+window.$CCDK.CCLog.reportErrorLog(logInfo);
+```
+
+`logInfo` 字段：
+
+| 字段                  | 说明     | 类型     | 可选值 | 默认值   |
+| --------------------- | -------- | -------- | ------ | -------- |
+| `serviceName`         | 服务名称 | `string` | —      | 项目名称 |
+| `errorMessage`        | 错误描述 | `string` | —      | `""`     |
+| `printStackTraceInfo` | 堆栈信息 | `string` | —      | `""`     |
+| `requestUrl`          | 请求地址 | `string` | —      | `""`     |
+| `remark`              | 备注     | `string` | —      | `""`     |
+
+---
+
+## 14. CCOpenAPI：OpenAPI 封装（概览）
+
+> 通过 CCDK 在前端直接调用 CloudCC OpenAPI，支持普通查询、分页查询、自定义 SQL
+> 等。
+
+典型方法：
+
+- `cquery` / `cqueryWithRoleRight`
+- `pageQuery` / `pageQueryWithRoleRight`
+- `getQueryPermisson`
+- `cqlQueryWithLogInfo` / `cqlQueryWithStatic`
+
+示例（普通查询）：
+
+```js
+const res = await window.$CCDK.CCOpenAPI.cquery(
+  clientId,
+  secretKey,
+  "Contact",
+  "name='13213'",
+  "name,createdate,createbyid",
+  "false",
+  {},
+);
+
+if (res.result) {
+  console.log(res.data);
+}
+```
+
+### 14.1 `cquery(clientId, secretKey, objectApiName, expressions, fields, isAddDelete, options)`
+
+| 参数            | 说明                                       | 类型     | 可选值 | 默认值    |
+| --------------- | ------------------------------------------ | -------- | ------ | --------- |
+| `clientId`      | 客户端 ID                                  | `string` | —      | 必填      |
+| `secretKey`     | 客户端密钥                                 | `string` | —      | 必填      |
+| `objectApiName` | 对象 API 名称，如 `Contact`、`Account`     | `string` | —      | 必填      |
+| `expressions`   | 查询条件，如 `name='13213'`                | `string` | —      | `''`      |
+| `fields`        | 返回字段列表，逗号分隔                     | `string` | —      | `''`      |
+| `isAddDelete`   | 是否包含已删除数据（`"true"` / `"false"`） | `string` | —      | `"false"` |
+| `options`       | 额外配置（如 `baseUrl`、`timeout`）        | `object` | —      | `{}`      |
+
+**返回值（通用结构）：**
+
+| 字段         | 说明                      | 类型      |
+| ------------ | ------------------------- | --------- |
+| `result`     | 是否成功                  | `boolean` |
+| `returnInfo` | 返回信息/错误说明         | `string`  |
+| `returnCode` | 返回编码（如 `"1"` 成功） | `string`  |
+| `data`       | 业务数据（数组或对象）    | `any`     |
+
+### 14.2 `cqueryWithRoleRight(clientId, secretKey, objectApiName, expressions, isAddDelete, options)`
+
+与 `cquery` 相同，但会按照当前用户权限过滤：
+
+| 参数            | 说明               | 类型     | 默认值    |
+| --------------- | ------------------ | -------- | --------- |
+| `clientId`      | 客户端 ID          | `string` | 必填      |
+| `secretKey`     | 客户端密钥         | `string` | 必填      |
+| `objectApiName` | 对象 API 名称      | `string` | 必填      |
+| `expressions`   | 查询条件           | `string` | `''`      |
+| `isAddDelete`   | 是否包含已删除数据 | `string` | `"false"` |
+| `options`       | 额外配置           | `object` | `{}`      |
+
+### 14.3 `pageQuery(clientId, secretKey, objectApiName, expressions, fields, pageNUM, pageSize, options)`
+
+| 参数            | 说明                  | 类型     | 默认值 |
+| --------------- | --------------------- | -------- | ------ |
+| `clientId`      | 客户端 ID             | `string` | 必填   |
+| `secretKey`     | 客户端密钥            | `string` | 必填   |
+| `objectApiName` | 对象 API 名称         | `string` | 必填   |
+| `expressions`   | 查询条件              | `string` | `''`   |
+| `fields`        | 返回字段列表          | `string` | `''`   |
+| `pageNUM`       | 当前页码（从 1 开始） | `number` | 必填   |
+| `pageSize`      | 每页条数              | `number` | 必填   |
+| `options`       | 额外配置              | `object` | `{}`   |
+
+附加返回字段（分页）：
+
+| 字段         | 说明         | 类型      |
+| ------------ | ------------ | --------- |
+| `pageNUM`    | 当前页码     | `number`  |
+| `pageSize`   | 每页条数     | `number`  |
+| `totalCount` | 总记录数     | `number`  |
+| `pageCount`  | 总页数       | `number`  |
+| `hasPre`     | 是否有上一页 | `boolean` |
+| `hasNext`    | 是否有下一页 | `boolean` |
+
+### 14.4 其他 OpenAPI 方法（简要参数说明）
+
+- `pageQueryWithRoleRight(clientId, secretKey, objectApiName, expressions, pageNUM, pageSize, options)`
+  - 同 `pageQuery`，但增加权限过滤；`options` 可包含 `fields`。
+- `getQueryPermisson(clientId, secretKey, objectApiName, options)`
+  - `objectApiName` 可传多个对象（逗号分隔），返回每个对象的查询权限与
+    `shareSql`。
+- `cqlQueryWithLogInfo(clientId, secretKey, objectApiName, expressions, options)`
+  - `expressions` 为 CQL / SQL 语句，受权限配置控制。
+- `cqlQueryWithStatic(clientId, secretKey, objectApiName, expressions, nextRecordQueryId, options)`
+  - 支持游标式分页，`nextRecordQueryId` 为上一次调用返回的游标 ID，首次为
+    `undefined`。
+
+---
+
+## 15. 其他常用工具与模块（详细）
+
+### 15.1 CCUtils：通用工具
+
+#### 15.1.1 获取域名 `getDomain()`
+
+```js
+const domain = $CCDK.CCUtils.getDomain();
+// 示例：返回 xx.com / xx.cn / xx.com.cn / xx.net.cn 等
+```
+
+#### 15.1.2 获取当前页面类型 `getCurrentPageType()`
+
+```js
+const pageType = $CCDK.CCUtils.getCurrentPageType();
+// "view"：视图页（列表页）
+// "detail"：详情页
+```
+
+#### 15.1.3 表单 ID 相关（新建/编辑页）
+
+在新建/编辑页面的客户端脚本中，`obj` 参数通常包含 `formId`，也可以通过 CCUtils
+获取：
+
+```js
+// 获取最后一次打开的表单 formId
+const formId = $CCDK.CCUtils.getFormId();
+
+// 获取当前会话内所有打开表单的 formId 集合
+const allFormIds = $CCDK.CCUtils.getFormId({ type: "all" });
+```
+
+#### 15.1.4 设置主表单字段值 `setFormFieldValue(option)`
+
+> 在新建/编辑页上给主对象字段设置默认值或动态赋值，需结合客户端脚本（onLoad/onChange）。
+
+```js
+// 客户端脚本中 obj.formId 由平台注入
+const formId = obj.formId;
+const option = {
+  formId,
+  list: [
+    {
+      fieldKey: "name", // 字段 apiname
+      value: "测试客户", // 字段值
+    },
+    {
+      fieldKey: "khmc__c",
+      value: "0013423dsdsds",
+      valueName: "客户名称", // 查找字段需要 label
+    },
+  ],
+};
+
+$CCDK.CCUtils.setFormFieldValue(option);
+```
+
+#### 15.1.5 获取主表单字段值 `getFormFieldValue(option)`
+
+```js
+const formId = obj.formId;
+const option = {
+  formId,
+  list: [
+    { fieldKey: "name" },
+    { fieldKey: "phone" },
+  ],
+};
+
+const result = $CCDK.CCUtils.getFormFieldValue(option);
+// 返回值包含各字段当前采集值
+```
+
+#### 15.1.6 获取主表单字段详细信息 `getFormFieldInfo(option)`
+
+```js
+const formId = obj.formId;
+const option = {
+  formId,
+  list: [{ fieldKey: "name" }],
+};
+
+const info = $CCDK.CCUtils.getFormFieldInfo(option);
+// info 中包含字段类型、label、当前值等详细信息
+```
+
+#### 15.1.7 从记录（相关列表）数据相关
+
+在从记录新增行（addLine 型客户端脚本）中，`obj` 通常包含 `formId`、`relatedId`：
+
+```js
+const { formId, relatedId } = obj;
+
+// 获取从记录所有数据
+$CCDK.CCUtils.getRelatedInfo({ formId });
+
+// 获取指定从记录的数据
+$CCDK.CCUtils.getRelatedValue({ formId, relatedId });
+
+// 设置从记录字段值
+$CCDK.CCUtils.setRelatedValue({
+  formId,
+  relatedId,
+  updateType: "lastLine", // "all" / "lastLine" / 指定索引
+  list: [
+    {
+      fieldKey: "amount__c",
+      value: 100,
+    },
+  ],
+});
+```
+
+#### 15.1.8 浏览器通知 `notify(options)`
+
+```js
+// 最简单用法
+$CCDK.CCUtils.notify({ title: "提示" });
+
+// 标题 + 正文
+$CCDK.CCUtils.notify({
+  title: "新消息",
+  body: "您有一条待办需要处理",
+});
+
+// 标题 + 正文 + 图标
+$CCDK.CCUtils.notify({
+  title: "系统通知",
+  body: "任务已完成",
+  icon: "/favicon.ico",
+});
+```
+
+#### 15.1.9 标签标题闪烁 `blinkTitle(options)`
+
+```js
+// 默认提示
+$CCDK.CCUtils.blinkTitle();
+
+// 自定义文案与间隔
+$CCDK.CCUtils.blinkTitle({
+  message: "你有一条新消息",
+  interval: 800,
+});
+```
+
+---
+
+### 15.2 CCCrypto：加解密
+
+> 基于 AES（含 key、iv）的简单加解密工具，仅 PC 可用。
+
+#### 15.2.1 加密 `encrypt(data, key, iv)`
+
+```js
+const cipher = $CCDK.CCCrypto.encrypt(
+  { name: "zhangsan" },
+  "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", // 32 字节密钥
+  1, // 偏移量
+);
+```
+
+#### 15.2.2 解密 `decrypt(data, key, iv)`
+
+```js
+const data = "rgTxYdmUGNelPbfoChXe5eTQqNDPxTNv..."; // 省略长密文
+const result = $CCDK.CCCrypto.decrypt(
+  data,
+  "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+  1,
+);
+```
+
+---
+
+### 15.3 CCSide：侧边工具栏
+
+> 在 PC 端打开一个挂载自定义页面的侧边栏，如「AI 助手」「工具面板」等。
+
+#### 15.3.1 初始化 `init(options)`
+
+```js
+$CCDK.CCSide.init({
+  width: "300px",
+  pageApi: "dht", // 对应自定义页面 API
+});
+```
+
+#### 15.3.2 打开/关闭
+
+```js
+$CCDK.CCSide.open();
+$CCDK.CCSide.close();
+```
+
+---
+
+### 15.4 CCApplication：应用信息
+
+#### 15.4.1 获取当前应用 `getApplicaton()`
+
+```js
+const app = $CCDK.CCApplication.getApplicaton();
+// app.id：应用 id
+// app.name：应用名称
+// app.navigationStyle：'0' 控制台样式，'1' 标准样式
+```
+
+> `open(appId)` 处于开发中，用于在前端打开指定应用。
+
+---
+
+### 15.5 CCCall：电话集成
+
+> 仅 PC 端，需与 CloudCC 后台配置的电话服务商配合使用。
+
+#### 15.5.1 初始化电话功能 `init(id, callClient)`
+
+```js
+const callClient = {
+  // 点击平台手机号、电话图标时平台会回调此方法
+  call: (options) => {
+    const number = options.number; // 要外呼的号码
+    // 调用第三方话务 SDK 进行外呼
+  },
+};
+
+const client = $CCDK.CCCall.init("abc", callClient);
+// "abc" 为电话服务商唯一标识，从 CloudCC 后台「沟通渠道 → 电话」配置中获取
+```
+
+#### 15.5.2 外呼与呼叫面板
+
+```js
+// 直接发起外呼
+$CCDK.CCCall.call("abc", { number: "13800000000" });
+
+// 打开电话面板
+$CCDK.CCCall.openCallPanel("abc", { number: "13800000000" });
+```
+
+---
+
+### 15.6 CCI18n：多语言
+
+> 在组件/页面中使用 CCDK 自带的 i18n 能力维护多语言词条。
+
+#### 15.6.1 添加词条 `addMessages(langType, message)`
+
+```js
+// 中文
+$CCDK.CCI18n.addMessages($CCDK.CCI18n.LocalEnum.ZH, {
+  hello: "你好",
+  test: "测试",
+});
+
+// 英文
+$CCDK.CCI18n.addMessages($CCDK.CCI18n.LocalEnum.EN, {
+  hello: "hello",
+  test: "test",
+});
+```
+
+#### 15.6.2 切换语言 `setLocale(langType)`
+
+```js
+$CCDK.CCI18n.setLocale($CCDK.CCI18n.LocalEnum.ZH); // 显示中文
+$CCDK.CCI18n.setLocale($CCDK.CCI18n.LocalEnum.EN); // 显示英文
+```
+
+#### 15.6.3 获取词条 `t(key)`
+
+```js
+// 在 JS 中
+const label = $CCDK.CCI18n.t("hello");
+
+// 在 Vue 计算属性中
+computed: {
+  labelTest() {
+    return window.$CCDK.CCI18n.t("test");
+  }
+}
+```
+
+---
+
+### 15.7 CCLoading：加载遮罩
+
+> 基于 ElementUI 的 Loading 服务，适合在组件/页面中显示「加载中」状态。
+
+#### 15.7.1 开启 Loading
+
+```js
+const loadingInstance = Vue.prototype.$loading({
+  target: document.body, // 或指定 DOM
+  lock: true,
+  text: "加载中...",
+  background: "rgba(0, 0, 0, 0.3)",
+});
+```
+
+常用配置：
+
+- `target`：需要覆盖的 DOM 节点（DOM 对象或选择器字符串）
+- `fullscreen`：是否全屏
+- `lock`：是否锁定 body 滚动
+- `text`：加载文字
+- `background`：遮罩背景色
+
+#### 15.7.2 关闭 Loading
+
+```js
+loadingInstance.close();
+```
+
+---
+
+## 16. CCDK 使用 Checklist
+
+- [ ] 已在入口文件正确引入 `cloudcc-ccdk/lib/ccdk.min.js`
+- [ ] 前端访问 CloudCC 后端类时统一使用 `CCCommon.post`，不手工拼接 URL
+- [ ] 在对象页面/路由跳转中优先使用 `CCPage`，避免直接硬编码链接
+- [ ] 需要访问详情/列表数据时优先使用 `CCDetail` / `CCList`
+- [ ] 日志与错误统一通过 `CCLog` 上报，消息提示通过 `CCMessage` 统一管理
+- [ ] 客户端脚本与组件中合理使用 `$CCDK`，并结合 `custom-component-dev.md` 与
+      `custom-client-script.md` 中的最佳实践