cloudcc-cli 2.3.0 → 2.3.2

package/src/customPage/create.js

@@ -3,20 +3,30 @@ const { getPackageJson } = require('../../utils/config');
 const { post } = require('../../utils/http');
 const BaseUrl = 'https://developer.apis.cloudcc.cn';
 
+function isEmptyArg(v) {
+    return v == null || String(v).trim() === '';
+}
+
 /**
  * 新建自定义页面
  *
- * 用法：cc customPage create <pageLabel> <pageApi> [projectPath]
+ * 用法：
+ *   cc create customPage <pageLabel> <pageApi> <pluginId|compLabel> [projectPath]
+ * 无参数（仅 create customPage）时：拉取自定义组件列表，使用第一个组件，并自动生成 pageLabel / pageApi。
  */
 async function createCustomPage(argvs) {
-    const pageLabel = argvs[2];
-    const pageApi = argvs[3];
-    const projectPath = argvs[4] || process.cwd();
+    const projectPath = argvs[5] || process.cwd();
+    let pageLabel = argvs[2];
+    let pageApi = argvs[3];
+    let pluginIdentifier = argvs[4];
+
+    const noPageArgs =
+        isEmptyArg(pageLabel) && isEmptyArg(pageApi) && isEmptyArg(pluginIdentifier);
 
-    if (!pageLabel || !pageApi) {
+    if (!noPageArgs && (isEmptyArg(pageLabel) || isEmptyArg(pageApi) || isEmptyArg(pluginIdentifier))) {
         console.error();
-        console.error(chalk.red('Error: pageLabel and pageApi are required'));
-        console.error(chalk.yellow('Usage: cc customPage create <pageLabel> <pageApi> [projectPath]'));
+        console.error(chalk.red('Error: pageLabel、pageApi、pluginId/compLabel 需同时提供，或全部省略以使用第一个自定义组件'));
+        console.error(chalk.yellow('Usage: cc create customPage [<pageLabel> <pageApi> <pluginId|compLabel>] [projectPath]'));
         console.error();
         return;
     }
@@ -39,20 +49,105 @@ async function createCustomPage(argvs) {
         version: 'public',
     };
 
+    const listRes = await post(
+        `${baseUrl}${devSvcDispatch}/custom/pc/1.0/post/listCustomComp`,
+        { orgId: config.orgId || '' },
+        header
+    );
+    if (!listRes || String(listRes.returnCode) !== '200') {
+        throw new Error('Create Custom Page Failed: list custom components failed');
+    }
+
+    const groupedCompMap = listRes.data || {};
+    const compList = Array.isArray(groupedCompMap['label.dev.bizType.custom'])
+        ? groupedCompMap['label.dev.bizType.custom']
+        : [];
+    if (compList.length === 0) {
+        throw new Error('Create Custom Page Failed: no custom components found');
+    }
+
+    let pluginDetail;
+    if (noPageArgs) {
+        pluginDetail = compList[0];
+        const ts = Date.now();
+        pageLabel = `CLI自动页面_${ts}`;
+        pageApi = `cc_cli_page_${ts}`;
+        pluginIdentifier = pluginDetail.id || pluginDetail.compLabel || pluginDetail.compUniName;
+        console.error();
+        console.error(
+            chalk.cyan(
+                `未指定页面参数，使用第一个自定义组件创建：` +
+                    `${pluginDetail.compLabel || pluginDetail.compName || pluginDetail.compUniName || pluginIdentifier} (${pluginIdentifier})`
+            )
+        );
+    } else {
+        pluginDetail = compList.find(
+            (item) =>
+                item &&
+                (item.id === pluginIdentifier ||
+                    item.compLabel === pluginIdentifier ||
+                    item.compUniName === pluginIdentifier)
+        );
+        if (!pluginDetail) {
+            throw new Error(`Create Custom Page Failed: component "${pluginIdentifier}" not found in custom component list`);
+        }
+    }
+
+    let vueData = {};
+    try {
+        vueData = pluginDetail.vueData ? JSON.parse(pluginDetail.vueData) : {};
+    } catch (e) {
+        throw new Error('Create Custom Page Failed: plugin vueData is not valid JSON');
+    }
+
+    const randomId = (len = 10) => Math.random().toString(36).slice(2, 2 + len);
+    const itemId = randomId(10);
+    const compUniName = pluginDetail.compUniName || pluginDetail.component || pluginDetail.name;
+    const compLabel = pluginDetail.compLabel || pluginDetail.compName || compUniName;
+    const compDesc = pluginDetail.compDesc || '';
+    const templatePropObj = vueData.propObj && typeof vueData.propObj === 'object' ? vueData.propObj : {};
+
+    const pageContentItem = {
+        ...vueData,
+        id: itemId,
+        comId: pluginDetail.id,
+        name: compUniName,
+        componentInfo: {
+            ...(vueData.componentInfo || {}),
+            component: compUniName,
+            compName: compLabel,
+            compDesc,
+        },
+        propObj: {
+            ...templatePropObj,
+            id: itemId,
+            key: templatePropObj.key || randomId(4),
+            pageApi,
+        },
+    };
+
     const body = {
         id: '',
         pageLabel,
         pageApi,
-        pageContent: '[]',
-        orgId: config.orgId || '',
-        renderVersion: '',
-        compList: [],
-        canvasStyleData: JSON.stringify({ width: 100, height: 100, scale: 100, unit: '%' }),
+        pageContent: JSON.stringify([pageContentItem]),
+        orgId: pluginDetail.orgId || config.orgId || '',
+        compList: [
+            {
+                id: pluginDetail.id,
+                compUniName,
+            },
+        ],
+        canvasStyleData: JSON.stringify({ width: 100, height: 100, scale: 100, unit: '%', pageApi }),
         isTemplate: 0,
     };
 
     console.error();
-    console.error(chalk.green(`Creating custom page "${pageLabel}" (api: ${pageApi}), please wait...`));
+    console.error(
+        chalk.green(
+            `Creating custom page "${pageLabel}" (api: ${pageApi}, component: ${pluginIdentifier}), please wait...`
+        )
+    );
 
     const res = await post(
         `${baseUrl}${devSvcDispatch}/custom/pc/1.0/post/insertCustomPage`,
@@ -60,7 +155,7 @@ async function createCustomPage(argvs) {
         header
     );
 
-    if (res && res.returnCode == 200) {
+    if (res && String(res.returnCode) === '200') {
         const id = res.data?.id || res.data || '';
         console.error(chalk.green(`Success! Custom page created.${id ? ' ID: ' + id : ''}`));
         console.error();

package/src/customPage/delete.js

@@ -6,7 +6,7 @@ const BaseUrl = 'https://developer.apis.cloudcc.cn';
 /**
  * 删除自定义页面
  *
- * 用法：cc customPage delete <id> [projectPath]
+ * 用法：cc delete customPage <id> [projectPath]
  */
 async function deleteCustomPage(argvs) {
     const id = argvs[2];
@@ -15,7 +15,7 @@ async function deleteCustomPage(argvs) {
     if (!id) {
         console.error();
         console.error(chalk.red('Error: Custom page ID is required'));
-        console.error(chalk.yellow('Usage: cc customPage delete <id> [projectPath]'));
+        console.error(chalk.yellow('Usage: cc delete customPage <id> [projectPath]'));
         console.error();
         return;
     }

package/src/customPage/doc.js

@@ -0,0 +1,46 @@
+/**
+ * customPage 文档入口：正文均在 `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");
+}
+
+/** 开发指导：搭建、集成与调试 */
+function getDevGuideDoc() {
+    return readDocFile("devguide");
+}
+
+/**
+ * cc doc customPage <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 customPage 需要子命令：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/customPage/docs/devguide.md

@@ -0,0 +1,200 @@
+# CloudCC 自定义页面开发指南
+
+## 1. 模块定位
+
+`customPage` 模块用于通过 CLI 管理自定义页面，当前提供：
+
+- 创建页面：`cc create customPage ...`
+- 查询页面：`cc get customPage ...`
+- 删除页面：`cc delete customPage ...`
+- 文档查看：`cc doc customPage introduction|devguide`
+
+---
+
+## 2. 开发前准备
+
+执行命令前请确认：
+
+- 已完成 `cc doc project devguide` 的环境准备
+- 项目路径下存在可用配置，且包含 `accessToken`
+- 当前组织已存在至少一个自定义组件（创建页面时会依赖组件列表）
+
+若配置缺失，命令会报错：
+
+```text
+Error: Configuration not found or accessToken is missing
+```
+
+---
+
+## 3. 命令总览（以代码实现为准）
+
+```bash
+cc create customPage [<pageLabel> <pageApi> <pluginId|compLabel>] [projectPath]
+cc get customPage [pageNo] [pageSize] [projectPath]
+cc delete customPage <id> [projectPath]
+cc doc customPage <introduction|devguide>
+```
+
+---
+
+## 4. 创建自定义页面
+
+## 4.1 标准创建模式
+
+```bash
+cc create customPage <pageLabel> <pageApi> <pluginId|compLabel> [projectPath]
+```
+
+参数说明：
+
+- `pageLabel`：页面名称
+- `pageApi`：页面 API 名称
+- `pluginId|compLabel`：组件标识，支持以下任一匹配：
+  - 组件 `id`
+  - 组件 `compLabel`
+  - 组件 `compUniName`
+- `projectPath`：项目路径，默认当前目录
+
+示例：
+
+```bash
+cc create customPage "合同助手页面" contract_assistant_page 2f9d0d6d2a ./
+cc create customPage "合同助手页面" contract_assistant_page 合同助手组件
+```
+
+## 4.2 自动创建模式（无参数）
+
+```bash
+cc create customPage
+```
+
+当不传 `pageLabel/pageApi/plugin` 三个参数时，CLI 会自动：
+
+1. 拉取自定义组件列表
+2. 使用列表第一个组件
+3. 生成页面名：`CLI自动页面_<timestamp>`
+4. 生成页面 API：`cc_cli_page_<timestamp>`
+
+这是快速验证环境是否可用的便捷方式。
+
+## 4.3 参数校验规则
+
+- 三个核心参数要么**同时传入**，要么**全部省略**
+- 若只传部分参数，会报错并提示正确用法：
+
+```text
+Error: pageLabel、pageApi、pluginId/compLabel 需同时提供，或全部省略以使用第一个自定义组件
+Usage: cc create customPage [<pageLabel> <pageApi> <pluginId|compLabel>] [projectPath]
+```
+
+## 4.4 创建过程说明
+
+创建命令内部会执行以下步骤：
+
+1. 读取项目配置（token、org 等）
+2. 请求组件列表接口：`listCustomComp`
+3. 按 `id/compLabel/compUniName` 匹配组件
+4. 读取组件 `vueData`，并拼装页面内容
+5. 调用创建接口：`insertCustomPage`
+
+常见失败场景：
+
+- 组件列表为空：`no custom components found`
+- 指定组件未找到：`component "<x>" not found in custom component list`
+- `vueData` 非合法 JSON：`plugin vueData is not valid JSON`
+
+---
+
+## 5. 查询自定义页面
+
+```bash
+cc get customPage [pageNo] [pageSize] [projectPath]
+```
+
+参数说明：
+
+- `pageNo`：页码，默认 `1`
+- `pageSize`：每页数量，默认 `20`
+- `projectPath`：项目路径，默认当前目录
+
+示例：
+
+```bash
+cc get customPage
+cc get customPage 1 50 ./
+```
+
+执行成功后会输出总数，并逐条打印页面：
+
+- `ID`
+- `Label`（`pageLabel`）
+- `API`（`pageApi`）
+
+---
+
+## 6. 删除自定义页面
+
+```bash
+cc delete customPage <id> [projectPath]
+```
+
+参数说明：
+
+- `id`：页面 ID（必填）
+- `projectPath`：项目路径，默认当前目录
+
+示例：
+
+```bash
+cc delete customPage 2f9d0d6d2a
+cc delete customPage 2f9d0d6d2a ./
+```
+
+若缺少 `id`，会报错：
+
+```text
+Error: Custom page ID is required
+Usage: cc delete customPage <id> [projectPath]
+```
+
+---
+
+## 7. 文档命令
+
+```bash
+cc doc customPage introduction
+cc doc customPage devguide
+```
+
+说明：
+
+- 仅支持 `introduction` 与 `devguide`
+- 传入其他子命令会抛错
+
+---
+
+## 8. 推荐操作流程
+
+```bash
+# 1) 先查列表，确认现有页面
+cc get customPage
+
+# 2) 创建页面（标准模式）
+cc create customPage "合同助手页面" contract_assistant_page 2f9d0d6d2a
+
+# 3) 再查列表，确认创建成功并记录 ID
+cc get customPage
+
+# 4) 如需回滚，按 ID 删除
+cc delete customPage <id>
+```
+
+---
+
+## 9. 注意事项
+
+- `create` 强依赖自定义组件，先确保组件已存在
+- 建议优先使用可读性高的 `pageApi` 命名（如业务域+功能）
+- 删除前先确认页面未被菜单或其他入口依赖
+- 生产环境操作前，先在测试环境验证参数与组件匹配

package/src/customPage/docs/introduction.md

@@ -0,0 +1,224 @@
+# CloudCC 自定义页面说明文档
+
+## 一、什么是自定义页面
+
+自定义页面是 CloudCC
+平台提供的可视化页面构建工具，基于**自定义组件**创建，通过**拖拉拽**的方式调整页面布局、配置组件属性，实现各种业务需求。
+
+### 核心特点
+
+- 🎨 **可视化编辑** - 无需编码，通过拖拽组件快速搭建页面
+- 🧩 **组件化** - 基于自定义组件构建，支持复用和扩展
+- 📱 **自适应布局** - 支持像素、百分比、视口等多种单位
+- 🔌 **灵活集成** - 支持菜单、内嵌、代码调用等多种使用方式
+
+---
+
+## 二、自定义页面能干什么
+
+### 1. 快速构建业务页面
+
+通过物料库中的基础组件和数据组件，快速搭建符合业务需求的页面，无需从零开始编码。
+
+### 2. 灵活布局设计
+
+- 支持固定宽高布局（像素单位）
+- 支持自适应布局（百分比单位）
+- 支持响应式布局（视口单位）
+
+### 3. 组件间通信
+
+通过 `$CCDK.CCBus` 实现组件间的消息传递，支持复杂业务逻辑的协同工作。
+
+### 4. 多场景集成
+
+- 创建独立菜单页面
+- 内嵌到系统详情页
+- 通过 `ccdk.openCustomPage()` 代码调用
+
+### 5. 移动端调试
+
+支持使用 eruda 插件在移动端 App 中调试 H5 页面。
+
+---
+
+## 三、主要作用
+
+| 作用            | 说明                         |
+| --------------- | ---------------------------- |
+| 🚀 **加速开发** | 可视化搭建，减少重复编码工作 |
+| 🔄 **组件复用** | 一次开发组件，多处页面使用   |
+| 🎯 **业务适配** | 灵活配置，快速响应业务变化   |
+| 📦 **降低门槛** | 非开发人员也可参与页面搭建   |
+| 🔧 **易于维护** | 组件化设计，修改影响范围可控 |
+
+---
+
+## 四、为什么要用自定义页面
+
+### 传统开发方式的问题
+
+- ❌ 每个页面都需要单独编码，重复工作多
+- ❌ 样式和布局不统一，维护成本高
+- ❌ 业务变更时需要修改代码，发布周期长
+- ❌ 非开发人员无法参与，依赖开发资源
+
+### 自定义页面的优势
+
+- ✅ **标准化** - 统一的组件规范和页面结构
+- ✅ **高效** - 拖拽式操作，分钟级完成页面搭建
+- ✅ **灵活** - 组件可配置，适应不同业务场景
+- ✅ **可扩展** - 支持自定义组件开发，满足特殊需求
+- ✅ **低代码** - 业务人员可参与，减少开发依赖
+
+---
+
+## 五、自定义页面能解决哪些问题
+
+### 1. 个性化业务需求
+
+标准页面无法满足的个性化业务场景，通过自定义页面快速实现。
+
+**示例**：特殊的审批流程页面、定制化的数据展示面板
+
+### 2. 复杂数据展示
+
+需要多维度、多格式展示数据的场景。
+
+**示例**：仪表盘、统计报表、数据可视化大屏
+
+### 3. 特殊交互需求
+
+标准组件无法满足的交互逻辑。
+
+**示例**：拖拽排序、动态表单、联动筛选
+
+### 4. 第三方系统集成
+
+需要嵌入外部系统或调用外部 API 的场景。
+
+**示例**：嵌入 BI 报表、调用外部服务接口
+
+### 5. 移动端适配
+
+需要同时支持 PC 和移动端的页面。
+
+**示例**：外勤人员使用的移动审批页面
+
+### 6. 快速原型验证
+
+业务需求不明确时，快速搭建原型进行验证。
+
+**示例**：新功能 MVP 验证、用户反馈收集
+
+---
+
+## 六、使用场景与业务场景
+
+### 6.1 推荐使用自定义页面的场景
+
+| 场景类型        | 具体场景                     | 推荐理由             |
+| --------------- | ---------------------------- | -------------------- |
+| 📊 **数据展示** | 仪表盘、统计报表、数据大屏   | 灵活布局，多组件组合 |
+| 📝 **表单录入** | 复杂表单、动态表单、多级表单 | 组件可配置，校验灵活 |
+| 🔍 **查询搜索** | 高级搜索、多条件筛选         | 组件间通信方便       |
+| 📋 **审批流程** | 定制化审批页、特殊流程       | 业务逻辑可定制       |
+| 📱 **移动端**   | 外勤应用、移动办公           | 自适应布局支持好     |
+| 🔗 **系统集成** | 嵌入外部系统、API 调用       | 扩展性强             |
+| 🎨 **品牌定制** | 企业个性化页面               | 样式可完全定制       |
+
+### 6.2 不推荐使用自定义页面的场景
+
+| 场景           | 原因         | 建议方案         |
+| -------------- | ------------ | ---------------- |
+| 标准 CRUD 操作 | 杀鸡用牛刀   | 使用系统标准页面 |
+| 简单信息展示   | 过度设计     | 使用系统详情页   |
+| 一次性使用     | 投入产出比低 | 评估是否需要     |
+
+---
+
+## 七、最佳实践
+
+### 7.1 页面设计原则
+
+```
+┌─────────────────────────────────┐
+│         自定义页面 (100%)        │
+│  ┌───────────────────────────┐  │
+│  │      自定义组件 (100%)     │  │
+│  │                           │  │
+│  │   组件内部自由布局         │  │
+│  │                           │  │
+│  └───────────────────────────┘  │
+└─────────────────────────────────┘
+```
+
+- 📐 **一页一组件** - 一个页面只放一个组件，画布和组件都设置 100% 宽高
+- 🧩 **组件内布局** - 复杂布局在组件内部实现，保持页面简洁
+- 🔄 **组件复用** - 通用功能封装成组件，多处复用
+
+### 7.2 组件通信规范
+
+```javascript
+// 组件 A - 接收消息
+mounted() {
+  this.$CCDK.CCBus.$on('demoB2A', (args) => {
+    console.log("收到消息", args)
+  })
+},
+beforeDestroy() {
+  this.$CCDK.CCBus.$off('demoB2A') // 记得解绑
+}
+
+// 组件 B - 发送消息
+methods: {
+  emit() {
+    this.$CCDK.CCBus.$emit("demoB2A", "消息内容")
+  }
+}
+```
+
+### 7.3 页面入口选择
+
+| 入口方式   | 适用场景           | 配置方式                |
+| ---------- | ------------------ | ----------------------- |
+| 菜单       | 独立功能模块       | 自定义页面菜单          |
+| 内嵌详情页 | 关联业务展示       | 系统详情页配置          |
+| 代码调用   | 动态跳转、条件打开 | `ccdk.openCustomPage()` |
+
+---
+
+## 八、快速开始
+
+### 8.1 创建自定义页面
+
+1. 登录 CloudCC 系统
+2. 点击右上角头像 → 开发者控制台
+3. 自定义布局 → 自定义页面 → 新建
+4. 从物料库拖拽组件到画布
+5. 配置组件属性
+6. 保存页面
+
+### 8.4 调试与发布
+
+- 使用预览功能测试页面
+- 移动端使用 eruda 调试
+- 发布后配置页面入口
+
+---
+
+## 九、总结
+
+自定义页面是 CloudCC 平台提供的**低代码页面构建解决方案**，核心价值在于：
+
+- 🎯 **提效** - 减少重复开发，加速交付
+- 🔧 **灵活** - 适应各种业务场景
+- 📦 **复用** - 组件化设计，一次开发多处使用
+- 🚀 **扩展** - 支持自定义组件，无上限扩展
+
+**适用原则**：标准功能优先，个性化需求用自定义页面。
+
+---
+
+_文档版本：1.0_\
+_最后更新：2026-03-25_

package/src/customPage/get.js

@@ -6,7 +6,7 @@ const BaseUrl = 'https://developer.apis.cloudcc.cn';
 /**
  * 获取自定义页面列表
  *
- * 用法：cc customPage list [pageNo] [pageSize] [projectPath]
+ * 用法：cc get customPage [pageNo] [pageSize] [projectPath]
  */
 async function listCustomPage(argvs) {
     const pageNo = parseInt(argvs[2], 10) || 1;

package/src/customPage/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 CustomPage(action, argvs) {
     cc[action](argvs);

package/src/customSetting/create.js

@@ -0,0 +1,36 @@
+/**
+ * 自定义设置 - 新建/更新（保存主对象）
+ * API: POST {setupSvc}/api/customsetting/save
+ * CLI: cc create customSetting <projectPath> <encodedBodyJson>
+ * 参数说明：
+ * - projectPath: 项目根目录
+ * - encodedBodyJson: encodeURI(JSON.stringify(body))
+ * - body: { tpSysObjectVO: { id, label, schemetableName, dataType, accessable, remark, ... } }
+ */
+const chalk = require("chalk");
+const { getPackageJson } = require("../../utils/config");
+const { postClass } = require("../../utils/http");
+
+async function create(projectPath = process.cwd(), encodedBodyJson) {
+    if (!encodedBodyJson) {
+        throw new Error("Create Custom Setting Failed: encodedBodyJson is required");
+    }
+    const body = JSON.parse(decodeURI(encodedBodyJson));
+    const config = await getPackageJson(projectPath);
+    console.error();
+    console.error(chalk.green("Creating custom setting, please wait..."));
+    console.error();
+    const res = await postClass(
+        config.setupSvc + "/api/customsetting/save",
+        body,
+        config.accessToken
+    );
+    if (res && res.result) {
+        console.error(chalk.green("Success! Custom setting saved."));
+        console.error();
+        return res;
+    }
+    throw new Error("Create Custom Setting Failed: " + (res?.returnInfo || res?.message || "Unknown error"));
+}
+
+module.exports = create;