cloudcc-cli 2.2.6 → 2.2.7

package/src/api/backend-sdk-java.md

@@ -0,0 +1,427 @@
+# CloudCC 后端 SDK（Java）使用指南
+
+> 本文档参考 CloudCC 官方「后端 SDK 参考」整理而成：[后端SDK参考](https://help.cloudcc.cn/product03/fu-wu-duan-sdkcan-kao-java/)。  
+> 目标：为自定义类、触发器、定时类中的 Java 开发，提供 `CCObject`、`UserInfo`、`CCService`、`SendEmail`、`DevLogger`、`TimeUtil` 等核心 API 的速查说明。
+
+---
+
+## 1. CCObject：CloudCC 对象封装
+
+### 1.1 类说明
+
+- 继承自 `java.util.HashMap`：`com.g3cloud.platform.publik.CCObject`  
+- 用于承载某个对象（如 `Account`、`Contact`）的一条记录或共享表记录。
+
+### 1.2 构造函数
+
+```java
+public CCObject() {}
+```
+
+```java
+public CCObject(String ccobj)
+```
+
+| 参数      | 类型     | 是否必填 | 说明         |
+| --------- | -------- | -------- | ------------ |
+| `ccobj`   | `String` | 是       | 对象 API 名称 |
+
+```java
+public CCObject(String ccobj, String isShared)
+```
+
+| 参数        | 类型     | 是否必填 | 说明                                      |
+| ----------- | -------- | -------- | ----------------------------------------- |
+| `ccobj`     | `String` | 是       | 对象 API 名称                             |
+| `isShared`  | `String` | 是       | 共享标识，建议使用 `CCObject.IS_SHARED`   |
+
+### 1.3 常量字段
+
+| 修饰符和类型                 | 字段           | 默认值         | 说明      |
+| ---------------------------- | -------------- | -------------- | --------- |
+| `public static final String` | `OBJECT_API`   | `CCObjectAPI`  | 对象 API  |
+| `public static final String` | `IS_SHARED`    | `isShared`     | 共享对象标识 |
+
+### 1.4 常用方法
+
+#### `getObjectApiName()`
+
+```java
+public String getObjectApiName()
+```
+
+返回当前 `CCObject` 对应的对象 API 名称。
+
+#### `put(String apiName, String value)`
+
+```java
+public String put(String apiName, String value)
+```
+
+| 参数        | 类型     | 是否必填 | 说明              |
+| ----------- | -------- | -------- | ----------------- |
+| `apiName`   | `String` | 是       | 字段 API 名称      |
+| `value`     | `String` | 是       | 字段值（字符串形式） |
+
+示例：
+
+```java
+CCObject contact = new CCObject("Contact");
+contact.put("email", "hello@cloudcc.com");
+```
+
+---
+
+## 2. UserInfo：当前用户信息
+
+类：`com.g3cloud.common.UserInfo`（实现 `java.io.Serializable`）
+
+### 2.1 常用方法
+
+```java
+public String getUserId()
+public String getOrgId()
+public String getRoleId()
+```
+
+- `getUserId()`：当前用户 ID  
+- `getOrgId()`：当前组织 ID  
+- `getRoleId()`：当前角色 ID  
+
+在自定义类构造函数或方法中通常作为参数传入，用于实例化 `CCService`、`DevLogger` 等。
+
+---
+
+## 3. CCService：对象操作核心工具类
+
+类：`com.g3cloud.platform.publik.CCService`
+
+### 3.1 构造函数
+
+```java
+public CCService(UserInfo userInfo)
+```
+
+| 参数        | 类型       | 是否必填 | 说明     |
+| ----------- | ---------- | -------- | -------- |
+| `userInfo`  | `UserInfo` | 是       | 当前用户对象 |
+
+在自定义类中常见用法：
+
+```java
+private CCService cs;
+private UserInfo userInfo;
+
+public MyClass(UserInfo userInfo) {
+    this.userInfo = userInfo;
+    this.cs = new CCService(userInfo);
+}
+```
+
+### 3.2 新增记录：`insert`
+
+```java
+public ServiceResult insert(CCObject ccobj) throws BusiException
+```
+
+| 参数     | 类型        | 是否必填 | 说明    |
+| -------- | ----------- | -------- | ------- |
+| `ccobj`  | `CCObject`  | 是       | CC 对象 |
+
+示例：
+
+```java
+CCObject contact = new CCObject("Contact");
+contact.put("email", "hello@cloudcc.com");
+cs.insert(contact);
+```
+
+### 3.3 查询记录：`cquery`
+
+```java
+public List<CCObject> cquery(String apiName, String condition, String order) throws Exception
+```
+
+| 参数         | 类型     | 是否必填 | 说明                                                                 |
+| ------------ | -------- | -------- | -------------------------------------------------------------------- |
+| `apiName`    | `String` | 是       | 对象 API 名称                                                        |
+| `condition`  | `String` | 否       | 使用字段 apiname 查询，自定义字段 API 后需加 `__c`，为空则查询所有   |
+| `order`      | `String` | 否       | 排序条件，字段 API 后需加 `__c`                                      |
+
+示例：
+
+```java
+List<CCObject> opps = cs.cquery(
+    "Opportunity",
+    "khmc__c = '123'",
+    "jine__c desc"
+);
+```
+
+#### 查询共享数据
+
+```java
+public List<CCObject> cquery(String apiName, String condition, boolean isDataObject) throws Exception
+```
+
+| 参数           | 类型      | 是否必填 | 说明                                         |
+| -------------- | --------- | -------- | -------------------------------------------- |
+| `apiName`      | `String`  | 是       | 对象 API 名称                                |
+| `condition`    | `String`  | 否       | 同上                                         |
+| `isDataObject` | `Boolean` | 否       | `true` 查询普通数据，`false` 查询共享数据     |
+
+示例：
+
+```java
+List<CCObject> opps = cs.cquery(
+    "Opportunity",
+    "khmc__c = '123'",
+    false
+);
+```
+
+### 3.4 SQL 查询：`cqlQuery`
+
+```java
+public List<CCObject> cqlQuery(String apiName, String cql) throws Exception
+```
+
+| 参数      | 类型     | 是否必填 | 说明                                   |
+| --------- | -------- | -------- | -------------------------------------- |
+| `apiName` | `String` | 是       | 对象 API 名称                          |
+| `cql`     | `String` | 否       | CQL/SQL 语句，支持常用 where 条件       |
+
+示例：
+
+```java
+List<CCObject> list = cs.cqlQuery(
+  "test_object_a",
+  "select * from test_object_a where text_field = 'hello002'"
+);
+```
+
+### 3.5 修改记录：`update`
+
+```java
+public ServiceResult update(CCObject ccobj) throws Exception
+```
+
+示例：
+
+```java
+CCObject obj = new CCObject("test_object_a");
+obj.put("id", "a252025B79C1B99R62Nf");
+obj.put("text_field", "hello003");
+cs.update(obj);
+```
+
+### 3.6 删除记录：`delete`
+
+```java
+public ServiceResult delete(CCObject ccobj) throws Exception
+```
+
+示例：
+
+```java
+CCObject obj = new CCObject("test_object_a");
+obj.put("id", "a252025B79C1B99R62Nf");
+cs.delete(obj);
+```
+
+### 3.7 删除共享表记录：`deleteShareObjectBySql`
+
+```java
+public void deleteShareObjectBySql(String objectApiName, String expression) throws Exception
+```
+
+| 参数             | 类型     | 是否必填 | 说明                               |
+| ---------------- | -------- | -------- | ---------------------------------- |
+| `objectApiName`  | `String` | 是       | 对象 API 名称                      |
+| `expression`     | `String` | 是       | SQL 表达式，字段 **不需要** 加 `__c` |
+
+---
+
+## 4. 自定义设置（CustomSetting）
+
+### 4.1 列表类型：`getListCustomSetting`
+
+```java
+public Map getListCustomSetting(String objectApiName)
+```
+
+| 参数             | 类型     | 是否必填 | 说明          |
+| ---------------- | -------- | -------- | ------------- |
+| `objectApiName`  | `String` | 是       | 自定义设置 API |
+
+返回指定 API 下的全部列表类型自定义设置。
+
+### 4.2 列表类型单条：`getListCustomSetting(String apiName, String name)`
+
+```java
+Map map = cs.getListCustomSetting(String apiName, String name);
+```
+
+| 参数        | 类型     | 是否必填 | 说明           |
+| ----------- | -------- | -------- | -------------- |
+| `apiName`   | `String` | 是       | 自定义设置 API  |
+| `name`      | `String` | 是       | 自定义设置记录名称 |
+
+### 4.3 层次结构类型：`getCustomSetting`
+
+```java
+public Map getCustomSetting(String objectApiName, String id)
+```
+
+| 参数             | 类型     | 是否必填 | 说明                     |
+| ---------------- | -------- | -------- | ------------------------ |
+| `objectApiName`  | `String` | 是       | 自定义设置 API           |
+| `id`             | `String` | 是       | 简档 ID 或用户 ID        |
+
+---
+
+## 5. SendEmail：发送邮件
+
+类：`com.g3cloud.platform.common.service.emailservice.SendEmail`
+
+### 5.1 构造函数
+
+```java
+public SendEmail(UserInfo userInfo)
+```
+
+| 参数        | 类型       | 是否必填 | 说明     |
+| ----------- | ---------- | -------- | -------- |
+| `userInfo`  | `UserInfo` | 是       | 用户对象 |
+
+### 5.2 直接发送邮件：`sendMailFromSystem`
+
+```java
+public boolean sendMailFromSystem(
+    String[] toAddress,
+    String[] ccAddress,
+    String[] bccAddress,
+    String subject,
+    String content,
+    boolean isText)
+```
+
+| 参数         | 类型       | 是否必填 | 说明                                      |
+| ------------ | ---------- | -------- | ----------------------------------------- |
+| `toAddress`  | `String[]` | 是       | 收件人数组                                |
+| `ccAddress`  | `String[]` | 是       | 抄送人数组（可为空数组）                  |
+| `bccAddress` | `String[]` | 是       | 密送人数组（可为空数组）                  |
+| `subject`    | `String`   | 是       | 邮件标题                                  |
+| `content`    | `String`   | 是       | 邮件内容（支持 HTML）                     |
+| `isText`     | `boolean`  | 是       | `true` 纯文本；`false` HTML 格式邮件     |
+
+### 5.3 使用模板发送：`sendEmailNew`
+
+```java
+public ServiceResult sendEmailNew(
+    String emailtemplateid,
+    String[] toaddress,
+    String[] ccaddress,
+    String[] bcaddress,
+    String id) throws Exception
+```
+
+| 参数              | 类型       | 是否必填 | 说明          |
+| ----------------- | ---------- | -------- | ------------- |
+| `emailtemplateid` | `String`   | 是       | 邮件模板 ID    |
+| `toaddress`       | `String[]` | 是       | 收件人         |
+| `ccaddress`       | `String[]` | 是       | 抄送人         |
+| `bcaddress`       | `String[]` | 是       | 密送人         |
+| `id`              | `String`   | 是       | 关联记录 ID     |
+
+---
+
+## 6. DevLogger：运行日志采集
+
+类：`com.g3cloud.platform.common.service.devlogger.DevLogger`（示例名，具体包以实际项目为准）
+
+### 6.1 构造函数
+
+```java
+public DevLogger(UserInfo userInfo)
+```
+
+| 参数        | 类型       | 是否必填 | 说明     |
+| ----------- | ---------- | -------- | -------- |
+| `userInfo`  | `UserInfo` | 是       | 用户对象 |
+
+### 6.2 info 日志：`devLogInfo`
+
+```java
+public void devLogInfo(String info)
+```
+
+| 参数    | 类型     | 是否必填 | 说明     |
+| ------- | -------- | -------- | -------- |
+| `info`  | `String` | 是       | 日志信息 |
+
+### 6.3 error 日志：`devLogError`
+
+```java
+public void devLogError(String error, Throwable throwable)
+```
+
+| 参数         | 类型        | 是否必填 | 说明       |
+| ------------ | ----------- | -------- | ---------- |
+| `error`      | `String`    | 是       | 错误信息   |
+| `throwable`  | `Throwable` | 否       | 异常对象   |
+
+---
+
+## 7. TimeUtil：多时区时间工具
+
+说明：`TimeUtil` 用于在多时区环境下安全处理时间，避免直接使用 `new Date()` / `Calendar.getInstance()` 带来的偏差。
+
+### 7.1 获取当前时间：`getNowDate`
+
+```java
+TpSysTask task = new TpSysTask();
+task.setBeginTime(TimeUtil.getNowDate(userInfo));
+```
+
+| 参数        | 类型       | 是否必填 | 说明     |
+| ----------- | ---------- | -------- | -------- |
+| `userInfo`  | `UserInfo` | 是       | 用户对象 |
+
+### 7.2 获取用户时区：`getUserTimeZone`
+
+```java
+TimeZone tz = TimeUtil.getUserTimeZone(userInfo);
+```
+
+### 7.3 获取带时区的 `SimpleDateFormat`：`getSimpleDateFormat`
+
+```java
+SimpleDateFormat myDateFormat =
+    TimeUtil.getSimpleDateFormat("yyyy-MM-dd", userInfo);
+```
+
+| 参数        | 类型       | 是否必填 | 说明           |
+| ----------- | ---------- | -------- | -------------- |
+| `format`    | `String`   | 是       | 日期格式化模式 |
+| `userInfo`  | `UserInfo` | 是       | 用户对象       |
+
+### 7.4 获取带时区的 `Calendar`
+
+```java
+Calendar cal = Calendar.getInstance(TimeUtil.getUserTimeZone(userInfo));
+// 或
+Calendar cal2 = TimeUtil.getCalendar(userInfo);
+```
+
+---
+
+## 8. 后端 SDK 使用建议 Checklist
+
+- [ ] 在自定义类/触发器/定时类中统一使用 `CCService` 操作对象，不直接写 JDBC。  
+- [ ] 查询条件和排序中，自定义字段使用 API 名称并加 `__c` 后缀（共享表表达式除外）。  
+- [ ] 涉及时区的所有时间写入/比较统一使用 `TimeUtil`。  
+- [ ] 需要发邮件时首选 `SendEmail`，避免自己拼 SMTP。  
+- [ ] 关键业务流程和异常通过 `DevLogger` 记录，便于问题排查。  
+- [ ] 自定义设置使用 `getListCustomSetting` / `getCustomSetting` 统一读取。  
+