cloudcc-cli 2.3.1 → 2.3.2

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)

package/src/staticResource/count.js

@@ -1,25 +1,46 @@
 const { getPackageJson } = require("../../utils/config");
-const { postClass } = require("../../utils/http");
+const BaseUrl = "https://developer.apis.cloudcc.cn";
 
+/**
+ * 静态资源 - 容量统计
+ * CLI: cc count staticResource <projectPath> [encodedCondJson]
+ * 参数说明：
+ * - projectPath: 项目根目录，默认 process.cwd()
+ * - encodedCondJson(可选): encodeURI(JSON.stringify(body))
+ * - body: 统计条件对象（可为空 {}）
+ * 请求头说明：
+ * - accessToken: 从 cloudcc-cli.config.js 读取
+ * - source: 默认 cloudcc_cli
+ */
 async function count(projectPath = process.cwd(), encodedCondJson, isMcp = false) {
     let body = {};
     if (encodedCondJson) {
         body = JSON.parse(decodeURI(encodedCondJson));
     }
     const config = await getPackageJson(projectPath);
-    const res = await postClass(
-        config.setupSvc + "/api/staticResource/countStaticResource",
-        body,
-        config.accessToken
+    const devSvcDispatch = config.devSvcDispatch || "/devconsole";
+    const baseUrl = config.baseUrl || BaseUrl;
+    const res = await fetch(
+        `${baseUrl}${devSvcDispatch}/staticResource/countStaticResource`,
+        {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json; charset=utf-8",
+                accessToken: config.accessToken,
+                source: config.source || "cloudcc_cli",
+            },
+            body: JSON.stringify(body),
+        }
     );
-    if (res && res.result) {
-        const data = res.data || {};
+    const data = await res.json();
+    if (data && (data.result || String(data.returnCode) === "200" || String(data.returnCode).endsWith("-OK"))) {
+        const countData = data.data || {};
         if (!isMcp) {
-            console.log(JSON.stringify(data));
+            console.log(JSON.stringify(countData));
         }
-        return data;
+        return countData;
     }
-    throw new Error("Count Static Resource Failed: " + (res?.returnInfo || res?.message || "Unknown error"));
+    throw new Error("Count Static Resource Failed: " + (data?.returnInfo || data?.message || "Unknown error"));
 }
 
 module.exports = count;

package/src/staticResource/create.js

@@ -0,0 +1,97 @@
+/**
+ * 静态资源 - 新建/编辑（上传）
+ * CLI: cc create staticResource <projectPath> <encodedBodyJson>
+ * 参数说明：
+ * - projectPath: 项目根目录
+ * - encodedBodyJson: encodeURI(JSON.stringify(body))
+ * - body:
+ *   {
+ *     filePath?: string,   // 新建必填；编辑不换文件可不传
+ *     label: string,       // 必填
+ *     desc?: string,       // 可选
+ *     id?: string,         // 编辑时传
+ *     name?: string,       // 可选，不传默认取文件名
+ *     type?: string        // 可选，不传默认取文件后缀
+ *   }
+ */
+const fs = require("fs");
+const path = require("path");
+const chalk = require("chalk");
+const { getPackageJson } = require("../../utils/config");
+
+const BaseUrl = "https://developer.apis.cloudcc.cn";
+
+async function create(projectPath = process.cwd(), encodedBodyJson) {
+    if (!encodedBodyJson) {
+        throw new Error("Create Static Resource Failed: encodedBodyJson is required");
+    }
+
+    const body = JSON.parse(decodeURI(encodedBodyJson));
+    const { filePath, label, desc = "", id = "", name, type } = body || {};
+
+    if (!label) {
+        throw new Error("Create Static Resource Failed: label is required");
+    }
+
+    const config = await getPackageJson(projectPath);
+    if (!config || !config.accessToken) {
+        throw new Error("Create Static Resource Failed: accessToken is missing");
+    }
+
+    const devSvcDispatch = config.devSvcDispatch || "/devconsole";
+    const baseUrl = config.baseUrl || BaseUrl;
+    const url = `${baseUrl}${devSvcDispatch}/staticResource/saveStaticResource`;
+
+    const formData = new FormData();
+    formData.append("label", String(label));
+    formData.append("desc", String(desc));
+    if (id) {
+        formData.append("id", String(id));
+    }
+
+    if (filePath) {
+        const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(projectPath, filePath);
+        if (!fs.existsSync(absPath)) {
+            throw new Error(`Create Static Resource Failed: file not found - ${absPath}`);
+        }
+        const fileBuffer = fs.readFileSync(absPath);
+        const fileName = name || path.basename(absPath);
+        const fileType = type || path.extname(fileName).replace(".", "");
+        formData.append("name", fileName);
+        formData.append("type", fileType);
+        formData.append("file", new Blob([fileBuffer]), fileName);
+    } else {
+        // 编辑且不更换文件时，按接口约定传空字符串。
+        formData.append("file", "");
+        if (name) {
+            formData.append("name", String(name));
+        }
+        if (type) {
+            formData.append("type", String(type));
+        }
+    }
+
+    console.error();
+    console.error(chalk.green("Saving static resource, please wait..."));
+    console.error();
+
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            accessToken: config.accessToken,
+            source: config.source || "cloudcc_cli",
+        },
+        body: formData,
+    });
+    const result = await res.json();
+
+    if (result && (result.result || String(result.returnCode) === "200" || String(result.returnCode).endsWith("-OK"))) {
+        console.error(chalk.green("Success! Static resource saved."));
+        console.error();
+        return result;
+    }
+
+    throw new Error("Create Static Resource Failed: " + (result?.returnInfo || result?.message || "Unknown error"));
+}
+
+module.exports = create;

package/src/staticResource/delete.js

@@ -1,7 +1,19 @@
 const chalk = require("chalk");
 const { getPackageJson } = require("../../utils/config");
-const { postClass } = require("../../utils/http");
+const BaseUrl = "https://developer.apis.cloudcc.cn";
 
+/**
+ * 静态资源 - 删除
+ * CLI: cc delete staticResource <projectPath> <resourceId>
+ * 参数说明：
+ * - projectPath: 项目根目录，默认 process.cwd()
+ * - id(resourceId): 静态资源 id（必填）
+ * 请求体说明：
+ * - { id }
+ * 请求头说明：
+ * - accessToken: 从 cloudcc-cli.config.js 读取
+ * - source: 默认 cloudcc_cli
+ */
 async function remove(projectPath = process.cwd(), id) {
     if (!id) {
         throw new Error("Delete Static Resource Failed: id is required");
@@ -10,17 +22,27 @@ async function remove(projectPath = process.cwd(), id) {
     console.error();
     console.error(chalk.green(`Deleting static resource (${id}), please wait...`));
     console.error();
-    const res = await postClass(
-        config.setupSvc + "/api/staticResource/deleteStaticResource",
-        { id },
-        config.accessToken
+    const devSvcDispatch = config.devSvcDispatch || "/devconsole";
+    const baseUrl = config.baseUrl || BaseUrl;
+    const res = await fetch(
+        `${baseUrl}${devSvcDispatch}/staticResource/deleteStaticResource`,
+        {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json; charset=utf-8",
+                accessToken: config.accessToken,
+                source: config.source || "cloudcc_cli",
+            },
+            body: JSON.stringify({ id }),
+        }
     );
-    if (res && res.result) {
+    const data = await res.json();
+    if (data && (data.result || String(data.returnCode) === "200" || String(data.returnCode).endsWith("-OK"))) {
         console.error(chalk.green("Success! Static resource deleted."));
         console.error();
-        return res;
+        return data;
     }
-    throw new Error("Delete Static Resource Failed: " + (res?.returnInfo || res?.message || "Unknown error"));
+    throw new Error("Delete Static Resource Failed: " + (data?.returnInfo || data?.message || "Unknown error"));
 }
 
 module.exports = remove;

package/src/staticResource/detail.js

@@ -1,24 +1,46 @@
 const { getPackageJson } = require("../../utils/config");
-const { postClass } = require("../../utils/http");
+const BaseUrl = "https://developer.apis.cloudcc.cn";
 
+/**
+ * 静态资源 - 查询详情
+ * CLI: cc detail staticResource <projectPath> <resourceId>
+ * 参数说明：
+ * - projectPath: 项目根目录，默认 process.cwd()
+ * - id(resourceId): 静态资源 id（必填）
+ * 请求体说明：
+ * - { id }
+ * 请求头说明：
+ * - accessToken: 从 cloudcc-cli.config.js 读取
+ * - source: 默认 cloudcc_cli
+ */
 async function detail(projectPath = process.cwd(), id, isMcp = false) {
     if (!id) {
         throw new Error("Static Resource detail requires id");
     }
     const config = await getPackageJson(projectPath);
-    const res = await postClass(
-        config.setupSvc + "/api/staticResource/detailStaticResource",
-        { id },
-        config.accessToken
+    const devSvcDispatch = config.devSvcDispatch || "/devconsole";
+    const baseUrl = config.baseUrl || BaseUrl;
+    const res = await fetch(
+        `${baseUrl}${devSvcDispatch}/staticResource/detailStaticResource`,
+        {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json; charset=utf-8",
+                accessToken: config.accessToken,
+                source: config.source || "cloudcc_cli",
+            },
+            body: JSON.stringify({ id }),
+        }
     );
-    if (res && res.result) {
-        const data = res.data || {};
+    const data = await res.json();
+    if (data && (data.result || String(data.returnCode) === "200" || String(data.returnCode).endsWith("-OK"))) {
+        const detailData = data.data || {};
         if (!isMcp) {
-            console.log(JSON.stringify(data));
+            console.log(JSON.stringify(detailData));
         }
-        return data;
+        return detailData;
     }
-    throw new Error("Get Static Resource Detail Failed: " + (res?.returnInfo || res?.message || "Unknown error"));
+    throw new Error("Get Static Resource Detail Failed: " + (data?.returnInfo || data?.message || "Unknown error"));
 }
 
 module.exports = detail;