cloudcc-cli 2.3.1 → 2.3.2

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.layouts && Array.isArray(res.layouts) && res.layouts.length > 0) {
+            return res.layouts;
+        }
+
+        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;

package/src/pagelayout/doc.js

@@ -0,0 +1,46 @@
+/**
+ * pagelayout 文档入口：正文均在 `docs/` 目录。
+ */
+const fs = require("fs");
+const path = require("path");
+
+const DOCS_DIR = path.join(__dirname, "docs");
+
+function readDocFile(basename) {
+    return fs.readFileSync(path.join(DOCS_DIR, `${basename}.md`), "utf8");
+}
+
+/** 介绍文档：页面布局能力、类型与入口 */
+function getIntroductionDoc() {
+    return readDocFile("introduction");
+}
+
+/** 开发指导：CLI 查询/创建等 */
+function getDevGuideDoc() {
+    return readDocFile("devguide");
+}
+
+/**
+ * cc doc pagelayout <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 pagelayout 需要子命令：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/pagelayout/docs/devguide.md

@@ -0,0 +1,295 @@
+# CloudCC 页面布局使用总结
+
+页面布局（Page Layout）用于定义对象在详情页的字段展示方式，包括字段排列、分区、按钮位置等。
+
+**前置条件**：页面布局操作需要先选中自定义对象或标准对象。
+
+---
+
+## 快速开始（CLI 命令）
+
+### 支持的页面布局操作
+
+| 操作 | 说明 |
+|------|------|
+| `get` | 查询页面布局列表 |
+| `create` | 创建/复制页面布局 |
+
+---
+
+## CLI 命令详解
+
+### 查询页面布局列表
+
+获取指定对象的页面布局列表。
+
+```bash
+cc get pagelayout <projectPath> <objApiName>
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，`.` 表示当前目录 |
+| `objApiName` | 是 | 对象 API 名称（前缀） |
+
+**示例：**
+
+```bash
+# 查询对象 b25 的页面布局列表
+cc get pagelayout . b25
+
+# 使用完整 API 名称
+cc get pagelayout . Account
+```
+
+---
+
+### 创建页面布局
+
+基于现有布局创建新的页面布局。
+
+```bash
+cc create pagelayout <projectPath> <objId> <layoutName> [sourceLayoutId] [isCloneDynamic]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，`.` 表示当前目录 |
+| `objId` | 是 | 对象 ID |
+| `layoutName` | 是 | 新页面布局名称 |
+| `sourceLayoutId` | 否 | 要复制的源布局 ID，不传则使用默认第一个 |
+| `isCloneDynamic` | 否 | 是否复制动态布局规则，默认 `true` |
+
+**示例：**
+
+```bash
+# 创建页面布局（自动使用默认布局作为模板）
+cc create pagelayout . 20267D1465464C5OB6m5 "课程表2"
+
+# 指定源布局 ID 进行复制
+cc create pagelayout . 20267D1465464C5OB6m5 "课程表2" add20261DA7347CZPAUz
+
+# 不复制动态布局规则
+cc create pagelayout . 20267D1465464C5OB6m5 "课程表2" add20261DA7347CZPAUz false
+```
+
+---
+
+## 完整工作流示例
+
+### 场景：为自定义对象创建新的页面布局
+
+```bash
+# 1. 确认项目已初始化（有 cloudcc-cli.config.js）
+cat cloudcc-cli.config.js
+
+# 2. 查询对象的页面布局列表
+cc get pagelayout . b25
+
+# 3. 根据对象 ID 创建新布局
+cc create pagelayout . 20267D1465464C5OB6m5 "新的布局名称"
+
+# 4. 验证创建成功，再次查询列表
+cc get pagelayout . b25
+```
+
+---
+
+## API 接口详情
+
+### 什么是页面布局？
+
+**页面布局（Page Layout）** 定义了对象在详情页的展示方式，包括：
+- 字段的排列和分组
+- 相关列表的显示
+- 操作按钮的位置
+- 动态布局规则
+
+### 核心属性
+
+| 属性 | 说明 | 示例 |
+|------|------|------|
+| **ID（id）** | 页面布局唯一标识 | `add20261DA7347CZPAUz` |
+| **名称（layoutName）** | 页面布局显示名称 | `课程表布局` |
+| **对象 ID（objid）** | 关联的对象 ID | `20267D1465464C5OB6m5` |
+
+---
+
+## 一、查询页面布局列表
+
+### 1.1 接口说明
+
+**接口**: `POST /api/layout/queryPageLayout`
+
+**请求参数**：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `prefix` | string | 是 | 对象 API 名称前缀 |
+
+**返回数据**：
+
+```javascript
+{
+  "result": true,
+  "returnInfo": "操作成功",
+  "layouts": [
+    {
+      "id": "add20261DA7347CZPAUz",
+      "layoutName": "默认布局",
+      "objid": "20267D1465464C5OB6m5",
+      // ... 其他字段
+    }
+  ]
+}
+```
+
+**返回字段说明**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `layouts` | array | 页面布局数组 |
+| `layouts[].id` | string | 布局 ID |
+| `layouts[].layoutName` | string | 布局名称 |
+| `layouts[].objid` | string | 关联对象 ID |
+
+---
+
+## 二、创建页面布局
+
+创建页面布局是一个两步流程：
+
+1. **获取现有布局列表**：调用 `layout/newpage` 接口获取可用于复制的布局
+2. **复制创建新布局**：调用 `layout/cloneLayout` 接口基于选定布局创建新布局
+
+### 2.1 获取现有布局列表
+
+**接口**: `POST /api/layout/newpage`
+
+**请求参数**：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `objid` | string | 是 | 对象 ID |
+
+**返回数据**：
+
+```javascript
+{
+  "result": true,
+  "returnInfo": "操作成功",
+  "layouts": [
+    {
+      "id": "add20261DA7347CZPAUz",
+      "layoutName": "默认布局",
+      "objid": "20267D1465464C5OB6m5"
+    }
+  ]
+}
+```
+
+**默认布局选择逻辑**：
+
+- 返回列表中的第一个布局作为默认复制源
+
+### 2.2 复制创建新布局
+
+**接口**: `POST /api/layout/cloneLayout`
+
+**请求参数**：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `layoutId` | string | 是 | 要复制的源布局 ID |
+| `layoutName` | string | 是 | 新布局名称 |
+| `objid` | string | 是 | 对象 ID |
+| `isCloneDynamic` | string | 否 | 是否复制动态布局规则，默认 `"true"` |
+
+**请求示例**：
+
+```javascript
+{
+  "layoutId": "add20261DA7347CZPAUz",
+  "layoutName": "课程表2",
+  "objid": "20267D1465464C5OB6m5",
+  "isCloneDynamic": "true"
+}
+```
+
+**返回数据**：
+
+```javascript
+{
+  "result": true,
+  "returnInfo": "操作成功",
+  "data": {
+    "id": "add2026XXXXXXXXXXXXX",
+    "layoutName": "课程表2"
+  }
+}
+```
+
+---
+
+## 三、页面布局数据结构
+
+### 3.1 列表数据格式
+
+```javascript
+{
+  id: "add20261DA7347CZPAUz",
+  layoutName: "默认布局",
+  objid: "20267D1465464C5OB6m5"
+}
+```
+
+---
+
+## 四、最佳实践
+
+### 命名规范
+
+| 项目 | 规范 | 示例 |
+|------|------|------|
+| 布局名称 | 使用描述性名称 | `标准详情页布局`、`移动端布局` |
+| 复制源选择 | 选择结构最相近的布局作为复制源 | - |
+
+### 布局设计建议
+
+- **按需复制动态布局规则**：如果源布局有复杂的动态规则，确认是否需要复制到新布局
+- **避免重复创建**：创建前先查询现有布局，避免重复
+
+### 推荐操作流程
+
+1. 查看对象现有布局：`cc get pagelayout . <apiName>`
+2. 确定复制源布局 ID
+3. 创建新布局：`cc create pagelayout . <objId> <layoutName> [sourceLayoutId]`
+4. 验证创建结果
+
+---
+
+## 五、常见问题
+
+**Q: 为什么查询页面布局需要先选中对象？**
+
+A: 页面布局是绑定到具体对象的，不同对象有不同的字段和关联关系，因此必须先确定对象才能操作其页面布局。
+
+**Q: 如何获取对象 ID？**
+
+A: 可以通过对象 API 名称查询对象信息获取 ID，或从管理后台的对象管理页面获取。
+
+**Q: isCloneDynamic 参数的作用是什么？**
+
+A: 该参数控制是否复制源布局的动态布局规则。设置为 `"true"` 时会复制动态规则，设置为 `"false"` 则只复制静态布局。
+
+**Q: 创建页面布局时报错 "对象不存在"？**
+
+A: 请确认传入的 `objId` 是正确的对象 ID，且该对象在当前环境中存在。
+
+---
+
+*文档版本：1.0 | 最后更新：2026-03-26*