cloudcc-cli 2.3.0 → 2.3.2

package/src/menu/delete.js

@@ -0,0 +1,59 @@
+const chalk = require("chalk");
+const { postClass } = require("../../utils/http");
+const { getPackageJson } = require("../../utils/config");
+
+/**
+ * 删除自定义菜单（标签页）
+ * 用法：cc delete menu <projectPath> <tabId>
+ */
+async function remove(argvs) {
+    try {
+        const projectPath = argvs[2] || process.cwd();
+        const tabId = argvs[3];
+
+        if (!tabId) {
+            console.error();
+            console.error(chalk.red("Error: 缺少菜单 ID"));
+            console.error(chalk.yellow("用法: cc delete menu <projectPath> <tabId>"));
+            console.error();
+            throw new Error("缺少必需参数: tabId");
+        }
+
+        const config = await getPackageJson(projectPath);
+        if (!config || !config.accessToken) {
+            console.error();
+            console.error(chalk.red("Error: 配置未找到或 accessToken 缺失"));
+            console.error();
+            throw new Error("配置未找到或 accessToken 缺失");
+        }
+
+        console.error();
+        console.error(chalk.green(`Deleting menu (${tabId}), please wait...`));
+        console.error();
+
+        const result = await postClass(
+            config.setupSvc + "/api/customTab/deleteTab",
+            { id: tabId },
+            config.accessToken
+        );
+
+        if (result && result.result) {
+            console.error();
+            console.error(chalk.green("Success! Menu deleted."));
+            console.error();
+            return result;
+        }
+
+        const msg = result && (result.returnInfo || result.message) ? (result.returnInfo || result.message) : "Unknown error";
+        console.error();
+        console.error(chalk.red("Error: " + msg));
+        console.error();
+        throw new Error("Delete Menu Failed: " + msg);
+    } catch (error) {
+        console.error();
+        console.error(chalk.red("菜单删除失败:"), error);
+        throw error;
+    }
+}
+
+module.exports = remove;

package/src/menu/doc.js

@@ -0,0 +1,57 @@
+/**
+ * menu 文档入口：正文均在 `docs/` 目录。
+ */
+const fs = require("fs");
+const path = require("path");
+
+const DOCS_DIR = path.join(__dirname, "docs");
+const CCDK_SDK = path.join(__dirname, "..", "api", "ccdk-sdk.md");
+
+function readDocFile(basename) {
+    return fs.readFileSync(path.join(DOCS_DIR, `${basename}.md`), "utf8");
+}
+
+/** 介绍文档：菜单能力、类型与入口 */
+function getIntroductionDoc() {
+    return readDocFile("introduction");
+}
+
+/** 开发指导：CLI 创建/查询/删除等；末尾拼接 CCDK SDK 速查 */
+function getDevGuideDoc() {
+    const base = readDocFile("devguide").trimEnd();
+    let sdk = "";
+    try {
+        sdk = fs.readFileSync(CCDK_SDK, "utf8").trim();
+    } catch (e) {
+        sdk = "";
+    }
+    if (!sdk) {
+        return base;
+    }
+    return [base, "", "---", "", "## 附录：CCDK SDK 速查", "", sdk, ""].join("\n");
+}
+
+/**
+ * cc doc menu <introduction|devguide>
+ * @param {string[]} argvs [doc, type, introduction|devguide, ...]
+ */
+function doc(argvs) {
+    const subType = argvs[2];
+    const key = String(subType || "").trim().toLowerCase();
+    if (!key) {
+        throw new Error("cc doc menu 需要子命令：introduction 或 devguide");
+    }
+    if (key === "introduction") {
+        const content = getIntroductionDoc();
+        console.log(content);
+        return content;
+    }
+    if (key === "devguide") {
+        const content = getDevGuideDoc();
+        console.log(content);
+        return content;
+    }
+    throw new Error(`doc 不支持的子命令: ${subType}，请使用 introduction 或 devguide`);
+}
+
+module.exports = doc;

package/src/menu/docs/devguide.md

@@ -0,0 +1,203 @@
+# CloudCC 菜单开发指南
+
+## 1. 模块定位
+
+`menu` 模块用于创建、查询、删除 CloudCC 菜单（标签页）。  
+菜单是对象、页面、脚本能力的可视化入口，也是应用导航的重要组成部分。
+
+可通过以下命令查看文档：
+
+```bash
+cc doc menu introduction
+cc doc menu devguide
+```
+
+---
+
+## 2. 开发前准备
+
+执行菜单相关命令前，请确认：
+
+- 已完成 `cc doc project devguide` 的环境初始化
+- 项目根目录存在可用的 `cloudcc-cli.config.js`
+- 当前环境连接可用（org / token / endpoint 正确）
+- 已明确菜单所属资源（对象 ID、页面 API、脚本内容或站点 ID）
+
+---
+
+## 3. 支持的命令总览
+
+```bash
+cc create menu object <path> <objectId> <tabName> [tabStyle] [mobileimg] [cloudccservicetab]
+cc create menu page <path> <pageApi> <tabName> <pname> [tabStyle] [mobileimg] [cloudccservicetab] [mobileurl]
+cc create menu script <path> <tabName> <pname> [functioncode] [tabStyle] [mobileimg] [cloudccservicetab]
+cc create menu site <path> <siteId> <tabName> [tabStyle] [mobileimg] [cloudccservicetab]
+
+cc get menu <projectPath> [encodedCondJson]
+cc delete menu <projectPath> <tabId>
+```
+
+---
+
+## 4. 创建菜单
+
+### 4.1 创建自定义对象菜单
+
+```bash
+cc create menu object <path> <objectId> <tabName> [tabStyle] [mobileimg] [cloudccservicetab]
+```
+
+参数说明：
+
+- `path`：项目路径，`.` 表示当前目录
+- `objectId`：自定义对象 ID
+- `tabName`：菜单显示名称
+- `tabStyle`：PC 端图标（可选，默认 `cloudtab145`）
+- `mobileimg`：移动端图标（可选，默认 `cloudcc01`）
+- `cloudccservicetab`：服务图标（可选，默认 `cloudccservicetab_1`）
+
+示例：
+
+```bash
+cc create menu object . a0F9D000000XXXXUAI "客户管理"
+```
+
+### 4.2 创建自定义页面菜单
+
+```bash
+cc create menu page <path> <pageApi> <tabName> <pname> [tabStyle] [mobileimg] [cloudccservicetab] [mobileurl]
+```
+
+参数说明：
+
+- `path`：项目路径
+- `pageApi`：自定义页面 API 名称（CLI 会追加 `#lightning`）
+- `tabName`：菜单显示名称
+- `pname`：菜单内部名称（建议字母开头，字母/数字/下划线）
+- `tabStyle` / `mobileimg` / `cloudccservicetab`：图标参数（可选）
+- `mobileurl`：移动端地址（可选）
+
+示例：
+
+```bash
+cc create menu page . contract-assistant "合同助手" contract_menu
+```
+
+### 4.3 创建自定义脚本菜单
+
+```bash
+cc create menu script <path> <tabName> <pname> [functioncode] [tabStyle] [mobileimg] [cloudccservicetab]
+```
+
+参数说明：
+
+- `path`：项目路径
+- `tabName`：菜单显示名称
+- `pname`：菜单内部名称
+- `functioncode`：脚本内容（可选，默认示例脚本）
+- `tabStyle` / `mobileimg` / `cloudccservicetab`：图标参数（可选）
+
+示例：
+
+```bash
+cc create menu script . "数据导入工具" data_import_menu "ccc.alert('Hello World');"
+```
+
+### 4.4 创建站点菜单
+
+```bash
+cc create menu site <path> <siteId> <tabName> [tabStyle] [mobileimg] [cloudccservicetab]
+```
+
+参数说明：
+
+- `path`：项目路径
+- `siteId`：站点 ID
+- `tabName`：菜单显示名称
+- `tabStyle` / `mobileimg` / `cloudccservicetab`：图标参数（可选）
+
+示例：
+
+```bash
+cc create menu site . a0H9D000000XXXXUAI "合作伙伴门户"
+```
+
+---
+
+## 5. 查询与删除
+
+### 5.1 查询菜单
+
+```bash
+cc get menu <projectPath> [encodedCondJson]
+```
+
+说明：
+
+- `projectPath` 默认当前目录
+- `encodedCondJson` 为 URI 编码后的 JSON 查询条件
+
+示例：
+
+```bash
+cc get menu .
+cc get menu . '%7B%22type%22%3A%22page%22%7D'
+```
+
+### 5.2 删除菜单
+
+```bash
+cc delete menu <projectPath> <tabId>
+```
+
+说明：
+
+- `tabId` 为菜单 ID，建议先执行 `cc get menu .` 再删除
+
+示例：
+
+```bash
+cc delete menu . a0I9D000000XXXXUAI
+```
+
+---
+
+## 6. 与后台菜单配置流程的映射
+
+根据 CloudCC 官方菜单流程，完整上线通常包含三层动作：
+
+1. 新建菜单（对象 / 页面 / 脚本）
+2. 添加到简档（控制可见角色）
+3. 添加到应用程序（控制出现在什么应用）
+
+`cloudcc-cli` 当前主要覆盖第 1 步（菜单实体创建）。  
+因此在 CLI 创建后，建议在后台继续核验第 2-3 步，确保用户可见且出现在目标应用导航中。
+
+---
+
+## 7. 常见注意事项
+
+- 菜单创建成功不等于用户可见，需检查简档权限
+- 菜单创建成功不等于出现在预期应用，需检查应用挂载
+- `page` 类型请确认页面 API 存在且可访问
+- 删除菜单前确认未被培训文档、操作手册或用户流程依赖
+- 建议先在测试环境验证，再在生产环境执行
+
+---
+
+## 8. 推荐操作顺序
+
+```bash
+# 1) 查询现有菜单，避免重名
+cc get menu .
+
+# 2) 创建目标菜单（示例：页面菜单）
+cc create menu page . contract-manage "合同管理" contract_menu
+
+# 3) 再次查询确认已创建
+cc get menu .
+```
+
+创建后请在 CloudCC 后台完成简档与应用核验。
+
+---

package/src/menu/docs/introduction.md

@@ -0,0 +1,99 @@
+# CloudCC 菜单模块介绍
+
+## 1. 模块定位
+
+`menu` 模块用于在 CloudCC
+中创建和管理导航菜单（标签页），把对象、页面或脚本能力暴露给业务用户。
+
+在 CloudCC
+中，菜单是用户看到系统功能的主要入口。对象、页面、脚本等能力通常需要通过菜单挂载到应用中，才方便被终端用户访问。
+
+---
+
+## 2. 菜单能做什么
+
+通过菜单模块，你可以：
+
+- 为自定义对象创建入口
+- 为自定义页面创建入口
+- 为自定义脚本创建入口
+- 将入口加入应用导航
+- 配置 PC 与移动端图标，统一产品体验
+
+---
+
+## 3. 支持的菜单类型
+
+| 类型     | 说明           | 常见用途                  |
+| -------- | -------------- | ------------------------- |
+| `object` | 自定义对象菜单 | 打开对象列表/详情能力     |
+| `page`   | 自定义页面菜单 | 打开 Lightning 自定义页面 |
+| `script` | 自定义脚本菜单 | 点击后执行脚本逻辑        |
+| `site`   | 站点菜单       | 关联 Site.com 站点        |
+
+---
+
+## 4. 菜单在平台中的典型流程
+
+参考 CloudCC 官方「菜单」能力，创建菜单通常包含以下流程：
+
+1. 进入后台设置，打开菜单管理
+2. 新建菜单（对象菜单 / 页面菜单 / 脚本菜单）
+3. 配置菜单标签与图标
+4. 选择可见简档（决定谁能看到菜单）
+5. 选择要加入的应用程序（决定菜单出现在哪个应用）
+6. 保存并验证显示效果
+
+在 `cloudcc-cli` 中，你主要通过 `cc create menu ...` 完成第 2-3
+步；权限与应用归属建议在创建后补充核验。
+
+---
+
+## 5. 为什么要用菜单模块
+
+菜单模块解决的是“能力可访问性”问题：
+
+- 只创建对象/页面，不创建菜单，用户通常无法在导航中直接发现该能力
+- 通过菜单可将功能按业务场景组织到不同应用
+- 结合简档权限，可对不同角色展示不同入口
+
+---
+
+## 6. 适用场景
+
+以下场景建议使用 `menu` 模块：
+
+- 新建了自定义对象，需要给业务团队增加入口
+- 开发了 Lightning 自定义页面，需要挂到导航栏
+- 需要提供一个一键执行脚本的菜单入口
+- 不同业务线需要在各自应用里看到不同菜单组合
+
+---
+
+## 7. 与其他模块的关系
+
+`menu` 常与以下模块协同：
+
+- `object`：菜单绑定对象能力
+- `customPage`：菜单绑定页面能力
+- `script`：菜单绑定脚本能力
+- `application`：菜单最终出现在具体应用中
+- `project`：提供连接配置与环境能力
+
+---
+
+## 8. 建议实践
+
+- 菜单命名与对象/页面语义保持一致，降低学习成本
+- 先在测试环境完成创建与权限验证，再推向生产
+- 统一图标规范，避免同一应用内视觉风格不一致
+- 创建后立即验证简档可见性与应用挂载是否正确
+
+---
+
+## 9. 相关文档与命令
+
+```bash
+cc doc menu introduction
+cc doc menu devguide
+```

package/src/menu/get.js

@@ -0,0 +1,56 @@
+const { postClass } = require("../../utils/http");
+const { getPackageJson } = require("../../utils/config");
+
+/**
+ * 查询自定义菜单（标签页）列表
+ * 用法：cc get menu <projectPath> [encodedCondJson]
+ */
+async function get(argvs, isMcp = false) {
+    const projectPath = argvs[2] || process.cwd();
+    const condArg = argvs[3];
+
+    let body = {};
+    if (condArg) {
+        try {
+            body = JSON.parse(decodeURI(condArg));
+        } catch (e) {
+            throw new Error("Get Menu Failed: encodedCondJson 解析失败，请传 encodeURI(JSON.stringify(...))");
+        }
+    }
+
+    const config = await getPackageJson(projectPath);
+    const res = await postClass(
+        config.setupSvc + "/api/customTab/queryTabList",
+        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") {
+            // 兼容 queryTabList 返回的分组结构：botlist/objectlist/objlist/pagelist/scriptlist...
+            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 Menu Failed: " + msg);
+}
+
+module.exports = get;

package/src/menu/index.js

@@ -1,5 +1,8 @@
 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)
 }

package/src/menu/validator.js

@@ -0,0 +1,80 @@
+const chalk = require('chalk');
+const menuGet = require('./get');
+
+/**
+ * 验证 pname 是否有效
+ * 规则：
+ * 1. 只能包含字母、数字、下划线
+ * 2. 开头必须是字母
+ * 3. 不能有中文
+ * 4. 必须唯一（查询现有菜单列表）
+ *
+ * @param {string} pname - 要验证的菜单名称
+ * @param {string} projectPath - 项目路径
+ * @param {string} currentType - 当前菜单类型 (script/page/object/site)
+ * @returns {Promise<{valid: boolean, message?: string}>}
+ */
+async function validatePname(pname, projectPath, currentType) {
+    // 1. 检查是否为空
+    if (!pname || typeof pname !== 'string') {
+        return { valid: false, message: 'pname 不能为空' };
+    }
+
+    // 2. 检查长度
+    if (pname.length < 1 || pname.length > 50) {
+        return { valid: false, message: 'pname 长度必须在 1-50 个字符之间' };
+    }
+
+    // 3. 检查是否有中文
+    if (/[\u4e00-\u9fa5]/.test(pname)) {
+        return { valid: false, message: 'pname 不能包含中文字符' };
+    }
+
+    // 4. 检查开头必须是字母
+    if (!/^[a-zA-Z]/.test(pname)) {
+        return { valid: false, message: 'pname 必须以字母开头' };
+    }
+
+    // 5. 检查只能包含字母、数字、下划线
+    if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(pname)) {
+        return { valid: false, message: 'pname 只能包含字母、数字和下划线' };
+    }
+
+    // 6. 检查唯一性
+    try {
+        const argvs = ['', '', projectPath];
+        const existingMenus = await menuGet(argvs, true);
+
+        if (Array.isArray(existingMenus)) {
+            const duplicate = existingMenus.find(menu =>
+                menu.pname === pname && menu.type !== currentType
+            );
+            if (duplicate) {
+                return { valid: false, message: `pname "${pname}" 已被其他菜单使用` };
+            }
+        }
+    } catch (error) {
+        // 如果查询失败，记录警告但不阻止创建
+        console.error(chalk.yellow(`警告: 无法验证 pname 唯一性: ${error.message}`));
+    }
+
+    return { valid: true };
+}
+
+/**
+ * 格式化 pname（将不合法字符替换为下划线）
+ * @param {string} input - 输入字符串
+ * @returns {string} - 格式化后的字符串
+ */
+function formatPname(input) {
+    if (!input || typeof input !== 'string') {
+        return '';
+    }
+    // 将非字母数字下划线字符替换为下划线
+    return input.replace(/[^0-9a-zA-Z_]/g, '_');
+}
+
+module.exports = {
+    validatePname,
+    formatPname
+};

package/src/object/delete.js

@@ -0,0 +1,51 @@
+const chalk = require("chalk");
+const { postClass } = require("../../utils/http");
+const { getPackageJson } = require("../../utils/config");
+
+/**
+ * 删除自定义对象
+ * 用法：cc delete object <projectPath> <objid>
+ */
+async function remove(argvs) {
+    const projectPath = argvs[2] || process.cwd();
+    const objid = argvs[3];
+
+    if (!objid) {
+        console.error();
+        console.error(chalk.red("Error: objid is required"));
+        console.error(chalk.yellow("Usage: cc delete object <projectPath> <objid>"));
+        console.error();
+        return;
+    }
+
+    const config = await getPackageJson(projectPath);
+    if (!config || !config.accessToken) {
+        console.error();
+        console.error(chalk.red("Error: Configuration not found or accessToken is missing"));
+        console.error();
+        return;
+    }
+
+    console.error();
+    console.error(chalk.green(`Deleting custom object (${objid}), please wait...`));
+    console.error();
+
+    const res = await postClass(
+        config.setupSvc + "/api/customObject/deleteLogic",
+        { objid },
+        config.accessToken
+    );
+
+    if (res && res.result) {
+        console.error(chalk.green("Success! Custom object deleted."));
+        console.error();
+        return res;
+    }
+
+    const errMsg = res && (res.returnInfo || res.message) ? (res.returnInfo || res.message) : "Unknown error";
+    console.error(chalk.red(`Fail: ${errMsg}`));
+    console.error();
+    throw new Error("Delete Custom Object Failed: " + errMsg);
+}
+
+module.exports = remove;

package/src/object/doc.js

@@ -0,0 +1,45 @@
+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 自定义对象介绍\n\n（未找到文件：${INTRODUCTION}）\n`
+    );
+}
+
+function getDevGuideDoc() {
+    return readDocOrFallback(
+        DEVGUIDE,
+        `# CloudCC 自定义对象开发指南\n\n（未找到文件：${DEVGUIDE}）\n`
+    );
+}
+
+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;