cloudcc-cli 2.2.5 → 2.2.7

package/src/application/create.js

@@ -0,0 +1,114 @@
+const { postClass } = require("../../utils/http")
+const { getPackageJson } = require("../../utils/config");
+const briefGet = require("../brief/get");
+const chalk = require('chalk')
+
+/**
+ * 创建应用（Application）
+ * @param {Array} argvs - 命令行参数数组
+ * @returns {Promise<Object>} 创建结果
+ */
+async function create(argvs) {
+    try {
+        // 命令行参数格式：cc create application <path> <p1> <p2> [duel1]
+        // argvs: ['application', 'create', path, p1, p2, duel1]
+        let path = argvs[2];
+        let p1 = argvs[3];  // 应用名称
+        let p2 = argvs[4];  // 应用代码
+        let duel1 = argvs[5];  // 菜单ID，多个时用逗号分隔，可选，默认为 "acf000001"
+
+        // 验证必需参数
+        if (!p1 || !p2) {
+            console.error();
+            console.error(chalk.red('Error: 缺少必需参数'));
+            console.error('用法: cc create application <path> <p1> <p2> [duel1]');
+            console.error('  path: 项目路径');
+            console.error('  p1: 应用名称');
+            console.error('  p2: 应用代码');
+            console.error('  duel1: 菜单ID（可选，多个时用逗号分隔，默认: acf000001）');
+            console.error();
+            throw new Error('缺少必需参数: p1 和 p2');
+        }
+
+        // 处理 duel1，确保始终包含 acf000001
+        const REQUIRED_MENU_ID = "acf000001";
+        if (!duel1) {
+            // 如果没有传入，使用默认值
+            duel1 = REQUIRED_MENU_ID;
+        } else {
+            // 如果传入了，确保 acf000001 在列表中
+            const menuIds = duel1.split(',').map(id => id.trim()).filter(id => id);
+            if (!menuIds.includes(REQUIRED_MENU_ID)) {
+                // 如果列表中没有 acf000001，添加到列表开头
+                menuIds.unshift(REQUIRED_MENU_ID);
+            }
+            duel1 = menuIds.join(',');
+        }
+
+        let config = await getPackageJson(path);
+
+        // 从 brief/get 获取角色ID列表（仍使用原始 argv 参数： path 位于 argvs[2]）
+        // 注意：brief/get 的接口返回是 { success, data } 的格式
+        let briefData = await briefGet(argvs);
+
+        if (!briefData.success) {
+            console.error("获取角色列表失败:", briefData.message);
+            throw new Error("获取角色列表失败");
+        }
+
+        // 提取所有角色的 ID 列表，用逗号连接
+        const profileIdList = briefData.data.map(profile => profile.id);
+        const p12 = profileIdList.join(',');
+
+        // 构建请求体，使用用户提供的参数结构
+        const requestBody = {
+            "visited_0": "1",
+            "visited_1": "1",
+            "setupid": "TabSet",
+            "apptype": "app",
+            "p1": p1,
+            "p2": p2,
+            "p3": "",
+            "navigationStyle": "1",
+            "jump": "1",
+            "p4": "",
+            "appstyle": 21,
+            "p8": "home",
+            "duel1": duel1,
+            "visited_2": "1",
+            "visited_3": "1",
+            "p12": p12
+        };
+
+        // 显示创建进度
+        console.error();
+        console.error(chalk.green('Creating application, please wait...'));
+        console.error();
+
+        // 发送请求到服务器
+        const result = await postClass(
+            config.setupSvc + "/api/appProgram/tabSetDone",
+            requestBody,
+            config.accessToken
+        );
+
+        // API 返回结构中, result 字段决定调用是否成功
+        if (result && result.result) {
+            console.error();
+            console.error(chalk.green('Success！'));
+            console.error();
+            return result;
+        } else {
+            const msg = result && result.returnInfo ? result.returnInfo : 'Unknown error';
+            console.error();
+            console.error(chalk.red('Error：' + msg));
+            throw new Error('Create Application Failed: ' + msg);
+        }
+    } catch (error) {
+        console.error();
+        console.error(chalk.red("应用创建失败:"), error);
+        throw error;
+    }
+}
+
+module.exports = create;

package/src/application/get.js

@@ -0,0 +1,13 @@
+const { postClass } = require("../../utils/http")
+const { getPackageJson } = require("../../utils/config")
+
+async function get(argvs, isMcp = false) {
+    // TODO: 实现获取应用列表的功能
+    let res = [];
+    if (!isMcp) {
+        console.log(JSON.stringify(res));
+    }
+    return res
+}
+
+module.exports = get;

package/src/application/index.js

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

package/src/classes/doc.js

@@ -0,0 +1,486 @@
+/**
+ * classes 文档统一入口（合并自 prompt.js + classEditor.js）
+ */
+const fs = require("fs");
+const path = require("path");
+
+function generateFullMarkdownDoc() {
+    const lines = [
+        '# CloudCC 自定义类开发指南',
+        '',
+        '> 本文档参考 CloudCC 官方「自定义类」文档整理而成：[自定义类](https://help.cloudcc.cn/product03/zi-ding-yi-lei/)。  ',
+        '> 目标：指导开发者在 CloudCC 平台上编写 Java 自定义类，熟练使用 `CCService`、`CCObject`、`SendEmail`、`DevLogger`、`TimeUtil` 等工具类，并理解类在触发器、定时作业、自定义组件中的调用方式。',
+        '',
+        '---',
+        '',
+        '## 1. 概念与使用场景',
+        '',
+        '### 1.1 什么是自定义类',
+        '',
+        '- 自定义类本质上是运行在 CloudCC 平台上的 Java 类。  ',
+        '- 可被以下模块调用：',
+        '  - 自定义按钮',
+        '  - 触发器',
+        '  - 定时类 / 定时作业',
+        '  - 自定义组件（通过 CCDK 请求自定义类）',
+        '- 典型用途：',
+        '  - 封装复杂业务逻辑',
+        '  - 查询 / 写入对象数据',
+        '  - 调用自定义设置、发送邮件、记录开发日志',
+        '',
+        '**注意**：调用 `CCService` 的方法时，需要对异常进行显式抛出或捕获。',
+        '',
+        '### 1.2 入口：进入类开发页面',
+        '',
+        '1. 登录 CloudCC 系统  ',
+        '2. 点击右上角头像，选择「开发者平台」（仅对管理员简档用户开放）  ',
+        '3. 左侧菜单：`扩展 → 类`，进入类开发页面',
+        '',
+        '---',
+        '',
+        '## 2. 示例：查询客户对象数据（AccountClass）',
+        '',
+        '下面是一个官方示例类：查询客户对象数据并返回 JSON。',
+        '',
+        '```java',
+        'import net.sf.json.JSONObject;',
+        'import net.sf.json.JSONArray;',
+        'import net.sf.json.JSON;',
+        '',
+        '/**',
+        ' * author：*** on 2022-10-12',
+        ' * 客户类',
+        ' */',
+        'public class AccountClass {',
+        '    private CCService cs;',
+        '    private UserInfo userInfo;',
+        '',
+        '    public AccountClass(UserInfo userInfo) {',
+        '        this.userInfo = userInfo;',
+        '        cs = new CCService(userInfo);',
+        '    }',
+        '',
+        '    public JSONObject selectAccount() throws Exception {',
+        '        JSONObject rtninfo = new JSONObject(); // 返回结果',
+        '        JSONArray dataList = new JSONArray();  // 数据列表',
+        '        boolean flag = false;',
+        '        try {',
+        '            // 查询客户对象数据',
+        '            String sql = "select name, leixing, fenji, hangye from Account where is_deleted=\'0\' ";',
+        '            List<CCObject> accountList = cs.cqlQuery("Account", sql);',
+        '',
+        '            for (int i = 0; i < accountList.size(); i++) {',
+        '                String name = accountList.get(i).get("name") == null ? "" : accountList.get(i).get("name").toString();',
+        '                String type = accountList.get(i).get("leixing") == null ? "" : accountList.get(i).get("leixing").toString();',
+        '                String grade = accountList.get(i).get("fenji") == null ? "0" : accountList.get(i).get("fenji").toString();',
+        '                String industry = accountList.get(i).get("hangye") == null ? "0" : accountList.get(i).get("hangye").toString();',
+        '',
+        '                JSONObject data = new JSONObject();',
+        '                data.put("name", name);',
+        '                data.put("type", type);',
+        '                data.put("grade", grade);',
+        '                data.put("industry", industry);',
+        '                data.put("no", (i + 1) + ""); // 序号',
+        '                dataList.add(data);',
+        '            }',
+        '            flag = true;',
+        '        } catch (Exception e) {',
+        '            throw e;',
+        '        }',
+        '        rtninfo.put("status", flag);',
+        '        rtninfo.put("data", dataList.toString());',
+        '        return rtninfo;',
+        '    }',
+        '}',
+        '```',
+        '',
+        '要点：',
+        '- 构造函数接收 `UserInfo`，通过它实例化 `CCService`。  ',
+        '- 查询结果使用 `CCObject` 列表封装，再转为 `JSONObject`/`JSONArray` 返回。  ',
+        '- 方法签名抛出 `Exception`，调用方需要处理。',
+        '',
+        '---',
+        '',
+        '## 3. CCService：对象数据读写核心',
+        '',
+        '> `CCService` 是操作 CloudCC 对象（类似 ORM）的核心服务类，支持增删改查、自定义设置等。',
+        '',
+        '### 3.1 在类中实例化 CCService',
+        '',
+        '通用写法：',
+        '',
+        '```java',
+        'public class DemoClass {',
+        '    private CCService cs;',
+        '    private UserInfo userInfo;',
+        '',
+        '    public DemoClass(UserInfo userInfo) {',
+        '        this.userInfo = userInfo;',
+        '        this.cs = new CCService(userInfo);',
+        '    }',
+        '}',
+        '```',
+        '',
+        '在触发器中则通常不需要手动实例化，可直接使用平台提供的 `cs`（见触发器指南）。',
+        '',
+        '### 3.2 新增记录：insert',
+        '',
+        '1. 通过 `CCObject` 构造要插入的记录  ',
+        '2. 调用 `cs.insert(对象)` 持久化到数据库',
+        '',
+        '```java',
+        '// 构造一个数据对象，传入对象 API 名称',
+        'CCObject opp = new CCObject("Opportunity");',
+        '',
+        '// 给 CCObject 赋值，key 为字段 API 名称',
+        'opp.put("name", "新建机会");',
+        'opp.put("jine__c", 10000); // 示例：金额字段',
+        '',
+        '// 插入数据库',
+        'cs.insert(opp);',
+        '```',
+        '',
+        '**注意**：ID、自动编号、创建人、创建时间等系统字段不需要也不应该手动赋值。',
+        '',
+        '### 3.3 查询记录：cquery',
+        '',
+        '`cquery` 提供多种重载，用于按条件和排序查询数据。',
+        '',
+        '- 返回对象全部记录：',
+        '',
+        '```java',
+        'List<CCObject> opps = cs.cquery("Opportunity");',
+        '```',
+        '',
+        '- 按条件查询（where 表达式）：',
+        '',
+        '```java',
+        'List<CCObject> opps = cs.cquery(',
+        '    "Opportunity",',
+        '    "khmc__c = \'" + record_new.get("id") + "\'"',
+        ');',
+        '```',
+        '',
+        '- 按条件 + 排序：',
+        '',
+        '```java',
+        'List<CCObject> opps = cs.cquery(',
+        '    "Opportunity",',
+        '    "khmc__c = \'" + record_new.get("id") + "\'",',
+        '    "jine__c desc"',
+        ');',
+        '```',
+        '',
+        '**注意**：条件与排序中的自定义字段 API 名称要加 `__c` 后缀。',
+        '',
+        '### 3.4 修改记录：update',
+        '',
+        '```java',
+        '// 先查询到目标记录',
+        'List<CCObject> list = cs.cquery("Opportunity", "id = \'" + record_id + "\'");',
+        'if (!list.isEmpty()) {',
+        '    CCObject opp = list.get(0);',
+        '    opp.put("name", "修改后的机会名称");',
+        '    cs.update(opp);',
+        '}',
+        '```',
+        '',
+        '### 3.5 删除记录：delete',
+        '',
+        '```java',
+        'List<CCObject> list = cs.cquery("Opportunity", "id = \'" + record_id + "\'");',
+        'if (!list.isEmpty()) {',
+        '    CCObject opp = list.get(0);',
+        '    cs.delete(opp);',
+        '}',
+        '```',
+        '',
+        '### 3.6 操作共享表',
+        '',
+        '#### 查询共享表',
+        '',
+        '```java',
+        '// isDataObject 传 false，表示查询共享表',
+        'List<CCObject> shares = cs.cquery(',
+        '    "Opportunity",',
+        '    "userid = \'" + userId + "\'",',
+        '    false',
+        ');',
+        '```',
+        '',
+        '#### 删除共享表记录',
+        '',
+        '```java',
+        'cs.deleteShareObjectBySql("Opportunity", "userid = \'" + userId + "\'");',
+        '```',
+        '',
+        '**注意**：共享表中表达式里的字段 **不需要加 `__c` 后缀**。',
+        '',
+        '### 3.7 自定义设置（CustomSetting）',
+        '',
+        '#### 列表类型自定义设置（List）',
+        '',
+        '- 返回某个 API 名称下的全部数据：',
+        '',
+        '```java',
+        'Map listSettings = cs.getListCustomSetting("MyListSettingApiName");',
+        '```',
+        '',
+        '- 返回指定 `Name` 的单条数据：',
+        '',
+        '```java',
+        'Map singleSetting = cs.getListCustomSetting("MyListSettingApiName", "SomeName");',
+        '```',
+        '',
+        '#### 层次结构类型自定义设置（Hierarchy）',
+        '',
+        '```java',
+        '// id 为简档 ID 或用户 ID',
+        'Map hiSetting = cs.getCustomSetting("MyHierarchySettingApiName", profileOrUserId);',
+        '```',
+        '',
+        '---',
+        '',
+        '## 4. 常用工具类',
+        '',
+        '### 4.1 SendEmail：发送邮件',
+        '',
+        '```java',
+        'SendEmail sendEmail = new SendEmail(userInfo);',
+        'sendEmail.sendMailFromSystem(',
+        '    new String[]{"to@example.com"},     // 收件人',
+        '    new String[]{"cc@example.com"},     // 抄送',
+        '    new String[]{"bcc@example.com"},    // 密送',
+        '    "邮件主题",',
+        '    "邮件内容",',
+        '    true                                // 是否纯文本',
+        ');',
+        '```',
+        '',
+        '### 4.2 DevLogger：开发日志',
+        '',
+        '> 用于在自定义类中记录开发日志，便于排查问题。',
+        '',
+        '```java',
+        '// 初始化日志类',
+        'DevLogger cclogger = new DevLogger(userInfo);',
+        '',
+        '// 打印 info 级别日志',
+        'cclogger.devLogInfo("这是 info 日志");',
+        '',
+        '// 打印 error 级别日志',
+        'cclogger.devLogError("这是 error 日志");',
+        '',
+        '// 打印异常堆栈',
+        'try {',
+        '    // 业务逻辑',
+        '} catch (Exception e) {',
+        '    cclogger.devLogError("发生异常", e);',
+        '    throw e;',
+        '}',
+        '```',
+        '',
+        '### 4.3 TimeUtil：多时区日期时间',
+        '',
+        '> 为保证跨时区时间的准确性，推荐使用 `TimeUtil` 获取当前时间与时间格式化工具。',
+        '',
+        '- 获取当前时间（根据用户时区）：',
+        '',
+        '```java',
+        'TpSysTask task = new TpSysTask();',
+        'task.setBeginTime(TimeUtil.getNowDate(userInfo));',
+        '```',
+        '',
+        '- 使用 `SimpleDateFormat` 时设置时区：',
+        '',
+        '```java',
+        'SimpleDateFormat myDateFormat = new SimpleDateFormat("yyyy-MM-dd");',
+        'myDateFormat.setTimeZone(TimeUtil.getUserTimeZone(userInfo));',
+        '```',
+        '',
+        '- 使用工具方法直接获取带时区的 `SimpleDateFormat`：',
+        '',
+        '```java',
+        'SimpleDateFormat myDateFormat =',
+        '    TimeUtil.getSimpleDateFormat("yyyy-MM-dd", userInfo);',
+        '```',
+        '',
+        '- 使用 `Calendar` 时设置时区：',
+        '',
+        '```java',
+        '// 方式一',
+        'Calendar cal = Calendar.getInstance(TimeUtil.getUserTimeZone(userInfo));',
+        '',
+        '// 方式二（推荐使用工具方法）',
+        'Calendar cal2 = TimeUtil.getCalendar(userInfo);',
+        '```',
+        '',
+        '### 4.4 CCObject：数据载体',
+        '',
+        '```java',
+        '// 构造一个数据对象，传入对象 API 名称',
+        'CCObject opp = new CCObject("Opportunity");',
+        '',
+        '// 构造一个共享表对象',
+        'CCObject oppshare = new CCObject("Opportunity", CCObject.IS_SHARED);',
+        '',
+        '// 赋值',
+        'opp.put("name", "value");',
+        '```',
+        '',
+        '---',
+        '',
+        '## 5. 自定义类与其他模块的配合',
+        '',
+        '### 5.1 触发器中使用类',
+        '',
+        '- 触发器可以直接调用自定义类中的方法，也可以直接使用 `CCService`。  ',
+        '- 触发器由 CloudCC 平台动态编译，调用写法与普通 Java 方法调用类似。',
+        '- 典型模式：',
+        '  - 在触发器中只做入口和参数准备',
+        '  - 将复杂逻辑委托给自定义类方法',
+        '',
+        '（触发器具体语法与最佳实践详见 `custom-trigger-dev.md`。）',
+        '',
+        '### 5.2 自定义类调用其他自定义类（PageClsInvoker）',
+        '',
+        '> 当需要在一个自定义类中调用另一个自定义类的方法时，可使用 `PageClsInvoker` 的 `invoker` 方法。',
+        '',
+        '`invoker` 有两个常用重载：',
+        '',
+        '```java',
+        'Object invoker(String className, String method, List<Map> conlist, List<Map> arglist);',
+        'Object invoker(String className, String method, List<Map> conlist, Map map);',
+        '```',
+        '',
+        '参数说明：',
+        '- `className`：目标自定义类名称',
+        '- `method`：要调用的方法名',
+        '- `conlist`：构造器参数列表（可为 `null`）',
+        '  - 每个 Map 包含：',
+        '    - `argType`：参数类型',
+        '    - `argValue`：参数值',
+        '- `arglist` / `map`：方法参数',
+        '  - 同样包含 `argType` 和 `argValue`',
+        '',
+        '#### 5.2.1 使用 Map 作为方法参数',
+        '',
+        '目标类：',
+        '',
+        '```java',
+        'public class Hello {',
+        '',
+        '    public Hello() {}',
+        '',
+        '    public Hello(UserInfo userInfo) {',
+        '        System.out.print("测试");',
+        '    }',
+        '',
+        '    public void test5(Map map) throws Exception {',
+        '        System.out.print("获取 map 中的值" + map.get("name"));',
+        '    }',
+        '}',
+        '```',
+        '',
+        '调用方：',
+        '',
+        '```java',
+        'List<Map> conlist = new ArrayList<Map>();',
+        '',
+        'Map c = new HashMap();',
+        'c.put("argType", UserInfo.class);',
+        'c.put("argValue", userInfo);',
+        'conlist.add(c);',
+        '',
+        'Map m = new HashMap();',
+        'm.put("name", "Alex");',
+        '',
+        'new PageClsInvoker(userInfo).invoker("Hello", "test5", conlist, m);',
+        '```',
+        '',
+        '#### 5.2.2 使用 List<Map> 作为方法参数列表',
+        '',
+        '目标类：',
+        '',
+        '```java',
+        'public class Hello {',
+        '',
+        '    public Hello() {}',
+        '',
+        '    public ServiceResult test3(UserInfo userInfo, String leadName) throws Exception {',
+        '        CCService cs = new CCService((UserInfo) userInfo);',
+        '        CCObject co = new CCObject("Lead");',
+        '        co.put("name", leadName);',
+        '        ServiceResult sr = cs.insert(co);',
+        '        return sr;',
+        '    }',
+        '}',
+        '```',
+        '',
+        '调用方：',
+        '',
+        '```java',
+        'List<Map> arglist = new ArrayList<Map>();',
+        '',
+        'Map u = new HashMap();',
+        'u.put("argType", UserInfo.class);',
+        'u.put("argValue", userInfo);',
+        'arglist.add(u);',
+        '',
+        'Map n = new HashMap();',
+        'n.put("argType", String.class);',
+        'n.put("argValue", "Alex");',
+        'arglist.add(n);',
+        '',
+        'new PageClsInvoker(userInfo).invoker("Hello", "test3", null, arglist);',
+        '```',
+        '',
+        '---',
+        '',
+        '## 6. 自定义类开发 Checklist',
+        '',
+        '- [ ] 类名、方法名与调用方（按钮/触发器/组件/定时作业）约定一致  ',
+        '- [ ] 构造函数正确接收 `UserInfo` 并实例化 `CCService` 等依赖  ',
+        '- [ ] 所有 `CCService` 操作（`insert`/`update`/`delete`/`cquery`）使用正确的对象 API 名称和字段 API 名称（自定义字段加 `__c`）  ',
+        '- [ ] 访问共享表时，表达式中的字段未错误地添加 `__c` 后缀  ',
+        '- [ ] 涉及时间处理的逻辑统一使用 `TimeUtil`，避免时区问题  ',
+        '- [ ] 异常统一捕获并按需抛出，同时使用 `DevLogger` 记录关键错误信息  ',
+        '- [ ] 使用 `SendEmail` 时确认收件地址与内容来源安全可靠  ',
+        '- [ ] 使用 `PageClsInvoker` 跨类调用时，`argType` 与 `argValue` 类型匹配  ',
+        '- [ ] 对外暴露的方法返回结构（如 `JSONObject`）与前端/调用方约定一致，字段清晰、语义明确  ',
+    ];
+
+    const base = lines.join("\n");
+    const sdkPath = path.join(__dirname, "..", "api", "backend-sdk-java.md");
+    let sdkContent = "";
+    try {
+        sdkContent = fs.readFileSync(sdkPath, "utf8");
+    } catch (e) {
+        sdkContent = `# CloudCC 后端 SDK（Java）使用指南\n\n（未找到文件：${sdkPath}）\n`;
+    }
+
+    return [
+        base,
+        "",
+        "---",
+        "",
+        "## 附录：后端 SDK（Java）速查",
+        "",
+        "> 来源：`src/api/backend-sdk-java.md`",
+        "",
+        sdkContent.trim(),
+        "",
+    ].join("\n");
+}
+
+function doc() {
+    const content = generateFullMarkdownDoc();
+    console.log(content);
+    return content;
+}
+
+// 兼容旧调用方：统一指向同一个方法（仍返回全量文档）
+doc.getClassEditorDoc = doc;
+doc.getEditGuide = doc;
+
+module.exports = doc;

package/src/classes/index.js

@@ -5,6 +5,7 @@ cc.pull = require("./pull")
 cc.get = require("./get")
 cc.pullList = require("./pullList")
 cc.detail = require("./detail")
+cc.doc = require("./doc")
 function Classes(action, argvs) {
   cc[action](argvs[2], argvs[3])
 }