neo-cmp-cli 1.13.11 → 1.13.13

package/template/neo-bi-cmps/docs/neo-backend-dev/references/03-SDK/345/267/245/345/205/267/347/261/273/346/216/245/345/217/243.md

@@ -0,0 +1,346 @@
+# 技能包：SDK 工具类接口
+
+## 概述
+
+销售易 PaaS SDK 提供了丰富的工具类接口，用于数据操作、HTTP 请求、缓存、异步任务等。
+
+---
+
+## 1. 数据操作接口（XObjectService）
+
+用于对销售易系统中的对象数据进行 CRUD 操作。
+
+### 查询数据
+
+```java
+import com.rkhd.platform.sdk.service.XObjectService;
+import com.rkhd.platform.sdk.model.QueryResult;
+import com.rkhd.platform.sdk.model.XObject;
+
+// 基本查询
+QueryResult result = XObjectService.instance().query(
+    "SELECT id, name, createdAt FROM account WHERE name LIKE '%test%' LIMIT 10"
+);
+List<XObject> records = result.getRecords();
+
+// 查询并包含已删除数据
+QueryResult result = XObjectService.instance().query(sql, true);
+```
+
+### 插入数据
+
+```java
+import com.rkhd.platform.sdk.service.XObjectService;
+import com.rkhd.platform.sdk.service.MetadataService;
+
+XObject xObject = new CustomEntity1__c();
+xObject.setAttribute("name", "测试数据");
+xObject.setAttribute("entityType",
+    MetadataService.instance().getBusiType(xObject.getApiKey(), "defaultBusiType").getId());
+XObjectService.instance().insert(xObject);
+```
+
+### 更新数据
+
+```java
+XObject xObject = new CustomEntity1__c();
+xObject.setId(dataId);
+xObject.setAttribute("name", "更新后的名称");
+XObjectService.instance().update(xObject);
+```
+
+### 删除数据
+
+```java
+XObject xObject = new CustomEntity1__c();
+xObject.setId(dataId);
+XObjectService.instance().delete(xObject);
+```
+
+### 限制
+
+- 单次链路查询不超过 **10,000 条**
+- 单次 DML 操作不超过 **10,000 条**
+- 单个脚本中 rkhdHttpClient 可进行的 query 或 DML 最大 **50 次**
+
+---
+
+## 2. 向外部系统发起 HTTP 请求（CommonHttpClient）
+
+### GET 请求
+
+```java
+import com.rkhd.platform.sdk.http.CommonHttpClient;
+import com.rkhd.platform.sdk.http.CommonData;
+import com.rkhd.platform.sdk.http.HttpResult;
+
+CommonHttpClient client = CommonHttpClient.instance();
+CommonData commonData = CommonData.newBuilder()
+    .callType("GET")
+    .callString("https://external-api.com/data?id=123")
+    .header("Authorization", "Bearer token")
+    .build();
+HttpResult result = client.execute(commonData);
+String responseBody = result.getResult();
+```
+
+### POST 请求（JSON）
+
+```java
+import com.alibaba.fastjson.JSONObject;
+
+JSONObject body = new JSONObject();
+body.put("name", "test");
+body.put("value", 100);
+
+CommonData commonData = CommonData.newBuilder()
+    .callType("POST")
+    .callString("https://external-api.com/create")
+    .header("Content-Type", "application/json")
+    .header("Authorization", "Bearer token")
+    .body(body.toJSONString())
+    .build();
+HttpResult result = CommonHttpClient.instance().execute(commonData);
+```
+
+### 下载文件
+
+```java
+CommonData commonData = CommonData.newBuilder()
+    .callString("https://external-api.com/file/download")
+    .callType("GET")
+    .build();
+RkhdBlob blob = CommonHttpClient.instance().downBlob(commonData);
+String fileName = blob.getFileName();
+byte[] fileContent = blob.getBytes();
+```
+
+### 限制
+
+- 单个脚本中调用最大 **50 次**
+- 入参最大值 **15 MB**
+- HTTP 默认超时 **10 秒**
+
+---
+
+## 3. 向销售易系统发起 HTTP 请求（RkhdHttpClient）
+
+```java
+import com.rkhd.platform.sdk.http.RkhdHttpClient;
+import com.rkhd.platform.sdk.http.RkhdHttpData;
+
+RkhdHttpClient client = RkhdHttpClient.instance();
+
+// GET 请求
+RkhdHttpData getData = RkhdHttpData.newBuilder()
+    .callString("/rest/data/v2/query")
+    .callType("GET")
+    .build();
+String response = client.execute(getData);
+
+// POST 请求（上传文件）
+Map<String, Object> formData = new HashMap<>();
+RkhdBlob blob = new RkhdBlob();
+blob.setFileName("文件名.格式");
+blob.setBytes(fileBytes);
+formData.put("files", blob);
+formData.put("isImage", false);
+formData.put("needFileId", true);
+
+RkhdHttpData postData = RkhdHttpData.newBuilder()
+    .callString("/rest/file/v2.0/file/batch")
+    .callType("POST")
+    .formData(formData)
+    .build();
+postData.putHeader("Content-Type", "multipart/form-data");
+client.execute(postData);
+```
+
+---
+
+## 4. 异步脚本（FutureTask）
+
+```java
+import com.rkhd.platform.sdk.async.FutureTaskService;
+
+// 在同步脚本中调用异步任务
+FutureTaskService.instance().submit(
+    "other.{company}.{project}.async.MyAsyncTask",
+    "参数字符串"
+);
+```
+
+异步任务实现类：
+
+```java
+package other.{company}.{project}.async;
+
+import com.rkhd.platform.sdk.async.FutureTask;
+import com.rkhd.platform.sdk.log.Logger;
+import com.rkhd.platform.sdk.log.LoggerFactory;
+
+public class MyAsyncTask implements FutureTask {
+    private Logger log = LoggerFactory.getLogger();
+
+    @Override
+    public void execute(String params) {
+        log.info("异步任务开始执行, 参数: " + params);
+        // 业务逻辑
+    }
+}
+```
+
+### 限制
+
+- 同步脚本中可调用 FutureTask 最大 **50 次**
+- 异步脚本中不可调用 FutureTask
+- 异步脚本最大运行时长 **90 秒**
+
+---
+
+## 5. 租户级缓存（CacheService）
+
+```java
+import com.rkhd.platform.sdk.cache.CacheService;
+
+CacheService cache = CacheService.instance();
+
+// 写入缓存
+cache.put("myKey", "myValue");
+
+// 读取缓存
+String value = cache.get("myKey");
+
+// 删除缓存
+cache.remove("myKey");
+```
+
+### 限制
+
+- 最大缓存大小 **200 KB**
+- 最大缓存 key 数量 **64 个**
+- 同步脚本调用次数 **50 次**
+- 异步脚本调用次数 **100 次**
+
+---
+
+## 6. 批量数据处理（BatchJobService）
+
+```java
+import com.rkhd.platform.sdk.batch.BatchJobService;
+
+// 创建批量作业
+BatchJobService.instance().submit(
+    "other.{company}.{project}.batch.MyBatchJob",
+    "SELECT id, name FROM account",
+    200  // 每批次处理条数
+);
+```
+
+### 限制
+
+- 执行批次取值范围 **50 ~ 500 条**
+- 单个 BatchJob 最大数据量 **100,000 条**
+- 每日最大数据量 **1,000,000 条**
+
+---
+
+## 7. 日志接口（Logger）
+
+```java
+import com.rkhd.platform.sdk.log.Logger;
+import com.rkhd.platform.sdk.log.LoggerFactory;
+
+private static final Logger LOG = LoggerFactory.getLogger();
+
+LOG.debug("调试信息");
+LOG.info("普通信息");
+LOG.warn("警告信息");
+LOG.error("错误信息");
+```
+
+日志查看路径：系统后台 → 日志审计 → 业务逻辑代码日志 → 文本输出
+
+---
+
+## 8. 自定义配置（CustomConfigService）
+
+```java
+import com.rkhd.platform.sdk.service.CustomConfigService;
+
+CustomConfigService configService = CustomConfigService.instance();
+Map<String, String> configs = configService.getConfigSet("configSetApiName");
+String value = configs.get("configItemKey");
+```
+
+---
+
+## 9. 发送邮件（EmailService）
+
+```java
+import com.rkhd.platform.sdk.email.EmailService;
+import com.rkhd.platform.sdk.email.EmailBody;
+
+EmailService emailService = EmailService.instance();
+EmailBody body = EmailBody.newBuilder()
+    .subject("邮件主题")
+    .body("邮件内容")
+    .smtpHost("smtp.163.com")
+    .smtpPort("465")
+    .isSSL(true)
+    .receiverList(Arrays.asList("receiver@example.com"))
+    .senderUserName("sender@163.com")
+    .senderUserPass("password")
+    .build();
+emailService.sendEmail(body);
+```
+
+---
+
+## 10. 分布式锁（LockService）
+
+```java
+import com.rkhd.platform.sdk.lock.LockService;
+
+LockService lockService = LockService.instance();
+
+// 获取锁
+boolean locked = lockService.tryLock("lockKey", 10); // 超时10秒
+
+if (locked) {
+    try {
+        // 业务逻辑
+    } finally {
+        lockService.unlock("lockKey");
+    }
+}
+```
+
+### 限制
+
+- 最大同时存在 key 数量 **5000 个**
+
+---
+
+## 11. 数据加解密（SymmetricCryptoUtil）
+
+```java
+import com.rkhd.platform.sdk.crypto.SymmetricCryptoUtil;
+
+// AES 加密
+String encrypted = SymmetricCryptoUtil.encrypt("明文数据", "密钥");
+
+// AES 解密
+String decrypted = SymmetricCryptoUtil.decrypt(encrypted, "密钥");
+```
+
+---
+
+## 12. 获取环境信息（ScriptRuntimeContext）
+
+```java
+import com.rkhd.platform.sdk.context.ScriptRuntimeContext;
+
+ScriptRuntimeContext context = ScriptRuntimeContext.instance();
+// 获取当前租户 ID、用户 ID 等运行时环境信息
+```

package/template/neo-bi-cmps/docs/neo-backend-dev/references/04-/350/256/241/345/210/222/344/275/234/344/270/232/345/274/200/345/217/221.md

@@ -0,0 +1,188 @@
+# 技能包：计划作业开发
+
+## 概述
+
+计划作业用于执行定时批量任务，如定时数据同步、定时清理、定时报表生成等。
+
+## 适用场景
+
+- 定时从外部系统同步数据到 CRM
+- 定时清理过期数据
+- 定时生成统计报表
+- 定时发送通知
+
+## 代码模板
+
+### 计划作业实现类
+
+```java
+package other.{company}.{project};
+
+import com.rkhd.platform.sdk.log.Logger;
+import com.rkhd.platform.sdk.log.LoggerFactory;
+import com.rkhd.platform.sdk.model.QueryResult;
+import com.rkhd.platform.sdk.model.XObject;
+import com.rkhd.platform.sdk.schedule.ScheduleJob;
+import com.rkhd.platform.sdk.service.XObjectService;
+
+import java.util.List;
+
+/**
+ * 计划作业模板
+ * 定时执行的批量任务
+ */
+public class MyScheduleJob implements ScheduleJob {
+
+    private static final Logger LOG = LoggerFactory.getLogger();
+
+    @Override
+    public void execute() {
+        LOG.info("计划作业开始执行");
+
+        try {
+            // === 在此编写定时任务逻辑 ===
+
+            // 示例：查询需要处理的数据
+            String sql = "SELECT id, name FROM customEntity1__c WHERE status__c = '待处理' LIMIT 100";
+            QueryResult result = XObjectService.instance().query(sql);
+            List<XObject> records = result.getRecords();
+
+            if (records != null && records.size() > 0) {
+                LOG.info("待处理数据条数: " + records.size());
+
+                for (XObject record : records) {
+                    try {
+                        // 处理每条数据
+                        record.setAttribute("status__c", "已处理");
+                        XObjectService.instance().update(record);
+                    } catch (Exception e) {
+                        LOG.error("处理数据失败, ID: " + record.getId() + ", 错误: " + e.getMessage());
+                    }
+                }
+            } else {
+                LOG.info("没有待处理的数据");
+            }
+
+            LOG.info("计划作业执行完成");
+
+        } catch (Exception e) {
+            LOG.error("计划作业执行异常: " + e.getMessage());
+        }
+    }
+}
+```
+
+### 带外部系统同步的计划作业
+
+```java
+package other.{company}.{project};
+
+import com.alibaba.fastjson.JSON;
+import com.alibaba.fastjson.JSONArray;
+import com.alibaba.fastjson.JSONObject;
+import com.rkhd.platform.sdk.http.CommonData;
+import com.rkhd.platform.sdk.http.CommonHttpClient;
+import com.rkhd.platform.sdk.http.HttpResult;
+import com.rkhd.platform.sdk.log.Logger;
+import com.rkhd.platform.sdk.log.LoggerFactory;
+import com.rkhd.platform.sdk.model.XObject;
+import com.rkhd.platform.sdk.schedule.ScheduleJob;
+import com.rkhd.platform.sdk.service.MetadataService;
+import com.rkhd.platform.sdk.service.XObjectService;
+
+/**
+ * 定时同步外部数据的计划作业
+ */
+public class SyncScheduleJob implements ScheduleJob {
+
+    private static final Logger LOG = LoggerFactory.getLogger();
+
+    @Override
+    public void execute() {
+        LOG.info("数据同步计划作业开始执行");
+
+        try {
+            // 1. 从外部系统获取数据
+            CommonData commonData = CommonData.newBuilder()
+                .callType("GET")
+                .callString("https://external-api.com/data/list")
+                .header("Authorization", "Bearer external_token")
+                .build();
+            HttpResult httpResult = CommonHttpClient.instance().execute(commonData);
+            String response = httpResult.getResult();
+
+            // 2. 解析数据
+            JSONObject jsonResponse = JSON.parseObject(response);
+            JSONArray dataList = jsonResponse.getJSONArray("data");
+
+            if (dataList == null || dataList.size() == 0) {
+                LOG.info("外部系统无新数据");
+                return;
+            }
+
+            LOG.info("获取到外部数据条数: " + dataList.size());
+
+            // 3. 写入 CRM 系统
+            for (int i = 0; i < dataList.size(); i++) {
+                JSONObject item = dataList.getJSONObject(i);
+                try {
+                    // 根据实际对象创建数据
+                    // XObject xObject = new CustomEntity1__c();
+                    // xObject.setAttribute("name", item.getString("name"));
+                    // xObject.setAttribute("entityType",
+                    //     MetadataService.instance().getBusiType(
+                    //         xObject.getApiKey(), "defaultBusiType").getId());
+                    // XObjectService.instance().insert(xObject);
+                } catch (Exception e) {
+                    LOG.error("同步数据失败: " + e.getMessage());
+                }
+            }
+
+            LOG.info("数据同步计划作业执行完成");
+
+        } catch (Exception e) {
+            LOG.error("数据同步异常: " + e.getMessage());
+        }
+    }
+}
+```
+
+## 配置文件模板
+
+scriptTrigger.xml：
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<configs>
+  <config>
+    <scheduleJob>
+      <class>other.{company}.{project}.job.MyScheduleJob</class>
+    </scheduleJob>
+    <scheduleJob>
+      <class>other.{company}.{project}.job.SyncScheduleJob</class>
+    </scheduleJob>
+  </config>
+</configs>
+```
+
+## 配置并启用计划作业
+
+1. 上传代码包并启用
+2. 进入系统后台 → 开发 → 计划作业
+3. 新建计划作业，选择对应的 Class
+4. 设置执行频率（最小间隔 15 分钟）
+5. 启用计划作业
+
+## 查看执行情况
+
+- 系统后台 → 开发 → 计划作业 → 查看执行日志
+- 系统后台 → 日志审计 → 业务逻辑代码日志
+
+## 限制
+
+| 限制项 | 值 |
+|--------|-----|
+| 最多同时启用 | 30 个/租户 |
+| 自定义类型最多启用 | 5 个/租户 |
+| 最小执行间隔 | 15 分钟 |
+| 异步脚本最大运行时长 | 90 秒 |