neo-cmp-cli 1.13.11 → 1.13.12

package/template/neo-bi-cmps/docs/neo-backend-dev/references/01-Trigger/345/274/200/345/217/221.md

@@ -0,0 +1,183 @@
+# 技能包：Trigger 开发
+
+## 概述
+
+Trigger（触发器）用于在业务数据操作保存至数据库之前（before）或之后（after）增加自定义业务逻辑。
+
+## 适用场景
+
+- 创建数据时根据业务规则校验数据
+- 编辑数据后自动同步至第三方系统
+- 数据保存前自动填充/修改字段值
+- 批量数据的查重校验
+
+## 支持的操作
+
+| 操作 | 说明 |
+|------|------|
+| add | 创建 |
+| update | 更新 |
+| delete | 删除 |
+| transfer | 转移 |
+| lock | 锁定 |
+| unlock | 解锁 |
+| recover | 从回收站恢复 |
+
+## 代码模板
+
+### 前置 Trigger（before）
+
+```java
+package other.{company}.{project};
+
+import com.rkhd.platform.sdk.exception.ScriptBusinessException;
+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.trigger.*;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 前置 Trigger 模板
+ * 在数据保存到数据库之前执行，可修改数据或阻止保存
+ */
+public class BeforeTriggerTemplate implements Trigger {
+
+    private static final Logger LOG = LoggerFactory.getLogger();
+
+    @Override
+    public TriggerResponse execute(TriggerRequest request) throws ScriptBusinessException {
+        LOG.info("BeforeTrigger 开始执行, 操作: " + request.getOperate());
+
+        List<DataResult> results = new ArrayList<>();
+
+        for (XObject xObject : request.getDataList()) {
+            try {
+                // === 在此编写业务逻辑 ===
+
+                // 示例：修改字段值
+                // xObject.setAttribute("fieldApiName__c", "newValue");
+
+                // 示例：校验数据，不通过则阻止保存
+                // String name = xObject.getAttribute("name");
+                // if (name == null || name.isEmpty()) {
+                //     results.add(new DataResult(false, "名称不能为空", xObject));
+                //     if (!request.getPartialSuccess()) {
+                //         return new TriggerResponse(false, "数据校验失败", results);
+                //     }
+                //     continue;
+                // }
+
+                results.add(new DataResult(true, "", xObject));
+            } catch (Exception e) {
+                LOG.error("处理数据异常: " + e.getMessage());
+                results.add(new DataResult(false, e.getMessage(), xObject));
+            }
+        }
+
+        return new TriggerResponse(true, "", results);
+    }
+}
+```
+
+### 后置 Trigger（after）
+
+```java
+package other.{company}.{project};
+
+import com.rkhd.platform.sdk.exception.ScriptBusinessException;
+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.trigger.*;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 后置 Trigger 模板
+ * 在数据保存到数据库之后执行，可用于数据同步、通知等
+ */
+public class AfterTriggerTemplate implements Trigger {
+
+    private static final Logger LOG = LoggerFactory.getLogger();
+
+    @Override
+    public TriggerResponse execute(TriggerRequest request) throws ScriptBusinessException {
+        LOG.info("AfterTrigger 开始执行, 操作: " + request.getOperate());
+
+        List<DataResult> results = new ArrayList<>();
+
+        for (XObject xObject : request.getDataList()) {
+            try {
+                LOG.info("处理数据 ID: " + xObject.getId());
+
+                // === 在此编写业务逻辑 ===
+
+                // 示例：同步数据到外部系统
+                // syncToExternalSystem(xObject);
+
+                results.add(new DataResult(true, "成功", xObject));
+            } catch (Exception e) {
+                LOG.error("处理数据异常: " + e.getMessage());
+                results.add(new DataResult(false, e.getMessage(), xObject));
+            }
+        }
+
+        return new TriggerResponse(true, "成功", results);
+    }
+}
+```
+
+### 使用 TriggerContext 在 before/after 间传参
+
+```java
+// Before Trigger 中设置上下文
+TriggerContext triggerContext = new TriggerContext();
+triggerContext.set("key", "value");
+return new TriggerResponse(true, "", results, triggerContext);
+
+// After Trigger 中获取上下文
+TriggerContext triggerContext = request.getTriggerContext();
+String value = triggerContext.get("key");
+```
+
+## 配置文件模板
+
+scriptTrigger.xml：
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<configs>
+  <config>
+    <!-- 前置 Trigger -->
+    <trigger>
+      <object>{objectApiKey}__c</object>
+      <operate>add</operate>
+      <position>before</position>
+      <order>1</order>
+      <class>other.{company}.{project}.trigger.BeforeTriggerTemplate</class>
+    </trigger>
+    <!-- 后置 Trigger -->
+    <trigger>
+      <object>{objectApiKey}__c</object>
+      <operate>add</operate>
+      <position>after</position>
+      <order>1</order>
+      <class>other.{company}.{project}.trigger.AfterTriggerTemplate</class>
+    </trigger>
+  </config>
+</configs>
+```
+
+## 开发注意事项
+
+1. **类名不能以 "test" 结尾**
+2. **Java 文件必须 UTF-8 无 BOM 编码**
+3. **DataResult 数量必须与 TriggerRequest 数据量一致**
+4. **return 必须返回 TriggerResponse 对象**
+5. **Package 名称必须三级且以 other 开始**（如 `other.xsy.demo`），不能生成4级或以上的包名
+6. **同步脚本最大运行时长 15 秒**，超时会被自动终止
+7. **API 调用默认不触发 Trigger**

package/template/neo-bi-cmps/docs/neo-backend-dev/references/02-/350/207/252/345/256/232/344/271/211API/345/274/200/345/217/221.md

@@ -0,0 +1,196 @@
+# 技能包：自定义 API 开发
+
+## 概述
+
+自定义 API 允许开发者根据业务需求封装自定义的 REST API 接口，供外部系统或页面代码调用。
+
+## 适用场景
+
+- 封装复杂的业务查询逻辑为 API
+- 为外部系统提供数据集成接口
+- 为自定义页面提供后端数据服务
+- 实现跨对象的复杂数据操作
+
+## 代码模板
+
+### GET 请求 API
+
+```java
+package other.{company}.{project};
+
+import com.rkhd.platform.sdk.api.annotations.RequestMethod;
+import com.rkhd.platform.sdk.api.annotations.RestApi;
+import com.rkhd.platform.sdk.api.annotations.RestMapping;
+import com.rkhd.platform.sdk.api.annotations.RestQueryParam;
+import com.rkhd.platform.sdk.exception.ApiEntityServiceException;
+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.service.XObjectService;
+
+import com.alibaba.fastjson.JSONArray;
+import com.alibaba.fastjson.JSONObject;
+
+import java.util.List;
+
+@RestApi(baseUrl = "/custom")
+public class CustomGetApi {
+
+    private Logger log = LoggerFactory.getLogger();
+
+    /**
+     * GET 请求示例
+     * 访问路径: /rest/data/v2.0/scripts/api/getData?keyword=xxx
+     */
+    @RestMapping(value = "/getData", method = RequestMethod.GET)
+    public String handleGet(@RestQueryParam("keyword") String keyword)
+            throws ApiEntityServiceException {
+        try {
+            log.info("收到查询请求, keyword: " + keyword);
+
+            // 查询数据
+            String sql = "SELECT id, name FROM account WHERE name LIKE '%" + keyword + "%' LIMIT 10";
+            QueryResult queryResult = XObjectService.instance().query(sql);
+            List<XObject> records = queryResult.getRecords();
+
+            // 构建返回结果
+            JSONObject result = new JSONObject();
+            JSONArray dataArray = new JSONArray();
+
+            if (records != null) {
+                for (XObject record : records) {
+                    JSONObject item = new JSONObject();
+                    item.put("id", record.getId());
+                    item.put("name", record.getAttribute("name"));
+                    dataArray.add(item);
+                }
+            }
+
+            result.put("code", "200");
+            result.put("data", dataArray);
+            result.put("total", dataArray.size());
+            return result.toJSONString();
+
+        } catch (Exception e) {
+            log.error("查询异常: " + e.getMessage());
+            JSONObject error = new JSONObject();
+            error.put("code", "500");
+            error.put("message", e.getMessage());
+            return error.toJSONString();
+        }
+    }
+}
+```
+
+### POST 请求 API
+
+```java
+package other.{company}.{project};
+
+import com.rkhd.platform.sdk.api.annotations.RequestMethod;
+import com.rkhd.platform.sdk.api.annotations.RestApi;
+import com.rkhd.platform.sdk.api.annotations.RestMapping;
+import com.rkhd.platform.sdk.api.annotations.RestBeanParam;
+import com.rkhd.platform.sdk.exception.ApiEntityServiceException;
+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.service.XObjectService;
+
+import com.alibaba.fastjson.JSON;
+import com.alibaba.fastjson.JSONObject;
+
+@RestApi(baseUrl = "/custom")
+public class CustomPostApi {
+
+    private Logger log = LoggerFactory.getLogger();
+
+    /**
+     * POST 请求示例
+     * 访问路径: /rest/data/v2.0/scripts/api/createData
+     * Content-Type: application/json
+     * 注意：POST方法参数必须使用 @RestBeanParam(name="xxx") 注解
+     */
+    @RestMapping(value = "/createData", method = RequestMethod.POST)
+    public String handlePost(@RestBeanParam(name = "requestBody") String requestBody)
+            throws ApiEntityServiceException {
+        try {
+            log.info("收到创建请求, body: " + requestBody);
+
+            JSONObject body = JSON.parseObject(requestBody);
+
+            // 创建数据
+            // XObject xObject = new CustomEntity1__c();
+            // xObject.setAttribute("name", requestBody.getString("name"));
+            // xObject.setAttribute("entityType", MetadataService.instance()
+            //     .getBusiType(xObject.getApiKey(), "defaultBusiType").getId());
+            // XObjectService.instance().insert(xObject);
+
+            JSONObject result = new JSONObject();
+            result.put("code", "200");
+            result.put("message", "创建成功");
+            return result.toJSONString();
+
+        } catch (Exception e) {
+            log.error("创建异常: " + e.getMessage());
+            JSONObject error = new JSONObject();
+            error.put("code", "500");
+            error.put("message", e.getMessage());
+            return error.toJSONString();
+        }
+    }
+}
+```
+
+## 配置文件模板
+
+scriptTrigger.xml：
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<configs>
+  <config>
+    <customApi>
+      <class>other.{company}.{project}.api.CustomGetApi</class>
+    </customApi>
+    <customApi>
+      <class>other.{company}.{project}.api.CustomPostApi</class>
+    </customApi>
+  </config>
+</configs>
+```
+
+## 调用方式
+
+### 外部调用
+
+```
+GET  https://api.xiaoshouyi.com/rest/data/v2.0/scripts/api/getData?keyword=xxx
+POST https://api.xiaoshouyi.com/rest/data/v2.0/scripts/api/createData
+
+Header:
+  Authorization: Bearer {access_token}
+  Content-Type: application/json
+```
+
+### 页面代码中调用（NeoLappSdk.js）
+
+```javascript
+lapp.connection.invoke({
+    url: '/rest/data/v2.0/scripts/api/getData?keyword=test',
+    method: 'GET'
+}).then(
+    res => { console.log(res); },
+    err => { console.log(err); }
+)
+```
+
+## 注意事项
+
+1. 自定义 API 入参最大值 **15 MB**
+2. 外部并发调用限制：用户级 **15 次/秒**，租户级 **50 次/秒**
+3. 第三方包仅支持 **fastJson** 和 **commons-lang**
+4. POST 方法参数必须使用 `@RestBeanParam(name="xxx")` 注解，不能直接用裸参数
+5. `QueryResult.getRecords()` 返回 `List<XObject>`，没有 `getTotalSize()` 方法，需通过 `records.size()` 或单独 count 查询获取总数
+6. Package 名称必须三级且以 other 开始（如 `other.xsy.pipeline`），不能生成四级包名