cloudcc-cli 2.3.0 → 2.3.2

package/src/scheduleJob/docs/devguide.md

@@ -0,0 +1,79 @@
+# CloudCC 定时作业（scheduleJob）开发指南
+
+本指南说明 `scheduleJob` 模块在 cloudcc-cli
+中的能力边界、命令参数、接口映射与二次开发注意事项。
+
+---
+
+## 一、模块定位
+
+`scheduleJob` 只负责“作业管理”相关能力：
+
+- 查询作业列表：`get`
+- 查询作业详情：`detail`
+- 删除作业：`delete`
+- 文档查看：`doc`
+
+---
+
+## 二、CLI 命令说明
+
+### 1) 查询作业列表
+
+```bash
+cc get scheduleJob <projectPath> [encodedCondJson]
+```
+
+参数说明：
+
+| 参数              | 必填 | 说明                      |
+| ----------------- | ---- | ------------------------- |
+| `projectPath`     | 否   | 项目路径，默认当前目录    |
+| `encodedCondJson` | 否   | URI 编码后的查询条件 JSON |
+
+---
+
+### 2) 查询作业详情
+
+```bash
+cc detail scheduleJob <jobId> [projectPath]
+```
+
+参数说明：
+
+| 参数          | 必填 | 说明                   |
+| ------------- | ---- | ---------------------- |
+| `jobId`       | 是   | 定时作业 ID            |
+| `projectPath` | 否   | 项目路径，默认当前目录 |
+
+---
+
+### 3) 删除作业
+
+```bash
+cc delete scheduleJob <jobId> [projectPath]
+```
+
+参数说明：
+
+| 参数          | 必填 | 说明                   |
+| ------------- | ---- | ---------------------- |
+| `jobId`       | 是   | 待删除作业 ID          |
+| `projectPath` | 否   | 项目路径，默认当前目录 |
+
+---
+
+### 4) 查看文档
+
+```bash
+cc doc scheduleJob <introduction|devguide>
+```
+
+---
+
+## 三、关联文档
+
+- `cc doc timer introduction`
+- `cc doc timer devguide`
+
+---

package/src/scheduleJob/docs/introduction.md

@@ -0,0 +1,101 @@
+# CloudCC 定时作业（scheduleJob）介绍
+
+定时作业（`scheduleJob`）用于查看和管理已经配置在 CloudCC 平台中的调度任务。它聚焦于**作业管理侧**，常用于运维排查、任务巡检和作业下线。依赖定时类。
+
+---
+
+## 快速开始（CLI 命令）
+
+### 支持的操作
+
+| 操作 | 说明 |
+|------|------|
+| `get` | 查询定时作业列表 |
+| `detail` | 查看单个作业详情 |
+| `delete` | 删除指定作业 |
+| `doc` | 查看模块文档 |
+
+---
+
+## 什么时候用 scheduleJob
+
+当你需要处理“已配置好的定时任务”时，优先使用 `scheduleJob`：
+
+- 日常巡检：查看当前有哪些任务、是否符合预期
+- 故障排查：根据作业 ID 查看具体配置
+- 任务治理：删除无效、重复或已弃用的作业
+
+---
+
+## 与 timer 的关系
+
+- `timer`：偏向**开发与发布定时类代码**（创建、发布、拉取源码等）
+- `scheduleJob`：偏向**运行时作业管理**（查列表、查详情、删除）
+
+通常流程是：先通过 `timer` 交付能力，再通过 `scheduleJob` 做线上作业管理。
+
+---
+
+## 后台页面配置说明（与实际界面对齐）
+
+根据当前定时作业配置页面，创建/编辑作业时主要关注以下字段：
+
+| 配置项 | 是否必填 | 说明 |
+|------|------|------|
+| 作业程序 | 是 | 选择要执行的定时类程序（即作业绑定的业务逻辑） |
+| 频率 | 是 | 支持 `每周`、`每月` |
+| 星期（仅每周） | 是（每周时） | 勾选周一到周日，可多选，表示每周哪些天触发 |
+| 开始 | 是 | 作业生效开始日期 |
+| 结束 | 是 | 作业生效结束日期 |
+| 执行时间 | 是 | 每次触发的具体时间点（例如 `上午 0:00`） |
+
+### 频率规则
+
+- 选择 `每周`：必须至少勾选一个星期值（周一到周日）
+- 选择 `每月`：按每月规则触发（具体以后台月度配置项为准）
+- 所有计划都会受 `开始` 和 `结束` 日期约束，超出范围不触发
+
+### 示例：每周定时任务
+
+```text
+作业程序：客户长时间未联系新建活动
+频率：每周
+星期：星期一、星期三、星期五
+开始：2026-04-01
+结束：2026-12-31
+执行时间：上午 08:00
+```
+
+该配置表示：在有效期内，每周一/三/五上午 08:00 执行一次选定作业程序。
+
+---
+
+## 命令示例
+
+```bash
+# 1) 查看全部定时作业
+cc get scheduleJob .
+
+# 2) 带条件查询（URI 编码 JSON）
+cc get scheduleJob . '%7B%22name%22%3A%22%E6%8A%A5%E8%A1%A8%22%7D'
+
+# 3) 查看某个作业详情
+cc detail scheduleJob a0I9D000000XXXXUAI .
+
+# 4) 删除作业（危险操作）
+cc delete scheduleJob a0I9D000000XXXXUAI .
+
+# 5) 查看文档
+cc doc scheduleJob introduction
+cc doc scheduleJob devguide
+```
+
+---
+
+## 注意事项
+
+- `delete` 为破坏性操作，建议先 `detail` 再删除
+- 查询条件参数需使用 URI 编码 JSON
+- 请确保当前项目目录已完成 CloudCC CLI 初始化并可读取访问配置
+
+---

package/src/scheduleJob/get.js

@@ -0,0 +1,26 @@
+const { getPackageJson } = require("../../utils/config");
+const { postClass } = require("../../utils/http");
+
+async function get(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/schedulAbleprg/list",
+        body,
+        config.accessToken
+    );
+
+    if (res && res.result) {
+        const list = Array.isArray(res.data) ? res.data : [];
+        if (!isMcp) {
+            console.log(JSON.stringify(list));
+        }
+        return list;
+    }
+    throw new Error("Get Schedule Job Failed: " + (res?.returnInfo || res?.message || "Unknown error"));
+}
+
+module.exports = get;

package/src/scheduleJob/index.js

@@ -0,0 +1,15 @@
+const cc = {};
+cc.get = require("./get");
+cc.detail = require("./detail");
+cc.delete = require("./delete");
+cc.doc = require("./doc");
+
+function main(action, argvs) {
+    if (action === "doc") {
+        cc.doc(argvs);
+        return;
+    }
+    cc[action](argvs[2], argvs[3]);
+}
+
+module.exports = main;

package/src/script/delete.js

@@ -0,0 +1,112 @@
+const { checkUpdate } = require("../../utils/checkVersion.js");
+const chalk = require("chalk");
+const { post } = require("../../utils/http.js");
+const { getPackageJson } = require("../../utils/config.js");
+
+const BaseUrl = "https://developer.apis.cloudcc.cn";
+
+function parseScriptPath(scriptPath) {
+  const [objName, scriptName] = String(scriptPath || "").split("/");
+  if (!objName || !scriptName) {
+    throw new Error('Script path format error, should be "objName/scriptName"');
+  }
+  return { objName, scriptName };
+}
+
+async function resolveScriptIdFromRemote({ objName, scriptName }, devConsoleConfig) {
+  const body = {
+    pageSize: 50,
+    pageNo: 1,
+    condition: {
+      objName,
+      scriptName,
+      pageLabel: "",
+      id: ""
+    }
+  };
+
+  const res = await post(
+    (devConsoleConfig.baseUrl || BaseUrl) + "/devconsole/script/pageClientScript",
+    body,
+    devConsoleConfig
+  );
+
+  if (!res || !res.result) {
+    throw new Error("Query Client Script Failed: " + (res?.returnInfo || "Unknown error"));
+  }
+
+  const list = res.data?.list || [];
+  const match = list.find(it => it && it.objName === objName && it.scriptName === scriptName) || list[0];
+  if (!match || !match.id) {
+    throw new Error(`Cannot resolve script id from remote: ${objName}/${scriptName}`);
+  }
+  return match.id;
+}
+
+async function del(argvs) {
+  const res = await checkUpdate();
+  if (res) return;
+
+  const arg = argvs[2]; // scriptId or "objName/scriptName"
+  const projectPath = argvs[3] || process.cwd();
+  if (!arg) {
+    console.error();
+    console.error(chalk.red("Delete Client Script Failed: missing script id or path"));
+    console.error();
+    return;
+  }
+
+  try {
+    const devConsoleConfig = await getPackageJson(projectPath);
+    if (!devConsoleConfig || !devConsoleConfig.accessToken) {
+      console.error();
+      console.error(chalk.red("Delete Client Script Failed: accessToken is missing. Please check config/cache."));
+      console.error();
+      return;
+    }
+
+    let scriptId = arg;
+    if (String(arg).includes("/")) {
+      const scriptPath = parseScriptPath(arg);
+      scriptId = await resolveScriptIdFromRemote(scriptPath, devConsoleConfig);
+    }
+
+    const now = new Date();
+    const timeStr =
+      now.getFullYear() +
+      "-" +
+      String(now.getMonth() + 1).padStart(2, "0") +
+      "-" +
+      String(now.getDate()).padStart(2, "0") +
+      " " +
+      String(now.getHours()).padStart(2, "0") +
+      ":" +
+      String(now.getMinutes()).padStart(2, "0") +
+      ":" +
+      String(now.getSeconds()).padStart(2, "0");
+    console.error(chalk.green(timeStr));
+    console.error(chalk.green("Deleting, please wait..."));
+
+    const url = (devConsoleConfig.baseUrl || BaseUrl) + "/devconsole/script/deleteClientScript";
+    const result = await post(url, { id: scriptId }, devConsoleConfig);
+
+    if (result && result.result) {
+      console.error();
+      console.error(chalk.green("Success！"));
+      console.error();
+      return true;
+    }
+    console.error();
+    console.error(chalk.red("Delete Client Script Failed：" + (result?.returnInfo || "Unknown error")));
+    console.error();
+    return false;
+  } catch (e) {
+    console.error();
+    console.error(chalk.red("Delete Client Script Failed：" + (e?.message || e)));
+    console.error();
+    return false;
+  }
+}
+
+module.exports = del;
+

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;