cloudcc-cli 2.3.1 → 2.3.3

package/src/config/docs/devguide.md

@@ -0,0 +1,100 @@
+# CloudCC 配置模块开发指南
+
+## 1. 模块定位
+
+`config` 模块用于管理本地项目配置文件 `cloudcc-cli.config.js` 的环境切换与查看。
+
+当前支持：
+
+- 切换当前环境：`cc use config <env> [projectPath]`
+- 查看当前配置：`cc get config [projectPath]`
+- 查看开发文档：`cc doc config devguide`
+
+---
+
+## 2. 开发前准备
+
+执行命令前请确认：
+
+- 已完成 `cc doc project devguide` 的初始化流程
+- 项目根目录存在 `cloudcc-cli.config.js`
+- `cloudcc-cli.config.js` 中包含可切换的环境配置（如 `test`、`prod`）
+
+---
+
+## 3. 命令总览（以当前实现为准）
+
+```bash
+cc use config <env> [projectPath]
+cc get config [projectPath]
+cc doc config devguide
+```
+
+参数约定：
+
+- `env`：目标环境名称（例如 `test`、`prod`）
+- `projectPath`：项目路径，不传时默认当前目录
+
+---
+
+## 4. 切换环境
+
+```bash
+cc use config <env> [projectPath]
+```
+
+说明：
+
+- 命令会读取 `<projectPath>/cloudcc-cli.config.js`
+- 将 `use` 字段更新为传入的 `env`
+- 写回配置文件后，后续命令将按新的 `use` 环境读取连接信息
+
+示例：
+
+```bash
+# 在当前目录切换到 test 环境
+cc use config test .
+```
+
+---
+
+## 5. 查看配置
+
+```bash
+cc get config [projectPath]
+```
+
+说明：
+
+- 命令会读取并输出当前配置对象
+- 不传 `projectPath` 时默认读取当前目录
+
+示例：
+
+```bash
+# 查看当前目录配置
+cc get config .
+```
+
+---
+
+## 6. 常见注意事项
+
+- 执行路径错误会导致找不到 `cloudcc-cli.config.js`
+- `env` 必须是配置中可识别的环境名称，否则后续命令可能读取失败
+- 切换环境后建议立即执行一次 `cc get config .` 进行确认
+
+---
+
+## 7. 推荐操作顺序
+
+```bash
+# 1) 查看当前配置
+cc get config .
+
+# 2) 切换到目标环境
+cc use config test .
+
+# 3) 再次查看，确认已生效
+cc get config .
+```

package/src/config/index.js

@@ -1,7 +1,12 @@
 const cc = {}
 cc.use = require("./use")
 cc.get = require("./get")
+cc.doc = require("./doc")
 function main(action, argvs) {
+  if (action === "doc") {
+    cc.doc(argvs)
+    return
+  }
   cc[action](argvs[2], argvs[3])
 }
 

package/src/customPage/create.js

@@ -3,21 +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 create customPage <pageLabel> <pageApi> <pluginId|compLabel> [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 pluginIdentifier = argvs[4];
     const projectPath = argvs[5] || process.cwd();
+    let pageLabel = argvs[2];
+    let pageApi = argvs[3];
+    let pluginIdentifier = argvs[4];
 
-    if (!pageLabel || !pageApi || !pluginIdentifier) {
+    const noPageArgs =
+        isEmptyArg(pageLabel) && isEmptyArg(pageApi) && isEmptyArg(pluginIdentifier);
+
+    if (!noPageArgs && (isEmptyArg(pageLabel) || isEmptyArg(pageApi) || isEmptyArg(pluginIdentifier))) {
         console.error();
-        console.error(chalk.red('Error: pageLabel, pageApi and pluginId/compLabel are required'));
-        console.error(chalk.yellow('Usage: cc create customPage <pageLabel> <pageApi> <pluginId|compLabel> [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;
     }
@@ -40,7 +49,6 @@ async function createCustomPage(argvs) {
         version: 'public',
     };
 
-    // 先通过 listCustomComp 获取组件列表，再按组件标识匹配目标组件
     const listRes = await post(
         `${baseUrl}${devSvcDispatch}/custom/pc/1.0/post/listCustomComp`,
         { orgId: config.orgId || '' },
@@ -58,12 +66,31 @@ async function createCustomPage(argvs) {
         throw new Error('Create Custom Page Failed: no custom components found');
     }
 
-    let 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 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 = {};
@@ -105,16 +132,22 @@ async function createCustomPage(argvs) {
         pageApi,
         pageContent: JSON.stringify([pageContentItem]),
         orgId: pluginDetail.orgId || config.orgId || '',
-        compList: [{
-            id: pluginDetail.id,
-            compUniName,
-        }],
+        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}, component: ${pluginIdentifier}), 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`,

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/{.cursor/skills/cloudcc-cli-dev/docs//350/207/252/345/256/232/344/271/211/351/241/265/351/235/242.md → src/customPage/docs/introduction.md}

@@ -199,11 +199,7 @@ methods: {
 5. 配置组件属性
 6. 保存页面
 
-### 8.2 开发自定义组件
-
-参考：[自定义组件开发文档](https://cloudccone.feishu.cn/wiki/AzyWwgHBPiEG2gkeDEXcb56snbb)
-
-### 8.3 调试与发布
+### 8.4 调试与发布
 
 - 使用预览功能测试页面
 - 移动端使用 eruda 调试

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

@@ -1,3 +1,12 @@
+/**
+ * 自定义设置 - 新建/更新（保存主对象）
+ * 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");

package/src/customSetting/delete.js

@@ -1,3 +1,12 @@
+/**
+ * 自定义设置 - 删除主对象
+ * API: POST {setupSvc}/api/customsetting/deleteobj
+ * CLI: cc delete customSetting <projectPath> <settingId>
+ * 参数说明：
+ * - projectPath: 项目根目录
+ * - id(命令参数名 settingId): 自定义设置 id
+ * - 请求体: { objid: id }
+ */
 const chalk = require("chalk");
 const { getPackageJson } = require("../../utils/config");
 const { postClass } = require("../../utils/http");
@@ -12,7 +21,7 @@ async function remove(projectPath = process.cwd(), id) {
     console.error();
     const res = await postClass(
         config.setupSvc + "/api/customsetting/deleteobj",
-        { id },
+        { objid: id },
         config.accessToken
     );
     if (res && res.result) {

package/src/customSetting/deleteCustomSettingField.js

@@ -0,0 +1,43 @@
+/**
+ * 自定义设置字段 - 删除字段
+ * API: POST {setupSvc}/api/customsetting/deletefield
+ * CLI: cc deleteCustomSettingField customSetting <projectPath> <fieldId> <settingId>
+ * 参数说明：
+ * - projectPath: 项目根目录
+ * - id(命令参数名 fieldId): 字段 id
+ * - objid(命令参数名 settingId): 所属自定义设置 id
+ * - 请求体: { id, objid }
+ */
+const chalk = require("chalk");
+const { getPackageJson } = require("../../utils/config");
+const { postClass } = require("../../utils/http");
+
+/**
+ * 删除自定义字段
+ */
+async function deletefield(projectPath = process.cwd(), id, objid) {
+    if (!id) {
+        throw new Error("Custom Setting deletefield Failed: id is required");
+    }
+    if (!objid) {
+        throw new Error("Custom Setting deletefield Failed: objid is required");
+    }
+
+    const config = await getPackageJson(projectPath);
+    const res = await postClass(
+        config.setupSvc + "/api/customsetting/deletefield",
+        { id, objid },
+        config.accessToken
+    );
+
+    if (res && res.result) {
+        console.error();
+        console.error(chalk.green(`Success! Custom setting field deleted.`));
+        console.error();
+        return res;
+    }
+    throw new Error("Custom Setting deletefield Failed: " + (res?.returnInfo || res?.message || "Unknown error"));
+}
+
+module.exports = deletefield;
+

package/src/customSetting/detail.js

@@ -1,3 +1,12 @@
+/**
+ * 自定义设置 - 详情（含字段列表）
+ * API: POST {setupSvc}/api/customsetting/detail
+ * CLI: cc detail customSetting <projectPath> <settingId>
+ * 参数说明：
+ * - projectPath: 项目根目录
+ * - id(命令参数名 settingId): 自定义设置 id
+ * - 请求体: { objid: id }
+ */
 const { getPackageJson } = require("../../utils/config");
 const { postClass } = require("../../utils/http");
 
@@ -8,7 +17,7 @@ async function detail(projectPath = process.cwd(), id, isMcp = false) {
     const config = await getPackageJson(projectPath);
     const res = await postClass(
         config.setupSvc + "/api/customsetting/detail",
-        { id },
+        { objid: id },
         config.accessToken
     );
     if (res && res.result) {