cloudcc-cli 2.3.1 → 2.3.3

package/src/fields/docs/devguide.md

@@ -0,0 +1,224 @@
+# CloudCC 字段开发指南
+
+## 1. 模块定位
+
+`fields` 模块用于管理 CloudCC 对象字段，当前提供查询、创建、删除三类能力。
+
+可通过以下命令读取文档：
+
+```bash
+cc doc fields introduction
+cc doc fields devguide
+```
+
+---
+
+## 2. 当前支持的命令
+
+```bash
+cc get fields <projectPath> <objPrefix>
+cc create fields <projectPath> <fieldType> <objid> <fieldLabel> [extraArg]
+cc delete fields <projectPath> <fieldId> <objid>
+```
+
+说明：
+
+- `projectPath`：本地项目路径，用于读取 `cloudcc-cli.config.js`
+- `objPrefix`：对象前缀，用于查询字段
+- `fieldType`：字段类型编码（例如 `S`、`N`、`D` 等）
+- `objid`：对象 ID
+- `fieldLabel`：字段显示名称
+- `extraArg`：部分字段类型需要的额外参数，如 `ptext` 或 `lookupObj`
+- `fieldId`：字段 ID（用于删除）
+
+说明：
+
+- 当前 CLI 参数以 `src/fields/create.js`、`src/fields/get.js`、`src/fields/delete.js` 的实际实现为准
+- 字段 API 名称在当前创建逻辑中默认由 CLI 自动生成，不要求单独传入
+
+---
+
+## 3. 查询字段
+
+### 3.1 基本命令
+
+```bash
+cc get fields <projectPath> <objPrefix>
+```
+
+返回结果包含：
+
+- `obj`：对象基础信息
+- `stdFields`：标准字段列表
+- `cusFields`：自定义字段列表
+
+每个字段通常包含：
+
+- `fieldname`：字段显示名称
+- `apiname`：字段 API 名称
+- `schemefieldType`：字段类型编码
+- `id`：字段 ID
+
+---
+
+## 4. 创建字段
+
+### 4.1 基本命令
+
+```bash
+cc create fields <projectPath> <fieldType> <objid> <fieldLabel> [extraArg]
+```
+
+建议：
+
+- 先确认对象存在且 `objid` 正确
+- 字段类型与业务含义保持一致（如日期、数字、文本）
+- 当前 CLI 会根据字段标签自动生成字段 API 名称
+- 如果字段依赖选项值或关联对象，创建前先准备好 `extraArg`
+
+### 4.2 支持的字段类型说明
+
+根据 CloudCC 官方关于“对象-字段”的说明，平台层面支持文本、URL、百分比、币种、数字、文本区、长文本、富文本、电话、电子邮件、日期、日期/时间、评分、选项列表、图片、查找关系、主详信息关系、公式、自动编号、累计汇总、查找多选、复选框等类型。[CloudCC 帮助中心 - 标准对象 / 对象-字段](https://help.cloudcc.cn/product02/biao-zhun-dui-xiang/#3%E5%AF%B9%E8%B1%A1-%E5%AD%97%E6%AE%B5)
+
+当前 `src/fields/fields` 中已实现的 CLI 字段类型如下。
+
+#### 基础输入类
+
+| CLI 类型编码 | 类型名称 | 说明 |
+| --- | --- | --- |
+| `S` | 文本 | 单行文本，默认长度 255 |
+| `U` | URL | 输入有效网址，点击后可打开链接 |
+| `P` | 百分比 | 输入百分比数字 |
+| `C` | 币种 | 金额/币种场景，模板内部 `fdtype` 为 `c` |
+| `N` | 数字 | 输入数值，适用于数量、金额基数等 |
+| `D` | 日期 | 仅日期 |
+| `T` | 时间 | 仅时间 |
+| `F` | 日期/时间 | 日期和时间组合 |
+| `B` | 复选框 | 布尔值，真/假 |
+| `H` | 电话 | 电话号码 |
+| `E` | 电子邮件 | 邮箱地址 |
+| `SCORE` | 评分 | 用于评分或评价场景 |
+
+#### 文本区与内容类
+
+| CLI 类型编码 | 类型名称 | 说明 |
+| --- | --- | --- |
+| `X` | 文本区 | 多行文本，适合一般备注和说明 |
+| `J` | 文本区（长） | 长文本，模板默认长度 10000 |
+| `A` | 文本区（富文本） | 支持富文本内容、图文描述 |
+| `IMG` | 图片 | 图片类字段 |
+| `FL` | 文件 | 文件类字段 |
+
+#### 选择类
+
+| CLI 类型编码 | 类型名称 | 说明 |
+| --- | --- | --- |
+| `L` | 选项列表 | 单选下拉 |
+| `Q` | 选项列表（多选） | 多选下拉 |
+
+这两类字段创建时都需要额外的选项值参数：
+
+```bash
+cc create fields <projectPath> L <objid> <fieldLabel> <ptext>
+cc create fields <projectPath> Q <objid> <fieldLabel> <ptext>
+```
+
+其中 `ptext` 表示选项内容，通常用于传入候选值集合。
+
+平台层面的选项列表能力常用于：
+
+- 状态
+- 阶段
+- 分类
+- 来源
+- 优先级
+
+#### 关系类
+
+| CLI 类型编码 | 类型名称 | 说明 |
+| --- | --- | --- |
+| `Y` | 查找关系 | 关联另一个对象 |
+| `MR` | 查找多选 | 多选关联对象 |
+| `M` | 主详信息关系 | 主从/主详关系字段 |
+
+这三类字段创建时都需要额外传入目标对象参数：
+
+```bash
+cc create fields <projectPath> Y <objid> <fieldLabel> <lookupObj>
+cc create fields <projectPath> MR <objid> <fieldLabel> <lookupObj>
+cc create fields <projectPath> M <objid> <fieldLabel> <lookupObj>
+```
+
+其中 `lookupObj` 表示被关联对象。
+
+这类字段常用于：
+
+- 客户与联系人的关联
+- 项目与客户的关联
+- 主记录与明细记录的主详结构
+- 多对象之间的一对多或多对多表达
+
+#### 地址与定位类
+
+| CLI 类型编码 | 类型名称 | 说明 |
+| --- | --- | --- |
+| `AD` | 地址 | 地址复合字段 |
+| `LT` | 地理定位 | 地理坐标或定位信息 |
+
+#### 安全与加密类
+
+| CLI 类型编码 | 类型名称 | 说明 |
+| --- | --- | --- |
+| `ENC` | 加密文本（存储加密） | 底层存储加密 |
+| `ENCD` | 加密文本（显示加密） | 展示时掩码加密 |
+
+说明：
+
+- CLI 中使用的类型编码是 `ENC`、`ENCD`
+- 模板内部提交到接口时，对应的 `fdtype` 分别是 `enc`、`encd`
+- `C` 在模板内部对应的 `fdtype` 为小写 `c`
+- 这两类字段更适合身份证号、银行卡号、敏感联系方式等场景
+
+### 4.3 当前 CLI 未覆盖但平台支持的字段能力
+
+根据官方文档，平台层面还支持以下字段能力，但当前 `src/fields/fields` 目录下尚未看到对应 CLI 创建模板：
+
+- 公式
+- 自动编号
+- 累计汇总
+
+如果后续希望通过 CLI 直接创建这些字段类型，需要继续补充对应的模板实现。
+
+---
+
+## 5. 删除字段
+
+### 5.1 基本命令
+
+```bash
+cc delete fields <projectPath> <fieldId> <objid>
+```
+
+删除前建议：
+
+- 先确认字段未被页面、公式、触发器、类或脚本依赖
+- 先记录字段 API 名称与 ID，防止误删
+- 在测试环境验证后再在正式环境执行
+
+---
+
+## 6. 开发前检查
+
+- 已完成 `cc doc project devguide` 中的环境准备
+- 项目根目录存在可用的 `cloudcc-cli.config.js`
+- 当前环境密钥配置正确
+- 已确认对象 API 名称、字段类型和命名规则
+
+---
+
+## 7. 常见实践建议
+
+- 优先先做对象建模，再补字段明细，避免频繁返工
+- 字段命名规范化（显示名称清晰、API 名称可维护）
+- 对核心字段（金额、状态、日期）提前统一格式约定
+- 删除字段前先做依赖排查，确保不影响线上逻辑

package/src/fields/docs/introduction.md

@@ -0,0 +1,217 @@
+# CloudCC 字段介绍
+
+## 1. 什么是字段
+
+字段是对象上的数据属性定义，用于描述一条记录中每个信息项的结构与含义。
+
+你可以把字段理解为：
+
+- 业务数据的最小单元
+- 对象模型的具体列定义
+- 页面录入、查询、统计和自动化逻辑的基础
+
+从 CloudCC
+平台的角度看，字段就是对象的属性。姓名、手机、金额、状态、日期、负责人、附件等信息，本质上都是通过字段来承载的。
+
+---
+
+## 2. 标准字段与自定义字段
+
+CloudCC 对象上的字段通常分为两类：
+
+- 标准字段：平台预置字段，属于对象默认能力的一部分
+- 自定义字段：企业根据自身业务场景新增、维护和删除的字段
+
+所有对象通常都带有一些共通标准字段，例如：
+
+- 对象记录名
+- 创建时间
+- 创建人
+- 最后修改时间
+- 最后修改人
+- 所有人
+
+当标准字段无法表达业务信息时，就需要通过自定义字段去补充业务含义。
+
+---
+
+## 3. 字段模块能做什么
+
+`fields` 模块用于围绕对象管理字段，当前支持：
+
+- 查询对象字段（标准字段 + 自定义字段）
+- 创建字段
+- 删除字段
+
+可通过以下命令读取文档：
+
+```bash
+cc doc fields introduction
+cc doc fields devguide
+```
+
+---
+
+## 4. 字段在系统中的作用
+
+字段决定了对象能记录什么信息、如何被录入、如何被展示以及如何参与流程。
+
+常见作用包括：
+
+- 定义业务属性（如名称、金额、状态、日期）
+- 驱动页面展示和表单校验
+- 支撑筛选、排序、报表统计
+- 作为触发器和后端逻辑的判断条件
+- 为自动化、审批、报表和搜索提供数据基础
+
+如果对象是业务模型的骨架，那么字段就是业务模型的具体内容。
+
+---
+
+## 5. 为什么要重视字段设计
+
+字段设计质量会直接影响：
+
+- 数据录入是否清晰
+- 报表口径是否统一
+- 查询筛选是否高效
+- 流程和代码是否容易维护
+
+字段设计不合理时，常见问题包括：
+
+- 同类信息分散在多个字段里
+- 命名混乱，后续脚本和接口难维护
+- 页面录入项过多或缺失，影响使用体验
+- 统计分析无法统一口径
+- 自动化逻辑和触发器条件复杂、难排查
+
+因此，字段管理不是简单“加几个列”，而是业务建模和数据治理的重要部分。
+
+---
+
+## 6. 什么时候需要管理字段
+
+通常在以下场景需要使用 `fields` 模块：
+
+- 新建对象后，需要补齐业务字段
+- 业务流程变化，需要新增或调整字段结构
+- 数据治理中，需要清理不再使用的字段
+- 接口联动或自动化逻辑需要新增数据位
+- 页面、报表、审批、搜索需要新增业务属性
+
+---
+
+## 7. 常见业务场景
+
+字段设计常见于以下业务场景：
+
+- 销售场景：金额、预计签约日期、成交概率、阶段
+- 服务场景：工单状态、处理时间、满意度评分、附件图片
+- 项目场景：项目阶段、负责人、里程碑时间、进度说明
+- 资产场景：设备编号、安装地址、巡检周期、归属客户
+- 渠道场景：渠道级别、返佣比例、合作到期日、联系人信息
+
+很多企业在标准 CRM
+之外扩展业务时，真正落地管理的第一步往往不是写代码，而是先把字段设计清楚。
+
+---
+
+## 8. 平台能力与 CLI 能力的关系
+
+根据 CloudCC
+官方文档，平台层面支持丰富的字段体系，包括文本、URL、百分比、币种、数字、文本区、长文本、富文本、电话、电子邮件、日期、日期/时间、评分、选项列表、图片、查找关系、主详信息关系、公式、自动编号、累计汇总、查找多选、复选框等类型。
+
+当前 `cloudcc-cli` 的 `fields`
+模块已经覆盖了其中一部分常用字段类型，用于自动化创建和管理字段。
+
+因此在实际使用时，需要区分两层：
+
+- CloudCC 平台支持的完整字段能力
+- 当前 CLI 已实现的字段创建能力
+
+命令开发与自动化脚本，应以 `cc doc fields devguide` 中列出的“当前 CLI
+支持字段类型”为准。
+
+---
+
+## 9. 字段列表说明
+
+从业务理解角度，可以把常见字段类型分成下面几组：
+
+### 9.1 基础信息字段
+
+1. 文本（`S`）：用于姓名、编号、标题、简称等
+2. 数字（`N`）：用于数量、次数、评分基数等
+3. 币种（`C`）：用于金额、预算、合同额、回款额等
+4. 百分比（`P`）：用于概率、折扣率、完成率等
+5. 复选框（`B`）：用于是/否类状态
+
+### 9.2 时间类字段
+
+1. 日期（`D`）：用于开始日期、截止日期、签约日期等
+2. 时间（`T`）：用于预约时间、提醒时间等
+3. 日期/时间（`F`）：用于更精确的业务时间点，如处理时间、提交时间、完成时间
+
+### 9.3 联系方式与标识类字段
+
+1. 电话（`H`）：用于手机、座机、联系方式
+2. 电子邮件（`E`）：用于邮箱地址
+3. URL（`U`）：用于官网、资料链接、外部系统地址
+
+### 9.4 文本内容类字段
+
+1. 文本区（`X`）：用于备注、补充说明、简短描述
+2. 文本区（长）（`J`）：用于较长说明、详细记录、过程描述
+3. 文本区（富文本）（`A`）：用于图文混排的业务说明、通知内容、知识内容
+
+### 9.5 选择类字段
+
+1. 选项列表（`L`）：用于状态、阶段、分类、来源、优先级等单选场景
+2. 选项列表（多选）（`Q`）：用于标签、能力项、覆盖区域、产品范围等多选场景
+
+### 9.6 关系类字段
+
+1. 查找关系（`Y`）：用于把一条记录关联到另一对象
+2. 主详信息关系（`M`）：用于建立主从结构，适合主表与明细表场景
+3. 查找多选（`MR`）：用于一条记录关联多个对象值
+
+这类字段通常用于：
+
+1. 客户和联系人
+2. 项目和客户
+3. 合同和回款计划
+4. 主记录和明细记录
+
+### 9.7 媒体与附件类字段
+
+1. 图片（`IMG`）：用于头像、产品图、现场照片、凭证图片
+2. 文件（`FL`）：用于合同附件、方案文档、交付资料
+
+### 9.8 安全与特殊字段
+
+1. 加密文本（存储加密）（`ENC`）
+2. 加密文本（显示加密）（`ENCD`）
+3. 评分（`SCORE`）
+4. 地址（`AD`）
+5. 地理定位（`LT`）
+
+平台层面还支持但通常更偏高级配置的字段类型包括：
+
+1. 公式
+2. 自动编号
+3. 累计汇总
+
+这些字段更适合在有明确建模规则和业务约束时使用。
+
+---
+
+## 10. 与其他模块的关系
+
+字段通常和这些模块联动：
+
+- `object`：字段附着于对象，是对象建模的细化
+- `menu` / `application`：字段会影响列表和详情页呈现
+- `triggers` / `classes`：字段值常用于业务逻辑判断
+- `script` / `plugin` / `customPage`：前端交互通常围绕字段展开
+
+字段设计合理与否，直接影响后续开发效率和数据质量。

package/src/fields/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/globalSelectList/create.js

@@ -0,0 +1,51 @@
+const chalk = require("chalk");
+const { getPackageJson } = require("../../utils/config");
+const { postClass } = require("../../utils/http");
+
+/**
+ * cc create globalSelectList [projectPath] [encodedBodyJson]
+ *
+ * encodedBodyJson 示例（URI 编码前）：
+ * {
+ *   "label": "test2",
+ *   "name": "test2",
+ *   "description": "描述",
+ *   "ptext": "值1\r\n值2\r\n值3",
+ *   "isPicklistSorted": "1",
+ *   "isFirstDefault": "1"
+ * }
+ *
+ * @param {string} projectPath
+ * @param {string} encodedBodyJson
+ * @param {boolean} isMcp
+ */
+async function create(projectPath = process.cwd(), encodedBodyJson, isMcp = false) {
+    if (!encodedBodyJson) {
+        throw new Error("Create Global Select List Failed: encodedBodyJson is required");
+    }
+    const body = JSON.parse(decodeURI(encodedBodyJson));
+    if (!body.label || !body.name) {
+        throw new Error("Create Global Select List Failed: label and name are required");
+    }
+    const config = await getPackageJson(projectPath);
+    if (!isMcp) {
+        console.error();
+        console.error(chalk.green("Creating global select list, please wait..."));
+        console.error();
+    }
+    const res = await postClass(
+        config.setupSvc + "/api/globalSelectSetup/save",
+        body,
+        config.accessToken
+    );
+    if (res && res.result) {
+        if (!isMcp) {
+            console.error(chalk.green("Success! Global select list created. id: " + res.data));
+            console.error();
+        }
+        return res;
+    }
+    throw new Error("Create Global Select List Failed: " + (res?.returnInfo || res?.message || "Unknown error"));
+}
+
+module.exports = create;

package/src/globalSelectList/delete.js

@@ -0,0 +1,56 @@
+const chalk = require("chalk");
+const { getPackageJson } = require("../../utils/config");
+const { postClass } = require("../../utils/http");
+
+/**
+ * cc delete globalSelectList [projectPath] [id]
+ *
+ * 删除逻辑：
+ * 1. 先以 deleteFromDisk=false 执行软删除
+ * 2. 若服务端返回失败（已被软删除过），自动以 deleteFromDisk=true 重试，执行彻底删除
+ *
+ * @param {string} projectPath
+ * @param {string} id
+ * @param {boolean} isMcp
+ */
+async function remove(projectPath = process.cwd(), id, isMcp = false) {
+    if (!id) {
+        throw new Error("Delete Global Select List Failed: id is required");
+    }
+    const config = await getPackageJson(projectPath);
+    if (!isMcp) {
+        console.error();
+        console.error(chalk.green(`Deleting global select list (${id}), please wait...`));
+        console.error();
+    }
+
+    // 第一次尝试：软删除
+    let res = await postClass(
+        config.setupSvc + "/api/globalSelectSetup/delete",
+        { id, deleteFromDisk: "false" },
+        config.accessToken
+    );
+
+    // 若失败，说明记录已处于已删除状态，改用彻底删除重试
+    if (res && !res.result) {
+        if (!isMcp) {
+            console.error(chalk.yellow("Record may already be soft-deleted, retrying with permanent delete..."));
+        }
+        res = await postClass(
+            config.setupSvc + "/api/globalSelectSetup/delete",
+            { id, deleteFromDisk: "true" },
+            config.accessToken
+        );
+    }
+
+    if (res && res.result) {
+        if (!isMcp) {
+            console.error(chalk.green("Success! Global select list deleted."));
+            console.error();
+        }
+        return res;
+    }
+    throw new Error("Delete Global Select List Failed: " + (res?.returnInfo || res?.message || "Unknown error"));
+}
+
+module.exports = remove;

package/src/globalSelectList/detail.js

@@ -0,0 +1,45 @@
+const { getPackageJson } = require("../../utils/config");
+const { postClass } = require("../../utils/http");
+
+/**
+ * cc detail globalSelectList [projectPath] [id]
+ *
+ * 返回结构：
+ * {
+ *   globalSelect: { id, label, name, description, isDeleted, ... },
+ *   enabledList:  [ { id, codevalue, sortorder, isdefaultvalue, isactive, ... } ],
+ *   disabledList: [],
+ *   useList:      []
+ * }
+ *
+ * @param {string} projectPath
+ * @param {string} id
+ * @param {boolean} isMcp
+ */
+async function detail(projectPath = process.cwd(), id, isMcp = false) {
+    if (!id) {
+        throw new Error("Global Select List detail requires id");
+    }
+    const config = await getPackageJson(projectPath);
+    const res = await postClass(
+        config.setupSvc + "/api/globalSelectSetup/detail",
+        { id },
+        config.accessToken
+    );
+    if (res && res.result) {
+        const data = res.data || {};
+        const result = {
+            globalSelect: data.globalSelect || {},
+            enabledList: data.enabledList || [],
+            disabledList: data.disabledList || [],
+            useList: data.useList || []
+        };
+        if (!isMcp) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        return result;
+    }
+    throw new Error("Get Global Select List Detail Failed: " + (res?.returnInfo || res?.message || "Unknown error"));
+}
+
+module.exports = detail;

package/src/globalSelectList/doc.js

@@ -0,0 +1,52 @@
+/**
+ * globalSelectList 文档入口：正文均在 `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");
+}
+
+/**
+ * 介绍文档（introduction.md）
+ * 用于了解 CloudCC 全局选项列表的概念、定位、价值与适用场景。
+ */
+function getIntroductionDoc() {
+    return readDocFile("introduction");
+}
+
+/**
+ * 开发指导文档（devguide.md）
+ * 用于在 CloudCC 平台上进行全局选项列表的管理与使用。
+ */
+function getDevGuideDoc() {
+    return readDocFile("devguide");
+}
+
+/**
+ * cc doc globalSelectList <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 globalSelectList 需要子命令：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;