cloudcc-cli 2.3.1 → 2.3.3

package/src/project/docs/devguide.md

@@ -0,0 +1,359 @@
+# CloudCC Project 文档（全量）
+
+## 开发环境搭建
+
+# CloudCC CRM 前后端开发环境搭建指南
+
+> 本文档基于 CloudCC
+> 官方「开发环境」文档整理而成，原文参见：[CloudCC 开发环境](https://help.cloudcc.cn/product03/kai-fa-huan-jing/)。\
+> 目标：指导开发者完成本地 Node / VS Code / cloudcc-cli / MCP / 模板项目 /
+> 密钥配置等端到端环境搭建。
+
+---
+
+## 1. 前置条件与总体说明
+
+- 适用人群：CloudCC 前端组件、客户端脚本、后端类/触发器/定时器等二次开发工程师。
+- 基本流程：
+  1. 安装 Node 与 npm，并切换 npm 源
+  2. 安装 `cloudcc-cli` 全局依赖
+  3. 安装 VS Code 与 CloudCC 插件
+  4. 配置本地 MCP（`cc-mcp`）
+  5. 使用 CLI 创建模板项目并安装依赖
+  6. 通过 CRM 获取开发者密钥、安全标记并写入 `cloudcc-cli.config.js`
+  7. 视情况配置私有云与多环境参数
+
+---
+
+## 2. 安装 Node 与 npm 源配置
+
+### 2.1 安装 Node
+
+- **推荐版本**：`v20.19.5`（官方示例）
+- **下载地址**：
+  - Node 官方历史版本下载：`https://nodejs.org/download/release/v20.19.5/`
+- **建议**：使用 `nvm` 等 Node 多版本管理工具切换版本，保证与 CloudCC 官方推荐版本一致。
+
+安装完成后，在终端中验证：
+
+```bash
+node -v
+```
+
+### 2.2 切换 npm 源到阿里镜像
+
+为加速依赖安装，建议设置 npm 源为阿里镜像：
+
+```bash
+npm config set registry https://registry.npmmirror.com
+```
+
+验证是否设置成功：
+
+```bash
+npm config get registry
+```
+
+返回 `https://registry.npmmirror.com/` 即表示生效。
+
+---
+
+## 3. 安装 cloudcc-cli（全局）
+
+### 3.1 Windows 用户
+
+在命令行中执行：
+
+```bash
+npm install -g cloudcc-cli
+```
+
+### 3.2 macOS 用户
+
+在终端中执行（需要 sudo）：
+
+```bash
+sudo npm install -g cloudcc-cli
+```
+
+### 3.3 验证安装
+
+查看全局依赖列表，确认 `cloudcc-cli` 已安装：
+
+```bash
+npm ls -g --depth=0
+```
+
+在 macOS 上如需查看 sudo 下的全局包，可使用：
+
+```bash
+sudo npm ls -g --depth=0
+```
+
+---
+
+## 4. 安装 VS Code 与 CloudCC 插件
+
+### 4.1 安装 VS Code
+
+- 下载地址：`https://code.visualstudio.com/download`
+- 安装完成后，用 VS Code 作为主要开发编辑器。
+
+### 4.2 安装 CloudCC 插件
+
+1. 打开 VS Code，点击左侧扩展（Extensions）图标
+2. 搜索 `CloudCC`
+3. 选择官方 CloudCC 插件并安装
+
+> 若在 Cursor 中开发，可参考 CloudCC 帮助中心中关于「常用工具 / Cursor 安装方式」的说明：`https://help.cloudcc.cn/product03/chang-yong-gong-ju/`
+
+---
+
+## 5. 安装并配置本地 MCP（cc-mcp）
+
+在支持 MCP 的开发工具中（如 Cursor），需要在 MCP 配置文件中添加：
+
+```json
+{
+    "mcpServers": {
+        "cloudcc-cli": {
+            "command": "cc-mcp"
+        }
+    }
+}
+```
+
+说明：
+
+- `cloudcc-cli`：MCP 服务器标识，用于在工具中调用 CloudCC 相关能力
+- `command: "cc-mcp"`：实际执行的命令，通常由 `cloudcc-cli` 提供
+
+---
+
+## 6. 创建模板项目并本地运行
+
+### 6.1 使用 CLI 创建项目
+
+在终端中切换到你的开发目录（如 `Documents`）：
+
+```bash
+cd ~/Documents
+cc create project demo1
+```
+
+`demo1` 为示例项目名，可按需替换。
+
+### 6.2 安装依赖并启动
+
+1. 使用 VS Code 打开刚创建的项目目录
+2. 在 VS Code 中选择菜单：`终端 → 新建终端`
+3. 在项目根目录安装依赖：
+
+```bash
+npm i
+```
+
+4. 依赖安装完成后启动本地开发服务器：
+
+```bash
+npm run serve
+```
+
+5. 在浏览器访问：
+
+```text
+http://localhost:8080/
+```
+
+看到模板页面即表示前端本地环境搭建成功。
+
+---
+
+## 7. 获取并配置开发者密钥
+
+> 目的：将本地项目与指定 CloudCC
+> 环境（Org）关联，需使用具备「开发者权限」的账号在 CRM
+> 中获取密钥和安全标记，然后配置到项目根目录下的 `cloudcc-cli.config.js`。
+
+### 7.1 创建开发者账号
+
+前提：拥有系统管理员账号。
+
+1. 使用系统管理账号登录 CRM
+2. 点击右上角齿轮，进入后台设置
+3. 进入 `用户管理 → 新建` 创建新用户
+4. 为新用户分配**具有开发者权限**的简档：
+   - 路径：`管理用户 → 简档 → 对应简档 → 普通用户权限 → 代码管理`
+   - 确认「代码管理」权限已开启
+
+### 7.2 获取开发者密钥（CloudCCDev）
+
+1. 使用开发者账号登录 CRM
+2. 点击右上角齿轮，进入后台设置
+3. 路径：`用户及控制 → 安全性控制 → 连接的应用程序 → 新建`
+4. 填写：
+   - 连接的应用程序名称
+   - API 名称
+   - 联系人电子邮件
+5. 创建完成后，在详情页中找到 `CloudCC Dev`，点击后面的复制按钮，得到开发者密钥，妥善保管。
+
+### 7.3 获取安全标记（safetyMark）
+
+1. 使用同一开发者账号登录 CRM
+2. 路径：`常规 → 个人设置 → 重置我的安全标记`
+3. 点击后，安全标记会发送到用户邮箱，在邮箱中查收并记录。
+
+### 7.4 配置 `cloudcc-cli.config.js`
+
+在模板项目根目录找到并打开 `cloudcc-cli.config.js`，参考官方示例填写：
+
+```javascript
+module.exports = {
+    // 当前使用的环境标记
+    use: "dev",
+
+    // dev 环境密钥
+    dev: {
+        safetyMark: "必填，安全标记",
+        CloudCCDev: "必填，开发者密钥",
+        username: "选填，开发者用户名，会覆盖 CloudCCDev 中的 username",
+    },
+
+    // prod 环境密钥
+    prod: {
+        safetyMark: "必填，安全标记",
+        CloudCCDev: "必填，开发者密钥",
+        username: "选填，开发者用户名，会覆盖 CloudCCDev 中的 username",
+    },
+};
+```
+
+说明：
+
+- `use` 决定当前连接哪个环境（如 `"dev"` / `"prod"` 等）
+- 不要把真实密钥提交到 Git 仓库（应在 `.gitignore` 中忽略）
+
+---
+
+## 8. 私有云与特殊参数配置
+
+### 8.1 私有云标记
+
+在私有云场景下，需要额外增加 `version: "private"` 字段示意：
+
+```javascript
+module.exports = {
+    use: "dev",
+    dev: {
+        safetyMark: "必填，安全标记",
+        CloudCCDev: "必填，开发者密钥",
+        version: "必填，private",
+        username: "选填，开发者用户名，会覆盖 CloudCCDev 中的 username",
+    },
+    prod: {
+        safetyMark: "必填，安全标记",
+        CloudCCDev: "必填，开发者密钥",
+        version: "必填, private",
+        username: "选填，开发者用户名，会覆盖 CloudCCDev 中的 username",
+    },
+};
+```
+
+### 8.2 baseUrl 与网关前缀
+
+示例配置（精简自官方文档）：
+
+```javascript
+dev: {
+  // 服务访问地址：
+  // 国内默认：https://developer.apis.cloudcc.cn
+  // 海外默认：https://developer.apis.cloudcc.com
+  // 私有云：可在登录 CRM 后，右键 → 检查 → 控制台，执行 $CCDK.CCConfig.getBaseUrl()
+  baseUrl: "http://xxx",
+
+  // 组件进入后台后自动销毁时间（毫秒），如 10 分钟：10 * 60 * 1000
+  destroyTimeout: 600000,
+
+  // 开发者平台在网关配置的前缀名，注意 URL 不要以 / 结尾
+  devSvcDispatch: "/devconsole",
+
+  // api-service-svc 访问网关前缀地址
+  apiSvcPrefix: "/xxx",
+
+  // setup-svc 访问网关前缀地址
+  setupSvcPrefix: "/xxx"
+}
+```
+
+---
+
+## 9. 多环境配置示例
+
+`cloudcc-cli.config.js` 支持配置多个环境，通过 `use` 字段选择当前使用的环境：
+
+```javascript
+module.exports = {
+    // 使用 dev 环境密钥，与 dev 环境连接
+    use: "dev",
+
+    // dev 环境密钥
+    dev: {
+        safetyMark: "xxx",
+        CloudCCDev: "xxx",
+    },
+
+    // prod 环境密钥
+    prod: {
+        safetyMark: "xxx",
+        CloudCCDev: "xxx",
+    },
+};
+```
+
+建议：
+
+- 本地调试使用 `dev` 或测试环境
+- 合并上线前在 `uat` 或类似环境进行回归验证
+- 生产配置应仅在 CI/CD 或受控环境中可见，避免在开发机上长期保存生产密钥
+
+---
+
+## 10. 开发工具与代码规范补充
+
+### 10.1 推荐开发工具组合
+
+- 编辑器：VS Code（配合 CloudCC 扩展）
+- 包管理：npm（建议配置阿里源）
+- 版本控制：Git
+
+官方文档中的推荐插件示例：
+
+- `ESLint`：代码规范检查
+- `Vetur` / 对应 Vue 插件：Vue 语法高亮与提示
+- `GitLens`：Git 历史与责任人查看
+- `Live Server`：静态资源快速预览（如需）
+
+### 10.2 代码规范（简要）
+
+详细 JS/CSS/注释规范可参考官方文档「开发规范」小节，这里仅保留关键点：
+
+- 启用 ESLint 作为基础校验
+- 在项目根目录维护 `README.md`，记录每次发布版本与更新内容
+- Vue 组件中使用 `scoped` 样式或统一引入的样式变量文件，避免污染全局
+
+---
+
+## 11. 小结：环境搭建 Checklist
+
+在实际项目中，可使用以下清单快速自检：
+
+- [ ] 已安装 Node（推荐 v20.19.5）并通过 `node -v` 验证
+- [ ] npm 源已切换到 `https://registry.npmmirror.com`
+- [ ] 已全局安装 `cloudcc-cli` 并验证
+- [ ] 已安装 VS Code 与 CloudCC 插件（或已按官方指引配置 Cursor）
+- [ ] MCP 已配置 `cloudcc-cli → cc-mcp`
+- [ ] 已通过 `cc create project` 创建模板项目并成功 `npm i` + `npm run serve`
+- [ ] 已创建开发者账号并确认「代码管理」权限开启
+- [ ] 已获取开发者密钥与安全标记并正确配置 `cloudcc-cli.config.js`
+- [ ] 如为私有云，已配置 `version: "private"` 与正确的 `baseUrl`/网关前缀
+- [ ] 多环境（dev/prod/uat 等）配置与 `use` 字段已核对无误

package/src/project/docs/introduction.md

@@ -0,0 +1,3 @@
+# CloudCC Project 介绍
+
+cloudcc二开模版项目，用于在本地对二开代码进行管理。

package/src/recordType/create.js

@@ -0,0 +1,77 @@
+const chalk = require("chalk");
+const { getPackageJson } = require("../../utils/config");
+const { postClass } = require("../../utils/http");
+const newInfo = require("./newInfo");
+
+/**
+ * cc create recordType <projectPath> <encodedBodyJson>
+ *
+ * encodedBodyJson（encodeURI 编码前）：
+ * {
+ *   "objid": "202646FC67ACF24D39sG",
+ *   "name": "记录类型标签",
+ *   "apiCode": "unique_api_name"
+ * }
+ *
+ * 其余参数（简档列表、页面布局等）自动从 newInfo 接口取默认值。
+ *
+ * @param {string} projectPath
+ * @param {string} encodedBodyJson
+ * @param {boolean} isMcp
+ */
+async function create(projectPath = process.cwd(), encodedBodyJson, isMcp = false) {
+    if (!encodedBodyJson) {
+        throw new Error("Create Record Type Failed: encodedBodyJson is required");
+    }
+    const { objid, name, apiCode } = JSON.parse(decodeURI(encodedBodyJson));
+    if (!objid || !name || !apiCode) {
+        throw new Error("Create Record Type Failed: objid, name and apiCode are required");
+    }
+
+    // 从 newInfo 获取默认数据（简档列表、页面布局列表等）
+    const info = await newInfo(projectPath, objid, true);
+    const defaultLayoutId = info.layouts?.[0]?.id || "";
+    const pslist = Object.entries(info.profilemap).map(([profileid, profilename], idx) => ({
+        profileid,
+        visibleRecordtypes: info.profileRecordtypes?.[profileid] || "",
+        isActive: true,
+        isDefault: idx === 0,
+        layoutid: defaultLayoutId,
+        profile: { profilename }
+    }));
+
+    const body = {
+        objid,
+        obj: {
+            existsRectype: "",
+            description: "",
+            isenable: "",
+            name,
+            apiCode
+        },
+        existobj: "",
+        pslist
+    };
+
+    const config = await getPackageJson(projectPath);
+    if (!isMcp) {
+        console.error();
+        console.error(chalk.green("Creating record type, please wait..."));
+        console.error();
+    }
+    const res = await postClass(
+        config.setupSvc + "/api/recordType/saveRecordType",
+        body,
+        config.accessToken
+    );
+    if (res && res.result) {
+        if (!isMcp) {
+            console.error(chalk.green("Success! Record type created."));
+            console.error();
+        }
+        return res;
+    }
+    throw new Error("Create Record Type Failed: " + (res?.returnInfo || res?.message || "Unknown error"));
+}
+
+module.exports = create;

package/src/recordType/delete.js

@@ -0,0 +1,52 @@
+const chalk = require("chalk");
+const { getPackageJson } = require("../../utils/config");
+const { postClass } = require("../../utils/http");
+
+/**
+ * cc delete recordType <projectPath> <encodedBodyJson>
+ * 删除记录类型（删除前请先调用 validDelete 获取替换目标列表）
+ *
+ * encodedBodyJson（encodeURI 编码前）示例：
+ * {
+ *   "id": "2026667B898023FoKwCe",       // 待删除记录类型 ID
+ *   "objid": "202646FC67ACF24D39sG",    // 对象 ID
+ *   "replaceId": "2026A1C1DE314F24t6eZ" // 替换记录类型 ID，不替换则传空字符串 ""
+ * }
+ *
+ * @param {string} projectPath
+ * @param {string} encodedBodyJson
+ * @param {boolean} isMcp
+ */
+async function remove(projectPath = process.cwd(), encodedBodyJson, isMcp = false) {
+    if (!encodedBodyJson) {
+        throw new Error("Delete Record Type Failed: encodedBodyJson is required");
+    }
+    const body = JSON.parse(decodeURI(encodedBodyJson));
+    if (!body.id || !body.objid) {
+        throw new Error("Delete Record Type Failed: id and objid are required");
+    }
+    if (!("replaceId" in body)) {
+        throw new Error("Delete Record Type Failed: replaceId is required (pass empty string if no replacement)");
+    }
+    const config = await getPackageJson(projectPath);
+    if (!isMcp) {
+        console.error();
+        console.error(chalk.green(`Deleting record type (${body.id}), please wait...`));
+        console.error();
+    }
+    const res = await postClass(
+        config.setupSvc + "/api/recordType/deleteObj",
+        body,
+        config.accessToken
+    );
+    if (res && res.result) {
+        if (!isMcp) {
+            console.error(chalk.green("Success! Record type deleted."));
+            console.error();
+        }
+        return res;
+    }
+    throw new Error("Delete Record Type Failed: " + (res?.returnInfo || res?.message || "Unknown error"));
+}
+
+module.exports = remove;

package/src/recordType/doc.js

@@ -0,0 +1,36 @@
+/**
+ * recordType 文档统一入口
+ */
+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");
+}
+
+/**
+ * cc doc recordType <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 recordType 需要子命令：introduction 或 devguide");
+    }
+    if (key === "introduction") {
+        const content = readDocFile("introduction");
+        console.log(content);
+        return content;
+    }
+    if (key === "devguide") {
+        const content = readDocFile("devguide");
+        console.log(content);
+        return content;
+    }
+    throw new Error(`doc 不支持的子命令: ${subType}，请使用 introduction 或 devguide`);
+}
+
+module.exports = doc;

package/src/recordType/docs/devguide.md

@@ -0,0 +1,160 @@
+# CloudCC 记录类型操作指南
+
+---
+
+## 1. 入口与列表页
+
+进入路径：`对象管理 → 选择对象 → 记录类型` 标签页
+
+列表页展示：
+- **记录类型标签**：显示名称
+- **描述**
+- **是否启用**
+- **最后修改人**
+
+右上角操作按钮：**新建 / 排序 / 页面布局分配**
+
+```bash
+# 获取指定对象的记录类型列表
+cc getList recordType . <objid>
+```
+
+---
+
+## 2. 新建前查询初始信息
+
+新建前需先获取简档列表、现有记录类型列表、页面布局列表：
+
+```bash
+cc newInfo recordType . <objid>
+```
+
+返回结构：
+
+```json
+{
+  "existsRectypeList": [ { "id": "", "name": "--主--" } ],
+  "profilemap": { "<profileId>": "简档名称" },
+  "layouts": [ { "id": "<layoutId>", "name": "页面布局名称" } ],
+  "profileRecordtypes": { "<profileId>": "" },
+  "slist": []
+}
+```
+
+---
+
+## 3. 新建记录类型
+
+```bash
+cc create recordType . <encodedBodyJson>
+```
+
+原始 JSON（`encodeURI` 编码前）：
+
+```json
+{
+  "objid": "202646FC67ACF24D39sG",
+  "name": "记录类型标签",
+  "apiCode": "unique_api_name"
+}
+```
+
+> 其余参数（简档列表、页面布局等）由系统自动调用 `newInfo` 接口获取并使用默认值：默认**不启用**（`isenable: ""`）、不继承现有记录类型、使用第一个页面布局、所有简档均启用且第一个简档设为默认。
+
+| 字段       | 说明                                            |
+|------------|-------------------------------------------------|
+| `objid`    | 对象 ID                                         |
+| `name`     | 记录类型标签（显示名称）                        |
+| `apiCode`  | 唯一名称，创建后不可修改（对应 UI「唯一名称」） |
+
+---
+
+## 4. 编辑记录类型
+
+**Step 1：获取回显数据**
+
+```bash
+cc editInfo recordType . <encodedBodyJson>
+# encodedBodyJson: { "id": "<recordTypeId>", "objid": "<objid>" }
+```
+
+**Step 2：修改后保存（只可编辑以下四个字段）**
+
+| 可编辑字段    | 字段名        |
+|--------------|---------------|
+| 记录类型标签  | `name`        |
+| 描述          | `description` |
+| 唯一名称      | `apiCode`     |
+| 启用          | `isenable`    |
+
+```bash
+cc editSave recordType . <encodedBodyJson>
+# encodedBodyJson: 将 editInfo 返回的 data 对象修改目标字段后提交
+```
+
+---
+
+## 5. 删除记录类型
+
+**Step 1：删除前校验**（检测启用状态 + 获取可替换记录类型列表）
+
+```bash
+cc validDelete recordType . <encodedBodyJson>
+# encodedBodyJson: { "id": "<recordTypeId>", "objid": "<objid>" }
+```
+
+> **规则**：调用此命令时会先检测记录类型是否处于启用状态：
+> - 若当前为**启用**状态，命令将报错并提示先执行禁用操作，不会继续执行删除校验
+> - 若当前为**禁用**状态，则正常返回可替换记录类型列表
+>
+> 请先调用 `cc editSave` 将 `isenable` 设为 `"false"` 完成禁用，再重新执行此命令。
+
+返回：
+
+```json
+{
+  "obj": { "id": "2026667B898023FoKwCe", "name": "测试1" },
+  "recordtypes": [
+    { "id": "", "name": "--无--" },
+    { "id": "2026A1C1DE314F24t6eZ", "name": "测试2" }
+  ]
+}
+```
+
+**Step 2：执行删除**
+
+```bash
+cc delete recordType . <encodedBodyJson>
+# encodedBodyJson: { "id": "<recordTypeId>", "objid": "<objid>", "replaceId": "<replaceId>" }
+```
+
+| 字段        | 说明                                        |
+|-------------|---------------------------------------------|
+| `id`        | 待删除记录类型 ID                           |
+| `objid`     | 对象 ID                                     |
+| `replaceId` | 替换记录类型 ID；不替换时传空字符串 `""`    |
+
+> **注意**：删除后，原使用该记录类型的所有记录将替换为 `replaceId` 指定的记录类型。
+
+---
+
+## 6. 查看文档
+
+```bash
+cc doc recordType introduction   # 能力与适用场景说明
+cc doc recordType devguide        # 本操作指南
+```
+
+---
+
+## 7. API 参考
+
+| 操作         | 接口                                  | 关键参数                       |
+|--------------|---------------------------------------|--------------------------------|
+| 获取列表     | `POST /api/recordType/getRecordTypeList` | `objid`                     |
+| 新建初始信息 | `POST /api/recordType/newRecordType`  | `objid`                        |
+| 新建保存     | `POST /api/recordType/saveRecordType` | `objid`, `obj`, `pslist`       |
+| 编辑回显     | `POST /api/recordType/editRecordType` | `id`, `objid`                  |
+| 编辑保存     | `POST /api/recordType/editSave`       | 完整记录类型对象               |
+| 删除校验     | `POST /api/recordType/validDelete`    | `id`, `objid`                  |
+| 删除         | `POST /api/recordType/deleteObj`      | `id`, `objid`, `replaceId`     |