cloudcc-cli 2.3.0 → 2.3.2

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*

package/src/pagelayout/docs/introduction.md

@@ -0,0 +1,44 @@
+# 页面布局（Page Layout）介绍
+
+页面布局是 CloudCC 中用于定义对象详情页展示方式的重要配置。
+
+## 什么是页面布局？
+
+页面布局决定了：
+- 字段在详情页如何排列和分组
+- 哪些字段显示、哪些隐藏
+- 操作按钮的位置和顺序
+- 相关列表的展示方式
+- 动态布局规则（根据条件显示/隐藏字段）
+
+## 适用对象
+
+页面布局可以应用于：
+- **标准对象**：如 Account（客户）、Contact（联系人）等系统内置对象
+- **自定义对象**：用户根据业务需求创建的对象
+
+## 前置条件
+
+操作页面布局前，必须先**选中对象**（自定义对象或标准对象）。
+
+## 核心能力
+
+| 能力 | 说明 |
+|------|------|
+| 查询布局列表 | 查看对象下的所有页面布局 |
+| 创建布局 | 基于现有布局复制创建新布局 |
+| 复制动态规则 | 可选择是否复制源布局的动态布局规则 |
+
+## 使用场景
+
+1. **多终端适配**：为 PC 端和移动端创建不同的布局
+2. **多角色视图**：为不同角色创建差异化的详情页展示
+3. **业务场景适配**：针对特定业务流程定制字段展示
+
+## 下一步
+
+查看开发指南了解具体 CLI 命令：
+
+```bash
+cc doc pagelayout devguide
+```

package/src/pagelayout/get.js

@@ -0,0 +1,46 @@
+const { postClass } = require("../../utils/http");
+const { getPackageJson } = require("../../utils/config");
+const chalk = require("chalk");
+
+/**
+ * 查询页面布局列表
+ * 用法：cc get pagelayout <projectPath> <objApiName>
+ */
+async function get(argvs, isMcp = false) {
+    const projectPath = argvs[2] || process.cwd();
+    const objApiName = argvs[3];
+
+    if (!objApiName) {
+        console.error();
+        console.error(chalk.red("Error: 缺少对象 API 名称"));
+        console.error("用法: cc get pagelayout <projectPath> <objApiName>");
+        console.error("示例:");
+        console.error("  cc get pagelayout . b25");
+        console.error("  cc get pagelayout . Account");
+        console.error();
+        throw new Error("缺少必需参数: objApiName");
+    }
+
+    const config = await getPackageJson(projectPath);
+
+    const res = await postClass(
+        config.setupSvc + "/api/layout/queryPageLayout",
+        {
+            prefix: objApiName
+        },
+        config.accessToken
+    );
+
+    if (res && res.result) {
+        const layouts = res.layouts || [];
+        if (!isMcp) {
+            console.log(JSON.stringify(layouts));
+        }
+        return layouts;
+    }
+
+    const msg = res && (res.returnInfo || res.message) ? (res.returnInfo || res.message) : "Unknown error";
+    throw new Error("Get PageLayout Failed: " + msg);
+}
+
+module.exports = get;

package/src/pagelayout/index.js

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

package/src/plugin/detail.js

@@ -10,7 +10,14 @@ const BaseUrl = "https://developer.apis.cloudcc.cn";
  * - 如果提供了 pluginId，从线上查询
  * - 如果都没有，返回错误
  */
-async function detail(argvs) {
+function outputResult(result, isMcp) {
+    if (!isMcp) {
+        console.log(JSON.stringify(result));
+    }
+    return result;
+}
+
+async function detail(argvs, isMcp = false) {
     const pluginName = argvs[2];
     const pluginId = argvs[3];
     const projectPath = argvs[4] || process.cwd();
@@ -30,7 +37,7 @@ async function detail(argvs) {
             const configContent = JSON.parse(fs.readFileSync(configPath, 'utf8'));
             const vueContent = fs.readFileSync(vueFilePath, 'utf8');
 
-            return {
+            return outputResult({
                 name: pluginName,
                 component: configContent.component || `component-${pluginName}`,
                 compName: configContent.compName || pluginName,
@@ -40,7 +47,7 @@ async function detail(argvs) {
                 config: configContent,
                 published: !!configContent.id,
                 fromLocal: true
-            };
+            }, isMcp);
         } catch (e) {
             throw new Error(`Failed to read plugin files: ${e.message}`);
         }
@@ -72,10 +79,11 @@ async function detail(argvs) {
                 header
             );
             if (res && res.returnCode == 200 && res.data) {
-                return {
-                    ...res.data,
+                const { compContentJs, compContentVue, ...safeData } = res.data;
+                return outputResult({
+                    ...safeData,
                     fromLocal: false
-                };
+                }, isMcp);
             } else {
                 throw new Error('Get Plugin Details Failed: ' + (res?.returnInfo || 'Unknown error'));
             }