cloudcc-cli 2.3.1 → 2.3.3

package/src/script/doc.js

@@ -1,259 +1,45 @@
-/**
- * script 文档统一入口（全量一次性输出）
- */
 const fs = require("fs");
 const path = require("path");
 
-function generateFullMarkdownDoc() {
-    const lines = [
-        "# CloudCC 客户端脚本开发指南",
-        "",
-        "> 本文档参考 CloudCC 官方「客户端脚本」文档整理而成：[客户端脚本](https://help.cloudcc.cn/product03/ke-hu-duan-jiao-ben/)。  ",
-        "> 目标：指导开发者在不同页面（列表、新建/编辑、详情、全局）特定时机运行 JavaScript，基于 CCDK 能力实现字段控制、布局调整等前端增强。",
-        "",
-        "---",
-        "",
-        "## 1. 概念与入口",
-        "",
-        "### 1.1 什么是客户端脚本",
-        "",
-        "- 客户端脚本是在 **浏览器端**、特定页面和时机执行的一段 JavaScript。  ",
-        "- 依托 `$CCDK` 提供的桥接能力，可以：",
-        "  - 显示提示信息",
-        "  - 控制字段显隐 / 只读",
-        "  - 调整页面 DOM 结构",
-        "  - 在保存前/后执行校验或自定义逻辑",
-        "",
-        "### 1.2 进入客户端脚本设置页面",
-        "",
-        "1. 登录 CloudCC 系统  ",
-        "2. 点击右上角头像，选择「开发者平台」（仅管理员简档可见）  ",
-        "3. 左侧菜单：`扩展 → 客户端脚本`",
-        "",
-        "---",
-        "",
-        "## 2. 创建第一个客户端脚本",
-        "",
-        "### 2.1 新建脚本",
-        "",
-        "1. 在「客户端脚本」列表页，点击右上角「新建」  ",
-        "2. 填写基本信息（名称、适用对象/页面/事件等），进入代码编辑页面  ",
-        "3. 在代码输入区输入示例代码：",
-        "",
-        "```javascript",
-        "$CCDK.CCMessage.showMessage('hello cloudCC');",
-        "```",
-        "",
-        "4. 点击右上角「保存」",
-        "",
-        "### 2.2 回到前台查看效果",
-        "",
-        "例如：  ",
-        "- 配置为在「客户详情页 onLoad」执行  ",
-        "- 返回前台 → 打开客户菜单 → 进入任意一条客户详情  ",
-        "- 页面加载完成后，会看到 `hello cloudCC` 提示信息",
-        "",
-        "---",
-        "",
-        "## 3. 利用 devid 精确控制页面元素",
-        "",
-        "> 为方便控制页面元素，平台在关键 DOM 节点上添加了 `devid` 自定义属性，并使用特定业务 ID 绑定。可通过 F12 查看并用于脚本选择器。",
-        "",
-        "### 3.1 示例：禁用编辑页的「分级」字段",
-        "",
-        "#### 第一步：查看 devid",
-        "",
-        "1. 按 `F12` 打开浏览器开发者工具  ",
-        "2. 切换到「元素」(Elements) 面板  ",
-        "3. 使用元素选择器选中「分级」字段对应 DOM  ",
-        "4. 在右侧/标签属性中查找并复制该元素的 `devid` 值备用",
-        "",
-        "#### 第二步：创建客户端脚本",
-        "",
-        "在客户端脚本中，根据 `devid` 操作 DOM：",
-        "",
-        "```javascript",
-        "// 方式一：通过动态插入样式禁用点击",
-        "let style = document.createElement('style');",
-        "style.type = 'text/css';",
-        "style.innerHTML = '[devid=\"ffe201100003855g6Ipz\"]{pointer-events:none}';",
-        "document.getElementsByTagName('head').item(0).appendChild(style);",
-        "",
-        "// 方式二：直接隐藏某个元素",
-        "let dd = document.querySelector('div[devid=\"ffe201100003428r65pk\"]');",
-        "if (dd) {",
-        "  dd.style.display = \"none\";",
-        "}",
-        "```",
-        "",
-        "保存后回到前台，进入对应页面查看效果。",
-        "",
-        "### 3.2 示例：隐藏详情页某个字段",
-        "",
-        "同样通过 `devid` 精确定位字段，再注入样式：",
-        "",
-        "```javascript",
-        "// 隐藏并不占用空间",
-        "let style = document.createElement('style');",
-        "style.type = 'text/css';",
-        "style.innerHTML = '[devid=\"ffe20220523account01\"]{display:none !important}';",
-        "document.getElementsByTagName('head').item(0).appendChild(style);",
-        "```",
-        "",
-        "```javascript",
-        "// 隐藏但保留空间",
-        "let style = document.createElement('style');",
-        "style.type = 'text/css';",
-        "style.innerHTML = '[devid=\"ffe20220523account01\"]{visibility:hidden !important}';",
-        "document.getElementsByTagName('head').item(0).appendChild(style);",
-        "```",
-        "",
-        "### 3.3 示例：移动页面元素到其他位置",
-        "",
-        "```javascript",
-        "// 获取要移动的节点",
-        "const moveNode = document.querySelector('[devid=\"aee2024EFBBA5EEfs1Ta\"]');",
-        "// 目标节点",
-        "const targetNode = document.querySelector('[devid=\"adf2024D33E03DA6xzBj\"]');",
-        "// 目标节点的父节点",
-        "const targetParentNode = targetNode.parentNode;",
-        "",
-        "// 将需要移动的节点插入到目标节点前面",
-        "if (moveNode && targetNode && targetParentNode) {",
-        "  targetParentNode.insertBefore(moveNode, targetNode);",
-        "}",
-        "```",
-        "",
-        "**注意**：DOM 可能尚未渲染完成，可结合定时器或 `MutationObserver` 等机制等待节点出现。",
-        "",
-        "---",
-        "",
-        "## 4. 页面类型与脚本事件映射",
-        "",
-        "> 系统页面大致分为「全局、列表、新建/编辑、详情」等类型，每种页面支持不同事件，脚本在对应时机执行。",
-        "",
-        "以下是官方提供的主要事件（简化说明）：",
-        "",
-        "### 4.1 全局类型",
-        "",
-        "- **onCreate**",
-        "  - 适用：PC / HS",
-        "  - 函数签名：`function test($CCDK, obj = {})`",
-        "  - 说明：项目启动时触发（业务页面代码尚未执行）",
-        "",
-        "- **onLoad**",
-        "  - 适用：PC / HS",
-        "  - 场景：全局 UI 首次展示后",
-        "",
-        "- **onDestroy**",
-        "  - 适用：PC / HS",
-        "  - 场景：关闭 Tab / 更改流程等导致当前应用关闭时",
-        "",
-        "### 4.2 视图页（列表页面）",
-        "",
-        "事件函数统一形如：`function test($CCDK, obj = {})`",
-        "",
-        "- **onCreated**",
-        "  - 时机：进入视图页，但 DOM 还未创建  ",
-        "- **onLoad**",
-        "  - 时机：首次进入，或点击搜索刷新列表数据后  ",
-        "- **onDestroy**",
-        "  - 时机：离开列表页（如进入详情页等）",
-        "",
-        "### 4.3 新建/编辑页",
-        "",
-        "同样使用 `function test($CCDK, obj = {})`：",
-        "",
-        "- **onCreated**",
-        "  - 时机：进入新建/编辑页面，但 DOM 尚未创建  ",
-        "- **onLoad**",
-        "  - 时机：详情数据加载完成、页面渲染结束  ",
-        "- **onDestroy**",
-        "  - 时机：离开新建/编辑页面  ",
-        "- **beforeSave**",
-        "  - 参数：`obj.detailData` 为 key-value 形式的详情数据，**可以在这里修改**  ",
-        "  - 时机：点击保存按钮时触发，适合做前端校验与补充字段赋值  ",
-        "- **afterSave**",
-        "  - 时机：保存接口请求完成后触发  ",
-        "- **onChange**",
-        "  - 时机：编辑某个字段、光标失焦，且 value 有变化时触发",
-        "",
-        "### 4.4 详情页",
-        "",
-        "- **onLoad**",
-        "  - 适用：PC / HS  ",
-        "  - 时机：获取详情基础数据并完成 DOM 渲染后触发  ",
-        "",
-        "---",
-        "",
-        "## 5. 实战建议与注意事项",
-        "",
-        "### 5.1 DOM 渲染时机",
-        "",
-        "- 部分页面在脚本执行时 DOM 可能尚未完全渲染，建议：",
-        "  - 使用 `setTimeout` / 轮询检查目标节点是否存在  ",
-        "  - 或配合 `MutationObserver` 监听 DOM 变化后再操作  ",
-        "",
-        "### 5.2 与 CCDK 的配合",
-        "",
-        "- `$CCDK` 提供了多种能力，如：",
-        "  - `CCMessage`：消息提示  ",
-        "  - `CCLoad`：脚本/样式加载  ",
-        "  - 其他与对象/类交互的桥接能力  ",
-        "- 客户端脚本中应优先调用 `$CCDK` 而非自行拼接接口。",
-        "",
-        "### 5.3 与自定义组件的边界",
-        "",
-        "- 客户端脚本更适合：",
-        "  - 简单的字段控制",
-        "  - 小范围布局微调",
-        "  - 轻量交互增强  ",
-        "- 更复杂的 UI、交互与业务逻辑推荐用「自定义组件」实现（详见 `custom-component-dev.md`）。",
-        "",
-        "---",
-        "",
-        "## 6. 客户端脚本开发 Checklist",
-        "",
-        "- [ ] 已在「开发者平台 → 客户端脚本」正确选择对象、页面类型与事件（onLoad / beforeSave 等）  ",
-        "- [ ] 使用 `$CCDK` 能力而非手工拼接接口或直接依赖不稳定的全局变量  ",
-        "- [ ] 所有 DOM 操作都考虑了渲染时机，避免因节点不存在而报错  ",
-        "- [ ] 通过 `devid` 精确定位关键元素，避免依赖脆弱的层级或 class 选择器  ",
-        "- [ ] 对性能敏感操作（如定时器、频繁 DOM 查询）做了节流或销毁处理  ",
-        "- [ ] 已区分客户端脚本与自定义组件的职责，将复杂 UI / 交互放到组件中实现  ",
-        "- [ ] 在目标环境中完整测试：列表 / 新建 / 编辑 / 详情等场景，确认无脚本错误和布局异常  ",
-        "",
-    ];
+const DOCS_DIR = path.join(__dirname, "docs");
+const INTRODUCTION = path.join(DOCS_DIR, "introduction.md");
+const DEVGUIDE = path.join(DOCS_DIR, "devguide.md");
 
-    const base = lines.join("\n");
-    const ccdkPath = path.join(__dirname, "..", "api", "ccdk-sdk.md");
-    let ccdkContent = "";
+function readDocOrFallback(filePath, fallback) {
     try {
-        ccdkContent = fs.readFileSync(ccdkPath, "utf8");
+        return fs.readFileSync(filePath, "utf8").trim();
     } catch (e) {
-        ccdkContent = `# CloudCC 前端 SDK（cloudcc-ccdk）使用指南\n\n（未找到文件：${ccdkPath}）\n`;
+        return fallback;
     }
+}
 
-    return [
-        base,
-        "",
-        "---",
-        "",
-        "## 附录：CCDK SDK 速查",
-        "",
-        "> 来源：`src/api/ccdk-sdk.md`",
-        "",
-        ccdkContent.trim(),
-        "",
-    ].join("\n");
+function getIntroductionDoc() {
+    return readDocOrFallback(
+        INTRODUCTION,
+        `# CloudCC 客户端脚本介绍\n\n（未找到文件：${INTRODUCTION}）\n`
+    );
 }
 
-function doc() {
-    const content = generateFullMarkdownDoc();
-    console.log(content);
-    return content;
+function getDevGuideDoc() {
+    return readDocOrFallback(
+        DEVGUIDE,
+        `# CloudCC 客户端脚本开发指南\n\n（未找到文件：${DEVGUIDE}）\n`
+    );
 }
 
-// 兼容旧调用方：仍提供同名入口（但都返回全量文档）
-doc.getEditGuide = doc;
+function doc(argvs = []) {
+    const subType = String(argvs[2] || "").trim().toLowerCase();
+    if (!subType || subType === "devguide") {
+        const content = getDevGuideDoc();
+        console.log(content);
+        return content;
+    }
+    if (subType === "introduction") {
+        const content = getIntroductionDoc();
+        console.log(content);
+        return content;
+    }
+    throw new Error(`doc 不支持的子命令: ${argvs[2]}，请使用 introduction 或 devguide`);
+}
 
 module.exports = doc;

package/src/script/docs/devguide.md

@@ -0,0 +1,290 @@
+# CloudCC Script 文档（全量）
+
+## 客户端脚本（Script）操作指南
+
+直接查看：`cc doc script`
+
+---
+
+## 1. 常见操作
+
+- 查询客户端脚本列表
+- 查看客户端脚本详情
+- 新建客户端脚本（生成本地目录与模板）
+- 发布客户端脚本到环境（保存/更新线上脚本）
+- 从环境拉取脚本内容到本地（覆盖本地脚本文件）
+- 删除客户端脚本
+
+---
+
+## 2. 常用 CLI 命令
+
+### 1) 查看客户端脚本文档
+
+命令：
+
+```bash
+cc doc script
+```
+
+说明：输出客户端脚本文档，并自动附带本文件内容。
+
+---
+
+### 2) 查询客户端脚本列表
+
+命令：
+
+```bash
+cc get script <encodedCondJson> <projectPath>
+```
+
+参数说明：
+
+| 参数名称 | 类型 | 是否必须 | 默认值 | 备注 |
+| :--- | :--- | :--- | :--- | :--- |
+| encodedCondJson | string | 视场景 | — | `encodeURI(JSON.stringify(body))` |
+| projectPath | string | 非必须 | 当前目录 | 项目根目录 |
+
+请求体（decoded 后）字段（与页面抓包一致）：
+
+| 参数名称 | 类型 | 是否必须 | 默认值 | 备注 |
+| :--- | :--- | :--- | :--- | :--- |
+| pageSize | number | 非必须 | `50` | 每页条数 |
+| pageNo | number | 非必须 | `1` | 页码（从 1 开始） |
+| condition | object | 非必须 | `{}` | 查询条件 |
+| condition.scriptName | string | 非必须 | `""` | 脚本名称筛选 |
+| condition.pageLabel | string | 非必须 | `""` | 页面标签筛选 |
+| condition.objName | string | 非必须 | `""` | 对象名称筛选 |
+
+输出：简化列表（每条包含 `name` / `id` / `apiname`）。
+
+---
+
+### 3) 查看客户端脚本详情
+
+命令（两种用法）：
+
+```bash
+# 1) 按本地脚本路径查看（不依赖线上）
+cc detail script <objName/scriptName>
+
+# 2) 按线上脚本 id 查看
+cc detail script "" <scriptId> <projectPath>
+```
+
+说明：
+
+- 传 `objName/scriptName`：读取本地 `script/<objName>/<scriptName>/config.json` 和脚本文件。
+- 传 `scriptId`：调用线上接口查询并返回详情。
+
+---
+
+### 4) 新建客户端脚本（本地生成）
+
+命令：
+
+```bash
+cc create script <encodedBodyJson>
+```
+
+参数说明：
+
+| 参数名称 | 类型 | 是否必须 | 默认值 | 备注 |
+| :--- | :--- | :--- | :--- | :--- |
+| encodedBodyJson | string | 必须 | — | `encodeURI(JSON.stringify(body))` |
+
+请求体（decoded 后）常用字段（会写入 `config.json`）：
+
+| 参数名称 | 类型 | 是否必须 | 默认值 | 备注 |
+| :--- | :--- | :--- | :--- | :--- |
+| objName | string | 必须 | — | 对象 API 名称（目录名） |
+| scriptName | string | 必须 | — | 脚本名称（目录名 + 文件名） |
+| pageId / eventType / event / fieldId / usageScenario | string | 非必须 | `""` | 作为脚本配置元数据 |
+
+生成目录结构：
+
+- `script/<objName>/<scriptName>/<scriptName>.js`
+- `script/<objName>/<scriptName>/config.json`
+
+---
+
+### 5) 发布客户端脚本（保存到线上）
+
+命令：
+
+```bash
+cc publish script <objName/scriptName>
+```
+
+说明：
+
+- 读取本地 `script/<objName>/<scriptName>/<scriptName>.js` 与 `config.json`
+- 只会发布 `function main($CCDK, obj) { ... }` 的函数体内容（会校验 main 函数存在）
+- 首次发布成功后，会把返回的 `id` 写回 `config.json`，用于后续更新/拉取/删除
+
+---
+
+### 6) 拉取客户端脚本（用线上内容覆盖本地）
+
+命令：
+
+```bash
+cc pull script <objName/scriptName>
+```
+
+说明：要求本地 `config.json` 内已存在 `id`（先发布一次）。
+
+---
+
+### 7) 拉取线上脚本到本地（按 id 拉取并生成目录）
+
+命令：
+
+```bash
+cc pullList script <scriptId> <projectPath>
+```
+
+说明：会在 `<projectPath>/script/<objName>/<scriptName>/` 下生成 `config.json` 与脚本文件。
+
+---
+
+### 8) 删除客户端脚本
+
+命令（两种用法）：
+
+```bash
+# 1) 直接按 scriptId 删除
+cc delete script <scriptId> <projectPath>
+
+# 2) 按 "objName/scriptName" 删除（会先查询解析出 id，再删除）
+cc delete script <objName/scriptName> <projectPath>
+```
+
+---
+
+## 3. 示例
+
+### 查询客户端脚本列表（默认条件）
+
+```bash
+cc get script "$(node -e "console.log(encodeURI(JSON.stringify({pageSize:50,pageNo:1,condition:{scriptName:'',pageLabel:'',objName:''}})))")" .
+```
+
+### 按脚本名筛选（例如：test）
+
+```bash
+cc get script "$(node -e "console.log(encodeURI(JSON.stringify({pageSize:50,pageNo:1,condition:{scriptName:'test',pageLabel:'',objName:''}})))")" .
+```
+
+### 新建脚本（本地）
+
+```bash
+cc create script "$(node -e "console.log(encodeURI(JSON.stringify({objName:'contact',scriptName:'hello_script'})))")"
+```
+
+### 发布脚本（上线）
+
+```bash
+cc publish script contact/hello_script
+```
+
+### 拉取脚本（从线上覆盖本地）
+
+```bash
+cc pull script contact/hello_script
+```
+
+### 删除脚本（按 id）
+
+```bash
+cc delete script <scriptId> .
+```
+
+---
+
+## 4. Checklist
+
+- [ ] 已在正确项目目录执行命令（或显式传入 `projectPath`）
+- [ ] `cc get script` 的条件已按 `encodeURI(JSON.stringify(...))` 传入
+- [ ] 发布前脚本文件包含 `function main($CCDK, obj) { ... }`
+- [ ] 首次发布后确认 `config.json` 已写入 `id`
+- [ ] 拉取/删除前确认目标 `id` 正确（避免误删）
+
+---
+
+## 5. 进阶示例
+
+### 5.1 快速入门示例
+
+#### 进入客户端脚本设置页面
+
+1. 登录 CloudCC 系统
+2. 点击右上角头像，选择「开发者平台」（仅管理员简档可见）
+3. 左侧菜单：`扩展 -> 客户端脚本`
+
+#### 新建并执行第一个脚本
+
+在代码输入区输入：
+
+```javascript
+$CCDK.CCMessage.showMessage("hello cloudCC");
+```
+
+保存后进入对应页面（如详情页 `onLoad`），可看到提示信息。
+
+### 5.2 基于 devid 控制页面元素
+
+> 可通过浏览器开发者工具（F12）查看页面元素上的 `devid`，再在脚本中精确定位。
+
+#### 禁用编辑页字段
+
+```javascript
+let style = document.createElement("style");
+style.type = "text/css";
+style.innerHTML = '[devid="ffe201100003855g6Ipz"]{pointer-events:none}';
+document.getElementsByTagName("head").item(0).appendChild(style);
+```
+
+#### 隐藏详情页字段（不占位）
+
+```javascript
+let style = document.createElement("style");
+style.type = "text/css";
+style.innerHTML = '[devid="ffe20220523account01"]{display:none !important}';
+document.getElementsByTagName("head").item(0).appendChild(style);
+```
+
+#### 隐藏详情页字段（保留占位）
+
+```javascript
+let style = document.createElement("style");
+style.type = "text/css";
+style.innerHTML = '[devid="ffe20220523account01"]{visibility:hidden !important}';
+document.getElementsByTagName("head").item(0).appendChild(style);
+```
+
+#### 移动页面元素位置
+
+```javascript
+const moveNode = document.querySelector('[devid="aee2024EFBBA5EEfs1Ta"]');
+const targetNode = document.querySelector('[devid="adf2024D33E03DA6xzBj"]');
+const targetParentNode = targetNode && targetNode.parentNode;
+
+if (moveNode && targetNode && targetParentNode) {
+    targetParentNode.insertBefore(moveNode, targetNode);
+}
+```
+
+### 5.3 事件选择建议
+
+- 全局脚本：适合应用启动、销毁等全局行为
+- 列表页脚本：适合列表加载后增强
+- 新建/编辑页脚本：适合 `beforeSave` 校验与赋值
+- 详情页脚本：适合详情渲染后字段展示控制
+
+### 5.4 使用注意事项
+
+- DOM 可能未渲染完成，建议结合 `setTimeout` 或 `MutationObserver`
+- 优先使用 `$CCDK` 能力，不建议直接拼接接口调用
+- 对频繁执行逻辑做好性能控制，避免页面卡顿

package/src/script/docs/introduction.md

@@ -0,0 +1,48 @@
+# CloudCC 客户端脚本介绍
+
+客户端脚本是在 CloudCC
+前端页面（如列表页、新建/编辑页、详情页、全局页面）特定事件时机执行的一段
+JavaScript。它依托 `$CCDK`
+的桥接能力，在不改造核心系统代码的前提下，快速实现页面行为和交互的业务化定制。
+
+## 能干什么
+
+- 在页面加载、字段变更、保存前后等时机执行自定义逻辑
+- 控制字段显隐、只读、禁用、默认值与展示顺序
+- 基于页面元素 `devid` 做精确的 DOM 调整（隐藏、移动、样式优化等）
+- 增加消息提示、前端校验、轻量自动化处理
+- 对不同页面类型配置不同脚本，实现同对象的差异化行为
+
+## 主要作用
+
+- 让业务规则更贴近一线使用场景，而不是被标准页面能力限制
+- 用小成本实现高频、细粒度的前端需求调整
+- 缩短需求交付周期，降低“等待版本发版”带来的响应延迟
+
+## 为什么要用
+
+- 标准配置无法覆盖所有业务细节，尤其是页面行为层面的动态需求
+- 某些需求只在特定页面、特定角色、特定时机触发，客户端脚本更灵活
+- 相比重型开发方式（完整自定义组件/页面），客户端脚本更轻量、迭代更快
+
+## 能解决哪些问题
+
+- 保存前做字段联动与数据校验，减少脏数据入库
+- 详情页按业务需要隐藏敏感信息或弱化无关字段
+- 编辑页限制关键字段误操作（禁用或只读）
+- 按流程阶段动态调整页面交互，减少用户操作路径和学习成本
+- 对标准页面做局部增强，而不影响系统其他模块
+
+## 在什么情况下使用
+
+- 需求是“前端页面行为增强”，且改动范围集中在单页或少量页面
+- 需要快速上线验证，后续可能持续迭代优化
+- 需要利用页面事件（如 `onLoad`、`beforeSave`、`onChange`）挂载业务逻辑
+- 希望复用 CloudCC 现有页面能力，不希望引入过重改造
+
+## 典型业务场景
+
+- 销售管理：编辑客户时按客户等级控制字段可编辑范围
+- 服务管理：详情页按服务阶段动态显示关键指标字段
+- 线索管理：保存前自动补齐或校验必填业务字段
+- 渠道管理：列表页加载后增加提示与辅助标识，帮助快速筛选和处理

package/src/script/index.js

@@ -5,6 +5,7 @@ cc.pull = require("./pull")
 cc.get = require("./get")
 cc.pullList = require("./pullList")
 cc.detail = require("./detail")
+cc.delete = require("./delete")
 cc.doc = require("./doc")
 function main(action, argvs) {
   cc[action](argvs)