cloudcc-cli 2.3.1 → 2.3.3

package/src/role/docs/devguide.md

@@ -0,0 +1,81 @@
+# CloudCC 角色 CLI 命令说明
+
+## 支持的命令
+
+| 操作 | 说明 |
+|------|------|
+| `create` | 创建新角色 |
+| `get` | 查询角色列表 |
+| `delete` | 删除角色 |
+
+## CLI 命令详解
+
+### 创建角色
+
+```bash
+cc create role <path> <roleName> [parentRoleName] [description]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `path` | 是 | 项目路径，`.` 表示当前目录 |
+| `roleName` | 是 | 角色名称 |
+| `parentRoleName` | 否 | 直属上司角色名称（不传则交互式选择）|
+| `description` | 否 | 角色描述 |
+
+**示例：**
+
+```bash
+# 交互式选择直属上司
+cc create role . "销售经理"
+
+# 指定直属上司（非交互式）
+cc create role . "销售经理" "CEO"
+
+# 指定直属上司并添加描述
+cc create role . "市场专员" "销售总监" "负责市场推广工作"
+```
+
+### 查询角色列表
+
+```bash
+cc get role <projectPath> [encodedCondJson]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `encodedCondJson` | 否 | URI 编码后的查询条件 JSON |
+
+**示例：**
+
+```bash
+# 获取所有角色
+cc get role .
+
+# 带查询条件
+cc get role . '%7B%22name%22%3A%22%E9%94%80%E5%94%AE%22%7D'
+```
+
+### 删除角色
+
+```bash
+cc delete role <projectPath> <roleId>
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `roleId` | 是 | 角色 ID |
+
+**示例：**
+
+```bash
+cc delete role . a0I9D000000XXXXUAI
+```

package/src/role/docs/introduction.md

@@ -0,0 +1,124 @@
+# CloudCC 角色使用总结
+
+角色（Role）用于定义 CloudCC 系统中的职能分工，可以对用户进行分组管理并分配不同的权限。
+
+---
+
+## 快速开始（CLI 命令）
+
+### 支持的角色操作
+
+| 操作 | 说明 |
+|------|------|
+| `create` | 创建新角色 |
+| `get` | 查询角色列表 |
+| `delete` | 删除角色 |
+
+---
+
+## CLI 命令详解
+
+### 创建角色
+
+创建一个新的 CloudCC 角色。
+
+```bash
+cc create role <path> <roleName> [description]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `path` | 是 | 项目路径，`.` 表示当前目录 |
+| `roleName` | 是 | 角色名称 |
+| `description` | 否 | 角色描述 |
+
+**示例：**
+
+```bash
+# 创建角色
+cc create role . "销售经理"
+
+# 创建带描述的角色
+cc create role . "市场专员" "负责市场推广工作"
+```
+
+---
+
+### 查询角色列表
+
+获取当前环境中的所有角色列表。
+
+```bash
+cc get role <projectPath> [encodedCondJson]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `encodedCondJson` | 否 | URI 编码后的查询条件 JSON |
+
+**示例：**
+
+```bash
+# 获取所有角色
+cc get role .
+
+# 带查询条件
+cc get role . '%7B%22name%22%3A%22%E9%94%80%E5%94%AE%22%7D'
+```
+
+---
+
+### 删除角色
+
+删除指定的角色。
+
+```bash
+cc delete role <projectPath> <roleId>
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `roleId` | 是 | 角色 ID |
+
+**示例：**
+
+```bash
+# 删除指定角色
+cc delete role . a0I9D000000XXXXUAI
+```
+
+---
+
+## 完整工作流示例
+
+### 场景：为新部门创建 CloudCC 角色
+
+```bash
+# 1. 确认项目已初始化（有 cloudcc-cli.config.js）
+cat cloudcc-cli.config.js
+
+# 2. 查询现有角色
+cc get role .
+
+# 3. 创建新角色
+cc create role . "销售经理"
+cc create role . "销售代表"
+
+# 4. 验证角色创建成功
+cc get role .
+
+# 5. 如需删除
+# cc delete role . <roleId>
+```
+
+---
+
+*文档版本：1.0 | 最后更新：2026-03-26*

package/src/role/get.js

@@ -0,0 +1,57 @@
+const { postClass } = require("../../utils/http");
+const { getPackageJson } = require("../../utils/config");
+
+/**
+ * 查询角色列表
+ * 用法：cc get role <projectPath> [encodedCondJson]
+ * 接口：POST /api/role/queryRole
+ * 默认参数：{ display: "list" }
+ */
+async function get(argvs, isMcp = false) {
+    const projectPath = argvs[2] || process.cwd();
+    const condArg = argvs[3];
+
+    let body = { display: "list" };
+    if (condArg) {
+        try {
+            body = JSON.parse(decodeURI(condArg));
+        } catch (e) {
+            throw new Error("Get Role Failed: encodedCondJson 解析失败，请传 encodeURI(JSON.stringify(...))");
+        }
+    }
+
+    const config = await getPackageJson(projectPath);
+    const res = await postClass(
+        config.setupSvc + "/api/role/queryRole",
+        body,
+        config.accessToken
+    );
+
+    if (res && res.result) {
+        const data = res.data;
+        let rawList = [];
+        if (Array.isArray(data)) {
+            rawList = data;
+        } else if (data && Array.isArray(data.list)) {
+            rawList = data.list;
+        } else if (data && typeof data === "object") {
+            rawList = Object.keys(data)
+                .filter((key) => /list$/i.test(key) && Array.isArray(data[key]))
+                .flatMap((key) =>
+                    data[key].map((item) => ({
+                        ...item,
+                        __group: key
+                    }))
+                );
+        }
+        if (!isMcp) {
+            console.log(JSON.stringify(rawList));
+        }
+        return rawList;
+    }
+
+    const msg = res && (res.returnInfo || res.message) ? (res.returnInfo || res.message) : "Unknown error";
+    throw new Error("Get Role Failed: " + msg);
+}
+
+module.exports = get;

package/src/role/index.js

@@ -0,0 +1,10 @@
+const cc = {}
+cc.create = require("./create")
+cc.delete = require("./delete")
+cc.get = require("./get")
+cc.doc = require("./doc")
+function main(action, argvs) {
+  cc[action](argvs)
+}
+
+module.exports = main;

package/src/scheduleJob/doc.js

@@ -0,0 +1,49 @@
+const fs = require("fs");
+const path = require("path");
+
+const DOCS_DIR = path.join(__dirname, "docs");
+const INTRODUCTION = path.join(DOCS_DIR, "introduction.md");
+const DEVGUIDE = path.join(DOCS_DIR, "devguide.md");
+
+function readDocOrFallback(filePath, fallback) {
+    try {
+        return fs.readFileSync(filePath, "utf8").trim();
+    } catch (e) {
+        return fallback;
+    }
+}
+
+function getIntroductionDoc() {
+    return readDocOrFallback(
+        INTRODUCTION,
+        `# CloudCC 定时作业（scheduleJob）介绍\n\n（未找到文件：${INTRODUCTION}）\n`
+    );
+}
+
+function getDevGuideDoc() {
+    return readDocOrFallback(
+        DEVGUIDE,
+        `# CloudCC 定时作业（scheduleJob）开发指南\n\n（未找到文件：${DEVGUIDE}）\n`
+    );
+}
+
+/**
+ * cc doc scheduleJob <introduction|devguide>
+ * @param {string[]} argvs [doc, type, introduction|devguide, ...]
+ */
+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/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/index.js

@@ -2,8 +2,13 @@ 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]);
 }
 

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;
+