cloudcc-cli 2.3.1 → 2.3.3

package/src/classes/docs/devguide.md

@@ -0,0 +1,541 @@
+# CloudCC 自定义类开发指南
+
+> 本文档参考 CloudCC
+> 官方「自定义类」文档整理而成：[自定义类](https://help.cloudcc.cn/product03/zi-ding-yi-lei/)。\
+> 目标：指导开发者在 CloudCC 平台上编写 Java 自定义类，熟练使用
+> `CCService`、`CCObject`、`SendEmail`、`DevLogger`、`TimeUtil`
+> 等工具类，并理解类在触发器、定时作业、自定义组件中的调用方式。
+
+---
+
+## 0. 必须使用 CLI 管理本地类文件
+
+自定义类在本项目中的目录结构、`config.json`、主类中的 `// @SOURCE_CONTENT_START`
+… `// @SOURCE_CONTENT_END` 区域，均与 **cloudcc-cli**
+的创建、发布、拉取逻辑绑定。**必须通过下列命令**
+完成新建目录、与服务器同步、发布与删除；不要手工新建
+`classes/<类名>/`、不要复制粘贴整套类文件夹、不要私自篡改 `config.json` 里的
+`id` 或破坏版本字段，否则容易导致发布失败、拉取覆盖异常或与线上一致性不一致。
+
+**允许的做法**：在 CLI 已生成的主类 `*.java` 中，仅在上述 SOURCE
+标记之间编写与修改业务代码；其余与平台同步相关的操作一律走命令。
+
+执行命令前请确认：已完成 `cc doc project devguide`
+中的环境初始化，项目根目录配置可用且包含 `accessToken`。
+
+### 0.1 命令总览（以代码实现为准）
+
+```bash
+cc create classes <name>
+cc publish classes <name>
+cc pull classes <name>
+cc get classes [listQueryJson] [projectPath]
+cc detail classes <name>
+cc detail classes "" <id>
+cc pullList classes <id> <projectPath>
+cc delete classes <nameOrId> [projectPath]
+cc doc classes <introduction|devguide>
+```
+
+参数约定：
+
+- `name`：Java 类名，与 `classes/<name>/` 目录名一致。
+- `listQueryJson`：可选；列表查询条件的 JSON 经 `encodeURI(JSON.stringify(...))`
+  编码后传入。不传时使用默认分页参数。
+- `projectPath`：项目根路径，可选；不传则使用当前工作目录。
+- `id`：线上类 ID。`detail`
+  在仅查服务器时可将类名置空：`cc detail classes "" <id>`。`pullList` 用 ID
+  将线上类落到指定项目的 `classes/` 下。
+- `nameOrId`：本地目录名，或类 ID。若本地存在 `config.json` 且含
+  `id`，删除时会优先用其中的服务器 ID。
+
+### 0.2 命令说明摘要
+
+| 命令       | 作用                                                                                |
+| ---------- | ----------------------------------------------------------------------------------- |
+| `create`   | 在 `classes/<name>/` 生成主类、测试类、`config.json` 模板                           |
+| `publish`  | 将本地 SOURCE 区域源码提交到服务器；首次成功后会写回 `config.json` 的 `id`          |
+| `pull`     | 按本地 `config.json` 的 `id` 从服务器拉取源码，覆盖主类中 SOURCE 区域（需已发布过） |
+| `get`      | 查询线上类列表（JSON 输出）                                                         |
+| `detail`   | 按类名优先读本地；或仅按 `id` 读服务器详情                                          |
+| `pullList` | 按类 `id` 将线上类拉取到指定 `projectPath` 下的 `classes/<类名>/`                   |
+| `delete`   | 调用接口删除服务器上的类；参数可为本地类名或类 ID                                   |
+| `doc`      | 输出 `introduction` 或 `devguide`（`devguide` 含附录 SDK 速查）                     |
+
+### 0.3 推荐操作顺序
+
+```bash
+# 1) 查看线上已有类（可选，避免重名或确认 ID）
+cc get classes
+
+# 2) 新建类（仅通过 create 生成目录与文件）
+cc create classes MyClass
+
+# 3) 编辑 classes/MyClass/MyClass.java 中 SOURCE 区域后发布
+cc publish classes MyClass
+
+# 4) 需要与服务器对齐时，拉取覆盖本地 SOURCE 区域
+cc pull classes MyClass
+
+# 5) 按已知线上类 ID 拉到指定项目（迁移、批量）
+cc pullList classes <线上类ID> <projectPath>
+
+# 6) 不再使用时删除线上类
+cc delete classes MyClass
+```
+
+### 0.4 文档子命令
+
+```bash
+cc doc classes introduction
+cc doc classes devguide
+```
+
+仅支持 `introduction` 与 `devguide`，其他子命令会报错。
+
+---
+
+## 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
+
+- [ ] 类目录与平台同步仅通过 `cc create` / `cc pull` / `cc pullList` /
+      `cc publish` / `cc delete` 等命令操作，不手工造目录或改 `config.json` 的
+      `id`
+- [ ] 类名、方法名与调用方（按钮/触发器/组件/定时作业）约定一致
+- [ ] 构造函数正确接收 `UserInfo` 并实例化 `CCService` 等依赖
+- [ ] 所有 `CCService` 操作（`insert`/`update`/`delete`/`cquery`）使用正确的对象
+      API 名称和字段 API 名称（自定义字段加 `__c`）
+- [ ] 访问共享表时，表达式中的字段未错误地添加 `__c` 后缀
+- [ ] 涉及时间处理的逻辑统一使用 `TimeUtil`，避免时区问题
+- [ ] 异常统一捕获并按需抛出，同时使用 `DevLogger` 记录关键错误信息
+- [ ] 使用 `SendEmail` 时确认收件地址与内容来源安全可靠
+- [ ] 使用 `PageClsInvoker` 跨类调用时，`argType` 与 `argValue` 类型匹配
+- [ ] 对外暴露的方法返回结构（如
+      `JSONObject`）与前端/调用方约定一致，字段清晰、语义明确

package/src/classes/get.js

@@ -1,9 +1,16 @@
 const { getPackageJson } = require("../../utils/config")
 const { postClass } = require("../../utils/http")
 
-async function get(arg, path, isMcp = false) {
+/**
+ * cc get classes [listQueryJson] [projectPath]
+ * @param {string[]} argvs [action, type, listQuery?, projectPath?, isMcp?]
+ */
+async function get(argvs) {
+    const arg = argvs[2]
+    const projectPath = argvs[3]
+    const isMcp = Boolean(argvs[4])
     let body = arg != null && arg != '' ? JSON.parse(decodeURI(arg)) : { shownum: "2000", showpage: "1", fid: "", sname: '', rptcond: '', rptorder: '' }
-    let config = await getPackageJson(path);
+    let config = await getPackageJson(projectPath);
     let res = await postClass(config.setupSvc + "/api/ccfag/list", body, config.accessToken)
     if (res.result) {
         const simpleList = (res.data.list || []).map(item => ({

package/src/classes/index.js

@@ -7,8 +7,9 @@ cc.pullList = require("./pullList")
 cc.detail = require("./detail")
 cc.doc = require("./doc")
 cc.delete = require("./delete")
+
 function Classes(action, argvs) {
-  cc[action](argvs[2], argvs[3])
+  cc[action](argvs)
 }
 
 module.exports = Classes;

package/src/classes/publish.js

@@ -9,7 +9,12 @@ const { javaContentRegular } = require("../../utils/utils")
 
 const { getPackageJson } = require("../../utils/config")
 
-async function publish(name) {
+/**
+ * cc publish classes <name>
+ * @param {string[]} argvs [action, type, name, ...]
+ */
+async function publish(argvs) {
+  const name = argvs[2]
   let res = await checkUpdate();
   if (!res) {
     console.error();

package/src/classes/pull.js

@@ -8,7 +8,12 @@ const { javaContentRegular } = require("../../utils/utils")
 const { getPackageJson } = require("../../utils/config")
 const { postClass } = require("../../utils/http")
 
-async function pull(name) {
+/**
+ * cc pull classes <name>
+ * @param {string[]} argvs [action, type, name, ...]
+ */
+async function pull(argvs) {
+    const name = argvs[2]
     let res = await checkUpdate();
     if (!res) {
         console.error();

package/src/classes/pullList.js

@@ -4,10 +4,13 @@ const { getPackageJson } = require("../../utils/config");
 const { postClass } = require("../../utils/http");
 
 /**
- * Batch pull class details and generate local files
- * @param class id
+ * cc pullList classes <id> <projectPath>
+ * @param {string[]} argvs [action, type, id, projectPath?, isMcp?]
  */
-async function pullList(id, url, isMcp = false) {
+async function pullList(argvs) {
+    const id = argvs[2]
+    const url = argvs[3]
+    const isMcp = Boolean(argvs[4])
     let config = await getPackageJson(url);
     const body = { id };
     const res = await postClass(config.setupSvc + "/api/ccfag/detail", body, config.accessToken);

package/src/config/doc.js

@@ -0,0 +1,31 @@
+/**
+ * config 文档入口：正文在 `docs/` 目录。
+ */
+const fs = require("fs");
+const path = require("path");
+
+const DOCS_DIR = path.join(__dirname, "docs");
+
+function getDevGuideDoc() {
+    return fs.readFileSync(path.join(DOCS_DIR, "devguide.md"), "utf8");
+}
+
+/**
+ * cc doc config devguide
+ * @param {string[]} argvs [doc, config, devguide, ...]
+ */
+function doc(argvs) {
+    const subType = argvs[2];
+    const key = String(subType || "").trim().toLowerCase();
+    if (!key) {
+        throw new Error("cc doc config 需要子命令：devguide");
+    }
+    if (key === "devguide") {
+        const content = getDevGuideDoc();
+        console.log(content);
+        return content;
+    }
+    throw new Error(`doc 不支持的子命令: ${subType}，请使用 devguide`);
+}
+
+module.exports = doc;