cloudcc-cli 2.3.1 → 2.3.3

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/index.js

@@ -2,6 +2,7 @@ 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/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;

package/src/object/docs/devguide.md

@@ -0,0 +1,112 @@
+# CloudCC 自定义对象开发指南
+
+## 1. 模块定位
+
+`object` 模块用于管理 CloudCC 自定义对象，当前提供查询、创建、删除三类能力。
+
+可通过以下命令读取文档：
+
+```bash
+cc doc object introduction
+cc doc object devguide
+```
+
+---
+
+## 2. 当前支持的命令
+
+```bash
+cc get object <projectPath> [type]
+cc create object <projectPath> <label> [nameLabel]
+cc delete object <projectPath> <objid>
+```
+
+说明：
+
+- `projectPath`：本地项目路径，用于读取 `cloudcc-cli.config.js`
+- `label`：对象中文名称或展示名称
+- `nameLabel`：对象 API 名称；不传时会基于 `label` 自动生成
+- `objid`：对象 ID
+
+---
+
+## 3. 查询对象
+
+### 3.1 查询全部对象
+
+```bash
+cc get object <projectPath>
+```
+
+返回标准对象和自定义对象的合并列表。
+
+### 3.2 按类型查询
+
+```bash
+cc get object <projectPath> standard
+cc get object <projectPath> custom
+```
+
+常见含义：
+
+- `standard`：标准对象
+- `custom`：自定义对象
+
+---
+
+## 4. 创建对象
+
+### 4.1 基本命令
+
+```bash
+cc create object <projectPath> <label> [nameLabel]
+```
+
+规则：
+
+- 若传入 `nameLabel`，则使用传入值作为对象 API 名称
+- 若未传入 `nameLabel`，CLI 会根据 `label` 自动生成一个英文可用的 slug，并拼成对象 API 名称
+
+### 4.2 创建过程
+
+创建对象时，模块会：
+
+1. 读取项目配置
+2. 查询角色列表
+3. 自动生成对象权限配置
+4. 调用 `/api/customObject/saveButton` 创建对象
+
+---
+
+## 5. 删除对象
+
+### 5.1 基本命令
+
+```bash
+cc delete object <projectPath> <objid>
+```
+
+删除前建议：
+
+- 先确认对象未被页面、菜单、字段或自动化逻辑依赖
+- 先保留对象 ID 与对象名称，避免误删
+
+---
+
+## 6. 开发前检查
+
+- 已完成 `cc doc project devguide` 中的环境准备
+- 项目根目录存在可用的 `cloudcc-cli.config.js`
+- 当前环境密钥配置正确
+- 已确认对象名称、API 名称、角色权限需求
+
+---
+
+## 7. 占位说明
+
+这份文档当前为初版开发指南，后续可继续补充：
+
+- 对象建模规范
+- 命名建议
+- 角色权限说明
+- 与字段、菜单、应用的联动关系

package/src/object/docs/introduction.md

@@ -0,0 +1,187 @@
+# CloudCC 自定义对象介绍
+
+## 1. 什么是自定义对象
+
+自定义对象是 CloudCC 平台中承载业务数据的核心建模能力。
+
+当标准对象无法满足业务需求时，可以通过自定义对象定义一类新的业务实体，用来存储、组织和管理企业自己的业务数据。
+
+可以把它理解为：
+
+- 一个新的业务数据模型
+- 一张由平台托管的业务数据表
+- 后续字段、页面、菜单、权限、自动化逻辑的基础载体
+
+---
+
+## 2. 自定义对象能做什么
+
+创建一个自定义对象后，通常可以围绕它继续完成以下工作：
+
+- 为对象添加字段，定义业务属性
+- 为对象配置页面、菜单和应用入口
+- 为对象编写触发器、后端类、客户端脚本等逻辑
+- 作为报表、列表、详情页、审批流或自动化规则的数据基础
+- 与其他对象建立关联关系，形成完整的业务模型
+
+也就是说，自定义对象不是孤立存在的，它往往是整个 CloudCC 二次开发的起点。
+
+---
+
+## 3. 主要作用是什么
+
+自定义对象的主要作用是把企业自己的业务概念，沉淀成平台可以管理和扩展的数据实体。
+
+例如，企业可能会有一些 CloudCC 标准对象中没有的业务概念：
+
+- 渠道合作商
+- 培训计划
+- 项目立项单
+- 售后服务工单
+- 设备巡检记录
+- 合同回款计划
+
+这些内容如果没有独立的数据对象，就很难被规范地管理、查询、统计和扩展。
+
+通过自定义对象，可以把这些业务概念平台化，后续再叠加字段、权限、页面和自动化逻辑，实现完整的业务支撑。
+
+---
+
+## 4. 为什么要用自定义对象
+
+使用自定义对象，通常是为了解决以下问题：
+
+### 4.1 标准对象不够用
+
+标准 CRM 对象更适合通用销售、客户、商机等场景。  
+如果你的业务有明显的行业特性或内部流程特性，就需要自定义对象来承载这些专属数据。
+
+### 4.2 业务数据没有统一模型
+
+很多团队一开始会把业务数据分散在备注、Excel、附件或多个对象的扩展字段里。  
+这样会导致：
+
+- 数据结构混乱
+- 难查询、难统计
+- 权限和流程不好控制
+- 后续开发成本越来越高
+
+自定义对象可以帮助团队建立统一的数据模型。
+
+### 4.3 后续扩展困难
+
+如果没有对象作为基础，就很难继续配置：
+
+- 字段
+- 页面
+- 菜单
+- 审批
+- 触发器
+- 自动化逻辑
+- 报表与统计
+
+自定义对象本质上是在为后续的二次开发打地基。
+
+---
+
+## 5. 能解决哪些问题
+
+自定义对象通常可以解决以下几类问题：
+
+- 业务实体无法落地存储的问题
+- 非标准流程缺少独立数据载体的问题
+- 数据分散、命名混乱、难以统一管理的问题
+- 无法围绕某类业务数据做页面、权限、流程和自动化的问题
+- 无法对特定业务做统计分析和生命周期管理的问题
+
+---
+
+## 6. 在什么情况下使用
+
+当出现以下情况时，通常就应该考虑使用自定义对象：
+
+- 现有标准对象找不到合适的数据承载位置
+- 一类业务数据有明确的独立含义，需要单独维护
+- 需要给这类数据配置独立字段、列表、详情页或菜单入口
+- 需要围绕这类数据编写触发器、后端逻辑或客户端脚本
+- 需要对这类数据做独立的权限控制、流程控制或报表统计
+
+简单说，只要某类业务数据需要被“长期、规范、可扩展”地管理，就适合建成一个自定义对象。
+
+---
+
+## 7. 常见业务场景
+
+### 7.1 行业化业务扩展
+
+例如教育、制造、医疗、服务型企业，往往会有标准 CRM 没有的业务实体：
+
+- 课程班级
+- 设备档案
+- 巡检计划
+- 维修工单
+- 服务回访单
+
+这类场景通常适合通过自定义对象建模。
+
+### 7.2 内部流程数字化
+
+如果企业希望把线下或半线下流程搬到 CloudCC 中管理，例如：
+
+- 项目申请
+- 费用登记
+- 合同变更申请
+- 客诉处理
+- 交付验收记录
+
+这类流程通常都需要一个独立对象来沉淀流程数据。
+
+### 7.3 围绕客户或商机的扩展管理
+
+有些数据虽然与客户或商机有关，但不适合直接塞到标准对象里，例如：
+
+- 客户拜访记录
+- 渠道返佣记录
+- 实施里程碑
+- 回款计划
+
+这类场景可以用自定义对象做扩展，再通过关联字段与客户、商机连接起来。
+
+### 7.4 需要长期运营的数据台账
+
+比如：
+
+- 资产台账
+- 证照台账
+- 项目档案
+- 服务记录
+
+这类数据通常结构稳定、需要长期维护，很适合对象化管理。
+
+---
+
+## 8. 使用自定义对象时的理解方式
+
+在设计时，可以先问自己几个问题：
+
+1. 这是不是一类独立的业务实体？
+2. 这类数据是否需要独立字段和独立页面？
+3. 是否需要围绕它做权限、流程、自动化或报表？
+4. 这类数据未来会不会持续扩展？
+
+如果这几个问题大多回答为“是”，通常就说明应该考虑新建一个自定义对象。
+
+---
+
+## 9. 与其他模块的关系
+
+自定义对象通常和这些模块联动：
+
+- `fields`：给对象增加字段
+- `menu`：给对象增加菜单入口
+- `application`：把对象放入应用
+- `triggers`：围绕对象数据变化编写触发逻辑
+- `classes`：围绕对象编写业务服务逻辑
+- `script` / `plugin` / `customPage`：围绕对象做页面交互与前端扩展
+
+因此，自定义对象往往是 CloudCC 二次开发中最基础、最上游的建模模块之一。

package/src/object/get.js

@@ -7,29 +7,7 @@ async function get(argvs, isMcp = false) {
     let object = argvs[4]
     let res = [];
     let config = await getPackageJson(path);
-    if ("fields" === type) {
-        object = JSON.parse(decodeURI(object))
-        let fieldsResults = await postClass(config.setupSvc + "/api/fieldSetup/queryField", { prefix: object.objprefix }, config.accessToken)
-        res = {
-            ...object,
-            stdFields: fieldsResults.data.stdFields.map((field) => {
-                return {
-                    fieldname: field.labelName,
-                    apiname: field.schemefieldName,
-                    schemefieldType: field.schemefieldType,
-                    id: field.id
-                }
-            }),
-            cusFields: fieldsResults.data.cusFields.map((field) => {
-                return {
-                    fieldname: field.labelName,
-                    apiname: field.schemefieldName,
-                    schemefieldType: field.schemefieldType,
-                    id: field.id
-                }
-            })
-        }
-    } else if ("chat" === type) {
+    if ("chat" === type) {
         //get chat object
         let standardObjList = await postClass(config.setupSvc + "/api/customObject/standardObjList", {}, config.accessToken);
         standardObjList.data.map((item) => {

package/src/object/index.js

@@ -2,6 +2,7 @@ const cc = {}
 cc.get = require("./get")
 cc.create = require("./create")
 cc.delete = require("./delete")
+cc.doc = require("./doc")
 function main(action, argvs) {
   cc[action](argvs)
 }

package/src/pagelayout/create.js

@@ -0,0 +1,123 @@
+const { postClass } = require("../../utils/http");
+const { getPackageJson } = require("../../utils/config");
+const chalk = require("chalk");
+
+/**
+ * 获取对象现有的页面布局列表
+ * @param {Object} config - 项目配置
+ * @param {string} objId - 对象 ID
+ * @returns {Promise<Array>} 页面布局列表
+ */
+async function getExistingLayouts(config, objId) {
+    try {
+        const res = await postClass(
+            config.setupSvc + "/api/layout/newpage",
+            { objid: objId },
+            config.accessToken
+        );
+
+        if (res && res.result && res.data && Array.isArray(res.data) && res.data.length > 0) {
+            return res.data;
+        }
+
+        throw new Error("未找到可用的页面布局");
+    } catch (error) {
+        throw new Error("获取页面布局列表失败: " + error.message);
+    }
+}
+
+/**
+ * 复制创建页面布局
+ * @param {Object} config - 项目配置
+ * @param {string} objId - 对象 ID
+ * @param {string} layoutName - 新布局名称
+ * @param {string} sourceLayoutId - 源布局 ID
+ * @param {string} isCloneDynamic - 是否复制动态布局规则
+ * @returns {Promise<Object>} 创建结果
+ */
+async function cloneLayout(config, objId, layoutName, sourceLayoutId, isCloneDynamic = "true") {
+    const res = await postClass(
+        config.setupSvc + "/api/layout/cloneLayout",
+        {
+            layoutId: sourceLayoutId,
+            layoutName: layoutName,
+            objid: objId,
+            isCloneDynamic: isCloneDynamic
+        },
+        config.accessToken
+    );
+
+    if (res && res.result) {
+        return res.data || res;
+    }
+
+    const msg = res && (res.returnInfo || res.message) ? (res.returnInfo || res.message) : "Unknown error";
+    throw new Error("Clone Layout Failed: " + msg);
+}
+
+/**
+ * 创建页面布局
+ * 用法：cc create pagelayout <projectPath> <objId> <layoutName> [sourceLayoutId] [isCloneDynamic]
+ * @param {Array} argvs - 命令行参数数组
+ * @returns {Promise<Object>} 创建结果
+ */
+async function create(argvs) {
+    try {
+        // 命令行参数格式：cc create pagelayout <projectPath> <objId> <layoutName> [sourceLayoutId] [isCloneDynamic]
+        const projectPath = argvs[2] || process.cwd();
+        const objId = argvs[3];
+        const layoutName = argvs[4];
+        const sourceLayoutId = argvs[5];
+        const isCloneDynamic = argvs[6] || "true";
+
+        if (!objId) {
+            console.error();
+            console.error(chalk.red("Error: 缺少对象 ID"));
+            console.error("用法: cc create pagelayout <projectPath> <objId> <layoutName> [sourceLayoutId] [isCloneDynamic]");
+            console.error("示例:");
+            console.error('  cc create pagelayout . 20267D1465464C5OB6m5 "课程表2"');
+            console.error("  cc create pagelayout . 20267D1465464C5OB6m5 \"课程表2\" add20261DA7347CZPAUz");
+            console.error();
+            throw new Error("缺少必需参数: objId");
+        }
+
+        if (!layoutName) {
+            console.error();
+            console.error(chalk.red("Error: 缺少页面布局名称"));
+            console.error("用法: cc create pagelayout <projectPath> <objId> <layoutName> [sourceLayoutId] [isCloneDynamic]");
+            console.error();
+            throw new Error("缺少必需参数: layoutName");
+        }
+
+        const config = await getPackageJson(projectPath);
+
+        let targetLayoutId = sourceLayoutId;
+
+        // 如果没有指定源布局 ID，查询现有布局列表并选择第一个
+        if (!targetLayoutId) {
+            console.error();
+            console.error(chalk.blue("正在获取现有页面布局列表..."));
+            const layouts = await getExistingLayouts(config, objId);
+            targetLayoutId = layouts[0].id;
+            console.error(chalk.green(`将使用布局 "${layouts[0].layoutName}" (${targetLayoutId}) 作为复制源`));
+        }
+
+        console.error();
+        console.error(chalk.green(`Creating page layout "${layoutName}"...`));
+        console.error();
+
+        const result = await cloneLayout(config, objId, layoutName, targetLayoutId, isCloneDynamic);
+
+        console.error(chalk.green("页面布局创建成功！"));
+        console.log(JSON.stringify(result));
+
+        return result;
+
+    } catch (error) {
+        console.error();
+        console.error(chalk.red("页面布局创建失败:"), error.message || error);
+        throw error;
+    }
+}
+
+module.exports = create;